pattern-mcp 0.2.0 → 0.3.0

package/README.md

@@ -5,8 +5,9 @@
 [![npm downloads](https://img.shields.io/npm/dm/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 helps coding agents make better UI
-component decisions.
+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.
 
 [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)
 
@@ -31,7 +32,7 @@ whether to:
 
 Pattern is designed for agents to use **while they are building**.
 
-It exposes three tools:
+It exposes four tools:
 
 - `recommend_component` — evaluates a UI component need and returns a
   structured recommendation.
@@ -41,6 +42,9 @@ It exposes three tools:
 - `record_component_decision` — records what the agent actually did so
   future recommendations in the same project can take that decision into
   account.
+- `read_ledger` — lists past `recommend_component` judgments for a
+  `project_id`, including any that were served from the ledger cache (see
+  [Per-project judgment ledger](#per-project-judgment-ledger)).
 
 ## How it works
 
@@ -70,6 +74,9 @@ A result can also be:
 - `custom_build`
 - `no_candidates_found`
 - `skip_list`
+- `ledger_cache_hit` — served from a recent, matching prior judgment
+  instead of a fresh search+score (see
+  [Per-project judgment ledger](#per-project-judgment-ledger)).
 
 `no_candidates_found` is kept separate from a low-coverage result. Not
 finding a candidate is different from finding candidates that don't cover
@@ -78,7 +85,14 @@ the requirements.
 If `project_id` is supplied, Pattern also checks for past confirmed
 decisions on that project and factors them in as a consistency signal —
 never a rule that overrides a genuinely better match found in the current
-search.
+search. Separately, `project_id` also enables the judgment ledger: a
+high-confidence prior judgment matching this exact
+component_need/domain/framework/existing_stack, recorded recently enough,
+can be served directly (`ledger_cache_hit`) instead of running a fresh
+search+score. This is the one deliberate exception to "every recommendation
+searches and scores again" — see
+[Per-project judgment ledger](#per-project-judgment-ledger) for the exact
+rules and why it's safe.
 
 Every result includes `computed_at`, because coverage is a snapshot of the
 search at that point in time, not a permanent fact. Every result also
@@ -600,7 +614,8 @@ Anthropic API call.
   "domain": "Airbnb-style rental marketplace",
   "action": "custom_built",
   "source": "custom",
-  "timestamp": "2026-08-25T14:32:00.000Z"
+  "timestamp": "2026-08-25T14:32:00.000Z",
+  "time_saved_minutes": 25
 }
 ```
 
@@ -609,6 +624,15 @@ Anthropic API call.
 - `action` must be `"installed"` or `"custom_built"`.
 - `source` can be `"shadcn"`, `"21st.dev"`, `"reui"`, or `"custom"`.
 - `timestamp` is optional. If omitted, Pattern uses the current time.
+- `time_saved_minutes` is optional -- the calling agent's own estimate,
+  in minutes, of how much time this decision saved by having Pattern's
+  verdict instead of researching candidates and judging fit from scratch.
+  This is entirely self-reported. Pattern has no way to measure a
+  counterfactual ("how long would this have taken without Pattern?"), so
+  unlike `_meta` (Pattern's own real cost/latency for the call that
+  produced the verdict), this number is never computed or verified --
+  it's just recorded as-given. Omit it rather than guess a number to fill
+  the field.
 
 ### Output
 
@@ -620,6 +644,131 @@ Anthropic API call.
 }
 ```
 
+## Tool: `read_ledger`
+
+Lists past `recommend_component` judgments for a `project_id` -- every
+call that reached the API and produced a verdict, not just ones explicitly
+confirmed via `record_component_decision`. Useful for auditing what
+Pattern has already judged for a project, or for understanding why a call
+came back with `served_from_ledger: true`.
+
+### Input
+
+```json
+{
+  "project_id": "my-booking-app",
+  "component_need": "cancellation",
+  "limit": 10
+}
+```
+
+- `project_id` is required.
+- `component_need` is optional -- a simple keyword filter (substring
+  match, no embeddings) against stored entries' `component_need`. Omit to
+  list everything for the project.
+- `limit` is optional, defaults to 20. Most recent entries first.
+
+### Output
+
+```json
+{
+  "project_id": "my-booking-app",
+  "entries": [
+    {
+      "id": "a1b2c3d4-...",
+      "timestamp": "2026-08-29T19:50:47.073Z",
+      "project_id": "my-booking-app",
+      "component_need": "cancellation policy display with refund tiers by date",
+      "domain": "Airbnb-style rental marketplace",
+      "framework": "React + Tailwind",
+      "checklist": ["...", "..."],
+      "checklist_source": "extracted",
+      "candidates_evaluated": [
+        { "source": "ReUI (reui.io)", "name": "Timeline", "url": "https://reui.io/components/timeline", "coverage_pct": 62.5 }
+      ],
+      "verdict": "use_existing",
+      "chosen_candidate": "Timeline",
+      "confidence": "low",
+      "reason": "scored",
+      "coverage": "5/8 (62.5%)",
+      "project_conventions_snapshot": "9f3a1c7e2b0d4f5a"
+    }
+  ]
+}
+```
+
+Each entry holds only distilled fields -- `candidates_evaluated` never
+contains raw HTML, full prop tables, or the per-requirement evidence text
+`recommend_component` itself returns. See
+[Data minimization](#data-minimization) below.
+
+## Per-project judgment ledger
+
+Distinct from [per-project decision memory](#per-project-decision-memory)
+below -- that file only gains an entry when `record_component_decision` is
+explicitly called. The ledger instead gains one entry automatically for
+**every** `recommend_component` call that reaches the API with a
+`project_id` and lands on reason `"scored"` or `"no_candidates_found"`.
+
+Pattern stores it locally in:
+
+```
+~/.pattern/ledger.jsonl
+```
+
+Change the location with `PATTERN_LEDGER_PATH`. One JSON object per line
+(append-only, JSONL).
+
+### The cache-hit exception
+
+Every other part of Pattern scores fresh every time (see
+[No caching, by design](#no-caching-by-design)). The ledger is the one
+deliberate exception: a later `recommend_component` call with a matching
+`project_id` **can** be served directly from a prior entry, skipping
+search+score entirely, when **all** of the following hold:
+
+- `component_need` matches exactly (case-insensitive).
+- `domain` and `framework` match exactly.
+- `existing_stack` hashes to the same value as the stored entry's
+  (both omitted counts as a match).
+- The stored entry's `confidence` is `"high"`.
+- The stored entry's `reason` is `"scored"` or `"no_candidates_found"`.
+- The stored entry is no older than `PATTERN_LEDGER_TTL_DAYS` (default
+  **30** days, configurable).
+
+When served this way, the response has `reason: "ledger_cache_hit"`,
+`served_from_ledger: true`, `ledger_entry_id`, and
+`original_verdict_timestamp` -- so nothing is ever silently passed off as
+freshly verified. `_meta.estimated_cost_usd` and `tokens_used` are
+genuinely `0`: no API call happened. `requirements_checked` is `null` on
+this path -- the ledger never stores per-requirement evidence text (see
+[Data minimization](#data-minimization)), so a cache hit can only replay
+the verdict/confidence/coverage/chosen-candidate, not the original
+per-requirement reasoning.
+
+Any mismatch on the criteria above -- a different `domain`, a changed
+`existing_stack`, an entry that's gone stale, or one that wasn't
+high-confidence -- falls through to a normal, fresh search+score call.
+
+### Turning the cache-hit exception off
+
+Set `PATTERN_NO_LEDGER_CACHE_HIT` (any truthy value) to restore
+"every `recommend_component` call always scores fresh" without removing
+any ledger code. This disables only the cache-hit short-circuit --
+entries are still written to `ledger.jsonl` and `read_ledger` still works
+either way, so the audit trail keeps growing even with the switch on.
+Unset the variable to re-enable cache hits again at any time.
+
+### Data minimization
+
+Nothing written to the ledger ever contains raw search/fetch content.
+Every candidate is reduced to exactly four fields before it's written --
+`source`, `name`, `url`, `coverage_pct` -- enforced at the type level
+(`assertDistilledCandidateShape` in `src/index.ts`), not just by
+convention: a raw or extended object throws rather than silently
+persisting. Run `node scripts/verify-ledger-boundary.mjs` (after
+`npm run build`) to check this boundary directly.
+
 ## Per-project decision memory
 
 Pattern stores confirmed decisions locally in:
@@ -644,12 +793,16 @@ The file is organized by project:
       "domain": "Airbnb-style rental marketplace",
       "action": "custom_built",
       "source": "custom",
-      "timestamp": "2026-08-25T14:32:00.000Z"
+      "timestamp": "2026-08-25T14:32:00.000Z",
+      "time_saved_minutes": 25
     }
   ]
 }
 ```
 
+`time_saved_minutes` is omitted from an entry entirely when the calling
+agent didn't provide one -- it's never backfilled or estimated by Pattern.
+
 Each project keeps its 50 most recent decisions. Older entries are
 removed as new ones are added.
 
@@ -668,12 +821,13 @@ sensitive information in them. See [SECURITY.md](./SECURITY.md).
 A failure to write the decision file is returned as an error from
 `record_component_decision`.
 
-**No caching, by design.** Project memory does not cache recommendations.
-A previous decision is only additional context for a new judgment. Every
-`recommend_component` call performs a fresh search and recalculates
-coverage. This means Pattern can use past decisions to improve
-consistency without letting stale decisions replace current evidence —
-see [Known limitations](#known-limitations) for more.
+**No caching, by design.** Project memory (this file, `memory.json`) does
+not cache recommendations. A previous decision is only additional context
+for a new judgment. This is unrelated to the
+[judgment ledger](#per-project-judgment-ledger)'s bounded cache-hit
+exception, which lives in a separate file (`ledger.jsonl`) and is always
+flagged (`served_from_ledger: true`) when it happens — see
+[Known limitations](#known-limitations) for more.
 
 ## Security and privacy
 
@@ -692,19 +846,28 @@ Pattern uses the Anthropic API, so `recommend_component` has a cost.
 
 A typical single pass costs about $0.06–$0.10 with Sonnet 5 at current
 pricing. Skip-listed primitives cost $0 because they're handled locally
-and never reach the API.
+and never reach the API. A [ledger cache hit](#the-cache-hit-exception)
+also costs $0, for the same reason -- no API call happens.
 
 ### The `_meta` field
 
 Every `recommend_component` and `extract_requirements` response includes
-an internal `_meta` block reporting what that call actually spent:
+an internal `_meta` block reporting what that call actually spent. This
+is not shown to the user automatically -- the calling agent has to
+surface it, the same way it's separately instructed to show
+`install_command` before running it (see
+[above](#installation-commands-are-not-trusted)). Both tool descriptions
+say so explicitly: surface `_meta.estimated_cost_usd` after the call,
+since it's real spend against the user's own API key, not internal
+bookkeeping.
 
 ```json
 {
   "total_ms": 41516,
   "breakdown_ms": { "extract": 5006, "search": 3114, "score": 33396 },
   "tokens_used": { "input": 8400, "output": 620 },
-  "estimated_cost_usd": 0.14
+  "estimated_cost_usd": 0.14,
+  "scoring_fetch": { "attempted": true, "succeeded": true, "url": "https://ui.shadcn.com/docs/components/..." }
 }
 ```
 
@@ -719,6 +882,14 @@ an internal `_meta` block reporting what that call actually spent:
   discounts.
 - `breakdown_ms` -- how `total_ms` splits across `recommend_component`'s
   three internal phases.
+- `scoring_fetch` -- whether step 4's single candidate-verification fetch
+  (see [Fetch-grounded scoring](#fetch-grounded-scoring-and-reference-verification)
+  below) actually happened for this response. `url` is `null` when
+  `attempted` is `false` (no real candidate to verify, e.g. `reason:
+  "no_candidates_found"` or `"skip_list"`). This is a diagnostic only --
+  Pattern never uses it to auto-correct `requirements_checked` after the
+  fact, since there's no safe fallback value for an unverified met/not-met
+  call the way there is for a reference URL.
 
 **How `breakdown_ms` is measured, and its one real caveat.** The bundled
 call runs extraction, search, and scoring inside a single model turn
@@ -746,6 +917,10 @@ not the wall-clock time you waited. The three ensemble passes run with the
 2nd and 3rd concurrent, so perceived latency is closer to ~2x one pass,
 not the ~3x `total_ms` will show. Cost and token spend are genuinely
 additive across reruns, which is what `_meta` is reporting there.
+`scoring_fetch` is the one exception -- it isn't summed (a fetch either
+happened for the specific pass whose evidence became the returned
+`requirements_checked`, or it didn't), so it reports that winning pass's
+own value, not an aggregate across all three.
 
 Three things help keep the cost down without changing the decision process.
 
@@ -770,18 +945,33 @@ shadcn/ui, 21st.dev, and ReUI are searched in the same turn rather than
 sequentially, which reduces how much conversation context needs to be
 sent repeatedly.
 
-### Reference verification
-
-Pattern allows up to 2 `web_fetch` calls, used only to verify reference
-URLs.
+### Fetch-grounded scoring and reference verification
+
+Pattern allows up to 3 `web_fetch` calls per pass: 1 reserved for scoring,
+2 reserved for reference verification (1 for Mobbin, 1 for Figma
+Community).
+
+Before finalizing coverage, Pattern fetches the best-fitting candidate's
+own real docs/source page once and re-checks the checklist against that
+page, not just the search-result snippet it started with. This exists
+because search-result descriptions can both overstate a component's real
+capabilities and miss real ones it actually has -- both were observed in
+testing on the same case (an invented feature claim and a missed real
+one). If the fetch fails, or there's no confirmed URL to fetch, Pattern
+falls back to search-only evidence and says so in the affected items.
+
+Each result's `_meta.scoring_fetch` reports whether this fetch actually
+happened for that response (`{ attempted, succeeded, url }`) -- it's a
+diagnostic, not something Pattern uses to auto-correct individual
+requirement judgments. Unlike a reference URL (which has a safe fallback:
+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.
 
-Pattern does not use `web_fetch` during requirement scoring. It's
-reserved for verifying reference links.
-
 ### Choosing a cheaper model
 
 You can change the model with:
@@ -1047,22 +1237,32 @@ pipeline is still fully bundled; nothing about this evaluation changed.
 
 ### No caching, by design
 
-Every recommendation searches and scores again.
+Every recommendation searches and scores again -- with one bounded
+exception (see below).
 
 This means a recommendation can change as component libraries change.
 For example, a later shadcn/ui release can introduce a component that
 changes a previous `custom_build` result.
 
-Do not persist a recommendation across sessions or builds at the
-calling-agent layer.
-
-If you add caching, keep it session-scoped.
+Do not build a second, unbounded cache of recommendations at the
+calling-agent layer on top of Pattern's own. If you add caching there,
+keep it session-scoped.
 
 [Project decision memory](#per-project-decision-memory) does not change
 this. It provides context from previous decisions, but every
 `recommend_component` call still performs a fresh search and scoring
 pass.
 
+The one deliberate exception is the
+[judgment ledger's cache-hit path](#the-cache-hit-exception): a later
+call matching an exact, recent, high-confidence prior judgment can be
+served without a fresh search+score. It's bounded (exact
+component_need/domain/framework/conventions match, a staleness TTL) and
+always self-identifies via `served_from_ledger: true` and
+`reason: "ledger_cache_hit"` -- so a calling agent that wants a guaranteed
+fresh check on every call should look for that flag and treat it the same
+as any other verdict it wants to double-check.
+
 ### The skip-list is still evolving
 
 The primitive skip-list is a starting point and has not yet been

package/dist/index.js

@@ -2,23 +2,35 @@
 /**
  * Pattern
  *
- * MCP server exposing two tools. `recommend_component` judges whether a UI
+ * MCP server exposing tools built around one judgment: whether a UI
  * component need should be met with an existing shadcn/ui, 21st.dev, or
  * ReUI (reui.io) component, or requires a custom build guided by a
- * real-app reference from Mobbin. `record_component_decision` appends a
- * confirmed decision to local per-project memory (see MEMORY_PATH below),
- * which recommend_component can optionally read back (via project_id) as
- * consistency context for a future call -- never as a cached verdict;
- * coverage is still scored fresh every time.
+ * real-app reference from Mobbin.
  *
- * The judgment logic (extract requirements -> search -> score real code ->
- * threshold into a verdict) is delegated to a single Anthropic API call
- * with the server-side web_search tool enabled, so the same reasoning
+ * Two separate local stores back this, with two different rules:
+ *  - `record_component_decision` appends a confirmed decision to local
+ *    per-project memory (see MEMORY_PATH below), which recommend_component
+ *    can optionally read back (via project_id) as consistency context for
+ *    a future call -- never as a cached verdict; coverage is still scored
+ *    fresh every time. Unchanged, still true.
+ *  - Every recommend_component call that reaches the API instead appends
+ *    to a per-project ledger (see LEDGER_PATH below). Unlike memory.json,
+ *    a high-confidence ledger entry CAN be served directly on a later,
+ *    matching call instead of a fresh search+score -- the one deliberate
+ *    exception to "always fresh," bounded by exact component_need/domain/
+ *    framework/conventions match and a staleness TTL, and always flagged
+ *    via `served_from_ledger: true` in the response so nothing is silently
+ *    passed off as freshly verified. See findLedgerCacheHit.
+ *
+ * The judgment logic itself (extract requirements -> search -> score real
+ * code -> threshold into a verdict) is delegated to a single Anthropic API
+ * call with the server-side web_search tool enabled, so the same reasoning
  * this project validated by hand in conversation is what runs here.
  */
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createHash, randomUUID } from "node:crypto";
 import { appendFileSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
@@ -100,6 +112,30 @@ const LOG_PATH = process.env.PATTERN_LOG_PATH ?? join(homedir(), ".pattern", "ca
 // of what's in this file (see README's "no verdict caching" rule).
 const MEMORY_PATH = process.env.PATTERN_MEMORY_PATH ?? join(homedir(), ".pattern", "memory.json");
 const MAX_DECISIONS_PER_PROJECT = 50;
+// Per-project judgment ledger -- distinct from both LOG_PATH and
+// MEMORY_PATH above. Every recommend_component call that reaches the API
+// with a project_id and lands on reason "scored" or "no_candidates_found"
+// appends one line here (see appendLedgerEntry), unlike MEMORY_PATH which
+// only gains an entry when record_component_decision is explicitly called.
+// Unlike MEMORY_PATH, this file's entries CAN produce a cached verdict on a
+// later call (see findLedgerCacheHit) -- the one deliberate exception to
+// this project's "coverage is scored fresh every time" rule, bounded by
+// exact component_need/domain/framework/conventions match, confidence
+// "high", and LEDGER_TTL_DAYS staleness, and always flagged in the
+// response via served_from_ledger so nothing is silently passed off as
+// fresh. Same homedir/project_id-keyed convention as LOG_PATH/MEMORY_PATH,
+// not a repo-root file -- this server has no concept of "which repo" a
+// call is about, only the caller-supplied project_id string.
+const LEDGER_PATH = process.env.PATTERN_LEDGER_PATH ?? join(homedir(), ".pattern", "ledger.jsonl");
+const LEDGER_TTL_DAYS = Number(process.env.PATTERN_LEDGER_TTL_DAYS ?? 30);
+// Kill switch for the cache-hit short-circuit specifically -- does NOT
+// disable the ledger itself. Entries still get written and read_ledger
+// still works either way; this only controls whether judgeComponent is
+// allowed to skip a fresh search+score on a matching entry. Set
+// PATTERN_NO_LEDGER_CACHE_HIT (any truthy value) to revert to "every
+// recommend_component call always scores fresh" without removing any
+// ledger code -- flip it back off (unset the var) to re-enable.
+const LEDGER_CACHE_HIT_ENABLED = !process.env.PATTERN_NO_LEDGER_CACHE_HIT;
 // $/1M tokens, checked against the Anthropic pricing page rather than
 // recalled from training data (rates drift). Both current and legacy
 // Haiku 4.5 model-id spellings are listed since PATTERN_MODEL is
@@ -338,6 +374,7 @@ async function streamAnthropicMessage(body) {
 const TOOL_NAME = "recommend_component";
 const RECORD_DECISION_TOOL_NAME = "record_component_decision";
 const EXTRACT_REQUIREMENTS_TOOL_NAME = "extract_requirements";
+const READ_LEDGER_TOOL_NAME = "read_ledger";
 const INPUT_SCHEMA = {
     type: "object",
     properties: {
@@ -367,8 +404,14 @@ const INPUT_SCHEMA = {
                 "belongs to. When provided, past decisions confirmed via " +
                 "record_component_decision for this same project_id are surfaced to " +
                 "the model as a consistency signal (never a rule -- a genuinely " +
-                "better match found in this search still wins). Omit to skip memory " +
-                "lookup entirely; this never falls back to a shared/global bucket.",
+                "better match found in this search still wins). Separately, this call " +
+                "may also be served directly from a recent, high-confidence prior " +
+                "recommend_component judgment for this same project_id/component_need/" +
+                "domain/framework/existing_stack, skipping search+score entirely -- " +
+                "check the response for served_from_ledger: true, which is always set " +
+                "when this happens; see read_ledger to inspect what's stored. Omit " +
+                "project_id to skip both lookups entirely; neither ever falls back to " +
+                "a shared/global bucket.",
         },
         checklist: {
             type: "array",
@@ -428,9 +471,35 @@ const RECORD_DECISION_INPUT_SCHEMA = {
             type: "string",
             description: "Optional. ISO 8601 timestamp of the decision. Defaults to the current time if omitted.",
         },
+        time_saved_minutes: {
+            type: "number",
+            description: "Optional. Your own estimate, in minutes, of the time this decision saved you by having " +
+                "Pattern's verdict instead of researching candidates and judging fit yourself from scratch. " +
+                "This is self-reported by the calling agent -- Pattern has no way to measure a counterfactual, " +
+                "so it never computes this itself (unlike _meta, which is Pattern's own real cost/latency). " +
+                "Omit if you don't have a meaningful estimate; never guess a number just to fill the field.",
+        },
     },
     required: ["project_id", "component_need", "action", "source"],
 };
+const READ_LEDGER_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        project_id: {
+            type: "string",
+            description: "The project_id used in prior recommend_component calls whose ledger entries you want to inspect.",
+        },
+        component_need: {
+            type: "string",
+            description: "Optional. Filters entries by simple keyword match against their component_need. Omit to list all entries for the project.",
+        },
+        limit: {
+            type: "number",
+            description: "Optional. Maximum number of entries to return, most recent first. Defaults to 20.",
+        },
+    },
+    required: ["project_id"],
+};
 // Shared between buildSystemPrompt's own step 2 and
 // buildExtractionSystemPrompt (the extract_requirements tool's standalone
 // prompt) -- the extraction *instructions* are one piece of text reused
@@ -466,7 +535,9 @@ Search shadcn/ui, 21st.dev, and ReUI (reui.io) for components matching the need,
 If search returns zero real candidates -- not just weak matches, but nothing relevant at all (e.g. only vendor policy pages, unrelated components) -- stop here and return verdict "custom_build" with reason "no_candidates_found". Do not fabricate a coverage score in this case; omit requirements_checked and coverage entirely.
 
 4. SCORE COVERAGE AGAINST THE CHECKLIST
-For each real candidate, evaluate against the checklist using actual evidence you can find about the component's real props/structure/code -- not just its marketing description, since descriptions can claim functionality the component doesn't actually have. Mark each requirement met or not-met with a one-line reason. Compute coverage = (requirements met) / (total requirements) for the best-fitting candidate. Base this only on your web_search results from step 3 -- do not use the web_fetch tool here or anywhere in steps 2-5; it is reserved entirely for step 6's reference deep-link check below, and using it earlier can starve that reserved budget.
+For each real candidate, evaluate against the checklist using actual evidence you can find about the component's real props/structure/code -- not just its marketing description, since descriptions can claim functionality the component doesn't actually have. Mark each requirement met or not-met with a one-line reason. Compute coverage = (requirements met) / (total requirements) for the best-fitting candidate.
+
+Before finalizing that coverage score, fetch the best-fitting candidate's own real docs/source page ONCE with the web_fetch tool -- a reserved slot exists for exactly this, separate from step 6's reference-verification budget below, so using it here will not starve that reserved budget. Re-check every requirement against what that fetched page actually says, not just the web_search snippet/description you started with -- a search result can describe functionality a component doesn't actually have, or omit a real prop/feature it does have, and only the fetched page is real evidence either way. Only fetch a URL that a real search result in step 3 actually returned -- never construct or guess one. If the fetch fails, or there's no confirmed URL to fetch, score from the web_search evidence alone and say so in the affected items' evidence text. This one candidate-verification fetch is the only exception to "no web_fetch in steps 2-5" -- it remains reserved for step 6's reference deep-link check otherwise.
 
 5. APPLY VERDICT THRESHOLDS
 coverage >= 80% -> verdict "use_existing", confidence "high"
@@ -592,10 +663,13 @@ async function runSinglePass(input) {
         };
     }
     // Coverage still computes fresh below regardless of what this finds --
-    // memory only ever adds context to the user message, it never short-
-    // circuits search/scoring or gets treated as a cached verdict. No
-    // project_id -> no lookup at all, not a shared/global fallback (see
-    // getPastDecisions).
+    // memory (MEMORY_PATH/record_component_decision) only ever adds context
+    // to the user message, it never short-circuits search/scoring or gets
+    // treated as a cached verdict. No project_id -> no lookup at all, not a
+    // shared/global fallback (see getPastDecisions). This is distinct from
+    // the ledger cache-hit check in judgeComponent, which CAN skip this
+    // entire function on a matching high-confidence entry -- that check
+    // happens one level up, before runSinglePass is ever called.
     const pastDecisions = input.project_id ? getPastDecisions(input.project_id) : [];
     const pastDecisionsBlock = pastDecisions.length === 0
         ? ""
@@ -668,13 +742,20 @@ existing_stack: ${input.existing_stack ?? "(not specified)"}${checklistBlock}${p
             {
                 type: "web_fetch_20250910",
                 name: "web_fetch",
-                // Exactly one fetch per reference source (Mobbin, Figma
-                // Community) -- step 6 fetches the search result page to look
-                // for a deep link to the specific screen/flow already
-                // identified, never more than once per source. Not reserved
-                // from the web_search budget above; this is a separate tool
-                // with its own separate cap.
-                max_uses: 2,
+                // 3 reserved slots, same "reserve, don't let an earlier step
+                // starve a later one's budget" pattern as web_search's
+                // SEARCH_BUDGET + 2 above: 1 for step 4's single candidate-
+                // verification fetch (re-checking the best-fitting candidate's
+                // real docs against the checklist, added to catch evidence
+                // errors search-snippet-only scoring was producing -- confirmed
+                // live: an invented feature claim and a missed real one, both on
+                // the same case, both from trusting search snippets over the
+                // actual page), and 2 for step 6's Mobbin + Figma Community
+                // deep-link checks (exactly one fetch per reference source,
+                // never more than once per source). Not reserved from the
+                // web_search budget above; this is a separate tool with its own
+                // separate cap.
+                max_uses: 3,
                 // Category/browse pages can be large, and all we need from them
                 // is a permalink, not the full page -- caps token cost of a
                 // fetch that turns out not to have a deep link after all.
@@ -804,6 +885,7 @@ existing_stack: ${input.existing_stack ?? "(not specified)"}${checklistBlock}${p
     // other enforce* functions above.
     parsed.checklist_source = checklistSource;
     parsed._meta = buildMeta(data.timings, data.usage);
+    parsed._meta.scoring_fetch = findScoringFetch(fetchCallDetails);
     // Same "server-side, not just prompt instruction" policy as the rest of
     // this file: a past_decision_signal is only trusted when this call
     // actually had past-decision context to consider. Strips a fabricated
@@ -1007,6 +1089,12 @@ function recordDecision(input) {
         action: input.action,
         source: input.source,
         timestamp: input.timestamp ?? new Date().toISOString(),
+        // Finite-number guard only -- no range/sanity clamp, since a caller's
+        // own estimate isn't Pattern's to second-guess. NaN/Infinity would
+        // corrupt memory.json's JSON on write, so those alone are rejected.
+        time_saved_minutes: typeof input.time_saved_minutes === "number" && Number.isFinite(input.time_saved_minutes)
+            ? input.time_saved_minutes
+            : undefined,
     };
     const memory = readMemory();
     const existing = memory[input.project_id] ?? [];
@@ -1022,6 +1110,93 @@ export function getPastDecisions(projectId) {
     const memory = readMemory();
     return memory[projectId] ?? [];
 }
+function hashConventions(existingStack) {
+    if (!existingStack)
+        return null;
+    return createHash("sha256").update(existingStack).digest("hex").slice(0, 16);
+}
+// Same "missing/malformed collapses to empty" philosophy as readMemory,
+// but line-oriented (JSONL) rather than whole-file JSON -- a single
+// corrupted line (e.g. a hand-edited file, or a write that got cut off)
+// is skipped rather than failing the whole read.
+function readLedgerEntries(projectId) {
+    let raw;
+    try {
+        raw = readFileSync(LEDGER_PATH, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === "object" && parsed.project_id === projectId) {
+                entries.push(parsed);
+            }
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return entries;
+}
+// The only entry point that writes ledger.jsonl. Validates every
+// candidate against the DistilledCandidate boundary before it ever touches
+// disk -- a raw object reaching here throws rather than silently
+// persisting (see assertDistilledCandidateShape).
+function appendLedgerEntry(entry) {
+    for (const candidate of entry.candidates_evaluated) {
+        assertDistilledCandidateShape(candidate);
+    }
+    mkdirSync(dirname(LEDGER_PATH), { recursive: true });
+    appendFileSync(LEDGER_PATH, JSON.stringify(entry) + "\n", "utf8");
+}
+// Verdict-serving match: deliberately stricter than findLedgerMatches
+// below (exact component_need/domain/framework, not keyword overlap)
+// since this decides whether a fresh API call gets skipped entirely, not
+// just what gets listed back to a caller browsing history.
+function findLedgerCacheHit(input, entries) {
+    const snapshot = hashConventions(input.existing_stack);
+    const needLower = input.component_need.trim().toLowerCase();
+    const ttlMs = LEDGER_TTL_DAYS * 24 * 60 * 60 * 1000;
+    const now = Date.now();
+    const eligible = entries.filter((e) => {
+        if (e.component_need.trim().toLowerCase() !== needLower)
+            return false;
+        if (e.domain !== input.domain)
+            return false;
+        if (e.framework !== input.framework)
+            return false;
+        if (e.project_conventions_snapshot !== snapshot)
+            return false;
+        if (e.confidence !== "high")
+            return false;
+        if (e.reason !== "scored" && e.reason !== "no_candidates_found")
+            return false;
+        const age = now - new Date(e.timestamp).getTime();
+        if (!Number.isFinite(age) || age > ttlMs)
+            return false;
+        return true;
+    });
+    if (eligible.length === 0)
+        return null;
+    return eligible.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime())[0];
+}
+// Broader listing for the read_ledger tool itself -- simple keyword match
+// on component_need (no embeddings, per the build plan's explicit v1
+// scope), not the strict exact match findLedgerCacheHit needs.
+function findLedgerMatches(projectId, componentNeed, limit = 20) {
+    let entries = readLedgerEntries(projectId);
+    if (componentNeed && componentNeed.trim()) {
+        const needle = componentNeed.trim().toLowerCase();
+        entries = entries.filter((e) => e.component_need.toLowerCase().includes(needle));
+    }
+    entries.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+    return entries.slice(0, limit);
+}
 // Orchestrates the ensemble: run once, and only pay for 2 more full
 // pipeline passes when the single-run result landed close enough to a
 // verdict threshold that a single item's judgment swinging could flip
@@ -1053,7 +1228,75 @@ function aggregateMeta(passes) {
         estimated_cost_usd: Math.round(metas.reduce((sum, m) => sum + m.estimated_cost_usd, 0) * 10000) / 10000,
     };
 }
+// Builds the LedgerEntry appended after a fresh (non-cache-hit) judgment.
+// checklist/checklist_source come from the result itself, not input.checklist
+// -- that field captures what was actually scored regardless of whether the
+// caller pre-supplied it or this call extracted it internally.
+function buildLedgerEntry(input, projectId, result) {
+    const candidate = distillCandidate(result);
+    const checklist = Array.isArray(result.requirements_checked)
+        ? result.requirements_checked.map((r) => r.requirement).filter((r) => !!r)
+        : [];
+    return {
+        id: randomUUID(),
+        timestamp: new Date().toISOString(),
+        project_id: projectId,
+        component_need: input.component_need,
+        domain: input.domain,
+        framework: input.framework,
+        checklist,
+        checklist_source: result.checklist_source ?? "extracted",
+        candidates_evaluated: candidate ? [candidate] : [],
+        verdict: result.verdict,
+        chosen_candidate: candidate?.name ?? null,
+        confidence: result.confidence,
+        reason: result.reason,
+        coverage: result.coverage ?? null,
+        project_conventions_snapshot: hashConventions(input.existing_stack),
+    };
+}
 async function judgeComponent(input) {
+    // The one deliberate exception to "coverage is scored fresh every time"
+    // (see file header and runSinglePass's memory-lookup comment) -- bounded
+    // by exact component_need/domain/framework/conventions match, confidence
+    // "high", and LEDGER_TTL_DAYS staleness. Checked before the skip-list
+    // fast-path so a skip-list primitive never bothers with a ledger read.
+    // Gated by LEDGER_CACHE_HIT_ENABLED (PATTERN_NO_LEDGER_CACHE_HIT) so the
+    // "always fresh" behavior can be restored without removing this code.
+    const ledgerCacheHit = LEDGER_CACHE_HIT_ENABLED && !isSkipListMatch(input.component_need) && input.project_id
+        ? findLedgerCacheHit(input, readLedgerEntries(input.project_id))
+        : null;
+    if (ledgerCacheHit) {
+        console.error(JSON.stringify({
+            diagnostic: "ledger_cache_hit",
+            project_id: input.project_id,
+            ledger_entry_id: ledgerCacheHit.id,
+            original_timestamp: ledgerCacheHit.timestamp,
+        }));
+        const candidate = ledgerCacheHit.candidates_evaluated[0] ?? null;
+        const result = {
+            verdict: ledgerCacheHit.verdict,
+            confidence: ledgerCacheHit.confidence,
+            reason: "ledger_cache_hit",
+            coverage: ledgerCacheHit.coverage,
+            requirements_checked: null,
+            recommendation: candidate
+                ? { source: candidate.source, install_command: null, component_description: candidate.name, reference: null }
+                : null,
+            ensemble: { triggered: false },
+            checklist_source: ledgerCacheHit.checklist_source,
+            served_from_ledger: true,
+            ledger_entry_id: ledgerCacheHit.id,
+            original_verdict_timestamp: ledgerCacheHit.timestamp,
+            _meta: {
+                total_ms: 1,
+                breakdown_ms: { extract: 1, search: 0, score: 0 },
+                tokens_used: { input: 0, output: 0 },
+                estimated_cost_usd: 0,
+            },
+        };
+        return JSON.stringify(result);
+    }
     // Session cap and local logging both apply only to calls that actually
     // reach the API -- skip-list hits never do, so both are excluded here
     // on the same condition rather than counted/logged and refunded.
@@ -1075,6 +1318,9 @@ async function judgeComponent(input) {
         first.result.ensemble = { triggered: false };
         if (reachesApi)
             logCall(input, first.result);
+        if (reachesApi && input.project_id && (first.result.reason === "scored" || first.result.reason === "no_candidates_found")) {
+            appendLedgerEntry(buildLedgerEntry(input, input.project_id, first.result));
+        }
         return JSON.stringify(first.result);
     }
     console.error(JSON.stringify({
@@ -1111,7 +1357,16 @@ async function judgeComponent(input) {
     if (majorityCount < passes.length)
         base.confidence = "low";
     base.ensemble = { triggered: true, runs: verdicts, agreement };
+    // Captured before aggregateMeta overwrites base._meta (same object as
+    // winningPass.result._meta) with a fresh summed-across-passes object --
+    // scoring_fetch isn't summed like cost/tokens, it describes whichever
+    // single pass's evidence actually became requirements_checked/
+    // recommendation below, so it must come from the winning pass
+    // specifically, not be dropped by aggregateMeta not knowing about it.
+    const winningScoringFetch = winningPass.result._meta?.scoring_fetch;
     base._meta = aggregateMeta(passes) ?? base._meta;
+    if (base._meta)
+        base._meta.scoring_fetch = winningScoringFetch;
     console.error(JSON.stringify({
         diagnostic: "ensemble_decision",
         runs: verdicts,
@@ -1123,6 +1378,9 @@ async function judgeComponent(input) {
     // reachable for calls that passed the skip-list check above -- always
     // reachesApi === true here, no guard needed.
     logCall(input, base);
+    if (input.project_id && (base.reason === "scored" || base.reason === "no_candidates_found")) {
+        appendLedgerEntry(buildLedgerEntry(input, input.project_id, base));
+    }
     return JSON.stringify(base);
 }
 // The model's stated `coverage` string doesn't always match its own
@@ -1177,6 +1435,38 @@ export function parseCoveragePercent(coverage) {
     }
     return null;
 }
+const ALLOWED_DISTILLED_CANDIDATE_KEYS = new Set(["source", "name", "url", "coverage_pct"]);
+// Throws rather than silently stripping unknown keys -- a raw object
+// reaching this function is a bug (some caller skipped distillCandidate),
+// and failing loudly is what makes "Pattern never persists scraped source"
+// a checkable claim rather than a hopeful one.
+export function assertDistilledCandidateShape(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error("DistilledCandidate must be a plain object");
+    }
+    const keys = Object.keys(value);
+    const extra = keys.filter((k) => !ALLOWED_DISTILLED_CANDIDATE_KEYS.has(k));
+    if (extra.length > 0) {
+        throw new Error(`DistilledCandidate has disallowed key(s): ${extra.join(", ")}`);
+    }
+}
+// Only ever called for verdict "use_existing" with a populated
+// recommendation -- custom_build has no existing candidate to distill, so
+// candidates_evaluated/chosen_candidate stay empty/null in the ledger for
+// those. `url` reuses the already fetch-verified scoring_fetch URL
+// (see JudgmentResult._meta.scoring_fetch) rather than inventing a second
+// notion of "the candidate's real page" -- if that fetch didn't happen or
+// failed, url is null rather than falling back to an unverified guess.
+export function distillCandidate(result) {
+    if (result.verdict !== "use_existing" || !result.recommendation)
+        return null;
+    return {
+        source: result.recommendation.source ?? null,
+        name: result.recommendation.component_description ?? null,
+        url: result._meta?.scoring_fetch?.succeeded ? result._meta.scoring_fetch.url ?? null : null,
+        coverage_pct: parseCoveragePercent(result.coverage),
+    };
+}
 export function enforceVerdictThreshold(parsed) {
     if (parsed.reason !== "scored")
         return;
@@ -1275,6 +1565,20 @@ export const DOMAIN_FOR_SOURCE_KEYWORD = {
     mobbin: "mobbin.com",
     figma: "figma.com",
 };
+// Distinguishes step 4's single candidate-verification fetch from step 6's
+// Mobbin/Figma reference fetches -- both use the same web_fetch tool and
+// the same reserved budget's underlying diagnostics, so this identifies
+// step 4's fetch as whichever call (if any) targets a domain that ISN'T a
+// reference source. Diagnostic only, feeding _meta.scoring_fetch -- never
+// used to correct or invalidate individual requirement judgments (see that
+// field's own comment for why there's no safe fallback to correct to).
+export function findScoringFetch(fetchCallDetails) {
+    const referenceDomains = Object.values(DOMAIN_FOR_SOURCE_KEYWORD);
+    const candidateFetch = fetchCallDetails.find((d) => d.url && !referenceDomains.some((domain) => d.url.includes(domain)));
+    if (!candidateFetch)
+        return { attempted: false, succeeded: false, url: null };
+    return { attempted: true, succeeded: candidateFetch.succeeded, url: candidateFetch.url ?? null };
+}
 // Figma Community's own URL structure makes a "/community/file/<id>/<slug>"
 // URL inherently specific to one file -- unlike Mobbin's "/explore/..."
 // category pages, there's no browse-vs-specific gap to resolve here.
@@ -1438,7 +1742,11 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "Omit it to keep today's default behavior unchanged. The response " +
                 "always includes checklist_source ('extracted' | 'provided') and " +
                 "an internal _meta block (timing/token/cost accounting) -- neither " +
-                "affects the verdict itself.",
+                "affects the verdict itself. Surface _meta.estimated_cost_usd to " +
+                "the user after the call (e.g. 'that judgment cost ~$0.12'), the " +
+                "same way install_command is shown before running -- it's real " +
+                "spend against the user's own API key, not internal bookkeeping " +
+                "to keep from them.",
             inputSchema: INPUT_SCHEMA,
         },
         {
@@ -1454,7 +1762,9 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "heuristic based on how specific component_need is, not a " +
                 "calibrated signal -- treat 'low' as a hint to reread the input, " +
                 "not a hard error. Cheaper and faster than recommend_component " +
-                "since it makes no search calls at all.",
+                "since it makes no search calls at all. Also returns an internal " +
+                "_meta block -- surface _meta.estimated_cost_usd to the user " +
+                "after the call, same as recommend_component.",
             inputSchema: EXTRACT_REQUIREMENTS_INPUT_SCHEMA,
         },
         {
@@ -1467,9 +1777,27 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "calls with the same project_id will see this decision as a " +
                 "consistency signal, not a binding rule. Use a stable project_id " +
                 "(e.g. the project's directory path or name) so decisions are " +
-                "grouped correctly and never mixed with another project's.",
+                "grouped correctly and never mixed with another project's. Pass " +
+                "time_saved_minutes (optional) if you have a genuine estimate of how " +
+                "much time this decision saved you -- this is your own self-reported " +
+                "number, never computed or verified by Pattern.",
             inputSchema: RECORD_DECISION_INPUT_SCHEMA,
         },
+        {
+            name: READ_LEDGER_TOOL_NAME,
+            description: "Lists past recommend_component judgment entries for a project_id -- " +
+                "every call that reached the API and produced a verdict, not just " +
+                "ones you explicitly confirmed via record_component_decision. Each " +
+                "entry holds only distilled fields (verdict, confidence, coverage, " +
+                "chosen candidate's source/name/url) -- never the original " +
+                "per-requirement evidence text. Useful for auditing what Pattern has " +
+                "already judged for a project, or for understanding why a later " +
+                "call came back with served_from_ledger: true (see recommend_component " +
+                "-- a high-confidence entry here, matching on component_need/domain/" +
+                "framework/existing_stack and recent enough, can be served directly " +
+                "instead of a fresh search+score).",
+            inputSchema: READ_LEDGER_INPUT_SCHEMA,
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -1538,13 +1866,37 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
         }
     }
+    if (request.params.name === READ_LEDGER_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            const entries = findLedgerMatches(args.project_id, args.component_need, args.limit);
+            return {
+                content: [{ type: "text", text: JSON.stringify({ project_id: args.project_id, entries }) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    }
     throw new Error(`Unknown tool: ${request.params.name}`);
 });
 async function main() {
     const transport = new StdioServerTransport();
     await server.connect(transport);
 }
-main().catch((err) => {
-    console.error("Fatal error starting pattern-mcp:", err);
-    process.exit(1);
-});
+// Guard exists so verification scripts (e.g. verify-ledger-boundary.mjs)
+// can import this module's exported pure functions (distillCandidate,
+// assertDistilledCandidateShape, parseCoveragePercent, etc.) without also
+// spinning up a stdio server that blocks on stdin. Real usage (the bin
+// entry point, `npx pattern-mcp`) never sets this, so autostart is
+// unaffected.
+if (!process.env.PATTERN_NO_AUTOSTART) {
+    main().catch((err) => {
+        console.error("Fatal error starting pattern-mcp:", err);
+        process.exit(1);
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pattern-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "MCP tool that judges whether a UI component need should be met with an existing shadcn/ui, 21st.dev, or ReUI component or requires a custom build, using field/requirement coverage scored against real component code.",
   "type": "module",
   "main": "dist/index.js",