BrandTrackers Docs — docs/atlas/

STATUS: 🟢 ACTIVE · Live window = POINTER (DN-145): the window-id lives in the docs/INDEX.md §2 ATLAS row; the roadmap lives in docs/atlas/HANDOFF.md §Forward-plan · Lane: ATLAS · Master plan: docs/atlas/PLAN.md · Boot: docs/atlas/HANDOFF.md (or /resume-session ATLAS) · Writing standard (BINDING): docs/atlas/STYLE.md (incl. the 2026-08-17 review-loop rules). What this is. docs/INDEX.md says where things live. Atlas says what things MEAN and how they relate — the ONE place every future session (human or LLM) points at, so the industry logic never gets re-explained. It sits ABOVE the schema and the pipelines and points DOWN to the owner docs. Live, browsable site: atlas.brandtrackers.xyz (rendered from this markdown, drift-checked against the live DB so it can't silently rot — docs-as-code).

Why this exists (Joe's ask — the founding brief)

"Stop making me re-explain the logic — ONE canonical, human-readable, verified definition of every pillar, relationship, and pipeline that I point every future session at." Comparable platforms (Crunchbase / PitchBook / Bloomberg) call it a domain model / ontology spec / canonical data dictionary. The row-count spinning is a symptom of not having this.

• 📎 Founding brief: docs/reference/2026-07/2026-07-24/bigprompt-arch.md — Joe's original stream-of-consciousness 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.

The anti-rot guarantee (why it won't get lost this time)

Generated from recorded evidence, with checks. Source = versioned git markdown · generated measurements retain the date of their input snapshot and can become stale; refresh the probe before relying on an older measurement · atlas-drift.py fails on database divergence · atlas-examples.py --check fails when a worked example stops matching real rows · atlas-conformance.py turns each model-vs-reality gap into a check that goes green by itself when someone fixes it · atlas-canon-check.sh fails a model page that grows a bare number or an open question · atlas-carry-check.sh fails a close that drops a carried thread · atlas-reviewed-check.py fails a page edited after the date it says it was last read · atlas-walk-budget.py caps every review page against its measured baseline · boot-doc-freshness-check.sh Assertion H fails a §0 boot contract left stale · Vale fails a commit that slips back into jargon · and the lane is registered in the hook-enforced boot chain.

Structure — FOUR SURFACES (DN-218)

A page here answers exactly one kind of question, because a document that mixes them makes every reader classify every paragraph. The test for any sentence: what would have to happen for this to change?

Surface	Files	Changes when
The model — what a thing IS	index.md · pillars/*.md (one per family: Entities · Content · Moments · Groupings · Concepts)	a decision is ratified
Decisions — what is settled and what is not	decisions/open-questions.md (the review agenda) · decisions/decided.md (ruled, with the reasoning)	a question is ruled on
Reference — GENERATED, never hand-written	_generated/state-of-the-data.md (scripts/atlas-state.py) · _generated/conformance.md (scripts/atlas-conformance.py) · _generated/schema-census.md (scripts/atlas-census.py)	the data or the model moves
Internal notes — how this is built	PLAN.md · PRD.md · this file · _research/	any working day

The rule that follows: a model page contains no unresolved question and no bare number. Undecided goes to the questions ledger. A count is generated. A place where the system contradicts the model becomes a check on the conformance report — not a paragraph that goes stale and that nobody remembers to delete once it is fixed. scripts/atlas-canon-check.sh enforces this and names the offending line.

Every model page follows the same five-part pattern (see pillars/entities.md): a plain definition → a clickable mermaid map (diagrams, never components — llms-full.txt is built from the markdown) → the vocabulary and the rules, never the counts → a generated worked example from live rows → the four pointers out. Plain markdown, no YAML frontmatter.

Also here: .vitepress/ (site config + the llms.txt plugin) · _carry-manifest.txt (the threads this lane may never lose — scripts/atlas-carry-check.sh fails a close that drops one).

How to view it

• Local (fast, decoupled): npm run docs:dev → http://localhost:5173 (VitePress dev server, instant HMR). Source of truth = these markdown files.
• Live (canonical): https://atlas.brandtrackers.xyz.
• LLM entry: atlas.brandtrackers.xyz/llms.txt (+ llms-full.txt) — the raw-markdown boot surface for agents.

Deploy architecture (Joe-locked 2026-07-24b — DN-213)

Atlas ships from the EXISTING brandtrackers-app Vercel project (prj_My6gFrYuUlO2f58f1caAidd3PDkt) — NOT a new project (Joe's override of the earlier plan). VitePress builds LOCALLY (npm run docs:build) into frontend/public/_atlas/, and that output is COMMITTED to git — the Vercel project's root directory is frontend/, so docs/ is not in its build context and the site cannot be built there. The atlas.brandtrackers.xyz host is served via a host-gated rewrite in frontend/src/middleware.ts that bypasses WorkOS auth for that host only. Going live requires a vercel promote of a main build carrying that committed output. ✅ The out-of-memory promote failure is FIXED — the build script caps the V8 heap rather than raising it. Two rules survive it, both re-learned the hard way:

• A failed promote is silent. The previous build keeps serving, so the site looks healthy while new work never ships. Confirm the production deployment is READY and that its commit matches what you shipped.
• curl cannot verify this site. It fetches the server response, which stayed correct for five days while every subpage rendered a 404 in a browser. Load the pages in a real browser against the deployed host, and verify production ON production — the dev server serves at a different path and cannot reproduce the class of bug that hosting introduces.

Earlier checkpoint (12 September 2026; retained as history)

• ✅ The foundation — folder, census, regenerators, boot chain, the site at atlas.brandtrackers.xyz.
• ✅ Six model pages — Entities · Products · Groupings (renamed from Works & Groupings, 2026-08-17) · Content · Moments · the Overview. The four-surface split holds across all of them.
• ✅ The review, through two walk rounds — all 25 numbered questions + the three preliminary calls RULED; both vocabularies ratified at the type level; the browsable vocabulary reference generated (198 pages, in the close battery).
• ✅ The family reconciliation arc — surface + schema view + decision gallery built; the mechanism taken provisionally; the ratified type set 64 after the 16 August rulings and 69 since Joe's first sitting on 11 September kept five more words; the recommendation page was the ONE review surface (Joe's consolidation call, 17 Aug) and is now the record behind the review pack (/review/index.html, 25 Aug) — eight generated sections, 59 decisions since the DN-231 folds, one answer line each.
• ✅ The Pipelines section (2026-08-17) — six have-vs-need pages verified against the running code and live database.
• ⬜ OPEN — Joe's answers, one sitting at a time. The review pack produced no decisions in twelve days, so on 7 September he picked the hybrid: three to five decisions a page, all the same kind of question, answerable without opening anything. He walked the first sitting on 11 September and answered all five. The foundations sitting (/sittings/14.html, four questions about how things connect) was built the same day and waits on his answers. Every ruling is indexed in _data/rulings.json, and scripts/atlas-rulings-check.py stops a page from re-asking one. What is next lives in HANDOFF.md §0. Answers still come one line per decision by id (P-03: CONFIRM · S-01: CHANGE: … · N-01: LEAVE OPEN: …), and a sitting's "Show my answers to copy" box gives them in exactly that shape. His comprehensive content-types list is still to come (carry #22).
• ⬜ Then: Concepts → the five use-case walkthroughs re-cut against his answers → the final confirm (the relationship matrix is done).
• ↩ Then back to the pipeline lane. This lane is not the destination — see §Return-path at the top of HANDOFF.md. Two gates must clear, not one: these rulings and the separate, still-unwalked substrate console.

Current review checkpoint — 4 October 2026

Sittings 1, 14 and 11 have recorded answers. The current agenda is Open questions; the four latest decisions and review-cycle requirements are in Decided. The September directions above to wait for Sitting 14 or prepare Sitting 11 are superseded.

The site is named BrandTrackers Docs; Atlas remains its source directory and hostname. Draft vocabulary definitions still require a meaning review and a plain-language review. Existing generated measurements retain their stated snapshot dates. A build or a documentation check is not a fresh database audit. Before each new sitting, reconcile affected current guidance, independently inspect the relevant architecture and actual data path, then publish and verify the hosted review. Full-site reconciliation and downstream implementation remain open.

The scaffold that preceded this

docs/DOMAIN-MODEL.md (single-file scaffold, committed 2e62bd78a 2026-07-24) is the seed; its §0–§6 structure migrates into the per-file layout here.