docs: restructure the README and docs into per-surface guides - #11
Merged
Conversation
The single 1261-line file had grown past what anyone reads end to end, and its Stack table and module tree had drifted from the source: portable-pty was listed at 0.8 (0.9), toml at 0.8 (0.9), WebMirrorConfig no longer exists, and daemon/, backend/hub.rs, git/clone/ and web/viewer/clone_jobs/ were missing entirely. architecture.md keeps its path — AGENTS.md, the self-review skill, and six source comments link to it — and becomes a 236-line index: overview, layout, an accurate module map, the stack, the critical risk, and links into docs/architecture/. The per-area rationale moves into session.md, git-views.md, terminal.md, ui.md, plugin-host.md, and web.md, condensed to the decisions and invariants with the incident retellings cut to a line.
The four plan documents said so themselves — implementation done, settled design moved to architecture.md, kept only for why it went that way. That rationale is worth keeping; four separate files each restating their own status is not. decisions.md collects what survives: the rejected alternatives (shell-via-PTY for path completion, libloading plugins, shadcn/ui, git://, cursor-based log paging, connect-to-stale-socket instance detection), the points where implementation diverged from plan, and the constraints that still bind. The 2026-05-08 code review is spent — its action items are all applied — so only two decisions survive from it. Cargo.toml's exclude list and three source comments pointed at these files; they now point at the design docs or drop the parenthetical. Comments only, no behaviour change.
token-optimization.md was seven universal assistant defaults with nothing about this repo, and it contradicted review-protocol.md section 1 — it asked for partial reads where the review protocol requires reading changed files in full. Removed. The remaining six rules files carried the same content twice in places (commits.md's Prohibited restated Commit Units; testing.md listed its layers and when to use them as two lists). Condensed to the constraints, 218 lines to 134. Two rules were wrong rather than verbose: the commit format allowed no scope though every recent commit uses one, and the branch rule named main where this repo's default is dev. The skills drop their duplicated preamble and the /ralph references, which name a command that does not exist. security-review loses the SQL-injection and TLS lenses — there is no database and no outbound TLS surface here — and gains the real exposure surface.
The README had grown to 719 lines and answered every question at the same depth — the install line and the config-reload table sat in one scroll, so neither was findable. It now carries the tour: what nightcrow is, how to install it, enough to get a session up, and a feature summary that links out. Everything else moves to one page per surface — getting-started, projects, views, keybindings, session-state, web-viewer, plugins, configuration — with docs/README.md as the index. The cross-references the README made to its own headings become links between those pages.
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
1 participant
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.
The README was 719 lines and
docs/architecture.mdwas 1261 — both answered every question at the same depth, so nothing in either was findable. This splits them, retires the finished plan documents, and trims the agent rules. Documentation and comments only; no behaviour change.Commits
docs(architecture)—architecture.mdkeeps its path (AGENTS.md, the self-review skill, and six source comments link to it) and becomes a 236-line index. The per-area rationale moves intodocs/architecture/{session,git-views,terminal,ui,plugin-host,web}.md.docs— the four plan documents and the 2026-05-08 code review are retired intodocs/decisions.md, which keeps the rejected alternatives and the points where implementation diverged from plan.docs(agents)—.agents/rules/token-optimization.mdremoved; the other six rules condensed 218 → 134 lines; skills deduplicated.docs— the README splits into eight per-surface guides underdocs/, indexed bydocs/README.md.Staleness this turned up
portable-pty 0.8(actually 0.9),toml 0.8(actually 0.9).WebMirrorConfigno longer exists insrc/. The module tree was missingdaemon/entirely, plusbackend/hub.rs,git/clone/, andweb/viewer/clone_jobs/.commits.mdallowed no scope in the commit format though every recent commit uses one, and namedmainas the default branch where this repo's isdev.token-optimization.mdcontradictedreview-protocol.md§1 — it asked for partial reads where the review protocol requires reading changed files in full.Why the plan documents go
Each of the four said so in its own preamble: implementation complete, settled design already moved to
architecture.md, kept only as a record of why it went that way. That rationale is worth keeping — four files each restating their own status is not.Cargo.toml'sexcludelist and three source comments referenced them and now point at the design docs instead.Verification
README.md,AGENTS.md, anddocs/**resolve — checked programmatically, 0 broken.cargo checkwas not a usable gate locally: it fails with 20 pre-existing errors on Windows because the daemon is Unix-only (libc::flock,pre_exec,signal_hook::iterator). Confirmed identical against a stashed tree. CI is the real gate here.Note
.claude/rulesand.claude/skillsare git symlinks to../.agents/*; only.agents/was edited, as intended.