docs: resolve dead links + inline surface justification#4
Merged
Conversation
Replaces two dead link chains that had been in public docs since Phase 9: 1. `docs/architecture.md` (referenced once in each README) — never existed. Replaced with a 12-row table in README's "Why each surface?" section justifying each surface by "what friction appears if it's missing", per the recommendation that README alone should answer the question. 2. `memory/project_phases.md` (referenced from README × 2 and CONTRIBUTING) — lived in user-level Claude memory, not the repo, so every clone saw a 404. Materialized as `docs/project_phases.md`: 10-phase build order + design rationale (why this sequence, why independently demoable). Stripped the private frontmatter (originSessionId, etc.). Also adjusts .claude/CLAUDE.md's "no new markdown design docs" rule to explicitly permit docs/ for public-facing explainers referenced from README or CONTRIBUTING — closes the loophole that forced this fix. Co-Authored-By: Claude Opus 4.7 (1M context) <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.
Summary
Closes two long-standing dead link chains in public docs (both present since before v0.1.0):
docs/architecture.md— referenced in both READMEs, never existed. Replaced with a 12-row justification table inline in README's Why each surface? section. Each row names the friction that appears if the surface is absent — not feature advertising.memory/project_phases.md— referenced from README × 2 and CONTRIBUTING. Lived in user-level Claude memory only, so every clone saw a 404. Materialized asdocs/project_phases.mdwith the 10-phase build order plus design rationale (why this sequence, why independently demoable). Private frontmatter stripped.Also updates
.claude/CLAUDE.md's "no new markdown design docs" rule to explicitly permitdocs/for public explainers referenced from README or CONTRIBUTING — closes the convention gap that let these dead links persist.Changes
docs/project_phases.md(31 lines, includes table + rationale + git-tag browse tip)README.md/README.en.md— dead link × 2 swapped for the inline surface table + repointed phases linkCONTRIBUTING.md:3— phases link repointed.claude/CLAUDE.md— phases link repointed, docs/ rule clarifiedTest plan
grep -r "docs/architecture\|memory/project_phases"— 0 matches in repodocs/project_phases.mdrenders as valid Markdown🤖 Generated with Claude Code