@lifeaitools/rdc-skills 0.15.0 → 0.17.0

package/skills/lifeai-brochure-author/SKILL.md

@@ -0,0 +1,338 @@
+---
+name: lifeai-brochure-author
+version: 0.1.0
+description: |
+  The mandatory contract for authoring brochure JSX using @lifeai/brochure-kit. Use this skill EVERY TIME any AI engine (Claude, Cursor, Copilot, /design, Cowork, v0) generates JSX intended for the Brochurify pipeline — whether the user says "write a brochure," "make a one-pager," "draft a PDF report," or any equivalent. Also trigger when a file imports from @lifeai/brochure-kit. Failing to read this skill before authoring is a defect.
+
+triggers:
+  - "write a brochure"
+  - "make a one-pager"
+  - "draft a PDF report"
+  - "design a brochure"
+  - "create an investor doc"
+  - "generate a fact sheet"
+  - "brochurify"
+  - "@lifeai/brochure-kit"
+  - any JSX file under apps/*/brochures/ or packages/brochure-*/
+
+required_validators:
+  - command: pnpm bk-lint
+    blocking: true
+---
+
+# LIFEAI Brochure Authoring Contract
+
+This is the contract every AI engine obeys when generating brochure JSX. The contract is non-negotiable. If you cannot generate output that complies, **stop and ask for clarification rather than emit non-compliant code.**
+
+## The Core Rule
+
+Every brochure is a tree composed exclusively of components from `@lifeai/brochure-kit`. Raw HTML elements (`div`, `span`, `section`, etc.) are forbidden in the page tree. There are no exceptions.
+
+```tsx
+// ❌ WRONG
+<div className="flex flex-col gap-4">
+  <h1 style={{color: '#2d5a3f'}}>Title</h1>
+  <p>Body text...</p>
+</div>
+
+// ✅ RIGHT
+<Stack gap="md">
+  <Heading level={1} variant="accent">Title</Heading>
+  <Prose>Body text...</Prose>
+</Stack>
+```
+
+If you find yourself reaching for a `<div>`, the answer is one of: `<Stack>`, `<Cluster>`, `<Section>`, `<Columns>`, or `<Brochure>`. There is always a kit primitive for what you want.
+
+## The Allowed Components
+
+Exactly these. No others.
+
+### Layout primitives
+- `<Brochure>` — root wrapper. Required. Carries `theme`, `pageSize`, `mode`.
+- `<Page>` — explicit page boundary. Use sparingly; prefer Sections.
+- `<Section>` — semantic grouping. Carries `level`, `id`, `affinity`.
+- `<Cluster>` — tightly-coupled children (heading + intro + image). Stays together when possible.
+- `<Stack>` — loose vertical flow. The default container.
+- `<Columns>` — multi-column block. Carries `count`, `gap`.
+- `<Spacer>` — explicit air. Declared in named sizes only.
+
+### Content primitives
+- `<Prose>` — body text. Wraps paragraphs. Required for any flowing copy.
+- `<Heading>` — section heading. Carries `level` (1-6), `variant`.
+- `<Quote>` — pull quote. Carries `attribution`, `variant`.
+- `<Stat>` — single numeric callout. Carries `value`, `label`, `variant`.
+- `<StatRow>` — horizontal band of Stats. Carries `count`.
+- `<DataTable>` — table. Carries `headers`, `rows`, `splitPolicy`.
+- `<List>` — typed list. Carries `kind` (bullet, number, check, none).
+- `<Definition>` — term + definition pair.
+
+### Visual primitives
+- `<Figure>` — image with caption. Carries `src`, `alt`, `caption`, `width`, `height`, `crop`, `bleed`.
+- `<Hero>` — page-anchored hero. Carries `src`, `alt`, `placement`.
+- `<Divider>` — explicit separator. Carries `variant`.
+
+### Meta primitives
+- `<Cover>` — first page, page-locked.
+- `<TableOfContents>` — auto-generated from `<Heading>`s.
+- `<Footnote>` — page-anchored footnote. Carries `id`, `marker`.
+
+## The Allowed HTML (inside `<Prose>` only)
+
+Inside `<Prose>`, these inline HTML elements are allowed:
+- `<em>`, `<strong>` — emphasis
+- `<a>` — links (with `href`)
+- `<code>` — inline code
+- `<sub>`, `<sup>` — subscript/superscript
+- `<br>` — line break (use sparingly)
+
+Anything else inside `<Prose>` is rejected.
+
+## The Forbidden Patterns
+
+These are hard-rejected by the validator. Do not emit them under any circumstance.
+
+1. **Raw layout HTML** — `<div>`, `<span>`, `<section>`, `<article>`, `<aside>`, `<header>`, `<footer>`, `<nav>` outside of `<Prose>`.
+2. **Inline styles** — `style={{...}}` on any element. Use variant props instead.
+3. **Color literals** — Hex codes, rgb(), hsl() in JSX. Use theme tokens via variants.
+4. **Viewport units** — `vh`, `vw`, `vmin`, `vmax` anywhere. Pages have fixed dimensions; viewport units break pagination.
+5. **Flexbox utility classes** — `flex`, `flex-col`, `justify-*`, `items-*` directly in className. Use kit primitives that handle layout.
+6. **Tailwind sizing literals** — `w-64`, `h-32`, `min-h-screen`. Use kit props.
+7. **Empty containers** — `<Stack></Stack>` with no children is rejected. Use `<Spacer>` for explicit air.
+8. **Nested `<Page>`** — Pages cannot contain Pages.
+9. **`<Figure>` without dimensions** — Every Figure must declare `width` and `height` (in inches or as a kit named size: `xs`, `sm`, `md`, `lg`, `xl`, `full`, `bleed`).
+10. **External CSS imports** — No `import './foo.css'` in brochure files. Theming is via tokens.
+
+## The Required Props
+
+Every brochure must:
+
+1. Have exactly one `<Brochure>` root wrapper
+2. Declare `theme` on `<Brochure>` (one of: `prt`, `place-fund`, `zoen`, `evergreen`, `editorial-neutral`)
+3. Declare `pageSize` on `<Brochure>` (one of: `letter`, `a4`, `legal`, `digest`, `tabloid`)
+4. Declare `mode` on `<Brochure>` (one of: `read-only`, `cosmetic`, `editorial`, `creative`)
+
+## The Token System
+
+All styling derives from `@lifeai/brochure-tokens`. You reference tokens via variant props, never via raw values.
+
+```tsx
+// ✅ Variant references resolve to tokens
+<Heading variant="accent">...</Heading>           // → color: token.color.accent
+<Stat variant="emphasis">...</Stat>               // → typography.scale.emphasis
+<Stack gap="md">...</Stack>                       // → spacing.scale.md
+<Figure width="lg" height="md">...</Figure>       // → kit-named sizes
+
+// ❌ Literal references fail
+<Heading style={{color: '#2d5a3f'}}>...</Heading> // hard-rejected
+<Stack style={{gap: '24px'}}>...</Stack>          // hard-rejected
+```
+
+Available variant tokens depend on the theme. Common ones: `default`, `muted`, `accent`, `accent2`, `emphasis`, `serif`, `mono`. The theme file (in `packages/brochure-tokens/src/themes/`) is the authoritative list.
+
+## Pagination Affinities
+
+Components declare how they want to paginate. You don't manage page breaks manually except via `<Page>`. The engine does it.
+
+| Component | Default affinity |
+|---|---|
+| `<Heading level=1|2>` | `preferTopOfPage` + `keepWithNext` |
+| `<Heading level=3-6>` | `keepWithNext` |
+| `<Cluster>` | `preferKeepTogether` |
+| `<Stack>` | `breakable` |
+| `<Quote>` | `preferKeepTogether` |
+| `<Stat>`, `<StatRow>` | `atomic` (never split) |
+| `<DataTable>` | `splitWithRepeatedHeaders` (min 3 rows per fragment) |
+| `<Figure>` | `keepWithCaption` |
+| `<Hero>` | `preferStandalone` page |
+| `<Footnote>` | sticks to anchor page |
+
+You can override per-instance with the `affinity` prop on most components: `affinity="breakable"`, `affinity="keepTogether"`, `affinity="hardBreakBefore"`, `affinity="hardBreakAfter"`, `affinity="preferStandalone"`.
+
+## Worked Example 1: Investor One-Pager (Read-Only Mode)
+
+```tsx
+import {
+  Brochure, Cover, Section, Cluster, Stack, Heading, Prose,
+  Stat, StatRow, Figure, Footnote
+} from '@lifeai/brochure-kit';
+
+export const PrtOnePager = () => (
+  <Brochure theme="prt" pageSize="letter" mode="read-only">
+    <Cover>
+      <Heading level={1} variant="accent">Planetary Regenerative Trust</Heading>
+      <Heading level={3} variant="muted">Q3 2026 Fund Update</Heading>
+      <Figure
+        src="prt-cover.jpg"
+        alt="Aerial view of Sky Mesa South Ranch"
+        width="bleed"
+        height="lg"
+        affinity="preferStandalone"
+      />
+    </Cover>
+
+    <Section level={1} id="overview">
+      <Heading level={2}>Fund Overview</Heading>
+      <StatRow count={3}>
+        <Stat value="$200M" label="Target raise" variant="emphasis" />
+        <Stat value="506(c)" label="Reg D structure" />
+        <Stat value="3" label="Investment lanes" />
+      </StatRow>
+      <Cluster>
+        <Heading level={3}>Five Capitals Framework</Heading>
+        <Prose>
+          PRT operates across the Five Capitals: <strong>Natural, Social,
+          Financial, Built, and Human</strong>. Capital flows are gated by
+          place-readiness rather than calendar deadlines<Footnote id="fn1" />.
+        </Prose>
+      </Cluster>
+    </Section>
+
+    <Section level={1} id="lanes">
+      <Heading level={2}>Investment Lanes</Heading>
+      <Prose>
+        Three lanes accept capital with distinct return profiles, hold
+        periods, and risk parameters.
+      </Prose>
+    </Section>
+
+    <Footnote id="fn1" marker="1">
+      Readiness gates are defined per-place by Story of Place methodology and
+      reviewed by an independent stewardship council.
+    </Footnote>
+  </Brochure>
+);
+```
+
+Things to notice:
+- No `<div>` anywhere. Every container is a kit primitive.
+- No styles. Every visual decision is a variant prop.
+- The Figure on the cover declares `width="bleed"` (a kit-named size that resolves to full bleed at PDF time)
+- The Footnote is declared inline and the actual footnote content is at the end; the engine pairs them and places the content on whatever page the anchor lands on.
+- `affinity="preferStandalone"` on the cover Figure ensures the cover image doesn't fight with body content on page 1.
+
+## Worked Example 2: Why-Us Document (Cosmetic Mode)
+
+```tsx
+import {
+  Brochure, Cover, Section, Stack, Cluster, Heading, Prose, Quote,
+  Figure, List, Definition, Divider
+} from '@lifeai/brochure-kit';
+
+export const WhyUsSkyMesa = () => (
+  <Brochure theme="place-fund" pageSize="letter" mode="cosmetic">
+    <Cover>
+      <Heading level={1}>Why Us</Heading>
+      <Heading level={3} variant="muted">Sky Mesa South Ranch · Aspen, Colorado</Heading>
+    </Cover>
+
+    <Section level={1}>
+      <Heading level={2}>The Land Speaks First</Heading>
+      <Prose>
+        Before any framework or fund structure, we begin with the question:
+        what is this place already trying to become? Sky Mesa South Ranch sits
+        in the Roaring Fork watershed, on land with five generations of
+        ranching memory and the deep ecological imprint of high-altitude
+        montane ecosystems.
+      </Prose>
+      <Figure
+        src="sky-mesa-aerial.jpg"
+        alt="Sky Mesa from the eastern ridge"
+        caption="Sky Mesa South Ranch, photographed in late summer 2025"
+        width="lg"
+        height="md"
+      />
+    </Section>
+
+    <Divider variant="rule" />
+
+    <Section level={1}>
+      <Heading level={2}>Five Capitals at Sky Mesa</Heading>
+      <List kind="check">
+        <Definition term="Natural">Watershed restoration, riparian recovery, soil regeneration</Definition>
+        <Definition term="Social">Multi-generational ranching community, Indigenous consultation</Definition>
+        <Definition term="Financial">PRT Lane B with conservation easement layer</Definition>
+        <Definition term="Built">Adaptive reuse of existing ranching infrastructure</Definition>
+        <Definition term="Human">On-site stewardship apprenticeships starting Year 1</Definition>
+      </List>
+    </Section>
+
+    <Section level={1}>
+      <Quote attribution="Bill Reed, AIA LEED">
+        Regeneration is not a technology applied to a place. It is a
+        relationship a place enters into with the people who tend it.
+      </Quote>
+    </Section>
+  </Brochure>
+);
+```
+
+## Worked Example 3: Fact Sheet (Read-Only Mode, Dense)
+
+```tsx
+import {
+  Brochure, Section, Stack, Heading, Prose,
+  DataTable, StatRow, Stat
+} from '@lifeai/brochure-kit';
+
+export const FundFactSheet = () => (
+  <Brochure theme="prt" pageSize="letter" mode="read-only">
+    <Section level={1}>
+      <Heading level={1} variant="accent">PRT Fund Fact Sheet</Heading>
+      <Heading level={3} variant="muted">As of Q3 2026</Heading>
+    </Section>
+
+    <Section level={2}>
+      <Heading level={2}>Performance</Heading>
+      <StatRow count={4}>
+        <Stat value="$185M" label="Committed capital" />
+        <Stat value="$92M" label="Deployed" />
+        <Stat value="12" label="Active places" />
+        <Stat value="8.4%" label="Net IRR (LTM)" variant="emphasis" />
+      </StatRow>
+    </Section>
+
+    <Section level={2}>
+      <Heading level={2}>Capital by Lane</Heading>
+      <DataTable
+        headers={["Lane", "Commitment", "Deployed", "Net IRR"]}
+        rows={[
+          ["A — Production", "$80M", "$48M", "10.2%"],
+          ["B — Place Capital", "$70M", "$32M", "7.8%"],
+          ["C — Stewardship", "$35M", "$12M", "5.4%"],
+        ]}
+        splitPolicy="repeat-headers"
+      />
+    </Section>
+  </Brochure>
+);
+```
+
+## Pre-Flight Checklist (Run before considering output complete)
+
+Before declaring any brochure JSX done, verify:
+
+- [ ] Only kit components in the page tree (no raw `<div>`, `<span>`, etc.)
+- [ ] No `style={{}}` attributes anywhere
+- [ ] No color, rgb, hsl literals in JSX
+- [ ] No `vh`, `vw` viewport units
+- [ ] Every `<Figure>` has `width` and `height`
+- [ ] Exactly one `<Brochure>` root
+- [ ] `theme`, `pageSize`, `mode` all set on `<Brochure>`
+- [ ] All Quotes inside `<Quote>` (not raw HTML)
+- [ ] All flowing text inside `<Prose>`
+- [ ] No empty containers
+- [ ] No nested `<Page>`
+- [ ] Run `pnpm bk-lint <file>` — exit code 0
+
+If any check fails, fix it before completing. The validator is the contract; this skill is the lookup table.
+
+## When Things Get Hard
+
+If you genuinely cannot express something in kit primitives, **stop and surface the gap.** Don't reach for `<div>`. Either:
+
+1. The kit needs a new component (file as a Phase-2 enhancement)
+2. The content is wrong for this format (push back on the user)
+3. There's a kit primitive you missed (re-read this skill)
+
+The first two are honorable. Reaching for `<div>` is not.

package/skills/overnight/SKILL.md

@@ -224,3 +224,7 @@ Provide the advisor with:
 - Max 2 hours per epic — if exceeded, skip and log `TIMEOUT`
 - If credential daemon goes down mid-session: write current state to overnight doc, push, exit gracefully
 - If git push fails: log the failure, attempt rebase, retry once — do not force push
+
+## Capture lessons (exit step)
+
+Before the final verdict line, follow `.rdc/guides/lessons-learned-spec.md` § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one `.rdc/lessons/<YYYY-MM-DD>-overnight-<short-slug>.md` per lesson using the schema in that spec. Set `scope` (`simple` | `architectural`) and `status` (`open`, or `applied` if you shipped the fix in this same run, with the commit linked). Commit the lesson file(s) on `develop` alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.

package/skills/plan/SKILL.md

@@ -250,3 +250,7 @@ Q5. What SSL path?
 ```
 
 Embed all five answers into the infra task description verbatim before handing to the agent.
+
+## Capture lessons (exit step)
+
+Before the final verdict line, follow `.rdc/guides/lessons-learned-spec.md` § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one `.rdc/lessons/<YYYY-MM-DD>-plan-<short-slug>.md` per lesson using the schema in that spec. Set `scope` (`simple` | `architectural`) and `status` (`open`, or `applied` if you shipped the fix in this same run, with the commit linked). Commit the lesson file(s) on `develop` alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.

package/skills/preplan/SKILL.md

@@ -84,3 +84,7 @@ direction if given. If advisor cannot resolve, log and skip to next step.
 - Web search is mandatory — don't just analyze the codebase
 - Keep the doc under 200 lines — concise, not exhaustive
 - Unattended: NEVER pause for input; infer and proceed
+
+## Capture lessons (exit step)
+
+Before the final verdict line, follow `.rdc/guides/lessons-learned-spec.md` § Capture procedure. If this run taught something non-obvious — a first root-cause theory that turned out wrong, the documented/standard path not working, a missing gate or check that cost a round, or a surprising tool/infra behavior — write one `.rdc/lessons/<YYYY-MM-DD>-preplan-<short-slug>.md` per lesson using the schema in that spec. Set `scope` (`simple` | `architectural`) and `status` (`open`, or `applied` if you shipped the fix in this same run, with the commit linked). Commit the lesson file(s) on `develop` alongside the run's other commits, and note "N lessons captured" in your verdict/summary. A run that taught nothing writes nothing — absence is the default.

package/skills/rdc-brochurify/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: rdc-brochurify
+version: 0.1.0
+description: |
+  Orchestrate a Brochurify job from source ingest through delivered PDF, using six parallel-dispatched typed sub-agents and the convergence loop. Use this skill EVERY TIME the user invokes Brochurify directly via "brochurify this", "make a brochure from", "convert this to a brochure PDF", or "rdc:brochurify". Also runs automatically when a job arrives from the broker via monkey_dispatch. The skill enforces D-001 through D-016 from the brochurify DECISIONS-LOG.
+triggers:
+  - "rdc:brochurify"
+  - "brochurify this"
+  - "make a brochure from"
+  - "convert to brochure PDF"
+  - "generate brochure from"
+  - monkey_dispatch payload with skill="brochurify"
+---
+
+# rdc:brochurify Orchestrator
+
+The orchestrator dispatches six waves of typed sub-agents in sequence. Each wave has a clear input contract, an output contract, and a parallelism profile.
+
+## Inputs
+
+The orchestrator accepts a job payload:
+
+```json
+{
+  "job_id": "uuid",
+  "source": {
+    "kind": "url" | "html" | "docx" | "md" | "jsx" | "corpus",
+    "ref": "https://..." | "file:///path/..." | "<html>..." | { corpus_query }
+  },
+  "mode": "read-only" | "cosmetic" | "editorial" | "creative",
+  "theme": "prt" | "place-fund" | "zoen" | "evergreen" | "editorial-neutral",
+  "page_size": "letter" | "a4" | "legal" | "digest" | "tabloid",
+  "brief": "optional natural-language brief for editorial/creative modes",
+  "org_id": "uuid",
+  "user_id": "uuid"
+}
+```
+
+## Outputs
+
+- A PDF in R2 (`brochurify-output` bucket) with a signed URL
+- A completion record in Supabase `brochure_jobs` with:
+  - `pdf_r2_key`, `pdf_url`
+  - `final_grade`, `page_scores` (jsonb array)
+  - `iter` (iteration count reached)
+  - `trace` (jsonb log of all 6 waves × iterations)
+
+## The Six Waves
+
+### Wave 1 — Ingest
+
+**Goal:** Normalize any source into kit-compliant JSX.
+
+**Sub-agent:** `ingest-author` (typed agent with the `lifeai-brochure-author` skill loaded)
+
+**Inputs:** raw source from job payload
+**Outputs:** `working/draft.jsx` (kit-compliant JSX) + `working/assets/` (extracted images)
+
+**Per-source handling:**
+- `url` — fetch via Playwright (whitelist) or structural-summary mode (open web)
+- `html` — direct ingest, strip scripts/iframes/ads
+- `docx` — pandoc to HTML, then ingest
+- `md` — render to HTML, then ingest
+- `jsx` — pre-built input; skip to validate
+- `corpus` — Creative mode only; corpus reader + Author-Mode-* sub-agent
+
+**Failure mode:** if ingest cannot map content to kit primitives, raise a structured error with the unmappable content range and ask the user to clarify.
+
+### Wave 2 — Validate
+
+**Goal:** Confirm the JSX passes static and structural validation before render.
+
+**Sub-agent:** none — runs `pnpm bk-lint working/draft.jsx` directly
+
+**Behavior:**
+- If pass → Wave 3
+- If fail → return errors to Wave 1 agent, retry once
+- If fail twice → escalate to orchestrator: try a different ingest strategy, page-size change, or surface to user
+
+**Every failure here writes to `enhancement-log.jsonl`** with:
+- `src: "ingest-author"`
+- `fail_layer: "static"` or `fail_layer: "structural"`
+- The specific rule violated
+
+### Wave 3 — Render
+
+**Goal:** Produce a first-iteration PDF and per-page screenshots.
+
+**Sub-agent:** none — runs Paged.js via Playwright headless
+
+**Process:**
+1. Build the kit + theme bundle into `working/bundle.html`
+2. Open with Paged.js polyfill
+3. Wait for `pagedjs:rendered` event
+4. Snapshot DOM after pagination → `working/paged.html`
+5. Per-page screenshot at 150 DPI → `working/pages/page-{N}.png`
+6. Render to PDF → `working/iter-{i}.pdf`
+
+**Failure mode:** if Paged.js fails to converge (rare; usually a kit bug), fall back to print-to-PDF without paged-media polyfill, flag as low-quality iteration, continue.
+
+### Wave 4 — Grade (Vision, Parallel)
+
+**Goal:** Score each page against the 7-dimension rubric.
+
+**Sub-agent:** `vision-grader` — dispatched **once per page in parallel**.
+
+**Per-page inputs:**
+- The page screenshot
+- The source JSX for that page (extracted by walking the paginated DOM)
+- The rubric (R1-R7 with weights and target ranges)
+
+**Per-page outputs (structured):**
+```json
+{
+  "page": 3,
+  "grade": 82,
+  "dimensions": {
+    "R1_margin_integrity": 95,
+    "R2_bottom_slack": 70,
+    "R3_heading_breathing": 85,
+    "R4_widows_orphans": 100,
+    "R5_image_placement": 80,
+    "R6_table_integrity": 100,
+    "R7_text_density": 75
+  },
+  "issues": [
+    {"dim": "R2", "desc": "tail gap 1.1in below last paragraph", "fix_hint": "compress paragraph or push next-page content"}
+  ]
+}
+```
+
+**Document grade:** `min(page_grades)` per D-013.
+
+**Convergence:**
+- Grade ≥ 75 → Wave 6 (Deliver)
+- Grade < 75 AND iter < 10 → Wave 5 (Patch)
+- iter = 10 → Wave 6 with `partial=true` flag
+
+### Wave 5 — Patch (Parallel)
+
+**Goal:** Produce a corrected JSX that addresses the issues from Wave 4.
+
+**Sub-agent:** `patch-author` — dispatched **once per low-graded page in parallel**.
+
+**Mode restrictions:**
+- `read-only` — only break, sizing, spacing patches allowed
+- `cosmetic` — read-only patches + image resize, caption compression, paragraph splits at sentence boundaries
+- `editorial` — cosmetic + paragraph rewrites within 15% character or 25% word reduction
+- `creative` — editorial + free composition (the authoring sub-agent fully active)
+
+**Patch types:**
+- `force-break-before` — insert page break before an element
+- `adjust-spacing` — change Stack/Cluster gap variant
+- `resize-figure` — change Figure width/height variant
+- `compress-paragraph` — drop or merge a sentence (cosmetic+ only)
+- `rewrite-paragraph` — full rewrite (editorial+ only)
+- `rebalance-cluster` — split a Cluster onto two pages
+- `change-affinity` — adjust an affinity prop
+
+Each patch is applied to `working/draft.jsx`, the validator re-runs, then Wave 3 renders again.
+
+**Edit tracking (editorial mode):** every paragraph rewrite is logged with before/after to `working/edits.jsonl`. The completion record includes this log.
+
+### Wave 6 — Deliver
+
+**Goal:** Final PDF, signed URL, completion record.
+
+**Process:**
+1. Upload final PDF to R2 with key `brochurify-output/{org_id}/{job_id}.pdf`
+2. Generate 7-day signed URL
+3. Update `brochure_jobs` row:
+   ```sql
+   UPDATE brochure_jobs SET
+     status = 'completed',
+     iter = $iter,
+     current_grade = $grade,
+     page_scores = $pageScoresJson,
+     pdf_r2_key = $r2Key,
+     pdf_url = $signedUrl,
+     completed_at = now()
+   WHERE id = $jobId;
+   ```
+4. Send SSE event `{type:"complete", url, grade, iter}` to broker
+5. Append enhancement log entries from this run to `enhancement-log.jsonl`
+
+## Trace Logging
+
+Every wave appends to `working/trace.jsonl`:
+
+```jsonl
+{"ts":"...","wave":1,"agent":"ingest-author","iter":1,"status":"start"}
+{"ts":"...","wave":1,"agent":"ingest-author","iter":1,"status":"complete","blocks":127}
+{"ts":"...","wave":2,"iter":1,"status":"complete","errors":0}
+{"ts":"...","wave":3,"iter":1,"status":"complete","pages":8,"render_ms":2340}
+{"ts":"...","wave":4,"iter":1,"page":1,"grade":85,"status":"complete"}
+{"ts":"...","wave":4,"iter":1,"page":2,"grade":68,"status":"complete","issues":2}
+...
+```
+
+This trace is stored in `brochure_jobs.payload.trace` for forensic review.
+
+## Cost Profile
+
+- **Wave 1:** 1 sub-agent call (one model invocation)
+- **Wave 2:** 0 model calls (deterministic validator)
+- **Wave 3:** 0 model calls (deterministic render)
+- **Wave 4:** N parallel model calls (N = page count)
+- **Wave 5:** M parallel model calls (M = pages needing patch; usually 0-3)
+- **Wave 6:** 0 model calls
+
+Typical 8-page brochure, 2 iterations: ~1 + 16 + 4 = ~21 model calls total. All on Max plan. Zero per-job API cost.
+
+## Hard Caps
+
+- **Max iterations:** 10 (per D-006)
+- **Max wall-clock:** 15 minutes per job
+- **Max page count:** 50 (anything larger is split into multiple jobs)
+- **Max source size:** 5MB raw HTML, 25MB docx, 50MB total assets
+
+Exceeding any cap → job fails with structured error; no partial billing.
+
+## Failure Recovery
+
+| Failure | Recovery |
+|---|---|
+| Validator fails repeatedly | Try page-size change (Letter → Legal → Digest) before failing job |
+| Vision agent disagrees with itself | Lock grade after 3 iterations of same page; mark "best-effort" |
+| Convergence not reached at iter=10 | Ship best version, flag low-graded pages, log to enhancement |
+| Paged.js render fails | Fall back to direct PDF; flag low-quality iteration |
+| R2 upload fails | Retry 3x then fall back to Supabase storage URL |
+
+## When to invoke
+
+Direct user invocation: `rdc:brochurify <source-url-or-path> [--mode] [--theme] [--page-size]`
+
+Programmatic invocation: a `monkey_dispatch` job arriving with `skill="brochurify"` and the job payload as `args`.
+
+Either path executes the same 6-wave loop. Direct user invocation also returns the trace and the PDF URL to the calling session.