diff --git a/docs/superpowers/specs/2026-11-11-code-family-dossier-design.md b/docs/superpowers/specs/2026-11-11-code-family-dossier-design.md
new file mode 100644
index 0000000..5d9499b
--- /dev/null
+++ b/docs/superpowers/specs/2026-11-11-code-family-dossier-design.md
@@ -0,0 +1,245 @@
+# Code-family dossiers: the complete life history of a code family, with its politics
+
+Date: 2026-11-11. Status: design, for review. Builds on
+`2026-09-09-code-family-longitudinal-design.md` (P49/P50).
+
+## Intent
+
+For any CPT/HCPCS code family, the stack can tell its whole biography as
+one cited account:
+
+1. **Origin** — the clinical concept and the benefit design or law that
+   called for a code (statute, regulation, CMS program, demonstration).
+2. **Formation** — when the code set first formed and was drafted: the
+   AMA CPT Editorial Panel action (or CMS creating a G-code), and the
+   first year it appears in the fee schedule.
+3. **Valuation** — the initial RUC survey and recommendation (survey
+   percentile, work RVU, time, comparator codes) and what CMS did with it
+   (accepted, refined, rejected — and why), plus practice-expense inputs.
+4. **Every change since** — revaluations, descriptor and guideline
+   changes, misvalued-code nominations, telehealth listing, bundling,
+   deletion, replacement — through all time.
+5. **Payment over all time** — a year-by-year table of RVUs, conversion
+   factor and national payment, proposed vs final, with utilization.
+
+At every step it shows **the politics**: how public commenters lined up
+(support / support with modifications / oppose), who they were, what
+evidence each side cited, and what each stood to gain or lose — in
+**money** (payment and specialty income shifts) and in **power** (who
+controls the code: RUC and CPT Panel seats, code sponsorship, which
+specialties bill it). The aim is to explain stances well enough to
+predict them from the stakes, and to ground the power analysis in the
+published research on the RUC (US) and on fee-setting bodies abroad.
+
+The user wants this "for everything", in this order: **primary care and
+home-based care first**, then **anything overlapping bundling or
+value-based care**, then **the obscure rest**.
+
+## Output
+
+- **A standing dossier page per family**, read on screen (not designed
+  for print). It is the canonical, browsable account.
+- **The same material in chat.** A question about a family answers from
+  the dossier's evidence, cites it, and links to the page. Chat's current
+  payment/valuation table is the starting point, made complete
+  (all years, all codes in the family, proposed vs final).
+- Everything is cited: a Federal Register paragraph (`#p-N` jump link),
+  a comment (regulations.gov id), a CMS file, a public AMA document, a
+  statute section, or a study. An unsourced statement does not appear.
+
+Dossier page layout (my call; a mockup can come before building):
+header (family, codes, status, years active) → one-paragraph summary →
+timeline (each event with date, what changed, source, and its comment
+split) → valuation panel (RUC recommendation vs CMS decision per code
+per round, comparators) → payment table (all years) → stakeholders
+panel (who supported/modified/opposed, by organization type and
+specialty, with their stakes) → governance context (relevant findings
+from the RUC and international literature) → sources.
+
+## Phase 1 scope (proof of concept, then fan out)
+
+**Proof family (my call): home and residence visits** — 99341–99350 plus
+the deleted domiciliary codes 99324–99340 and 99343 they absorbed in
+2023. The user named it, and it exercises every gap: deleted codes,
+late-1990s origin, RUC 25th-percentile recommendations
+(`PETM225D` ¶1676), commenter splits (¶1679), the G2211/B1/B2 add-on and
+the 2027 home-visit revaluation. Its dossier is the acceptance test.
+
+Then the rest of primary care and home-based care: office/outpatient
+E/M, G2211 and modifiers B1/B2, CCM (99490/99491/99487–99489/99437/
+99439/G2058), PCM (99424–99427, G2064/G2065), TCM (99495–99496), APCM
+(G0556–G0558), care plan oversight and home health certification
+(G0179–G0182, 99339/99340, 99374–99380), BHI and CoCM (99484,
+99492–99494), RPM/RTM, ACP (99497–99498), prolonged services
+(99354–99357, 99417/99418, G0316–G0318), virtual check-ins and
+communication-technology services (G2010/G2012/G2252).
+
+Phase 2: bundling and value-based-care overlaps (global surgical
+packages, MSSP/ACO and Innovation-Center-linked codes, APCM's tie to
+APM participation, care-management bundles, RHC/FQHC payment). Phase 3:
+everything else.
+
+## What exists (from the 2026-11-11 recon)
+
+Reuse, do not rebuild:
+- `pfs.code_event` (16,942 events / 6,713 codes) and `src/pfs/lineage.py`:
+  events anchored to FR paragraphs (CY2002–CY2027), RVU-file changes
+  (2016–2026), CPT Changes years; `src/llm/lineage.py` timeline block in
+  chat.
+- `fr_anchors` (200,975 paragraphs) and `pfs/reaction.py`'s
+  Comment:/Response: pairing; `pfs.code_reaction` with closed stance
+  labels support / oppose / modify / unclear (sampled for CCM only).
+- `pfs/valuation.py`, `pfs.rules.RULES` (CF 2014–2027), `pfs.rvu`
+  (2015–2027), `rvu_proposed`, work-time files, `pfs.utilization`.
+- Chunk metadata `codes` / `families` on all 1.42M comment chunks; bib
+  `code:` / `family:` tags; P35 theme tags (vocab v3) on comments.
+- `pfs.code_family` (8,489 derived families) and the five hand families.
+
+Gaps this design closes: (1) no structured RUC/CMS valuation
+extraction; (2) deleted codes have no lineage; (3) depth stops at CY2002
+rules / 2015 RVUs, no statute links; (4) primary-care family definitions
+are poor (generic keys, G2211 misgrouped, biliary codes in office E/M);
+(5) stance exists only for a CCM sample, commenter identity for 4.4% of
+comments; (6) chat caps the payment table at 2 years for multi-code
+families; (7) no governance literature in the library.
+
+## How it gets built (the parts decided)
+
+### Sources — public only for now (user decision)
+
+Federal Register PFS rules (back as far as federalregister.gov/govinfo
+publish them, then earlier rules via govinfo where available); CMS PFS
+relative-value files and public-use files for every year CMS publishes;
+CMS specialty-impact tables; regulations.gov comments; statute and
+regulation text (US Code, public laws, eCFR — `bib.cfrlink` exists);
+CMS manuals and MLN; MedPAC reports; public AMA material (CPT Editorial
+Panel summaries of actions and RUC meeting minutes/vote records where
+the AMA posts them publicly; RUC membership rosters); the open-access
+governance literature from the recon list
+(`scratchpad/recon/ruc-literature.md`, ~90 sources). Licensed books
+(*CPT Changes*, CPT codebooks, *Medicare RBRVS*) are added later when the
+user supplies them; the design must work without them and get richer
+with them.
+
+### Families
+
+A curated family registry for phase 1 (hand-checked membership,
+predecessor/successor links across renumbering and deletion, G-code
+families, the add-on and modifier relationships), layered over the
+derived families. Every code ever seen gets lineage, not only codes
+payable in the newest year.
+
+### Extraction (all local models — the llm module never calls cloud LLM APIs)
+
+- **Valuation decisions** from FR paragraphs: per code per round — RUC
+  recommended work RVU, survey percentile used, survey time, comparator
+  / crosswalk codes, CMS final value, decision (accept / refine / reject /
+  interim), CMS's stated rationale.
+- **Comment stance** per family per event: support / support with
+  modifications / oppose / unclear, with the reason and the evidence the
+  comment cites, extending `pfs.code_reaction` beyond CCM. CMS's own
+  Comment:/Response: summaries are a second, independent stance source
+  (CMS says "many commenters supported…"); both are shown, never merged
+  silently.
+- **Commenter identity**: organization, organization type (specialty
+  society, health system, vendor, payer, patient group, individual
+  clinician, individual), specialty, and form-letter campaign membership
+  (near-duplicate clustering). From regulations.gov fields first, then
+  letterhead/opening text of the comment and its attachments.
+
+### Stakes
+
+- **Money**: CMS specialty-impact tables per rule year; code-level
+  payment change × utilization, attributed to billing specialties;
+  proposed-vs-final deltas.
+- **Power**: RUC and CPT Panel seats by specialty and year (public
+  rosters), code sponsorship (who brought the code to the Panel/RUC, from
+  FR and public AMA records), share of a family's billing by specialty.
+- **Prediction**: an explainable model of stance from stakes
+  (expected stance per stakeholder given money and power at stake),
+  reported against actual stances per event, as calibration — not as a
+  black box.
+
+### Governance research
+
+Ingest the open-access items from the recon list into bib/Zotero
+(tagged, with full text where open access), mark paywalled ones on the
+wanted list. Dossiers cite specific findings where they bear on a
+family (e.g. RUC acceptance rates, survey response rates, the specialty
+seat effect on prices, international fee-setting comparisons).
+
+### Chat
+
+Family detection → dossier evidence block (timeline, valuation rounds,
+comment split, stakes) → answer cites it and links to the page. The
+payment table is complete (all years, all family codes) with proposed
+vs final marked.
+
+## Goals
+
+- The home-visit dossier is complete and correct end to end, checked
+  against the FR text and comments by hand — the acceptance test.
+- Every primary-care/home-based family in scope gets a dossier, then
+  phase 2 and 3 families.
+- Each dossier statement is cited; coverage gaps are stated on the page
+  ("rules before CY2002 not yet captured").
+
+## Non-goals
+
+- Printing or publishing dossiers outside the stack (they live behind
+  SSO like the rest).
+- Using licensed book content before the user supplies the books.
+- Cloud LLM calls.
+- Real-time updates; dossiers refresh on the nightly pipeline / on
+  demand.
+
+## Anti-goals (would make it a failure even if it works)
+
+- Unsourced or invented history (an origin story the sources don't
+  support).
+- Blurring proposed and final values, or CMS's summary of commenters with
+  our own count.
+- Editorial tone. The power analysis is shown through cited facts and
+  findings, in neutral language; the evidence carries the argument.
+- Profiling private individuals: individual commenters appear only in
+  counts and organization types, never as named profiles.
+
+## Constraints
+
+- Repo rules: main only, local-only LLMs, public data in the DR hoard
+  only (no ACO/WNOT/Wakely material), never spoof a browser UA for
+  FR/eCFR, hoard old copies of every source document.
+- GPU budget: the rig 4090 and rack 3060 are shared with tagging and
+  chat; extraction batches must be resumable.
+
+## Calls made after the builder check (mine, for review)
+
+- **How text gets onto a page.** Facts come from stored, cited rows:
+  valuation rounds, events, stances, identities, stakes, and a new
+  structured *origin* table linking each code to the statute, regulation,
+  program or demonstration behind it (extracted from FR preambles,
+  statute text and CMS program documents). The local model may write the
+  connective prose (summary paragraph, per-event "what changed" line)
+  **only from those rows**, and every sentence must carry at least one
+  row citation. A citation check rejects any sentence without one, and
+  rejects any number that differs from its cited row, before the page
+  renders. Hand-curation stays limited to family membership.
+- **Stance prediction.** Phase 1 ships an explicit rule from stakes to
+  expected stance (e.g. a payment cut to a specialty that bills the code
+  → expected oppose; new payment for a specialty's service → expected
+  support), shown beside actual stances so mismatches stand out. A
+  fitted, explainable model comes after the primary-care fan-out, once
+  many families supply stance and stakes data. The stakeholder unit is
+  **organization type × specialty**, with the named organizations listed
+  under it. Money stakes per specialty need specialty-level utilization,
+  which `pfs.utilization` lacks; the builder adds a public by-specialty
+  source (CMS Physician/Supplier Procedure Summary or the Medicare
+  Physician & Other Practitioners public-use files).
+
+## Left to the builder
+
+Storage schema for valuation rounds, stances and identities; extraction
+prompts and models (within local-only); the dossier page's framework
+(the llm service already serves the chat UI and `/search`, so a page
+there is the obvious home — builder's call); near-duplicate method for
+form letters; how far back public sources actually reach (report it).