Repository navigation
docs: rework AGENTS.md and split the docs by purpose - #82
Merged
Merged
Conversation
The docs repeated what the code already says, and had drifted from it. AGENTS.md now states the decisions a change must not undo, the working rules, and what the docs are for: the code states each rule first, and docs hold only what it can't say. ARCHITECTURE.md splits into docs/internals, DEPLOYMENT.md and new development and release pages go in docs/operations, and BOTS.md and a new guide go in docs/user. File catalogs, field lists and the phased build plan are gone, and stale claims are corrected against the code. Code comments cite the new pages. Only comments and strings change in code, and the transcribe bundle is untouched. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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.
Summary
The docs repeated what the code already says and had drifted from it, and
AGENTS.mddidn't say what the docs are for. Now the code states each rule first, docs hold only what it can't say, and each page has one job.ARCHITECTURE.md §Ncitations in about 80 files now name the new pages, and bare(§N)citations are gone.revoked_sessionsexists, administrators can record and download, and a removed guest can rejoin through the lobby.In code, only comments and strings change, including
types.gen.tsregenerated from those comments and four variable descriptions insite/src/lib/config.ts.Evidence
docs/ARCHITECTURE.mdclaimed "No session table", whilerevoked_sessionsexists.After:
docs/internals/auth.mdmatches the code.make check,npm run checkandnpm run lintinsite/(34TIDE_*variables documented), andscripts/check-release-pins.sh 0.1.2all pass.make mediaandmake moil-e2ewere not run, because no behaviour changes.server/internal/transcripts/bundle/andserver/third_party/moilhave no diff, so machine owners approve nothing again.Merge Danger
Door: two-way. Revert the commit.
Blast Radius: links
Published images carry a documentation label pointing at
blob/main/docs/DEPLOYMENT.md, which will 404 after this merge.release.ymlis fixed for future releases. External links todocs/ARCHITECTURE.mdanddocs/BOTS.mdbreak the same way.This also adopts conventional commits in
AGENTS.md, which differs from the plain sentences in the history so far.Model: Claude Opus 5.5. Harness: Claude Code.
🤖 Generated with Claude Code