Skip to content

Cut the README to a way in and let the docs carry the depth - #987

Merged
TheGreatAxios merged 1 commit into
mainfrom
cl-7884-make-the-readme-a-way-in-not-a-second-copy-of-the-docs
Sep 13, 2026
Merged

TheGreatAxios merged 1 commit into
mainfrom
cl-7884-make-the-readme-a-way-in-not-a-second-copy-of-the-docs

Conversation

@TheGreatAxios

Copy link
Copy Markdown
Collaborator

Closes CL-7884.

Summary

251 lines to 131. A first-time reader had to get past three permission subsections, a stack table, an architecture diagram, and the full director catalog before reaching anything that told them whether to keep going.

What was deleted, not moved

Architecture, the stack list, extensibility, and the agent-workspace catalog are deleted. Each is already covered in docs/, verified before removing rather than assumed:

Removed from README Confirmed covered in
Architecture + reactor diagram docs/ARCHITECTURE.md
Permission rule enumeration docs/ARCHITECTURE.md, docs/PRODUCT.md
Stack table docs/IMPLEMENTATION.md
Extensibility docs/PLUGINS.md, docs/MCP.md, docs/HOOKS.md
Director catalog, .agents/agents/, search_agents docs/ARCHITECTURE.md, docs/PRODUCT.md, docs/IMPLEMENTATION.md

Moving them would have bolted a "from the README" paragraph onto docs that already explain the thing better. Two copies of an explanation is one copy that goes stale, and it is never the docs copy.

What replaced the permission section

~50 lines of enumerated rules became a paragraph: auto mode runs ordinary work without prompting, stops for dependency installs / recursive deletes / paths outside the workspace / anything credential-shaped, and refuses shell-based file editing outright. Then a pointer to the full policy.

This is the judgement call worth reviewing. Auto mode is the feature most likely to surprise a new user, and a paragraph may be too little. I flagged it as uncertain on the issue rather than pretending otherwise.

Structure

What it is → install → first run → permissions → where to go next → contributing → license. The docs/ table moves from the footer to a signposted next step, and AGENTS.md gets a line saying what it is for.

Testing

Docs only. bun run lint and tsc --noEmit clean via the pre-commit gate. Links checked by inspection; the quickstart commands are unchanged from the current README, so they are as correct as they were before — I did not re-run them from a clean clone, which the issue asks for and remains unticked.

@linear-code

linear-code Bot commented Sep 13, 2026

Copy link
Copy Markdown

CL-7884

251 lines to 131. A reader had to get past three permission subsections,
a stack table, an architecture diagram, and the director catalog before
reaching anything that told them whether to keep going.

Architecture, the stack list, extensibility, and the agent-workspace
catalog are deleted rather than moved: docs/ARCHITECTURE.md,
docs/IMPLEMENTATION.md, docs/PRODUCT.md and docs/PLUGINS.md already cover
each one, verified before removing. Two copies of an explanation is one
copy that goes stale, and it is never the docs copy.

Permissions drop from ~50 lines of enumerated rules to a paragraph that
says what auto mode does, what it stops for, and where the full policy
is. The docs table moves from the footer to a signposted next step.

CL-7884
@TheGreatAxios
TheGreatAxios force-pushed the cl-7884-make-the-readme-a-way-in-not-a-second-copy-of-the-docs branch from 5fe926c to f22711f Compare September 13, 2026 18:02
@TheGreatAxios TheGreatAxios changed the title docs(readme): cut the README to a way in and let docs carry the depth Cut the README to a way in and let the docs carry the depth Sep 13, 2026
@TheGreatAxios

Copy link
Copy Markdown
Collaborator Author

Audit: Approve (CL-7884, 0.3.25)

Fit summary: README trim 251→131 lines. Deletions verified covered in docs/code; permission paragraph accurate. No scope creep beyond the trim.

Non-blocking nit (follow-up, not a merge blocker — intentionally not edited here): the Contributing paragraph adds an ungrounded 'will be declined' enforcement claim. Suggest softening to a guidance statement or grounding it in CONTRIBUTING.md in a follow-up PR.

@TheGreatAxios
TheGreatAxios merged commit 8a1e138 into main Sep 13, 2026
9 checks 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