BrandTrackers Docs — requirements and acceptance

Approved finite milestone — 6 October 2026

STATUS: ACTIVE. The PLAN owns execution order and gates. This PRD owns requirements and acceptance. Joe approved execution of finite reconciliation and an implementation handoff, preserving all original requirements, decisions, exact replies, historical sources and broader A–G product commitments. The existing inventory is the only obligation tracker; the program report is its reader projection.

Required outcomes:

1. A coherent, published model explaining entities, products/features, groupings, content, moments and their relationships in plain language.
2. Consequential relationship/classification decisions resolved without reasking settled meanings.
3. Evidence-backed, dependency-ordered repair contracts for schema, pipelines and prompts.
4. An explicit account of remaining delivery for discovery, boards, trackers, reels, scoped Ask, documents, Briefing/Feed, collaboration and phone use.

Every relationship contract must cover meaning, participants, direction, multiplicity, time, evidence, corrections and practical research use, mapped to actual storage, constraints, writers/readers, prompts and workflows. Approved meaning, reconciled documentation, verified implementation and demonstrated acceptance are different states. Unknown evidence must remain unknown.

Assess every current page and vocabulary entry. Resolve consequential rules. Minor wording may remain visibly assigned outside approved guidance. Definitions, diagrams, generated references, machine answers and LLM output must agree. Generated legacy storage is not current approved vocabulary; unknown measurements are not zero. Preserve old links and historical records.

The landing label is Overview. Navigation prioritizes Overview, Model, Vocabulary, Pipelines and Technical reference before Decisions and History/internal notes. Current address: https://docs.brandtrackers.xyz. The prior Atlas host preserves old links by redirect; dated receipts below retain the address observed at the time.

Acceptance contract

Requirement	Completion evidence
Continuity	INDEX, PLAN and selected current HANDOFF agree; negative controls reject historical/missing/conflicting selection. Historical text and identifiers remain conserved.
Model	Concepts/shared rules, connected pillars, grouping relationships and shared vocabulary are reconciled in approved order. Consequential choices have exact answer trails.
Coverage	Every inventory obligation and vocabulary entry has a current four-dimensional assessment; each system object/workflow has scoped evidence or named limitation. No page-count completion percentage.
Real system	Structural audit covers types, constraints, junctions, indexes/query plans, views, routines, triggers, permissions and dependencies. Profiles are sampled and labeled. Deployed behavior requires an authorized backend read path, not merely API health or Supabase access.
Research cases	IBM/US Open; McDonald's/Minecraft; model-card/chart; vendor case study; newsroom trigger; whole video/matching moment; physical work/photograph/original asset; feature research across categories; repost/version; correction/reanalysis; unavailable/private evidence all receive explicit dispositions. Logical support, test, runtime observation and product acceptance remain separate.
Publication	Current guidance contains no known unresolved contradiction. Applicable checks include meaningful failing controls and literal output. Verify hosted revision, links, diagrams, human/LLM output and phone-width readability. This is not actual-phone product acceptance.
Handoff	Each repair contract includes all consumers, prerequisites, compatibility, migration/backfill, failure verification, rollback, release boundary and open evidence. A load-bearing unknown blocks readiness. No unresolved HIGH finding undermines the delivered guidance or handoff.
Broader delivery	Original A–G requirements and substrate implementation choices retain provenance, downstream dependencies and acceptance gates. Finishing this milestone does not certify repairs or the product.

This milestone changes Docs, review metadata, generators and validation interfaces only. It does not authorize production schema/API/prompt/classification/automation changes, paid processing, frontend expansion or historical deletion. The original PRD and later amendments below remain preserved. Current requirements above and the approved PLAN govern over dated scheduling instructions.

Historical requirements and acceptance receipts — preserved, not recertified

BrandTrackers Docs — PRD

STATUS: 🟢 ACTIVE (re-read 2026-09-12; the live window-id is the docs/INDEX.md §2 ATLAS row) · 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).

Current execution — 5 October 2026

The approved continuity and whole-program audit plan now governs. Graphics recommendations are answered. Recover original scope, audit the connected model and system, review ranked findings, then reconcile Docs and prepare repair contracts. Preserve this PRD and the broader A–G contract. Earlier scheduling amendments below are dated history, not current packet-preparation instructions.

Morning checkpoint — 6 October 2026

The morning reset is the current review entry. It reports completed audit work separately from unreconciled Docs, unverified runtime behavior and unimplemented repairs. This checkpoint preserves the requirements below and the broader product contract. Joe approved the adjusted correction sequence on 6 October: Concepts and shared rules, connected pillars, grouping relationships, then shared vocabulary. This does not approve production repairs or equate audit activity with product acceptance. The domain move to docs.brandtrackers.xyz is authorized in the existing project; preserve old links. Keep Overview as the landing-page label and place current model, vocabulary and technical guidance before decisions, history and internal notes. Goal activation follows the requested planning discussion.

Review amendment — 4 October 2026

The site is BrandTrackers Docs. At that checkpoint the address move was deferred. The 6 October approval above supersedes that deferral. The original brief and dated acceptance receipts below remain preserved, not recertified.

Joe requested a bounded reset of the full review inventory after the latest answers. The current review plan records the approved dependency order and acceptance gates. The existing research-experience PLAN at docs/reference/chatgpt-desktop-study/prototype/PLAN.md, approved execution sequence and its Unit103/Unit104 amendments retain the broader A–G scope. This PRD continues to own the Docs product requirements; the review page is their readable execution summary, not a competing implementation specification.

Before another sitting, reconcile original question identities, partial replies and decisions outside the numbered inventory. Ask only residual meanings, with bounded evidence that can change the recommendation. After the decision pass, complete the enumerated page/vocabulary/schema/pipeline audit and then repair verified defects. Broader frontend expansion remains held. No silent approval, schema mutation, processing or automation activation is authorized by this amendment.

Joe explicitly approved execution of this two-pass plan on 4 October. The existing review-reset-inventory.json execution section owns the queue and subject-to-source map. Recover related current and historical material before each batch; distinguish approved intent, current implementation and proposed improvement. Compare retaining, simplifying and selectively changing the model. Publish and verify the review before asking; bank exact replies and update affected guidance together. The ordinary preparation target is roughly 30 minutes, with named evidence blockers rather than an arbitrary accuracy cutoff.

Success for the decision pass means every item has a disposition and dependency, not merely that all numbered pages were visited. Audit completion requires item-level evidence; implementation and product acceptance remain separate.

Review availability amendment — 4 October evening

Joe may be away for hours and wants several independently checked review pages available for the morning of 5 October, between 06:30 and 07:30 America/New_York. The existing review plan is the single reader entry. Prepare ahead without inferring answers. Its readiness table is a reader projection of the existing inventory, not a second question ledger.

The current execution target is four new evidence-backed packets, then further independent packets where evidence permits. This is not a completion quota or a guarantee of four ready pages. Track every residual item; mark dependencies and evidence gaps explicitly. Each ready packet needs a bounded independent review, inspected examples, relevant system evidence, verified publication and an unambiguous answer path. Preserve the full decision-pass scope and the later comprehensive audit. The morning handoff reports actual readiness and outstanding work.

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).
• [x] The relationship matrix page: every allowed edge traced to a real foreign key. ✅ shipped ATLAS-SEP02-01 — _generated/relationship-matrix.md, 19 edges over live foreign keys, guarded by atlas-relationships --check.
• [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 last pillar yet — the substrate, the live site, the writing standard, Entities, Content & Moments and Groupings (renamed from Works & Groupings, 2026-08-17) are written; Concepts is the one model page still to write, after the walk.
• Not a new format or a custom in-app UI — markdown stays the source; VitePress renders it. AMENDED 2026-09-07 (DN-232). This still holds for the MODEL pages — the pillars and the reference are markdown, VitePress renders them, and llms-full.txt stays readable. It has not held for the DECISION surfaces since 25 August: the review pack, the console and now the hybrid sittings are generated HTML under docs/atlas/public/, because a decision surface needs real media, marks and an export that a markdown page cannot carry. Leaving this bullet unqualified made the lane's own product requirements forbid the work it was doing.
• 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.

Whole-program audit amendment — approved 5 October 2026

Joe approved a whole-program audit and Docs reconciliation while graphics answers remain pending. The program report gives the current assessment and review desk gives the current entry. This changes the immediate work from packet preparation to complete scope recovery and verification. It preserves this PRD, the original brief, prior approvals, prototype PLAN, detailed BUILD-CONTRACT and A–G scope.

Required output: original intent → latest decision → current explanation → actual storage/processing → user journey → acceptance evidence, with separate meaning/documentation/implementation/acceptance assessments in the existing inventory. Recover all walks, sittings, original acceptance cases, definitions and substrate-console gates. Audit every current page and vocabulary entry, every application-owned database object and relevant platform dependency, and full workflows discovered from actual entrypoints as well as registries. Explicitly distinguish dated evidence, current verification and missing evidence.

Publish the initial map before more small naming packets. Review findings and proposed correction order before substantive restructuring. Then reconcile current explanations and generated sources in bounded units; add meaningful negative controls to checks. Each confirmed defect needs an implementation contract with all consumers, migration/backfill needs, verification, rollback and release boundary. Production changes, further frontend expansion, repair completion and product acceptance are outside this audit milestone.