pattern-mcp 0.6.0 → 0.8.0

package/dist/index.js

@@ -32,9 +32,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { execFileSync } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { captureApiError, captureRecommendation, printTelemetryNoticeOnce, shutdownTelemetry, } from "./telemetry.js";
 export const ANTHROPIC_API_KEY = process.env.ANTHROPIC_API_KEY;
 // Configurable so Sonnet vs. Haiku can be A/B tested without a code change.
@@ -59,6 +59,34 @@ const SEARCH_BUDGET = SEARCH_BUDGET_RAW.trim().toLowerCase() === "unlimited"
         }
         return parsed;
     })();
+// Cost/latency reduction plan, step 2 (BACKLOG.md): trimmed from 15,000
+// after a real 4-case instrumentation sample (2026-09-02) showed the
+// largest actual fetched page was ~10.7k tokens (a shadcn doc page),
+// comfortably under this new cap with headroom. Deliberately NOT split
+// into separate step-4 (candidate-doc) vs. step-6 (Mobbin/Figma) caps as
+// originally scoped: both steps share one web_fetch tool instance, so a
+// real split would mean defining two separately-named web_fetch tools and
+// trusting the model to pick the right one per step -- a real behavior
+// risk for a saving the same sample disproved anyway. Both custom_build
+// cases in that sample had elevated "fresh" (fully-priced, uncached)
+// token counts even though their Mobbin fetch *failed*
+// (url_not_accessible, 0 bytes returned) -- the cost driver there is the
+// extra Mobbin/Figma-restricted search calls, not fetched content size,
+// so this cap can't address it. (The Mobbin fetch failures themselves
+// were later confirmed, 2026-09-02, to be Mobbin blocking Anthropic's
+// fetch bot specifically -- the same URL 403s to that bot and 200s to a
+// generic user agent -- the same structural problem already known for
+// Figma's robots.txt block, just a different enforcement mechanism. See
+// the step-6 system prompt's Mobbin note below.) That's tracked as a separate, differently
+// -scoped backlog item, not folded into this one.
+const FETCH_MAX_CONTENT_TOKENS_RAW = process.env.PATTERN_FETCH_MAX_CONTENT_TOKENS ?? "12000";
+const FETCH_MAX_CONTENT_TOKENS = (() => {
+    const parsed = Number.parseInt(FETCH_MAX_CONTENT_TOKENS_RAW, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`PATTERN_FETCH_MAX_CONTENT_TOKENS must be a positive integer, got: ${FETCH_MAX_CONTENT_TOKENS_RAW}`);
+    }
+    return parsed;
+})();
 // Static skip-list: single-purpose primitives with no meaningful internal
 // structure to score coverage against. Decided in the product brief as a
 // starting point -- revisit once real usage data exists (see README).
@@ -114,6 +142,16 @@ 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;
+// Registered design systems (Solo Dev architecture,
+// pattern-solo-design-system-architecture.md) -- one registration per
+// project_id, config-shaped like MEMORY_PATH (overwritten wholesale by a
+// fresh register_design_system call, not appended to). Same homedir
+// convention as LOG_PATH/MEMORY_PATH/LEDGER_PATH: a local file keyed by
+// the caller-supplied project_id string, no server-side component. When a
+// project has a registration, recommend_component scores ONLY against it
+// (one-or-the-other per project, not additive with shadcn/21st.dev/reui --
+// see runSinglePass's designSystem branch).
+const DESIGN_SYSTEMS_PATH = process.env.PATTERN_DESIGN_SYSTEMS_PATH ?? join(homedir(), ".pattern", "design_systems.json");
 // 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"
@@ -188,6 +226,31 @@ function computeSnapshotRef(root) {
         return null;
     }
 }
+// Feature 2 / Decision Provenance, P3: best-effort reconstruction of
+// snapshot_ref for an entry written before that field existed (or written
+// outside a git repo -- though a project that's never used git has
+// nothing to reconstruct from either way). Finds the commit that was HEAD
+// at or just before the entry's own timestamp. Necessarily an
+// approximation, not a guarantee: a rebase, force-push, or history
+// rewrite since that time can make "the commit HEAD pointed to then" no
+// longer resolve to what the codebase actually looked like at judgment
+// time -- exactly the risk the spec's own mitigation table already names.
+// Read-only, same timeout/error-swallowing discipline as
+// computeSnapshotRef above.
+function reconstructSnapshotRef(root, atISOTimestamp) {
+    try {
+        const sha = execFileSync("git", ["log", `--before=${atISOTimestamp}`, "-1", "--format=%H"], {
+            cwd: root,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 2000,
+        }).trim();
+        return /^[0-9a-f]{7,40}$/i.test(sha) ? sha : null;
+    }
+    catch {
+        return null;
+    }
+}
 // 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
@@ -443,6 +506,10 @@ const REPORT_BUILD_COST_TOOL_NAME = "report_build_cost";
 const REPORT_OUTCOME_PROXY_TOOL_NAME = "report_outcome_proxy";
 const CHECK_LEDGER_LIVENESS_TOOL_NAME = "check_ledger_liveness";
 const EXPORT_LEDGER_PROVENANCE_TOOL_NAME = "export_ledger_provenance";
+const POST_LEDGER_PROVENANCE_TOOL_NAME = "post_ledger_provenance_to_github";
+const SWEEP_LEDGER_LIVENESS_TOOL_NAME = "sweep_ledger_liveness";
+const BACKFILL_LEDGER_SNAPSHOT_REF_TOOL_NAME = "backfill_ledger_snapshot_ref";
+const REGISTER_DESIGN_SYSTEM_TOOL_NAME = "register_design_system";
 const INPUT_SCHEMA = {
     type: "object",
     properties: {
@@ -692,6 +759,72 @@ const EXPORT_LEDGER_PROVENANCE_INPUT_SCHEMA = {
     },
     required: ["project_id", "ledger_entry_id"],
 };
+const POST_LEDGER_PROVENANCE_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        project_id: {
+            type: "string",
+            description: "The project_id used in the recommend_component call that produced this ledger entry.",
+        },
+        ledger_entry_id: {
+            type: "string",
+            description: "The specific entry to post, from read_ledger or check_ledger_liveness.",
+        },
+        repo: {
+            type: "string",
+            description: 'GitHub repo in "owner/repo" form, e.g. "my-org/my-booking-app".',
+        },
+        issue_number: {
+            type: "number",
+            description: "The PR or issue number to comment on -- GitHub treats both identically for comments, so no separate type flag is needed.",
+        },
+    },
+    required: ["project_id", "ledger_entry_id", "repo", "issue_number"],
+};
+const SWEEP_LEDGER_LIVENESS_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        project_id: {
+            type: "string",
+            description: "Optional. Scope the sweep to one project_id. Omit to sweep every " +
+                "project_id present in the ledger -- the whole-ledger, scheduler-driven " +
+                "mode this tool exists for.",
+        },
+    },
+    required: [],
+};
+const BACKFILL_LEDGER_SNAPSHOT_REF_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        project_id: {
+            type: "string",
+            description: "The project_id whose ledger entries to backfill.",
+        },
+        ledger_entry_id: {
+            type: "string",
+            description: "Optional. Backfill just this one entry instead of every entry for project_id missing snapshot_ref.",
+        },
+    },
+    required: ["project_id"],
+};
+const REGISTER_DESIGN_SYSTEM_INPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        project_id: {
+            type: "string",
+            description: "The project this registration belongs to -- must match the project_id used in recommend_component calls for it to be scored against. Registering a design system replaces (does not merge with) any prior registration for this same project_id, and switches recommend_component to score ONLY against it for this project -- shadcn/ui, 21st.dev, and ReUI are no longer searched once a project has a registration.",
+        },
+        manifest_path: {
+            type: "string",
+            description: "Path to a components manifest, relative to the project root (PATTERN_PROJECT_ROOT, defaults to this server's working directory) -- never an absolute path. Two recognized shapes: a hand-authored JSON array of {name, props, description, usage_example} objects (optionally wrapped in {\"components\": [...]}); or a Storybook-exported stories/index JSON file (an object with a top-level \"entries\" or \"stories\" map) -- component names only in that case, since Storybook's basic export doesn't carry prop data. Exactly one of manifest_path or directory_path is required.",
+        },
+        directory_path: {
+            type: "string",
+            description: "Path to a directory of component source files, relative to the project root -- never an absolute path. Scanned recursively for .jsx/.tsx/.js/.ts files (excluding node_modules/dist/build/.git and test/story files); each exported, uppercase-named function or const component found is a candidate, with props read from a `<Name>Props` interface/type, a `.propTypes` block, or (as a last resort) the component's own destructured parameters. This is a heuristic scan, not a full parser -- an empty or partial props list for some components is expected, not a bug, especially on plain JS with no prop typing at all. Exactly one of manifest_path or directory_path is required.",
+        },
+    },
+    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
@@ -701,6 +834,54 @@ const EXPORT_LEDGER_PROVENANCE_INPUT_SCHEMA = {
 // tools at all). This is what "factor it out into a shared function" means
 // here: the wording, not a shared HTTP call.
 const EXTRACTION_INSTRUCTIONS = "Turn the component need + domain into a concrete checklist of elements the component must contain -- specific enough to check against real code, not a vibe. Ground it in the stated domain, not the component name alone. Extract exactly 8 checklist items, ranked by importance to the component's core function (most important first) -- a fixed count, not a range, so coverage = met/total isn't itself a moving target across runs.";
+// Shared between buildSystemPrompt and buildDesignSystemSystemPrompt --
+// step 6 (custom_build reference grounding via Mobbin/Figma Community) is
+// entirely candidate-source-agnostic: it fires identically whether step 3
+// discovered candidates via live search or scored against a registered
+// design system, so this is one wording, not two copies that could drift
+// out of sync (see EXTRACTION_INSTRUCTIONS's comment for the same
+// "factor out the wording, not a function" reasoning).
+const CUSTOM_BUILD_REFERENCE_INSTRUCTIONS = `Search TWO reference sources, one search call each (two calls total, reserved separately from the discovery budget above):
+- Mobbin (site:mobbin.com) for the closest real-app screen matching the stated domain (e.g. real Airbnb screens for an Airbnb-style app).
+- Figma Community (site:figma.com/community) for a relevant real component or template file matching the stated domain and component need. Plain web search only -- there is no Figma API token available, don't attempt to use one.
+
+A search result URL is very often a category/browse page (e.g. mobbin.com/explore/mobile/screens/notifications), not a direct link to the specific screen or flow you actually identified (e.g. "Saturn Calendar - Notifications List"). Figma Community results are different: a URL containing "/community/file/" is already file-specific by Figma's own URL structure -- there is nothing more specific to find, so leave it as-is and do not spend a fetch on it. Only a Figma result that is NOT a "/community/file/" URL (a browse/tag/search page, e.g. figma.com/community/mobile-apps) has the same category-vs-specific gap Mobbin has.
+
+For each Mobbin result, and for any Figma Community result that isn't already a "/community/file/" URL: fetch that result's URL with the web_fetch tool (reserved separately from both search budgets above, and separately from steps 2-5 -- see step 4) and look in the fetched page content for a more specific permalink pointing at that same specific screen or flow you already identified. Use that permalink as the reference "url" ONLY if you can actually see it written in the fetched content -- never construct, guess, or pattern-match your way to a deep-link URL that isn't literally present on the page, even if you're confident you know the site's URL scheme. Note that Figma's robots.txt blocks automated fetching of the entire site, so a Figma category-page fetch will very likely fail outright -- that's expected, not a bug. Mobbin fetches are also very likely to fail: Mobbin blocks Anthropic's fetch bot specifically (confirmed directly -- the same URL that 403s to that bot returns 200 to a generic browser user agent), so treat a failed Mobbin fetch the same way, expected, not a sign anything went wrong. Each source gets at most ONE fetch attempt: if it fails for any reason, do not retry it by guessing a different URL variant for the same page (e.g. adding or removing a path segment) -- that guessed variant isn't a URL you actually found, it's exactly the kind of construction this process forbids, and the tool will reject it anyway since it never appeared in a real search or fetch result. Accept the failure and move on. If a fetch fails, or the fetched page doesn't expose a more specific link (login-gated, or the specific screen genuinely isn't linkable separately from the browse view), keep the category/search URL as "url" and say so plainly in "reference_description" -- e.g. "This is a Mobbin search entry point for the notifications category, not a direct link to the Saturn Calendar screen described below" -- so the reader knows they're landing on a browse page and will need to find the specific screen themselves.
+
+Include a reference for each source that actually returned a real, relevant result from a search you actually ran -- never name a plausible-sounding URL from memory for either source. If out of search budget, or a search found nothing relevant, that source is simply not included; there is no benefit to guessing, since anything not backed by an actual successful search for that source will be silently discarded server-side. The same no-fabrication rule applies to the fetch step: a claimed deep-link URL that isn't backed by an actual fetch of that page literally containing that link will be silently replaced server-side with the honest category-URL fallback, so there is no benefit to guessing there either.
+
+Shape the "reference" field based on how many sources actually grounded:
+- Both Mobbin and Figma Community grounded: an array of both reference objects.
+- Only one grounded: a single reference object (not a one-element array).
+- Neither grounded: omit "reference" entirely (null), same as a custom_build verdict with no usable reference at all today.
+
+Each reference object has: "source" ("Mobbin" or "Figma Community"), "url", and either "flow_name" (Mobbin) or "file_name" (Figma Community) -- whichever matches its own source. Each also gets its own "reference_description": 1-2 sentences of plain-language description of what that specific screen or file actually shows -- specific enough that an agent that can't open the URL still has something to act on. E.g. "Airbnb's checkout screen shows the cancellation policy as an expandable section below the price breakdown, with the exact refund percentage next to each date threshold." Base each description only on what you actually saw in that source's own search result, not a generic guess, and not by borrowing detail from the other source.`;
+// Shared for the same reason as CUSTOM_BUILD_REFERENCE_INSTRUCTIONS above
+// -- step 8 doesn't depend on where candidates came from, only on whether
+// past-decision context was included in the user message.
+const PAST_DECISION_SIGNAL_INSTRUCTIONS = `Include a top-level "past_decision_signal" field in your response: { "considered": true|false, "note": "string" }. Set "considered": true only if at least one listed past decision was genuinely similar enough to this need that it actually factored into your scoring or recommendation -- not just present in the list. "note" is one sentence: if considered is true, name which past decision and how it factored in (e.g. "Consistent with this project's prior custom build of a similar price breakdown component"); if false, one sentence on why none applied (e.g. "No past decision matches this need closely enough to be a relevant signal"). This field is mandatory whenever the section is present in the user message -- do not omit it, and do not include it at all if the section was absent.`;
+// Shared for the same reason -- the response contract itself doesn't
+// depend on candidate source either.
+const JUDGMENT_RESPONSE_SHAPE = `Respond with ONLY a single JSON object, no prose before or after, no markdown code fences, matching this exact shape:
+
+{
+  "verdict": "use_existing" | "custom_build",
+  "confidence": "high" | "medium" | "low",
+  "reason": "scored" | "no_candidates_found" | "skip_list",
+  "computed_at": "<today's date, ISO format>",
+  "requirements_checked": [ { "requirement": "string", "met": true|false, "evidence": "string" } ] | null,
+  "coverage": "string like '5/7 (71%)'" | null,
+  "oversized_match": true|false | omit if verdict is not use_existing,
+  "oversized_match_note": "string, required when oversized_match is true" | omit otherwise,
+  "recommendation": {
+    "source": "string or null",
+    "install_command": "string or null",
+    "component_description": "string (use_existing only) or null",
+    "reference": { "source": "Mobbin" | "Figma Community", "url": "string", "flow_name": "string (Mobbin only)", "file_name": "string (Figma Community only)", "reference_description": "string" } | [ /* same shape, up to 2 entries, one per source */ ] | null
+  },
+  "past_decision_signal": { "considered": true|false, "note": "string" } | omit this field entirely if step 8 doesn't apply
+}`;
 function buildSystemPrompt(searchBudget, opts) {
     const budgetLine = searchBudget === null
         ? "Budget: no fixed limit on search calls for candidate discovery -- search as much as genuinely helps you find and verify real candidates, but don't search redundantly once you have enough to score confidently."
@@ -760,48 +941,81 @@ If the verdict is use_existing, include "component_description": 1-2 sentences o
 "install_command" is untrusted text as far as the calling agent is concerned -- it comes from a web search result you read, not a verified package registry. Keep it to the single literal install command only (e.g. npx shadcn@latest add <component>), never chained with && or ; , piped into a shell, or bundled with any other command. The calling agent is separately instructed to show this to its user for confirmation before running it, not execute it silently -- don't write it in a way that assumes or requires automatic execution.
 
 6. IF custom_build
-Search TWO reference sources, one search call each (two calls total, reserved separately from the discovery budget above):
-- Mobbin (site:mobbin.com) for the closest real-app screen matching the stated domain (e.g. real Airbnb screens for an Airbnb-style app).
-- Figma Community (site:figma.com/community) for a relevant real component or template file matching the stated domain and component need. Plain web search only -- there is no Figma API token available, don't attempt to use one.
+${CUSTOM_BUILD_REFERENCE_INSTRUCTIONS}
 
-A search result URL is very often a category/browse page (e.g. mobbin.com/explore/mobile/screens/notifications), not a direct link to the specific screen or flow you actually identified (e.g. "Saturn Calendar - Notifications List"). Figma Community results are different: a URL containing "/community/file/" is already file-specific by Figma's own URL structure -- there is nothing more specific to find, so leave it as-is and do not spend a fetch on it. Only a Figma result that is NOT a "/community/file/" URL (a browse/tag/search page, e.g. figma.com/community/mobile-apps) has the same category-vs-specific gap Mobbin has.
+7. EXISTING STACK TIEBREAKER
+If existing_stack is provided and two candidates score similarly, prefer the one matching the existing stack. Never use it as a hard filter that excludes a genuinely better-scoring candidate from a different source.
 
-For each Mobbin result, and for any Figma Community result that isn't already a "/community/file/" URL: fetch that result's URL with the web_fetch tool (reserved separately from both search budgets above, and separately from steps 2-5 -- see step 4) and look in the fetched page content for a more specific permalink pointing at that same specific screen or flow you already identified. Use that permalink as the reference "url" ONLY if you can actually see it written in the fetched content -- never construct, guess, or pattern-match your way to a deep-link URL that isn't literally present on the page, even if you're confident you know the site's URL scheme. Note that Figma's robots.txt blocks automated fetching of the entire site, so a Figma category-page fetch will very likely fail outright -- that's expected, not a bug. Each source gets at most ONE fetch attempt: if it fails for any reason, do not retry it by guessing a different URL variant for the same page (e.g. adding or removing a path segment) -- that guessed variant isn't a URL you actually found, it's exactly the kind of construction this process forbids, and the tool will reject it anyway since it never appeared in a real search or fetch result. Accept the failure and move on. If a fetch fails, or the fetched page doesn't expose a more specific link (login-gated, or the specific screen genuinely isn't linkable separately from the browse view), keep the category/search URL as "url" and say so plainly in "reference_description" -- e.g. "This is a Mobbin search entry point for the notifications category, not a direct link to the Saturn Calendar screen described below" -- so the reader knows they're landing on a browse page and will need to find the specific screen themselves.
+8. PAST DECISION SIGNAL (only if the user message included a "Past confirmed decisions in this project" section)
+${PAST_DECISION_SIGNAL_INSTRUCTIONS}
 
-Include a reference for each source that actually returned a real, relevant result from a search you actually ran -- never name a plausible-sounding URL from memory for either source. If out of search budget, or a search found nothing relevant, that source is simply not included; there is no benefit to guessing, since anything not backed by an actual successful search for that source will be silently discarded server-side. The same no-fabrication rule applies to the fetch step: a claimed deep-link URL that isn't backed by an actual fetch of that page literally containing that link will be silently replaced server-side with the honest category-URL fallback, so there is no benefit to guessing there either.
+${JUDGMENT_RESPONSE_SHAPE}`;
+}
+// Design-system-scored variant of buildSystemPrompt -- used by
+// runSinglePass instead of buildSystemPrompt whenever the caller's
+// project_id has a registration from register_design_system (see
+// getRegisteredDesignSystem). Steps 1, 2, 5 (skip-list, checklist,
+// thresholds/oversized-match), 6, 7, 8, and the response shape are
+// unchanged in substance from buildSystemPrompt -- only step 3 (discovery)
+// and step 4 (scoring evidence) differ, because there's no live search to
+// run: the candidate pool is already fully known from the registration,
+// passed inline in the user message (see runSinglePass's designSystemBlock).
+function buildDesignSystemSystemPrompt(opts) {
+    const step2 = opts?.checklistProvided
+        ? `2. USE THE PROVIDED CHECKLIST
+The user message includes a "Provided checklist" section -- a requirement checklist already prepared for you (either hand-written by the calling agent, or produced by a prior extract_requirements call). Do not extract your own checklist, and do not add, remove, reorder, or reword any item. Treat it as fixed input and score coverage against exactly these items in step 4 below.`
+        : `2. EXTRACT REQUIREMENTS
+${EXTRACTION_INSTRUCTIONS}`;
+    return `You are a UI component judgment layer. Given a component need, you decide whether it should be met with a component already in this project's own registered design system, or requires a custom build guided by a real-app reference. This project has registered its own design system as the candidate pool for this call (see the "Registered design system candidates" section in the user message below) -- score ONLY against those candidates, never against shadcn/ui, 21st.dev, ReUI, or any other external library. You have access to a web_search tool, but it is reserved entirely for step 6 below (custom_build reference grounding) -- do not use it for candidate discovery, there is nothing to discover, the candidate pool is already given to you in full.
 
-Shape the "reference" field based on how many sources actually grounded:
-- Both Mobbin and Figma Community grounded: an array of both reference objects.
-- Only one grounded: a single reference object (not a one-element array).
-- Neither grounded: omit "reference" entirely (null), same as a custom_build verdict with no usable reference at all today.
+If the user message includes a "Past confirmed decisions in this project" section, treat it only as a signal, not a rule: if a highly similar past decision exists, consider consistency with it while scoring and recommending, but don't let it override a genuinely better match among the registered candidates, and don't skip or shortcut your own scoring because a past decision exists. You decide relevance yourself. Step 8 below tells you exactly how to report what you did with it.
 
-Each reference object has: "source" ("Mobbin" or "Figma Community"), "url", and either "flow_name" (Mobbin) or "file_name" (Figma Community) -- whichever matches its own source. Each also gets its own "reference_description": 1-2 sentences of plain-language description of what that specific screen or file actually shows -- specific enough that an agent that can't open the URL still has something to act on. E.g. "Airbnb's checkout screen shows the cancellation policy as an expandable section below the price breakdown, with the exact refund percentage next to each date threshold." Base each description only on what you actually saw in that source's own search result, not a generic guess, and not by borrowing detail from the other source.
+Follow this process exactly:
+
+1. SKIP-LIST CHECK
+If the component need is a trivial, single-purpose primitive with no meaningful internal structure (button, input, checkbox, label, badge, spinner, loader, tooltip, avatar, icon), skip the rest of this process and return verdict "use_existing" with reason "skip_list", confidence "high", and a note that this is a commodity primitive not worth scoring.
+
+${step2}
+
+3. MATCH AGAINST THE REGISTERED DESIGN SYSTEM
+The "Registered design system candidates" section below lists every candidate available for this call: each has a name and, where known, its props and a description/usage example. This data was already extracted from this project's own manifest or component code -- do not search the web for candidates, do not invent props or capabilities beyond what's listed, and do not assume a candidate has a prop just because a similarly-named external component typically would. A candidate with an empty or sparse props list is expected on some registered design systems (a directory scan or a bare-bones manifest can only capture what was actually written) -- score it honestly against what's listed, which will often mean lower coverage or lower confidence, not a bug in this process.
+
+If none of the registered candidates are even plausibly relevant to the component need -- not just a weak match, but nothing on-topic at all -- 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 plausibly relevant registered candidate, evaluate against the checklist using only the props/description/usage_example data given for it in the user message. There is nothing to fetch here -- unlike an external library, this data already IS this project's own real source of truth, not a summary of it. Mark each requirement met or not-met with a one-line reason grounded in what the candidate's listed data actually shows, never a guess at what a component with this name would probably support elsewhere. Compute coverage = (requirements met) / (total requirements) for the best-fitting candidate.
+
+5. APPLY VERDICT THRESHOLDS
+coverage >= 80% -> verdict "use_existing", confidence "high"
+coverage 40-79% -> verdict "use_existing", confidence "low" (list the missing fields)
+coverage < 40% -> verdict "custom_build"
+
+Before finalizing a "high" confidence use_existing verdict, check for an OVERSIZED MATCH: a
+candidate can satisfy every checklist item and still be the wrong call if its real capabilities
+substantially exceed what the stated project scope actually needs. This is a distinct check from
+coverage -- a component can be 100% covered and still be an Oversized Match. Weigh it against what
+the component_need and domain actually state about scale.
+
+Report this via two top-level fields, "oversized_match" (boolean) and "oversized_match_note" (string,
+required when true): set oversized_match true and name the specific excess capability in the note, not
+a vague "this may be more than needed." Do this regardless of what you also write for "confidence"
+below -- the server derives the actual confidence cap from oversized_match deterministically, so don't
+rely on your own "confidence" value alone to carry this signal.
+
+If the verdict is use_existing, include "component_description": 1-2 sentences of plain-language description of what the recommended candidate actually does, grounded only in the data given for it above -- not a generic guess at what a component with this name would typically look like.
+
+"install_command" should be omitted (null) for a registered-design-system candidate -- there is no install step for a component that's already part of this project's own codebase or design spec; the calling agent already has it.
+
+6. IF custom_build
+${CUSTOM_BUILD_REFERENCE_INSTRUCTIONS}
 
 7. EXISTING STACK TIEBREAKER
-If existing_stack is provided and two candidates score similarly, prefer the one matching the existing stack. Never use it as a hard filter that excludes a genuinely better-scoring candidate from a different source.
+If existing_stack is provided and two registered candidates score similarly, prefer the one matching the existing stack. Never use it as a hard filter that excludes a genuinely better-scoring registered candidate.
 
 8. PAST DECISION SIGNAL (only if the user message included a "Past confirmed decisions in this project" section)
-Include a top-level "past_decision_signal" field in your response: { "considered": true|false, "note": "string" }. Set "considered": true only if at least one listed past decision was genuinely similar enough to this need that it actually factored into your scoring or recommendation -- not just present in the list. "note" is one sentence: if considered is true, name which past decision and how it factored in (e.g. "Consistent with this project's prior custom build of a similar price breakdown component"); if false, one sentence on why none applied (e.g. "No past decision matches this need closely enough to be a relevant signal"). This field is mandatory whenever the section is present in the user message -- do not omit it, and do not include it at all if the section was absent.
+${PAST_DECISION_SIGNAL_INSTRUCTIONS}
 
-Respond with ONLY a single JSON object, no prose before or after, no markdown code fences, matching this exact shape:
-
-{
-  "verdict": "use_existing" | "custom_build",
-  "confidence": "high" | "medium" | "low",
-  "reason": "scored" | "no_candidates_found" | "skip_list",
-  "computed_at": "<today's date, ISO format>",
-  "requirements_checked": [ { "requirement": "string", "met": true|false, "evidence": "string" } ] | null,
-  "coverage": "string like '5/7 (71%)'" | null,
-  "oversized_match": true|false | omit if verdict is not use_existing,
-  "oversized_match_note": "string, required when oversized_match is true" | omit otherwise,
-  "recommendation": {
-    "source": "string or null",
-    "install_command": "string or null",
-    "component_description": "string (use_existing only) or null",
-    "reference": { "source": "Mobbin" | "Figma Community", "url": "string", "flow_name": "string (Mobbin only)", "file_name": "string (Figma Community only)", "reference_description": "string" } | [ /* same shape, up to 2 entries, one per source */ ] | null
-  },
-  "past_decision_signal": { "considered": true|false, "note": "string" } | omit this field entirely if step 8 doesn't apply
-}`;
+${JUDGMENT_RESPONSE_SHAPE}`;
 }
 // Standalone prompt for the extract_requirements tool -- shares
 // EXTRACTION_INSTRUCTIONS with buildSystemPrompt's own step 2 (see that
@@ -898,10 +1112,28 @@ async function runSinglePass(input) {
             .map((item, i) => `${i + 1}. ${item}`)
             .join("\n")}`
         : "";
+    // Solo Dev design-system architecture: a project_id with a registration
+    // (see registerDesignSystem) switches this whole call onto
+    // buildDesignSystemSystemPrompt below -- no live search, score directly
+    // against the candidates listed here instead. No registration -> this
+    // stays null and every line below behaves exactly as it did before this
+    // feature existed (see registerDesignSystem's own comment: one-or-the-
+    // other per project, not additive with the external-library path).
+    const designSystem = input.project_id ? getRegisteredDesignSystem(input.project_id) : null;
+    const designSystemBlock = designSystem
+        ? `\n\nRegistered design system candidates (source: ${designSystem.source_kind}, ${designSystem.source_path}):\n${designSystem.candidates
+            .map((c, i) => {
+            const propsPart = c.props.length > 0 ? `props: ${c.props.join(", ")}` : "props: (none captured)";
+            const descPart = c.description ? `; description: ${c.description}` : "";
+            const usagePart = c.usage_example ? `; usage_example: ${c.usage_example}` : "";
+            return `${i + 1}. ${c.name} -- ${propsPart}${descPart}${usagePart}`;
+        })
+            .join("\n")}`
+        : "";
     const userMessage = `component_need: ${input.component_need}
 domain: ${input.domain}
 framework: ${input.framework}
-existing_stack: ${input.existing_stack ?? "(not specified)"}${checklistBlock}${pastDecisionsBlock}`;
+existing_stack: ${input.existing_stack ?? "(not specified)"}${checklistBlock}${pastDecisionsBlock}${designSystemBlock}`;
     // Diagnostic only, same pattern as the other stderr diagnostics in this
     // file -- proves the memory lookup actually reached the prompt sent to
     // the model, not just that it was read from disk successfully.
@@ -928,7 +1160,9 @@ existing_stack: ${input.existing_stack ?? "(not specified)"}${checklistBlock}${p
         system: [
             {
                 type: "text",
-                text: buildSystemPrompt(SEARCH_BUDGET, { checklistProvided: checklistSource === "provided" }),
+                text: designSystem
+                    ? buildDesignSystemSystemPrompt({ checklistProvided: checklistSource === "provided" })
+                    : buildSystemPrompt(SEARCH_BUDGET, { checklistProvided: checklistSource === "provided" }),
                 cache_control: { type: "ephemeral" },
             },
         ],
@@ -950,7 +1184,13 @@ existing_stack: ${input.existing_stack ?? "(not specified)"}${checklistBlock}${p
                 // where 0 Mobbin queries were attempted but a specific Mobbin
                 // URL was still returned. Figma Community gets the same
                 // treatment now that it's a second reference source.
-                ...(SEARCH_BUDGET !== null ? { max_uses: SEARCH_BUDGET + 2 } : {}),
+                //
+                // Design-system-scored calls skip step 3's discovery search
+                // entirely (the candidate pool is already given, not searched
+                // for), so they only ever need the 2 reserved step-6 slots --
+                // fixed at 2 regardless of SEARCH_BUDGET, which governs external-
+                // library discovery only and has no meaning in this mode.
+                ...(designSystem ? { max_uses: 2 } : SEARCH_BUDGET !== null ? { max_uses: SEARCH_BUDGET + 2 } : {}),
             },
             {
                 type: "web_fetch_20250910",
@@ -968,11 +1208,18 @@ existing_stack: ${input.existing_stack ?? "(not specified)"}${checklistBlock}${p
                 // 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,
+                //
+                // Design-system-scored calls have no step-4 verification fetch
+                // (there's no URL to verify -- the registered data already IS the
+                // source of truth, see buildDesignSystemSystemPrompt's step 4),
+                // so only the 2 step-6 slots are reserved.
+                max_uses: designSystem ? 2 : 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.
-                max_content_tokens: 15000,
+                // fetch that turns out not to have a deep link after all. See
+                // FETCH_MAX_CONTENT_TOKENS above for why this is 12,000, not the
+                // original 15,000, and why it isn't split per-step.
+                max_content_tokens: FETCH_MAX_CONTENT_TOKENS,
             },
         ],
     });
@@ -1092,6 +1339,38 @@ existing_stack: ${input.existing_stack ?? "(not specified)"}${checklistBlock}${p
     enforceCoverageRecount(parsed);
     enforceVerdictThreshold(parsed);
     enforceRecommendationConsistency(parsed);
+    // Set server-side, never trusted from the model's own "source" text --
+    // same "server derives what it already knows deterministically" policy
+    // as the other enforce* calls above. A design-system-scored use_existing
+    // verdict always gets the literal string "design_system" here,
+    // regardless of what the model wrote, so downstream consumers (the
+    // ledger, provenance markdown, read_ledger rollups) can match on it
+    // reliably instead of parsing free-text.
+    if (designSystem && parsed.verdict === "use_existing" && parsed.recommendation) {
+        parsed.recommendation.source = "design_system";
+    }
+    // Design-system recall check (see findKeywordOverlapCandidates above):
+    // only meaningful when the model claimed nothing registered was even
+    // plausibly relevant -- a "scored" custom_build already means a real
+    // candidate was found, evaluated, and fell below threshold, a
+    // different, already-instrumented failure mode (requirements_checked
+    // shows exactly what was missing). Logged even on a clean miss (no
+    // overlap found) so the check's own execution is visible in stderr,
+    // not just its hits.
+    if (designSystem && parsed.reason === "no_candidates_found") {
+        const overlap = findKeywordOverlapCandidates(input.component_need, input.domain, designSystem.candidates);
+        console.error(JSON.stringify({
+            diagnostic: "design_system_recall_check",
+            project_id: input.project_id,
+            possible_missed_candidates: overlap.map((m) => m.name),
+        }));
+        if (overlap.length > 0) {
+            parsed.design_system_recall_check = {
+                possible_missed_candidates: overlap,
+                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.",
+            };
+        }
+    }
     // Set server-side rather than trusted from the model -- deterministic
     // from whether input.checklist was actually supplied, same "never trust
     // the model where the server already knows the truth" policy as the
@@ -1323,6 +1602,363 @@ export function getPastDecisions(projectId) {
     const memory = readMemory();
     return memory[projectId] ?? [];
 }
+// Same "malformed/missing collapses to empty, never throws" policy as
+// readMemory -- a fresh install or a hand-edited file that doesn't parse
+// shouldn't break recommend_component for every project, it should just
+// behave as if nothing is registered.
+function readDesignSystems() {
+    try {
+        const raw = readFileSync(DESIGN_SYSTEMS_PATH, "utf8");
+        const parsed = JSON.parse(raw);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+function writeDesignSystems(file) {
+    mkdirSync(dirname(DESIGN_SYSTEMS_PATH), { recursive: true });
+    writeFileSync(DESIGN_SYSTEMS_PATH, JSON.stringify(file, null, 2), "utf8");
+}
+// Read-only lookup used by runSinglePass. No project_id -> no lookup,
+// same "never fall back to a shared/global bucket" rule as
+// getPastDecisions above.
+export function getRegisteredDesignSystem(projectId) {
+    return readDesignSystems()[projectId] ?? null;
+}
+// Extracts the substring between the first "{" at or after fromIndex and
+// its matching "}", tracking brace depth so a nested object type inside a
+// props interface doesn't truncate the capture early -- a plain non-greedy
+// regex on "{...}" breaks on exactly that shape (e.g. `style?: { color:
+// string }`).
+function extractBalancedBraceBody(text, fromIndex) {
+    const openIdx = text.indexOf("{", fromIndex);
+    if (openIdx === -1)
+        return null;
+    let depth = 0;
+    for (let i = openIdx; i < text.length; i++) {
+        if (text[i] === "{")
+            depth++;
+        else if (text[i] === "}") {
+            depth--;
+            if (depth === 0)
+                return text.slice(openIdx + 1, i);
+        }
+    }
+    return null;
+}
+// Heuristic, not a parser -- matches "name:" / "name?:" field declarations
+// at the start of a line or after a separator. Good enough for the flat,
+// single-level prop interfaces real components typically declare; a
+// deliberately best-effort choice over pulling in a full TypeScript AST
+// parser for this (see BACKLOG.md's manifest-quality risk -- sparse or
+// imperfect extraction here is expected, not a bug).
+function extractPropNamesFromBody(body) {
+    const names = new Set();
+    const re = /(?:^|[;,{(\n])\s*([A-Za-z_$][A-Za-z0-9_$]*)\??\s*:/g;
+    let m;
+    while ((m = re.exec(body)) !== null) {
+        names.add(m[1]);
+    }
+    return [...names];
+}
+// Best-effort extraction of a destructured function-parameter's field
+// names, e.g. `({ title, onClose, variant = "default" })` -> ["title",
+// "onClose", "variant"]. Only used as a last-resort fallback when neither
+// a `<Name>Props` interface/type nor a `.propTypes` block was found.
+function extractDestructuredParamNames(defWindow) {
+    const match = defWindow.match(/\(\s*\{([^}]*)\}/);
+    if (!match)
+        return [];
+    return match[1]
+        .split(",")
+        .map((p) => p.trim().split(/[:=]/)[0].trim())
+        .filter((p) => /^[A-Za-z_$][A-Za-z0-9_$]*$/.test(p));
+}
+const DESIGN_SYSTEM_SCAN_EXCLUDED_DIRS = new Set([
+    "node_modules",
+    "dist",
+    "build",
+    ".git",
+    ".next",
+    ".turbo",
+    "coverage",
+]);
+const DESIGN_SYSTEM_SCAN_EXTENSIONS = new Set([".jsx", ".tsx", ".js", ".ts"]);
+// .d.ts (type declarations, not components) and test/story files (not the
+// component's own definition, and .stories.* would otherwise double-count
+// alongside the real component file) are excluded by filename fragment.
+const DESIGN_SYSTEM_SCAN_EXCLUDED_NAME_FRAGMENTS = [".test.", ".spec.", ".stories.", ".d.ts"];
+function walkComponentFiles(root) {
+    const files = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const dir = stack.pop();
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (!DESIGN_SYSTEM_SCAN_EXCLUDED_DIRS.has(entry.name))
+                    stack.push(join(dir, entry.name));
+                continue;
+            }
+            if (!DESIGN_SYSTEM_SCAN_EXTENSIONS.has(extname(entry.name)))
+                continue;
+            if (DESIGN_SYSTEM_SCAN_EXCLUDED_NAME_FRAGMENTS.some((frag) => entry.name.includes(frag)))
+                continue;
+            files.push(join(dir, entry.name));
+        }
+    }
+    return files;
+}
+// Component detection: an uppercase-leading exported function or const,
+// React's own naming convention for components -- deliberately excludes
+// lowercase exported helpers/hooks, which aren't components. Props are
+// resolved in priority order: a `<Name>Props` interface/type (most
+// reliable, TypeScript projects), then a `.propTypes` block (plain JS
+// with PropTypes), then a best-effort destructure of the function's own
+// parameter list. An empty result from all three is a real, expected
+// outcome for an untyped, undestructured component -- not an error.
+function scanComponentFile(absPath, relPath) {
+    let content;
+    try {
+        content = readFileSync(absPath, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const names = new Map();
+    const fnRe = /export\s+(?:default\s+)?function\s+([A-Z][A-Za-z0-9_]*)\s*\(/g;
+    const constRe = /export\s+(?:default\s+)?const\s+([A-Z][A-Za-z0-9_]*)\s*(?::[^=\n]+)?=/g;
+    let m;
+    while ((m = fnRe.exec(content)) !== null)
+        names.set(m[1], m.index);
+    while ((m = constRe.exec(content)) !== null)
+        if (!names.has(m[1]))
+            names.set(m[1], m.index);
+    const candidates = [];
+    for (const [name, idx] of names) {
+        let props = [];
+        const interfaceMatch = content.match(new RegExp(`(?:interface|type)\\s+${name}Props\\b`));
+        if (interfaceMatch?.index !== undefined) {
+            const body = extractBalancedBraceBody(content, interfaceMatch.index);
+            if (body)
+                props = extractPropNamesFromBody(body);
+        }
+        if (props.length === 0) {
+            const propTypesMatch = content.match(new RegExp(`${name}\\.propTypes\\s*=`));
+            if (propTypesMatch?.index !== undefined) {
+                const body = extractBalancedBraceBody(content, propTypesMatch.index);
+                if (body)
+                    props = extractPropNamesFromBody(body);
+            }
+        }
+        if (props.length === 0) {
+            props = extractDestructuredParamNames(content.slice(idx, Math.min(content.length, idx + 500)));
+        }
+        candidates.push({ name, props, description: null, usage_example: null, file_path: relPath });
+    }
+    return candidates;
+}
+function scanDirectoryForDesignSystem(absRoot) {
+    const candidates = [];
+    for (const abs of walkComponentFiles(absRoot)) {
+        candidates.push(...scanComponentFile(abs, relative(absRoot, abs)));
+    }
+    return candidates;
+}
+// Parses a manifest file's raw text into a flat candidate list. Two
+// recognized shapes, matching the architecture doc's launch scope:
+//  - Hand-authored: a top-level array of {name, props?, description?,
+//    usage_example?} objects, optionally wrapped in {"components": [...]}.
+//  - Storybook-exported index (stories.json v3, or index.json v4+): both
+//    key stories/entries by id, each carrying a "title" like
+//    "Components/Button" that groups stories under a component name.
+//    Props aren't part of this export (only Storybook's heavier docgen
+//    addon captures those), so candidates from this path start with an
+//    empty props list -- expected, not a bug, per the same manifest-
+//    quality risk noted on the directory-scan path above.
+// Throws with a clear, specific message on anything else, per the
+// architecture doc's own risk mitigation: "fail loud on malformed input
+// rather than scoring against garbage."
+function parseManifestCandidates(raw, sourcePath) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`Manifest at "${sourcePath}" is not valid JSON.`);
+    }
+    const handAuthoredArray = Array.isArray(parsed)
+        ? parsed
+        : parsed && typeof parsed === "object" && Array.isArray(parsed.components)
+            ? parsed.components
+            : null;
+    if (handAuthoredArray) {
+        return handAuthoredArray.map((item, i) => {
+            if (!item || typeof item !== "object" || typeof item.name !== "string" || !item.name) {
+                throw new Error(`Manifest entry at index ${i} in "${sourcePath}" is missing a required "name" string.`);
+            }
+            const record = item;
+            return {
+                name: record.name,
+                props: Array.isArray(record.props) ? record.props.filter((p) => typeof p === "string") : [],
+                description: typeof record.description === "string" ? record.description : null,
+                usage_example: typeof record.usage_example === "string" ? record.usage_example : null,
+                file_path: null,
+            };
+        });
+    }
+    const storybookEntries = parsed && typeof parsed === "object"
+        ? (parsed.entries ?? parsed.stories ?? null)
+        : null;
+    if (storybookEntries && typeof storybookEntries === "object") {
+        const names = new Set();
+        for (const entry of Object.values(storybookEntries)) {
+            const title = entry && typeof entry === "object" ? entry.title : null;
+            if (typeof title !== "string")
+                continue;
+            const name = title.split("/").pop()?.trim();
+            if (name)
+                names.add(name);
+        }
+        if (names.size === 0) {
+            throw new Error(`Manifest at "${sourcePath}" looked like a Storybook export (found "entries"/"stories") but no component titles could be extracted from it.`);
+        }
+        return [...names].map((name) => ({ name, props: [], description: null, usage_example: null, file_path: null }));
+    }
+    throw new Error(`Manifest at "${sourcePath}" doesn't match a recognized shape. Expected either a hand-authored array of ` +
+        `{name, props, description, usage_example} objects (optionally wrapped in {"components": [...]}), or a ` +
+        `Storybook-exported stories/index JSON file (an object with a top-level "entries" or "stories" map).`);
+}
+// Core of the register_design_system tool. Exactly one of manifest_path
+// or directory_path, both resolved via resolveWithinRoot -- same
+// PROJECT_ROOT-scoped, relative-path-only boundary check_ledger_liveness
+// already established for file_path, reused rather than inventing a
+// second filesystem-access convention. Overwrites any prior registration
+// for this project_id wholesale (one-or-the-other per project, not
+// additive/merged across repeat calls).
+export function registerDesignSystem(input) {
+    const provided = [input.manifest_path, input.directory_path].filter((v) => v !== undefined && v !== "");
+    if (provided.length !== 1) {
+        throw new Error("register_design_system requires exactly one of manifest_path or directory_path (both relative to the project root).");
+    }
+    let sourceKind;
+    let sourcePath;
+    let candidates;
+    if (input.manifest_path) {
+        sourceKind = "manifest";
+        sourcePath = input.manifest_path;
+        const abs = resolveWithinRoot(PROJECT_ROOT, input.manifest_path);
+        if (!abs) {
+            throw new Error(`manifest_path "${input.manifest_path}" must be a relative path within the project root (${PROJECT_ROOT}) -- it was either absolute or escaped the project root.`);
+        }
+        if (!existsSync(abs) || !statSync(abs).isFile()) {
+            throw new Error(`No file found at "${input.manifest_path}" (resolved to ${abs}).`);
+        }
+        candidates = parseManifestCandidates(readFileSync(abs, "utf8"), input.manifest_path);
+    }
+    else {
+        sourceKind = "directory_scan";
+        sourcePath = input.directory_path;
+        const abs = resolveWithinRoot(PROJECT_ROOT, sourcePath);
+        if (!abs) {
+            throw new Error(`directory_path "${sourcePath}" must be a relative path within the project root (${PROJECT_ROOT}) -- it was either absolute or escaped the project root.`);
+        }
+        if (!existsSync(abs) || !statSync(abs).isDirectory()) {
+            throw new Error(`No directory found at "${sourcePath}" (resolved to ${abs}).`);
+        }
+        candidates = scanDirectoryForDesignSystem(abs);
+    }
+    if (candidates.length === 0) {
+        throw new Error(`No components could be found at "${sourcePath}" (${sourceKind}). Check the manifest shape, or that the directory actually contains component files recognized by the scan (export default function/const, uppercase-leading name).`);
+    }
+    const registration = {
+        project_id: input.project_id,
+        source_kind: sourceKind,
+        source_path: sourcePath,
+        registered_at: new Date().toISOString(),
+        candidate_count: candidates.length,
+        candidates,
+    };
+    const file = readDesignSystems();
+    file[input.project_id] = registration;
+    writeDesignSystems(file);
+    return registration;
+}
+// ---------------------------------------------------------------------
+// Design-system recall check
+//
+// Catches a real, specific failure mode raised after this feature shipped:
+// the model can say "no_candidates_found" against a registered design
+// system even when a genuinely relevant candidate is sitting right there
+// in the prompt it was just given -- a reading-comprehension miss over
+// its own known-complete candidate list, not a live-search gap (compare
+// external-library mode, where "nothing found" is at least grounded in a
+// real search actually coming back empty). Unlike the ensemble
+// (isBoundaryRisk), which only re-checks coverage-boundary "scored"
+// results, nothing previously re-checked a "no_candidates_found" verdict
+// at all -- it was trusted on the first pass. This doesn't fix that by
+// spending another API call; it's a cheap, deterministic, zero-cost local
+// keyword-overlap check between component_need/domain and every
+// registered candidate's own name/props/description, run only when
+// reason is "no_candidates_found" in design-system mode. A hit doesn't
+// override the verdict -- a shared keyword is weak evidence, not proof of
+// a real match -- it only surfaces the risk on the response so the
+// calling agent knows to double-check before trusting a "nothing here"
+// answer, same "show the uncertainty, don't paper over it" policy as
+// ensemble/oversized_match elsewhere in this file.
+// ---------------------------------------------------------------------
+// Deliberately generic English filler, not UI-specific -- a UI-specific
+// word like "banner" or "list" is exactly the kind of overlap this check
+// exists to catch, so only true stopwords are excluded here.
+const KEYWORD_STOPWORDS = new Set([
+    "the", "a", "an", "and", "or", "of", "to", "for", "with", "in", "on", "at",
+    "by", "from", "is", "are", "was", "were", "be", "been", "being", "that",
+    "this", "these", "those", "it", "its", "as", "not", "no", "if", "when",
+    "which", "what", "who", "how", "into", "over", "out", "up", "down", "new",
+    "real", "component", "components", "need", "needs", "show", "showing",
+    "shows", "display", "displays", "displaying", "user", "users", "each",
+    "other", "also", "app", "style", "product",
+]);
+// Splits on non-alphanumeric boundaries AND camelCase/PascalCase boundaries
+// (so "bonusAmount" -> "bonus", "amount" and "ReferralBanner" -> "referral",
+// "banner"), lowercases, then drops stopwords and anything under 3
+// characters -- short tokens ("id", "on") are too generic to be a
+// meaningful signal either way.
+function extractKeywords(text) {
+    const words = text
+        .split(/[^A-Za-z0-9]+/)
+        .flatMap((w) => w.replace(/([a-z0-9])([A-Z])/g, "$1 $2").split(/\s+/))
+        .map((w) => w.toLowerCase())
+        .filter((w) => w.length >= 3 && !KEYWORD_STOPWORDS.has(w));
+    return new Set(words);
+}
+function candidateKeywords(c) {
+    return extractKeywords([c.name, ...c.props, c.description ?? "", c.usage_example ?? ""].join(" "));
+}
+// Returns every registered candidate sharing at least one real keyword
+// with component_need/domain, ranked by how many keywords it shares --
+// capped at 5 so a large design system can't produce an unreadable dump
+// on a genuinely generic need.
+export function findKeywordOverlapCandidates(componentNeed, domain, candidates) {
+    const needKeywords = extractKeywords(`${componentNeed} ${domain}`);
+    if (needKeywords.size === 0)
+        return [];
+    const matches = candidates
+        .map((c) => ({ name: c.name, shared_keywords: [...candidateKeywords(c)].filter((k) => needKeywords.has(k)) }))
+        .filter((m) => m.shared_keywords.length > 0);
+    matches.sort((a, b) => b.shared_keywords.length - a.shared_keywords.length);
+    return matches.slice(0, 5);
+}
 function hashConventions(existingStack) {
     if (!existingStack)
         return null;
@@ -1377,9 +2013,21 @@ function readLedgerLivenessRecords(ledgerEntryId) {
     }
     return records;
 }
+// Deliberately not a sort-then-take-first: readLedgerLivenessRecords
+// returns records in file/append order (oldest first), and a descending
+// sort by timestamp is NOT tie-safe -- JS's stable sort preserves the
+// original relative order among equal timestamps, so on a tie (two
+// records appended within the same millisecond, which sweepLedgerLiveness
+// does routinely -- a per-entry check followed immediately by a
+// dangling-cluster append for the same entry) it would silently return
+// the OLDER of the two. reduce with >= walks forward through true append
+// order and lets each later-appended tied record win, which is what
+// "latest" actually means here.
 function latestLiveness(ledgerEntryId) {
-    const records = readLedgerLivenessRecords(ledgerEntryId).sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
-    return records[0] ?? null;
+    const records = readLedgerLivenessRecords(ledgerEntryId);
+    if (records.length === 0)
+        return null;
+    return records.reduce((latest, r) => (new Date(r.timestamp).getTime() >= new Date(latest.timestamp).getTime() ? r : latest));
 }
 function withLatestLiveness(entry) {
     const latest = latestLiveness(entry.id);
@@ -1387,6 +2035,59 @@ function withLatestLiveness(entry) {
         return entry;
     return { ...entry, live_status: latest.live_status, last_verified_live: latest.timestamp };
 }
+// Feature 2 P3's overlay -- same append-only/latest-wins convention as
+// ledger_liveness.jsonl above, kept as a fully separate file/function pair
+// rather than folded into the liveness overlay: these two overlays answer
+// unrelated questions (is the file still there vs. what commit was this
+// judged against) and happen to share only their storage shape, not their
+// meaning.
+const SNAPSHOT_BACKFILL_PATH = process.env.PATTERN_SNAPSHOT_BACKFILL_PATH ?? join(homedir(), ".pattern", "snapshot_backfill.jsonl");
+function appendSnapshotBackfillRecord(record) {
+    mkdirSync(dirname(SNAPSHOT_BACKFILL_PATH), { recursive: true });
+    appendFileSync(SNAPSHOT_BACKFILL_PATH, JSON.stringify(record) + "\n", "utf8");
+}
+function readSnapshotBackfillRecords(ledgerEntryId) {
+    let raw;
+    try {
+        raw = readFileSync(SNAPSHOT_BACKFILL_PATH, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const records = [];
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === "object" && parsed.ledger_entry_id === ledgerEntryId) {
+                records.push(parsed);
+            }
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return records;
+}
+// Same tie-safety reasoning as latestLiveness above.
+function latestSnapshotBackfill(ledgerEntryId) {
+    const records = readSnapshotBackfillRecords(ledgerEntryId);
+    if (records.length === 0)
+        return null;
+    return records.reduce((latest, r) => (new Date(r.timestamp).getTime() >= new Date(latest.timestamp).getTime() ? r : latest));
+}
+// Only overlays onto entries that actually need it -- an entry with a
+// real snapshot_ref never consults the backfill overlay at all, so a
+// stray/stale backfill record can never shadow a genuine captured value.
+function withReconstructedSnapshotRef(entry) {
+    if (entry.snapshot_ref)
+        return entry;
+    const latest = latestSnapshotBackfill(entry.id);
+    if (!latest)
+        return entry;
+    return { ...entry, reconstructed_snapshot_ref: latest.reconstructed_snapshot_ref };
+}
 // Feature 1 / Referential Integrity, P1: the single-entry live-check.
 // Orphaned when file_path is set but the file no longer exists; live when
 // the file exists and (best-effort) still mentions chosen_candidate;
@@ -1394,9 +2095,10 @@ function withLatestLiveness(entry) {
 // resolveWithinRoot), or exists but the candidate name can't be confirmed
 // in its content -- conservative on purpose, per the spec's own risk
 // mitigation (a false "orphaned" is worse than a lingering "unknown").
-// "dangling" (an entry only cross-referenced by other ledger entries, no
-// live anchor anywhere) is graph-level analysis across the whole ledger,
-// not a single-entry check -- Feature 1 P3, not built here.
+// "dangling" (a cluster of entries with no live anchor anywhere among
+// them) is graph-level analysis across a whole project's entries, not a
+// single-entry check -- see detectDanglingClusters, part of
+// sweep_ledger_liveness (Feature 1 P2/P3), not this function.
 function checkFileLiveStatus(entry) {
     if (!entry.file_path)
         return "unknown";
@@ -1428,11 +2130,12 @@ function checkLedgerEntryLiveness(entry) {
     return record;
 }
 // check_ledger_liveness tool: on-demand invocation of the live-check above
-// (the design's "on demand via an MCP call" case -- a scheduled/batch
-// sweep is Feature 1 P2, not built here). Entries with no file_path are
-// reported but never checked/recorded -- their status is permanently
-// "unknown" by construction, so re-checking them on every call would only
-// grow ledger_liveness.jsonl without ever learning anything new.
+// (the design's "on demand via an MCP call" case -- see
+// sweepLedgerLiveness below for the scheduled/batch case, Feature 1 P2).
+// Entries with no file_path are reported but never checked/recorded --
+// their status is permanently "unknown" by construction, so re-checking
+// them on every call would only grow ledger_liveness.jsonl without ever
+// learning anything new.
 function checkLedgerLiveness(input) {
     const entries = readLedgerEntries(input.project_id).filter((e) => !input.ledger_entry_id || e.id === input.ledger_entry_id);
     const results = entries.map((e) => {
@@ -1462,6 +2165,37 @@ function checkLedgerLiveness(input) {
         results,
     };
 }
+// backfill_ledger_snapshot_ref tool (Feature 2 P3): attempts
+// reconstructSnapshotRef for every entry in a project that's missing a
+// real snapshot_ref, and persists each attempt to snapshot_backfill.jsonl
+// regardless of outcome -- a documented "we tried, here's what we found"
+// audit trail, not just a cache, since a failed reconstruction is itself
+// meaningful information (this project's git history doesn't reach back
+// that far, or PROJECT_ROOT isn't a git repo at all). 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.
+function backfillLedgerSnapshotRefs(input) {
+    const entries = readLedgerEntries(input.project_id).filter((e) => !input.ledger_entry_id || e.id === input.ledger_entry_id);
+    const results = entries.map((e) => {
+        if (e.snapshot_ref) {
+            return { ledger_entry_id: e.id, already_had_snapshot_ref: true, reconstructed_snapshot_ref: null };
+        }
+        const reconstructed = reconstructSnapshotRef(PROJECT_ROOT, e.timestamp);
+        appendSnapshotBackfillRecord({
+            id: randomUUID(),
+            timestamp: new Date().toISOString(),
+            ledger_entry_id: e.id,
+            project_id: e.project_id,
+            reconstructed_snapshot_ref: reconstructed,
+        });
+        return { ledger_entry_id: e.id, already_had_snapshot_ref: false, reconstructed_snapshot_ref: reconstructed };
+    });
+    return {
+        attempted: results.filter((r) => !r.already_had_snapshot_ref).length,
+        reconstructed: results.filter((r) => r.reconstructed_snapshot_ref !== null).length,
+        results,
+    };
+}
 // 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)
@@ -1492,8 +2226,9 @@ function readLedgerEntries(projectId) {
                     snapshot_ref: rawEntry.snapshot_ref ?? null,
                     last_verified_live: rawEntry.last_verified_live ?? null,
                     live_status: rawEntry.live_status ?? "unknown",
+                    reconstructed_snapshot_ref: rawEntry.reconstructed_snapshot_ref ?? null,
                 };
-                entries.push(withLatestLiveness(normalized));
+                entries.push(withReconstructedSnapshotRef(withLatestLiveness(normalized)));
             }
         }
         catch {
@@ -1502,6 +2237,109 @@ function readLedgerEntries(projectId) {
     }
     return entries;
 }
+// sweep_ledger_liveness (Feature 1 P2) needs every project_id present in
+// the ledger when none is specified -- readLedgerEntries always filters
+// to one project_id, so this is the one place that reads every line
+// unfiltered. Same "missing/malformed collapses to empty" tolerance as
+// readLedgerEntries itself.
+function listAllProjectIds() {
+    let raw;
+    try {
+        raw = readFileSync(LEDGER_PATH, "utf8");
+    }
+    catch {
+        return [];
+    }
+    const ids = new Set();
+    for (const line of raw.split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed && typeof parsed === "object" && typeof parsed.project_id === "string") {
+                ids.add(parsed.project_id);
+            }
+        }
+        catch {
+            // skip malformed line
+        }
+    }
+    return [...ids];
+}
+// Feature 1 P3: the graph-level half of referential integrity that
+// checkFileLiveStatus's single-entry check can't do. Pattern's ledger has
+// no explicit entry-to-entry reference field (each line is an independent
+// judgment record) -- feature_id is the one real grouping construct that
+// already exists (deriveFeatureId), so a "cluster" here means every entry
+// sharing one feature_id, and "cross-linked with no live anchor" means
+// none of them resolved to live_status "live". A cluster of exactly one
+// entry is just an ordinary orphaned/unknown entry, not a cluster
+// phenomenon, so single-entry groups are never flagged.
+//
+// Must run after checkLedgerLiveness has updated live_status for the
+// same project -- otherwise this would be judging stale per-entry
+// statuses. sweepLedgerLiveness below enforces that ordering; this
+// function does not re-check individual entries itself.
+function detectDanglingClusters(projectId) {
+    const entries = readLedgerEntries(projectId);
+    const byFeature = new Map();
+    for (const e of entries) {
+        const group = byFeature.get(e.feature_id) ?? [];
+        group.push(e);
+        byFeature.set(e.feature_id, group);
+    }
+    const clusters = [];
+    for (const [featureId, group] of byFeature) {
+        if (group.length < 2)
+            continue;
+        if (group.some((e) => e.live_status === "live"))
+            continue;
+        clusters.push({ feature_id: featureId, entry_ids: group.map((e) => e.id) });
+        for (const e of group) {
+            appendLedgerLivenessRecord({
+                id: randomUUID(),
+                timestamp: new Date().toISOString(),
+                ledger_entry_id: e.id,
+                project_id: projectId,
+                live_status: "dangling",
+                checked_file_path: e.file_path,
+            });
+        }
+    }
+    return clusters;
+}
+// The MCP tool: batch-updates live_status across an entire ledger,
+// optionally scoped to one project_id, but sweeping every project_id
+// present when omitted -- the "on a schedule (project open or cron)" half
+// of the design that check_ledger_liveness's on-demand, single-project
+// call (P1) doesn't cover. Pattern has no daemon or background process of
+// its own to schedule this from (each server invocation is transient,
+// tied to its MCP host's lifecycle) -- this tool is meant to be invoked
+// by whatever external scheduler you already have (a cron job, a CI
+// step), not something Pattern triggers on its own.
+function sweepLedgerLiveness(input) {
+    const projectIds = input.project_id ? [input.project_id] : listAllProjectIds();
+    const perProject = [];
+    const allDangling = [];
+    for (const projectId of projectIds) {
+        const liveness = checkLedgerLiveness({ project_id: projectId });
+        const clusters = detectDanglingClusters(projectId);
+        for (const c of clusters)
+            allDangling.push({ project_id: projectId, ...c });
+        perProject.push({
+            project_id: projectId,
+            checked: liveness.checked,
+            total_entries: liveness.total_entries,
+            dangling_clusters: clusters.length,
+        });
+    }
+    return {
+        projects_swept: projectIds.length,
+        total_entries_checked: perProject.reduce((sum, p) => sum + p.checked, 0),
+        dangling_clusters: allDangling,
+        per_project: perProject,
+    };
+}
 // 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
@@ -1556,6 +2394,24 @@ function findLedgerMatches(projectId, componentNeed, limit = 20) {
     entries.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
     return entries.slice(0, limit);
 }
+// entry.reconstructed_snapshot_ref only ever gets consulted when
+// snapshot_ref itself is null (see withReconstructedSnapshotRef) -- this
+// still checks both explicitly, rather than assuming that invariant holds,
+// so the two can never be silently conflated even if that changes later.
+// A reconstructed value is always labeled as such: it's an approximation
+// (the commit HEAD probably pointed to at that timestamp), not the
+// original captured snapshot, and presenting it unlabeled would overstate
+// its reliability.
+function formatSnapshotLine(entry) {
+    if (entry.snapshot_ref)
+        return "`" + entry.snapshot_ref + "`";
+    if (entry.reconstructed_snapshot_ref) {
+        return ("`" +
+            entry.reconstructed_snapshot_ref +
+            "` (reconstructed via backfill -- best-effort approximation, not the original captured snapshot)");
+    }
+    return "not available (project root wasn't a git repository at judgment time)";
+}
 // Feature 2 / Decision Provenance, P1: renders one ledger entry as a
 // stable markdown block -- "stable" meaning a pure function of the entry
 // alone (never Date.now(), never anything read live off disk), so the
@@ -1563,8 +2419,8 @@ function findLedgerMatches(projectId, componentNeed, limit = 20) {
 // what makes verify-provenance-artifact.mjs's snapshot test meaningful:
 // a diff in the generated markdown for a fixed fixture means the format
 // changed, not that time passed. Markdown, not JSON, per the spec --
-// PRs/issues render it natively (P2, not built here, attaches this to
-// one).
+// PRs/issues render it natively (see export_ledger_provenance and
+// post_ledger_provenance_to_github, which attach this to one).
 export function formatProvenanceArtifact(entry) {
     const lines = [];
     lines.push(`## Pattern decision: ${entry.component_need}`);
@@ -1574,7 +2430,7 @@ export function formatProvenanceArtifact(entry) {
     lines.push(`- **Coverage:** ${entry.coverage ?? "n/a"}`);
     lines.push(`- **Domain:** ${entry.domain}`);
     lines.push(`- **Framework:** ${entry.framework}`);
-    lines.push(`- **Snapshot:** ${entry.snapshot_ref ? "`" + entry.snapshot_ref + "`" : "not available (project root wasn't a git repository at judgment time)"}`);
+    lines.push(`- **Snapshot:** ${formatSnapshotLine(entry)}`);
     lines.push(`- **Judged at:** ${entry.timestamp}${entry.cache_hit ? " (served from ledger cache hit)" : ""}`);
     lines.push("");
     lines.push("### Requirements checked");
@@ -1599,11 +2455,99 @@ export function formatProvenanceArtifact(entry) {
             const chosen = c.name !== null && c.name === entry.chosen_candidate ? "✓" : "";
             lines.push(`| ${c.source ?? "n/a"} | ${c.name ?? "n/a"} | ${c.coverage_pct ?? "n/a"} | ${chosen} |`);
         }
+        // Solo Dev design-system architecture P3: distinguish a design_system
+        // source from an external library at render time -- reads only
+        // entry.candidates_evaluated (already-persisted, distilled data), so
+        // this stays a pure function of the entry alone like the rest of this
+        // formatter.
+        if (entry.candidates_evaluated.some((c) => c.source === "design_system")) {
+            lines.push("");
+            lines.push("_Sourced from this project's own registered design system (`register_design_system`), not an external library._");
+        }
     }
     lines.push("");
     lines.push(`_Generated by Pattern (\`export_ledger_provenance\`) from ledger entry \`${entry.id}\`._`);
     return lines.join("\n");
 }
+// Feature 2 / Decision Provenance, P2: posts an export_ledger_provenance
+// artifact as a real comment on a GitHub PR or issue. GitHub's REST API
+// treats a PR and an issue identically for comments (both are backed by
+// the same /issues/{number}/comments endpoint), so one input shape covers
+// both -- no separate "is this a PR" flag needed.
+//
+// This is the one tool in this server with a real, visible side effect on
+// a third-party service outside the caller's own machine -- every other
+// tool here only ever touches local files. The calling agent should
+// confirm with the user before invoking it, the same way it's expected to
+// confirm before running a suggested install_command (see SECURITY.md).
+//
+// Auth resolves the spec's own open question (personal token vs. GitHub
+// App) in favor of a personal token: reads GITHUB_TOKEN from the
+// environment, the same convention every GitHub Action and the `gh` CLI
+// itself use. A GitHub App needs a hosted installation flow and a webhook
+// receiver, which contradicts this project's "local npm package, no
+// hosted infrastructure" distribution model (see the README's Ledger
+// integrity section 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 computeSnapshotRef above.
+//
+// Idempotent by construction, not just by convention: every posted
+// comment is prefixed with a hidden HTML marker keyed to the ledger
+// entry's id, and a post first checks existing comments for that marker
+// -- a repeat call for the same entry returns posted: false instead of
+// creating a duplicate. Only checks the most recent 100 comments (one
+// page) -- a thread with more prior comments than that is an edge case
+// this pass doesn't handle; full pagination is a later concern, not built
+// here.
+const GITHUB_API_BASE = process.env.PATTERN_GITHUB_API_BASE ?? "https://api.github.com";
+function provenanceMarker(ledgerEntryId) {
+    return `<!-- pattern-ledger-provenance:${ledgerEntryId} -->`;
+}
+async function postProvenanceToGitHub(input) {
+    const token = process.env.GITHUB_TOKEN;
+    if (!token) {
+        throw new Error("GITHUB_TOKEN is not set. This tool posts a real comment to GitHub and needs a personal access token " +
+            "with repo scope (the same one `gh auth login` or a GitHub Action would use) -- set the GITHUB_TOKEN " +
+            "environment variable and retry.");
+    }
+    if (!/^[^/\s]+\/[^/\s]+$/.test(input.repo)) {
+        throw new Error(`repo must be in "owner/repo" form, got: "${input.repo}"`);
+    }
+    const entry = readLedgerEntries(input.project_id).find((e) => e.id === input.ledger_entry_id);
+    if (!entry) {
+        throw new Error(`No ledger entry with id "${input.ledger_entry_id}" found for project_id "${input.project_id}". Use read_ledger to list entries and their ids.`);
+    }
+    const marker = provenanceMarker(entry.id);
+    const headers = {
+        Authorization: `Bearer ${token}`,
+        Accept: "application/vnd.github+json",
+        "Content-Type": "application/json",
+        "User-Agent": "pattern-mcp",
+    };
+    const commentsUrl = `${GITHUB_API_BASE}/repos/${input.repo}/issues/${input.issue_number}/comments`;
+    const listResponse = await fetch(`${commentsUrl}?per_page=100`, { headers });
+    if (!listResponse.ok) {
+        const errText = await listResponse.text();
+        throw new Error(`GitHub API error ${listResponse.status} listing comments on ${input.repo}#${input.issue_number}: ${errText}`);
+    }
+    const existingComments = (await listResponse.json());
+    const existing = existingComments.find((c) => c.body.includes(marker));
+    if (existing) {
+        return { posted: false, reason: "already_posted", comment_url: existing.html_url, comment_id: existing.id };
+    }
+    const body = `${marker}\n\n${formatProvenanceArtifact(entry)}`;
+    const postResponse = await fetch(commentsUrl, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({ body }),
+    });
+    if (!postResponse.ok) {
+        const errText = await postResponse.text();
+        throw new Error(`GitHub API error ${postResponse.status} posting comment to ${input.repo}#${input.issue_number}: ${errText}`);
+    }
+    const created = (await postResponse.json());
+    return { posted: true, comment_url: created.html_url, comment_id: created.id };
+}
 // report_build_cost (cost-attribution build plan, 1.3) -- self-reported
 // build cost, cheapest option first, since Pattern has no visibility into
 // what happens after judgeComponent returns a verdict (1.4's
@@ -1854,6 +2798,7 @@ function buildLedgerEntry(input, projectId, result, opts) {
         file_path: input.file_path ?? null,
         last_verified_live: null,
         live_status: "unknown",
+        reconstructed_snapshot_ref: null,
     };
 }
 async function judgeComponent(input) {
@@ -2437,7 +3382,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "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.",
+                "to keep from them. If project_id has a design system registered " +
+                "via register_design_system, this call scores ONLY against that " +
+                "project's own registered candidates instead of shadcn/ui, " +
+                "21st.dev, and ReUI -- no separate flag needed, it's automatic " +
+                "based on project_id alone. In that mode, a custom_build verdict " +
+                "with reason no_candidates_found may also carry a top-level " +
+                "design_system_recall_check field -- a deterministic, zero-cost " +
+                "keyword-overlap check flagging registered candidates that share " +
+                "real keywords with this need but weren't selected. This is a " +
+                "weak signal, not proof of a missed match -- if present, surface " +
+                "it to the user before accepting the custom_build verdict at " +
+                "face value.",
             inputSchema: INPUT_SCHEMA,
         },
         {
@@ -2549,9 +3505,76 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
                 "the same entry always produces the same markdown, nothing here " +
                 "reads live system time or disk state. This only formats and " +
                 "returns text; it does not post anything to GitHub or anywhere " +
-                "else -- that's a separate, not-yet-built action.",
+                "else -- see post_ledger_provenance_to_github for that.",
             inputSchema: EXPORT_LEDGER_PROVENANCE_INPUT_SCHEMA,
         },
+        {
+            name: POST_LEDGER_PROVENANCE_TOOL_NAME,
+            description: "Posts one ledger entry's provenance artifact (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, not just your own " +
+                "machine -- confirm with the user before calling this, the same " +
+                "way you'd confirm before running a suggested install_command " +
+                "(see SECURITY.md). Requires GITHUB_TOKEN (a personal access " +
+                "token with repo scope) in the environment -- Pattern manages no " +
+                "GitHub credential of its own. Idempotent: a repeat call for the " +
+                "same ledger_entry_id/repo/issue_number detects the previously " +
+                "posted comment (via a hidden marker) and returns posted: false " +
+                "instead of creating a duplicate.",
+            inputSchema: POST_LEDGER_PROVENANCE_INPUT_SCHEMA,
+        },
+        {
+            name: SWEEP_LEDGER_LIVENESS_TOOL_NAME,
+            description: "Batch version of 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), " +
+                "then flags dangling clusters -- groups of 2+ entries sharing a " +
+                "feature_id where none of them resolved to live_status 'live'. " +
+                "Pattern has no daemon or scheduler of its own (each server " +
+                "invocation is transient, tied to its MCP host's lifecycle) -- " +
+                "this tool is meant to be invoked by whatever external scheduler " +
+                "you already have (a cron job, a CI step), not something Pattern " +
+                "triggers automatically. Tested at 200 and 1,000 synthetic " +
+                "entries without reintroducing search+score latency -- this is " +
+                "fs stat calls, not API calls.",
+            inputSchema: SWEEP_LEDGER_LIVENESS_INPUT_SCHEMA,
+        },
+        {
+            name: BACKFILL_LEDGER_SNAPSHOT_REF_TOOL_NAME,
+            description: "Best-effort reconstruction of snapshot_ref for ledger entries " +
+                "written before that field existed (or written outside a git " +
+                "repo): finds the commit that was HEAD at or just before each " +
+                "entry's own timestamp. Always clearly distinguished from a real " +
+                "captured snapshot_ref wherever it's rendered (export_ledger_provenance, " +
+                "post_ledger_provenance_to_github) -- a rebase/force-push/history " +
+                "rewrite since that time can make this approximation wrong, so " +
+                "it's never presented as equivalent to a value actually captured " +
+                "live. Entries that already have a real snapshot_ref are reported " +
+                "but never touched. Persists every attempt (including failures) " +
+                "for later lookup; never modifies ledger.jsonl itself.",
+            inputSchema: BACKFILL_LEDGER_SNAPSHOT_REF_INPUT_SCHEMA,
+        },
+        {
+            name: REGISTER_DESIGN_SYSTEM_TOOL_NAME,
+            description: "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 real candidates they'll actually use, " +
+                "not external libraries they won't. Pass either manifest_path (a " +
+                "hand-authored JSON manifest or a Storybook-exported stories/" +
+                "index JSON file) or directory_path (a components folder, scanned " +
+                "heuristically for exported components and their props) -- both " +
+                "relative to the project root, never absolute. Registering " +
+                "REPLACES any prior registration for this project_id, and once " +
+                "registered, recommend_component scores ONLY against these " +
+                "candidates for this project_id -- external-library search stops " +
+                "entirely, it does not layer on top. This only writes local " +
+                "config; it never calls the Anthropic API. Re-run this whenever " +
+                "the design system's own components change meaningfully -- " +
+                "registration is a point-in-time snapshot, not a live link.",
+            inputSchema: REGISTER_DESIGN_SYSTEM_INPUT_SCHEMA,
+        },
     ],
 }));
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
@@ -2717,6 +3740,70 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             };
         }
     }
+    if (request.params.name === POST_LEDGER_PROVENANCE_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            const result = await postProvenanceToGitHub(args);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    }
+    if (request.params.name === SWEEP_LEDGER_LIVENESS_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            const result = sweepLedgerLiveness(args);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    }
+    if (request.params.name === BACKFILL_LEDGER_SNAPSHOT_REF_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            const result = backfillLedgerSnapshotRefs(args);
+            return {
+                content: [{ type: "text", text: JSON.stringify({ project_id: args.project_id, ...result }) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [{ type: "text", text: `Error: ${message}` }],
+                isError: true,
+            };
+        }
+    }
+    if (request.params.name === REGISTER_DESIGN_SYSTEM_TOOL_NAME) {
+        const args = request.params.arguments;
+        try {
+            const registration = registerDesignSystem(args);
+            return {
+                content: [{ type: "text", text: JSON.stringify({ status: "registered", registration }) }],
+            };
+        }
+        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() {