Atlas — PRD

STATUS: 🟢 ACTIVE (ATLAS-JUL24-01, 2026-07-24) · Owner: the ATLAS lane · Boot: docs/atlas/HANDOFF.md · Master plan: docs/atlas/PLAN.md · Decision of record: DN-213.

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 ~6 open forks and rules them (marks → decisions.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.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.

Acceptance (W1.5 exit)

• [ ] Site renders locally (npm run docs:dev → localhost:5173) and builds (npm run docs:build → frontend/public/_atlas/ + llms.txt).
• [ ] 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.
• [ ] scripts/atlas-drift.py --check --live … prints 0 drift, wired into /nightly-verify + /handoff.
• [ ] /resume-session ATLAS resolves to docs/atlas/HANDOFF.md; INDEX §1/§2 carry the lane; every governance ledger carries ATLAS-JUL24-01 (DN-213 · F-168 · A4.54).
• [ ] bigprompt-arch.md is cited (README + this PRD); zero orphans.

Non-goals (this phase)

• Not the full pillar prose (that is W2/W3) — W1.5 stands up the substrate + the live site; the model fills in against it.
• 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.