Atlas — PRD

STATUS: 🟢 ACTIVE (ATLAS-AUG10-02, 2026-08-10) · Owner: the ATLAS lane · Boot: docs/atlas/HANDOFF.md · Master plan: docs/atlas/PLAN.md · Decisions of record: DN-213 (lane + deploy) · DN-214 (plain language, Vale-enforced) · DN-215 (lane-generic guards · diagrams-not-components · generated examples) · DN-217 (both page shapes — superseded by Q17/DN-220: the split won, the combined page is deleted) · DN-218 (the four surfaces) · DN-219/220 (all 25 questions ruled) · DN-221 (both vocabularies ratified).

Goal

Give BrandTrackers one canonical, verified, human- and machine-readable definition of the domain — every pillar, the relationships between them, the pipelines that write them, and the open decisions — so the industry logic is stated once and pointed at from every future session, instead of being re-explained from Joe's head and ~17 partial docs.

This is the missing top of the Authority Map: the conceptual layer that sits ABOVE the schema and the pipelines and points DOWN to each layer's one authoritative owner doc. It reconciles; it does not replace the good per-layer specs.

Founding brief: docs/reference/2026-07/2026-07-24/bigprompt-arch.md — Joe's original ask (companies → products → features · brand & identity vs marketing · the IBM × US Open credit chain · the ChatGPT model-card routing problem · "make sense of it, probe, verify, look at the database"). Atlas is the answer to that brief.

Users & their jobs

1. Joe (human reviewer) — the primary user. Away from keyboard or at the desk, he needs to look up what a pillar means, how two things relate, or what's still undecided, and to expand/correct a definition. He reviews the structure before any prose chapter is written, and later walks the open questions and rules them (agenda → decisions/open-questions.md; rulings → decisions/decided.md). Needs: browsable, searchable, always-current, canonical.
2. A fresh LLM session (the boot user). Every /resume-session ATLAS (and, over time, other lanes) reads Atlas to load the domain model before making decisions. Needs: clean raw markdown + an llms.txt / llms-full.txt entry; facts that trace to the live DB, not to memory.
3. The future product surface (downstream). The same ontology that governs classification is the spine a customer-facing "map of the domain" could later render. Atlas is authored so that model is reusable, not re-invented.

Journeys

• Look up a definition. Open atlas.brandtrackers.xyz (or npm run docs:dev), search or navigate to the pillar, read the plain-English definition + its verified state + its authoritative-home pointer.
• Trace a relationship. Go to the relationship matrix: source pillar → verb → target → junction/column → carries-provenance? → which pipeline writes it. "Fix-X-break-Y" becomes a diff, not a surprise.
• Rule an open fork. During the walk, Atlas presents each fork as a question with the live evidence; Joe marks it; the mark lands in decisions/decided.md as ratified logic — which is exactly what PIPE's paused W2 BUILD was gated on.
• Boot a session. A fresh window runs /resume-session ATLAS, lands on the HANDOFF, reads the pillar files + census, and starts from a verified model.

Success criteria

• Single source of truth: for any pillar/relationship/pipeline question, there is exactly one place the answer lives, and it wins over any conflicting doc.
• Verified, not remembered: every load-bearing fact traces to a live-DB probe; the census is regenerable; scripts/atlas-drift.py --check prints 0 drift.
• Always current: the site builds from git markdown; a schema change that isn't reflected trips the drift check.
• In the boot chain: /resume-session ATLAS resolves; INDEX §1/§2 name it; it is never an orphan again.
• Reachable anywhere: a canonical live URL (atlas.brandtrackers.xyz) so Joe can review away from keyboard.
• Legible to both readers (BINDING — DN-214): reader pages are plain language a first-time human understands, with no internal codes, raw database ids, or file:line citations — and Vale blocks the commit when they slip. The same content must remain readable as text in llms-full.txt, which is why relationships are mermaid diagrams and never components.
• Anchored in real rows: every pillar shows a worked example generated from live data. A model you cannot check against reality cannot be corrected.
• Checkable because the layers are separate (DN-218): a model page states what a thing IS and carries no unresolved question and no bare number. Measurements are generated (state-of-the-data); places where the system contradicts the model are checks (conformance) that go green by themselves when someone closes the gap; undecided things live in the questions ledger. A model page can then be wrong only about meaning — the one thing reading it can actually catch.

Acceptance — W1.5 exit ✅ MET (verified 2026-07-24)

• [x] Site renders locally (npm run docs:dev → localhost:5173) and builds (npm run docs:build → frontend/public/_atlas/ + llms.txt). (both scripts in the root package.json; llms.txt + llms-full.txt emitted)
• [x] Served live at atlas.brandtrackers.xyz from the existing brandtrackers-app project (DN-213), auth-bypassed for that host; the app host still auth-gates. (live returns 200 with <title>Atlas</title>; www.brandtrackers.xyz/admin still 307s to login)
• [x] scripts/atlas-drift.py --check --live … prints 0 drift, wired into /nightly-verify + /handoff. (battery item 11; verified ✓ atlas in sync (184 tables, 0 drift))
• [x] /resume-session ATLAS resolves to docs/atlas/HANDOFF.md; INDEX §1/§2 carry the lane; the governance ledgers carry the window. (and as of ATLAS-JUL24-02 the close guards actually audit THIS lane — before that they audited PIPE, F-170)
• [x] bigprompt-arch.md is cited (README + this PRD); zero orphans.

Acceptance — ATLAS-JUL24-02 exit ✅ MET

• [x] A written legibility standard (STYLE.md) enforced by Vale on reader pages — proved it blocks a page containing an internal code, a raw database id, or a file:line citation.
• [x] Relationships are navigable: clickable mermaid maps on the overview and the Entities pillar, and the same content readable as text in llms-full.txt.
• [x] A real worked example generated from live rows into the page (scripts/atlas-examples.py), names and counts only, --check clean.
• [x] The Entities pillar is the complete pattern every remaining pillar copies.

Acceptance — W2 exit (partially met)

• [x] Content & Moments written to the Entities pattern. (ATLAS-JUL24-03 published it both ways on Joe's call; Q17 then ruled for the SPLIT at the 2026-08-10 review — the combined page and its generator are deleted)
• [x] Works & Groupings written to the pattern, on the ruled ground, with the brand→container→piece→credit chain generated from real rows. (ATLAS-AUG10-02; Vale clean, --pillar works --check clean, conformance C14)
• [ ] The Concepts pillar (owes the craft-rulebook GENERATED page + the audience definitions list).
• [ ] The relationship matrix page: every allowed edge traced to a real foreign key.
• [x] Every number on the pillars written so far re-probed live in the window that wrote it. (each pillar window re-probes its whole surface; worked examples are generated from those snapshots, not typed)
• [x] The four surfaces exist and are enforced — model / decisions / generated reference / internal notes, with scripts/atlas-canon-check.sh failing a model page that carries a bare count, an open question, or a missing pointer. (ATLAS-JUL24-03; proven to bite on all three rules)
• [x] Joe picks the Content & Moments page shape at the review; the losing shape is deleted. (Q17 — the split; executed 2026-08-10)
• [x] Every numbered open question ruled, each ruling written into the model page it affects and — where it implies something must be true of the data — into a conformance check. (all 25 + R1–R3 ruled at the two walk rounds; C12/C13 landed ATLAS-AUG10-02; the ledger now holds only the still-open threads — crew-role · families 9/10 · the promotion-round marks)

Non-goals (this phase)

• Not the remaining pillars yet — the substrate, the live site, the writing standard and the Entities exemplar are done; W2 writes Content & Moments, Groupings (renamed from Works & Groupings, 2026-08-17), and Concepts, one per window.
• Not a new format or a custom in-app UI — markdown stays the source; VitePress renders it.
• Not the FE asset-detail modal or moments→admin wiring (a parallel lane — Atlas does not touch it).
• Not a schema/pipeline change — Atlas describes and reconciles; changes flow through the normal DN + migration path.