📋 Add code appendix design spec

Approved Hybrid D (MyST anchors + Typst registry) with Option A
hermeneutics paragraph numbering for full untruncated code appendix.

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: stevejpurves

docs/superpowers/specs/2026-06-08-jdh-code-appendix-design.md

@@ -0,0 +1,393 @@
+# JDH Code Appendix — Design Spec
+
+**Date:** 2026-06-08  
+**Status:** Approved  
+**Repos:** `jdh-cli`, `jdh-typst-template`
+
+## Goal
+
+Add an optional **Code Appendix** to JDH PDF exports: a clean page break and
+section after the main article body that lists every eligible code block in
+manuscript order, styled like the main flow (narrative gray / hermeneutics
+cyan) but **never truncated**. Each appendix entry shows the **same paragraph
+number** as in the main document so readers can cross-reference truncated
+excerpts in the body with full listings in the appendix.
+
+Fixture scale (BHmHNQKJaSWT): **1** narrative code block, **10** hermeneutics
+code blocks (11 appendix entries total).
+
+## Scope
+
+### In scope
+
+- Eligible **narrative** and **hermeneutics** block-level code (see eligibility)
+- Manuscript-order replay from a Typst registry populated during main-body render
+- Full code (no `max-lines` clip, no fade, no “N lines more” footer)
+- Paragraph numbers in appendix matching main-flow semantics (Option A for
+  hermeneutics)
+- Page break + section heading **before References** (`template.typ`)
+- Opt-in via project config (`meta-jdh.yml` or frontmatter)
+- Thin MyST anchor plugin + Typst registry/renderer (**Hybrid D**)
+- Unit tests for MyST eligibility / anchor injection; manual PDF verification
+- Documentation in `jdh-cli/docs/plugins/`
+
+### Out of scope
+
+- Figure boilerplate code (`code:fig:*` / figure-tagged cells)
+- Inline `` `code` ``
+- HTML export
+- Tables, figures, or prose in the appendix
+- Improve-pipeline duplication of code into `article.md`
+- Changing main-flow truncation defaults (`jdh-theme.code.max-lines`)
+- Adding visible paragraph numbers to hermeneutics code in the main body
+
+## Decisions (approved)
+
+### Technical approach: D — Hybrid (thin MyST anchors + Typst registry)
+
+MyST assigns stable sequence IDs and injects minimal Typst hooks; Typst captures
+code text, paragraph numbers, and kind at **render time** during main-body layout,
+then replays the registry after `[-CONTENT-]`. Matches the hermeneutics /
+narrative-code / jdh-table pattern without duplicating source in markdown.
+
+Not approach A (MyST-only appendix directive with duplicated bodies), B (improve
+step appends appendix markdown), or C (Typst-only without MyST sequencing).
+
+### Hermeneutics paragraph numbers: Option A
+
+Use the paragraph number of the **preceding numbered block** in main flow — the
+last prose paragraph or heading that received a paragraph number **before the
+opening of the hermeneutics block** (`:::{hermeneutics}`). All code excerpts
+inside that block share that number.
+
+Not Option B (dedicated hidden/visible ¶ per hermeneutics code excerpt in main
+flow).
+
+Implementation: at hermeneutics code render time, freeze
+`jdh-last-para-num` (see § Paragraph numbers) — the counter value after the
+last `p-step` on a numbered block before the hermeneutics wrapper opened.
+
+### Placement
+
+`template.typ`: after `[-CONTENT-]`, **before** `#bibliography(...)` (References).
+
+### Styling
+
+Appendix entries reuse main-flow visual language:
+
+| Kind | Main-flow wrapper | Appendix styling |
+|------|-------------------|------------------|
+| Narrative | `#narrative-code-block` | Same gray fill / bleed; no truncation footer |
+| Hermeneutics | `#hermeneutics-block` + code markers | Same cyan fill; sidebar markers optional (see Open items) |
+
+Typography from `jdh-theme.code` (font, size, line-height) applies in both
+flows.
+
+### Truncation
+
+Truncation is **Typst-only** today (`jdh-theme.code.max-lines`, `fade-lines`).
+Appendix sets `in-appendix-block` state so `show raw.where(block: true)` skips
+clipping and the “N lines more” overlay. Main-body behaviour unchanged.
+
+### Config
+
+Feature is **opt-in** (default off). See § Configuration.
+
+## Architecture
+
+Three layers, mirroring jdh-table / narrative-code:
+
+```
+MyST build                    Main-body Typst              Appendix Typst
+──────────                    ───────────────              ──────────────
+code-appendix.mjs      →      jdh-code-appendix-enter  →   jdh-render-code-appendix()
+  inject seq anchors            register {seq, kind,          pagebreak + heading
+  (after narrative/              content, paraNum}            replay registry
+   hermeneutics wraps)          during normal render          in-appendix-block: true
+                                (truncated in body)           full code, frozen ¶
+```
+
+```mermaid
+flowchart TB
+  subgraph myst [MyST build]
+    NC[narrative-code.mjs]
+    HM[hermeneutics.mjs]
+    CA[code-appendix.mjs]
+    NC --> CA
+    HM --> CA
+  end
+  subgraph main [Main body render]
+    REG[(jdh-code-appendix-registry state)]
+    NCW["#narrative-code-block"]
+    HMW["#hermeneutics-block + code"]
+    NCW -->|register entry| REG
+    HMW -->|register entry| REG
+  end
+  subgraph appendix [After CONTENT in template.typ]
+    REN["#jdh-render-code-appendix()"]
+    REG --> REN
+    REN --> REFS["#bibliography References"]
+  end
+  myst --> main
+  main --> appendix
+```
+
+### Registry entry shape
+
+Each eligible code block appends one record during main-body render:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `seq` | int | Manuscript order (from MyST anchor) |
+| `kind` | `"narrative"` \| `"hermeneutics"` | Styling branch |
+| `content` | string | Full raw source (`it.text`) |
+| `para-num` | int | Frozen paragraph number for appendix margin |
+
+Registry is a Typst `state("jdh-code-appendix-registry", ())` array, appended
+in `seq` order (MyST guarantees monotonic IDs).
+
+## Eligibility
+
+Mirror existing plugin rules. Include:
+
+| Source | Eligible? | Notes |
+|--------|-----------|-------|
+| Block `code` wrapped by `#narrative-code-block` | Yes | Untagged or `tags=["narrative"]` |
+| Block `code` inside `#hermeneutics-block` | Yes | One registry entry per code fence |
+| Code inside tables / admonitions (narrative rules) | Yes | Same as narrative-code |
+| `code:fig:*` / figure pipeline output | **No** | Removed by hide-figure-code |
+| Inline code | **No** | Not block-level |
+| Plain `raw` blocks outside wrappers | **No** | Not styled code |
+
+When `project.jdh.code_appendix` is false, MyST plugin is inert (no anchors;
+Typst renderer emits nothing).
+
+## Paragraph numbers
+
+Global counter: `counter("jdh-paragraph")` in `jdh.typ`. Title, abstract, and
+front matter are not numbered.
+
+### Shared Typst state
+
+Add `jdh-last-para-num` state, updated whenever a numbered block completes
+`p-step` (body paragraphs, headings, narrative code). Hermeneutics code reads
+this snapshot; it does **not** call `p-step` in main flow today.
+
+Add `jdh-hermeneutics-block-para-num` state, set once when `#hermeneutics-block`
+opens: copy `jdh-last-para-num` at block entry. All code registrations inside
+that block use `jdh-hermeneutics-block-para-num` (Option A — preceding block
+before the hermeneutics wrapper).
+
+### Narrative code
+
+At existing `#narrative-code-block` render site (where `p-display` + `p-step`
+already run), register with `para-num` = counter value **after** `p-step` — the
+same number shown in the main-flow margin.
+
+### Hermeneutics code
+
+At hermeneutics code render (inside `#hermeneutics-block`, no main-flow
+`p-display`), register with `para-num` = `jdh-hermeneutics-block-para-num`.
+
+Example (BHmHNQKJaSWT): narrative block shows ¶ 42 in main body → appendix
+entry 1 shows **42**. Hermeneutics excerpt following ¶ 58 prose → appendix
+entries show **58** (not a new number for the cyan code box).
+
+### Appendix display
+
+Appendix replays entries with **frozen** `para-num` in the margin column.
+Replay must **not** call `p-step` (no double-counting). Use a dedicated
+`p-display-frozen(n)` helper that prints a literal number instead of
+`counter.display()`.
+
+Appendix section heading uses `p-skip` (does not consume or display a new ¶).
+
+## Typst (`jdh-typst-template`)
+
+### New state
+
+```typst
+#let in-appendix-block = state("jdh-in-appendix-block", false)
+#let jdh-code-appendix-registry = state("jdh-code-appendix-registry", ())
+#let jdh-last-para-num = state("jdh-last-para-num", 0)
+#let jdh-hermeneutics-block-para-num = state("jdh-hermeneutics-block-para-num", 0)
+```
+
+### Registry helpers
+
+```typst
+#let jdh-code-appendix-enabled = state("jdh-code-appendix-enabled", false)
+
+#let jdh-code-appendix-register(kind, seq, content, para-num) = context {
+  if not jdh-code-appendix-enabled.get() { return }
+  jdh-code-appendix-registry.update(entries => {
+    entries + ((kind: kind, seq: seq, content: content, para-num: para-num))
+  })
+}
+```
+
+Called from `#narrative-code-block` and the hermeneutics code path in
+`show raw.where(block: true)` after content is known.
+
+### `in-appendix-block` truncation bypass
+
+In `show raw.where(block: true)`, when `in-appendix-block.get()`:
+
+- Skip `max-lines` / `hidden-lines` / fade / “N lines more”
+- Render full `it`
+- Keep font, fill, and wrapper styling
+
+### `#jdh-render-code-appendix()`
+
+Called from `template.typ` when enabled (via frontmatter flag passed into
+`#show: template.with(...)`):
+
+1. If registry empty → return nothing
+2. `#pagebreak()` (recto/odd break: open item)
+3. `#p-skip.update(true)` around appendix heading
+4. `#heading(level: 1)[Appendix: Code Listings]` (wording open item)
+5. `#in-appendix-block.update(true)`
+6. For each registry entry in `seq` order:
+   - `#p-display-frozen(entry.para-num)`
+   - Wrap in `#narrative-code-block` or `#hermeneutics-block` (appendix variant)
+   - Render `raw(block: true, entry.content, lang: ...)`
+7. `#in-appendix-block.update(false)`
+
+### `template.typ` hook
+
+```typst
+[-CONTENT-]
+
+#if doc.jdh.code-appendix ?? false {
+  #jdh-render-code-appendix()
+}
+
+#if doc.bibtex {
+  #bibliography("[-doc.bibtex-]", ...)
+}
+```
+
+Exact frontmatter path wired during implementation (`doc.jdh.code-appendix` or
+export option — see Open items).
+
+### Theme tokens (optional)
+
+```typst
+code-appendix: (
+  heading: "Appendix: Code Listings",
+  enabled-default: false,
+)
+```
+
+Under `jdh-theme` for heading text override.
+
+## MyST (`jdh-cli`)
+
+### Plugin: `code-appendix.mjs`
+
+New bundled plugin (or extend `narrative-code.mjs` + `hermeneutics.mjs` — prefer
+**single dedicated plugin** that runs after both, stage `document`):
+
+1. Read `project.jdh.code_appendix` from MyST config (if unavailable, no-op)
+2. Walk AST in document order; find eligible `code` nodes (same predicates as
+   narrative-code + code under `block[kind=hermeneutics]`)
+3. Assign monotonic `seq` (1, 2, 3, …)
+4. Insert raw Typst anchor immediately before each code node (inside existing
+   wrapper if already wrapped):
+
+   ```typst
+   #jdh-code-appendix-seq-enter(3, kind: "narrative")
+   ```
+
+   Matching `#jdh-code-appendix-seq-leave(3)` after the code node (or combine
+   into enter-only if registration happens entirely in Typst wrappers).
+
+5. Set `jdh-code-appendix-enabled` via raw Typst preamble when feature on:
+
+   ```typst
+   #jdh-code-appendix-enabled.update(true)
+   ```
+
+Plugin bundled and deployed like the other four JDH plugins (always listed in
+workdir `myst.yml`). Transform and Typst hooks no-op when `code_appendix` is
+false.
+
+### Interaction with existing plugins
+
+| Plugin | Change |
+|--------|--------|
+| `narrative-code.mjs` | No eligibility change; code-appendix runs after wrap |
+| `hermeneutics.mjs` | No change; code-appendix finds inner `code` nodes |
+| `hide-figure-code.mjs` | Figure code never reaches appendix |
+
+Transform order in `myst.yml`: hermeneutics → hide-figure-code → jdh-table →
+narrative-code → **code-appendix** (last).
+
+## Configuration
+
+Opt-in on the article project. Proposed shape in `meta-jdh.yml`:
+
+```yaml
+project:
+  jdh:
+    code_appendix: true
+```
+
+When true:
+
+- MyST plugin injects anchors and enables Typst registry
+- Typst template receives equivalent flag for `jdh-render-code-appendix()`
+
+When false (default): plugin is loaded but inert; no appendix pages.
+
+Default bundled `meta-jdh.yml`: `code_appendix: false` (or key omitted).
+
+Articles override in repo `meta-jdh.yml` or `myst.yml` frontmatter.
+
+## Testing
+
+| Test | Covers |
+|------|--------|
+| `test/code-appendix.test.ts` | Eligibility predicates, seq ordering, hermeneutics vs narrative, figure/inline exclusion, plugin no-op when disabled |
+| `test/bundled-plugins.test.ts` | Plugin deployed when config enabled |
+| Manual — BHmHNQKJaSWT | Rebuild PDF with `code_appendix: true`: 11 entries, order matches manuscript, narrative shows same ¶ as main, hermeneutics entries show preceding-block ¶, no truncation, appendix before References |
+| Manual — disabled | Default build unchanged (no appendix section) |
+
+## Repos touched
+
+| Repo | Files (indicative) |
+|------|-------------------|
+| **jdh-cli** | `templates/plugins/code-appendix.mjs`, `src/steps/common/init-myst-config.ts`, `templates/meta-jdh.yml` (docs default), `test/code-appendix.test.ts`, `docs/plugins/code-appendix.md`, `docs/plugins.md`, `docs/typst.md` |
+| **jdh-typst-template** | `jdh.typ` (state, registry, truncation bypass, `jdh-render-code-appendix`, `p-display-frozen`, `jdh-last-para-num` updates), `template.typ` (hook before bibliography) |
+
+Article repos (e.g. BHmHNQKJaSWT): set `code_appendix: true` in `meta-jdh.yml`
+to enable; no pipeline step changes.
+
+## Phased delivery
+
+1. **Phase 1:** Typst registry + `in-appendix-block` truncation bypass +
+   `jdh-render-code-appendix()` + `template.typ` hook; manual test with hard-coded
+   registry entry
+2. **Phase 2:** MyST `code-appendix.mjs` anchors + config opt-in + paragraph
+   number capture (narrative + Option A hermeneutics)
+3. **Phase 3:** Docs, automated tests, BHmHNQKJaSWT verification, theme polish
+   (heading wording, hermeneutics markers in appendix)
+
+## Open items
+
+| Item | Notes |
+|------|-------|
+| Appendix heading text | Default “Appendix: Code Listings”; confirm with JDH editorial / PDF guideline |
+| Hermeneutics sidebar markers in appendix | Recommend **omit** markers in appendix (full code, not “excerpt”); confirm visually |
+| Page break style | `#pagebreak()` vs `#pagebreak(to: "odd")` for recto start |
+| Frontmatter key path | `project.jdh.code_appendix` (MyST) vs `doc.jdh.code-appendix` (Typst) — align in implementation |
+| Multiple code fences in one hermeneutics block | All share block-exterior ¶ (Option A); duplicate numbers in appendix are intentional |
+| Language tag on replay | Preserve from original `code` node (`lang` field) for raw block |
+| Empty appendix | No page break if zero eligible blocks |
+
+## References
+
+- Prior exploration: task 67021dee (Hybrid D recommendation, BHmHNQKJaSWT inventory)
+- Existing patterns: `narrative-code.mjs`, `hermeneutics.mjs`, `jdh.typ` code truncation
+- Table spec (same doc series): `2026-06-07-jdh-table-design.md`
+- Fixture: `BHmHNQKJaSWT/_improved/article.md` — 1 narrative + 10 hermeneutics code blocks