@lcvbeek/patina 0.1.0 → 0.3.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,22 @@
 
 # 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`?
+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.
 
-`/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 helps you observe what's working, trim what isn't, and keep your context tight.
 
 ---
 
-## 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 +37,46 @@ 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        # set up scaffolding
+patina run         # answer onboarding questions
+patina diff        # review proposed changes
+patina buff        # apply the changes
+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 +85,9 @@ 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 status` | Show metrics: token spend, rework rate, tool usage, trends across cycles |
+| `patina buff` | Apply the pending diff to `patina.md` or spoke file (`patina apply` also works) |
+| `patina status` | Show metrics: token spend, rework rate, tool usage, trends across cycles. Shows a breakdown by project so you can verify which repos are being included |
+| `patina layers` | Visualise the patina you've built — one ASCII layer per retro cycle. Shows 5 most recent by default; use `-n 10` for more or `-n 0` for all |
 | `patina ingest` | Manually parse Claude Code logs (optional — `patina run` does this automatically) |
 
 ### patina capture
@@ -56,140 +100,223 @@ 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`.
+
+### patina ingest
+
+By default, only sessions from the **current project** are ingested — Patina derives the project slug from your working directory and matches it against `~/.claude/projects/`. This keeps metrics clean and prevents unrelated tools or automation from polluting your data.
+
+To include sessions from additional repos (e.g. a backend and frontend that share the same patina), add partial slug patterns to `.patina/config.json`:
+
+```json
+{
+  "include": ["my-backend-repo", "my-frontend-repo"]
+}
+```
+
+Patterns are matched as substrings against the project slug, so they work across machines with different home directories. `config.json` is committed — it's a team decision, not a personal one.
+
+Run `patina status` to see a breakdown by project and confirm what's being counted.
 
 ---
 
-## What gets committed
+## Team retros
 
-`.patina/` is partially tracked:
+Patina works for a single developer, but it's designed for teams. The `patina.md` constitution, cycle reports, and captures all live in git — everyone shares the same document, and anyone can contribute a capture.
 
-| 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` |
+To include teammates' session data in a retro:
+
+1. Each person runs `patina ingest` on their machine before the retro
+2. They commit and push their session files from `.patina/sessions/`
+3. Everyone pulls
+4. Whoever runs `patina run` gets the full team's sessions in the synthesis
+
+Sessions are gitignored by default. To opt in, remove `.patina/sessions/` from your `.gitignore`. Sessions are UUID-named JSON files (~500 bytes each) with no conversation content — safe to commit, no merge conflicts.
+
+If your team prefers not to commit sessions to the production repo, a future `dataDir` config option will let you point session storage at a dedicated repo instead.
 
 ---
 
-## What `patina run` produces
+## What gets committed
+
+`.patina/` is partially tracked:
 
-- `.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`
+| Path | Committed | Why |
+|---|---|---|
+| `.patina/patina.md` | Yes | The shared AI operating document (slim core) |
+| `.patina/config.json` | Yes | Project include list — team decision, shared across machines |
+| `.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/` | Optional | Session metadata from all team members — safe to commit, UUID-named so no merge conflicts |
+| `.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, a behavior contract, 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.3.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, a behavior contract, 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":"AAqCA;;;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,CA4HlD"}