Cut the README to a way in and let the docs carry the depth - #987
Merged
TheGreatAxios merged 1 commit intoSep 13, 2026
Merged
TheGreatAxios merged 1 commit into
TheGreatAxios merged 1 commit into
Conversation
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
force-pushed
the
cl-7884-make-the-readme-a-way-in-not-a-second-copy-of-the-docs
branch
from
September 13, 2026 18:02
5fe926c to
f22711f
Compare
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. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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:docs/ARCHITECTURE.mddocs/ARCHITECTURE.md,docs/PRODUCT.mddocs/IMPLEMENTATION.mddocs/PLUGINS.md,docs/MCP.md,docs/HOOKS.md.agents/agents/,search_agentsdocs/ARCHITECTURE.md,docs/PRODUCT.md,docs/IMPLEMENTATION.mdMoving 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, andAGENTS.mdgets a line saying what it is for.Testing
Docs only.
bun run lintandtsc --noEmitclean 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.