pattern-mcp 0.6.0 → 0.8.0

package/README.md

@@ -2,15 +2,32 @@
 
 [![Publish](https://github.com/donaldrichard19-LVD/pattern-mcp/actions/workflows/publish.yml/badge.svg)](https://github.com/donaldrichard19-LVD/pattern-mcp/actions/workflows/publish.yml)
 [![npm version](https://img.shields.io/npm/v/pattern-mcp.svg)](https://www.npmjs.com/package/pattern-mcp)
-[![npm downloads](https://img.shields.io/npm/dm/pattern-mcp.svg)](https://www.npmjs.com/package/pattern-mcp)
+[![npm downloads](https://img.shields.io/npm/dt/pattern-mcp.svg)](https://www.npmjs.com/package/pattern-mcp)
 [![MIT license](https://img.shields.io/badge/license-MIT-111111.svg)](./LICENSE)
 
-Pattern is an MCP server that checks a UI component need against real,
-current evidence before your agent commits to it, so a wrong decision
-gets caught before it's built, not after.
+Pattern solves a simple problem: agents don't always follow your design
+guidance. Instead of relying on the agent to interpret and follow
+instructions, Pattern turns that guidance into a checkable process. It
+evaluates UI components from external libraries or your own design
+system against a requirements checklist, then tells the agent whether to
+use an existing component or build one from scratch using a concrete
+design reference.
 
 [Website](https://usepattern.sh) · [npm](https://www.npmjs.com/package/pattern-mcp) · [Report an issue](https://github.com/donaldrichard19-LVD/pattern-mcp/issues/new/choose)
 
+<details>
+<summary><strong>Contents</strong> (click to expand)</summary>
+
+- [Install](#install) · [What Pattern Does](#what-pattern-does) · [How it works](#how-it-works) · [Quick Start](#quick-start) · [Try it](#try-it) · [Validation examples](#validation-examples)
+- **Make the judgment call:** [`recommend_component`](#tool-recommend_component) · [`extract_requirements`](#tool-extract_requirements)
+- **Track cost and outcome:** [`record_component_decision`](#tool-record_component_decision) · [`read_ledger`](#tool-read_ledger) · [`report_build_cost`](#tool-report_build_cost) · [`report_outcome_proxy`](#tool-report_outcome_proxy) · [Feature cost attribution](#feature-cost-attribution) · [Outcome proxies](#outcome-proxies) · [Per-project judgment ledger](#per-project-judgment-ledger)
+- **Verify and export old decisions:** [`check_ledger_liveness`](#tool-check_ledger_liveness) · [`sweep_ledger_liveness`](#tool-sweep_ledger_liveness) · [`export_ledger_provenance`](#tool-export_ledger_provenance) · [`backfill_ledger_snapshot_ref`](#tool-backfill_ledger_snapshot_ref) · [`post_ledger_provenance_to_github`](#tool-post_ledger_provenance_to_github) · [Ledger integrity and decision provenance](#ledger-integrity-and-decision-provenance) (design overview — start here for how the five fit together)
+- [Per-project decision memory](#per-project-decision-memory) · [Security and privacy](#security-and-privacy) · [Telemetry](#telemetry)
+- **Cost:** [The `_meta` field](#the-_meta-field) · [Prompt caching](#prompt-caching) · [Measured cache and fetch behavior](#measured-cache-and-fetch-behavior) · [Search limits](#search-limits) · [Ensemble cost](#ensemble-cost-boundary-risk-cases-only) · [Session call cap](#session-call-cap)
+- [Local call log](#local-call-log) · [Known limitations](#known-limitations)
+
+</details>
+
 ## Install
 
 ```bash
@@ -32,13 +49,18 @@ whether to:
 
 Pattern is designed for agents to use **while they are building**.
 
-It exposes eight tools:
+It exposes eleven tools, in three groups:
+
+**Make the judgment call.**
 
 - `recommend_component` — evaluates a UI component need and returns a
   structured recommendation.
 - `extract_requirements` — runs just the requirement-extraction step on
   its own, so you can inspect or hand-edit the checklist before
   `recommend_component` spends its search+score budget on it.
+
+**Track what it cost and what actually happened.**
+
 - `record_component_decision` — records what the agent actually did so
   future recommendations in the same project can take that decision into
   account.
@@ -54,13 +76,27 @@ It exposes eight tools:
   merge, kept-vs-replaced) for one feature, deliberately independent of
   Pattern's own verdict -- see [Outcome
   proxies](#outcome-proxies).
+
+**Verify old decisions still hold up, and export a record of them.** See
+[Ledger integrity and decision
+provenance](#ledger-integrity-and-decision-provenance) for how these five
+fit together.
+
 - `check_ledger_liveness` — checks whether a ledger entry's recorded
-  `file_path` still exists and still references its `chosen_candidate` --
-  see [Tool: `check_ledger_liveness`](#tool-check_ledger_liveness).
+  `file_path` still exists and still references its `chosen_candidate`.
+- `sweep_ledger_liveness` — batch version of `check_ledger_liveness`
+  across a whole project (or every project in the ledger), plus
+  dangling-cluster detection. Meant to be invoked by your own cron/CI, not
+  something Pattern schedules itself.
 - `export_ledger_provenance` — formats one ledger entry as a stable
   markdown block (checklist, candidates, verdict, `snapshot_ref`) you can
-  paste into a PR or issue by hand -- see [Tool:
-  `export_ledger_provenance`](#tool-export_ledger_provenance).
+  paste into a PR or issue by hand.
+- `backfill_ledger_snapshot_ref` — best-effort `snapshot_ref`
+  reconstruction for entries written before that field existed.
+- `post_ledger_provenance_to_github` — posts an `export_ledger_provenance`
+  artifact as a real comment on a GitHub PR/issue, idempotently. The one
+  tool here with a real, visible side effect outside your own machine;
+  confirm with the user before calling it.
 
 ## How it works
 
@@ -564,6 +600,114 @@ The calling agent should:
 
 See [SECURITY.md](./SECURITY.md) for more details.
 
+## Tool: `register_design_system`
+
+Points `recommend_component` at *this project's own* design system instead
+of shadcn/ui, 21st.dev, and ReUI -- for a solo dev with their own component
+library or design spec who wants Pattern's coverage scoring against
+candidates they'll actually use, not external libraries they won't. This is
+the Solo Dev architecture from `pattern-solo-design-system-architecture.md`:
+local, per-project, one-or-the-other -- registering a design system for a
+`project_id` **replaces** external-library scoring for that project
+entirely, it does not add to it. There's no shared/remote ledger, no
+multi-user attribution, and no team auth in this scope -- those are
+deliberately deferred to a team phase, only if this use case proves out.
+
+### Input
+
+Exactly one of `manifest_path` or `directory_path` is required, both
+relative to the project root (`PATTERN_PROJECT_ROOT`, defaults to this
+server's working directory) -- never an absolute path.
+
+```json
+{
+  "project_id": "my-booking-app",
+  "directory_path": "src/components"
+}
+```
+
+- **`manifest_path`** -- a components manifest. Two recognized shapes:
+  - A hand-authored JSON array of `{name, props, description,
+    usage_example}` objects, optionally wrapped in `{"components": [...]}`.
+  - A Storybook-exported `stories.json`/`index.json` file (an object with a
+    top-level `entries` or `stories` map). Component names only in this
+    case -- Storybook's basic export doesn't carry prop data, so candidates
+    from this path start with an empty `props` list.
+- **`directory_path`** -- a directory of real component source files,
+  scanned recursively for `.jsx`/`.tsx`/`.js`/`.ts` files (excluding
+  `node_modules`/`dist`/`build`/`.git` and `.test.`/`.spec.`/`.stories.`
+  files). Each exported, uppercase-named function or const component found
+  becomes a candidate, with props read in priority order from a
+  `<Name>Props` interface/type, a `.propTypes` block, or (last resort) the
+  component's own destructured parameters. This is a heuristic scan, not a
+  full parser -- a sparse or partial props list for some components is
+  expected, not a bug, especially on plain JS with no prop typing at all.
+
+### Output
+
+```json
+{
+  "status": "registered",
+  "registration": {
+    "project_id": "my-booking-app",
+    "source_kind": "directory_scan",
+    "source_path": "src/components",
+    "registered_at": "2026-09-03T18:04:11.201Z",
+    "candidate_count": 29,
+    "candidates": [
+      { "name": "ReferralBanner", "props": ["code", "bonusAmount"], "description": null, "usage_example": null, "file_path": "rewards/ReferralBanner.jsx" }
+    ]
+  }
+}
+```
+
+Registering overwrites (does not merge with) any prior registration for the
+same `project_id`. Once registered, `recommend_component` scores ONLY
+against these candidates for calls with this `project_id` -- no separate
+flag needed, it's automatic based on `project_id` alone, and step 3's live
+web search is skipped entirely (`web_search` is still available, but
+reserved for a `custom_build` verdict's Mobbin/Figma Community reference
+grounding, same as the external-library path). A `use_existing` verdict
+scored this way always carries `"source": "design_system"` on the
+resulting ledger entry, set server-side regardless of what the model wrote,
+so `read_ledger` and `export_ledger_provenance` can match on it reliably.
+
+This only writes local config to `~/.pattern/design_systems.json` (override
+with `PATTERN_DESIGN_SYSTEMS_PATH`) -- it never calls the Anthropic API.
+Registration is a point-in-time snapshot, not a live link: re-run this
+whenever the design system's own components change meaningfully.
+
+### A safety net for a missed match
+
+The model can occasionally say `custom_build`/`no_candidates_found`
+against a registered design system even when a real match is sitting
+right there in its own prompt -- a reading-comprehension miss over its own
+known-complete candidate list, not evidence the list was actually empty.
+When this happens, `recommend_component`'s response may carry a
+`design_system_recall_check` field: a deterministic, zero-cost, local
+keyword-overlap check (component name, props, description/usage_example
+vs. `component_need`/`domain`) run automatically whenever reason is
+`no_candidates_found` in this mode.
+
+```json
+{
+  "verdict": "custom_build",
+  "reason": "no_candidates_found",
+  "design_system_recall_check": {
+    "possible_missed_candidates": [
+      { "name": "ReferralBanner", "shared_keywords": ["referral", "bonus"] }
+    ],
+    "note": "These registered design-system candidates share keywords with this component_need but were not selected as a match -- the verdict may have missed a real one. This is a weak, keyword-only signal, not proof of an actual match: double-check these candidates yourself (or re-run this call) before trusting custom_build here."
+  }
+}
+```
+
+This never overrides the verdict -- a shared keyword is weak evidence, not
+proof of a real match -- it only surfaces the risk so you (or the calling
+agent) know to double-check before accepting a `custom_build` verdict at
+face value. Absent entirely when there's no overlap, or outside
+design-system mode.
+
 ## Tool: `extract_requirements`
 
 Runs only the requirement-extraction step `recommend_component` normally
@@ -739,14 +883,16 @@ came back with `served_from_ledger: true`.
       "file_path": null,
       "snapshot_ref": "a1b2c3d4e5f6...",
       "last_verified_live": null,
-      "live_status": "unknown"
+      "live_status": "unknown",
+      "reconstructed_snapshot_ref": null
     }
   ]
 }
 ```
 
-`file_path`/`snapshot_ref`/`last_verified_live`/`live_status` are the
-ledger integrity + decision provenance fields -- see [Ledger integrity and
+`file_path`/`snapshot_ref`/`last_verified_live`/`live_status`/
+`reconstructed_snapshot_ref` are the ledger integrity + decision
+provenance fields -- see [Ledger integrity and
 decision provenance](#ledger-integrity-and-decision-provenance) and [Tool:
 `check_ledger_liveness`](#tool-check_ledger_liveness). Entries written
 before this feature shipped read back with `file_path`/`snapshot_ref`/
@@ -954,8 +1100,11 @@ an arbitrary shell command.
 ```
 
 `live_status` is one of `"live"`, `"orphaned"`, `"unknown"`, or
-(reserved, not yet produced -- see [Ledger integrity and decision
-provenance](#ledger-integrity-and-decision-provenance)) `"dangling"`.
+`"dangling"` (only ever produced by
+[`sweep_ledger_liveness`](#tool-sweep_ledger_liveness)'s cluster
+detection, never by a single-entry `check_ledger_liveness` call -- see
+[Ledger integrity and decision
+provenance](#ledger-integrity-and-decision-provenance)).
 Entries with no `file_path` are listed but never checked or written to
 `ledger_liveness.jsonl` -- their status is permanently `"unknown"` since
 there's nothing to check. Results here are also layered onto
@@ -963,6 +1112,72 @@ there's nothing to check. Results here are also layered onto
 entries afterward -- `check_ledger_liveness` is the only thing that
 advances those fields past their write-time defaults.
 
+## Tool: `sweep_ledger_liveness`
+
+Batch version of [`check_ledger_liveness`](#tool-check_ledger_liveness):
+updates `live_status` for every `file_path`-bearing entry across an
+entire project, or -- when `project_id` is omitted -- every `project_id`
+present in the ledger. This is the "on a schedule (project open or cron)"
+half of the referential-integrity design that `check_ledger_liveness`'s
+on-demand, single-project call doesn't cover.
+
+**Pattern has no daemon or scheduler of its own.** Each server invocation
+is transient, tied to its MCP host's lifecycle -- there is nowhere inside
+this server for a cron job to live. This tool is meant to be invoked by
+whatever external scheduler you already have (a cron job, a CI step
+running nightly), not something Pattern triggers automatically or ever
+will on its own.
+
+### Input
+
+```json
+{
+  "project_id": "my-booking-app"
+}
+```
+
+`project_id` is optional -- omit it to sweep every `project_id` present
+in the ledger in one call.
+
+### Output
+
+```json
+{
+  "projects_swept": 2,
+  "total_entries_checked": 14,
+  "dangling_clusters": [
+    { "project_id": "my-booking-app", "feature_id": "3f9a21c0", "entry_ids": ["...", "..."] }
+  ],
+  "per_project": [
+    { "project_id": "my-booking-app", "checked": 9, "total_entries": 12, "dangling_clusters": 1 },
+    { "project_id": "other-project", "checked": 5, "total_entries": 5, "dangling_clusters": 0 }
+  ]
+}
+```
+
+### Dangling clusters, and how "cluster" maps onto what the ledger actually stores
+
+The ledger has no explicit entry-to-entry reference field -- each line is
+an independent judgment record. `feature_id` (see [Feature cost
+attribution](#feature-cost-attribution)) is the one real grouping
+construct that already exists, so a "cluster" here means every entry
+sharing one `feature_id`, and "no live anchor" means none of them
+resolved to `live_status: "live"`. A single-entry group is just an
+ordinary orphaned/unknown entry, not a cluster phenomenon, so groups of
+one are never flagged.
+
+Every entry in a qualifying cluster gets `live_status: "dangling"` --
+overriding whatever `"orphaned"`/`"unknown"` value it had -- visible on
+its next `read_ledger`/`check_ledger_liveness` read via the same
+`ledger_liveness.jsonl` overlay `check_ledger_liveness` already writes to
+(see [Referential integrity](#referential-integrity-file_path--live_status)).
+Tested against the exact repro shape reported by a user: 13 entries, 12
+sharing a `feature_id` with no live anchor among them, 1 separate and
+live -- all 12 flag `dangling`, the 13th doesn't. Also tested at 200 and
+1,000 synthetic entries without reintroducing search+score-class latency
+(both complete in well under a second -- this is `fs.existsSync` calls
+and in-memory grouping, not API calls).
+
 ## Tool: `export_ledger_provenance`
 
 Formats one ledger entry -- requirements checklist, candidates compared,
@@ -975,8 +1190,9 @@ design and its deliberate limits.
 Pure and deterministic: the same entry always produces byte-identical
 markdown, since the function reads nothing but its input (no live system
 time, no disk state). This only formats and returns text -- it does not
-post anything to GitHub or anywhere else; that's a separate action, not
-yet built.
+post anything anywhere; see
+[`post_ledger_provenance_to_github`](#tool-post_ledger_provenance_to_github)
+below for that.
 
 ### Input
 
@@ -1012,6 +1228,134 @@ custom-build reference (Mobbin/Figma) to the ledger (see
 A `null` `snapshot_ref` (project root wasn't a git repository at judgment
 time) renders as prose too, not the literal word `null`.
 
+## Tool: `backfill_ledger_snapshot_ref`
+
+Best-effort reconstruction of `snapshot_ref` for ledger entries written
+before that field existed (or written outside a git repository): finds
+the commit that was `HEAD` at or just before each entry's own timestamp
+(`git log --before=<timestamp> -1 --format=%H`). Entries that already
+have a real `snapshot_ref` are reported but never touched -- backfill
+only ever fills a gap, never second-guesses a captured value.
+
+### Input
+
+```json
+{
+  "project_id": "my-booking-app",
+  "ledger_entry_id": "a1b2c3d4-..."
+}
+```
+
+`ledger_entry_id` is optional -- omit it to backfill every entry in the
+project missing `snapshot_ref`.
+
+### Output
+
+```json
+{
+  "project_id": "my-booking-app",
+  "attempted": 3,
+  "reconstructed": 2,
+  "results": [
+    { "ledger_entry_id": "a1b2c3d4-...", "already_had_snapshot_ref": false, "reconstructed_snapshot_ref": "9f3a1c7e2b0d4f5a6b7c8d9e0f1a2b3c4d5e6f70" },
+    { "ledger_entry_id": "e5f6a7b8-...", "already_had_snapshot_ref": false, "reconstructed_snapshot_ref": null }
+  ]
+}
+```
+
+### A reconstructed value is always labeled, never presented as real
+
+Necessarily an approximation, not a guarantee: a rebase, force-push, or
+history rewrite since that timestamp can make "the commit `HEAD` pointed
+to then" no longer resolve to what the codebase actually looked like at
+judgment time. Every attempt is persisted (including failures -- a
+project whose git history doesn't reach back that far, or that isn't a
+git repository at all) to `~/.pattern/snapshot_backfill.jsonl` (override
+with `PATTERN_SNAPSHOT_BACKFILL_PATH`), and surfaces on later reads as
+`reconstructed_snapshot_ref` -- a field kept fully separate from
+`snapshot_ref` itself, never overwriting or being confused with it.
+[`export_ledger_provenance`](#tool-export_ledger_provenance) and
+[`post_ledger_provenance_to_github`](#tool-post_ledger_provenance_to_github)
+both render a reconstructed value with an explicit "(reconstructed via
+backfill -- best-effort approximation, not the original captured
+snapshot)" label, never silently as if it were equivalent to a value
+captured live.
+
+Tested against a real throwaway git repo with known commit history (an
+entry timestamped between two real commits reconstructs to exactly the
+first one), a 200-entry synthetic ledger outside any git repo (every
+attempt fails fast and reports `null` rather than throwing), and a
+read-only run against this project's own real `coop-commerce` ledger
+entries, per the spec's own test plan.
+
+## Tool: `post_ledger_provenance_to_github`
+
+Posts one ledger entry's provenance artifact (the same content
+`export_ledger_provenance` produces) as a real comment on a GitHub PR or
+issue. **This is the one tool in this server with a real, visible side
+effect on a third-party service** -- every other tool here only ever
+touches local files. Confirm with the user before calling it, the same
+way you're expected to confirm before running a suggested
+`install_command` (see [Installation commands are not
+trusted](#installation-commands-are-not-trusted) and SECURITY.md).
+
+GitHub treats a PR and an issue identically for comments (both use the
+same `/issues/{number}/comments` endpoint), so there's one input shape
+for both -- no separate "is this a PR" flag.
+
+### Auth: `GITHUB_TOKEN`, not a GitHub App
+
+This resolves the open question left in [Ledger integrity and decision
+provenance](#ledger-integrity-and-decision-provenance)'s earlier writeup
+in favor of a **personal access token**, read from the `GITHUB_TOKEN`
+environment variable -- the same convention every GitHub Action and the
+`gh` CLI itself already use. Needs `repo` scope. A GitHub App was the
+alternative on the table, but it needs a hosted installation flow and a
+webhook receiver, which contradicts this project's entire distribution
+model (a local npm package, no hosted infrastructure -- see [Ledger
+integrity and decision provenance](#ledger-integrity-and-decision-provenance)
+and the Pattern Primer's build-order principle). Pattern manages no
+GitHub credential of its own, the same way it manages no git credential
+for `snapshot_ref` -- it just reads what's already in your environment.
+
+### Input
+
+```json
+{
+  "project_id": "my-booking-app",
+  "ledger_entry_id": "a1b2c3d4-...",
+  "repo": "my-org/my-booking-app",
+  "issue_number": 42
+}
+```
+
+All four fields are required.
+
+### Output
+
+```json
+{
+  "posted": true,
+  "comment_url": "https://github.com/my-org/my-booking-app/pull/42#issuecomment-...",
+  "comment_id": 123456789
+}
+```
+
+### Idempotent by construction
+
+Every posted comment is prefixed with a hidden HTML marker keyed to the
+ledger entry's id (`<!-- pattern-ledger-provenance:<id> -->`). A call
+first checks the thread's existing comments (most recent 100 -- full
+pagination isn't handled yet) for that marker; if found, it returns
+`{ "posted": false, "reason": "already_posted", "comment_url": "..." }`
+pointing at the existing comment instead of creating a duplicate. A
+repeat call is always safe to make.
+
+Errors (`isError: true`) clearly on: no `GITHUB_TOKEN` set, a malformed
+`repo` (not `owner/repo`), an unknown `ledger_entry_id`, or a GitHub API
+error (bad credentials, repo/issue not found, rate limit) -- the error
+message includes the real HTTP status and GitHub's own error text.
+
 ## Feature cost attribution
 
 Every `recommend_component` call that writes to the ledger -- a fresh
@@ -1133,25 +1477,33 @@ Two gaps in the ledger, surfaced from user feedback: it tracks that a
 decision was made, but not whether the thing it decided about is still
 live in your codebase, and it stores the checklist/verdict but not a
 version pin or an exportable artifact you can attach to a PR or issue.
-This section covers what's shipped so far -- **P0/P1 of both halves**, not
-the full spec. See `pattern-ledger-integrity-and-provenance-spec.md` for
-the complete phased plan; P2/P3 (a scheduled/batch sweep, dangling-cluster
-detection, the provenance-artifact exporter, and GitHub PR/issue posting)
-are not built yet.
-
-**This is the one deliberate exception** to Pattern otherwise having [no
-filesystem/git access to your repo](#per-project-judgment-ledger) at all
-(the principle `report_build_cost`/`report_outcome_proxy` are built
-around). It's narrow on purpose:
-
-- `git rev-parse HEAD` (read-only, never touches repo state) to capture
-  `snapshot_ref` on every ledger write.
+Both are now fully addressed, across five tools:
+[`check_ledger_liveness`](#tool-check_ledger_liveness) and
+[`sweep_ledger_liveness`](#tool-sweep_ledger_liveness) close the first gap;
+[`export_ledger_provenance`](#tool-export_ledger_provenance),
+[`backfill_ledger_snapshot_ref`](#tool-backfill_ledger_snapshot_ref), and
+[`post_ledger_provenance_to_github`](#tool-post_ledger_provenance_to_github)
+close the second. See `pattern-ledger-integrity-and-provenance-spec.md`
+for the original phased plan this was built against.
+
+**This required the one deliberate exception** to Pattern otherwise having
+[no filesystem/git access to your repo](#per-project-judgment-ledger) at
+all (the principle `report_build_cost`/`report_outcome_proxy` are built
+around). Still narrow, still all read-only, and still nothing here ever
+writes to your repo or runs an arbitrary git/shell command:
+
+- `git rev-parse HEAD`, on every ledger write, to capture `snapshot_ref`.
+- `git log --before=<timestamp> -1 --format=%H`, only inside
+  `backfill_ledger_snapshot_ref`, to reconstruct a best-effort
+  `snapshot_ref` for an entry that predates it.
 - `fs.existsSync` plus a plain-text read of one file, only for a
   `file_path` you explicitly passed to `recommend_component`, only inside
-  `PROJECT_ROOT` (see below), to answer `check_ledger_liveness`.
-
-Nothing here runs an arbitrary git or shell command, and nothing writes to
-your repo.
+  `PROJECT_ROOT` (see below) -- what
+  [`check_ledger_liveness`](#tool-check_ledger_liveness)/[`sweep_ledger_liveness`](#tool-sweep_ledger_liveness)
+  check. `post_ledger_provenance_to_github` additionally makes a real,
+  visible network call to the GitHub API -- see that tool's own docs,
+  it's a materially different kind of exception (a third-party service,
+  not your local machine) from the four above.
 
 ### `PROJECT_ROOT`
 
@@ -1182,11 +1534,12 @@ original judgment's snapshot, look up the entry named in its
 [`export_ledger_provenance`](#tool-export_ledger_provenance) packages one
 entry's full record -- checklist, candidates, verdict, `snapshot_ref` --
 into a markdown block you can paste into a PR or issue by hand.
-
-Not yet built (P2-P3 of Feature 2): the MCP action to post that artifact
-to a GitHub PR/issue automatically (blocked on an open question -- personal
-token vs. GitHub App -- see BACKLOG.md), and provenance backfill for
-entries that predate `snapshot_ref`.
+[`post_ledger_provenance_to_github`](#tool-post_ledger_provenance_to_github)
+posts that same artifact automatically, idempotently, using a personal
+`GITHUB_TOKEN` rather than a GitHub App (see that tool's docs for why).
+[`backfill_ledger_snapshot_ref`](#tool-backfill_ledger_snapshot_ref)
+reconstructs a best-effort `snapshot_ref` for entries that predate the
+field, always clearly labeled as reconstructed wherever it's rendered.
 
 ### Referential integrity: `file_path` / `live_status`
 
@@ -1203,26 +1556,26 @@ check whether that file still exists and still mentions
   `PROJECT_ROOT`, or the file exists but `chosen_candidate` can't be
   confirmed in it. Deliberately the default outcome for anything
   ambiguous: a false `"orphaned"` is worse than a lingering `"unknown"`.
-- **`dangling`** -- reserved, not yet produced. Feature 1's second
-  staleness type (a cluster of entries that only reference each other,
-  with no live anchor anywhere) is graph-level analysis across the whole
-  ledger, not a single-entry check -- P3, not built here.
-
-Checks are on-demand only right now (call `check_ledger_liveness`
-yourself, or on whatever schedule you want) -- there's no automatic
-sweep. `live_status`/`last_verified_live` start `"unknown"`/`null` on
-every entry at write time and only ever advance via a
-`check_ledger_liveness` call; results are stored append-only in
-`~/.pattern/ledger_liveness.jsonl` (override with
-`PATTERN_LEDGER_LIVENESS_PATH`, same "append, never mutate the source
-line, most recent record wins at read time" convention as
+- **`dangling`** -- only ever produced by
+  [`sweep_ledger_liveness`](#tool-sweep_ledger_liveness), never by
+  `check_ledger_liveness` on its own: a cluster of 2+ entries sharing a
+  `feature_id` where none of them resolved to `"live"`. Graph-level
+  analysis across a project's whole entry set, not a single-entry check
+  -- see that tool's docs for why `feature_id` is the grouping used.
+
+`check_ledger_liveness` remains on-demand and single-project;
+[`sweep_ledger_liveness`](#tool-sweep_ledger_liveness) is the
+scheduled/batch counterpart -- meant to be invoked by your own cron/CI,
+since Pattern has no scheduler of its own. `live_status`/`last_verified_live`
+start `"unknown"`/`null` on every entry at write time and only ever
+advance via a `check_ledger_liveness`/`sweep_ledger_liveness` call;
+results are stored append-only in `~/.pattern/ledger_liveness.jsonl`
+(override with `PATTERN_LEDGER_LIVENESS_PATH`, same "append, never mutate
+the source line, most recent record wins at read time" convention as
 `outcome_proxies.jsonl`, see [Outcome proxies](#outcome-proxies)) and
 layered onto `ledger.jsonl`'s own entries at read time -- the ledger line
 itself is never rewritten.
 
-Not yet built (P2-P3 of Feature 1): a scheduled/batch sweep across an
-entire ledger, and dangling-cluster detection.
-
 ## Per-project decision memory
 
 Pattern stores confirmed decisions locally in:
@@ -1451,6 +1804,38 @@ Pattern caches its system instructions using `cache_control: ephemeral`.
 The instructions are the same across calls, so repeated requests don't
 pay the full input cost for that block.
 
+### Measured cache and fetch behavior
+
+`_meta.tokens_used.input_breakdown` splits input tokens into `fresh`,
+`cache_write`, and `cache_read` (see [The `_meta`
+field](#the-_meta-field)) -- added specifically to check assumptions
+about caching against real numbers rather than guessing. Two real
+findings so far:
+
+- **A single, non-repeat call is not "all fresh."** The working
+  assumption had been that only exact-repeat calls (the [ledger cache
+  hit](#the-cache-hit-exception)) benefit from caching at all. A live
+  test disproved that: a fresh, non-repeat toast-component call came back
+  with roughly half its input tokens served from `cache_read`. A
+  follow-up 4-case sample (2026-09-02, spanning a clean `use_existing`
+  call, a `custom_build` call, and two historically boundary/inconsistent
+  cases) confirmed this wasn't a fluke -- `cache_read` share stayed in a
+  46-63% band across all four, regardless of call shape.
+- **`fresh` (fully-priced, never-cached) tokens are driven by whether the
+  call reaches step 6's Mobbin/Figma reference search, not by general
+  complexity or the boundary-risk ensemble firing.** In that same
+  4-case sample, the two `use_existing` calls had negligible `fresh`
+  tokens (0.2%); both `custom_build` calls (which searched Mobbin/Figma)
+  had 24-27.5% `fresh` -- even though, in both of those cases, the actual
+  Mobbin *fetch* failed (`url_not_accessible`, 0 bytes returned). That
+  rules out fetched-page content size as the driver for this cost --
+  it's the extra Mobbin/Figma-restricted *search* calls themselves. This
+  is why [`PATTERN_FETCH_MAX_CONTENT_TOKENS`](#fetch-grounded-scoring-and-reference-verification)
+  was trimmed (a fetch-content cap can't fix a search-call cost) rather
+  than split per-step as originally considered, and why reducing
+  Mobbin/Figma search overhead is tracked as its own, differently-scoped
+  future item rather than folded into that change.
+
 ### Search limits
 
 Pattern limits candidate discovery to 3 web searches -- one per source.
@@ -1488,9 +1873,12 @@ the category page), there's no safe fallback for an unverified met/not-met
 call, so nothing is silently corrected -- `scoring_fetch` just tells you
 whether the grounding actually ran.
 
-A fetch can read up to 15,000 content tokens. `web_fetch` has no separate
-per-call fee; the cost comes from the content added to the model's
-context.
+A fetch can read up to `PATTERN_FETCH_MAX_CONTENT_TOKENS` content tokens
+(default 12,000 -- trimmed from 15,000 after a real instrumentation
+sample showed the largest actual fetched page was ~10.7k tokens, see
+[Measured cache and fetch behavior](#measured-cache-and-fetch-behavior)
+above). `web_fetch` has no separate per-call fee; the cost comes from the
+content added to the model's context.
 
 ### Choosing a cheaper model
 
@@ -1727,6 +2115,25 @@ search or code problem.
 
 The boundary-risk ensemble exists to detect and surface this uncertainty.
 
+### A missed match in your own design system isn't automatically re-checked
+
+In [design-system mode](#tool-register_design_system), the model can say
+`custom_build`/`no_candidates_found` even when a real, relevant candidate
+is sitting right in its own prompt -- a reading-comprehension miss over a
+fully-known candidate list, not a live-search gap. The boundary-risk
+ensemble above doesn't catch this: it only re-checks a `"scored"` result
+near the 40%/80% threshold, never a `"no_candidates_found"` verdict.
+
+The [keyword-overlap safety net](#a-safety-net-for-a-missed-match) flags
+this risk (`design_system_recall_check` on the response) but does not fix
+it -- it's a detection layer, not a re-check. The actual fix (re-running
+the model on a suspicious `no_candidates_found` verdict, the same way a
+close `"scored"` call already gets re-checked) is scoped but not built.
+`custom_build` ledger entries in this mode also record zero candidates
+(`candidates_evaluated: []`), same as the external-library path, so a
+genuine miss and a correct "nothing here" still look identical in
+`read_ledger` afterward unless the recall check happened to catch it.
+
 ### A staged pipeline was evaluated and not adopted
 
 To address the variance above, an alternative architecture was built and