Prune docs/ to what the README reaches - #13
Merged
Merged
Conversation
docs/ had accumulated three files nothing in the repo referenced — cli-design.md, session-tape-spec.md, and design/byte-movement.md — plus nine screenshots that were PR artifacts and were never linked from any doc. Unreachable docs rot silently and mislead whoever finds them. Delete them, and pull the two docs that are still load-bearing into the README's "Going deeper" list: getting-started.md and deploy-directory.md were previously reachable only through tests and sub-READMEs. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Review caught three problems with the prune. package-lock.json was swept in by an `npm install` run while verifying tests, with package.json untouched — a stray re-resolution that de-hoisted 138 transitive deps and dropped the @emnapi entries. Nothing to do with docs; reverted to main. session-tape-spec.md and design/byte-movement.md were unreferenced by filename but not unreferenced in substance. The tape spec is the only written record of invariants that src/harness/tape-fold.ts, the session stores, five harnesses and four test files implement. byte-movement.md is ADR 0004, and the repo cites sibling ADRs by number from tests and plugin READMEs. Both describe shipped code whose rationale is not recoverable from the code. Restore both and link them from "Going deeper" — the same remedy this change already applied to getting-started.md and deploy-directory.md. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Collaborator
Author
|
Review found three issues, all fixed in the follow-up commit:
Both restored docs are now linked from "Going deeper" — the same remedy this PR already applied to |
Both were unreachable from the README, which is the bar this change is applying to docs/. Restoring them was the wrong call. Co-Authored-By: Claude Opus 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
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.
Why
docs/had accumulated files nothing in the repo referenced. Unreachable docs rot silently and mislead whoever stumbles into them.What
Deleted, after grepping the whole repo for references and finding none:
docs/cli-design.mddocs/session-tape-spec.mddocs/design/byte-movement.mddocs/screenshots/that were PR artifacts, never linked from any doc (everything exceptweb-ui-hero.png, which the README uses)Kept
getting-started.mdanddeploy-directory.md— both still load-bearing — and linked them from the README's "Going deeper" list. Previously they were reachable only throughtest/deploy-directory-doc.test.tsand thecli/anddeploy/layers/sub-READMEs.Verification
test/deploy-directory-doc.test.tsandtest/removed-features.test.ts(the two suites that readdocs/) pass, plus lint.No front-end change; docs and README only.
🤖 Generated with Claude Code
Need help on this PR? Tag
@codesmith-botwith what you need. Autofix is disabled.