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

STATUS: 🟢 W1.5 (governance catch-up + rename + SITE LIVE) · Lane: ATLAS · Master plan: docs/atlas/PLAN.md (git-tracked) · Boot: docs/atlas/HANDOFF.md (or /resume-session ATLAS). 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) · the site auto-builds on deploy (always current) · scripts/atlas-drift.py fails the check on DB divergence (can't silently rot) · registered in the hook-enforced boot chain (every /resume-session ATLAS lands on it).

Structure (once built out — W2+)

• index.md — §0 thesis + pillar map (Mermaid)
• one file per pillar (entities · products · positioning · vendors-disciplines · groupings · content · moments · channels · audiences · vocabulary · signals?) — each = YAML frontmatter (machine: tables·edges·vocab·counts·status) + prose (human)
• relationships.md — §2 the allowed-edge matrix · pipelines.md — §3 · use-cases.md — §4 · decisions.md — §5 open forks · homes.md — §6 concept→owner-doc map
• PRD.md — goal / users / journeys / success criteria / acceptance
• _generated/ — schema-census.md (the live physical substrate: 184 tables / 2,296 cols / 200 FKs / 598 idx / 9 enums; ~48 are archive-snapshots → real surface ~136) — regenerate via scripts/atlas-census.py
• _research/ — phase1-deltas.md (the 5-agent corpus-mine + live-DB reconciliation buckets A/B/C)
• .vitepress/ — the site config (nav/sidebar/theme/llms.txt plugin)

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 at Vercel build time into frontend/public/_atlas/ (gitignored); 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. Deploy cadence follows the main app's manual promote (push → preview → vercel promote), which is a safety: a broken docs build fails only the preview, never prod. Full runbook + the domain/DNS step live in PLAN.md §W1.5-D + docs/DEVELOPMENT-LOOP.md.

Current state (W1.5)

• ✅ folder (docs/atlas/) + census (_generated/schema-census.md) + mining deltas in-repo (_research/) + census regenerator (scripts/atlas-census.py)
• 🟢 W1.5: rename → boot-chain wiring → 5 ledgers → VitePress site LIVE → atlas-drift.py → PRD → SessionStart recovery hook
• ⬜ NEXT (W2): fold the reconciled deltas into pillar files (Workflow-verified) → W3+ the walk (Joe rules the ~6 forks → decisions.md) → this un-pauses the PIPE lane's W2 BUILD.

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.