@lcvbeek/patina 0.2.0 → 0.4.0

package/README.md

@@ -1,5 +1,3 @@
-<img width="250" height="72" alt="Patina (2)" src="https://github.com/user-attachments/assets/77650975-b20b-4a65-b582-bb86ff6c2ae3" />
-
 # Patina
 
 [![npm version](https://img.shields.io/npm/v/@lcvbeek/patina.svg)](https://www.npmjs.com/package/@lcvbeek/patina)
@@ -7,28 +5,30 @@
 
 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
+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.
 
+Patina helps you observe what's working, trim what isn't, and keep your context tight.
+
 ---
 
 ## 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
+  → records a notable moment
+
+patina reflect                  # each person, before the retro
+  → reflection questions (6 included, customizable)
 
-patina run                      # when you're ready for a retro
+patina run                      # when the team is ready
   → auto-ingests Claude Code JSONL logs
-  → loads all captures since the last cycle
-  → 6 reflection questions (~10 min)
-  → Claude synthesises session data + captures + your answers
+  → loads all captures and reflections since the last cycle
+  → Claude synthesises session data + captures + reflections
   → coaching insight + proposed instruction diff
 
-patina diff                     # review the proposed change
-patina buff                     # apply it to .patina/patina.md
+patina buff                     # review the diff and apply it to .patina/PATINA.md
 ```
 
 Next session, the whole team works from an updated set of shared instructions.
@@ -64,11 +64,9 @@ npm install -g @lcvbeek/patina
 
 ```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/
+patina init        # set up scaffolding
+patina run         # answer onboarding questions (first time only)
+patina buff        # review and apply proposed changes
 git commit -m "First patina layer"
 ```
 
@@ -78,17 +76,24 @@ If you have no prior Claude Code session data, `patina run` will still work —
 
 ## Commands
 
-| Command | What it does |
-|---|---|
-| `patina init` | Scaffold `.patina/` in the current directory, create `patina.md` |
-| `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` 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) |
+| Command          | What it does                                                                                                                                            |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `init`           | Scaffold `.patina/` in the current directory, create `PATINA.md`                                                                                        |
+| `capture`        | Capture a notable moment while it's fresh — feeds into the next retro                                                                                   |
+| `reflect`        | Answer reflection questions before the retro — saved locally, loaded by `patina run`                                                                    |
+| `run`            | Run the retro — auto-ingests logs, loads captures + reflections, calls Claude for synthesis                                                             |
+| `buff` (`apply`) | Review the proposed instruction change and apply it — shows diff, prompts for confirmation                                                              |
+| `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 |
+| `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             |
+| `ingest`         | Manually parse Claude Code logs (optional — `patina run` does this automatically)                                                                       |
+
+### patina init
+
+```bash
+patina init
+```
+
+Creates `.patina/` with `PATINA.md`, `config.json`, `context/`, and `cycles/`. Adds `@.patina/PATINA.md` to `CLAUDE.md` (creating it if needed). Safe to run once per project.
 
 ### patina capture
 
@@ -100,32 +105,158 @@ 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/projects/<slug>/captures/` as individual JSON files — one per capture, so there are never merge conflicts. Author is read from `git config user.name`.
+
+### patina reflect
+
+```bash
+patina reflect
+```
+
+Walks through the reflection questions and saves answers locally. Run this before `patina run`. On a team, each person reflects on their own machine — `patina run` aggregates all answers recorded since the last cycle.
+
+Reflection questions can be customised by adding `.patina/questions.json` to the project (committed, so the whole team uses the same set).
+
+### patina run
+
+```bash
+patina run
+patina run --onboard # force onboarding questions
+```
+
+Auto-ingests Claude Code logs, loads all captures and reflections since the last cycle, calls Claude for synthesis, and writes the result to `.patina/cycles/<date>.md` and a pending diff. On first run, asks onboarding questions to establish your baseline agreements instead.
+
+### patina buff
+
+```bash
+patina buff          # show diff, prompt to apply
+patina buff --yes    # apply without prompting
+patina apply         # alias
+```
+
+Shows the pending instruction diff from the last `patina run` — rationale, target file, and the proposed addition — then prompts for confirmation. Applies to the correct file (core or spoke, based on section number) and clears the pending diff.
+
+### patina status
+
+```bash
+patina status
+```
+
+Shows token spend, rework rate, tool usage, and trends across cycles. Includes a per-project breakdown so you can verify which repos are contributing to your metrics.
+
+### patina layers
+
+```bash
+patina layers        # 5 most recent cycles
+patina layers -n 10  # last 10
+patina layers -n 0   # all
+```
+
+Renders one ASCII layer per retro cycle — a quick visual of how your patina has built up over time.
+
+### patina ingest
+
+```bash
+patina ingest
+```
+
+Manually parses Claude Code JSONL logs and writes session summaries to the data dir. `patina run` does this automatically — use this to pre-populate metrics or debug ingestion. 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.
+
+---
+
+## Data directory
+
+All operational data — sessions, captures, reflections, metrics, and pending diffs — lives outside the project repo. By default it goes to:
+
+```bash
+~/.patina/projects/<slug>/
+  sessions/
+  captures/
+  reflections/
+  metrics.json
+  pending-diff.json
+```
+
+The slug is derived from your working directory path (e.g. `/Users/lcvbeek/work/api` → `-Users-lcvbeek-work-api`), mirroring how Claude Code stores its own session data in `~/.claude/projects/`. Each project on your machine is automatically isolated.
+
+Nothing in `.patina/` needs to be gitignored — the project directory contains only committed artifacts.
+
+**Overriding the data dir.** Set `dataDir` in `.patina/config.json` to redirect all data to a different location. The path is resolved relative to the project root, so it works across machines with different home directories:
+
+```json
+{
+  "include": [],
+  "exclude": [],
+  "dataDir": "../our-patina-data"
+}
+```
+
+| Field     | Type       | Default                      | Description                                                                                          |
+| --------- | ---------- | ---------------------------- | ---------------------------------------------------------------------------------------------------- |
+| `include` | `string[]` | `[]`                         | Slug substrings of additional projects to ingest (e.g. `["api", "frontend"]`)                        |
+| `exclude` | `string[]` | `[]`                         | Slug substrings to exclude — takes precedence over `include`. Useful when include patterns are broad |
+| `dataDir` | `string`   | `~/.patina/projects/<slug>/` | Path to shared data directory (relative to project root). Set this for team retros                   |
+
+You can also set `PATINA_DATA_DIR` as an environment variable to override `dataDir` per-session (useful for testing).
+
+---
+
+## Team retros
+
+Patina works for a single developer, but it's designed to support teams. Point `dataDir` in `.patina/config.json` to a shared location and everyone's captures, reflections, and session data land in the same place:
+
+```json
+{
+  "include": [],
+  "dataDir": "../our-patina-data"
+}
+```
+
+The path is resolved relative to the project root, so it works across machines. A dedicated repo works well — files are small, contain no secrets, and are UUID-named so there are never merge conflicts.
+
+**The retro flow for a team:**
+
+1. Anyone captures notable moments throughout the cycle with `patina capture`
+2. Before the retro, each person runs `patina reflect` (~10 min)
+3. One person runs `patina run` — it loads all captures and reflections since the last cycle, calls Claude, and produces a synthesis with every team member's voice
+4. Review and apply with `patina buff`, commit the updated `PATINA.md`
+
+Without `dataDir`, all data stays local to each machine (`~/.patina/projects/<slug>/`). `patina run` will only see what's been captured and reflected on the machine it runs on — useful for solo use, but not a full team retro.
+
+**Multiple projects on one machine.** Each project gets its own data directory automatically — the slug is derived from the working directory path, so `/Users/leo/work/api` and `/Users/leo/work/frontend` are always isolated from each other.
+
+If a team works across multiple repos that share the same `PATINA.md` (e.g. a backend and a frontend), you can pull their session data into a single retro using the `include` list in `config.json`:
+
+```json
+{
+  "include": ["my-backend", "my-frontend"],
+  "dataDir": "../our-patina-data"
+}
+```
+
+Entries in `include` are matched as substrings against the project slug, so they work across machines regardless of home directory. `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
 
-`.patina/` is partially tracked:
+Everything in `.patina/` is committed — there's nothing to gitignore:
 
-| Path | Committed | Why |
-|---|---|---|
-| `.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` |
+| Path                  | Why                                                          |
+| --------------------- | ------------------------------------------------------------ |
+| `.patina/PATINA.md`   | The shared AI operating document (slim core)                 |
+| `.patina/config.json` | Project include list — team decision, shared across machines |
+| `.patina/context/`    | Spoke files — extended context loaded on demand              |
+| `.patina/cycles/`     | Each layer — full cycle reports                              |
+
+All operational data (sessions, reflections, captures, metrics, pending diffs) lives in `~/.patina/projects/<slug>/` — machine-local by default, never committed. Use `dataDir` in `config.json` to share it with your team.
 
 ---
 
-## What `patina.md` is
+## What `PATINA.md` is
 
 Your team's AI operating constitution. The slim core (~50 lines) has
-sections for working agreements, agent profiles, and hard guardrails —
+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.
@@ -140,12 +271,12 @@ Claude during synthesis.
 `patina init` adds the following line to your project's `CLAUDE.md` (creating it if it doesn't exist):
 
 ```text
-@.patina/patina.md
+@.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
+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.
 
 ---
@@ -172,7 +303,7 @@ What is never sent to Claude:
 
 `/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,
+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.
@@ -181,11 +312,11 @@ maintains together.
 
 ## Early software
 
-This is v0.1.0. It works, but expect rough edges:
+This is early software. 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)
+  is slow the command will fail (your reflection answers are already saved by
+  `patina reflect`, so you can retry `patina run` 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
@@ -200,7 +331,7 @@ Patina uses a **hub+spoke** model to keep agent context lean:
 
 ```text
 .patina/
-  patina.md              ← slim core (~50 lines, ~500 tokens). Always loaded.
+  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
@@ -209,9 +340,9 @@ Patina uses a **hub+spoke** model to keep agent context lean:
     opportunity-backlog.md ← improvement ideas
 ```
 
-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`.
+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`.
 
 **Spoke files** hold content that's useful during specific activities
 (debugging, testing, retro reviews) but would waste tokens if loaded every
@@ -220,7 +351,7 @@ comment index pointing to each spoke file.
 
 `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.
+`PATINA.md` into the hub+spoke layout.
 
 ### Why this matters
 
@@ -239,50 +370,52 @@ are flagged for removal each cycle.
 ## Design decisions
 
 <details>
-<summary><b>Why <code>patina.md</code> instead of editing CLAUDE.md directly?</b></summary>
+<summary><b>Why are cycle reports committed but captures and reflections are not?</b></summary>
+
+The distinction is input vs. output. Captures, reflections, and session logs are raw material that feeds the synthesis — they're per-machine, per-person, and ephemeral once the cycle runs. Cycle reports (`.patina/cycles/<date>.md`) are the permanent team record: the synthesised insight, proposed instruction changes, and metrics for each retro. They're what `patina layers` visualises and what new team members read to understand how the team's AI practice has evolved. They belong in git for the same reason commit history does.
 
-`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.
+Everything operational lives in `~/.patina/projects/<slug>/` (or a shared `dataDir`) and is never committed. Nothing in `.patina/` needs to be gitignored.
 
 </details>
 
 <details>
-<summary><b>Why hub+spoke instead of one file?</b></summary>
+<summary><b>Why <code>PATINA.md</code> instead of editing CLAUDE.md directly?</b></summary>
 
-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.
+`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>
 
 <details>
-<summary><b>Why the <code>claude</code> CLI instead of the API directly?</b></summary>
+<summary><b>Why hub+spoke instead of one file?</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.
+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.
 
 </details>
 
 <details>
-<summary><b>Why six reflection questions?</b></summary>
+<summary><b>Why the <code>claude</code> CLI instead of the API directly?</b></summary>
 
-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.
+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 individual capture files instead of one file?</b></summary>
+<summary><b>Solo vs. team vs. multi-project — how the same commands scale</b></summary>
+
+**Solo, one project.** Run `patina reflect` then `patina run`. Everything stays in `~/.patina/projects/<slug>/`. No config needed.
+
+**Team, one project.** Add `dataDir` to `.patina/config.json` pointing at a shared repo. Everyone's captures, reflections, and session data land in the same place. Each person runs `patina reflect` on their own machine before the retro; whoever runs `patina run` gets a synthesis with all voices included.
+
+**Team, multiple repos sharing one constitution.** Add slugs to `include` in `config.json` so `patina ingest` pulls session data from all related repos into the same retro. Use `patina status` to verify what's being counted.
+
+```json
+{
+  "include": ["api", "frontend"],
+  "exclude": ["api-legacy"],
+  "dataDir": "../our-patina-data"
+}
+```
 
-Multiple teammates capturing on the same day would produce merge conflicts
-in a single file. One JSON file per capture means clean parallel commits.
+The project repo (`PATINA.md`, `cycles/`, `config.json`) stays in git. The data repo (`dataDir`) is a separate, never-built repo that just accumulates JSON files.
 
 </details>

package/dist/commands/apply.d.ts

@@ -1,11 +1,11 @@
 /**
- * Find the section header in patina.md and insert the diff text after it.
+ * 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).
+ * 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/.
  */
@@ -14,5 +14,7 @@ export declare function updateCycleHistory(content: string, insight: string, cha
  * 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>;
+export declare function applyCommand(options?: {
+    yes?: boolean;
+}): 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":"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"}
+{"version":3,"file":"apply.d.ts","sourceRoot":"","sources":["../../src/commands/apply.ts"],"names":[],"mappings":"AAqDA;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAkEzF;AAID;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CA8C/F;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAc7F;AAED,wBAAsB,YAAY,CAAC,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CA2IjF"}