Skip to content

rewrite readme to focus on motivations; move features into docs/#19

Merged
cjus merged 1 commit into
mainfrom
carlos/readme-concise-rewrite
May 11, 2026
Merged

rewrite readme to focus on motivations; move features into docs/#19
cjus merged 1 commit into
mainfrom
carlos/readme-concise-rewrite

Conversation

@cjus
Copy link
Copy Markdown
Owner

@cjus cjus commented May 11, 2026

Summary

  • Rewrite README around three questions: what is this, why is it different, why might it be useful. Reduced from 234 → 61 lines.
  • Tagline updated from technical "agent loop" framing to "personal Agent"; positioning leads with local-Ollama economics + paid Claude escalation.
  • "Why Solrac" section explicitly contrasts against OpenClaw and Hermes Agent so readers can self-select.
  • FEATURES.md moved to docs/FEATURES.md; relative links inside the file updated (../README.md, ./USAGE.md#…).
  • Documentation table at the bottom of the README is now the canonical jump-off point into the docs/ tree.

Why

  • Long READMEs are off-putting. The previous README mixed motivation, feature list, install instructions, repo layout, stack, design philosophy teaser, anti-goals teaser, testing block, and a multi-doc web-UI cross-reference list — much of which already lives canonically in docs/.
  • Adjacent projects in this space (OpenClaw, Hermes Agent) lead with motivation and link out. Solrac should too.
  • Naming the comparison projects directly is honest positioning — they're broader and better-resourced; Solrac's distinct value (local-first economics, cost enforcement, audit-before-acting, single-process minimalism) is what justifies its existence.

What's removed from the README (canonical content lives in docs)

  • Repository layout tree → docs/ARCHITECTURE.md (module map)
  • Stack list → docs/ARCHITECTURE.md
  • Design philosophy teaser → docs/ARCHITECTURE.md#philosophy
  • "What's intentionally not here" teaser → docs/ARCHITECTURE.md#anti-goals
  • Testing commands → discoverable via `package.json`; covered in `docs/OPERATIONS.md`
  • Engine routing table → `docs/USAGE.md#engine-routing-prefix-table`
  • Operational dependencies bullets → `docs/SETUP.md`
  • Web UI multi-doc cross-reference list → users navigate via the Documentation table

No anti-goals are being reversed.

Test plan

  • Render the README on github.com/cjus/solrac to confirm link resolution and table formatting
  • Verify `docs/FEATURES.md` renders with working `../README.md` and `./USAGE.md#…` anchors
  • Confirm Documentation table links all resolve from the README's location

@cjus cjus merged commit 7bac203 into main May 11, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant