Kernel — the always-on rulebook
docs/rules/claude-startup-architecture.md
How the kernel · module · front-door layering works; the two gates; doc naming + dating convention (Rules #60/#64)
Contents
- TL;DR — three layers, two gates
- Compliance is external, not internal
- The module → front-door map
- Doc naming & dating convention
- The mechanical half — scripts/gates/check-startup-gates.mjs
- How to add a new module (the durable procedure)
- Directory contents
- Case study — the miss that produced the domain-entry gate (2026-07-28)
- Changelog
docs/rules/domain-taxonomy.md
Canonical taxonomy — docs folders ↔ rules/ modules ↔ backlog codes on one axis
curation
Domain modules (loaded when a session touches the domain):
Contents
- Two rules shown with the full five-layer stack (the pattern for every rule below)
- Illustrated — Rule #45 (claim-scan + number-trace gate)
- Illustrated — Rule #54 (every stat from the master report)
- All curation rules — compact stack
- Machinery this module adds (from proposal §6)
- Canonical rule text (migrated from CLAUDE.md)
- Rule #33 — Banned source-URL patterns are catalogued in apps/curation-agent/policies/sourcing.md; every write path must check.
- Rule #26 — Read the full drafting rulebook before any revision to a Commenting-status sourcedqueue row.
- Rule #27 — Surface the commenting queue at session start.
- Rule #28 — Every scoring change requires a tuning-log entry in apps/curation-agent/policies/scoring.md.
- Rule #30 — A vote is not "drafted" until polishedquestion and polisheddetail exist.
- Rule #31 — Mirror the canonical analog before building a new variant; never declare a missing capability as a design choice.
- Rule #32 — One vote per source document, unless the source explicitly contains multiple distinguishable, discrete votes.
- Rule #44 — Curation is one canonical pipeline, tier-uniform: score on raw, polish at the gate, gold-standard + provenance on the lean set only
mobile
Domain modules (loaded when a session touches the domain):
Contents
- Rules — compact five-layer stack
- Gates this module owns
- Canonical rule text (migrated from CLAUDE.md)
- Rule #0 — Never copy SVG path data into code
- Rule #2 — No new styles for existing elements
- Rule #2 — Only permitted sources during feed rebuild
- Rule #3 — All sizes go through r()
- Rule #5 — Feedback is GlobalFeedbackFlag only
- Rule #6 — QA punchlist after every build
- Rule #8 — One person, one vote
- Defense-in-depth layers
- Rules for contributors
- Rule #9 — PreviewProfile is sealed
- Architecture
web
Domain modules (loaded when a session touches the domain):
Contents
- Rules — compact five-layer stack
- Notes
- Canonical rule text (migrated from CLAUDE.md)
- Rule #23 — Public copy must be reviewed against docs/ops/brand/brand-voice.md before shipping
- Rule #39 — Public web pages are generated output. Edit the docs/web-comps/ template and regenerate; never hand-edit the rendered public/.html.
- Rule #40 — If correctness depends on something you can't see by reading code (rendered layout, runtime behavior, deployed state), get the means to OBSERVE it before proposing fixes. Never guess where things land on a page.
- Rule #41 — The generated site is guarded by golden snapshots. Run npm run snapshot:check and reconcile the diff before surfacing any push that touched the site.
- Rule #48 — Read docs/product/web/web-front-door.md before ANY public-website work.
- Canonical rule text (moved from CLAUDE.md 2026-09-10)
- Rule #51 — A branch with website-affecting commits (docs/web-comps/, public/, worker/, scripts/build-.mjs) that hasn't merged to main within 48h is an incident, not a backlog item. Surface it immediately.
admin
Domain modules (loaded when a session touches the domain):
Contents
- Rules — compact five-layer stack
- Notes
- Canonical rule text (migrated from CLAUDE.md)
- Rule #34 — Admin editorial mutations must await the network round-trip before clearing UI state. Optimistic-close patterns are prohibited.
- Rule #35 — Agent maintenance operations are forbidden during active editorial sessions.
- Rule #67 — In the profile queue, nothing actionable renders outside the panel it acts on.
- Rule #36 — Verify admin builds with tsc -b before any push that touches apps/admin/. Cloudflare Pages does, and it auto-deploys on push.
- Rule #43 — Backlog content changes originate in the .md files and propagate to the DB via the seed script. Never edit derived fields directly in backlogtasks.
- Admin env vars + architecture pointer (moved from CLAUDE.md 2026-09-10)
scheduling-v3
Domain modules (loaded when a session touches the domain):
release
Domain modules (loaded when a session touches the domain):
Contents
- Pre-archive checklist (iOS)
- Rules — compact five-layer stack
- Machinery this module wants (proposal §6)
- Canonical rule text (migrated from CLAUDE.md)
- Rule #50 — Every store push is recorded in the publication ledger before it ships. iOS and Android build numbers are tracked per-platform, never assumed equal.
- App / project reference (migrated from CLAUDE.md)
- Pre-archive sequence (iOS)
- Android build
- watchOS
assets
Domain modules (loaded when a session touches the domain):
environments
Domain modules (loaded when a session touches the domain):
Contents
- The topology in one screen (verified 2026-07-23)
- The load-bearing discipline (holds regardless of the prod label)
- The prod-label decision — DECIDED 2026-08-17 (GATE A): promotion by rotation
- The go-live campaign (the current work living in this module)
- Live figures — query, never quote
- The app's v2/v3 read path — and why accounts needs v3
- Where to test
- Git and environments — DECIDED 2026-08-22
- Decision gates
- Landmines — do not step on these at cutover
- Rules in play (owned elsewhere; this module is the topology home)
- Supabase RLS — test policies before enabling (moved from CLAUDE.md 2026-09-10)
Curation — sourcing → scoring → drafting → publish
docs/product/curation/curation-front-door.md
mandatory first read before ANY curation work (Rule #53). Module: rules/curation.md.
Contents
- 1. Which doc for what — the routing table
- 2. The fact that explains most failures: TWO execution environments
- 3. The full daily chain — where / depends-on / silent-failure / verify
- 4. Known failure modes — check these before theorizing a new cause
- 5. What "working" means — measure, don't assert (pairs with Rule #47)
- 5.0 Object vocabulary — the names are the admin's, not yours
- 5.1 Canonical metric definitions — look up the predicate, never invent it (Rule #62)
- 6. The scheduled tasks — what each ACTUALLY does
- 7. Before you touch a scheduled task — the checklist
curation-pipeline-canonical.md
The canonical pipeline, end to end
Contents
- The canonical order — gov path (Federal, State, County, Municipal, School, Special District)
- The canonical order — media path (local press-originated)
- Gates that apply to EVERY tier (no exemptions)
- Per-tier specifics
- Sourced-queue sizing — reserve targets per tier
- Supply-aware tier-mix + quality floor — the 25/25/50 is a guide, not a rigid ratio
- The anti-fumble list (what must NEVER happen, any tier)
- Build status (the work that makes this real)
- Update 2026-07-20 — worthiness re-architecture (all tiers)
- Update 2026-07-21 — LOCAL: merit-gated material (merit moves AHEAD of enrichment)
- Update 2026-07-21 (cont.) — LOCAL: merit-driven materials chase + surgical in-place enrichment
- Update 2026-07-21 (cont. 2) — eBOARD content route + chase wired into the daily run
- Daily-run source coverage (2026-07-21) — the honest map
- Update 2026-07-21 (cont. 3) — Granicus content route + sourced-row guard
pipeline-process-map.md
Stage-by-stage process map
Contents
- The flow at a glance — what happens to a vote, in plain terms
- Tier coverage — LOCAL, STATE, FEDERAL
- Stage 0 — HARVEST
- Stage 1 — SPLIT / CRACK (Phase 1.4)
- Stage 2 — ENRICH / REFETCH (Phase 1.5 / 1.5a / 1.5b)
- Stage 3 — SCORE (Phase 2–5)
- Stage 4 — ADMIT TO POOL (Phase 5b) — the pivotal stage
- Stage 5 — DRAFT + GATE (9pm, sandbox)
- Stage 6 — EDITORIAL REVIEW
- Stage 7 — PROMOTE → V3
- The disposition state machine (votdlocaldisposition)
- Canonical counts — what the master report emits (nothing else gets quoted)
- Terminology crosswalk — one concept, one canonical term
- The one real collision — held — RESOLVED 2026-07-14
daily-run.md
The daily run + run cost & spend discipline (Rule #63)
Contents
- The daily ritual — one command + three drafting sessions (four runs)
- The steps
- 1 · Harvest → score → admit (all tiers)
- 2 · Supply + health report
- 3 · Drafting (three manual runs — one Claude/Cowork session each)
- 4 · Duplicate control — scan + gate (two Claude/Cowork sessions — after drafting, before the overnight promote)
- 5 · Readout (one manual run — after the digest prints)
- Why manual + in-repo
- Run cost & spend discipline
curation-daily-loop-spec.md
Daily loop specification
Contents
- This is not a new system
- The daily loop
- What counts (the definition that makes the supply scorecard honest)
- The six guards
- G1 — Scorecard only post-score; never report a pre-score number
- G2 — Never count unopened meetings
- G3 — Enrich before culling; never cull a row for being "thin" until enrichment has tried and failed
- G4 — Fix the body-cap truncation
- G5 — Title-matching flags, it doesn't exclude (except unambiguous non-votes) — and it runs after enrich
- G6 — A persistent rejection / decided ledger, keyed on decision identity, checked at intake
- The daily supply scorecard (the heartbeat output)
- Automation & triggering
- Build status at a glance
harvest-source-registry.md
Per-source write-target lookup + freshness check
liveness-model.md
Liveness / decided-signal model — what "live" means
Contents
- The problem this fixes
- The shape — broad harvest, two gates, a tracker between them
- 1. Broad harvest → standing pool
- 2. Harvest gate — skip only known-decided
- 3. Liveness tracker — a daily loop
- 4. Publish gate — the decisive check, run latest-possible
- Locked defaults (2026-07-17)
- What exists vs. what's new
- Coverage reality — READ BEFORE TRUSTING ANY LIVENESS FIELD (2026-07-28)
- Build stages
- Cancelled meetings (2026-07-17)
- Cadence (2026-07-17)
- Related
dedup-system.md
Semantic dedup: daily scan + promote-time gate
Contents
- Amendment — 2026-09-17: the judge runs itself, and it rejects
- Why an LLM, not word-matching (the finding that shapes everything)
- Component 1 — THE SCAN (the judge; dedup-scan edge function, cron 09:30 UTC)
- Component 2 — THE GATE (last hard barrier at admission to the scheduler)
- Backstops (deterministic; they enforce a verdict, they do not judge)
- Schema & views
- Migrations
curation-promoter-v2-unified.md
The unified daily promoter (per-geo capacity, cascade, tier calibration)
Contents
- What the promoter does
- Architecture — two primitive modules + the runner
- apps/curation-agent/scripts/lib/calendar-slotting.mjs
- apps/curation-agent/scripts/lib/tier-calibration.mjs
- apps/curation-agent/scripts/promote-v2-unified.mjs
- Per-geo capacity model — the production rule
- Fast-Track — end-to-end flow
- Tier-mix calibration — 25/25/50
- What was deprecated + why
- Schema dependencies
- Failure modes the unification closes — historical context
- Future work
- Cross-references
scheduler-and-jurisdiction-model.md
Scheduling + jurisdiction model
Contents
- 1. The product concept — a synchronized daily cadence
- 2. Two models exist in the docs — and they diverge
- Model A — the day-type calendar (the synchronized-cadence vision)
- Model B — the per-geo continuous promoter (what's actually built and running)
- Why they diverge (and the proposed reconciliation)
- 3. The data model (verified against live schema, 2026-05-31)
- 4. Supply-side targets (sourcing & placement) — distinct from display cadence
- 5. Address → jurisdiction-set resolution (the missing pre-launch primitive)
- 6. Built vs designed vs missing
- 7. Open decisions
- 8. Terminology (canonical going forward)
- 9. Source docs & status
- 10. Relationship to the URL work
- 11. Resolved model — one synchronized vote a day, with universal cover (2026-05-31)
provenance-and-verification.md
Provenance + verification discipline
Contents
- 1. The bundle (what the drafter is given)
- 2. The contract (drafter obligations)
- Claim ledger format
- 3. The verifier gate (the drafter does not control it)
- Check 1 — Deterministic number trace (no model judgment)
- Check 2 — Adversarial claim check (separate model/agent)
- Check 3 — Summation gate
- 4. Integration (pipeline position)
- 5. Limits (stated honestly, because pretending otherwise is itself a fabrication)
- 6. Build order
votes-drafting-no-fabrication-enforcement-2026-06-15.md
No-fabrication enforcement
Contents
- 1. Background — what triggered this
- 2. Prior work (including the session shared into this chat)
- 2a. Where the shared session's account diverged from verified reality
- 3. Verification performed this session
- 4. Hardening implemented this session
- Migration inventory
- Six recommendations — status
- Post-hardening re-test (live)
- Verifier loop wired
- Docs updated
- 5. Current state of the system
- 6. Honest residuals / limits (not closed)
- 7. Recommended next steps
- Update 2026-07-22 — the enforcement gap: fabrication upstream of the gate (merit)
federal
Drafting runbooks
Contents
- Step 0 — Load the rulebook (non-negotiable, before any drafting)
- Step 0 — Recover stranded ledgers FIRST (before drafting anything new)
- Step 1 — Pick the batch (next un-drafted, in-pool, live)
- Step 2 — Per bill: the gated drafting loop
- Step 3 — Insert via executesql (NEVER a Node script)
- Step 4 — Present + record
- The kickoff task (create this in Cowork to finish the cutover)
- The harvester cutover (do together, or you double-run)
- The anti-fumble list (mirror of curation-pipeline-canonical.md)
- Federal specifics (so they don't trip you)
- Dedup master — curationdecisionledger (cross-tier, Path B 2026-07-17)
- The three-bucket model
- ⚠️ Required before trusting the fed/state legs (Mac, has network)
- Source label convention (added 2026-07-30)
state
Drafting runbooks
Contents
- Step 0 — Load the rulebook (non-negotiable, before any drafting)
- Step 0 — Recover stranded ledgers FIRST (before drafting anything new)
- Step 1 — Pick the batch (next un-drafted, in-pool, live)
- Step 2 — Per bill: the gated drafting loop
- Step 3 — Insert via executesql (NEVER a Node script)
- Step 4 — Present + record
- The anti-fumble list (must NEVER happen, mirror of curation-pipeline-canonical.md)
- Cohort gotchas already fixed (so they don't recur)
local
Drafting runbooks
Contents
- ⛔ MANDATORY START-UP — read before writing one word. Your draft is DISCARDED unless you do this.
- Hold management (so skips don't vanish or get re-ground every run)
- Update 2026-06-20 — THE compliant path is insert-batch-local.mjs. workshoplocal.polishedquestion is a dead-end.
- Update 2026-06-19 — supply/drafting split + autonomous drafting mode
- Current state — handoff as of 2026-06-18
- Step 0 — Load the rulebook (before any drafting)
- Step 1 — Pick the batch (ONE pool — governance + media)
- Step 2 — Per row: the gated drafting loop
- Media hold-reason contract — do NOT apply governance hold codes to originpillar='media' (added 2026-07-18)
- Step 3 — Insert + present
- Batch cadence — low-touch ownership mode (added 2026-06-18)
- Local-specific rules (vs state) — the cheat sheet
- The anti-fumble list (must NEVER happen)
- Update 2026-07-22 — issue-framing breadth + media jurisdiction narrowing (founder direction)
triage-system.md
Triage canonical — the pool loop, pre-pool rescue, co-pilot, and conversion to media / county-theme votes
Contents
- 0. What Triage is
- 1. Governing principles (settled — founder calls 2026-08-11)
- 2. Pool Triage — the built loop
- 2.1 Input seam — where flagged comes from
- 2.2 Output seam — where sourced goes
- 2.3 Dry-review loop
- 2.4 Surfaces
- 3. The co-pilot — automated legwork, supervised verdict
- 4. Pre-Pool Triage — the second input seam
- 4.1 Problem
- 4.2 Root cause (verified in code, 2026-08-09)
- 4.3 Design — three changes, in order
- 4.4 Outcomes, and the linkanyok caveat — the make-or-break
- 4.5 Resolved decisions (closed 2026-08-09 against the code + DB)
pipeline-action-inventory.md
The 28 actions from intake to sourcedqueue — derived companion to pipeline-process-map.md
Contents
- Intake
- Split / crack — Phase 1.4
- Merit Pass 1 — Phase 1.45 — assess-vote-merit.mjs (Sonnet)
- Enrich / material chase — Phase 1.5 family (LOCAL material effort is merit-gated, 2026-07-21 — spent on worthy rows; each stage's exact gate is named per stage)
- Validate — Phase 1.6 (authored cohorts only)
- Merit Pass 2 — Phase 1.7 — assess-vote-merit.mjs
- Profile & classify — Phase 2 / 2.5
- Signals — Phase 3 / 4 (scoring inputs; not a gate for local)
- Liveness — Phase 4.6 family (decided-checks)
- Score / admit — Phase 5 family
- Post-process retire / routing — daily.sh step 4
- Drafting → sourcedqueue — daily.sh step 5 (manual agent; legacy Phase 6/7 off under V3)
curation-serp-methodology.md
Scoring / supply
Contents
- 1. What we're measuring
- 2. Pipeline architecture
- 3. The probe mechanism
- 4. The 0-50 scale
- Why 0-50 specifically
- Treat scores as ordinal, not interval
- 5. The tool: websearch20250305
- What 20250305 is
- What 20250305 is NOT
- What pinning the version protects against
- What we don't see
- 6. Geo-targeting (currently federal-only; state/municipal pending)
- Current state — federal probe
- Roadmap — state and municipal probes
curation-press-methodology.md
Scoring / supply
Contents
- Why press is a separate signal
- Where pressscore sits in the pipeline
- Bill-specific query construction (per tier)
- FEDERAL
- STATE (CA)
- LOCAL (county / municipal / specialdistrict / school)
- Locale bias
- Score formula (0-30)
- Recency parsing
- Why these weights
- What a pressscore actually means
- Cost model
- Operational notes
- Skip-already-probed default
local-category-priors-spec.md
Scoring / supply
merit-supply-unlock-spec.md
Scoring / supply
Contents
- 1. The problem, in one line
- 2. The funnel, measured (2026-08-03, point-in-time — counts drift live as the pipeline runs)
- 3. Root cause — the two cliffs are ONE defect
- 4. The five fixes
- Fix 1 — PASS 1 defers on a thin body instead of killing (breaks the deadlock)
- Fix 2 — Crackers feed on needsmaterials, not only goodvote='true'
- Fix 3 — PASS 2 re-judges on "has materials now," not "grew ≥400 since PASS 1"
- Fix 4 — Merit row-selection must not skip qualifying rows
- Fix 5 — Make the reprocess actually run, and surface it when it doesn't
- 5. Expected unlock
- 6. Out of scope (deliberately)
- 7. Sign-off
- 8. Implementation status — 2026-08-03 (BUILT — NOT VERIFIED RUNNING)
local-supply-durable-fix-spec.md
Scoring / supply
Contents
- 1. Problem
- 2. Root causes (all verified this session — receipts in the session handoff)
- 3. Fix, by source capability (the key distinction)
- 4. Retirement / triage policy (founder-set 2026-07-30)
- 5. The changes
- A. Chase gate fix (Mac — chase-merit-materials.mjs)
- B. Standing retirement/triage function (DB — new votdretirestalelocal())
- C. Split-child age-out coherence (DB — in B or a trigger)
- D. CivicClerk / agenda-only policy (Mac — merit/materials logic)
- E. Report fix (Mac — stuck-supply-report.mjs)
- F. One-time backlog cleanup (DB)
- 6. Sequencing
- 7. Coordination + verification
- 8. Out of scope / open
thin-body-refetch-system.md
Extraction / enrichment
thin-item-enrichment-and-media-pivot-spec.md
Extraction / enrichment
local-packet-sources.md
Extraction / enrichment
Contents
- TL;DR — the reliable-harvest design (proven end-to-end 2026-07-10)
- The map — every local source
- Per-source detail (patterns, examples, screenshots, commentary)
- Citrus Heights — CivicPlus AgendaCenter ✅ (wired)
- Metro Fire — metrofire.ca.gov ✅
- San Juan Water — Granicus ✅¹
- Rancho Cordova — CivicClerk ✅
- SMUD — Board Meetings ✅ (posts ahead)
- SacRT — Board Combined File ✅ (FIXED 2026-07-21)²
- SCOE — Highbond ✅ (posts ahead)
- SCUSD — Finalsite ❌-ahead³
- Elk Grove — Granicus ✅ (BUILT 2026-07-21 — MetaViewer staff-report PDFs)⁴
- eBoard schools ✅ (BUILT 2026-07-21 — PrintAgenda + Attachment.aspx)⁵
- SacCounty — Hyland OnBase ✅ (the per-item BDL route — cracked 2026-07-17)
media-origination-system.md
Media origination
Contents
- The objective function
- Three orthogonal axes (the mistake was conflating them)
- The control loop
- Components (what's built)
- Data flow
- Ranking (which leads win an admission slot)
- What's left (next session)
- Known seams
- Update 2026-07-20 — media flows through the local merit gate
- Update 2026-08-02 — capture-fault flags insufficientsourcing (2.5)
- Update 2026-08-10 — per-run source firing log restored + .gov origination gate
local-media-vote-generator.md
Media origination
Contents
- The spine
- Stage 0 — the source pool
- Stage 1 — Triage (recall-preserving)
- Stage 2 — Deep read / the bar
- Draft
- Enrich — the gold-standard step (Claude-cowork pass, NOT automated)
- Worked example — Tower Bridge streetcar (enriched 2026-06-13)
- Operational cadence
- File map
- Open / next (the deliberate bar pass — do as one pass, not reactive patches)
external-source-research.md
Media origination
curation-punchlist.md
Ops / health
Contents
- Verified remaining — 2026-08-01 (supersedes stale rows in the table below)
- Where we stand — 2026-07-29
- Root causes
- Decisions — RESOLVED
- Wave 0 — Instruments (0.1, 0.2 DONE 2026-07-28)
- Wave 1 — Stop destroying live supply
- Wave 2 — Stop the waste (2.1 DONE)
- Wave 3 — Cadence that survives manual operation
- Wave 4 — Coverage holes
- Wave 5 — Documentation (lands with the change, never after — Rule #53)
- Execution order
- Handed to the parallel session (2026-07-28)
- New this session, not yet in a wave
- Changelog
curation-health-scout-runbook.md
Ops / health
curation-reporting-wire.md
Ops / health
Contents
- 0. Pick this up in 60 seconds
- 1. Files & where things live
- 2. The model
- Role vocabulary (every 4-part row uses it and FOOTS: in = drop + hold + pass)
- 2A. Design rationale — why everything is where it is
- 3. Row-by-row semantics & data source
- Enrichment ladder (the key model)
- 4. HTML architecture — how to WORK ON it
- 4.1 Data arrays (edit these to change numbers)
- 4.2 Render engine (edit these to change layout/behaviour)
- 4.3 Database ↔ UI bridge map
- 5. Regeneration — refresh numbers from Stage
- 6. The canonical 19 sources & the four queries
- 7. Build / iterate / verify workflow
curation-county-activation.md
Ops / health
Contents
- What's reusable vs. per-county
- Reuses as-is
- Per-county work
- Vendor platform quick-reference
- Lessons learned (Sacramento County build, 2026-05)
- Things that worked
- Things that didn't work the first time
- Activation playbook for next county
- Phase 1 — Source discovery (~3-4 hr)
- Phase 2 — Configure / build harvesters (~varies)
- Phase 3 — Press registry
- Phase 4 — Jurisdictional routing
- Phase 5 — Run + verify
- Realistic time estimate
topic-content-fit.md
Other
Contents
- Discovery context
- Heuristic rules (jurisdiction-based defaults)
- Subject-vs-mechanism rule
- Police-vs-surveillance test (CRIMINALJUSTICESAFETY vs. CIVILLIBERTIES)
- Energy-vs-taxes test (ENERGY vs. TAXESSPENDING)
- Transportation-vs-infrastructure test
- Housing-vs-economic-development test
- Operational rules for the curation pipeline
- Audit script
- Maintenance
v3-prelaunch-cutover-plan.md
Other
Contents
- The strategy in one paragraph
- Architecture / the moving parts
- Environment model — dev/staging → production (target topology)
- Phases
- Phase 0 — Freeze V2 / tie off the app
- Phase 1 — V3 infrastructure + prerequisites
- Phase 2 — V3 local supply
- Phase 3 — State/Fed rewrite + harvest
- Phase 4 — Schedule + publish to website (V3)
- Phase 5 — Validate + flip
- Per-tier rewrite status
- Dependencies / ordering
- Constraints / rules in play
- Optional accelerator (founder's call)
App / Mobile
app-feed-model.md
Daily-feed structure + module design
Contents
- Daily Feed — 3-Tier Module Structure (agreed March 2026)
- Module Header / Evidence / CTA Pattern (design principle, agreed March 2026)
- Modules suited to this pattern
- Modules that stay neutral
- Notes for build
- FM.T1.16 — Top by Topic (TopicTopVoteCard)
- How it differs from TopVoteCard
- Visual anatomy
- Footer state machine
- Selection rules — pickTopicCards()
- Topic categories
- Adding a new topic category
- Connecting to live data
- Platform Insight Module — Feed Design Notes
terminology.md
Naming / copy conventions + app-side type & enum reference
Contents
- Authentication vs. Verification
- Account vs. Profile vs. Registration
- Set up vs. Complete vs. Finish
- Votes — counting language
- Residency vs. Address vs. Voter registration
- Verification badge labels (UI only)
- Prompt copy — canonical strings
- Screen Names
- Nav Tabs
- Component & Panel Names
- Feed Card Types
- Feed Slot Types (code)
- Feed Engine Module IDs
- Data Model — TypeScript Types
tally-display-states-spec.md
How a vote's tally renders by participation level
tally-reporting-ladder-system.md
The tally reporting ladder as built — api.voteresults, every surface, the 10-second change window, what is parked, what was verified
Contents
- 1. The rule
- 2. The server — api.voteresults
- 3. Every surface, and where it lives
- App (apps/mobile)
- Apple Watch (apps/mobile/ios/votd Watch)
- Website and Worker
- 4. The 10-second change window
- 5. Rank — parked
- 6. The Feed — parked, and finished for when it returns
- 7. What was verified, and what was not
- 8. Open items
- 9. Changing it
- 10. Commits (2026-09-24)
tally-reporting-ladder.md
The ladder's rule, wording and sources (under 30 / 30–99 / 100+)
source-attachments.md
How source / research material attaches & displays
Contents
- Overview
- Attachment Tiers
- Tier 1 — Simple Link
- Tier 2 — Link Preview
- Tier 3 — Uploaded File
- Tier 4 — Multiple Sources (Carousel)
- Data Model
- Propose a Vote Integration
- Display Contexts
- Community Research — Add Research (AR1–AR8)
- Entry points
- Access control — verified voters only
- Submission flow (AR2–AR7)
- Post-submit — pending approval (AR8)
watch-experience.md
watchOS design intentions, architecture & learnings
Contents
- 1. Architecture Overview
- Navigation Model
- Why the Custom Pager Was Replaced
- Why No TabView
- Key Files
- Phone-Auth vs Verified Voters
- The tally page under the reporting ladder (2026-09-24)
- 2. Brand & Visual Language
- Colors (NEVER invent new ones)
- OLED Considerations
- Glass Material Design (watchOS 10+)
- Font Sizing
- 3. Critical Layout Learnings (FAILURES & ROOT CAUSES)
- LESSON 1: The Root Cause — Coordinate System Mismatch Between Screens
plain-language-glossary.md
Plain-language glossary
Contents
- Brand lexicon rules (global)
- Group A — always swap on commercial copy (everyday word)
- Group B — technical/statistical: keep on stakeholder pages, swap OR explain plainly on commercial
- Group C — fine, keep (on-brand or unavoidable)
- Deliberately kept (do NOT simplify away)
- Avoiding "decision" / "vote" fatigue
- Running collection — hard words found in the answer-by-answer pass
- Framing note (not just words)
- Words that are FINE (do not force-swap)
- P12–P24 pass (hard words + accuracy)
- Other-pages pass (2026-07-08) — stakeholder-calibrated (grade 8–10; swap only where equally strong)
Web — the public site
docs/product/web/web-front-door.md
mandatory first read before ANY public-website work (Rule #48). Module: rules/web.md.
Contents
- TL;DR — the publish loop
- Architecture / data flow
- Source of truth (Rule #39 / #25)
- Design-system consolidation (2026-07) — where we were, what changed, how to manage
- Build commands (package.json)
- Release gate (homepage + vote pages are edge-rendered)
- SOURCETABLE — which calendar the site reads
- Env vars for the build
- ⚠️ The silent-stale-deploy trap (this has bitten twice — 2026-06-26/27)
- Deploy ⚠️ (the step that bites)
- Verify on .html, not on the pretty URL (added 2026-09-02)
- Pre-push gates
- Pre-launch / "locked"
- Key files
vote-url-architecture.md
Canonical vote-URL scheme
Contents
- Why
- The four decisions (locked) + the international revision
- URL scheme
- Year management
- Jurisdiction collisions and the registry
- Use the EXISTING jurisdictions table — do not create a new one
- Address mapping (shared graph — design now, build later)
- Downstream — the day-type calendar (existing concept) and what this work feeds it
- Folders as aggregate pages
- Data-model changes
- Code touch-points
- Canonical-page ownership — resolved (2026-05-31): static owns it
- Phasing
- Open items to confirm before code
web-rollout-plan.md
Web app rollout plan
Contents
- TL;DR
- Next steps
- Strategic context
- Decision history
- What v1 ships
- v1 page inventory
- v1 auth mechanism
- v1 vote action treatment
- v1 propose-a-vote treatment
- v1 schema.org / SEO surface
- What v1 does NOT ship (v2 scope)
- Phase 0 — server hardening
- Current state assessment (motivation for Phase 0)
- Schema migrations
cloudflare-access-recipe.md
Cloudflare Access setup runbook
Admin — the editorial app
docs/product/admin/admin-front-door.md
. Module: rules/admin.md.
admin-architecture.md
Deep reference — canonical patterns + new-page checklist
Contents
- Stack
- File map
- Read layer — useQuery everywhere
- Pattern
- Stale times in use (as of 2026-05-16)
- What this means for new admin pages
- Write layer — optimistic mutations
- Pattern
- Variants in use
- EditorialQueue's approvedraft RPC (Tier C8)
- Realtime — supabase.channel('postgreschanges')
- Tables with realtime enabled (supabaserealtime publication — re-verified on Stage 2026-08-28, identical set)
- Pattern
- What this means for new admin pages
admin-page-state-reference.md
Per-page state reference
Infra — the technical foundation
data-model.md
canonical DB map (Rule #49)
Contents
- Gotchas — where things ACTUALLY live (read this first)
- Functional groups (curated)
- Core tables — key columns (hand-maintained)
- sourcedqueue — editorial lifecycle & triggers (hand-maintained, 2026-07-29)
- Enums (live)
- Key foreign keys
- Status flows
- Integrity & RLS posture
- Project model
- Table inventory (exact row counts — refreshed by dump-data-model.mjs)
votd-selection.md
VOTD cadence + selection (Rule #55)
Contents
- TL;DR — the one-paragraph answer
- 1. The live daily chain (verified 2026-07-15)
- 2. The scheduler — votdreschedulev3 (LIVE)
- 3. The consumer — "newest-open vote passing your jurisdiction"
- 4. Supply / shortfall signals — votdschedulerlog (re-verified 2026-08-17)
- 5. DEAD — do not use (verified abandoned 2026-07-15)
- 6. Open work (as of 2026-07-15)
- 7. Reporting — the cadence-runway axis (view BUILT 2026-07-15)
address-jurisdiction-resolution.md
Scheduling
Contents
- Session handoff — read this first, update before you stop
- 0. Summary
- 1. Why this exists
- 2. Hard constraints
- 3. Decisions
- Decision #1 — Build, not buy. (LOCKED 2026-06-08)
- Decision #2 — Hybrid by layer: GIS-as-generator + Registrar table, baked to a served table. (LOCKED 2026-06-08 — GIS-primary for Sacramento; see §7)
- 4. Verified current state (as of 2026-06-08 investigation)
- 5. GIS vs tables — the implementation substrate
- 6. Architecture
- 7. Sourcing the Sacramento data pack (public GIS)
- 8. Definition of done — Sacramento launch
- 9. Open decisions / forks (not yet settled)
- 10. Relationships
residency-confirmation-system.md
Accounts / verification
Contents
- 1. Two rungs, not three
- 2. Gates are composed, not listed
- 3. The tally CTA
- 4. The confirm machine
- 5. What proves an approval
- 6. Document review
- 6b. verifying is one status with two messages
- 6c. Capture method — uniform across document types
- 7. Channels
- 8. Blockers, in order
- 9. When verification does not resolve — OPEN DESIGN, 2026-08-27
- 9.1 The problem verifying currently hides
- 9.2 The proposed states
- 9.3 Two producers, not one
verification-funnel-to-99.md
Accounts / verification
Contents
- The model — no single check hits 99%; confidence is layered
- Two rings — "resident of this community" vs "resident of this address"
- The master table — the verification funnel (25,000 → 0)
- What the table says about cost
- The strategic stop point — pre-funding, stop cheap and grow (founder call)
- Why "in-house and forgeable" is still defensible
- Losses are drop-off, not rejection
- The not-counted group, honestly
- Why the two rings matter — the counting decision
- The rungs, explained — what each proves, and what it doesn't
- Common objections — and how we answer them
- The hardest case — self-duplication via a real alternate identity (a known residual)
- How we talk to people we can't verify yet — the tone
- The 99% goal — a hard requirement, measured like uptime
reverse-match-vendor-comparison.md
Accounts / verification
Contents
- DECISION (2026-07-01) — Trestle Real Contact ($0.03), single call, binary full-match rule
- Live test results (2026-07-01)
- Coverage ceiling — the number that drives the whole design
- Design consequence
- Next cheap lever (in progress) — IP geolocation
- What we need (requirements)
- The options
- Recommendation
- Due-diligence log — Trestle Real Contact
- API contract — confirmed 2026-07-03 (integration-ready)
- Confirm-before-commit checklist (the signup + due-diligence steps)
privacy-data-flow-brief.md
Accounts / verification
attestation-and-consent-copy.md
Accounts / verification
Contents
- 0. AS SHIPPED — declarationversion v4-2026-09 (2026-09-24; v3 2026-09-23)
- 1. Eligibility attestation (citizen · 18+ · resident)
- 2. Verification consent (sending data to the match vendor)
- 3. GPS opt-in (escalation only — shown only on a no-match)
- Flow integration (how it threads into signup)
- Brand-voice notes (Rule #23)
- Caveats
twilio-a2p-copy.md
Accounts / verification
Contents
- 1. App opt-in microcopy
- 1a. Signup phone screen (signup.tsx, under the phone field / above Continue)
- 1b. Reminder opt-in (confirm-address.tsx)
- 2. Campaign form content (paste into the A2P campaign)
- 3. Supabase SMS template (set this so the OTP matches sample #1)
- 4. ⚠️ Privacy-policy requirement (commonly-missed rejection cause)
- 5. Checklist to submit
- 5a. Use-case eligibility — how much of this is actually a risk
- 5b. ⚠️ ROOT CAUSE OF THE SHAFT TAGS: the scanner reads votd.io, and votd.io publishes questions about restricted topics
- Why this is structural, not a copy defect
- The distinction that has to be argued to a human
- Wider implication, worth knowing before it bites again
- 5b-bis. ⚠️ THE SITE READS STAGE, NOT PROTO. Read this before touching site data.
- 5c. The parked questions (2026-09-03) — REVERSIBLE, and they must come back
voter-file-access-paths-2026-07-03.md
Accounts / verification
Contents
- The reframe that changes everything: VOTD needs a number, not the file
- The paths, ranked for VOTD
- 1. Scholarly lane via a university research partnership — the strongest alternative (recommend pursuing in parallel now)
- 2. Commercial aggregate match-service — the fast interim (with real caveats)
- 3. §19003(b) case-by-case bespoke purpose — the backstop application
- 4. Nonpartisan civic-data intermediaries — a model, and a maybe
- 5. The remaining enumerated lanes — why they're out (documented for completeness)
- The "can't-fail" portfolio
- Sources
phase-1-build-prep-2026-07-03.md
Accounts / verification
Contents
- Current state — introspected 2026-07-03 (the C1 gap, confirmed)
- 1.1 — Real OTP + server-authorized vote + one-person-one-vote
- Additive / dormant — verification result columns (safe to apply early)
- 1.3 — Trestle Real Contact integration (contract confirmed)
- Migration-file discipline (Rule #15)
- Open decisions for the branch
identity-verification.md
Trust / vote-integrity
Contents
- Purpose & scope
- Threat model
- Current state (closed testing, May 2026)
- Implemented mobile verification state + access gates
- The baseline 3-step verification (planned)
- Step 1 — Phone OTP
- Step 2 — Residency verification (commercial) — supersedes the former "voter roll cross-reference" (2026-07-01)
- Step 3 — Phone-identity match
- What the 3-step combination DOES catch
- What the 3-step combination does NOT catch
- Excluded populations (the cost of automated verification)
- Cost analysis — the honest version
- Per-signup target: $0.10 average for the first 100K signups
- Annual fixed costs (separate budget line)
signals.md
(+ statutory / form source PDFs)
Contents
- What is a signal?
- Editorial Signals
- On proposals (user-submitted)
- On scraped agenda items (editorial queue)
- Editor actions on editorial signals
- Anomaly Signals
- Vote-level anomalies
- User-level anomalies
- How anomaly signals are generated
- User Trust Score
- Factors that increase trust
- Factors that decrease trust
- Score bands
- Signal flow — end to end
security-audit-2026-06-23.md
(+ statutory / form source PDFs)
Contents
- Executive summary
- CRITICAL
- C1 — Vote integrity is unenforced; tallies are spoofable (one-person-one-vote bypass)
- C2 — Stored XSS on every vote page via JSON-LD <script> breakout
- HIGH
- H1 — Admin service-role endpoints have no in-code authentication
- H2 — No SSRF guard on any server-side fetch sink
- H3 — Unpublished editorial content is world-readable (single-layer confidentiality)
- MEDIUM
- M1 — backlogtasks writable by any authenticated session
- M2 — Sensitive PII stored unencrypted on-device
- M3 — 4 SECURITY DEFINER functions without a pinned searchpath
- LOW / INFORMATIONAL
- Verified clean (no action)
voter-eligibility-and-data.md
(+ statutory / form source PDFs)
Contents
- 0. TL;DR — decision at a glance
- 0.5 Build roadmap — the step map (backlog: PRD-INF-04)
- 1. The core distinction: eligibility vs registration
- 2. Two separate needs — do not conflate them
- Need A — Verify / authenticate a user at signup (eligibility + residency)
- Need B — Content & research operations
- 2.3 VOTD's defined intended use — v1 (decided 2026-07-01)
- 2.4 Empirical check — has voter-data-for-verification ever been approved in California? (researched 2026-07-01)
- 2.5 Need A — recommended verification architecture (designed 2026-07-01)
- 2.6 Product model — participation tiers (a vote saves to the user's account immediately; it is NOT counted in the published tally until the user is verified)
- 2.7 End-to-end architecture + phased build (the "middle")
- 2.8 Backend aggregate matching — the compute-and-discard permissibility line (clarified 2026-07-03)
- 3. The legal framework — CA voter-data access regime
- 3.1 What's in the file (§19001 definition of "voter registration information")
ca-voter-file-access-legal-sources-2026-07-01.md
(+ statutory / form source PDFs)
ca-elections-code-voter-data.md
(+ statutory / form source PDFs)
infrastructure.md
Deploy / hosting / cron
Contents
- Domains
- Cloudflare
- Email on votd.io — Google Workspace (cut over 2026-09-09)
- Supabase Projects
- iOS App
- App Name & Branding
- Share Link Architecture (planned)
- Deployed Sites
- Cloudflare Pages — required environment variables
- Cloudflare Access (Zero Trust)
- Git & CI/CD
- Claude seamless push (how to enable)
- Key Infrastructure Decisions
- Invite Link System (TestFlight phase — temporary)
environments-canonical-index.md
Deploy / hosting / cron
scheduled-tasks.md
Deploy / hosting / cron
Contents
- Where automation runs (read this first)
- The Cowork sandbox constraint (verified 2026-07-05)
- The pipeline stages (numbered by data flow — NOT the order they run)
- Cowork scheduled tasks
- Supabase — server-side (pgcron + Edge Functions + DB gates)
- Enforcement gates (event-driven DB triggers — not scheduled)
- GitHub Actions
- Open items / follow-ups (2026-07-05)
- Cadence — how the harvest dispatcher actually spreads (2026-07-28)
- Change log
email-system.md
Deploy / hosting / cron
build-issues.md
Deploy / hosting / cron
Contents
- Android Dev Environment Recipe — 2026-04-22 (Galaxy A53 5G UW, Android 15)
- Required env vars (in ~/.bashprofile for bash, ~/.zshrc for zsh)
- Symptom: Gradle fails with "Dependency requires at least JVM runtime version 11. This build uses a Java 8 JVM."
- Node version: 22 LTS required, NOT 24
- typedRoutes experiment must be OFF for Android dev server
- Device authorization (one-time per device)
- Build command
- Expected harmless warnings on Android
- Known harmless side-effects to clean up before commit
- Bug #5 — WatchConnectivity crashes Expo Go (KNOWN LIMITATION)
- What happens
- Workaround
- Testing rules
- Bug #4 — Missing/aliased theme token imports → SIGABRT on New Architecture (RESOLVED build 74)
crash-log-guide.md
Deploy / hosting / cron
publishing-and-release-workflow.md
iOS · Play · web (module: )
release
iOS · Play · web (module: )
Contents
- Pre-archive checklist (iOS)
- Rules — compact five-layer stack
- Machinery this module wants (proposal §6)
- Canonical rule text (migrated from CLAUDE.md)
- Rule #50 — Every store push is recorded in the publication ledger before it ships. iOS and Android build numbers are tracked per-platform, never assumed equal.
- App / project reference (migrated from CLAUDE.md)
- Pre-archive sequence (iOS)
- Android build
- watchOS
GTM — execute in market
gtm-playbook.md
the go-to-market playbook: geo tracks, channel strategy, launch sequencing
gtm-detail.md
Channel-by-channel detail (email · share · social · press · paid · street · VIP)
Contents
- Navigation
- Supporting docs landscape
- Strategy depth
- Pilot target + funnel math
- Top-10 growth levers
- Beachhead selection analysis
- The 10-lever execution matrix
- Cluster profiles + boundaries
- Sac City — detailed
- CHA — detailed
- Seeding venues — full research
- Digital watering holes — full research
- Channel detail
- Email — full spec
store-listings.md
App-store listing copy (canonical)
linkedin-launch.md
LinkedIn launch sequence
Contents
- Logo & cover
- Fields — enter these
- Overview / About — FINAL (as published on the page)
- Why it's built this way (LinkedIn best practice)
- 1 — Headline
- 2 — About — FINAL (center-right register)
- 2b — About: register variants and change map
- Register vocabulary reference
- 3 — Experience: VOTD entry
- 4 — Experience: Fractional CMO & Advisor
- 4a — Experience: Referendum — REMOVED
- 5 — Open to Work — setting (not copy)
- 6 — Featured section
- 7 — Skills
animator-brief.md
Motion-designer brief — territories, exhibits, Lottie export requirements (anchored: its assets are wired into brand/brand-manifest.json)
launch-tracker.html
Interactive launch tracker — the board UX the admin backlog board reuses
Go-live / Launch
rules/environments.md
the environments canonical: topology, what feeds what, the v2/v3 flag, gates + landmines. Item-level launch work lives in the launch decision map (ops/go-live/launch-decision-map-2026-08-15.xlsx), which retires into the backlog dashboard after its row-by-row pass. (The former MASTER-GO-LIVE-TRACKER.md was archived 2026-08-18 — it was three docs in one and its name misled.)
Contents
- The topology in one screen (verified 2026-07-23)
- The load-bearing discipline (holds regardless of the prod label)
- The prod-label decision — DECIDED 2026-08-17 (GATE A): promotion by rotation
- The go-live campaign (the current work living in this module)
- Live figures — query, never quote
- The app's v2/v3 read path — and why accounts needs v3
- Where to test
- Git and environments — DECIDED 2026-08-22
- Decision gates
- Landmines — do not step on these at cutover
- Rules in play (owned elsewhere; this module is the topology home)
- Supabase RLS — test policies before enabling (moved from CLAUDE.md 2026-09-10)
go-live-master-plan-inputs.md
Intake for the master-plan session (open gates, landmines, decisions)
go-live-migration-checklist.md
Migration checklist
Contents
- What must land on prod (only-on-Proto today)
- 1. Extensions
- 2. Schema (DB objects)
- 3. Scheduled jobs (pgcron)
- 4. Edge functions (deploy from supabase/functions/, verifyjwt: false)
- 5. Secrets — do NOT travel via git; manual per project (Dashboard → Edge Functions → Secrets)
- 6. Mac-side scheduled reminders (the fetching pipeline — CLAUDE-scheduled tasks)
- 7. Data
- 7b. Repoint — five distinct surfaces, not one line
- 8. VERIFY — the anti-orphan gate (do this the morning after cutover)
launch-ops-checklist.md
Launch-day ops checklist
Contents
- Cloudflare — votd.io zone / votd-public Worker
- Supabase — Stage aqbuwpncrurkloczbvkg
- The four signals (built 2026-09-14, migration 20260914…theaccountsstackgetsthefoursignalsthatcanbreakquietly)
- Infrastructure alerts — Supabase console, Stage
- The review, and what it found (2026-09-14)
- Proto xtxznjnqikuabjyotjbi — availability only
- RLS — superseded
- Notify + OTP senders — the two switches that release account mail
- Access perimeter — declared in the database, checked daily
- Deferred — ships WITH the Meta Pixel (before S3 paid ads, ~Jun 30)
- Follow-on (code or Cloudflare Transform Rule)
- Post-deploy — snapshot the live templates (LAST STEP, after a confirmed deploy)
app-store-launch-gates.md
Store submission gates
Contents
- Current State
- Timeline Math — S6 Launch (Aug 11–24 target)
- iOS — Gate Sequence
- Gate 1 — Technical Build Requirements
- Gate 2 — App Store Connect Listing
- Gate 3 — Screenshots
- Gate 4 — Privacy Labels (Data Safety)
- Gate 5 — Review Credentials
- Gate 6 — Terms of Service
- Review Timeline
- Known iOS Rejection Risks for VOTD
- Android — Gate Sequence
- Gate 1 — Graduate to Closed Testing ✓ DONE
- Gate 2 — 20 Testers, 14 Days
website-launch-restore-registry.md
PARKED-FOR-LAUNCH registry — every site element to restore at launch
launch-drafts-overview.md
Turnkey go-live Privacy + Delete-Account pages, held out of the build until the app does what they describe — swap in at public launch
Contents
- Rolling back to the beta pages
- Swap in at public launch (turnkey)
- Terms of Use (added 2026-09-01)
- The counsel package (2026-09-01)
- What changed 2026-09-01
- Notes relocated from the page templates (2026-09-03)
- 09-terms.html — dispute resolution is deliberately absent
- 04-privacy.html — two described practices are not running
- 06-about.html — the non-affiliation block is the canonical disclosure
- 07-sources.html — one state source link is pulled
- The standing rule
launch-and-raise-plan.md
Launch / signal / raise + go-no-go
Contents
- The bet, in one paragraph
- Why this matters — the impact thesis
- Why this shape
- What VOTD is — and why the usual metrics are the wrong ones
- What success actually looks like (the signal VOTD will read)
- The honest tension (do not skip)
- Timetable
- Triggers & milestones
- The go/no-go rule (pre-committed)
- Funding paths — mission capital as a bridge to the raise
- Open items to lock before launch
votes-to-work.md
Post-vote amplification strategy
Contents
- Why this matters
- How elected-official comms actually work
- The three channels
- Channel 1 — Public comment on the agenda item
- Channel 2 — Weekly VOTD newsletter
- Channel 3 — Beautiful assets for media distribution
- Data tier — public surface vs commercial product
- Non-adversarial framing rules
- How this is not a heavy lift
- Public-content surfaces
- URL structure
- County front door
- Per-vote pages
- Past-issue navigation
assessment
Press qualification
Contents
action-plan
Press qualification
Contents
- Part 1 — rewrites that thread the needle
- 1a. About page — new opening (replaces "An independent civic engagement app…")
- 1b. About page — new "Who publishes VOTD" section (this is the #1 gap: the masthead)
- 1c. FAQ "What is VOTD?" — lead with the publication, keep the snapshot
- 1d. Homepage — add one identity line
- 1e. Do NOT touch (already right)
- Part 2 — where VOTD could be seen as non-compliant (with mitigations)
- Part 3 — CNPA and LION Publishers, in detail
- CNPA — California News Publishers Association (recommended first)
- LION Publishers — Local Independent Online News (strong second)
- SPJ — Society of Professional Journalists (individual backstop)
- Recommendation
- Part 4 — engagement strategy + timeline (added 2026-07-03)
- Sources
packet
Press qualification
accounts-golive-hub.md
Accounts cutover hub — the index for the go-live accounts work
accounts-golive-runbook.md
Step-by-step accounts cutover runbook
Contents
- Phase 0 — Foundations (do first; some parallel)
- Phase 1 — Front-side verification build 🚀 (Proto, additive + feature-flagged)
- Phase 2 — Accounts + vote-integrity hardening 🚀
- Phase 3 — Promote Stage to production + go-live cutover 🚀🔒
- Phase 4 — Voter-records track 🕓 (back-side; post-funding; parallel, off critical path)
- Signup + verification UX — locked decisions (2026-07-04)
- OTP provider — Twilio simple text (Programmable SMS), native in Supabase
- The signup flow (screens + locked copy)
- The verification ladder + count-gate
- On-submit verification — synchronous, immediate signal
- GPS confirm — one-time, foreground, boolean-only (NOT tracking)
- Appointment reminder — "remind," never "ping" (not-home path)
- Re-engagement escalation ladder (state-driven, unlock-framed)
- Utility bill / photo ID — the "works anywhere" rung
accounts-gate-map.md
Which gates block the accounts go-live, and in what order
Contents
- 0. The state variable
- Which document is canonical for what
- 1. PHONE → auth (signup → verify-otp / verify-signin)
- 2. NAME + EMAIL (profile-setup)
- 3. ADDRESS → jurisdiction (address-setup)
- 4. RESIDENCY CONFIRM → the count-gate (review-confirm → registration-complete / confirm-address / verify-document)
- 4e. EDIT ACCOUNT — changing details after the funnel (review-confirm as the surface; today change-contact → confirm-contact-change)
- What it resets, and what it deliberately does not
- Why this surface is nonetheless the highest-value target on the account
- THE EDIT ACCOUNT MODEL — decided 2026-09-08 (founder). Not yet built.
- The repeat-change gate — decided, partly built, and narrower than remembered
- What makes a declaration stale — settled 2026-09-09, and two triggers are still missing
- THE GATE FOLLOWS STAKES, NOT DEVICE RECOGNITION — corrected and BUILT 2026-09-09
- AN ACCEPTED CREDENTIAL MAY NOT BE FOLLOWED BY A REFUSAL — settled 2026-09-09
environment-and-app-distribution-model.md
Which environment feeds which build, and how the app is distributed
Contents
- Where we landed (2026-07-03)
- What's true regardless of the prod label (build now on these facts)
- Stage stand-up log — 2026-07-04
- Stage data seed — 2026-07-06
- The launch-time decision — DECIDED 2026-08-17 (GATE A): promotion by rotation
- Git — a feature branch, nothing heavier
- How the two databases stay in sync
- The mobile app — build flavors, not two products
- Four mechanics this section assumed away — measured 2026-08-22
- The admin — a runtime tab, the third pattern (added 2026-08-22)
- The admin's staging surface — temporary, and it dies at 3.7
- DECIDED 2026-08-22 — Stage is the WORK tab, not a verification tab
- Admin page readiness on Stage — measured 2026-08-22
- Costs & disciplines
Brand / Design
docs/ops/brand/brand-assets.md
single-source asset rules (Rule #51). Module: rules/assets.md.
brand-voice.md
Canonical public-web voice & editorial standards (Rule #23)
Contents
- House lexicon — the settled way we say things (added 2026-07-08)
- Vote sources — never narrow VOTD to one (added 2026-08-07)
- Page-level structure framework (added 2026-05-01)
- The What → So What → What's Next arc
- Layer relationships within a section
- Headline discipline — always a statement, never an imperative
- Worked example — VOTD homepage hero (locked 2026-05-01)
- What to avoid
- Where this framework applies
- Brand posture (added 2026-06-08)
- Copy invites action, not just opinion
- Positivity is a hallmark — not a rule, a character
- Sell it directly — confidence grows toward launch (added 2026-06-28)
- Voice — complementary action verb (resolved 2026-05-03)
Comms
messaging-spine.md
the canonical narrative: what VOTD is, who it is for, how it is described
Contents
- 1. North star (one sentence)
- 2. The thesis (why it exists, why now)
- 3. The one-breath pitch and the six-question ladder (tongue-ready)
- The six-question ladder (added 2026-08-24)
- Guardrails across all six
- 4. The two rails (never cross them under challenge)
- 5. Different, and arguably better (the per-comparison playbook)
- vs an Election
- vs a Poll
- vs a Survey
- 6. Words to use (and avoid)
- 7. Positioning principles
- 8. Standard descriptions (boilerplate)
- 9. Sources
positioning-and-category.md
Category strategy + quick reference
Contents
- The decision, in one line
- Why not the existing labels
- Why not "datatainment" (the instinct, taken seriously, then rejected as the category)
- The two-layer model
- Naming — parked (2026-06-02)
- The "-Tech" verdict (rejected-alternatives record)
- Comparables — the working frame (the "Hollywood" pitch)
- Stress-test before this becomes load-bearing
- Category economics — proof it belongs in the land of money-makers
- Monetization implication of the category choice
- Landmines (do not step on)
- Where each register is used
- Open items
- References
positioning-cheat-sheet.md
Category strategy + quick reference
Contents
- Say this first (any audience)
- The grid: what each instrument is for
- Capstone: the only column whose job contains the others' jobs
- The four audiences
- 1. The Confused — "Wait, what is this? A poll? A petition? A government thing?"
- 2. The Skeptic — "Cute app. Does anyone use it? Does it change anything? Won't it die like the rest?"
- 3. The Entrenched — "This undermines representative democracy, pressures us, oversimplifies, and will be gamed by our opponents."
- 4. The Hard to Please — "Self-selected sample. Not representative. Question wording bias. Statistically invalid."
- The AI question (in person, when it comes up)
- Guardrails (all audiences)
- Sources
competitive-landscape.md
Full competitive analysis
Contents
- The cohort
- The broader field — gov-tech, polling, and deliberation (tiered)
- What's inhibited the cohort from breaking out
- Data-vendor landscape
- What VOTD does that the cohort doesn't
- The reframe — old apparatus vs new instrument
- How VOTD wins (three concrete moves)
- Two guardrails when using this framing
- Distilled internal FAQs
participation-baselines.md
Turnout evidence base + significance methodology
statistical-significance.md
Turnout evidence base + significance methodology
Contents
- Summary
- Why two questions, not one
- The participation funnel (what the numbers are measured against)
- Tier 1 — The count (what the participants decided)
- Tier 2 — Representative (does it reflect the whole community?)
- Reporting the margin: Wilson, not Wald
- Assumptions, stated plainly
- The math, in plain terms
- Small populations (the one genuinely hard case)
- Sources
- What changed and why (2026-07-12)
- What changed and why (2026-08-24)
investor-pitch-and-targets.md
Pitch language + target map
Contents
- Why two pools, two pitches
- The neutrality screen — read this before building the cap table
- Cohort A — Mission funders (grant + PRI/MRI layer)
- What they want to see
- Pitch language (lift into LOIs / program-officer emails / the mission one-pager)
- Voice notes
- Top 20 targets — Cohort A
- Cohort B — Impact angels + impact VC
- What they back
- Pitch language (lift into the deck / angel emails / the pre-seed memo)
- Voice notes
- Top 20 targets — Cohort B
- Sequencing & routing
- Open items — verify before outreach
one-pager-community.md
One-pager copy
Contents
one-pager-advisors-and-team.md
One-pager copy
civic-data-insights-strategy.md
Insights-as-content strategy
Contents
- What Makes VOTD's Data Unique
- Statistical Significance Model
- Core principle
- The count (what the participants decided)
- Representative / Indicative (survey precision, vs. registered voters)
- Sacramento pilot jurisdiction reference (Cochran + FPC)
- Demographic concentration caveat
- App / engineering note (2026-07-12)
- What to Publish at Each Stage
- Months 1–3 (pilot, ~60 votes, small user base)
- Months 4–12 (growing data, 200+ votes)
- Year 2+ (multi-city, scale)
- The Three Insight Types (permanent framework)
- Full-Strength Insight Concepts — "The Big Picture" (captured 2026-06-28)
executive-founder-playbook-v2.md
Founder playbook
Contents
- Contents
- Part I — Strategic Positioning
- Chapter 01 · The Core Frame: Executive Founder by Design
- The Engagement Narrative
- The 2026 Market Context
- Chapter 02 · The Primary Play: Fractional, Not Full-Time
- What Fractional Looks Like in Practice
- Option A — Own the Founder Title
- Option B — The AI Transformation Play
- Bridge Skill: Revenue-Stream Fluency
- Chapter 03 · Handling "What Are You Working On?"
- Part II — Your Competitive Edge
- Chapter 04 · The Force Multiplier Narrative
- Why It Lands
faq-plain-language-rewrite.md
FAQ plain-language rewrite
Contents
- P1 — What is VOTD? (grade 14.5 → ~7)
- P2 — Is VOTD a government platform? (grade 19.7 → ~6)
- P3 — Why participate in VOTD? (grade 14.3 → ~7)
- P4 — How does VOTD make sure people vote just once? (grade 11.9 → ~7)
- P5 — How does VOTD monitor to ensure legitimacy of votes? (grade 13.2 → ~7)
- P6 — How does VOTD ensure final vote data security and transparency? (grade 13.6 → ~7) (app-only)
- P7 — Who reviews flagged votes and what authority do they have? (grade 13.4 → ~8)
- P8 — How is VOTD different from an X poll, Change.org petition, or online survey? (grade 13.5 → ~7)
- P9 — Is VOTD's data statistically representative? (grade 12.4 → ~8)
- P10 — What would it take for VOTD to achieve statistical significance? (grade 14.9 → ~9, stakeholder-technical)
- P11 — What does VOTD do to ensure its data isn't demographically skewed? (grade 12.4 → ~9, stakeholder-technical)
- P12 — How does VOTD select what gets voted on? (grade 16.8 → ~7)
- P13 — What makes a strong vote topic? (grade 12.5 → ~7)
- P14 — How does VOTD keep vote question wording neutral? (grade 13.4 → ~8) (app-only)
Legal
docs/ops/legal/incorporation.md
legal-entity decisions (Delaware PBC).
Contents
- The decisions
- Why Delaware C-corp (and why not LLC or sole prop)
- Why Delaware (the state), not California
- Why Public Benefit Corporation
- Why Stripe Atlas
- Atlas vs Clerky — side-by-side (added 2026-05-31)
- Clerky pricing model — lifetime vs pay-per-use, and what's in each document set
- Year-one cost picture
- Action checklist
- Execution log — Clerky checklist (2026-07-09)
- Board, advisors, and the solo-founder question
- What this document does not cover
Lives at docs/ root
backlog.md
Live backlog — ## Active is the canonical durable task state (Rule #29)
Contents
- Active
- PRD-INF-18 — closed surface: nothing reachable that VOTD did not present (P0, S7, opened 2026-09-24)
- PRD-APP-16 — NEXT WAVE AFTER THE WALKS: the tally reporting ladder (P0, S7, decided 2026-09-24)
- PRD-INF-19 — personal-data key held outside the database (P3, Later, opened 2026-09-24)
- PRD-APP-15 — the system share sheet hands each app its own file (P3, Later, opened 2026-09-23)
- PRD-APP-14 — a member can see what happened to their suggestions (P1, opened 2026-09-23)
- PRD-CUR-16 — nothing resolves a parked proposal (P1, opened 2026-09-23)
- PRD-CUR-15 — the calendar's verbatim gate has nothing left to verify against (P1, opened 2026-09-23)
- PRD-CUR-14 — retain every candidate source, with its verdict (P2, opened 2026-09-23)
- PRD-APP-13 — which sources a vote carries (P2, opened 2026-09-23)
- PRD-APP-12 — community research returns (P3, Later, opened 2026-09-23)
- PRD-INF-01.7 — close the security posture gaps (P1, opened 2026-09-23)
- PRD-APP-11 — Add Research accepts a contribution and throws it away (P0, opened 2026-09-22)
- PRD-CUR-13 — a member proposal reaches the calendar (P0, opened 2026-09-22)
backlog-index.md
Board task set — the seed source for the PRD-ADM-03 dashboard (Rule #43)
Contents
- Taxonomy — two masters, sub-tracks, brand colors
- Schema
- Priority rollup (task-based)
- Build sequence — near-term critical path (founder-set 2026-06-03)
- Tasks (consolidated master set)
- Per-track tables & clusters — retired/folded 2026-06-03
- Cross-task dependencies (the riders that span tasks)
- Completed / shipped (for review)
- Status
- Archived tasks
faq.md
Canonical FAQ source — generates faqData.ts, public/support/, PublicFAQ, InternalFAQ (Rule #25). Build dependency; stays here
Contents
- How this file is structured
- Public
- P1. What is VOTD? <!-- topic: about -->
- P2. Why participate in VOTD? <!-- topic: about -->
- P3. Is VOTD a government platform? <!-- topic: about -->
- P4. How does VOTD make sure people vote just once? <!-- topic: integrity -->
- P5. How does VOTD monitor for suspicious vote activity? <!-- topic: integrity -->
- P6. How does VOTD ensure final vote data security and transparency? <!-- topic: integrity --> <!-- surface: app-only -->
- P7. How does VOTD handle abnormal voting activity? <!-- topic: integrity -->
- P8. How is VOTD different from an X poll, Change.org petition, or online survey? <!-- topic: methodology -->
- P9. Is VOTD's data statistically representative? <!-- topic: methodology -->
- P10. What would it take for VOTD to achieve statistical significance? <!-- topic: methodology -->
- P11. How does VOTD select what gets voted on? <!-- topic: topics -->
- P12. What makes a vote topic strong? <!-- topic: topics -->
index.html
The docs.votd.io landing page