@lcvbeek/patina 0.1.0 → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Leo van Beek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -2,19 +2,20 @@
 
 # Patina
 
-Patina is what forms naturally when you keep working with AI. Each retro cycle deposits a thin layer — captured moments, reflection answers, Claude's synthesis, a proposed instruction change. Over time, `patina.md` builds up into something with real depth: a working record of how your team uses AI, versioned in git, shared by everyone including new hires.
+[![npm version](https://img.shields.io/npm/v/@lcvbeek/patina.svg)](https://www.npmjs.com/package/@lcvbeek/patina)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](./LICENSE)
 
----
-
-## How is this different from Claude Code's built-in `/insights`?
-
-`/insights` produces a personal HTML report in `~/.claude/` — useful analysis, but it belongs to one person and doesn't persist between sessions. Patina produces `patina.md`, a structured document that lives in your repo, is versioned with git, and accumulates layers across cycles. The goal isn't better analysis — it's a shared artifact your team actually owns and maintains together.
+Patina is what forms naturally when you keep working with AI. Each retro
+cycle deposits a thin layer — captured moments, reflection answers, Claude's
+synthesis, a proposed instruction change. Over time, `patina.md` builds up
+into something with real depth: a working record of how your team uses AI,
+versioned in git, shared by everyone including new hires.
 
 ---
 
-## The loop
+## How it works
 
-```
+```text
 patina capture                  # anyone on the team, anytime
   → records a notable moment to .patina/captures/
   → committed to the repo, visible to everyone
@@ -34,6 +35,47 @@ Next session, the whole team works from an updated set of shared instructions.
 
 ---
 
+## Requirements
+
+- Node.js 18+
+- Access to Claude via one of:
+  - **Claude Code CLI** (recommended) — install at
+    [claude.ai/code](https://claude.ai/code), authenticate once, and Patina
+    uses it automatically. Respects your existing plan including Claude Max.
+  - **Anthropic API key** — set `ANTHROPIC_API_KEY` in your environment.
+    Patina falls back to this if the CLI isn't found.
+    Billed separately per token.
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+```
+
+---
+
+## Install
+
+```bash
+npm install -g @lcvbeek/patina
+```
+
+---
+
+## First run
+
+```bash
+cd your-project
+patina init        # creates .patina/ and patina.md
+patina run         # first cycle — answer 9 onboarding questions (~10 min)
+patina diff        # review what Claude proposed
+patina buff        # apply the change
+git add .patina/patina.md .patina/cycles/ .patina/captures/
+git commit -m "First patina layer"
+```
+
+If you have no prior Claude Code session data, `patina run` will still work — your answers are the primary input for the first cycle.
+
+---
+
 ## Commands
 
 | Command | What it does |
@@ -42,8 +84,10 @@ Next session, the whole team works from an updated set of shared instructions.
 | `patina capture [text]` | Capture a notable moment while it's fresh — feeds into the next retro |
 | `patina run` | Full retro session — auto-ingests logs, loads captures, asks reflection questions, calls Claude for synthesis |
 | `patina diff` | Review the proposed instruction change from the last `patina run` |
-| `patina buff` | Apply the pending diff to `patina.md` (`patina apply` also works) |
+| `patina buff` | Apply the pending diff to `patina.md` or spoke file (`patina apply` also works) |
+| `patina migrate` | Split a monolithic `patina.md` into slim core + spoke files |
 | `patina status` | Show metrics: token spend, rework rate, tool usage, trends across cycles |
+| `patina layers` | Visualise the patina you've built — one ASCII layer per retro cycle |
 | `patina ingest` | Manually parse Claude Code logs (optional — `patina run` does this automatically) |
 
 ### patina capture
@@ -56,7 +100,9 @@ patina capture          # interactive mode
 
 Tags: `near-miss` / `went-well` / `frustration` / `pattern` / `other`
 
-Captures are written to `.patina/captures/` as individual JSON files (one per capture, to avoid merge conflicts) and committed to the repo. Author is read from `git config user.name`.
+Captures are written to `.patina/captures/` as individual JSON files
+(one per capture, to avoid merge conflicts) and committed to the repo.
+Author is read from `git config user.name`.
 
 ---
 
@@ -66,130 +112,177 @@ Captures are written to `.patina/captures/` as individual JSON files (one per ca
 
 | Path | Committed | Why |
 |---|---|---|
-| `.patina/patina.md` | ✓ | The shared AI operating document |
-| `.patina/cycles/` | ✓ | Each layer — full cycle reports, the team's accumulated record |
-| `.patina/captures/` | ✓ | In-the-moment observations from anyone on the team |
-| `.patina/sessions/` | ✗ | Personal session data, machine-specific |
-| `.patina/metrics.json` | ✗ | Derived from sessions, not a source of truth |
-| `.patina/pending-diff.json` | ✗ | Ephemeral — consumed by `patina buff` |
-
----
-
-## What `patina run` produces
-
-- `.patina/cycles/YYYY-MM-DD.md` — full cycle report: metrics snapshot, identified patterns, coaching insight, proposed instruction diff, reflection answers
-- `.patina/pending-diff.json` — the diff staged for `patina buff`
-- An updated `.patina/patina.md` once you run `patina buff`
+| `.patina/patina.md` | Yes | The shared AI operating document (slim core) |
+| `.patina/context/` | Yes | Spoke files — extended context loaded on demand |
+| `.patina/cycles/` | Yes | Each layer — full cycle reports |
+| `.patina/captures/` | Yes | In-the-moment observations from anyone on the team |
+| `.patina/sessions/` | No | Personal session data, machine-specific |
+| `.patina/metrics.json` | No | Derived from sessions, not a source of truth |
+| `.patina/pending-diff.json` | No | Ephemeral — consumed by `patina buff` |
 
 ---
 
 ## What `patina.md` is
 
-Your team's AI operating constitution. It has sections for working agreements, agent profiles, delegation patterns, an incident log, eval criteria, and an opportunity backlog. `patina buff` appends a new entry to the cycle history and inserts the proposed instruction into the right section.
+Your team's AI operating constitution. The slim core (~50 lines) has
+sections for working agreements, agent profiles, and hard guardrails —
+always loaded into every Claude Code session. Extended sections (autonomy
+map, incident log, eval framework, cycle history) live in
+`.patina/context/` as spoke files loaded on demand.
 
-The file is yours — edit it directly whenever you want. Patina treats it as the source of truth for how your team works with AI and passes it to Claude during synthesis.
+`patina buff` routes proposed changes to the correct file.
+The file is yours — edit it directly whenever you want. Patina treats it
+as the source of truth for how your team works with AI and passes it to
+Claude during synthesis.
 
 ### How agents read it
 
 `patina init` adds the following line to your project's `CLAUDE.md` (creating it if it doesn't exist):
 
-```
+```text
 @.patina/patina.md
 ```
 
-Claude Code's `@filename` import syntax means every Claude Code session in the project automatically gets the contents of `patina.md` — no manual copying needed. When `patina buff` updates `patina.md`, Claude picks up the change in the next session.
-
-If a `CLAUDE.md` already exists, `init` appends the import line without touching anything else.
+Claude Code's `@filename` import syntax means every Claude Code session in
+the project automatically gets the contents of `patina.md` — no manual
+copying needed. When `patina buff` updates `patina.md`, Claude picks up the
+change in the next session.
 
 ---
 
-## What gets tracked
+## Privacy
 
 Everything stays local. No data leaves your machine except what you choose to send to Claude via the `claude` CLI during `patina run`.
 
 What gets ingested from your Claude Code logs:
+
 - Session timestamps and project names
 - Estimated token counts
 - Tool call names and frequencies
 - Whether a session contained rework (detected heuristically from the JSONL)
 
 What is never sent to Claude:
+
 - Raw session content or conversation transcripts
 - Anything outside `.patina/`
 
 ---
 
-## Requirements
+## How is this different from Claude Code's `/insights`?
 
-- Node.js 18+
-- Access to Claude via one of:
-  - **Claude Code CLI** (recommended) — install at [claude.ai/code](https://claude.ai/code), authenticate once, and Patina uses it automatically. Respects your existing plan including Claude Max.
-  - **Anthropic API key** — set `ANTHROPIC_API_KEY` in your environment. Patina falls back to this if the CLI isn't found. Billed separately per token.
+`/insights` produces a personal HTML report in `~/.claude/` — useful
+analysis, but it belongs to one person and doesn't persist between sessions.
+Patina produces `patina.md`, a structured document that lives in your repo,
+is versioned with git, and accumulates layers across cycles. The goal isn't
+better analysis — it's a shared artifact your team actually owns and
+maintains together.
 
-```bash
-export ANTHROPIC_API_KEY=sk-ant-...
-```
+---
+
+## Early software
+
+This is v0.1.0. It works, but expect rough edges:
+
+- The `claude` CLI call in `patina run` has a 120-second timeout; if Claude
+  is slow the command will fail (your reflection answers are saved to
+  `.patina/pending-reflection.json` so you can retry without re-answering)
+- Session ingestion parses Claude Code's JSONL format — if Anthropic changes
+  that format, ingestion will break
+- Token estimates are heuristic, not exact
+
+If something breaks or the instruction diff Claude produces is bad, that's useful signal. Open an issue or message me directly.
 
 ---
 
-## Install
+## Context architecture
 
-```bash
-git clone https://github.com/lcvbeek/patina.git
-cd patina
-npm install
+Patina uses a **hub+spoke** model to keep agent context lean:
+
+```text
+.patina/
+  patina.md              ← slim core (~50 lines, ~500 tokens). Always loaded.
+  context/
+    autonomy-detail.md   ← full autonomy map with routine scenarios
+    incident-log.md      ← past agent incidents
+    eval-framework.md    ← eval criteria and pass thresholds
+    cycle-history.md     ← retro cycle history
+    opportunity-backlog.md ← improvement ideas
 ```
 
-Run via:
+The **core** (`patina.md`) contains only the highest-value content: working
+agreements, agent behavior contracts, and hard guardrails. It's loaded into
+every Claude Code session via `@.patina/patina.md` in `CLAUDE.md`.
 
-```bash
-npx tsx src/index.ts <command>
-```
+**Spoke files** hold content that's useful during specific activities
+(debugging, testing, retro reviews) but would waste tokens if loaded every
+session. Agents can read them on demand when relevant — the core includes a
+comment index pointing to each spoke file.
 
-Or add an alias:
+`patina buff` automatically routes proposed changes to the correct file
+based on section number. `patina migrate` splits an existing monolithic
+`patina.md` into the hub+spoke layout.
 
-```bash
-alias patina="npx tsx /path/to/patina/src/index.ts"
-```
+### Why this matters
 
-Global install via `npm install -g` is coming once the CLI is stable.
+Context pollution reduces model precision. Anthropic's research shows that
+the smallest high-signal token set produces the best results. By keeping the
+always-loaded core under 80 lines / 3,200 chars, Patina ensures the
+constitution never becomes a tax on your agent's performance — even after
+dozens of retro cycles.
+
+The synthesis prompt enforces this: proposed instructions must be imperative,
+apply to >50% of sessions, and not duplicate existing entries. Stale entries
+are flagged for removal each cycle.
 
 ---
 
-## First run
+## Design decisions
 
-```bash
-cd your-project
-patina init        # creates .patina/ and patina.md
-patina run         # first cycle — answer the reflection questions
-patina diff        # review what Claude proposed
-patina buff        # apply the change
-git add .patina/patina.md .patina/cycles/ .patina/captures/
-git commit -m "First patina cycle"
-```
+<details>
+<summary><b>Why <code>patina.md</code> instead of editing CLAUDE.md directly?</b></summary>
 
-If you have no prior Claude Code session data, `patina run` will still work — your reflection answers are the primary input for the first cycle.
+`patina.md` is a structured format Patina can reliably parse, section-match,
+and append to. `patina init` wires it into your `CLAUDE.md` via
+`@.patina/patina.md`, so agents always get the latest version. Keeping it
+separate means Patina never risks corrupting your hand-written `CLAUDE.md`
+content.
 
----
+</details>
 
-## Early software
+<details>
+<summary><b>Why hub+spoke instead of one file?</b></summary>
 
-This is v0.1.0. It works, but expect rough edges:
+A monolithic `patina.md` grows unboundedly as cycles accumulate. After 10+
+cycles, sections like incident log and cycle history add hundreds of tokens
+that are rarely relevant. The hub+spoke model keeps always-loaded context at
+~500 tokens while preserving all data in spoke files for when it's needed.
+See [Context architecture](#context-architecture) for details.
 
-- The `claude` CLI call in `patina run` has a 120-second timeout; if Claude is slow the command will fail (your reflection answers are saved to `.patina/pending-reflection.json` so you can retry without re-answering)
-- Session ingestion parses Claude Code's JSONL format — if Anthropic changes that format, ingestion will break
-- Token estimates are heuristic, not exact
+</details>
 
-If something breaks or the instruction diff Claude produces is bad, that's useful signal. Open an issue or message me directly.
+<details>
+<summary><b>Why the <code>claude</code> CLI instead of the API directly?</b></summary>
 
----
+No separate API key needed — it respects your existing Claude Code
+authentication and model access. If you don't have the CLI, set
+`ANTHROPIC_API_KEY` and Patina falls back to the SDK.
+
+</details>
+
+<details>
+<summary><b>Why six reflection questions?</b></summary>
 
-## Design decisions worth knowing
+The reflection questions supplement sparse log data and give Claude
+qualitative signal the JSONL doesn't contain — what felt frustrating, what
+nearly went wrong. Both matter for the synthesis. The first cycle asks 9
+onboarding questions instead, to establish your baseline agreements.
 
-**Why a living doc instead of CLAUDE.md?** `patina.md` is a structured format Patina can reliably read and append to. You can copy entries into your `CLAUDE.md` or `AGENTS.md` manually — that handoff is intentional for now.
+</details>
 
-**Why does it use the `claude` CLI instead of the API directly?** No separate API key, and it respects your existing Claude Code authentication and model access.
+<details>
+<summary><b>Why individual capture files instead of one file?</b></summary>
 
-**Why six questions?** The reflection questions supplement sparse log data and give Claude qualitative signal the JSONL doesn't contain — what felt frustrating, what nearly went wrong. Both matter for the synthesis.
+Multiple teammates capturing on the same day would produce merge conflicts
+in a single file. One JSON file per capture means clean parallel commits.
 
-**Why individual capture files instead of appending to one file?** Multiple teammates capturing on the same day would produce merge conflicts in a single file. One file per capture means clean parallel commits.
+</details>

package/dist/commands/apply.d.ts

@@ -1,2 +1,18 @@
+/**
+ * Find the section header in patina.md and insert the diff text after it.
+ * Falls back to appending at the end of the section if the header isn't found exactly.
+ */
+export declare function applyDiffToDoc(content: string, section: string, diffText: string): string;
+/**
+ * Update the Retro Cycle History table.
+ * Operates on the cycle-history spoke file content (not the core patina.md).
+ * Keeps at most CYCLE_HISTORY_CAP rows — oldest rows are dropped when the cap
+ * is exceeded. Full cycle detail is preserved in .patina/cycles/.
+ */
+export declare function updateCycleHistory(content: string, insight: string, changeDesc: string): string;
+/**
+ * Update the cycle history spoke file on disk.
+ */
+export declare function updateCycleHistoryFile(cwd: string, insight: string, changeDesc: string): void;
 export declare function applyCommand(): Promise<void>;
 //# sourceMappingURL=apply.d.ts.map

package/dist/commands/apply.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/commands/apply.ts"],"names":[],"mappings":"AAkJA,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CA8ElD"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/commands/apply.ts"],"names":[],"mappings":"AAoCA;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CA+DzF;AAID;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CA6C/F;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAc7F;AAED,wBAAsB,YAAY,IAAI,OAAO,CAAC,IAAI,CAAC,CAoHlD"}

package/dist/commands/apply.js

@@ -1,7 +1,8 @@
 import fs from 'fs';
 import path from 'path';
 import readline from 'readline';
-import { assertInitialised, readPendingDiff, LIVING_DOC_FILE, PENDING_DIFF_FILE, METRICS_FILE, } from '../lib/storage.js';
+import { assertInitialised, readPendingDiff, LIVING_DOC_FILE, PENDING_DIFF_FILE, METRICS_FILE, SPOKE_FILES, CORE_MAX_LINES, CORE_MAX_CHARS, resolveTargetFile, ensureSpokeFiles, } from '../lib/storage.js';
+import { lintMarkdown, fixMarkdown } from '../lib/lint.js';
 const isTTY = process.stdout.isTTY;
 function bold(s) { return isTTY ? `\x1b[1m${s}\x1b[0m` : s; }
 function dim(s) { return isTTY ? `\x1b[2m${s}\x1b[0m` : s; }
@@ -23,7 +24,7 @@ function confirm(question) {
  * Find the section header in patina.md and insert the diff text after it.
  * Falls back to appending at the end of the section if the header isn't found exactly.
  */
-function applyDiffToDoc(content, section, diffText) {
+export function applyDiffToDoc(content, section, diffText) {
     const lines = content.split('\n');
     // Try to find the matching section header (## 1. Working Agreements, etc.)
     // Match by number prefix or by full title (case-insensitive)
@@ -56,10 +57,10 @@ function applyDiffToDoc(content, section, diffText) {
         ];
         return newLines.join('\n');
     }
-    // Find the end of this section (next ## heading or end of file)
+    // Find the end of this section (next ## heading, --- separator, or end of file)
     let sectionEnd = lines.length;
     for (let i = sectionIdx + 1; i < lines.length; i++) {
-        if (lines[i].startsWith('## ')) {
+        if (lines[i].startsWith('## ') || lines[i].trim() === '---') {
             sectionEnd = i;
             break;
         }
@@ -82,33 +83,43 @@ function applyDiffToDoc(content, section, diffText) {
 }
 const CYCLE_HISTORY_CAP = 5;
 /**
- * Update the Retro Cycle History table in patina.md.
+ * Update the Retro Cycle History table.
+ * Operates on the cycle-history spoke file content (not the core patina.md).
  * Keeps at most CYCLE_HISTORY_CAP rows — oldest rows are dropped when the cap
  * is exceeded. Full cycle detail is preserved in .patina/cycles/.
  */
-function updateCycleHistory(content, insight, changeDesc) {
+export function updateCycleHistory(content, insight, changeDesc) {
     const today = new Date().toISOString().slice(0, 10);
     const cycleCount = (content.match(/^\| \d+/gm) || []).length + 1;
-    const newRow = `| ${cycleCount} | ${today} | ${insight.slice(0, 60)}… | ${changeDesc.slice(0, 50)}… |`;
+    const newRow = `| ${cycleCount} | ${today} | ${insight.slice(0, 60)}... | ${changeDesc.slice(0, 50)}... |`;
     const placeholder = '| — | — | — | — |';
-    if (content.includes(placeholder)) {
-        return content.replace(placeholder, newRow);
+    let updated = content;
+    if (updated.includes(placeholder)) {
+        updated = updated.replace(placeholder, newRow);
     }
-    // Append a new row before the end of the history table
-    const historyHeader = '## 7. Retro Cycle History';
-    const historyIdx = content.indexOf(historyHeader);
-    if (historyIdx === -1)
-        return content;
-    const after = content.slice(historyIdx);
-    const lastRowMatch = after.match(/(\| .+ \|\n?)(?!.*\| .+ \|)/s);
-    if (!lastRowMatch)
-        return content;
-    const insertPos = historyIdx + after.indexOf(lastRowMatch[0]) + lastRowMatch[0].length;
-    let updated = content.slice(0, insertPos) + newRow + '\n' + content.slice(insertPos);
-    // Trim oldest rows if over cap — find all data rows in Section 7 and drop from the top
-    const headerMatch = updated.match(/## 7\. Retro Cycle History[\s\S]*?\| Cycle \| Date \| Key Insight \| Change Made \|\n\|[-| ]+\|\n/);
-    if (headerMatch) {
-        const tableStart = updated.indexOf(headerMatch[0]) + headerMatch[0].length;
+    else {
+        // Append a new row at the end of the table
+        const tableHeaderPattern = /\| Cycle \| Date \| Key Insight \| Change Made \|\n\|[-| ]+\|/;
+        const headerMatch = updated.match(tableHeaderPattern);
+        if (!headerMatch) {
+            // No table found — append one
+            updated = updated.trimEnd() + '\n' + newRow + '\n';
+        }
+        else {
+            // Find the last table row and append after it
+            const after = updated.slice(headerMatch.index);
+            const lastRowMatch = after.match(/(\| .+ \|\n?)(?!.*\| .+ \|)/s);
+            if (lastRowMatch) {
+                const insertPos = headerMatch.index + after.indexOf(lastRowMatch[0]) + lastRowMatch[0].length;
+                updated = updated.slice(0, insertPos) + newRow + '\n' + updated.slice(insertPos);
+            }
+        }
+    }
+    // Trim oldest rows if over cap
+    const tableHeaderPattern2 = /\| Cycle \| Date \| Key Insight \| Change Made \|\n\|[-| ]+\|\n/;
+    const headerMatch2 = updated.match(tableHeaderPattern2);
+    if (headerMatch2) {
+        const tableStart = headerMatch2.index + headerMatch2[0].length;
         const afterTable = updated.slice(tableStart);
         const rowRegex = /^\| \d+ \|.+\|\n?/gm;
         const rows = [...afterTable.matchAll(rowRegex)];
@@ -120,6 +131,23 @@ function updateCycleHistory(content, insight, changeDesc) {
     }
     return updated;
 }
+/**
+ * Update the cycle history spoke file on disk.
+ */
+export function updateCycleHistoryFile(cwd, insight, changeDesc) {
+    const spokeFile = path.join(cwd, SPOKE_FILES['cycle-history']);
+    let content = '';
+    if (fs.existsSync(spokeFile)) {
+        content = fs.readFileSync(spokeFile, 'utf-8');
+    }
+    else {
+        // Create with default template if missing
+        ensureSpokeFiles(cwd);
+        content = fs.readFileSync(spokeFile, 'utf-8');
+    }
+    const updated = updateCycleHistory(content, insight, changeDesc);
+    fs.writeFileSync(spokeFile, updated, 'utf-8');
+}
 export async function applyCommand() {
     assertInitialised();
     const cwd = process.cwd();
@@ -129,35 +157,67 @@ export async function applyCommand() {
         console.log(dim('Run `patina run` first, then `patina diff` to review.'));
         return;
     }
-    const livingDocPath = path.join(cwd, LIVING_DOC_FILE);
+    // Route diff to the correct file (core patina.md or a spoke file)
+    const targetFilePath = resolveTargetFile(pending.section, cwd);
+    const targetRelPath = path.relative(cwd, targetFilePath);
+    const isCore = targetFilePath === path.join(cwd, LIVING_DOC_FILE);
     console.log(`\n${bold('patina apply')} — applying instruction change`);
     console.log(hr());
+    console.log(`  Target  : ${cyan(targetRelPath)}`);
     console.log(`  Section : ${cyan(pending.section)}`);
     console.log(`  Adding  :\n`);
     pending.diff.split('\n').forEach(line => {
         console.log(`    ${green('+ ' + line)}`);
     });
     console.log();
-    const ok = await confirm(`Apply this change to ${LIVING_DOC_FILE}? [y/N] `);
+    const ok = await confirm(`Apply this change to ${targetRelPath}? [y/N] `);
     if (!ok) {
         console.log(dim('Aborted. Pending diff unchanged.'));
         return;
     }
-    // Read or create living doc
-    let content = fs.existsSync(livingDocPath)
-        ? fs.readFileSync(livingDocPath, 'utf-8')
-        : '# AI Operating Constitution\n\n## 1. Working Agreements\n\n';
-    // Apply the diff
+    // Ensure spoke files exist before applying
+    ensureSpokeFiles(cwd);
+    // Read or create target file
+    let content = fs.existsSync(targetFilePath)
+        ? fs.readFileSync(targetFilePath, 'utf-8')
+        : isCore
+            ? '# AI Operating Constitution\n\n## 1. Working Agreements\n\n'
+            : '';
+    // Apply the diff and auto-fix common lint issues
     content = applyDiffToDoc(content, pending.section, pending.diff);
-    // Update cycle history
-    content = updateCycleHistory(content, pending.rationale, pending.diff.slice(0, 50));
-    // Update the "last updated" timestamp
-    content = content.replace(/> Maintained by `patina`\. Last updated: .+/, `> Maintained by \`patina\`. Last updated: ${new Date().toISOString().slice(0, 10)}`);
-    fs.writeFileSync(livingDocPath, content, 'utf-8');
-    // Warn if patina.md is getting large
-    const SIZE_WARN_BYTES = 5 * 1024; // 5KB
-    if (Buffer.byteLength(content, 'utf-8') > SIZE_WARN_BYTES) {
-        console.log(yellow('⚠') + `  patina.md is over 5KB — consider reviewing sections for outdated entries.`);
+    content = fixMarkdown(content);
+    fs.writeFileSync(targetFilePath, content, 'utf-8');
+    // Warn about any remaining lint issues
+    const warnings = lintMarkdown(content);
+    if (warnings.length > 0) {
+        console.log(yellow('!') + ` ${warnings.length} markdown lint warning(s) in ${targetRelPath}:`);
+        for (const w of warnings.slice(0, 5)) {
+            console.log(dim(`    line ${w.line}: ${w.rule} — ${w.message}`));
+        }
+        if (warnings.length > 5) {
+            console.log(dim(`    ... and ${warnings.length - 5} more. Run \`npm run lint:md\` for full report.`));
+        }
+    }
+    // Update cycle history in the spoke file
+    updateCycleHistoryFile(cwd, pending.rationale, pending.diff.slice(0, 50));
+    // Update the "last updated" timestamp in core patina.md
+    const livingDocPath = path.join(cwd, LIVING_DOC_FILE);
+    if (fs.existsSync(livingDocPath)) {
+        let coreContent = fs.readFileSync(livingDocPath, 'utf-8');
+        const today = new Date().toISOString().slice(0, 10);
+        coreContent = coreContent.replace(/> Last updated: .+/, `> Last updated: ${today}`);
+        // Also match the old format
+        coreContent = coreContent.replace(/> Maintained by `patina`\. Last updated: .+/, `> Last updated: ${today}`);
+        fs.writeFileSync(livingDocPath, coreContent, 'utf-8');
+        // Enforce hard cap on core patina.md
+        const coreLines = coreContent.split('\n');
+        const coreChars = coreContent.length;
+        if (coreLines.length > CORE_MAX_LINES || coreChars > CORE_MAX_CHARS) {
+            console.log(yellow('!') +
+                `  Core patina.md exceeds limits (${coreLines.length} lines / ${coreChars} chars).` +
+                `  Cap: ${CORE_MAX_LINES} lines / ${CORE_MAX_CHARS} chars.` +
+                `  Consider pruning stale entries or moving detail to spoke files.`);
+        }
     }
     // Clear pending diff
     const pendingDiffPath = path.join(cwd, PENDING_DIFF_FILE);
@@ -175,11 +235,11 @@ export async function applyCommand() {
         catch { /* non-fatal */ }
     }
     console.log();
-    console.log(green('✓') + ` Applied to ${bold(LIVING_DOC_FILE)}`);
+    console.log(green('✓') + ` Applied to ${bold(targetRelPath)}`);
     console.log(green('✓') + ' Cycle history updated');
     console.log(green('✓') + ' Pending diff cleared');
     console.log();
-    console.log(dim(`Next: review ${LIVING_DOC_FILE} to confirm the change looks right.`));
+    console.log(dim(`Next: review ${targetRelPath} to confirm the change looks right.`));
     console.log(dim('Run `patina ingest` at the start of your next cycle to continue tracking.'));
     console.log();
 }