docs: a map, and banners on the docs that describe a deleted architecture (Track 6) #52
Loading…
Add table
Add a link
Reference in a new issue
No description provided.
Delete branch "track6/docs-map"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Track 6, the last piece of C6.
The actual problem
docs/is already grouped by topic — the problem was never organisation. It's that a reader cannot tell which documents are current. Several describe stock Chromium +getDisplayMediadriven from outside the browser, in the present tense. M7 deletedcapture/streamer-page/and moved the WebRTC peer into the browser process, so those documents describe components that no longer exist.PROJECT_BRIEF.mdliterally has a section headed "Phase 0 — Foundations (where we are now)".Two changes, no files moved
1.
docs/README.md— a map. There was no index at all: landing indocs/gave you 11 directories and no signal. Grouped by what the reader is trying to do (integrate against a deployment / run it / change the browser itself / background), plus an explicit "Historical — do not read as current" section. All 26 links verified to resolve.2. Status banners on the five documents that needed one, each stating the specific fact rather than a generic "may be outdated" —
PROJECT_BRIEF.md, both phase-exit reports, the Phase 1 stack audit. (measurements/,demos/, andv1-success-criteria.mdalready had one, in the same> **Status:**idiom this follows.)What I deliberately did NOT deprecate
docs/operations/phase1-deployment-checklist.md. It looks like a Phase-1 artefact, but it's a checklist, not an architecture description — auth, TURN, observability, sandboxing, networking and capacity sizing are all unaffected by where the WebRTC peer lives.Exactly one of its 230 lines was stale: a "stock
infra/Dockerfileis fine" fallback pointing at an image M7 deleted. I fixed that line and the banner says "still current", with the review date. Blanket-deprecating it would have discarded good operational guidance to save a minute of reading.Why no
integrate/ operate/ contribute/treeThe original plan called for moving files into audience directories. I'd push back on that: every path in
docs/is referenced from code comments, other docs, and CLAUDE.md's "which to trust" table. A mass rename buys a tidierlsand costs every one of those references — and this repo has already been bitten by exactly that class of stale-pointer breakage. The index gives the same navigation with none of the churn. Happy to do the moves if you'd rather, but I don't think the trade is worth it.Verified
make verifypassesTrack 6. The problem was not that docs/ is disorganised — it is already grouped by topic — but that a reader cannot tell which documents are current. Several describe stock Chromium + getDisplayMedia, driven from OUTSIDE the browser, and read in the present tense. M7 deleted capture/streamer-page/ and moved the WebRTC peer INTO the browser process, so those documents describe components that no longer exist. PROJECT_BRIEF.md literally has a section headed "Phase 0 — Foundations (where we are now)". Two changes, no files moved: 1. docs/README.md — a map, grouped by what the reader is trying to do (integrate against a deployment / run it / change the browser itself / background), plus an explicit "Historical — do not read as current" section. There was no index at all before: landing in docs/ gave you 11 directories and no signal. All 26 links verified to resolve. 2. Status banners on the five documents that needed one, each stating the SPECIFIC fact rather than a generic "may be outdated": PROJECT_BRIEF.md, docs/phase-{0,1}-exit-report.md, docs/audits/phase1-stack-audit.md (docs/measurements/, docs/demos/, docs/v1-success-criteria.md already had one, in the same `> **Status:**` idiom this follows.) Deliberately NOT deprecated: docs/operations/phase1-deployment-checklist.md. It looked like a Phase-1 artefact, but it is a CHECKLIST, not an architecture description — auth, TURN, observability, sandboxing, networking and capacity sizing are all unaffected by where the WebRTC peer lives. Exactly ONE of its 230 lines was stale (a "stock infra/Dockerfile is fine" fallback, pointing at an image M7 deleted). Fixed that line, banner says "still current" and records the review date. Blanket-deprecating it would have discarded good operational guidance to save a minute of reading. Files are not moved into integrate/ operate/ contribute/ trees. Every path in docs/ is referenced from code comments, other docs, and CLAUDE.md's "which to trust" table; a mass rename buys a tidier `ls` and costs every one of those references. The index gives the same navigation without the churn. Verified: make verify passes; 71 internal links across all touched files resolve. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>