@lifeaitools/rdc-skills 0.14.0 → 0.16.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "rdc",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "RDC typed-agent dispatch skill suite for Claude Code — plan, build, review, overnight unattended builds with work-item tracking and TDD enforcement.",
   "author": {
     "name": "LIFEAI",
@@ -954,6 +954,49 @@
       "enabled_default": true,
       "codeflow_required": false
     },
+    "housekeeping": {
+      "name": "housekeeping",
+      "slash": "rdc:housekeeping",
+      "category": "reporting",
+      "usage": "rdc:housekeeping [--fix]",
+      "args": {
+        "positional": [],
+        "flags": [
+          {
+            "name": "--fix",
+            "type": "boolean",
+            "default": false,
+            "description": "Auto-remediate safe issues (scaffold CLAUDE.md, fix PUBLISH.md URLs, create missing dirs)"
+          }
+        ]
+      },
+      "requires": [
+        "supabase",
+        "clauth",
+        "coolify",
+        "git"
+      ],
+      "produces": [
+        ".rdc/reports/"
+      ],
+      "default_model": "sonnet",
+      "triggers": [
+        "weekly maintenance",
+        "housekeeping",
+        "directory structure audit",
+        "verify all apps",
+        "check repo health",
+        "maintenance audit"
+      ],
+      "follows": [],
+      "leads_to": [
+        "review"
+      ],
+      "sandbox_aware": true,
+      "output_contract": "guides/output-contract.md",
+      "enabled_default": true,
+      "codeflow_required": false
+    },
     "status": {
       "name": "status",
       "slash": "rdc:status",

package/guides/lessons-learned-spec.md

@@ -0,0 +1,153 @@
+---
+mdk_schema_version: "1.0"
+doc_type: guide
+system: claude-workflow
+status: active
+owner: infrastructure
+created: 2026-06-08
+last_reviewed: 2026-06-08
+source_of_truth: true
+supersedes: []
+depends_on:
+  - ".claude/rules/architectural-change-approval.md"
+  - ".rdc/guides/output-contract.md"
+tags: [rdc, lessons-learned, skills, housekeeping, adaptive]
+---
+
+# Lessons-Learned Capture & Triage — Spec
+
+> Auto-referenced by long-running `rdc:*` skills at exit, and by `rdc:housekeeping` for triage.
+> Goal: make the fleet an **interactive adaptive modeler** — every run that teaches us
+> something writes it down, and the weekly housekeeping pass turns those lessons into
+> actual fixes (rules, skill docs, work_items).
+
+---
+
+## Why this exists
+
+Lessons learned during a run (a non-obvious infra trap, a wrong assumption, a missing
+gate, a tooling gotcha) used to survive only if someone hand-wrote a memory. This system
+makes capture a **routine exit step** of every long skill, and triage a **routine phase**
+of the weekly housekeeping. Capture is cheap and append-only; triage is where fixes happen.
+
+Precedent: brochurify's `rdc-extract-verifier-rules` already does read-log → cluster →
+propose-rule for one domain. This generalizes that pattern fleet-wide.
+
+---
+
+## Storage — directory of per-lesson files
+
+Lessons live in **`.rdc/lessons/`**, one markdown file per lesson:
+
+```
+.rdc/lessons/<YYYY-MM-DD>-<skill>-<short-slug>.md
+```
+
+- One file per lesson (NOT a single appended file) so parallel agents finishing at the
+  same time never collide on one file in git.
+- `<skill>` is the capturing skill (`build`, `deploy`, `overnight`, `fixit`, `plan`,
+  `preplan`, `review`, `release`, `collab`).
+- `<short-slug>` is 2–4 kebab words naming the lesson.
+
+A run that taught nothing writes nothing — **absence is the default**. Only write a lesson
+when something was genuinely learned (see § When to capture).
+
+---
+
+## Lesson file schema
+
+```markdown
+---
+id: <YYYY-MM-DD>-<skill>-<short-slug>
+date: "<YYYY-MM-DD>"
+skill: build | deploy | overnight | fixit | plan | preplan | review | release | collab
+session: <session-id or short ref>
+scope: simple | architectural          # triage routing — see § Scope gate
+status: open | triaged | applied | wont-fix
+area: infra | skill | guide | rule | schema | ui | content | other
+links:
+  commits: []                          # SHAs that relate to the lesson
+  memory: []                           # memory file slugs, if a memory was also written
+  work_items: []                       # work_item UUIDs spawned during triage
+---
+
+## What happened
+<one paragraph — the concrete situation, with evidence (exit code, file:line, command)>
+
+## Root cause
+<one paragraph — the evidenced cause, not a guess>
+
+## The fix / rule
+<what should change so this never recurs: a rule edit, skill-doc line, code change,
+or a check. If already applied in the same run, say so and link the commit.>
+```
+
+`scope` is the single most important field — it routes triage:
+
+- **`simple`** — a doc line, a one-file fix, a config tweak, a clarifying sentence in a
+  skill, a missing grep guard. Housekeeping applies these directly.
+- **`architectural`** — anything matching `.claude/rules/architectural-change-approval.md`
+  (rule/CLAUDE.md/ARCHITECTURE.md edits, cross-cutting refactors, schema reshape, public
+  API/MCP changes, skill-contract changes affecting multiple skills). Housekeeping does
+  NOT apply these; it surfaces them via `AskUserQuestion` for explicit approval first.
+
+When unsure, mark `architectural`.
+
+---
+
+## When to capture (at skill exit)
+
+Write a lesson when ANY of these were true during the run:
+
+1. A root cause turned out to be different from the first theory (a wrong assumption).
+2. The standard/documented path didn't work and you had to do something non-obvious.
+3. A gate, check, or doc was missing and its absence cost a round.
+4. A tool/infra behaved in a surprising way (exit codes, caching, serve/PM2/webhook quirks).
+5. A hook blocked you and the block revealed a real gap (not just your mistake).
+
+Do NOT capture: routine success, your own one-off typo, anything already fully documented
+in a rule/guide. If a durable user preference or correction was involved, also write a
+`memory` (this spec and memory are complementary — link them).
+
+---
+
+## Capture procedure (the exit step long skills call)
+
+At the end of a long skill run, before the final verdict line:
+
+1. Decide if anything qualifies (§ When to capture). If not, write nothing and move on.
+2. For each lesson, write `.rdc/lessons/<date>-<skill>-<slug>.md` using the schema above.
+   Set `status: open` (or `applied` if you already shipped the fix in this same run, with
+   the commit linked).
+3. Set `scope` honestly (`simple` vs `architectural`).
+4. Commit the lesson file(s) on `develop` alongside the run's other commits.
+5. Mention in the verdict/summary that N lessons were captured.
+
+---
+
+## Triage procedure (rdc:housekeeping, weekly)
+
+`rdc:housekeeping` adds a **Lessons triage** phase:
+
+1. Read all `.rdc/lessons/*.md` with `status: open`.
+2. Cluster by `area` + root-cause similarity (dedupe repeats into one fix).
+3. For each cluster:
+   - `scope: simple` → apply the fix directly (rule line, skill-doc edit, config, guard),
+     commit it, set the lesson(s) `status: applied` and link the commit.
+   - `scope: architectural` → do NOT edit. Present the issue + options via
+     `AskUserQuestion` (per `architectural-change-approval.md`). On approval, apply via the
+     correct lifecycle (rdc-skills tag/push for skills; cited commit for rules) and set
+     `status: applied`. If deferred, set `status: triaged` and spawn a `work_item`.
+   - Not worth fixing → `status: wont-fix` with a one-line reason.
+4. Summarize in the housekeeping report: captured / applied / escalated / deferred counts.
+
+Lessons are never silently deleted — `applied` and `wont-fix` files stay as the audit trail.
+
+---
+
+## Skills that capture (the long-running set)
+
+`build` · `deploy` · `overnight` · `fixit` · `plan` · `preplan` · `review` · `release` · `collab`
+
+Each references this spec from a final "§ Capture lessons" step. A Stop-hook backstop warns
+when one of these skills ends a run with findings but no new `.rdc/lessons/` file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lifeaitools/rdc-skills",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "RDC typed-agent dispatch skill suite for Claude Code - plan, build, review, overnight builds",
   "keywords": [
     "claude-code",

package/scaffold/templates/brochure-studio-default.html

@@ -0,0 +1,70 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8"/>
+<title>{{TITLE}}</title>
+<link rel="preconnect" href="https://fonts.googleapis.com"/>
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin/>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Source+Serif+4:ital,opsz,wght@0,8..60,300..900;1,8..60,300..900&family=Hanken+Grotesk:ital,wght@0,300..900;1,300..900&display=swap"/>
+<style>
+/* TOKENS_INJECT */
+@page { size: letter; margin: 0.6in 0.7in; }
+:root {
+  --loam-800:#2b2218; --loam-700:#3d2f1f; --loam-600:#5c4628;
+  --loam-300:#bda079; --loam-200:#d9c4a4; --loam-100:#ece0c8;
+  --moss-700:#4f5a37; --ochre-700:#97772c; --ochre-100:#f4e9d4;
+  --linen-50:#faf8f5; --linen-100:#f4edde;
+  --char-700:#2b2e26; --char-500:#4d5145; --char-400:#6d7164;
+  --ff-display:'Source Serif 4', Georgia, serif;
+  --ff-sans:'Hanken Grotesk', system-ui, sans-serif;
+}
+* { box-sizing: border-box; }
+html, body { background: white; }
+body {
+  margin: 0; font-family: var(--ff-sans); font-size: 10.5pt; line-height: 1.55;
+  color: var(--char-700);
+  -webkit-print-color-adjust: exact; print-color-adjust: exact;
+}
+h1, h2, h3, h4 { font-family: var(--ff-display); color: var(--loam-800); font-weight: 600; letter-spacing: -0.005em; }
+h1 { font-size: 28pt; line-height: 1.15; margin: 0 0 0.4em; }
+h2 { font-size: 18pt; line-height: 1.2; margin: 1.8em 0 0.4em; padding-bottom: 0.25em; border-bottom: 1px solid var(--loam-200); }
+h3 { font-size: 13pt; margin: 1.4em 0 0.3em; color: var(--loam-700); }
+p  { margin: 0 0 0.7em; }
+ul, ol { margin: 0 0 0.8em 1.1em; padding: 0; }
+li { margin: 0.15em 0; }
+code { font-family: 'JetBrains Mono', ui-monospace, monospace; font-size: 9pt; background: var(--linen-100); padding: 0.05em 0.3em; border-radius: 2px; }
+pre { background: var(--linen-100); padding: 0.7em 0.9em; border-radius: 4px; overflow-wrap: anywhere; font-size: 8.5pt; }
+img { max-width: 100%; height: auto; display: block; margin: 0.8em auto; }
+strong { color: var(--loam-800); }
+em { color: var(--char-500); }
+
+.cover { page-break-after: always; min-height: 9in; display: flex; flex-direction: column; justify-content: space-between; padding: 0.3in 0; }
+.cover-eyebrow { font-family: var(--ff-sans); font-size: 9pt; letter-spacing: 0.15em; text-transform: uppercase; color: var(--ochre-700); }
+.cover-title { font-family: var(--ff-display); font-size: 44pt; line-height: 1.05; color: var(--loam-800); margin: 0.2em 0 0.4em; }
+.cover-sub { font-family: var(--ff-display); font-style: italic; font-size: 14pt; color: var(--loam-600); max-width: 5.5in; }
+.cover-foot { font-size: 8.5pt; color: var(--char-400); border-top: 1px solid var(--loam-200); padding-top: 0.4em; display: flex; justify-content: space-between; }
+
+.brochure-section { page-break-before: always; }
+.brochure-section:first-of-type { page-break-before: auto; }
+
+@media screen {
+  body { max-width: 7.1in; margin: 0.6in auto; padding: 0 0.7in; }
+}
+</style>
+</head>
+<body>
+  <header class="cover">
+    <div>
+      <div class="cover-eyebrow">Brochure</div>
+      <h1 class="cover-title">{{TITLE}}</h1>
+      <div class="cover-sub">Composed by rdc:brochure</div>
+    </div>
+    <div class="cover-foot">
+      <span>RDC</span>
+      <span>{{TITLE}}</span>
+    </div>
+  </header>
+
+  {{SECTIONS}}
+</body>
+</html>

package/skills/build/SKILL.md

@@ -401,3 +401,7 @@ NEVER run pnpm build or pnpm turbo. Use npx vitest run only.
 - Unattended: max 2 retries per task before escalating to advisor
 - Every Agent() dispatch: `model: <routed>` + `max_turns: 70` + `isolation: "worktree"` — non-negotiable. Model is chosen per task per the routing table in Step 7: Sonnet 4.6 for updates/edits, Opus 4.6 for harder coding, Opus 4.8 for design/innovative thought (CS 2.0, brand/UX, architecture). Supervisor logs `model=<chosen> reason=<phrase>` per agent. Exception: validator agent in Step 10 omits isolation; validator model stays `claude-sonnet-4-6` (verification, not generation).
 - Finding an existing file is NOT task completion — verify it satisfies the spec
+
+## 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>-build-<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/collab/SKILL.md

@@ -215,3 +215,7 @@ If Dave types in this terminal during a turn:
 - Treat it as an override injected into the current task
 - Acknowledge it in your `chitchat_reply` response
 - If it changes direction mid-task, note what you stopped and why
+
+## 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>-collab-<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/deploy/SKILL.md

@@ -372,6 +372,10 @@ Fields:
 
 When diagnosing a broken deploy in Mode 3: query `coolify_events` FIRST before re-running the deploy — the most recent event row tells you whether the previous deploy actually triggered, whether it failed, and how long it ran. Faster than checking the Coolify UI.
 
+## 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>-deploy-<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.
+
 ## References
 
 - Type-specific checklists + DNS tree + gate commands: `docs/runbooks/coolify-deploy-checklist.md`

package/skills/fixit/SKILL.md

@@ -159,3 +159,7 @@ Report: what was fixed, file(s) changed, commit hash. One sentence.
 - Never run `pnpm build` — not needed for a fixit
 - If scope expands mid-fix: stop, escalate to rdc:build, don't finish under fixit
 - Marker file must be cleaned up whether fix succeeds or escalates
+
+## 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>-fixit-<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/housekeeping/SKILL.md

@@ -0,0 +1,176 @@
+---
+name: rdc:housekeeping
+description: "Usage `rdc:housekeeping [--fix]` — Weekly maintenance audit: directory structure verification, PUBLISH.md URL validation, CLAUDE.md freshness, orphan detection, places compliance, and stale version scan. Produces `.rdc/reports/YYYY-MM-DD-housekeeping.md`. With `--fix`, auto-remediate safe issues."
+---
+
+> **⚠️ OUTPUT CONTRACT (READ FIRST):** `guides/output-contract.md`
+> Checklist-only output. No tool-call narration. No raw MCP/JSON/log dumps.
+> One checklist upfront, updated in place, shown again at end with a 1-line verdict.
+
+> If dispatching subagents or running as a subagent: read `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md` first (fallback: `{PROJECT_ROOT}/.rdc/guides/agent-bootstrap.md`), then `{PROJECT_ROOT}/.rdc/guides/engineering-behavior.md` (fallback: `{PROJECT_ROOT}/.rdc/guides/engineering-behavior.md`).
+
+> **Sandbox contract:** This skill honors `RDC_TEST=1` per `guides/agent-bootstrap.md` § RDC_TEST Sandbox Contract. Destructive external calls short-circuit under the flag.
+
+
+# rdc:housekeeping — Weekly Maintenance Audit
+
+## When to Use
+- Weekly maintenance (Sunday or session start)
+- After large batch of new apps/packages/sites added
+- Before monthly `workspace-intelligence-audit`
+- When disoriented about repo health
+- Called by `rdc:overnight` as a pre-flight if `--housekeeping` flag set
+
+## Arguments
+- `rdc:housekeeping` — audit only, report issues
+- `rdc:housekeeping --fix` — auto-remediate safe issues (scaffold missing CLAUDE.md, fix PUBLISH.md URLs, create missing tracker dirs)
+
+## Procedure
+
+### 1. Directory Structure Verification
+
+Scan every deployable target for required files:
+
+```
+For each dir in apps/*, sites/*, models/*, workers/*, mcp-servers/*, packages/*:
+```
+
+| Target Type | Required Files |
+|-------------|---------------|
+| Next.js app (`apps/*` with next.config) | `package.json`, `CLAUDE.md`, `PUBLISH.md`, `tsconfig.json` |
+| Vite SPA (`models/*`, `sites/*` with vite.config) | `package.json`, `CLAUDE.md`, `PUBLISH.md`, `vite.config.js` or `.ts`, `dist/` |
+| Static site (`sites/*` no vite/next) | `index.html`, `CLAUDE.md`, `PUBLISH.md` |
+| Worker (`workers/*`) | `package.json`, `CLAUDE.md`, `wrangler.toml`, `src/index.ts` |
+| MCP server (`mcp-servers/*`) | `package.json`, `CLAUDE.md`, `ARCHITECTURE.md`, `PUBLISH.md` |
+| Package (`packages/*`) | `package.json`, `CLAUDE.md`, `tsconfig.json`, `src/` |
+
+Report: `PASS` / `MISSING: <file list>` per target.
+
+**With `--fix`:** Scaffold missing CLAUDE.md files using package.json description + src/ inspection (same pattern as the 2026-06-08 audit). Do NOT auto-create PUBLISH.md (requires domain knowledge).
+
+### 2. PUBLISH.md URL Validation
+
+For every PUBLISH.md that exists:
+
+1. Parse frontmatter: extract `entity_slug`, `environments`, `status`
+2. Query `app_deployments` for the slug:
+   ```sql
+   SELECT app_slug, environment, url, host_type FROM app_deployments WHERE app_slug = '<slug>';
+   ```
+3. Cross-reference: any URL mentioned in the PUBLISH.md body/notes/SURFACE blocks must match the `app_deployments.url` for that environment
+4. Check domain convention compliance (per `.claude/rules/domain-conventions.md`):
+   - Real estate projects → `*.dev.place.fund` (dev) / `*.place.fund` (prod)
+   - Class-A brands → `dev.<brand>` (dev) / `<brand>` (prod)
+   - Internal tools → `*.dev.regendevcorp.com` (dev) / `*.regendevcorp.com` (prod)
+5. Flag mismatches: `MISMATCH: PUBLISH.md says <X>, app_deployments says <Y>`
+
+**With `--fix`:** Update PUBLISH.md URLs to match app_deployments (the DB is the source of truth).
+
+### 3. CLAUDE.md Freshness Check
+
+For each package with a CLAUDE.md:
+1. Get CLAUDE.md last modified date
+2. Get latest src/ modification date
+3. If src/ changed after CLAUDE.md by >30 days, flag: `STALE: CLAUDE.md older than src/ by <N> days`
+4. Check if new exports were added to `src/index.ts` that aren't mentioned in CLAUDE.md
+
+**With `--fix`:** Re-scaffold CLAUDE.md from current src/ state.
+
+### 4. Package.json Health
+
+For each package:
+1. Check `version` — flag `0.0.0` or `0.1.0` on packages with >5 src files as potentially stale
+2. Check `exports` field exists (required for monorepo packages)
+3. Check `name` matches `@regen/<dir-name>` or `@lifeai/<dir-name>` convention
+4. Flag name mismatches between directory and package.json
+
+### 5. Places Compliance
+
+For each directory under `places/`:
+1. Check PLACE.md exists with valid frontmatter (`schema_version`, `prt_slug`, `project_type`, `research_status`)
+2. Check HISTORY.md exists (required for real-estate project types per `.claude/rules/history-md-convention.md`)
+3. Check `corpus/INDEX.md` exists
+4. Check `tracker/` directory exists with DECISIONS.md + MILESTONES.md
+5. Check `artifacts/` directory exists
+
+**With `--fix`:** Scaffold missing PLACE.md from HISTORY.md frontmatter, create missing tracker/corpus dirs.
+
+### 6. Orphan Detection
+
+1. **Empty/stub directories:** Any target dir with <3 files and no package.json → flag for removal
+2. **Standalone repo drift:** Check `C:/Dev/` for repos that have monorepo copies and compare versions
+3. **Dead app_deployments rows:** Query for slugs with `status='down'` or `status='broken'`
+
+### 7. Stale Coolify Apps on .dev URLs
+
+Query Coolify API for apps serving `.dev.*` URLs — these should be on PM2 per domain conventions:
+```bash
+TOKEN=$(curl -s http://127.0.0.1:52437/v/coolify-api)
+curl -s -H "Authorization: Bearer $TOKEN" "https://deploy.regendevcorp.com/api/v1/applications" | \
+  python3 -c "import sys,json; [print(a['name'], a.get('fqdn','')) for a in json.load(sys.stdin) if '.dev.' in (a.get('fqdn',''))]"
+```
+
+Flag any .dev apps still on Coolify.
+
+### 8. Media CDN Hotlink Allowlist
+
+Read `workers/media-cdn/src/index.ts` ALLOWED_SUFFIXES. Cross-reference against all class-A brand domains from `app_deployments`:
+```sql
+SELECT DISTINCT url FROM app_deployments WHERE host_type = 'coolify' AND url NOT LIKE '%.place.fund' AND url NOT LIKE '%.regendevcorp.com';
+```
+
+Flag any class-A domain NOT in ALLOWED_SUFFIXES.
+
+**With `--fix`:** Add missing suffixes to ALLOWED_SUFFIXES and redeploy the worker.
+
+### 9. Report
+
+Write to `.rdc/reports/YYYY-MM-DD-housekeeping.md`:
+
+```markdown
+# Housekeeping Report — YYYY-MM-DD
+
+## Summary
+| Check | Pass | Fail | Fixed |
+|-------|------|------|-------|
+
+## Directory Structure
+<table of targets with issues>
+
+## PUBLISH.md URL Validation
+<table of mismatches>
+
+## CLAUDE.md Freshness
+<stale entries>
+
+## Package Health
+<version/exports/naming issues>
+
+## Places Compliance
+<incomplete places>
+
+## Orphans
+<empty dirs, dead deployments>
+
+## Media CDN
+<missing allowlist entries>
+
+## Verdict: CLEAN / HAS_ISSUES
+```
+
+## Lessons triage (weekly)
+
+Read all `.rdc/lessons/*.md` with `status: open` (schema + procedure: `.rdc/guides/lessons-learned-spec.md` § Triage procedure). Cluster by `area` + root-cause similarity (dedupe repeats into one fix). For each cluster:
+
+- `scope: simple` → apply the fix directly (rule line, skill-doc edit, config, guard), commit it, set the lesson(s) `status: applied` with the commit linked.
+- `scope: architectural` → do NOT edit. Present the issue + options via `AskUserQuestion` (per `.claude/rules/architectural-change-approval.md`). On approval, apply via the correct lifecycle (rdc-skills tag/push for skills; cited commit for rules) and set `status: applied`. If deferred, set `status: triaged` and spawn a `work_item`.
+- Not worth fixing → `status: wont-fix` with a one-line reason.
+
+Never delete lesson files — `applied` and `wont-fix` stay as the audit trail. Report captured / applied / escalated / deferred counts in the housekeeping report.
+
+## Rules
+- Never run `pnpm build` — not needed for this audit
+- Never modify app_deployments — the DB is the source of truth; PUBLISH.md conforms to it
+- The `--fix` flag only auto-remediates safe issues (CLAUDE.md scaffold, missing dirs, URL alignment)
+- Architectural changes (name mismatches, dead package removal) are always flagged, never auto-fixed
+- This skill is read-heavy, write-light — most runs are audit-only

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.

package/skills/rdc-extract-verifier-rules/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: rdc-extract-verifier-rules
+version: 0.1.0
+description: |
+  Read recent enhancement-log entries, cluster failures by pattern, generate candidate verifier rules, test them against the known-good corpus and the failure corpus, and propose pull requests adding the highest-confidence rules to forbidden-patterns.json. Use this skill on a nightly cadence (3 AM PT), or manually when the user says "extract verifier rules", "promote enhancement log", "what new rules should we add", or after a significant brochure run produced many failures.
+triggers:
+  - "rdc:extract-verifier-rules"
+  - "extract verifier rules"
+  - "promote enhancement log"
+  - "what new rules should we add"
+  - "verifier corpus update"
+  - nightly cron at 3:00 AM PT
+---
+
+# rdc:extract-verifier-rules
+
+The self-learning loop. The verifier corpus is the moat (per `DECISIONS-LOG.md` D-009). This skill is how the corpus grows.
+
+## What it does
+
+1. Read `enhancement-log.jsonl` entries since last run timestamp
+2. Cluster entries by fingerprint similarity + reason text
+3. For each cluster with `N >= 3` occurrences:
+   - Generate a candidate regex or AST pattern
+   - Test the pattern against the **known-good corpus** (last 100 successful brochures) for false positives
+   - Test the pattern against the **failure cluster** for recall
+   - If false-positive rate = 0 AND recall ≥ 80%, mark as `propose`
+4. For each `propose` candidate:
+   - Open a PR on `regen-root` adding the rule to `verifiers/forbidden-patterns.json`
+   - Auto-merge if confidence ≥ 95% AND a maintainer's auto-merge flag is enabled
+   - Otherwise, await human review
+5. Write a markdown summary to `.rdc/reports/verifier-{YYYY-MM-DD}.md`
+
+## Cluster algorithm
+
+Two-stage clustering:
+
+**Stage 1 — Fingerprint clustering:**
+- Each enhancement-log entry has an `input_fingerprint` (sha256 of the offending JSX block)
+- Entries with identical fingerprints cluster trivially (same exact mistake)
+
+**Stage 2 — Semantic clustering:**
+- For unique fingerprints, embed the `reason` and `pattern` fields with `@xenova/transformers` (384-dim, local — no API)
+- Cosine similarity ≥ 0.85 → same cluster
+- Use HDBSCAN with min_samples=3 to identify real clusters vs. noise
+
+## Candidate rule generation
+
+For each cluster, generate one of:
+
+### Regex candidate
+- Take all `pattern` strings in the cluster
+- Find common substring or template
+- Generalize literal values to character classes
+- Validate the regex is well-formed and not catastrophic
+
+Example:
+```
+Cluster patterns:
+  <div className="flex flex-col gap-4">
+  <div className="flex flex-col gap-6">
+  <div className="flex flex-row items-center">
+
+Generated regex:
+  <div[^>]*className="[^"]*\\bflex\\b
+```
+
+### AST candidate
+- For cluster entries with rich AST context, build an AST query string
+- Test with @typescript-eslint/parser
+
+Example:
+```
+AST candidate:
+  JSXOpeningElement[name.name='div'] > JSXAttribute[name.name='className'] CallExpression[callee.name='clsx']
+```
+
+## False-positive check
+
+Run the candidate against the known-good corpus:
+- The 12 Phase 1 reference brochures
+- All design-partner brochures with `final_grade >= 85`
+- Any brochure tagged `corpus:reference` in Supabase
+
+If the candidate matches any known-good output → reject the candidate. False positives in the verifier corpus are unacceptable because they break working flows.
+
+## Recall check
+
+Run the candidate against the failure cluster:
+- Must match ≥ 80% of cluster entries
+- Below 80%, the candidate is too specific; widen and retry
+
+## PR generation
+
+For each promoted candidate, create a PR on `LIFEAI/regen-root`:
+
+```
+Title: [verifier-corpus] Add rule FP0{N} — {short description}
+
+Body:
+This rule was generated by rdc:extract-verifier-rules on {date}.
+
+**Cluster size:** {N} occurrences over {time span}
+**False positive rate:** {rate}
+**Recall:** {percent}
+
+**Sample failures:**
+{3-5 example enhancement-log entries}
+
+**Generated rule:**
+```json
+{rule JSON}
+```
+
+**Reviewer checklist:**
+- [ ] Verify the rule doesn't match any known-good brochure
+- [ ] Verify the suggested fix is reasonable
+- [ ] Confirm severity level
+- [ ] Confirm category
+
+Auto-merging: {yes/no based on confidence}
+```
+
+## Auto-merge policy
+
+Auto-merge if **all** are true:
+- False-positive rate = 0
+- Recall ≥ 95%
+- Cluster size ≥ 10
+- The rule pattern is a strict subset of an existing pattern (not a fundamentally new category)
+- A maintainer's auto-merge flag is enabled in `.rdc/config.json`
+
+Otherwise, await human review.
+
+## Output: nightly report
+
+`.rdc/reports/verifier-{YYYY-MM-DD}.md`:
+
+```markdown
+# Verifier Corpus Update — {date}
+
+## Summary
+
+- Enhancement log entries since last run: {N}
+- Clusters identified: {C}
+- Rules proposed: {R}
+- Rules auto-merged: {A}
+- Rules awaiting review: {W}
+
+## Top clusters
+
+| Cluster | Size | Pattern | Status |
+|---|---|---|---|
+| ...
+
+## Open PRs
+
+- #{N}: FP0{X} — {description}
+- ...
+
+## False-positive rejections
+
+Candidates that failed the known-good test:
+- {summary}
+
+## Corpus growth
+
+- Total rules in forbidden-patterns.json: {before} → {after}
+- Total component-allowlist entries: unchanged
+- Pagination rules: unchanged
+```
+
+## Manual invocation
+
+A maintainer can run this skill manually after a significant brochure run to immediately promote lessons learned:
+
+```
+rdc:extract-verifier-rules --since "2026-05-27" --auto-merge=false
+```
+
+The `--auto-merge=false` flag forces human review on all proposals regardless of confidence.
+
+## Why this matters
+
+The verifier corpus is the asset. Anyone can copy the kit. Anyone can copy the ESLint plugin. **Replicating 12 months of customer-tested failure patterns is the moat.** This skill is how that moat compounds. Every brochure run feeds it. Every nightly run grows it.
+
+After 12 months at moderate scale, the corpus will contain ~500-2,000 rules, calibrated against real customer documents, with each rule's hit count visible. New competitors entering this category will face a starting position 12 months behind.
+
+That is the point.

package/skills/release/SKILL.md

@@ -109,3 +109,7 @@ rdc-skills-install --profile core
 ```
 
 Use `--profile lifeai` only on a workstation that intentionally has the LIFEAI project layout and services.
+
+## 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>-release-<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/review/SKILL.md

@@ -146,3 +146,7 @@ description: "Usage `rdc:review [--unattended]` — Post-build quality gate: tsc
 - Each fix is a separate commit (not batched)
 - Always push fixes to origin after committing *(skip if `$RDC_TEST=1` — echo `[RDC_TEST] skipping git push` instead)*
 - Unattended: NEVER pause for input
+
+## 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>-review-<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.