akashic / the long memory
Roadmap.
What we’re building, in priority order. Ten workstreams, each broken into stable-numbered items so we can reference them in commits, issues, and conversation. No public dates — only ordering and intent. This page renders directly from MASTER_BUILD_PLAN.md in the repo, so it cannot drift from what we’re actually tracking.
How to read this
- Item numbers are stable. Item 3.6 is always “/llms.txt + /llms-full.txt.” If we drop an item, we strike it; we never renumber.
- T-shirt sizes. XS ≤ 1 day, S 1–3 days, M 3–7 days, L 1–3 weeks, XL 3+ weeks.
- Dependencies are cross-referenced. “Depends on 2.1” means item 2.1 has to ship first. The critical path is summarized near the bottom.
- Per-item drill-downs. The strategic table here is the surface; each item has a detailed drill-down (technical approach, file-by-file plan, verification) and a playbook (numbered command-level steps) in the repo’s
drill-down/andplaybook/directories.
The plan
# Master Build Plan — Akashic / The Long Memory
> **Status:** v0.1 master skeleton, generated 2026-05-20.
> Companion to `BUILD_STATUS.md` (what's shipped) and `PLACE_PAGES_PLAN.md`
> (Phase 1–4 record). Drill-down expansions are added inline under each
> item as we go. Items are stable-numbered so we can reference them
> (e.g. "expand 3.2", "block 7.1 on 2.4").
---
## 0 · Strategic frame
Akashic today is **a deep static reference site for US political geography**
(3,143 counties + 8,243 tier pages live, Worker SSR for the long tail).
The platform value is unusual in three ways:
- **Depth per page** — 148 years of presidential results, full ACS demographics,
precinct geometry, narrative prose, similarity graph, custom OG card.
- **Coverage** — every legal political geography the US tracks, not just counties.
- **Provenance** — every figure traces to a named federal/academic source.
The work ahead falls into ten workstreams. Roughly:
| # | Workstream | Headline goal |
|---|---|---|
| 1 | Data integrity & coverage | Close the SLD/CBSA/DMA gaps; non-place demographics; fresher data |
| 2 | Deployment topology | Unblock Option B, consolidate domains, bind `place.akashic.app` |
| 3 | SEO & AI-SEO packaging | JSON-LD everywhere, llms.txt, canonical hygiene, robots policy |
| 4 | Product surface & UX | Long-tail `/place/*`, breadcrumbs, faceted browse, FAQ pages |
| 5 | Performance & Core Web Vitals | Precinct SVG diet, hero responsive, lazy-load heavy widgets |
| 6 | Editorial & content | Fill missing subheads, write non-county narratives, glossary, citations |
| 7 | Governance & open data | Licensing, attribution, JSON/CSV downloads, citation widget |
| 8 | Auth, canvas & UGC | Email verify, canvas UX polish, sharing, profile pages |
| 9 | Observability & analytics | Search Console, Cloudflare Analytics, Neon plans, error budgets |
| 10 | Brand & marketing surface | Logo, social, sitelinks search, press kit, partnerships |
T-shirt sizes throughout: **XS** ≤ 1 day, **S** 1–3 days, **M** 3–7 days,
**L** 1–3 weeks, **XL** 3+ weeks.
---
## 1 · Data integrity & coverage
**Goal:** Every place page renders the most complete, current, well-attributed
data the underlying sources allow; gaps are minimized and disclosed.
| # | Item | Size | Depends on | Why |
|---|---|---|---|---|
| 1.1 | Fill SLD crosswalk gaps (4,985 SLD-lower + 1,986 SLD-upper missing) | M | Neon work | Doubles SLD coverage |
| 1.2 | Multi-state CBSA constituent counties | S | — | Today only primary state's counties surface |
| 1.3 | DMA choropleth (currently deferred) | S | 1.2 pattern | DMAs render mapless |
| 1.4 | Pre-aggregate `mv_place_demographics` for CBSA/DMA/SLD | M | Neon work | Worker shows "—" placeholders today |
| 1.5 | Per-precinct results beyond 2024 (add 2020, 2016 backfill) | L | Neon `result_facts` | Single-year precinct view limits the storytelling |
| 1.6 | State legislative + congressional election history (not just presidential) | XL | Source acquisition | Unlocks SLD pages as genuine reference, not just president-rolled-up |
| 1.7 | House/Senate roll-call results per CD | L | C-SPAN / GovTrack / Voteview | Adds "how their rep votes" context to CD pages |
| 1.8 | Annual ACS refresh automation | S | CI | Today it's a hand-run pipeline |
| 1.9 | Election cycle ingest automation (2028 ready by 2027-Q4) | S | 1.8 pattern | Avoid scramble after each election |
| 1.10 | Historical CD boundaries (per redistricting era, not just 118th) | M | `geographies.valid_from/valid_to` already tracks | Lets us serve `/cd/{id}?cycle=2013-2023` |
| 1.11 | Data freshness API endpoint (`/api/data-freshness`) | XS | — | Surfaces source-by-source as-of dates |
| 1.12 | Schema drift CI (prevent silent ACS-variable renames) | S | — | Audit fix plan noted this already bit B17020 |
---
## 2 · Deployment topology & infrastructure
**Goal:** Single deployment story, one canonical domain per audience, no
file-cap workarounds, custom domains everywhere.
| # | Item | Size | Depends on | Why |
|---|---|---|---|---|
| 2.1 | Unblock Option B (`@cloudflare/next-on-pages`) | M | upstream peer-dep | One project, no 20k cap, native SSR for long tail |
| 2.2 | Bind `place.akashic.app` → Worker | XS | DNS | OG card URLs + Better Auth `baseURL` already assume it |
| 2.3 | Consolidate `akashic.app` / `www.akashic.app` / `akashicedge.com` (301 to canonical) | S | DNS + Cloudflare rules | Today: split equity, duplicate indexing risk |
| 2.4 | Move tier pages onto `akashic.app` subpaths (or keep `tiers.*`) — decide & enforce | S | 2.1 ideal | Site looks like one product, not three |
| 2.5 | Move OG cards to R2 (or keep static) — decide on the 4,750-image budget | S | — | If we lift the 20k cap (via 2.1), this becomes moot |
| 2.6 | Sharp-rendered SLD OG cards (currently shared default) | S | 2.1 lifts file cap, OR R2 | Closes the social-card gap on 6,596 pages |
| 2.7 | GitHub Actions deploy pipeline for all three projects | S | — | Today: manual `wrangler pages deploy out` |
| 2.8 | Branch previews for marketing changes | XS | CI | Lets editorial work get reviewed |
| 2.9 | Wrangler `routes` configuration (instead of *.workers.dev) | XS | 2.2 | Trivial after the custom domain is bound |
| 2.10 | Move Neon connection to pooled endpoint for Worker reads (keep unpooled for auth writes) | S | — | Better Auth's path needs the unpooled endpoint; reads can be pooled |
| 2.11 | Cloudflare cache tag strategy (`Cache-Tag: place,geo:{id}`) for surgical purge | S | Cloudflare Enterprise feature — verify plan | Today: 24h TTL or full purge |
| 2.12 | Edge-side error handling (5xx → cached fallback HTML) | XS | — | One-line resilience |
---
## 3 · SEO & AI-SEO packaging
**Goal:** Make the site the reference LLMs cite when asked about US political
geography. Traditional SERP wins are a happy side effect.
| # | Item | Size | Depends on | Why |
|---|---|---|---|---|
| 3.1 | Fix `robots.ts` `akashic.com` → `akashic.app` typo | XS | — | Sitemap line currently points at wrong host |
| 3.2 | Robots.txt: explicit AI crawler policy (GPTBot, ClaudeBot, Google-Extended, PerplexityBot, etc.) | XS | — | High-trust signal; lets us throttle individually later |
| 3.3 | JSON-LD on every page (Article + AdministrativeArea/Place + Dataset + BreadcrumbList + Organization) | M | 6.3 (Wikidata sameAs) | Currently ZERO structured data |
| 3.4 | `alternates.canonical` per page (all tiers + Worker) | S | 2.2/2.3 | None today; Worker canonical points at workers.dev |
| 3.5 | OG completeness pass: `og:url`, `og:locale`, `og:image:alt`, `article:published_time/modified_time` | XS | — | Misses on every page |
| 3.6 | `/llms.txt` + `/llms-full.txt` | XS | 7.1 (license decided) | Emerging convention, fast win |
| 3.7 | Citable-facts panel (`<dl>` Key Facts above the fold) on every place page | S | 6.4 (sources catalog) | LLMs lift labeled facts, not buried prose |
| 3.8 | TL;DR paragraph (30 words, keyword-rich) at top of every place page | S | template work | What gets quoted verbatim |
| 3.9 | Semantic HTML upgrades: `<article>`, `<section><h2>`, `<time datetime>`, `scope=` on table th | XS | — | Replaces `<div class="major-section-header">` |
| 3.10 | Sitemap index + per-tier sitemaps + real `lastmod` from data_freshness | S | 1.11 | Today: single big sitemap, lastmod=build date |
| 3.11 | Worker canonical/`noindex` decision (either bind domain in 2.2 + correct canonical, or `X-Robots-Tag: noindex` until then) | XS | 2.2 | Worst-of-both today |
| 3.12 | Per-page titles upgraded with geo type + state suffix (state/CBSA/DMA/CD/SLD currently bare) | XS | — | "Pittsburgh" → "Pittsburgh Metro Area Elections 1876–2024 — The Long Memory" |
| 3.13 | Per-page descriptions: keyword pass + 160-char clamp | XS | — | Currently 1 in 8 truncates in SERPs |
| 3.14 | FAQ schema generator (Q&A pregenerated per place: "How did X vote in 2024?", "What's X's archetype?") | S | 6.7 (FAQ copy) | Direct AI-Overview surface |
| 3.15 | `<title>` + `<desc>` on inline SVGs (precinct, choropleth, sparkline) | XS | — | A11y + crawl |
| 3.16 | Index pages: `/state/{abbr}/counties/`, `/archetype/{key}/`, `/cbsa/by-state/{abbr}/` | M | 4.6 | Closes "all bellwether counties" type queries |
| 3.17 | Search Console + Bing Webmaster + IndexNow ping | XS | 9.1 | Fast indexation after each deploy |
| 3.18 | `next-sitemap` or hand-rolled multi-host sitemap rebuilder in CI | S | 3.10 | Today: build-time only |
---
## 4 · Product surface & UX
**Goal:** Visitors (human or LLM) can navigate from any place to every related
place in ≤3 clicks; the long tail is just as reachable as the marquee.
| # | Item | Size | Depends on | Why |
|---|---|---|---|---|
| 4.1 | Long-tail `/place/{geo_id}` (incorporated place / CDP) — currently Worker-only | M | 2.1 or 2.2 | 31,909 places unlocked |
| 4.2 | Breadcrumb nav component on every place page (Home › State › County etc.) | S | 4.6 (parent links) | Crawl + UX |
| 4.3 | "All counties in {state}" index page | S | 3.16 overlaps | Today: only via search/sitemap |
| 4.4 | "All CBSAs/DMAs/CDs in {state}" index pages | S | 4.3 pattern | Same reasoning, per tier |
| 4.5 | "All {archetype} places" browse pages with map | M | 3.16 | Pivot view; very citable |
| 4.6 | Resolve & link parent geographies on every page (county → state, county → CBSA/DMA/CD, CD → state) | S | — | "More in {state}" rail exists; structured parent links don't |
| 4.7 | Sibling navigation (prev/next county alphabetically within state; prev/next CD) | XS | — | Tiny but loved-by-power-users |
| 4.8 | Compare two places side-by-side (`/compare/{idA}/{idB}`) | M | — | LLMs love compare pages; humans share them |
| 4.9 | Historical era pages for redistricted CDs (`/cd/{id}/2013-2023`) | M | 1.10 | Today: only the 118th |
| 4.10 | Mobile UX pass (touch targets, table-on-mobile reflow, hero on small screens) | M | — | Audit mentioned but not verified |
| 4.11 | Print stylesheet for place pages | XS | — | Researcher/journalist surface |
| 4.12 | Dark/light toggle (today: dark only) | S | — | Optional |
| 4.13 | Custom-shape feature graduated: featured shapes, shape gallery, shape forking | M | 8.x | Today: drawable + shareable, but no discovery |
| 4.14 | Atlas Q&A surface (Neon already has it) — `/ask` natural language → place page | L | LLM infra | Unique product; differentiator |
| 4.15 | Polymarket / prediction-market overlay on each place (Neon has the integration data) | M | — | Live signal layer |
| 4.16 | Embeddable widgets (`<iframe src="https://akashic.app/embed/county/{fips}/sparkline">`) | M | 7.3 | Distribution play |
---
## 5 · Performance & Core Web Vitals
**Goal:** LCP < 2.0s on 4G, CLS < 0.05, HTML payload < 80 KB on every place page,
crawl budget healthy.
| # | Item | Size | Depends on | Why |
|---|---|---|---|---|
| 5.1 | Run `topojson-simplify` on precinct SVGs (devDep already installed) | S | — | Today some SVGs are 1–2 MB |
| 5.2 | Lazy-load precinct SVG client-side after first paint (fetch + inject) | S | 5.1 | Removes from LCP path |
| 5.3 | Hero image `srcset`/`sizes` + WebP/AVIF variants | S | re-encode pipeline | Currently full-res Wikimedia JPEG |
| 5.4 | `loading="lazy"` + `decoding="async"` on every non-hero image | XS | — | Easy free pickup |
| 5.5 | Defer Outfit weights we don't actually use (loaded 200/300/400/500/600/700) | XS | — | Verify which weights ship |
| 5.6 | Explicit `Cache-Control` headers for HTML + assets via `_headers` file | XS | — | Today: Cloudflare defaults |
| 5.7 | Brotli compression on JSON data files | XS | Cloudflare | Likely on by default; verify |
| 5.8 | Drop unused JS from the per-page bundle (analyze with `next build --debug`) | S | — | React 19 + client islands; verify size |
| 5.9 | Pre-warm Worker isolates (Cron Trigger ping) | XS | 9.x | Cold start matters for AI-crawler quality scores |
| 5.10 | CLS audit: fixed dimensions on precinct map, choropleth, sparkline containers | XS | — | SVG without explicit size shifts layout |
| 5.11 | INP audit: SearchInput keystroke + autocomplete render time | XS | — | `counties_index.json` could be sizable |
| 5.12 | `counties_index.json` size audit + split-by-letter if needed | S | 5.11 | Lazy-loaded but ships ~3,143 entries today |
---
## 6 · Editorial & content
**Goal:** Every page has unique, attributable, fact-dense prose. Tone is
documentary, not editorial-opinion. LLMs and humans alike read it as authority.
| # | Item | Size | Depends on | Why |
|---|---|---|---|---|
| 6.1 | Fill missing editorial subhead/description (Adams PA 42001 done; verify zero gaps across all 11,732 pages) | S | — | Manifest sweep |
| 6.2 | Non-county editorial copy: state/CBSA/DMA/CD/SLD per-tier subheads (Neon has ~50% coverage of CD/SLD) | L | LLM + editorial review | Generated then human-pass |
| 6.3 | Wikidata QID + Wikipedia URL per place (`sameAs` backfill) | M | wbsearchentities script | Knowledge graph link |
| 6.4 | Per-figure inline source attribution (ElectionsTable currently global) | XS | — | LLM citation hygiene |
| 6.5 | Glossary page + `<abbr title>` overlay for archetype/CBSA/MSA/SLD/PVI terms | S | — | Lowers comprehension cost |
| 6.6 | Methodology white-paper version (deep-dive `/methodology` beyond `/about`) | M | writer time | Citable in itself |
| 6.7 | FAQ Q&A copy per place (template + LLM fill: "How did X vote in 2024?" etc.) | M | 3.14 schema target | Surface for AI Overviews |
| 6.8 | Editorial style guide doc (voice, factual rules, anti-spin) | S | — | Multi-author safety |
| 6.9 | Updated About page reflecting new tiers, Worker, canvas, archetypes-as-of-2024 | XS | — | Currently county-centric |
| 6.10 | Rewrite hero copy on long-arc realigners (auto-check that "For 72 years…" reads correctly for every realigner, not just McDowell) | S | regression suite | Audit/QA pass |
| 6.11 | Tone QA on the 12 narrative templates: make sure they read well at the extremes (tiniest county, biggest county, post-realigner, etc.) | S | — | Easy editorial polish |
---
## 7 · Governance & open data
**Goal:** Make Akashic the obvious data citation in journalism, academia, and LLM
training pipelines. Clear license, clean exports, easy to give credit.
| # | Item | Size | Depends on | Why |
|---|---|---|---|---|
| 7.1 | Choose & publish license (CC BY 4.0 recommended for original content) | XS | — | Required for 7.x, 3.6 |
| 7.2 | `/ATTRIBUTION.txt` + `/LICENSE.txt` with per-source license declarations | XS | 7.1 | Standard practice |
| 7.3 | Public data downloads: `/data/per_county/{fips}.json` already exists; document it; mirror CSV variants | S | — | Bulk download endpoint |
| 7.4 | Bulk dataset releases: `akashic-elections-2024.csv.gz`, `akashic-demographics-2024-acs.csv.gz` | M | 7.3 | Citable, archivable |
| 7.5 | "Cite this page" widget (BibTeX / MLA / APA / Chicago auto-format) | S | 7.1 | Journalism / academic adoption |
| 7.6 | Press kit: logo, brand colors, copyright-free screenshots, fact sheet | S | 10.1 | Lowers cost for journalists to cover us |
| 7.7 | Public roadmap page (`/roadmap`) — this file, lightly edited | XS | this plan stabilizes | Transparency |
| 7.8 | DOI per dataset release (via Zenodo or DataCite) | M | 7.4 | Academic citation gold standard |
| 7.9 | Embeddable widget license (separate from data license) | XS | 4.16 | Avoid ambiguity for press embeds |
---
## 8 · Auth, canvas, and user-generated content
**Goal:** Canvas (draw a polygon, see its history) becomes a real product
surface, not a hidden feature. Auth is robust.
| # | Item | Size | Depends on | Why |
|---|---|---|---|---|
| 8.1 | Email verification (Resend or SES) | S | provider account | Today: disabled "MVP" comment in `auth.ts` |
| 8.2 | Password reset flow | S | 8.1 | Standard expectation |
| 8.3 | OAuth providers (Google, GitHub) via Better Auth | S | — | Lowers signup friction |
| 8.4 | Rate-limit auth endpoints (Cloudflare Turnstile or Better Auth built-in) | XS | — | Today disabled with comment "Cloudflare WAF handles it" — verify |
| 8.5 | Profile page (`/profile`) — your saved shapes, your shape gallery | S | — | Today: shapes exist, no profile UI |
| 8.6 | Public profile (`/u/{handle}`) — opt-in | M | 8.5 | Sharing/discovery |
| 8.7 | Canvas UX polish: zoom + pan map, snap-to-county/precinct, undo/redo refinement | M | — | Today: CONUS bounding-box only, manual lon/lat clicks |
| 8.8 | Canvas: import GeoJSON / KML / shapefile | M | — | Power users (campaign consultants, journalists) live here |
| 8.9 | Shape gallery (featured custom shapes, browse public ones) | M | 4.13 | Community surface |
| 8.10 | Shape API (`POST /api/shape` returns JSON for embedding) | S | 7.9 license | Power-user surface |
| 8.11 | Shape comments / annotations | M | 8.5 | Engagement layer |
| 8.12 | Permissioned shape sharing (`/shape/{id}?token=...`) | S | — | Pre-public preview |
---
## 9 · Observability & analytics
**Goal:** We know what's slow, what's broken, what's getting cited, and where
traffic is coming from — without guessing.
| # | Item | Size | Depends on | Why |
|---|---|---|---|---|
| 9.1 | Set up Google Search Console for all hosts + IndexNow integration | XS | 3.18 | We're flying blind on indexed count |
| 9.2 | Bing Webmaster + IndexNow | XS | 9.1 | Bing powers ChatGPT search |
| 9.3 | Cloudflare Analytics per project + Worker (already present, but build a dashboard) | XS | — | Traffic / cache hit / errors |
| 9.4 | Neon query plan audit (`EXPLAIN ANALYZE` on every Worker query) | S | — | Risk noted in PLACE_PAGES_PLAN |
| 9.5 | Real-user monitoring (web-vitals → Cloudflare Analytics Engine or a third-party) | S | — | Validates 5.x work |
| 9.6 | Lighthouse CI on a representative set of pages (county, state, CD, SLD, Worker) per deploy | S | 2.7 CI | Regression catch |
| 9.7 | Error reporting (Sentry / Cloudflare Workers Logpush → durable store) | S | — | Today: `wrangler tail` only |
| 9.8 | Sitemap submission health check (cron — alert on drop in indexed count) | XS | 9.1 | Catch SEO regressions |
| 9.9 | Referrer log to detect AI crawler citations (Perplexity sends a `Perplexity-User` referrer; tally) | S | 9.7 | Confirms 3.x work paid off |
| 9.10 | Uptime ping on all hosts + Worker (UptimeRobot or Cloudflare Workers HealthCheck) | XS | — | Free assurance |
| 9.11 | Build-time data validation report (HTML summary of `validate-output.ts`) | XS | — | Today: console output only |
---
## 10 · Brand & marketing surface
**Goal:** When someone hears about Akashic, what they find communicates the
product clearly and looks like a real institution, not a hobby site.
| # | Item | Size | Depends on | Why |
|---|---|---|---|---|
| 10.1 | Logo file in repo (`public/logo.svg` + favicon set) | XS | — | Referenced by JSON-LD Organization, missing today |
| 10.2 | Apple touch icon, manifest.json (PWA-lite) | XS | 10.1 | Polish |
| 10.3 | Social presence: Twitter/X handle + Bluesky + auto-share on launch | XS | — | Distribution path |
| 10.4 | Newsletter capture on home + about | S | provider (Buttondown / Resend) | Audience asset |
| 10.5 | Launch announcement blog post + place on `/blog` | S | — | Press peg |
| 10.6 | Press kit page `/press` | S | 10.1 | Reduces friction for coverage |
| 10.7 | Partner outreach: MIT Election Lab, ICPSR, Pew, Cook Political, Sabato's, FiveThirtyEight alumni — get cross-links | L | 7.x | Backlink + credibility |
| 10.8 | Wikipedia presence: add Akashic as an external reference on highly-trafficked county pages (must be done by neutral editors, not us) | L | 6.3 sameAs | Massive AI grounding signal |
| 10.9 | Conference / talk submission (NICAR, Code for America, AAPOR) | M | 10.6 | Builds the citation graph |
| 10.10 | Sitelinks search box (Organization JSON-LD `potentialAction`) | XS | 3.3 | Free Google sitelinks if title authority earned |
---
## Quick-glance critical path (where most other things wait on)
```
2.2 (bind place.akashic.app)
├── 3.4 (canonical URLs)
├── 3.11 (Worker canonical/noindex)
├── 4.1 (long-tail /place/*)
└── 8.x (auth domain hygiene)
2.1 (Option B / next-on-pages)
├── 2.4 (consolidate tier paths)
├── 2.6 (SLD OG cards)
└── 5.x performance gains it unlocks
7.1 (license)
├── 3.6 (llms.txt)
├── 7.x (downloads, citation)
└── 4.16 (embeddable widgets)
3.3 (JSON-LD)
├── 6.3 (Wikidata sameAs)
└── 3.14 (FAQ schema)
1.4 (mv_place_demographics for non-place tiers)
└── unblocks Worker rendering parity for CBSA/DMA/SLD
```
---
## Drill-down methodology
The master table above is the strategic surface. Detailed per-item expansions
live in `drill-down/ws-{N}-{slug}.md`, one file per workstream, so this file
stays scannable while every item gets real depth.
### Per-item template
Every expansion uses this shape (full version in `drill-down/README.md`):
```markdown
### N.M — Title
**Status:** Not started | In progress | ✅ Shipped (date)
**Size:** XS/S/M/L/XL (re-verified against code)
**Depends on:** N.M, N.M **Unblocks:** N.M, N.M
**Goal** — one sentence.
**Approach / Design** — the technical approach.
**File-by-file plan**
- `path/to/file` — what to add/change
**Risks & mitigations**
- Risk → Mitigation
**Verification / done criteria**
- [ ] Concrete observable check
```
### Drilling-down protocol
1. Re-read the linked code under "File-by-file plan" before sizing the item.
2. Promote the verification checklist to the literal acceptance test.
3. Status transitions: 🟡 Not started → 🟢 In progress → ✅ Shipped (mirror
the shipped line into `BUILD_STATUS.md`).
4. Item numbers are stable — never renumber. Dropped items get
`~(dropped)~` plus a one-line explanation.
5. Cross-workstream deps link to the anchor in the other file.
### Drill-down index
Each row links to two layers of detail:
- **Drill-down** — the reference document. Approach, file-by-file plan,
risks, verification. Answers *what and why*.
- **Playbook** — the runbook. Pre-flight checks, numbered command-level
steps, literal acceptance tests, rollback. Answers *exactly what do I
type and how do I know it worked*.
| WS | Drill-down (what & why) | Playbook (how) | Items |
|---|---|---|---|
| 1 | [Data integrity & coverage](drill-down/ws-1-data.md) | [pb-1-data.md](playbook/pb-1-data.md) | 1.1–1.12 |
| 2 | [Deployment topology](drill-down/ws-2-deploy.md) | [pb-2-deploy.md](playbook/pb-2-deploy.md) | 2.1–2.12 |
| 3 | [SEO & AI-SEO](drill-down/ws-3-seo.md) | [pb-3-seo.md](playbook/pb-3-seo.md) | 3.1–3.18 |
| 4 | [Product surface & UX](drill-down/ws-4-product.md) | [pb-4-product.md](playbook/pb-4-product.md) | 4.1–4.16 |
| 5 | [Performance](drill-down/ws-5-perf.md) | [pb-5-perf.md](playbook/pb-5-perf.md) | 5.1–5.12 |
| 6 | [Editorial & content](drill-down/ws-6-editorial.md) | [pb-6-editorial.md](playbook/pb-6-editorial.md) | 6.1–6.11 |
| 7 | [Governance & open data](drill-down/ws-7-governance.md) | [pb-7-governance.md](playbook/pb-7-governance.md) | 7.1–7.9 |
| 8 | [Auth, canvas, UGC](drill-down/ws-8-canvas.md) | [pb-8-canvas.md](playbook/pb-8-canvas.md) | 8.1–8.12 |
| 9 | [Observability](drill-down/ws-9-observability.md) | [pb-9-observability.md](playbook/pb-9-observability.md) | 9.1–9.11 |
| 10 | [Brand & marketing](drill-down/ws-10-brand.md) | [pb-10-brand.md](playbook/pb-10-brand.md) | 10.1–10.10 |
(Status of the items themselves — Not started / In progress / Shipped — lives
in each workstream file, not here. Playbook format documented in
[playbook/README.md](playbook/README.md).)
---
## Working notes
- Item numbering is stable across revisions. Renumbering is forbidden;
if an item is dropped, mark it ~struck~ and add an explanation under it.
- New items get the next free decimal in their workstream
(e.g. add 3.19, not 3.14a).
- Cross-references use the bare number (e.g. "depends on 2.1").
- T-shirt sizes are first-pass; real estimates appear in the drill-down.
- "Done" items move to BUILD_STATUS.md when they ship; the line here gets
marked ✅ with the date.
See also
For the full methodology behind every page, see the methodology paper. For term definitions, see the glossary. For the one-page project summary, see about.