rafters 0.0.82 → 0.0.83

package/dist/index.js

@@ -28380,6 +28380,41 @@ var RegistryItemIntelligenceSchema = external_exports.object({
     nevers: external_exports.array(external_exports.string()).default([])
   }).optional()
 });
+var ComponentTargetSchema = external_exports.enum(["react", "astro", "vue", "svelte", "wc"]);
+var PropFieldSchema = external_exports.discriminatedUnion("type", [
+  external_exports.object({
+    type: external_exports.literal("enum"),
+    values: external_exports.array(external_exports.string()),
+    // verbatim literal union members -- never "string"
+    default: external_exports.string().optional(),
+    required: external_exports.boolean().optional(),
+    constraint: external_exports.object({
+      when: external_exports.object({ prop: external_exports.string(), matches: external_exports.string() }),
+      requires: external_exports.object({ prop: external_exports.string() })
+    }).optional()
+  }),
+  external_exports.object({
+    // Matches #2072's PropNode 'grammar' arm exactly, so graph.ts's
+    // describe(<id>.props.<name>.vocab) drill has real shape data.
+    type: external_exports.literal("grammar"),
+    grammar: external_exports.array(external_exports.string()).min(1),
+    // grammar shape tokens, e.g. ['word', 'word/alpha']
+    vocab: external_exports.string(),
+    // drillable addr, e.g. 'container.props.fill.vocab' -- never inlined
+    onInvalid: external_exports.literal("silent-noop"),
+    default: external_exports.string().optional()
+  }),
+  external_exports.object({
+    type: external_exports.literal("deprecated"),
+    deprecatedFor: external_exports.string()
+  })
+]);
+var FacetSchema = external_exports.object({
+  props: external_exports.record(external_exports.string(), PropFieldSchema),
+  slots: external_exports.array(external_exports.string()).optional(),
+  events: external_exports.array(external_exports.string()).optional(),
+  snippet: external_exports.string()
+});
 var RegistryItemSchema = external_exports.object({
   name: external_exports.string(),
   type: RegistryItemTypeSchema,
@@ -28388,7 +28423,11 @@ var RegistryItemSchema = external_exports.object({
   files: external_exports.array(RegistryFileSchema),
   rules: external_exports.array(external_exports.string()).default([]),
   composites: external_exports.array(external_exports.string()).default([]),
-  intelligence: RegistryItemIntelligenceSchema.optional()
+  intelligence: RegistryItemIntelligenceSchema.optional(),
+  // Per-target facets. zod v4's `z.record(enum, ...)` demands EVERY enum key be
+  // present; a component built for only some targets must parse, so this is a
+  // partial record (only the built targets appear).
+  facets: external_exports.partialRecord(ComponentTargetSchema, FacetSchema).default({})
 });
 var RegistryIndexSchema = external_exports.object({
   name: external_exports.string(),
@@ -28476,6 +28515,46 @@ var RegistryClient = class {
     }
     throw new Error(`"${name}" not found in registry (component, primitive, composite, or rule)`);
   }
+  /**
+   * Fetch every registry item in one call, for the whole-catalog load the MCP
+   * intel graph needs at startup.
+   *
+   * Prefers a single bulk round-trip against `/registry/items.json`. A registry
+   * that does not serve that route -- an older deploy, or a third-party
+   * `registryUrl` (which is user-configurable, see ConfigWiringSchema) -- returns
+   * a non-2xx, and this falls back to looping `fetchItem` over `fetchIndex()`'s
+   * name list, retaining today's per-item cost so no workspace's `describe` ever
+   * hard-fails on a registry that predates the bulk endpoint.
+   */
+  async fetchAllItems() {
+    const response = await fetch(`${this.baseUrl}/registry/items.json`);
+    if (response.ok) {
+      return external_exports.array(RegistryItemSchema).parse(await response.json());
+    }
+    return this.fetchAllItemsByIndex();
+  }
+  /**
+   * The fallback whole-catalog load: one `fetchItem` per name in the index,
+   * across every describe-relevant kind. Deduped so a name appearing in more
+   * than one index list is fetched once.
+   */
+  async fetchAllItemsByIndex() {
+    const index = await this.fetchIndex();
+    const names = [
+      ...index.components,
+      ...index.primitives,
+      ...index.composites,
+      ...index.substrate
+    ];
+    const seen = /* @__PURE__ */ new Set();
+    const items = [];
+    for (const name of names) {
+      if (seen.has(name)) continue;
+      seen.add(name);
+      items.push(await this.fetchItem(name));
+    }
+    return items;
+  }
   /**
    * List all available components.
    */
@@ -30874,8 +30953,8 @@ function readVersion() {
 var VERSION = readVersion();
 
 // src/mcp/tools.ts
-import { readFile as readFile6 } from "fs/promises";
-import { join as join12 } from "path";
+import { readFile as readFile6, writeFile as writeFile4 } from "fs/promises";
+import { isAbsolute as isAbsolute3, join as join12 } from "path";
 
 // ../composites/src/built-in-rules/email.ts
 var email3 = external_exports.string().email();
@@ -31025,9 +31104,6 @@ function register3(composite) {
   }
   composites.set(id, composite);
 }
-function get2(id) {
-  return composites.get(id);
-}
 function getAll2() {
   return Array.from(composites.values());
 }
@@ -31238,7 +31314,323 @@ function resolveWorkspace(workspaces, defaultWorkspace, name) {
   return defaultWorkspace;
 }
 
+// src/mcp/graph.ts
+function assembleGraph(items) {
+  const nodes = /* @__PURE__ */ new Map();
+  for (const item of items) {
+    const kind = kindOf(item.type);
+    if (kind === null) continue;
+    const src = item.intelligence;
+    const intel = {
+      dos: src?.usagePatterns?.dos ?? [],
+      nevers: src?.usagePatterns?.nevers ?? []
+    };
+    if (src?.cognitiveLoad !== void 0) intel.cognitiveLoad = src.cognitiveLoad;
+    if (src?.semanticMeaning !== void 0) intel.semanticMeaning = src.semanticMeaning;
+    if (src?.accessibility !== void 0) intel.accessibility = src.accessibility;
+    if (src?.attentionEconomics !== void 0) intel.attentionEconomics = src.attentionEconomics;
+    if (src?.trustBuilding !== void 0) intel.trustBuilding = src.trustBuilding;
+    nodes.set(item.name, {
+      id: item.name,
+      kind,
+      intel,
+      facets: item.facets ?? {},
+      composesWith: item.composites
+    });
+  }
+  for (const node of nodes.values()) {
+    for (const target of node.composesWith) {
+      if (!nodes.has(target)) {
+        throw new Error(`graph: node "${node.id}" composesWith unknown id "${target}"`);
+      }
+    }
+  }
+  return { nodes };
+}
+function kindOf(type2) {
+  if (type2 === "composite") return "composite";
+  if (type2 === "ui" || type2 === "primitive") return "component";
+  return null;
+}
+function describe(addr, graph, target) {
+  const parts = addr === "" ? [] : addr.split(".");
+  if (parts.length === 0) {
+    return {
+      kinds: [
+        { addr: "components", type: "edge" },
+        { addr: "composites", type: "edge" }
+      ],
+      nodeCount: graph.nodes.size
+    };
+  }
+  const [head, ...rest] = parts;
+  if (head === void 0) return { error: `cannot resolve: ${addr}` };
+  if (head === "components" || head === "composites") {
+    const kind = head === "components" ? "component" : "composite";
+    const roster = [];
+    for (const node2 of graph.nodes.values()) {
+      if (node2.kind === kind) roster.push({ id: node2.id });
+    }
+    return roster;
+  }
+  const node = graph.nodes.get(head);
+  if (!node) return { error: `unknown node: ${head}` };
+  if (rest.length === 0) return layer0(node, target);
+  if (rest.length === 1 && rest[0] === "composesWith") {
+    return resolveEdges(node, graph, target);
+  }
+  if (rest[0] === "props") {
+    const facet = target === void 0 ? void 0 : node.facets[target];
+    const propName = rest[1];
+    const prop = facet && propName !== void 0 ? facet.props[propName] : void 0;
+    if (!prop) return { error: `cannot resolve: ${addr}` };
+    if (rest.length === 2) return toAgentProp(prop);
+    return { error: `cannot resolve: ${addr}` };
+  }
+  return { error: `cannot resolve: ${addr}` };
+}
+function toAgentProp(prop) {
+  if (prop.type === "grammar") {
+    const { vocab: _vocab, ...agentView } = prop;
+    return agentView;
+  }
+  return prop;
+}
+function layer0(node, target) {
+  const facet = target === void 0 ? void 0 : node.facets[target];
+  const children = [];
+  if (facet) {
+    for (const [name, prop] of Object.entries(facet.props)) {
+      const child = { addr: `${node.id}.props.${name}`, type: prop.type };
+      if (prop.type === "deprecated") child.deprecatedFor = prop.deprecatedFor;
+      children.push(child);
+    }
+  }
+  if (node.composesWith.length > 0) {
+    children.push({ addr: `${node.id}.composesWith`, type: "edge" });
+  }
+  const result = { id: node.id, kind: node.kind, intel: node.intel, children };
+  if (facet) {
+    result.snippet = facet.snippet;
+    if (facet.slots !== void 0) result.slots = facet.slots;
+    if (facet.events !== void 0) result.events = facet.events;
+  }
+  return result;
+}
+function resolveEdges(node, graph, target) {
+  const seen = /* @__PURE__ */ new Set();
+  const results = [];
+  for (const edgeId of node.composesWith) {
+    if (seen.has(edgeId)) continue;
+    seen.add(edgeId);
+    const edgeNode = graph.nodes.get(edgeId);
+    if (edgeNode) results.push(layer0(edgeNode, target));
+  }
+  return results;
+}
+
+// src/mcp/intent.ts
+var INTENT_TAGS = {
+  modal: ["attention", "blocking", "above-all", "focus-trap"],
+  alert: ["attention", "inline", "passive"],
+  tooltip: ["hint", "passive", "inline", "hover"]
+};
+var INTENT_AXES = [
+  {
+    tag: "above-all",
+    keywords: [
+      "above everything",
+      "above all",
+      "on top of everything",
+      "sits on top",
+      "on top",
+      "over everything",
+      "over all",
+      "topmost",
+      "highest layer"
+    ]
+  },
+  {
+    tag: "blocking",
+    keywords: [
+      "above everything",
+      "on top of everything",
+      "over everything",
+      "block",
+      "blocking",
+      "must dismiss",
+      "interrupt",
+      "take over",
+      "stops everything",
+      "requires a response",
+      "can't ignore",
+      "cannot ignore"
+    ]
+  },
+  {
+    tag: "inline",
+    keywords: ["inline", "in place", "in the flow", "within the page", "non-blocking"]
+  },
+  {
+    tag: "passive",
+    keywords: ["passive", "non-intrusive", "subtle", "quietly", "in the background"]
+  },
+  {
+    tag: "attention",
+    keywords: ["attention", "notice", "get noticed", "important message"]
+  },
+  {
+    tag: "hint",
+    keywords: ["hint", "a tip", "explain", "extra info", "more info"]
+  },
+  {
+    tag: "hover",
+    keywords: ["hover", "on hover", "mouse over"]
+  }
+];
+function isNaturalLanguageQuery(input) {
+  return input.includes(" ");
+}
+function matchIntent(query, graph) {
+  const normalized = query.toLowerCase();
+  const matchedTags = collectMatchedTags(normalized);
+  if (matchedTags.size === 0) return noMatch();
+  const winner = selectUse(matchedTags, graph);
+  if (winner === void 0) return noMatch();
+  const winningTags = winner.tags.filter((tag) => matchedTags.has(tag));
+  const decisive = new Set(winningTags);
+  const nearMiss = selectNearMiss(winner, decisive, matchedTags, graph);
+  if (nearMiss === void 0) return noMatch();
+  const use = describeNode(winner.id, graph);
+  const not = describeNode(nearMiss.id, graph);
+  if (use === void 0 || not === void 0) return noMatch();
+  const divergingTags = nearMiss.tags.filter((tag) => !winner.tags.includes(tag));
+  const because = `${winner.id} is ${winningTags.join("/")}; ${nearMiss.id} is ${divergingTags.join("/")}`;
+  return { use, not, because };
+}
+function collectMatchedTags(normalizedQuery) {
+  const matched = /* @__PURE__ */ new Set();
+  for (const axis of INTENT_AXES) {
+    for (const keyword of axis.keywords) {
+      if (normalizedQuery.includes(keyword)) {
+        matched.add(axis.tag);
+        break;
+      }
+    }
+  }
+  return matched;
+}
+function selectUse(matchedTags, graph) {
+  let best;
+  let bestScore = 0;
+  for (const [id, tags] of Object.entries(INTENT_TAGS)) {
+    if (!graph.nodes.has(id)) continue;
+    const score = tags.reduce((sum, tag) => matchedTags.has(tag) ? sum + 1 : sum, 0);
+    if (score > bestScore) {
+      bestScore = score;
+      best = { id, tags };
+    }
+  }
+  return best;
+}
+function selectNearMiss(use, decisive, matchedTags, graph) {
+  let best;
+  let bestOverlap = 0;
+  for (const [id, tags] of Object.entries(INTENT_TAGS)) {
+    if (id === use.id || !graph.nodes.has(id)) continue;
+    if (tags.some((tag) => decisive.has(tag))) continue;
+    const overlap = tags.filter((tag) => use.tags.includes(tag));
+    const sharesOutsideMatched = overlap.some((tag) => !matchedTags.has(tag));
+    if (!sharesOutsideMatched) continue;
+    if (overlap.length > bestOverlap) {
+      bestOverlap = overlap.length;
+      best = { id, tags };
+    }
+  }
+  return best;
+}
+function describeNode(id, graph) {
+  const result = describe(id, graph);
+  if (!Array.isArray(result) && "children" in result) return result;
+  return void 0;
+}
+function noMatch() {
+  return { note: "no route matched; describe(components) or describe(composites) to browse" };
+}
+
+// src/mcp/overlay.ts
+function buildInstalledSet(config2) {
+  return {
+    components: new Set(config2.installed?.components ?? []),
+    composites: new Set(config2.installed?.composites ?? [])
+  };
+}
+function describeWithOverlay(addr, graph, ctx) {
+  const result = describe(addr, graph, ctx.target);
+  if (addr === "components" || addr === "composites") {
+    const set3 = addr === "components" ? ctx.installed.components : ctx.installed.composites;
+    const roster = result;
+    return roster.map((entry) => ({ id: entry.id, presence: presenceOf(set3, entry.id) }));
+  }
+  if (addr !== "" && !addr.includes(".") && isNodeResult(result)) {
+    const set3 = result.kind === "component" ? ctx.installed.components : ctx.installed.composites;
+    return {
+      ...result,
+      presence: presenceOf(set3, result.id),
+      target: ctx.target,
+      rendersForTarget: ctx.target !== void 0 && graph.nodes.get(result.id)?.facets[ctx.target] !== void 0
+    };
+  }
+  return result;
+}
+function presenceOf(set3, id) {
+  return set3.has(id) ? "installed" : "available";
+}
+function isNodeResult(result) {
+  return typeof result === "object" && result !== null && !Array.isArray(result) && "id" in result && "kind" in result && "children" in result;
+}
+
 // src/mcp/tools.ts
+function isSafeRelPath(p2) {
+  if (isAbsolute3(p2)) return false;
+  return !p2.split(/[/\\]/).includes("..");
+}
+var SafePathFieldSchema = PathFieldSchema.refine(
+  (field) => {
+    const entries = typeof field === "string" ? [field] : field;
+    return entries.every((e) => isSafeRelPath(typeof e === "string" ? e : e.path));
+  },
+  { message: "path must be relative and stay inside the workspace (no absolute or `..` paths)" }
+);
+var ConfigWiringSchema = external_exports.object({
+  // Closed set -- excludes 'unknown', which is a detection sentinel, not a
+  // valid target a caller may set.
+  framework: external_exports.enum(["next", "vite", "remix", "react-router", "astro", "wc", "vanilla"]),
+  // Must be a valid http(s) URL. (Blocking private/link-local/metadata hosts
+  // is tracked as a follow-up -- see the registryUrl SSRF issue.)
+  registryUrl: external_exports.string().url().refine((u) => /^https?:$/.test(new URL(u).protocol), {
+    message: "registryUrl must be an http(s) URL"
+  }),
+  // Closed set derived from the framework (see ComponentTarget in detect.ts).
+  componentTarget: external_exports.enum(["react", "astro", "vue", "svelte", "wc"]),
+  source: external_exports.string().min(1),
+  cssPath: external_exports.union([external_exports.string(), external_exports.null()]).refine((v) => v === null || isSafeRelPath(v), {
+    message: "cssPath must be relative and stay inside the workspace"
+  }),
+  componentsPath: SafePathFieldSchema,
+  primitivesPath: SafePathFieldSchema,
+  compositesPath: SafePathFieldSchema,
+  rulesPath: SafePathFieldSchema,
+  exports: external_exports.object({
+    tailwind: external_exports.boolean(),
+    typescript: external_exports.boolean(),
+    dtcg: external_exports.boolean(),
+    compiled: external_exports.boolean(),
+    documentation: external_exports.boolean()
+  }).partial()
+}).partial().strict();
+var STUDIO_OWNED_KEYS = ["intent", "darkMode", "fonts"];
+var ADD_MANAGED_KEYS = ["installed"];
 var WORKSPACE_PARAM = {
   workspace: {
     type: "string",
@@ -31248,16 +31640,76 @@ var WORKSPACE_PARAM = {
 var TOOL_DEFINITIONS = [
   {
     name: "rafters_workspaces",
-    description: "List rafters workspaces visible to this MCP session. Returns name, path, and which one is the default for unscoped tool calls. Call this first when the project might be a monorepo.",
+    description: "List rafters workspaces, or update a workspace's WIRING config. Called with no arguments (or just `workspace`): returns each workspace name, path, and which is the default for unscoped tool calls -- call this first when the project might be a monorepo. Called with any wiring field: updates that workspace's .rafters/config.rafters.json -- framework, registryUrl, componentTarget, source, cssPath, and the path fields (componentsPath, primitivesPath, compositesPath, rulesPath) and exports; only fields you pass change. Cannot set designer decisions (intent, darkMode, fonts) -- those are set in Studio -- and cannot set installed -- that is managed by `rafters add`.",
     inputSchema: {
       type: "object",
-      properties: {},
+      properties: {
+        ...WORKSPACE_PARAM,
+        framework: { type: "string", description: 'Target framework (e.g., "react", "astro")' },
+        registryUrl: {
+          type: "string",
+          description: "Registry to install from / query. Point at your own internal registry."
+        },
+        componentTarget: { type: "string", description: "Where installed components are written" },
+        source: { type: "string", description: "Design system this project was imported from" },
+        cssPath: { type: ["string", "null"], description: "Path to the main CSS file, or null" },
+        componentsPath: {
+          oneOf: [{ type: "string" }, { type: "array" }],
+          description: "Folder(s) to read/write components. String or array of entries."
+        },
+        primitivesPath: {
+          oneOf: [{ type: "string" }, { type: "array" }],
+          description: "Folder(s) to read/write primitives. String or array of entries."
+        },
+        compositesPath: {
+          oneOf: [{ type: "string" }, { type: "array" }],
+          description: "Folder(s) to read/write composites. String or array of entries."
+        },
+        rulesPath: {
+          oneOf: [{ type: "string" }, { type: "array" }],
+          description: "Folder(s) to read/write rules. String or array of entries."
+        },
+        exports: {
+          type: "object",
+          description: "Which output formats to emit (tailwind, typescript, dtcg, compiled, documentation)."
+        }
+      },
       required: []
     }
   },
+  {
+    name: "rafters_describe",
+    description: 'Recursively introspect the component/composite intel graph. describe() returns the installed surface; describe(components)/describe(composites) list the kind roster; describe(button) returns a node -- intel plus type-marked, drillable children; describe(button.props.fill) drills into a prop; describe(button.props.fill.vocab) returns the real token values. A natural-language question (e.g. "what do I use when it needs to be above everything") routes to the best-matching node plus a near-miss counter-example instead of an address.',
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...WORKSPACE_PARAM,
+        address: {
+          type: "string",
+          description: 'A dot-address ("button.props.variant") or a natural-language question.'
+        }
+      },
+      required: ["address"]
+    }
+  },
+  {
+    name: "rafters_generate",
+    description: "STUB (Issue E). Will produce a rafters-correct composition with visible placeholders for app-specific fields/actions/copy. Currently returns a structured not-implemented result.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        ...WORKSPACE_PARAM,
+        intent: { type: "string", description: "What to generate" }
+      },
+      required: ["intent"]
+    }
+  },
+  // Deprecated aliases -- kept for one minor release, then removed (tracked as a
+  // follow-up). Input schemas unchanged; every response carries a `deprecated`
+  // field pointing at rafters_describe.
   {
     name: "rafters_composite",
-    description: "Query composites by ID, search term, or category. Returns designer intent (solves, appliesWhen, do/never), I/O rules for chaining, and block structure.",
+    description: "[DEPRECATED -- use rafters_describe] Query composites by ID, search term, or category. Returns designer intent (solves, appliesWhen, do/never), I/O rules for chaining, and block structure.",
     inputSchema: {
       type: "object",
       properties: {
@@ -31271,7 +31723,7 @@ var TOOL_DEFINITIONS = [
   },
   {
     name: "rafters_pattern",
-    description: 'Get design pattern guidance by querying composites. Search by what the pattern solves (e.g., "authentication", "data entry", "navigation") to get do/never rules, cognitive load, and designer intent.',
+    description: '[DEPRECATED -- use rafters_describe] Get design pattern guidance by querying composites. Search by what the pattern solves (e.g., "authentication", "data entry", "navigation") to get do/never rules, cognitive load, and designer intent.',
     inputSchema: {
       type: "object",
       properties: {
@@ -31290,7 +31742,7 @@ var TOOL_DEFINITIONS = [
   },
   {
     name: "rafters_component",
-    description: "Get component intelligence: cognitive load, accessibility, do/never guidance, variants, sizes.",
+    description: "[DEPRECATED -- use rafters_describe] Get component intelligence: cognitive load, accessibility, do/never guidance, variants, sizes.",
     inputSchema: {
       type: "object",
       properties: {
@@ -31304,6 +31756,7 @@ var TOOL_DEFINITIONS = [
     }
   }
 ];
+var DEPRECATED_MSG = "use rafters_describe instead";
 var RaftersToolHandler = class {
   workspaces;
   defaultWorkspace;
@@ -31311,32 +31764,52 @@ var RaftersToolHandler = class {
   compositesLoadedFor = /* @__PURE__ */ new Set();
   /** Tracks built-in composite loading separately (loaded once globally). */
   builtInCompositesLoaded = false;
-  constructor(workspaces, defaultWorkspace) {
+  /**
+   * Registry clients keyed by base URL, so each workspace's `registryUrl` gets
+   * its own fetch cache. Workspaces without a configured URL share the default
+   * singleton (which points at the public registry).
+   */
+  registryClients = /* @__PURE__ */ new Map();
+  /**
+   * Per-workspace-root cache: the intel graph, built once, lazily, on the first
+   * describe/generate call that touches that root. The graph is universal and
+   * target-free (a node carries all its per-target facets); the workspace's
+   * target is applied per query by the overlay, not baked into the cache. Same
+   * per-workspace caching shape as `compositesLoadedFor`/`registryClients`. A
+   * failed build is never inserted, so the next call retries rather than
+   * permanently wedging that workspace.
+   */
+  graphsByWorkspace = /* @__PURE__ */ new Map();
+  /**
+   * The whole-catalog item source `ensureGraph` builds from. Defaults to the
+   * workspace's registry client `fetchAllItems()` (bulk endpoint with per-item
+   * fallback). Injectable so the dispatch can be unit-tested against a fixture
+   * catalog without a network round-trip.
+   */
+  itemsSource;
+  constructor(workspaces, defaultWorkspace, itemsSource) {
     this.workspaces = workspaces;
     this.defaultWorkspace = defaultWorkspace;
+    this.itemsSource = itemsSource ?? (async (ws) => (await this.registryClientFor(ws)).fetchAllItems());
   }
   async handleToolCall(name, args) {
     switch (name) {
       case "rafters_workspaces":
-        return this.handleWorkspaces();
+        return this.handleWorkspaces(args);
+      case "rafters_describe":
+        return this.handleDescribe(args.address, args.workspace);
+      case "rafters_generate":
+        return this.handleGenerate(args.intent, args.workspace);
       case "rafters_composite":
         return this.handleComposite(args);
       case "rafters_pattern":
         return this.handlePattern(args);
       case "rafters_component":
-        return this.handleComponent(args.name);
+        return this.handleComponent(args.name, args.workspace);
       default:
-        return {
-          content: [
-            {
-              type: "text",
-              text: JSON.stringify({
-                error: `Unknown tool: ${name}`,
-                suggestion: "Available tools: rafters_workspaces, rafters_composite, rafters_pattern, rafters_component."
-              })
-            }
-          ]
-        };
+        return this.errorResult(`Unknown tool: ${name}`, {
+          suggestion: "Available tools: rafters_workspaces, rafters_describe, rafters_generate. Deprecated: rafters_composite, rafters_pattern, rafters_component."
+        });
     }
   }
   /**
@@ -31353,42 +31826,84 @@ var RaftersToolHandler = class {
    * Use this when a tool requires a workspace and the agent didn't pick one.
    */
   workspaceRequiredError() {
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify({
-            error: "workspace parameter required",
-            suggestion: "Multiple workspaces are available. Pass `workspace` with one of the names below.",
-            workspaces: this.workspaces.map((w) => ({
-              name: w.name,
-              root: w.root
-            }))
-          })
-        }
-      ]
-    };
+    return this.errorResult("workspace parameter required", {
+      suggestion: "Multiple workspaces are available. Pass `workspace` with one of the names below.",
+      workspaces: this.workspaces.map((w) => ({ name: w.name, root: w.root }))
+    });
   }
-  async handleWorkspaces() {
-    return {
-      content: [
-        {
-          type: "text",
-          text: JSON.stringify(
-            {
-              workspaces: this.workspaces.map((w) => ({
-                name: w.name,
-                root: w.root,
-                isDefault: w.name === this.defaultWorkspace?.name
-              })),
-              defaultWorkspace: this.defaultWorkspace?.name ?? null
-            },
-            null,
-            2
-          )
-        }
-      ]
-    };
+  /** Wrap a JSON-serialisable payload as a text tool result. */
+  jsonResult(payload) {
+    return { content: [{ type: "text", text: JSON.stringify(payload, null, 2) }] };
+  }
+  /** Wrap an error string (with optional extra fields) as a tool result. */
+  errorResult(error47, extra) {
+    return this.jsonResult({ error: error47, ...extra });
+  }
+  /**
+   * List workspaces, or -- when any wiring field is present -- update the
+   * target workspace's config. `workspace` selects which; every other key is
+   * treated as a wiring patch. No wiring keys means the list query.
+   */
+  async handleWorkspaces(args) {
+    const { workspace, ...patch } = args;
+    if (Object.keys(patch).length === 0) {
+      return this.jsonResult({
+        workspaces: this.workspaces.map((w) => ({
+          name: w.name,
+          root: w.root,
+          isDefault: w.name === this.defaultWorkspace?.name
+        })),
+        defaultWorkspace: this.defaultWorkspace?.name ?? null
+      });
+    }
+    return this.updateWorkspaceConfig(workspace, patch);
+  }
+  /**
+   * Write a WIRING patch to a workspace's config.rafters.json. Rejects the
+   * designer-owned keys (intent, darkMode, fonts -> Studio) and add-managed
+   * keys (installed -> `rafters add`) with a pointer to the right surface, so
+   * this path structurally cannot remove designer choice. Only the fields in
+   * the patch change; everything else in the config is preserved.
+   */
+  async updateWorkspaceConfig(workspaceName, patch) {
+    const resolved = this.resolve(workspaceName);
+    if (!resolved) {
+      return this.workspaceRequiredError();
+    }
+    const studioKeys = STUDIO_OWNED_KEYS.filter((k) => k in patch);
+    if (studioKeys.length > 0) {
+      return this.errorResult(
+        `${studioKeys.join(", ")} ${studioKeys.length > 1 ? "are" : "is"} a designer decision owned by Rafters Studio, not the MCP. Set ${studioKeys.length > 1 ? "them" : "it"} in Studio.`
+      );
+    }
+    const addKeys = ADD_MANAGED_KEYS.filter((k) => k in patch);
+    if (addKeys.length > 0) {
+      return this.errorResult(`${addKeys.join(", ")} is managed by \`rafters add\`, not the MCP.`);
+    }
+    const result = ConfigWiringSchema.safeParse(patch);
+    if (!result.success) {
+      return this.errorResult(`invalid wiring patch: ${result.error.message}`);
+    }
+    if (Object.keys(result.data).length === 0) {
+      return this.errorResult("no writable wiring fields provided");
+    }
+    const config2 = await this.readConfig(resolved.root);
+    if (!config2) {
+      return this.errorResult(
+        `no config at ${getRaftersPaths(resolved.root).config} -- run \`rafters init\` first`
+      );
+    }
+    const updated = { ...config2, ...result.data };
+    if (result.data.exports !== void 0) {
+      updated.exports = { ...config2.exports, ...result.data.exports };
+    }
+    try {
+      await this.writeConfig(resolved.root, updated);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return this.errorResult(`failed to write config: ${message}`);
+    }
+    return this.jsonResult({ ok: true, workspace: resolved.name, updated: result.data });
   }
   /**
    * Recursively discover composites under the given directories via the shared
@@ -31417,6 +31932,138 @@ var RaftersToolHandler = class {
       this.compositesLoadedFor.add(workspace.root);
     }
   }
+  /**
+   * Read and migrate a workspace's `.rafters/config.rafters.json`. Returns null
+   * when the file is absent or unparseable. The single config read the MCP
+   * tools share -- composite paths and the registry URL both come through here.
+   */
+  async readConfig(workspaceRoot) {
+    const paths = getRaftersPaths(workspaceRoot);
+    try {
+      return migrateConfig(
+        JSON.parse(await readFile6(paths.config, "utf-8"))
+      );
+    } catch {
+      return null;
+    }
+  }
+  /** Persist a workspace's config back to `.rafters/config.rafters.json`. */
+  async writeConfig(workspaceRoot, config2) {
+    const paths = getRaftersPaths(workspaceRoot);
+    await writeFile4(paths.config, `${JSON.stringify(config2, null, 2)}
+`);
+  }
+  /**
+   * Resolve the registry client for a workspace, honoring its configured
+   * `registryUrl`. Workspaces with no config, or no `registryUrl`, share the
+   * default singleton. Clients are cached per URL so each keeps its fetch cache.
+   */
+  async registryClientFor(workspace) {
+    if (!workspace) return registryClient;
+    const url3 = (await this.readConfig(workspace.root))?.registryUrl;
+    if (!url3) return registryClient;
+    let client = this.registryClients.get(url3);
+    if (!client) {
+      client = new RegistryClient(url3);
+      this.registryClients.set(url3, client);
+    }
+    return client;
+  }
+  /**
+   * Build (once, lazily) and cache the intel graph for a workspace root.
+   * `assembleGraph` (#2072/#2090) consumes the whole-catalog `RegistryItem[]` and
+   * carries each node's complete intelligence and all per-target facets onto the
+   * universal graph. Throws when the catalog can't be loaded (both the bulk
+   * endpoint and the per-item fallback failed) or the graph is structurally
+   * broken (a dangling `composesWith` edge -- #2072's deliberate fail-fast); the
+   * caller converts that into a structured error result. A failed build is never
+   * cached, so the next call retries.
+   */
+  async ensureGraph(workspace) {
+    const key = workspace?.root ?? "";
+    const cached2 = this.graphsByWorkspace.get(key);
+    if (cached2) return cached2;
+    const graph = assembleGraph(await this.itemsSource(workspace));
+    this.graphsByWorkspace.set(key, graph);
+    return graph;
+  }
+  /**
+   * Resolve a workspace's overlay context: the configured `componentTarget`
+   * (echoed as-is, `undefined` in degraded mode) and its installed set. Per the
+   * integration note on #2074, `installed.primitives` folds into the components
+   * set -- a `primitive`-kind item maps to graph kind `component`, so without the
+   * fold every installed primitive would misreport as `available`. Built here
+   * rather than by mutating `buildInstalledSet`'s output, leaving overlay.ts
+   * untouched.
+   *
+   * `componentTarget` comes off unvalidated on-disk config (`readConfig` is a raw
+   * `JSON.parse`), so it is run through `ComponentTargetSchema` here rather than
+   * trusted as a `ComponentTarget` -- a stale or typo'd value falls back to
+   * degraded mode (`undefined` target) instead of silently forcing
+   * `rendersForTarget` false for every node.
+   */
+  async overlayContext(workspace) {
+    const config2 = workspace ? await this.readConfig(workspace.root) : null;
+    const base = buildInstalledSet(config2 ?? {});
+    const components = /* @__PURE__ */ new Set([...base.components, ...config2?.installed?.primitives ?? []]);
+    const parsedTarget = ComponentTargetSchema.safeParse(config2?.componentTarget);
+    return {
+      target: parsedTarget.success ? parsedTarget.data : void 0,
+      installed: { components, composites: base.composites }
+    };
+  }
+  /**
+   * The `rafters_describe` dispatcher -- the one seam that composes #2072/#2074/
+   * #2075. A natural-language question routes through the intent door
+   * (`matchIntent`); a dot-address resolves through the workspace overlay
+   * (`describeWithOverlay`, which delegates to #2072's `describe`).
+   */
+  async handleDescribe(address, workspaceName) {
+    const resolved = this.resolve(workspaceName);
+    if (workspaceName && !resolved) {
+      return this.workspaceRequiredError();
+    }
+    let graph;
+    try {
+      graph = await this.ensureGraph(resolved);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : "Unknown error";
+      return this.errorResult(`failed to build intel graph: ${message}`);
+    }
+    if (isNaturalLanguageQuery(address)) {
+      return this.jsonResult(matchIntent(address, graph));
+    }
+    const ctx = await this.overlayContext(resolved);
+    return this.jsonResult(describeWithOverlay(address, graph, ctx));
+  }
+  /**
+   * The `rafters_generate` stub (Issue E). Registered now so the surface shape
+   * (name, input schema) stabilizes before the generator lands; it never
+   * attempts real composition. Deliberately does NOT build the graph: nothing
+   * here reads it, and a build failure must not turn an honest stub into an
+   * error result.
+   */
+  async handleGenerate(intent, workspaceName) {
+    const resolved = this.resolve(workspaceName);
+    if (workspaceName && !resolved) {
+      return this.workspaceRequiredError();
+    }
+    return this.jsonResult({
+      implemented: false,
+      note: `generate is a spike -- see issue E; not yet implemented (requested: ${intent})`
+    });
+  }
+  /**
+   * Stamp the deprecated marker as a top-level field. Objects gain a sibling
+   * `deprecated` key; the rare array/leaf result is wrapped so the marker still
+   * rides at top level.
+   */
+  withDeprecated(payload) {
+    if (typeof payload === "object" && payload !== null && !Array.isArray(payload)) {
+      return { ...payload, deprecated: DEPRECATED_MSG };
+    }
+    return { result: payload, deprecated: DEPRECATED_MSG };
+  }
   /**
    * Resolve the set of folders to scan for composite manifests in a workspace.
    * Reads `.rafters/config.rafters.json` and applies the workspace's
@@ -31426,13 +32073,7 @@ var RaftersToolHandler = class {
    */
   async compositeReadRoots(workspaceRoot) {
     const paths = getRaftersPaths(workspaceRoot);
-    let config2 = null;
-    try {
-      config2 = migrateConfig(
-        JSON.parse(await readFile6(paths.config, "utf-8"))
-      );
-    } catch {
-    }
+    const config2 = await this.readConfig(workspaceRoot);
     if (!config2?.compositesPath) {
       return [join12(paths.root, "composites")];
     }
@@ -31440,16 +32081,16 @@ var RaftersToolHandler = class {
   }
   async handleComposite(args) {
     const { id, query, category, workspace } = args;
+    if (id) {
+      return this.describeById(id, workspace);
+    }
     const resolved = this.resolve(workspace);
     if (workspace && !resolved) {
       return this.workspaceRequiredError();
     }
     await this.ensureCompositesLoaded(resolved);
     let composites2;
-    if (id) {
-      const c4 = get2(id);
-      composites2 = c4 ? [c4] : [];
-    } else if (query) {
+    if (query) {
       composites2 = search(query);
     } else if (category) {
       composites2 = getByCategory(category);
@@ -31474,9 +32115,7 @@ var RaftersToolHandler = class {
       // are listed -- the array is empty when nothing is constrained.
       blockRules: c4.blocks.filter((b2) => b2.rules && b2.rules.length > 0).map((b2) => ({ id: b2.id, type: b2.type, rules: b2.rules }))
     }));
-    return {
-      content: [{ type: "text", text: JSON.stringify({ composites: result }, null, 2) }]
-    };
+    return this.jsonResult({ composites: result, deprecated: DEPRECATED_MSG });
   }
   async handlePattern(args) {
     const { solves, query, workspace } = args;
@@ -31503,17 +32142,10 @@ var RaftersToolHandler = class {
         id: c4.manifest.id,
         solves: c4.manifest.solves
       }));
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({
-              error: "No patterns found matching query",
-              available
-            })
-          }
-        ]
-      };
+      return this.errorResult("No patterns found matching query", {
+        available,
+        deprecated: DEPRECATED_MSG
+      });
     }
     const patterns = composites2.map((c4) => ({
       id: c4.manifest.id,
@@ -31523,51 +32155,38 @@ var RaftersToolHandler = class {
       cognitiveLoad: c4.manifest.cognitiveLoad,
       usagePatterns: c4.manifest.usagePatterns
     }));
-    return {
-      content: [{ type: "text", text: JSON.stringify({ patterns }, null, 2) }]
-    };
+    return this.jsonResult({ patterns, deprecated: DEPRECATED_MSG });
   }
-  async handleComponent(componentName) {
+  /**
+   * DEPRECATED alias for `rafters_describe`. A component resolves by id through
+   * the overlay exactly as `describe(<id>)` does (#2072's resolver has no
+   * separate component/composite address form -- `describe(<id>)` resolves either
+   * kind), so this is a direct, lossless forward with the deprecated marker added.
+   */
+  async handleComponent(componentName, workspaceName) {
+    return this.describeById(componentName, workspaceName);
+  }
+  /**
+   * Shared by the deprecated `rafters_component` and `rafters_composite({id})`
+   * paths: resolve one id through the overlay, stamp the deprecated marker.
+   */
+  async describeById(id, workspaceName) {
+    const resolved = this.resolve(workspaceName);
+    if (workspaceName && !resolved) {
+      return this.workspaceRequiredError();
+    }
+    let graph;
     try {
-      const item = await registryClient.fetchComponent(componentName);
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify(
-              {
-                name: item.name,
-                type: item.type,
-                description: item.description,
-                primitives: item.primitives,
-                rules: item.rules,
-                composites: item.composites,
-                files: item.files,
-                // The intelligence field carries the WHY of the component:
-                // cognitive load, accessibility, do/never, semantic meaning.
-                // Extracted from JSDoc by the registry generator and present
-                // on every component JSON. Previously stripped by the schema
-                // (not declared) and not referenced by the handler -- the
-                // tool's whole reason for existing went missing somewhere.
-                intelligence: item.intelligence
-              },
-              null,
-              2
-            )
-          }
-        ]
-      };
+      graph = await this.ensureGraph(resolved);
     } catch (err) {
       const message = err instanceof Error ? err.message : "Unknown error";
-      return {
-        content: [
-          {
-            type: "text",
-            text: JSON.stringify({ error: message })
-          }
-        ]
-      };
+      return this.errorResult(`failed to build intel graph: ${message}`, {
+        deprecated: DEPRECATED_MSG
+      });
     }
+    const ctx = await this.overlayContext(resolved);
+    const out = describeWithOverlay(id, graph, ctx);
+    return this.jsonResult(this.withDeprecated(out));
   }
 };
 
@@ -31644,8 +32263,8 @@ import { existsSync as existsSync8 } from "fs";
 import { resolve as resolve6 } from "path";
 
 // ../studio/src/api/vite-plugin.ts
-import { readFile as readFile7, writeFile as writeFile4 } from "fs/promises";
-import { isAbsolute as isAbsolute3, join as join14 } from "path";
+import { readFile as readFile7, writeFile as writeFile5 } from "fs/promises";
+import { isAbsolute as isAbsolute4, join as join14 } from "path";
 var REGISTRY_PLUGINS3 = [scalePlugin, contrastPlugin, statePlugin, invertPlugin];
 var STUDIO_REASON_DEFAULT = "studio interactive edit";
 var TokenResponseSchema = external_exports.object({
@@ -31706,7 +32325,7 @@ async function readRaftersConfig() {
 }
 function validateFontsPath(path) {
   if (path === null || path === void 0) return null;
-  if (isAbsolute3(path)) return "fonts path must be relative";
+  if (isAbsolute4(path)) return "fonts path must be relative";
   return null;
 }
 function validateIntent(intent) {
@@ -31725,6 +32344,17 @@ var SetTokenMessageSchema = external_exports.object({
   persist: external_exports.boolean().optional(),
   reason: external_exports.string().optional()
 });
+var ConfigPatchSchema = external_exports.object({
+  intent: external_exports.string().min(1).optional(),
+  darkMode: external_exports.enum(["class", "media"]).optional(),
+  fonts: FontsConfigSchema.optional()
+}).refine((patch) => Object.keys(patch).length > 0, {
+  message: "patch must set at least one of: intent, darkMode, fonts"
+});
+function ridOf(rawData) {
+  const rid = rawData?.__rid;
+  return typeof rid === "string" ? rid : void 0;
+}
 var TokenPatchSchema = TokenSchema.pick({
   value: true,
   trustLevel: true,
@@ -32235,83 +32865,60 @@ function studioApiPlugin() {
           client.send("rafters:token-updated", { ok: false, error: String(error47) });
         }
       });
-      server.ws.on("rafters:get-config", async (_rawData, client) => {
+      server.ws.on("rafters:get-config", async (rawData, client) => {
+        const __rid = ridOf(rawData);
+        const reply = (msg) => client.send("rafters:config", { ...msg, __rid });
         const config2 = await readRaftersConfig();
         if (!config2) {
-          client.send("rafters:config", {
-            ok: false,
-            error: `config not found at ${configPath}`
-          });
+          reply({ ok: false, error: `config not found at ${configPath}` });
           return;
         }
-        client.send("rafters:config", { ok: true, config: config2 });
+        reply({ ok: true, config: config2 });
       });
-      server.ws.on("rafters:set-intent", async (rawData, client) => {
-        const parsed = external_exports.object({ intent: external_exports.string().min(1) }).safeParse(rawData);
+      server.ws.on("rafters:set-config", async (rawData, client) => {
+        const __rid = ridOf(rawData);
+        const reply = (msg) => client.send("rafters:config", { ...msg, __rid });
+        const parsed = ConfigPatchSchema.safeParse(rawData);
         if (!parsed.success) {
-          client.send("rafters:intent-updated", {
-            ok: false,
-            error: `Invalid message: ${parsed.error.message}`
-          });
-          return;
-        }
-        const { intent } = parsed.data;
-        const intentError = validateIntent(intent);
-        if (intentError) {
-          client.send("rafters:intent-updated", { ok: false, error: intentError });
-          return;
-        }
-        const config2 = await readRaftersConfig();
-        if (!config2) {
-          client.send("rafters:intent-updated", {
-            ok: false,
-            error: `config not found at ${configPath}`
-          });
+          reply({ ok: false, error: `Invalid patch: ${parsed.error.message}` });
           return;
         }
-        const updated = { ...config2, intent };
-        try {
-          await writeFile4(configPath, JSON.stringify(updated, null, 2));
-          client.send("rafters:intent-updated", { ok: true, intent });
-        } catch (error47) {
-          console.log(`[rafters] Intent update failed: ${error47}`);
-          client.send("rafters:intent-updated", { ok: false, error: String(error47) });
-        }
-      });
-      server.ws.on("rafters:set-fonts", async (rawData, client) => {
-        const parsed = FontsConfigSchema.safeParse(rawData);
-        if (!parsed.success) {
-          client.send("rafters:fonts-updated", {
-            ok: false,
-            error: `Invalid message: ${parsed.error.message}`
-          });
-          return;
+        const patch = parsed.data;
+        if (patch.intent !== void 0) {
+          const intentError = validateIntent(patch.intent);
+          if (intentError) {
+            reply({ ok: false, error: intentError });
+            return;
+          }
         }
-        const fontsData = parsed.data;
-        const pathError = validateFontsPath(fontsData.path);
-        if (pathError) {
-          client.send("rafters:fonts-updated", { ok: false, error: pathError });
-          return;
+        if (patch.fonts?.path !== void 0) {
+          const pathError = validateFontsPath(patch.fonts.path);
+          if (pathError) {
+            reply({ ok: false, error: pathError });
+            return;
+          }
         }
         const config2 = await readRaftersConfig();
         if (!config2) {
-          client.send("rafters:fonts-updated", {
-            ok: false,
-            error: `config not found at ${configPath}`
-          });
+          reply({ ok: false, error: `config not found at ${configPath}` });
           return;
         }
-        const existing = config2.fonts ?? {};
-        const fonts = { ...existing };
-        if (fontsData.path !== void 0) fonts.path = fontsData.path;
-        if (fontsData.imports !== void 0) fonts.imports = fontsData.imports;
-        const updated = { ...config2, fonts };
+        const updated = { ...config2 };
+        if (patch.intent !== void 0) updated.intent = patch.intent;
+        if (patch.darkMode !== void 0) updated.darkMode = patch.darkMode;
+        if (patch.fonts !== void 0) {
+          const merged = { ...config2.fonts };
+          if (patch.fonts.path !== void 0) merged.path = patch.fonts.path;
+          if (patch.fonts.imports !== void 0) merged.imports = patch.fonts.imports;
+          updated.fonts = merged;
+        }
         try {
-          await writeFile4(configPath, JSON.stringify(updated, null, 2));
-          client.send("rafters:fonts-updated", { ok: true, fonts });
+          await writeFile5(configPath, `${JSON.stringify(updated, null, 2)}
+`);
+          reply({ ok: true, config: updated });
         } catch (error47) {
-          console.log(`[rafters] Fonts update failed: ${error47}`);
-          client.send("rafters:fonts-updated", { ok: false, error: String(error47) });
+          console.log(`[rafters] Config update failed: ${error47}`);
+          reply({ ok: false, error: String(error47) });
         }
       });
       server.middlewares.use(async (req, res, next) => {