ATLAS — docs/atlas/ — the domain-model constitution

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)

Not memory — generated + enforced. Source = git markdown (can't be lost) · every measurement is generated, so no page can carry a stale count · 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 · 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.

Current state (updated 2026-08-17; the live window-id is the INDEX §2 row)

• ✅ 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 now 64 after the 16 August rulings; 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, 67 decisions, 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: the review pack, one line per decision by id in chat (P-03: CONFIRM · S-01: CHANGE: … · N-01: LEAVE OPEN: …) + his incoming comprehensive content-types list.
• ⬜ Then: Concepts → the relationship matrix → the five use-case walkthroughs → the final confirm.
• ↩ 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.

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.