# Doc Trust Map — which document to believe ``` Status: Current Owner: _null Last reviewed: 2026-08-18 Governs: docs/** Review trigger: Any doc added, deleted or moved; any change to which doc owns a subject Fires on: added, deleted, moved ``` This describes what is **actually** in this repository, written after everything else was settled. Where it differs from the template it came from, this one is right about this project. ## Work items are not in this tree The sequence of work, the open defects, and the things blocking a release all live in this repository's **issue tracker**, not in `docs/`. Milestones are batches; issues are deliverables; severity labels are `P0`, `P1`, `P2` and `release-blocker`. This section exists to stop the next contributor starting a fresh markdown to-do list. **It has already happened here.** Before 2026-08-18 this project kept its work in `FUTURE.md`, a changelog in `HISTORY.md`, an agent log in `DEVELOPMENT_LOG.md`, and phase checklists in `PROJECT.md`, `STRUCTURE.md` and `README.md` — six records, beside 205 issues in a tracker that none of them pointed at. Two of those documents still described the project as being in "Phase 5" while the code was at `0.9.3`, and nothing anywhere said so. | Question | Answer lives in | | --- | --- | | What are we building, and for whom? | `docs/planning/PROJECT_PLAN.md` | | What standards does the code have to meet? | `docs/planning/REQUIREMENTS.md` — and they need `_null`'s approval to change | | What is the sequence of work? | milestones in the tracker | | What is left in this batch? | open issues under that milestone | | What is broken right now? | issues labelled `P0` / `P1` / `P2` | | What makes a release wrong? | issues labelled `release-blocker` | | What is the next action? | the `nextAction` field on the project at privacyllc.dev — the newest entry in `docs/history/DEVELOPMENT_LOG.md` says what it was *then* | | What is blocking us? | the tracker, for the work; the blockers table at privacyllc.dev, for the stakeholder-facing version | | What do I do when a piece of work is finished? | `docs/WORK_CYCLE.md` | | What is deployed, and what do I do when it breaks? | `docs/OPERATIONS.md` | | What happened, and when? | `docs/history/DEVELOPMENT_LOG.md` | | Why is it shaped like this? | `docs/history/HISTORY.md` — decisions, and what was tried and dropped | | What were the batches, before the tracker? | `docs/history/BATCH_LEDGER.md` — archived, must not be updated | | Did QA pass, and what does the tester think? | `docs/qa/ClaudeReport.md` | | What did QA actually reach? | `docs/qa/ClaudeQACoverage.md` — and here, the answer is *nothing yet* | | How is it built? | `docs/architecture/README.md` | | How does the CRM integration work? | `docs/architecture/zoho-setup.md` | | What should it look like? | `docs/design/OVERHAUL_PLAN.md` | | What should it sound like? | `docs/design/REDESIGN_REVIEW.md` | | Which script do I run, and can it stop me? | `docs/TOOLS.md` — the signpost; `docs/architecture/README.md` has the table | | What runs before a commit? | `.githooks/` | | How do I write a check that will actually catch something? | `docs/architecture/GUARDS.md` | **Next action and blockers are recorded at the end of every piece of work, not when somebody asks.** `docs/WORK_CYCLE.md` holds that procedure and the reason each step is in it. ## Folder layout | Folder | Contents | | --- | --- | | `docs/planning/` | `PROJECT_PLAN` — the vision. `REQUIREMENTS` — the engineering standards. Not the schedule; that is the tracker | | `docs/qa/` | `ClaudeQAPlan` (playbook), `ClaudeQACoverage` (what each pass reached), `ClaudeReport` (the verdict) | | `docs/architecture/` | `README` — boundaries, schema, response shapes, the script table. `GUARDS` — how to write a check. `zoho-setup` — the CRM manual | | `docs/design/` | `OVERHAUL_PLAN` — the visual system. `REDESIGN_REVIEW` — positioning and tone | | `docs/security/` | `SECURITY` — threat model and third parties. `SECURITY_CHECKLIST` — the pre-release list | | `docs/history/` | `DEVELOPMENT_LOG` (dated, append-only), `HISTORY` (the narrative), `BATCH_LEDGER` (archived) | | `docs/data/` | the branding marks privacyllc.dev renders for this project | | `docs/` root | this map; `WORK_CYCLE`; `TOOLS`; `OPERATIONS` | `README.md` stays at the repository root; it is the landing page and moving it breaks that. Everything else lives under `docs/`. ## What this project keeps that the template does not describe - **`docs/planning/REQUIREMENTS.md`** — engineering standards with a change policy attached. It is not the plan and not the architecture; it is the set of rules every agent works to, and it predates the template. Kept whole. - **`docs/design/OVERHAUL_PLAN.md`** — 25 KB, and **two documents in one file**. Its design brief onward is the live token and layout authority; its earlier migration-phase and agent-plan sections describe a rebuild that finished. Its own front-note says which half is which. Splitting it would have risked losing prose that nothing else records, so it was not split. - **`docs/architecture/zoho-setup.md`** — written for a non-technical reader. Note the trap in its own header: it documents the OAuth path, and production runs WebToLead. - **The agent pipeline** — Scarlett, Neo, Private Hudson, Bishop, Ripley — is in `README.md`, not in this tree, because it is how work is dispatched rather than a subject anything is authoritative about. `.learnings/` holds four agents' notes and is gitignored. ## What the template carries that this project deleted Recorded so a reader can tell a deliberate absence from an oversight. | Deleted | Why | | --- | --- | | `ClaudeQAPlan.md` pass I — money flowing backwards | no money moves through this site. A pass that never applies is noise | | `SECURITY_CHECKLIST.md` — the authorisation group, and the session-token row | there is no login, no session, no role and no per-user data anywhere in the product | | `SECURITY.md` — the *(precautionary)* bring-your-own-credential paragraph | **a precautionary rule, dropped deliberately.** It describes holding credentials on behalf of users; there are no users. `PROJECT_PLAN.md` records accounts as out of scope, which is what makes it safe to drop | Every other *(precautionary)* marker was kept. `OPERATIONS.md` was kept in full — this is a deployed service with a live origin, a named host and a database. **Pass H was kept and rewritten** rather than deleted. Its authorisation half does not apply; its *what a stranger can reach and exhaust* half is the most exposed surface this project has. ## A fifth severity label exists, and is frozen `P3` sits on 21 closed issues from before this repository adopted the convention. It is **not** one of the four names the Command Center queries, so a defect filed `P3` today would be counted by nothing. It was kept rather than deleted because removing it would erase the severity record on those 21 issues, and merged into `P2` would misstate them. **Nothing new gets it.** New defects use `P0`, `P1`, `P2` or `release-blocker`. ## Source-of-truth ladder When two sources disagree, believe them in this order: 1. **Verified code behaviour** — read the source. Note that on this project "run the tests" is not available: there are none 2. **The issue tracker** — for anything about state of work 3. **Specialist docs** — authoritative for their own subject only 4. **History and logs** — a record of *then*, not a description of *now* A document that describes work as done is describing what was true when it was written. The tracker is describing now. ## The status header Every document in this tree opens with one, immediately after its H1 — and so do the documents at the repository root, which `scripts/doc-triggers.py` reads alongside this tree. The root is read one level deep only. ``` Status: Current | Draft | Superseded | Archived Owner: Last reviewed: Governs: Review trigger: Fires on: ``` **Exactly those four status words.** A document whose status falls outside the list is reported as having an unknown one rather than being quietly accepted. `Historical` is the word this convention used to have and deliberately dropped — `Archived` covers it. **Review trigger** is the line that matters. "Last reviewed" ages on its own and a reader cannot tell a current document from an abandoned one by looking at it; a trigger names the event that should bring somebody back. A header carrying `Status` without `Review trigger` is reported as incomplete — that combination looks finished and is not. **Governs** is a comma-separated list, and an entry may explain itself after the glob with a spaced dash — `docs/data/** — the assets privacyllc.dev renders`. `doc-triggers.py` cuts the entry there and reads the globs from the left of it. **Use that form and no other.** A gloss in parentheses, or after a colon, is not recognised: the whole entry becomes the glob, matches nothing, and the document is silently never fired. **Fires on** is optional and only for the case where `Governs:` is much broader than the trigger. This file is the extreme of that gap — it governs `docs/**`, the broadest glob here, while its trigger is one of the narrowest. Omit the line unless it is genuinely needed; absent means fire on every kind. `scripts/verify.d/30-doc-headers` checks all of this on every `npm run verify`, which is what stops it being a convention people remember. ## Declaring a document deliberately absent A repository may decide it will not keep one of these documents in git. Say so **here**, one line per path, anywhere in this file: ``` Exempt: — ``` **Write the real path only when you mean it.** Outside a fenced block, an `Exempt:` line naming a real document is not an example — it is a declaration. Keep illustrations fenced, and use placeholders anyway, as the form above does. **This project exempts nothing.** It considered it: the internal history and planning documents were gitignored with the comment *"never commit"*, and exempting them was one of the three options on the table. Instead the Forgejo repository was made **private** on 2026-08-18 and the documents were committed, because a half-populated doc tree reports to privacyllc.dev as a half-adopted project and the reason for the secrecy was the audience, not the content. **`docs/data/` and `docs/data/img/` cannot be exempted.** A declaration naming either is refused rather than honoured, because the Command Center renders what is in them. ## One asset is genuinely missing, and that is not an exemption docs/data/img/banner.webp does not exist — named here without backticks deliberately, because `doc-claims.sh` reads a backticked path as a claim that the file is there, and this sentence is the opposite claim. `icon.webp` and `logo.webp` do exist, both converted from this project's own marks in `assets/`. No placeholder was generated, deliberately — a placeholder that looks finished outlives the issue that would have replaced it. It is filed as a `P2` issue instead, and the project card will render without a banner until somebody draws one.