@oprt/cli 0.1.0 → 0.3.0

package/dist/index.cjs

@@ -22,26 +22,38 @@ var index_exports = {};
 __export(index_exports, {
   CliError: () => CliError,
   DEFAULT_OUT: () => DEFAULT_OUT,
+  RESULT_SCHEMAS: () => RESULT_SCHEMAS,
+  RESULT_SCHEMA_VERSION: () => RESULT_SCHEMA_VERSION,
+  RESULT_TYPES: () => RESULT_TYPES,
   TOOLS: () => TOOLS,
   VERSION: () => VERSION,
   applyBlock: () => applyBlock,
   blockVersion: () => blockVersion,
+  buildCheckReport: () => buildCheckReport,
+  checkExitCode: () => checkExitCode,
   checkPaths: () => checkPaths,
   checkSource: () => checkSource,
   componentDetail: () => componentDetail,
   componentIndex: () => componentIndex,
   contract: () => contract,
+  contractDigest: () => contractDigest,
   doctor: () => doctor,
+  envelope: () => envelope,
+  errorEnvelope: () => errorEnvelope,
   handleMessage: () => handleMessage,
+  identityOf: () => identityOf,
   init: () => init,
   install: () => install,
+  outputSchemaFor: () => outputSchemaFor,
   parseArgs: () => parseArgs,
   registry: () => registry,
   removeBlock: () => removeBlock,
   renderAgentBlock: () => renderAgentBlock,
+  renderCheckText: () => renderCheckText,
   renderComponent: () => renderComponent,
   resolveEntries: () => resolveEntries,
   runAgentCommand: () => runAgentCommand,
+  schemaFor: () => schemaFor,
   search: () => search,
   serve: () => serve
 });
@@ -53,78 +65,9 @@ var importMetaUrl = /* @__PURE__ */ getImportMetaUrl();
 
 // src/index.ts
 var import_node_fs6 = require("fs");
-var import_node_path6 = require("path");
+var import_node_path7 = require("path");
 var import_node_url3 = require("url");
 
-// package.json
-var package_default = {
-  name: "@oprt/cli",
-  version: "0.1.0",
-  description: "The OPERATOR command line: copy components and recipes into your app as source, give coding agents the contract, and check their code against it. Includes an MCP server.",
-  keywords: [
-    "design-system",
-    "cli",
-    "coding-agents",
-    "mcp",
-    "model-context-protocol",
-    "code-check",
-    "components"
-  ],
-  homepage: "https://oprt.dev/docs/agents/cli",
-  type: "module",
-  main: "./dist/index.cjs",
-  module: "./dist/index.js",
-  types: "./dist/index.d.ts",
-  bin: {
-    oprt: "./dist/bin.js"
-  },
-  engines: {
-    node: ">=22"
-  },
-  exports: {
-    ".": {
-      import: {
-        types: "./dist/index.d.ts",
-        default: "./dist/index.js"
-      },
-      require: {
-        types: "./dist/index.d.cts",
-        default: "./dist/index.cjs"
-      }
-    },
-    "./read": {
-      import: {
-        types: "./dist/read.d.ts",
-        default: "./dist/read.js"
-      },
-      require: {
-        types: "./dist/read.d.cts",
-        default: "./dist/read.cjs"
-      }
-    }
-  },
-  files: [
-    "dist"
-  ],
-  scripts: {
-    clean: `node -e "require('node:fs').rmSync('dist',{recursive:true,force:true})"`,
-    build: "pnpm run clean && node scripts/build-registry.mjs && tsup",
-    dev: "pnpm run clean && node scripts/build-registry.mjs && tsup --watch",
-    test: "vitest run",
-    typecheck: "tsc --noEmit",
-    lint: "eslint src scripts"
-  },
-  devDependencies: {
-    tsup: "^8.3.0",
-    typescript: "^5.6.3",
-    vitest: "^2.1.3"
-  },
-  license: "MIT",
-  publishConfig: {
-    access: "public"
-  }
-};
-
 // src/contract.ts
 var import_node_fs = require("fs");
 var import_node_path = require("path");
@@ -159,6 +102,197 @@ var CliError = class extends Error {
   suggestions;
 };
 
+// src/lookup.ts
+var SEARCH_LIMIT_MAX = 50;
+var SEARCH_LIMIT_DEFAULT = 10;
+var squash = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, "");
+var firstSentence = (text2) => /^.*?[.!?](?=\s|$)/.exec(text2)?.[0] ?? text2;
+function distance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, index) => index);
+  for (let i = 1; i <= a.length; i++) {
+    let diagonal = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const above = row[j];
+      row[j] = Math.min(above + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
+      diagonal = above;
+    }
+  }
+  return row[b.length];
+}
+function nearest(wanted, names2, limit = 5) {
+  const target = squash(wanted);
+  return names2.map((name) => {
+    const candidate = squash(name);
+    const apart = distance(target, candidate);
+    const close = apart <= 2 || target.length >= 3 && (candidate.includes(target) || target.includes(candidate));
+    return { name, apart, close };
+  }).filter(({ close }) => close).sort((a, b) => a.apart - b.apart || a.name.localeCompare(b.name)).slice(0, limit).map(({ name }) => name);
+}
+function resolveComponent(contract2, wanted) {
+  const names2 = Object.keys(contract2.components);
+  const found = names2.find((name) => name === wanted) ?? names2.find((name) => squash(name) === squash(wanted));
+  if (found !== void 0) return found;
+  const suggestions = nearest(wanted, names2);
+  throw new CliError(
+    `Unknown component ${JSON.stringify(wanted)}.` + (suggestions.length > 0 ? ` Did you mean ${suggestions.join(", ")}?` : "") + " Run oprt component --list.",
+    2,
+    { code: "ERR_UNKNOWN_COMPONENT", suggestions }
+  );
+}
+function allowedChildren(rules, name) {
+  for (const [parent, rule] of Object.entries(rules ?? {})) {
+    if (parent === name) return rule.allowed_children;
+    const nested = allowedChildren(rule.children, name);
+    if (nested !== void 0) return nested;
+  }
+  return void 0;
+}
+var partsOf = (contract2, name) => Object.keys(contract2.components).filter(
+  (part) => contract2.guidance.components[part]?.part_of === name
+);
+function componentIndex(contract2) {
+  return Object.keys(contract2.components).filter((name) => (contract2.guidance.components[name]?.use_for ?? []).length > 0).sort((a, b) => a.localeCompare(b)).map((name) => ({
+    name,
+    purpose: contract2.guidance.components[name].use_for.join("; "),
+    parts: partsOf(contract2, name)
+  }));
+}
+function componentDetail(contract2, wanted) {
+  const name = resolveComponent(contract2, wanted);
+  const component = contract2.components[name];
+  const guide = contract2.guidance.components[name] ?? {};
+  const props = Object.entries(component.props).map(([prop, definition]) => {
+    const notes = guide.values?.[prop];
+    return { name: prop, ...definition, ...notes === void 0 ? {} : { notes } };
+  });
+  const allowed = allowedChildren(contract2.composition_rules, name);
+  return {
+    name,
+    description: component.description,
+    use_for: guide.use_for ?? [],
+    not_for: guide.not_for ?? [],
+    ...guide.part_of === void 0 ? {} : { part_of: guide.part_of },
+    parts: partsOf(contract2, name),
+    props,
+    ...component.slots === void 0 ? {} : { slots: component.slots },
+    composable_with: component.composable_with ?? [],
+    never_inside: component.never_inside ?? [],
+    ...allowed === void 0 ? {} : { allowed_children: allowed },
+    example: component.example
+  };
+}
+function propLine(prop, dense) {
+  const kind = prop.type === "enum" ? (prop.values ?? []).map((value) => value === prop.default ? `${value} (default)` : value).join(" | ") : (prop.type === "union" ? (prop.types ?? []).join(" or ") : prop.type) + (prop.default === void 0 ? "" : ` (default ${String(prop.default)})`);
+  const description = prop.description === void 0 ? "" : dense ? firstSentence(prop.description) : prop.description;
+  const lines = [
+    `  ${prop.name}: ${kind}${prop.required ? ", required" : ""}${description ? `. ${description}` : ""}`
+  ];
+  for (const [value, note] of Object.entries(prop.notes ?? {})) lines.push(`    ${value}: ${note}`);
+  return lines;
+}
+function renderComponent(detail, { dense }) {
+  const lines = [
+    detail.part_of === void 0 ? `${detail.name}: ${detail.use_for.join("; ")}` : `${detail.name}: a part of ${detail.part_of}. ${firstSentence(detail.description)}`
+  ];
+  if (detail.not_for.length > 0)
+    lines.push(
+      `Not for: ${detail.not_for.map(({ need, use }) => `${need} (use ${use})`).join("; ")}`
+    );
+  if (!dense) lines.push("", detail.description, "");
+  if (detail.props.length > 0) {
+    lines.push("Props:");
+    for (const prop of detail.props) lines.push(...propLine(prop, dense));
+  }
+  for (const [slot, { type, required }] of Object.entries(detail.slots ?? {}))
+    lines.push(
+      `${slot === "children" ? "Children" : `Slot ${slot}`}: ${type}${required ? ", required" : ""}`
+    );
+  if (detail.parts.length > 0) lines.push(`Parts: ${detail.parts.join(", ")}`);
+  if (detail.allowed_children !== void 0)
+    lines.push(`Takes directly inside: ${detail.allowed_children.join(", ")}`);
+  if (detail.composable_with.length > 0)
+    lines.push(`Goes inside: ${detail.composable_with.join(", ")}`);
+  if (detail.never_inside.length > 0) lines.push(`Never inside: ${detail.never_inside.join(", ")}`);
+  lines.push(
+    detail.example.includes("\n") ? `Example:
+${detail.example.split("\n").map((line) => `  ${line}`).join("\n")}` : `Example: ${detail.example}`
+  );
+  return `${lines.join("\n")}
+`;
+}
+var STOP = new Set(
+  "a an the to of for in on at with and or i we need want that which is are it its my some from by".split(
+    " "
+  )
+);
+var words = (text2) => (text2.toLowerCase().match(/[a-z0-9]+/g) ?? []).filter((word) => !STOP.has(word)).map((word) => word.length > 4 ? word.replace(/(?:ing|ed|es|s)$/, "") : word);
+var matched = (query, text2) => {
+  const present = new Set(words(text2));
+  return query.filter((word) => present.has(word)).length;
+};
+function search(contract2, registry2, query, limit = SEARCH_LIMIT_DEFAULT) {
+  const wanted = words(query);
+  if (wanted.length === 0) return [];
+  const whole = squash(query);
+  const scores = /* @__PURE__ */ new Map();
+  const add = (name, points, why) => {
+    const before = scores.get(name) ?? { score: 0 };
+    scores.set(name, {
+      score: before.score + points,
+      ...before.why !== void 0 ? { why: before.why } : why !== void 0 ? { why } : {}
+    });
+  };
+  for (const [name, component] of Object.entries(contract2.components)) {
+    const guide = contract2.guidance.components[name] ?? {};
+    const plain = squash(name);
+    if (plain === whole) add(name, 100);
+    else if (wanted.some((word) => word.length >= 3 && plain.includes(word))) add(name, 15);
+    else if (wanted.some((word) => word.length >= 4 && distance(word, plain) <= 1)) add(name, 12);
+    for (const phrase of guide.use_for ?? []) {
+      const hits = matched(wanted, phrase);
+      if (hits > 0) add(name, 12 * hits + (hits === wanted.length ? 40 : 0));
+    }
+    for (const { need, use } of guide.not_for ?? []) {
+      const hits = matched(wanted, need);
+      if (hits > 0 && hits >= Math.ceil(wanted.length * 0.6))
+        add(use, 10 * hits + (hits === wanted.length ? 15 : 0), `${name} is not for this: ${need}`);
+    }
+    const inDescription = matched(wanted, component.description);
+    if (inDescription > 0) add(name, 2 * inDescription);
+  }
+  const results = [];
+  for (const [name, { score, why }] of scores) {
+    const guide = contract2.guidance.components[name] ?? {};
+    results.push({
+      kind: "component",
+      name,
+      purpose: guide.part_of === void 0 ? (guide.use_for ?? []).join("; ") : `a part of ${guide.part_of}`,
+      score,
+      ...why === void 0 ? {} : { why },
+      next: `oprt component ${name}`
+    });
+  }
+  for (const entry of registry2.entries.filter(({ kind }) => kind === "recipe")) {
+    const recipe = contract2.patterns?.[entry.name];
+    const plain = squash(entry.name);
+    const inName = plain === whole ? 100 : wanted.some((word) => word.length >= 3 && plain.includes(word)) ? 15 : 0;
+    const hits = matched(wanted, entry.description);
+    const score = inName + (hits > 0 ? 10 * hits + (hits === wanted.length ? 15 : 0) : 0);
+    if (score > 0)
+      results.push({
+        kind: "recipe",
+        name: entry.name,
+        purpose: firstSentence(entry.description),
+        score,
+        next: recipe?.install ?? `oprt add ${entry.slug}`
+      });
+  }
+  results.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+  const floor = Math.max(4, (results[0]?.score ?? 0) * 0.15);
+  return results.filter(({ score }) => score >= floor).slice(0, limit);
+}
+
 // src/args.ts
 var DEFAULT_OUT = "src/components/operator";
 function split(command, rest, spec) {
@@ -214,9 +348,10 @@ var AGENT_COMMANDS = {
       "--json": "flag"
     });
     if (positional.length === 0) throw new CliError("Usage: oprt search <need> [--limit <n>]", 2);
-    const limit = value("--limit") === void 0 ? 10 : Number(value("--limit"));
-    if (!Number.isInteger(limit) || limit < 1)
-      throw new CliError("--limit takes a whole number above zero.", 2);
+    const given = value("--limit");
+    const limit = given === void 0 ? SEARCH_LIMIT_DEFAULT : Number(given);
+    if (!Number.isInteger(limit) || limit < 1 || limit > SEARCH_LIMIT_MAX)
+      throw new CliError(`--limit takes a whole number from 1 to ${SEARCH_LIMIT_MAX}.`, 2);
     return { command: "search", query: positional.join(" "), limit, json: has("--json") };
   },
   init(rest) {
@@ -279,7 +414,8 @@ function parseArgs(args) {
     names: [],
     out: DEFAULT_OUT,
     dryRun: false,
-    overwrite: false
+    overwrite: false,
+    json: false
   };
   const seen = /* @__PURE__ */ new Set();
   for (let i = 0; i < rest.length; i++) {
@@ -288,7 +424,7 @@ function parseArgs(args) {
       parsed.names.push(token);
       continue;
     }
-    if (!["--out", "--dry-run", "--overwrite"].includes(token))
+    if (!["--out", "--dry-run", "--overwrite", "--json"].includes(token))
       throw new CliError(`Unknown option ${JSON.stringify(token)}. Run oprt --help.`, 2);
     if (seen.has(token)) throw new CliError(`Duplicate option ${token}.`, 2);
     seen.add(token);
@@ -298,6 +434,7 @@ function parseArgs(args) {
         throw new CliError("--out requires a relative directory.", 2);
       parsed.out = value;
     } else if (token === "--dry-run") parsed.dryRun = true;
+    else if (token === "--json") parsed.json = true;
     else parsed.overwrite = true;
   }
   if (!parsed.names.length)
@@ -306,10 +443,10 @@ function parseArgs(args) {
 }
 
 // src/installer.ts
-function resolveEntries(names, registry2) {
-  if (!names.length) throw new CliError("add requires one or more names.", 2);
+function resolveEntries(names2, registry2) {
+  if (!names2.length) throw new CliError("add requires one or more names.", 2);
   const selected = /* @__PURE__ */ new Map();
-  for (const name of names) {
+  for (const name of names2) {
     const normalized = name.toLowerCase();
     const entry = registry2.entries.find(
       (candidate) => candidate.slug === normalized || candidate.name.toLowerCase() === normalized
@@ -417,202 +554,196 @@ function installSources(options, context) {
   return result;
 }
 
-// src/check.ts
-var import_node_fs3 = require("fs");
-var import_node_module = require("module");
-var import_node_path3 = require("path");
-var import_node_url2 = require("url");
+// src/identity.ts
+var import_node_crypto = require("crypto");
 
-// src/lookup.ts
-var squash = (name) => name.toLowerCase().replace(/[^a-z0-9]/g, "");
-var firstSentence = (text2) => /^.*?[.!?](?=\s|$)/.exec(text2)?.[0] ?? text2;
-function distance(a, b) {
-  const row = Array.from({ length: b.length + 1 }, (_, index) => index);
-  for (let i = 1; i <= a.length; i++) {
-    let diagonal = row[0];
-    row[0] = i;
-    for (let j = 1; j <= b.length; j++) {
-      const above = row[j];
-      row[j] = Math.min(above + 1, row[j - 1] + 1, diagonal + (a[i - 1] === b[j - 1] ? 0 : 1));
-      diagonal = above;
+// package.json
+var package_default = {
+  name: "@oprt/cli",
+  version: "0.3.0",
+  description: "The OPERATOR command line: copy components and recipes into your app as source, give coding agents the contract, and check their code against it. Includes an MCP server.",
+  keywords: [
+    "design-system",
+    "cli",
+    "coding-agents",
+    "mcp",
+    "model-context-protocol",
+    "code-check",
+    "components"
+  ],
+  homepage: "https://oprt.dev/docs/agents/cli",
+  type: "module",
+  main: "./dist/index.cjs",
+  module: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  bin: {
+    oprt: "./dist/bin.js"
+  },
+  engines: {
+    node: ">=22"
+  },
+  exports: {
+    ".": {
+      import: {
+        types: "./dist/index.d.ts",
+        default: "./dist/index.js"
+      },
+      require: {
+        types: "./dist/index.d.cts",
+        default: "./dist/index.cjs"
+      }
+    },
+    "./read": {
+      import: {
+        types: "./dist/read.d.ts",
+        default: "./dist/read.js"
+      },
+      require: {
+        types: "./dist/read.d.cts",
+        default: "./dist/read.cjs"
+      }
     }
+  },
+  files: [
+    "dist"
+  ],
+  scripts: {
+    clean: `node -e "require('node:fs').rmSync('dist',{recursive:true,force:true})"`,
+    build: "pnpm run clean && node scripts/build-registry.mjs && tsup",
+    dev: "pnpm run clean && node scripts/build-registry.mjs && tsup --watch",
+    test: "vitest run",
+    typecheck: "tsc --noEmit",
+    lint: "eslint src scripts"
+  },
+  devDependencies: {
+    "@modelcontextprotocol/sdk": "1.32.1",
+    tsup: "^8.3.0",
+    typescript: "^5.6.3",
+    vitest: "^2.1.3"
+  },
+  license: "MIT",
+  publishConfig: {
+    access: "public"
   }
-  return row[b.length];
-}
-function nearest(wanted, names, limit = 5) {
-  const target = squash(wanted);
-  return names.map((name) => {
-    const candidate = squash(name);
-    const apart = distance(target, candidate);
-    const close = apart <= 2 || target.length >= 3 && (candidate.includes(target) || target.includes(candidate));
-    return { name, apart, close };
-  }).filter(({ close }) => close).sort((a, b) => a.apart - b.apart || a.name.localeCompare(b.name)).slice(0, limit).map(({ name }) => name);
-}
-function resolveComponent(contract2, wanted) {
-  const names = Object.keys(contract2.components);
-  const found = names.find((name) => name === wanted) ?? names.find((name) => squash(name) === squash(wanted));
-  if (found !== void 0) return found;
-  const suggestions = nearest(wanted, names);
-  throw new CliError(
-    `Unknown component ${JSON.stringify(wanted)}.` + (suggestions.length > 0 ? ` Did you mean ${suggestions.join(", ")}?` : "") + " Run oprt component --list.",
-    2,
-    { code: "ERR_UNKNOWN_COMPONENT", suggestions }
-  );
-}
-function allowedChildren(rules, name) {
-  for (const [parent, rule] of Object.entries(rules ?? {})) {
-    if (parent === name) return rule.allowed_children;
-    const nested = allowedChildren(rule.children, name);
-    if (nested !== void 0) return nested;
+};
+
+// src/identity.ts
+var VERSION = package_default.version;
+var RESULT_SCHEMA_VERSION = 1;
+var digests = /* @__PURE__ */ new WeakMap();
+function contractDigest(contract2) {
+  let digest = digests.get(contract2);
+  if (digest === void 0) {
+    digest = `sha256:${(0, import_node_crypto.createHash)("sha256").update(JSON.stringify(contract2)).digest("hex")}`;
+    digests.set(contract2, digest);
   }
-  return void 0;
+  return digest;
 }
-var partsOf = (contract2, name) => Object.keys(contract2.components).filter(
-  (part) => contract2.guidance.components[part]?.part_of === name
-);
-function componentIndex(contract2) {
-  return Object.keys(contract2.components).filter((name) => (contract2.guidance.components[name]?.use_for ?? []).length > 0).sort((a, b) => a.localeCompare(b)).map((name) => ({
-    name,
-    purpose: contract2.guidance.components[name].use_for.join("; "),
-    parts: partsOf(contract2, name)
-  }));
-}
-function componentDetail(contract2, wanted) {
-  const name = resolveComponent(contract2, wanted);
-  const component = contract2.components[name];
-  const guide = contract2.guidance.components[name] ?? {};
-  const props = Object.entries(component.props).map(([prop, definition]) => {
-    const notes = guide.values?.[prop];
-    return { name: prop, ...definition, ...notes === void 0 ? {} : { notes } };
-  });
-  const allowed = allowedChildren(contract2.composition_rules, name);
+function identityOf(contract2) {
   return {
-    name,
-    description: component.description,
-    use_for: guide.use_for ?? [],
-    not_for: guide.not_for ?? [],
-    ...guide.part_of === void 0 ? {} : { part_of: guide.part_of },
-    parts: partsOf(contract2, name),
-    props,
-    ...component.slots === void 0 ? {} : { slots: component.slots },
-    composable_with: component.composable_with ?? [],
-    never_inside: component.never_inside ?? [],
-    ...allowed === void 0 ? {} : { allowed_children: allowed },
-    example: component.example
+    cli_version: VERSION,
+    contract_version: contract2.version,
+    contract_digest: contractDigest(contract2),
+    schema_version: RESULT_SCHEMA_VERSION
   };
 }
-function propLine(prop, dense) {
-  const kind = prop.type === "enum" ? (prop.values ?? []).map((value) => value === prop.default ? `${value} (default)` : value).join(" | ") : (prop.type === "union" ? (prop.types ?? []).join(" or ") : prop.type) + (prop.default === void 0 ? "" : ` (default ${String(prop.default)})`);
-  const description = prop.description === void 0 ? "" : dense ? firstSentence(prop.description) : prop.description;
-  const lines = [
-    `  ${prop.name}: ${kind}${prop.required ? ", required" : ""}${description ? `. ${description}` : ""}`
-  ];
-  for (const [value, note] of Object.entries(prop.notes ?? {})) lines.push(`    ${value}: ${note}`);
-  return lines;
-}
-function renderComponent(detail, { dense }) {
-  const lines = [
-    detail.part_of === void 0 ? `${detail.name}: ${detail.use_for.join("; ")}` : `${detail.name}: a part of ${detail.part_of}. ${firstSentence(detail.description)}`
-  ];
-  if (detail.not_for.length > 0)
-    lines.push(
-      `Not for: ${detail.not_for.map(({ need, use }) => `${need} (use ${use})`).join("; ")}`
-    );
-  if (!dense) lines.push("", detail.description, "");
-  if (detail.props.length > 0) {
-    lines.push("Props:");
-    for (const prop of detail.props) lines.push(...propLine(prop, dense));
-  }
-  for (const [slot, { type, required }] of Object.entries(detail.slots ?? {}))
-    lines.push(
-      `${slot === "children" ? "Children" : `Slot ${slot}`}: ${type}${required ? ", required" : ""}`
-    );
-  if (detail.parts.length > 0) lines.push(`Parts: ${detail.parts.join(", ")}`);
-  if (detail.allowed_children !== void 0)
-    lines.push(`Takes directly inside: ${detail.allowed_children.join(", ")}`);
-  if (detail.composable_with.length > 0)
-    lines.push(`Goes inside: ${detail.composable_with.join(", ")}`);
-  if (detail.never_inside.length > 0) lines.push(`Never inside: ${detail.never_inside.join(", ")}`);
-  lines.push(
-    detail.example.includes("\n") ? `Example:
-${detail.example.split("\n").map((line) => `  ${line}`).join("\n")}` : `Example: ${detail.example}`
-  );
-  return `${lines.join("\n")}
-`;
-}
-var STOP = new Set(
-  "a an the to of for in on at with and or i we need want that which is are it its my some from by".split(
-    " "
-  )
-);
-var words = (text2) => (text2.toLowerCase().match(/[a-z0-9]+/g) ?? []).filter((word) => !STOP.has(word)).map((word) => word.length > 4 ? word.replace(/(?:ing|ed|es|s)$/, "") : word);
-var matched = (query, text2) => {
-  const present = new Set(words(text2));
-  return query.filter((word) => present.has(word)).length;
-};
-function search(contract2, registry2, query, limit = 10) {
-  const wanted = words(query);
-  if (wanted.length === 0) return [];
-  const whole = squash(query);
-  const scores = /* @__PURE__ */ new Map();
-  const add = (name, points, why) => {
-    const before = scores.get(name) ?? { score: 0 };
-    scores.set(name, {
-      score: before.score + points,
-      ...before.why !== void 0 ? { why: before.why } : why !== void 0 ? { why } : {}
-    });
-  };
-  for (const [name, component] of Object.entries(contract2.components)) {
-    const guide = contract2.guidance.components[name] ?? {};
-    const plain = squash(name);
-    if (plain === whole) add(name, 100);
-    else if (wanted.some((word) => word.length >= 3 && plain.includes(word))) add(name, 15);
-    else if (wanted.some((word) => word.length >= 4 && distance(word, plain) <= 1)) add(name, 12);
-    for (const phrase of guide.use_for ?? []) {
-      const hits = matched(wanted, phrase);
-      if (hits > 0) add(name, 12 * hits + (hits === wanted.length ? 40 : 0));
-    }
-    for (const { need, use } of guide.not_for ?? []) {
-      const hits = matched(wanted, need);
-      if (hits > 0 && hits >= Math.ceil(wanted.length * 0.6))
-        add(use, 10 * hits + (hits === wanted.length ? 15 : 0), `${name} is not for this: ${need}`);
-    }
-    const inDescription = matched(wanted, component.description);
-    if (inDescription > 0) add(name, 2 * inDescription);
-  }
-  const results = [];
-  for (const [name, { score, why }] of scores) {
-    const guide = contract2.guidance.components[name] ?? {};
-    results.push({
-      kind: "component",
-      name,
-      purpose: guide.part_of === void 0 ? (guide.use_for ?? []).join("; ") : `a part of ${guide.part_of}`,
-      score,
-      ...why === void 0 ? {} : { why },
-      next: `oprt component ${name}`
-    });
-  }
-  for (const entry of registry2.entries.filter(({ kind }) => kind === "recipe")) {
-    const recipe = contract2.patterns?.[entry.name];
-    const plain = squash(entry.name);
-    const inName = plain === whole ? 100 : wanted.some((word) => word.length >= 3 && plain.includes(word)) ? 15 : 0;
-    const hits = matched(wanted, entry.description);
-    const score = inName + (hits > 0 ? 10 * hits + (hits === wanted.length ? 15 : 0) : 0);
-    if (score > 0)
-      results.push({
-        kind: "recipe",
-        name: entry.name,
-        purpose: firstSentence(entry.description),
-        score,
-        next: recipe?.install ?? `oprt add ${entry.slug}`
-      });
+
+// src/check.ts
+var import_node_fs3 = require("fs");
+var import_node_path4 = require("path");
+
+// src/parser.ts
+var import_node_module = require("module");
+var import_node_path3 = require("path");
+var import_node_url2 = require("url");
+var SUPPORTED_TYPESCRIPT = "TypeScript 5 or 6";
+var INSTALL_TYPESCRIPT = "npm install -D typescript@6";
+function usable(typescript) {
+  const ts = typescript;
+  if (typeof ts.createSourceFile !== "function" || ts.ScriptKind === void 0)
+    return `TypeScript ${ts.version ?? "(unknown version)"} has no JavaScript syntax API (createSourceFile), which oprt reads code with; ${SUPPORTED_TYPESCRIPT} has it`;
+  try {
+    const probe = ts.createSourceFile(
+      "probe.tsx",
+      "<a>",
+      ts.ScriptTarget?.Latest ?? 99,
+      true,
+      ts.ScriptKind.TSX
+    );
+    const diagnostics = probe.parseDiagnostics;
+    if (!Array.isArray(diagnostics)) return "it does not report parse errors on a source file";
+    if (diagnostics.length === 0) return "it did not report a syntax error in code that has one";
+  } catch (error) {
+    return `it failed on a probe parse: ${error instanceof Error ? error.message : String(error)}`;
   }
-  results.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
-  const floor = Math.max(4, (results[0]?.score ?? 0) * 0.15);
-  return results.filter(({ score }) => score >= floor).slice(0, limit);
+  return null;
+}
+var packageFolder = (file) => /^(.*[\\/]node_modules[\\/]typescript)[\\/]/.exec(file)?.[1] ?? file;
+function probeTypeScript(cwd, options = {}) {
+  const places = [
+    { from: (0, import_node_path3.join)(cwd, "package.json"), source: "project" },
+    ...options.installer === false ? [] : [{ from: (0, import_node_url2.fileURLToPath)(importMetaUrl), source: "installer" }]
+  ];
+  let unusable;
+  for (const { from, source } of places) {
+    let file;
+    let loaded2;
+    try {
+      const require2 = (0, import_node_module.createRequire)(from);
+      file = require2.resolve("typescript");
+      loaded2 = require2("typescript");
+    } catch (error) {
+      if (error.code !== "MODULE_NOT_FOUND")
+        unusable ??= `typescript was found but failed to load: ${error instanceof Error ? error.message : String(error)}`;
+      continue;
+    }
+    const typescript = loaded2.default ?? loaded2;
+    const problem = usable(typescript);
+    if (problem !== null) {
+      unusable ??= `${problem} (at ${packageFolder(file)}).`;
+      continue;
+    }
+    return {
+      ready: true,
+      typescript,
+      resolution: {
+        name: "typescript",
+        version: typescript.version,
+        source,
+        resolved_from: packageFolder(file)
+      }
+    };
+  }
+  if (unusable !== void 0)
+    return { ready: false, reason: "typescript_unusable", detail: unusable };
+  return {
+    ready: false,
+    reason: "typescript_missing",
+    detail: `typescript could not be resolved from ${cwd}${options.installer === false ? "" : " or from beside the installer"}.`
+  };
 }
 
 // src/check.ts
+var FINDING_CODES = [
+  "INVALID_PROP_VALUE",
+  "UNKNOWN_EXPORT",
+  "DOT_NOTATION",
+  "INVALID_NESTING",
+  "INVALID_CHILD",
+  "MISSING_REQUIRED_PROP",
+  "UNKNOWN_PROP",
+  "RAW_COLOR",
+  "ARBITRARY_SIZE",
+  "ROUNDED_CORNER",
+  "NATIVE_CONTROL",
+  /** The file does not parse. It was not checked against the contract. */
+  "SYNTAX_ERROR"
+];
+var LIMITATION_CODES = ["UNRESOLVED_SPREAD", "UNRESOLVED_VALUE"];
+var SCOPE = {
+  checked: ["syntax", "contract", "house_rules"],
+  not_checked: ["types", "render"]
+};
 var PACKAGE = "@oprt/react";
 var NATIVE = {
   button: "Button",
@@ -648,11 +779,49 @@ function allowedChildren2(rules, name) {
   }
   return void 0;
 }
+var quote = (text2) => {
+  const flat = text2.replace(/\s+/g, " ").trim();
+  return flat.length > 48 ? `${flat.slice(0, 45)}...` : flat;
+};
+var MAX_SYNTAX_ERRORS = 10;
 function checkSource(typescript, contract2, file, text2) {
   const ts = typescript;
   const kind = /\.tsx$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.JSX;
   const source = ts.createSourceFile(file, text2, ts.ScriptTarget.Latest, true, kind);
+  const parseDiagnostics = source.parseDiagnostics;
+  if (!Array.isArray(parseDiagnostics))
+    throw new CliError(
+      `This TypeScript does not report syntax errors on a parsed file, so a file that does not parse could be called clean. Install TypeScript 5 or 6 in this project (${INSTALL_TYPESCRIPT}).`,
+      1,
+      { code: "ERR_TYPESCRIPT_UNUSABLE" }
+    );
+  if (parseDiagnostics.length > 0) {
+    const ordered = [...parseDiagnostics].sort((a, b) => (a.start ?? 0) - (b.start ?? 0));
+    const shown = ordered.slice(0, MAX_SYNTAX_ERRORS);
+    return {
+      file,
+      status: "not_evaluated",
+      limitations: [],
+      findings: shown.map((diagnostic, index) => {
+        const { line, character } = source.getLineAndCharacterOfPosition(diagnostic.start ?? 0);
+        const more = ordered.length - shown.length;
+        return {
+          code: "SYNTAX_ERROR",
+          severity: "error",
+          file,
+          line: line + 1,
+          column: character + 1,
+          message: `${ts.flattenDiagnosticMessageText(diagnostic.messageText, " ")} (TS${diagnostic.code})` + (index === shown.length - 1 && more > 0 ? ` ${more} more syntax error${more === 1 ? "" : "s"} in this file not shown.` : "")
+        };
+      })
+    };
+  }
   const findings = [];
+  const limitations = [];
+  const limit = (node, limitation) => {
+    const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
+    limitations.push({ ...limitation, file, line: line + 1, column: character + 1 });
+  };
   const report = (node, finding) => {
     const { line, character } = source.getLineAndCharacterOfPosition(node.getStart(source));
     findings.push({
@@ -677,7 +846,7 @@ function checkSource(typescript, contract2, file, text2) {
     const from = statement.moduleSpecifier.text;
     const clause = statement.importClause;
     if (!clause || clause.isTypeOnly || !clause.namedBindings) continue;
-    const copied = from !== PACKAGE && /[./@]/.test(from[0] ?? "") && isComponent((0, import_node_path3.basename)(from));
+    const copied = from !== PACKAGE && /[./@]/.test(from[0] ?? "") && isComponent((0, import_node_path4.basename)(from));
     if (from !== PACKAGE && !copied) continue;
     if (ts.isNamespaceImport(clause.namedBindings)) {
       if (from === PACKAGE) namespaces.add(clause.namedBindings.name.text);
@@ -723,6 +892,31 @@ function checkSource(typescript, contract2, file, text2) {
     return [];
   };
   const valueOf = (attribute) => attribute.initializer === void 0 ? void 0 : ts.isJsxExpression(attribute.initializer) ? attribute.initializer.expression : attribute.initializer;
+  const optionValue = (expression) => {
+    const read = [];
+    const unread = [];
+    const walk = (node) => {
+      if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
+        read.push(node.text);
+      else if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node) || ts.isTypeAssertionExpression(node) || typeof ts.isSatisfiesExpression === "function" && ts.isSatisfiesExpression(node))
+        walk(node.expression);
+      else if (ts.isConditionalExpression(node)) {
+        walk(node.whenTrue);
+        walk(node.whenFalse);
+      } else if (ts.isBinaryExpression(node)) {
+        const operator = node.operatorToken.kind;
+        if (operator === ts.SyntaxKind.QuestionQuestionToken || operator === ts.SyntaxKind.BarBarToken) {
+          walk(node.left);
+          walk(node.right);
+        } else if (operator === ts.SyntaxKind.AmpersandAmpersandToken) walk(node.right);
+        else unread.push(node);
+      } else if (!// No value: the component's default applies.
+      (ts.isIdentifier(node) && node.text === "undefined" || node.kind === ts.SyntaxKind.NullKeyword))
+        unread.push(node);
+    };
+    if (expression) walk(expression);
+    return { literals: read, unread };
+  };
   const classText = (expression) => {
     if (!expression) return "";
     if (ts.isTemplateExpression(expression))
@@ -795,6 +989,13 @@ function checkSource(typescript, contract2, file, text2) {
     if (component === null) return null;
     const definition = contract2.components[component];
     const spread = attributes.some((attribute) => ts.isJsxSpreadAttribute(attribute));
+    for (const attribute of attributes)
+      if (ts.isJsxSpreadAttribute(attribute))
+        limit(attribute, {
+          code: "UNRESOLVED_SPREAD",
+          component,
+          message: `Props spread into <${component}> (${quote(attribute.getText(source))}) were not read: option values and required props that arrive through them were not checked.`
+        });
     const given = /* @__PURE__ */ new Set();
     for (const attribute of attributes) {
       if (!ts.isJsxAttribute(attribute)) continue;
@@ -803,18 +1004,26 @@ function checkSource(typescript, contract2, file, text2) {
       const known = Object.hasOwn(definition.props, prop) ? definition.props[prop] : void 0;
       if (known === void 0) {
         if (nativeAttribute(prop) || Object.hasOwn(definition.slots ?? {}, prop)) continue;
-        const names = Object.keys(definition.props);
+        const names2 = Object.keys(definition.props);
         report(attribute, {
           code: "UNKNOWN_PROP",
           severity: "warning",
           component,
           prop,
-          message: `${component} has no prop ${prop}.` + (names.length === 0 ? " It takes no props of its own." : ` Its props: ${names.slice(0, 14).join(", ")}${names.length > 14 ? ", \u2026" : ""}.`)
+          message: `${component} has no prop ${prop}.` + (names2.length === 0 ? " It takes no props of its own." : ` Its props: ${names2.slice(0, 14).join(", ")}${names2.length > 14 ? ", \u2026" : ""}.`)
         });
         continue;
       }
       if (known.type !== "enum" || known.values === void 0) continue;
-      for (const literal of literals(valueOf(attribute))) {
+      const { literals: options, unread } = optionValue(valueOf(attribute));
+      for (const expression of unread)
+        limit(attribute, {
+          code: "UNRESOLVED_VALUE",
+          component,
+          prop,
+          message: `${component} ${prop} is set from an expression (${quote(expression.getText(source))}) whose value is not in the source, so it was not compared with the options.`
+        });
+      for (const literal of options) {
         if (known.values.includes(literal)) continue;
         const elsewhere = Object.entries(contract2.components).filter(([, other]) => other.props[prop]?.values?.includes(literal)).map(([name]) => name);
         report(attribute, {
@@ -884,64 +1093,153 @@ function checkSource(typescript, contract2, file, text2) {
     ts.forEachChild(node, (child) => visit(child, ancestors, parent));
   };
   visit(source, [], null);
-  return findings.sort((a, b) => a.line - b.line || a.column - b.column);
+  const byPlace = (a, b) => a.line - b.line || a.column - b.column;
+  return {
+    file,
+    status: limitations.length > 0 ? "partial" : "evaluated",
+    findings: findings.sort(byPlace),
+    limitations: limitations.sort(byPlace)
+  };
 }
 var SKIPPED = /* @__PURE__ */ new Set(["node_modules", "dist", "build", "out", "coverage"]);
 var READ = /* @__PURE__ */ new Set([".tsx", ".jsx"]);
 var NOT_INTERFACE = /\.(?:test|spec|stories)\.[jt]sx$/;
+var excluded = (name) => SKIPPED.has(name) || name.startsWith(".");
 function* sources(path) {
-  const name = (0, import_node_path3.basename)(path);
-  if (SKIPPED.has(name) || name.startsWith(".") && name !== "." && name !== "..") return;
+  if (excluded((0, import_node_path4.basename)(path))) return;
   if ((0, import_node_fs3.statSync)(path).isDirectory()) {
-    for (const entry of (0, import_node_fs3.readdirSync)(path).sort()) yield* sources((0, import_node_path3.join)(path, entry));
-  } else if (READ.has((0, import_node_path3.extname)(path)) && !NOT_INTERFACE.test(name)) yield path;
+    for (const entry of (0, import_node_fs3.readdirSync)(path).sort()) yield* sources((0, import_node_path4.join)(path, entry));
+  } else if (READ.has((0, import_node_path4.extname)(path)) && !NOT_INTERFACE.test((0, import_node_path4.basename)(path))) yield path;
 }
-function findTypeScript(cwd) {
-  for (const from of [(0, import_node_path3.join)(cwd, "package.json"), (0, import_node_url2.fileURLToPath)(importMetaUrl)]) {
-    try {
-      return (0, import_node_module.createRequire)(from)("typescript");
-    } catch {
-    }
+function whyNotRead(path) {
+  const name = (0, import_node_path4.basename)(path);
+  if (excluded(name)) return "excluded_folder";
+  if ((0, import_node_fs3.statSync)(path).isDirectory()) return null;
+  if (!READ.has((0, import_node_path4.extname)(path))) return "unsupported_extension";
+  return NOT_INTERFACE.test(name) ? "test_or_story_file" : null;
+}
+function buildCheckReport(evaluations, context) {
+  const findings = evaluations.flatMap(({ findings: found }) => found);
+  const count = (status2) => evaluations.filter((evaluation) => evaluation.status === status2).length;
+  const partial = count("partial");
+  const notEvaluated = count("not_evaluated");
+  const evaluated = evaluations.length - notEvaluated;
+  const errors = findings.filter(({ severity }) => severity === "error").length;
+  const warnings = findings.length - errors;
+  let status;
+  if (evaluations.length === 0) status = "no_files_evaluated";
+  else if (evaluated === 0) status = "not_evaluated";
+  else if (partial > 0 || notEvaluated > 0) status = "partially_evaluated";
+  else status = findings.length > 0 ? "evaluated_with_findings" : "evaluated_clean";
+  return {
+    evaluation_status: status,
+    files: evaluations.length,
+    findings,
+    summary: { errors, warnings },
+    coverage: {
+      files_found: evaluations.length,
+      files_evaluated: evaluated,
+      files_partial: partial,
+      files_not_evaluated: notEvaluated
+    },
+    limitations: evaluations.flatMap(({ limitations }) => limitations),
+    skipped_inputs: context.skipped ?? [],
+    scope: { checked: [...SCOPE.checked], not_checked: [...SCOPE.not_checked] },
+    parser: context.parser
+  };
+}
+function checkExitCode(report, { strict }) {
+  if (report.evaluation_status === "no_files_evaluated") return 1;
+  if (report.summary.errors > 0 || report.coverage.files_not_evaluated > 0) return 1;
+  return strict && report.summary.warnings > 0 ? 1 : 0;
+}
+var describeProvided = (typescript) => ({
+  name: "typescript",
+  version: typescript.version ?? "unknown",
+  source: "provided"
+});
+function resolveParser(cwd, provided, who) {
+  if (provided !== void 0 && provided !== null)
+    return { typescript: provided, parser: describeProvided(provided) };
+  const probe = provided === null ? null : probeTypeScript(cwd);
+  if (probe?.ready) {
+    const { name, version, source } = probe.resolution;
+    return { typescript: probe.typescript, parser: { name, version, source } };
   }
-  return null;
+  if (probe !== null && probe.reason === "typescript_unusable")
+    throw new CliError(`${who} cannot use the TypeScript it found: ${probe.detail}`, 1, {
+      code: "ERR_TYPESCRIPT_UNUSABLE"
+    });
+  throw new CliError(
+    `${who} reads code with the project's TypeScript, and found none. Install typescript in this project (${INSTALL_TYPESCRIPT}) and run it again. It looked from ${cwd}.`,
+    1,
+    { code: "ERR_TYPESCRIPT_MISSING" }
+  );
 }
 function checkPaths(paths, context) {
-  const root = (0, import_node_path3.resolve)(context.cwd);
+  const root = (0, import_node_path4.resolve)(context.cwd);
   const files = [];
+  const skipped = [];
   for (const path of paths) {
-    const absolute = (0, import_node_path3.resolve)(root, path);
+    const absolute = (0, import_node_path4.resolve)(root, path);
     if (!(0, import_node_fs3.existsSync)(absolute))
       throw new CliError(`No such file or folder: ${path}`, 2, { code: "ERR_PATH_NOT_FOUND" });
+    const reason = whyNotRead(absolute);
+    if (reason !== null) skipped.push({ path, reason });
     files.push(...sources(absolute));
   }
-  const ts = context.typescript === void 0 ? findTypeScript(root) : context.typescript;
-  if (ts === null)
-    throw new CliError(
-      "oprt check reads code with the project's TypeScript, and found none. Install typescript in this project (npm install -D typescript) and run it again.",
-      1,
-      { code: "ERR_TYPESCRIPT_MISSING" }
-    );
-  const findings = [...new Set(files)].flatMap(
+  const { typescript, parser } = resolveParser(root, context.typescript, "oprt check");
+  const evaluations = [...new Set(files)].map(
     (file) => checkSource(
-      ts,
+      typescript,
       context.contract,
-      (0, import_node_path3.relative)(root, file).split(import_node_path3.sep).join("/"),
+      (0, import_node_path4.relative)(root, file).split(import_node_path4.sep).join("/"),
       (0, import_node_fs3.readFileSync)(file, "utf8")
     )
   );
-  return {
-    files: new Set(files).size,
-    findings,
-    summary: {
-      errors: findings.filter(({ severity }) => severity === "error").length,
-      warnings: findings.filter(({ severity }) => severity === "warning").length
-    }
-  };
+  return buildCheckReport(evaluations, { parser, skipped });
+}
+var plural = (amount, word) => `${amount} ${word}${amount === 1 ? "" : "s"}`;
+var MAX_LIMITS_SHOWN = 20;
+function renderCheckText(report) {
+  const lines = report.findings.map(
+    ({ file, line, column, severity, code, message }) => `${file}:${line}:${column}  ${severity}  ${code}  ${message}`
+  );
+  const shown = report.limitations.slice(0, MAX_LIMITS_SHOWN);
+  for (const { file, line, column, code, message } of shown)
+    lines.push(`${file}:${line}:${column}  limit  ${code}  ${message}`);
+  if (report.limitations.length > shown.length)
+    lines.push(
+      `  ...and ${plural(report.limitations.length - shown.length, "more limit")}; the JSON lists them all.`
+    );
+  const { coverage, evaluation_status: status } = report;
+  if (status === "no_files_evaluated") {
+    lines.push("No .tsx or .jsx file was read, so nothing was checked.");
+    const labels = {
+      unsupported_extension: "not a .tsx or .jsx file",
+      test_or_story_file: "a test, spec or story file, which is skipped",
+      excluded_folder: "a folder that is skipped (node_modules, dist, build, out, coverage, hidden)"
+    };
+    for (const { path, reason } of report.skipped_inputs)
+      lines.push(`  ${path}: ${labels[reason]}`);
+  } else if (coverage.files_not_evaluated > 0)
+    lines.push(
+      `${plural(coverage.files_not_evaluated, "file")} did not parse and ${coverage.files_not_evaluated === 1 ? "was" : "were"} not checked against the contract.`
+    );
+  else if (status === "evaluated_clean")
+    lines.push(
+      "Nothing found. Checked syntax, option values, nesting, required props and the house rules; types and rendering are not checked."
+    );
+  lines.push(
+    `${plural(report.summary.errors, "error")}, ${plural(report.summary.warnings, "warning")} in ${plural(report.files, "file")}. Status: ${status}.`
+  );
+  return `${lines.join("\n")}
+`;
 }
 
 // src/doctor.ts
 var import_node_fs4 = require("fs");
-var import_node_path4 = require("path");
+var import_node_path5 = require("path");
 
 // src/agent-block.ts
 var START = "<!-- OPERATOR:START -->";
@@ -1025,14 +1323,18 @@ var INSTRUCTION_FILES = [
 ];
 var minor = (version) => version.split(".").slice(0, 2).join(".");
 function installedVersion(cwd, name) {
-  for (let folder = cwd; ; folder = (0, import_node_path4.dirname)(folder)) {
-    const manifest = (0, import_node_path4.join)(folder, "node_modules", name, "package.json");
+  for (let folder = cwd; ; folder = (0, import_node_path5.dirname)(folder)) {
+    const manifest = (0, import_node_path5.join)(folder, "node_modules", name, "package.json");
     if ((0, import_node_fs4.existsSync)(manifest))
       return JSON.parse((0, import_node_fs4.readFileSync)(manifest, "utf8")).version;
-    if ((0, import_node_path4.dirname)(folder) === folder) return void 0;
+    if ((0, import_node_path5.dirname)(folder) === folder) return void 0;
   }
 }
-function doctor({ cwd, contract: contract2 }) {
+function doctor({
+  cwd,
+  contract: contract2,
+  parser = probeTypeScript(cwd)
+}) {
   const checks = [];
   for (const name of PACKAGES) {
     const version = installedVersion(cwd, name);
@@ -1054,7 +1356,7 @@ function doctor({ cwd, contract: contract2 }) {
     else checks.push({ id, status: "ok", message: `${name} ${version} is installed.` });
   }
   const written = INSTRUCTION_FILES.map((path) => {
-    const file = (0, import_node_path4.join)(cwd, path);
+    const file = (0, import_node_path5.join)(cwd, path);
     return {
       path,
       version: (0, import_node_fs4.existsSync)(file) ? blockVersion((0, import_node_fs4.readFileSync)(file, "utf8")) : void 0
@@ -1081,13 +1383,60 @@ function doctor({ cwd, contract: contract2 }) {
       status: "ok",
       message: `${written.map(({ path }) => path).join(", ")} carries the OPERATOR block (${contract2.version}).`
     });
+  const install2 = `${INSTALL_TYPESCRIPT} (or your package manager's equivalent), then run oprt doctor again. Lookups work without it.`;
+  let checkCode;
+  if (parser.ready) {
+    const { version, resolved_from, source } = parser.resolution;
+    checkCode = {
+      status: "ready",
+      message: `TypeScript ${version}, resolved from ${resolved_from}${source === "project" ? "" : " (beside oprt, not this project)"}.`,
+      typescript: { version, resolved_from, source }
+    };
+    checks.push(
+      source === "project" ? {
+        id: "typescript",
+        status: "ok",
+        message: `TypeScript ${version} is installed in this project (${resolved_from}).`
+      } : {
+        id: "typescript",
+        status: "warn",
+        message: `TypeScript ${version} is not in this project; the one beside oprt is used (${resolved_from}).`,
+        fix: `${INSTALL_TYPESCRIPT}, so checking reads code with a version installed in the project.`
+      }
+    );
+  } else {
+    checkCode = {
+      status: "blocked",
+      message: `${parser.reason}: ${parser.detail}`,
+      reason: parser.reason,
+      fix: install2
+    };
+    checks.push({
+      id: "typescript",
+      status: "fail",
+      message: `oprt check and the check_code tool cannot run (${parser.reason}): ${parser.detail}`,
+      fix: install2
+    });
+  }
   const count = (status) => checks.filter((check) => check.status === status).length;
-  return { checks, summary: { ok: count("ok"), warn: count("warn"), fail: count("fail") } };
+  return {
+    consumer_directory: cwd,
+    operations: {
+      lookup: {
+        status: "ready",
+        message: `search, component and list read the contract bundled with oprt (${contract2.version}): always available.`,
+        contract_version: contract2.version
+      },
+      check_code: checkCode
+    },
+    checks,
+    summary: { ok: count("ok"), warn: count("warn"), fail: count("fail") }
+  };
 }
 
 // src/init.ts
 var import_node_fs5 = require("fs");
-var import_node_path5 = require("path");
+var import_node_path6 = require("path");
 var AGENT_FILES = {
   claude: ["CLAUDE.md"],
   cursor: [".cursor/rules/operator.mdc"],
@@ -1115,7 +1464,7 @@ function init(options, context) {
   const dryRun = options.dryRun ?? false;
   const files = targets(options).map((path) => {
     validateRelative(path);
-    const destination = (0, import_node_path5.resolve)(root, path);
+    const destination = (0, import_node_path6.resolve)(root, path);
     inspectPath(root, destination);
     const existing = (0, import_node_fs5.existsSync)(destination) ? (0, import_node_fs5.readFileSync)(destination, "utf8") : null;
     if (options.remove) {
@@ -1132,7 +1481,7 @@ function init(options, context) {
     const fresh = existing === null && path.endsWith(".mdc") ? CURSOR_FRONT_MATTER : existing;
     const { text: text2, action } = applyBlock(fresh, block);
     if (action !== "unchanged" && !dryRun) {
-      (0, import_node_fs5.mkdirSync)((0, import_node_path5.dirname)(destination), { recursive: true });
+      (0, import_node_fs5.mkdirSync)((0, import_node_path6.dirname)(destination), { recursive: true });
       (0, import_node_fs5.writeFileSync)(destination, text2);
     }
     return { path, action: existing === null ? "create" : action };
@@ -1140,8 +1489,536 @@ function init(options, context) {
   return { version: context.contract.version, dryRun, files };
 }
 
+// src/results.ts
+var RESULT_TYPES = [
+  "check",
+  "search",
+  "component.detail",
+  "component.batch",
+  "component.list",
+  "init",
+  "doctor",
+  "add",
+  "list",
+  "instructions"
+];
+var envelope = (type, data, contract2) => ({
+  apiVersion: 1,
+  type,
+  identity: identityOf(contract2),
+  data
+});
+function errorEnvelope(error, contract2) {
+  const known = error instanceof CliError ? error : void 0;
+  const identity = contract2 === void 0 ? { cli_version: VERSION, schema_version: RESULT_SCHEMA_VERSION } : (({ cli_version, schema_version, contract_version, contract_digest }) => ({
+    cli_version,
+    schema_version,
+    contract_version,
+    contract_digest
+  }))(identityOf(contract2));
+  return {
+    apiVersion: 1,
+    error: error instanceof Error ? error.message : String(error),
+    code: known?.code ?? "ERR_FAILED",
+    ...known?.suggestions === void 0 ? {} : { suggestions: known.suggestions },
+    identity
+  };
+}
+function componentData(detail, dense) {
+  if (!dense) return { ...detail, dense };
+  const { description: _description, ...rest } = detail;
+  return {
+    ...rest,
+    props: detail.props.map(
+      (prop) => prop.description === void 0 ? prop : { ...prop, description: firstSentence(prop.description) }
+    ),
+    dense
+  };
+}
+function instructionsData(contract2) {
+  return {
+    rules: contract2.guidance.rules.map(({ id, rule, wrong, right }) => ({
+      id,
+      rule,
+      ...wrong === void 0 ? {} : { wrong },
+      ...right === void 0 ? {} : { right }
+    })),
+    components: componentIndex(contract2),
+    recipes: Object.entries(contract2.patterns ?? {}).map(([name, { description, install: install2 }]) => ({
+      name,
+      description,
+      install: install2
+    }))
+  };
+}
+var str = (extra = {}) => ({ type: "string", ...extra });
+var int = () => ({ type: "integer", minimum: 0 });
+var bool = () => ({ type: "boolean" });
+var arr = (items) => ({ type: "array", items });
+var names = () => arr(str());
+var words2 = (...values) => ({ type: "string", enum: [...values] });
+var ref = (name) => ({ $ref: `#/$defs/${name}` });
+var obj = (properties, optional = [], open = false) => ({
+  type: "object",
+  properties,
+  required: Object.keys(properties).filter((key) => !optional.includes(key)),
+  additionalProperties: open
+});
+var scalar = { type: ["string", "number", "boolean"] };
+var DEFS = {
+  identity: obj({
+    cli_version: str(),
+    contract_version: str(),
+    contract_digest: str({ pattern: "^sha256:[0-9a-f]{64}$" }),
+    schema_version: { type: "integer", minimum: 1 }
+  }),
+  error_identity: obj(
+    {
+      cli_version: str(),
+      schema_version: { type: "integer", minimum: 1 },
+      contract_version: str(),
+      contract_digest: str({ pattern: "^sha256:[0-9a-f]{64}$" })
+    },
+    ["contract_version", "contract_digest"]
+  ),
+  finding: obj(
+    {
+      code: words2(...FINDING_CODES),
+      severity: words2("error", "warning"),
+      file: str(),
+      line: { type: "integer", minimum: 1 },
+      column: { type: "integer", minimum: 1 },
+      component: str(),
+      prop: str(),
+      message: str(),
+      valid_values: names(),
+      suggestions: names()
+    },
+    ["component", "prop", "valid_values", "suggestions"]
+  ),
+  limitation: obj(
+    {
+      code: words2(...LIMITATION_CODES),
+      file: str(),
+      line: { type: "integer", minimum: 1 },
+      column: { type: "integer", minimum: 1 },
+      component: str(),
+      prop: str(),
+      message: str()
+    },
+    ["prop"]
+  ),
+  skipped_input: obj({
+    path: str(),
+    reason: words2("unsupported_extension", "test_or_story_file", "excluded_folder")
+  }),
+  parser: obj({
+    name: words2("typescript"),
+    version: str(),
+    source: words2("project", "installer", "provided")
+  }),
+  check_data: obj({
+    evaluation_status: words2(
+      "evaluated_clean",
+      "evaluated_with_findings",
+      "partially_evaluated",
+      "not_evaluated",
+      "no_files_evaluated"
+    ),
+    files: int(),
+    findings: arr(ref("finding")),
+    summary: obj({ errors: int(), warnings: int() }),
+    coverage: obj({
+      files_found: int(),
+      files_evaluated: int(),
+      files_partial: int(),
+      files_not_evaluated: int()
+    }),
+    limitations: arr(ref("limitation")),
+    skipped_inputs: arr(ref("skipped_input")),
+    scope: obj({ checked: names(), not_checked: names() }),
+    parser: ref("parser")
+  }),
+  search_result: obj(
+    {
+      kind: words2("component", "recipe"),
+      name: str(),
+      purpose: str(),
+      score: { type: "number" },
+      why: str(),
+      next: str()
+    },
+    ["why"]
+  ),
+  search_data: obj({
+    query: str(),
+    limit: { type: "integer", minimum: 1 },
+    matchCount: int(),
+    results: arr(ref("search_result"))
+  }),
+  index_entry: obj({ name: str(), purpose: str(), parts: names() }),
+  component_list_data: obj({ components: arr(ref("index_entry")) }),
+  detail_prop: obj(
+    {
+      name: str(),
+      type: str(),
+      values: names(),
+      types: names(),
+      default: scalar,
+      required: bool(),
+      description: str(),
+      notes: { type: "object", additionalProperties: str() }
+    },
+    ["values", "types", "default", "required", "description", "notes"],
+    // The contract may describe a prop with more than these (an array's item type, for one).
+    true
+  ),
+  component_detail: obj(
+    {
+      name: str(),
+      description: str(),
+      use_for: names(),
+      not_for: arr(obj({ need: str(), use: str() })),
+      part_of: str(),
+      parts: names(),
+      props: arr(ref("detail_prop")),
+      slots: {
+        type: "object",
+        additionalProperties: obj({ type: str(), required: bool() }, ["required"])
+      },
+      composable_with: names(),
+      never_inside: names(),
+      allowed_children: names(),
+      example: str(),
+      dense: bool()
+    },
+    ["description", "part_of", "slots", "allowed_children"]
+  ),
+  component_batch_data: obj({ components: arr(ref("component_detail")) }),
+  doctor_check: obj(
+    { id: str(), status: words2("ok", "warn", "fail"), message: str(), fix: str() },
+    ["fix"]
+  ),
+  doctor_data: obj({
+    consumer_directory: str(),
+    operations: obj({
+      lookup: obj({ status: words2("ready"), message: str(), contract_version: str() }),
+      check_code: obj(
+        {
+          status: words2("ready", "blocked"),
+          message: str(),
+          reason: words2("typescript_missing", "typescript_unusable"),
+          fix: str(),
+          typescript: obj({
+            version: str(),
+            resolved_from: str(),
+            source: words2("project", "installer", "provided")
+          })
+        },
+        ["reason", "fix", "typescript"]
+      )
+    }),
+    checks: arr(ref("doctor_check")),
+    summary: obj({ ok: int(), warn: int(), fail: int() })
+  }),
+  init_data: obj({
+    version: str(),
+    dryRun: bool(),
+    files: arr(
+      obj({
+        path: str(),
+        action: words2("create", "append", "update", "unchanged", "remove", "delete", "absent")
+      })
+    )
+  }),
+  install_file: obj({
+    path: str(),
+    destination: str(),
+    action: words2("create", "overwrite", "skip")
+  }),
+  add_data: obj({
+    outputDirectory: str(),
+    entries: names(),
+    dependencies: names(),
+    devDependencies: names(),
+    ranges: { type: "object", additionalProperties: str() },
+    files: arr(ref("install_file")),
+    dryRun: bool(),
+    setup: ref("setup")
+  }),
+  setup: obj({
+    tailwind: str(),
+    packages: arr(obj({ name: str(), range: str(), dev: bool(), why: str() })),
+    stylesheet: arr(obj({ line: str(), why: str() })),
+    root_import: obj({ line: str(), note: str() }),
+    not_needed: arr(obj({ name: str(), why: str() }))
+  }),
+  list_data: obj({
+    version: str(),
+    entries: arr(
+      obj(
+        {
+          name: str(),
+          slug: str(),
+          kind: words2("component", "recipe"),
+          description: str(),
+          files: names(),
+          dependencies: names(),
+          devDependencies: names()
+        },
+        ["devDependencies"]
+      )
+    ),
+    ranges: { type: "object", additionalProperties: str() }
+  }),
+  instructions_data: obj({
+    rules: arr(obj({ id: str(), rule: str(), wrong: str(), right: str() }, ["wrong", "right"])),
+    components: arr(ref("index_entry")),
+    recipes: arr(obj({ name: str(), description: str(), install: str() }))
+  })
+};
+var DATA = {
+  check: "check_data",
+  search: "search_data",
+  "component.detail": "component_detail",
+  "component.batch": "component_batch_data",
+  "component.list": "component_list_data",
+  init: "init_data",
+  doctor: "doctor_data",
+  add: "add_data",
+  list: "list_data",
+  instructions: "instructions_data"
+};
+var success = (type) => obj({
+  apiVersion: { const: 1 },
+  type: { const: type },
+  identity: ref("identity"),
+  data: ref(DATA[type])
+});
+var failure = () => obj(
+  {
+    apiVersion: { const: 1 },
+    error: str(),
+    code: str({ pattern: "^ERR_[A-Z_]+$" }),
+    suggestions: names(),
+    identity: ref("error_identity")
+  },
+  ["suggestions"]
+);
+function bundle(root) {
+  const used = {};
+  const visit = (node) => {
+    if (Array.isArray(node)) node.forEach(visit);
+    else if (typeof node === "object" && node !== null) {
+      for (const [key, value] of Object.entries(node)) {
+        if (key === "$ref" && typeof value === "string") {
+          const name = value.replace("#/$defs/", "");
+          if (used[name] === void 0) {
+            used[name] = DEFS[name];
+            visit(DEFS[name]);
+          }
+        } else visit(value);
+      }
+    }
+  };
+  visit(root);
+  return { ...root, $defs: used };
+}
+function schemaFor(type) {
+  return bundle(type === "error" ? failure() : success(type));
+}
+var S = { type: "string" };
+var I = { type: "integer" };
+var B = { type: "boolean" };
+var list = (items) => items === void 0 ? { type: "array" } : { type: "array", items };
+var shape = (properties, required) => ({
+  type: "object",
+  properties,
+  ...required === void 0 ? {} : { required }
+});
+var strings = list(S);
+var SUMMARIES = {
+  check: shape(
+    {
+      evaluation_status: words2(
+        "evaluated_clean",
+        "evaluated_with_findings",
+        "partially_evaluated",
+        "not_evaluated",
+        "no_files_evaluated"
+      ),
+      findings: list(
+        shape({
+          code: S,
+          severity: words2("error", "warning"),
+          file: S,
+          line: I,
+          column: I,
+          message: S
+        })
+      ),
+      summary: shape({ errors: I, warnings: I }),
+      coverage: shape({ files_evaluated: I, files_partial: I, files_not_evaluated: I }),
+      limitations: list(shape({ code: S, file: S, line: I, column: I, message: S })),
+      skipped_inputs: list(),
+      scope: { type: "object" },
+      parser: { type: "object" }
+    },
+    ["evaluation_status", "findings", "summary", "coverage", "limitations"]
+  ),
+  search: shape(
+    {
+      matchCount: I,
+      results: list(
+        shape({ kind: words2("component", "recipe"), name: S, purpose: S, why: S, next: S })
+      )
+    },
+    ["results"]
+  ),
+  "component.detail": shape(
+    {
+      name: S,
+      description: S,
+      use_for: strings,
+      not_for: list(),
+      part_of: S,
+      parts: strings,
+      props: list(
+        shape({ name: S, type: S, values: strings, required: B, notes: { type: "object" } })
+      ),
+      slots: { type: "object" },
+      composable_with: strings,
+      never_inside: strings,
+      allowed_children: strings,
+      example: S,
+      dense: B
+    },
+    ["name", "props", "example", "dense"]
+  ),
+  "component.list": shape({ components: list() }, ["components"]),
+  "component.batch": shape({ components: list() }, ["components"]),
+  instructions: shape(
+    {
+      rules: list(),
+      components: list(),
+      recipes: list()
+    },
+    ["rules", "components", "recipes"]
+  ),
+  init: shape({ files: list() }),
+  doctor: shape({ operations: { type: "object" }, checks: list() }),
+  add: shape({ files: list(), setup: { type: "object" } }),
+  list: shape({ entries: list() })
+};
+function shareRepeats(schema) {
+  const count = /* @__PURE__ */ new Map();
+  const tally = (node) => {
+    if (Array.isArray(node)) node.forEach(tally);
+    else if (typeof node === "object" && node !== null) {
+      const text2 = JSON.stringify(node);
+      if (text2.length >= 30) count.set(text2, (count.get(text2) ?? 0) + 1);
+      Object.values(node).forEach(tally);
+    }
+  };
+  tally(schema);
+  const repeated = [...count].filter(([, times]) => times >= 3).map(([text2]) => text2);
+  if (repeated.length === 0) return schema;
+  const names2 = new Map(
+    repeated.map((text2, index) => [text2, index === 0 ? "strings" : `part${index}`])
+  );
+  const defs = {};
+  const rewrite = (node) => {
+    if (Array.isArray(node)) return node.map(rewrite);
+    if (typeof node !== "object" || node === null) return node;
+    const name = names2.get(JSON.stringify(node));
+    if (name !== void 0) {
+      defs[name] = node;
+      return { $ref: `#/$defs/${name}` };
+    }
+    return Object.fromEntries(Object.entries(node).map(([key, value]) => [key, rewrite(value)]));
+  };
+  const rewritten = rewrite(schema);
+  return { ...rewritten, $defs: defs };
+}
+function outputSchemaFor(type) {
+  return shareRepeats({
+    type: "object",
+    properties: {
+      type: { const: type },
+      // The four versions and the digest; the docs name them, and so does every answer.
+      identity: { type: "object" },
+      data: SUMMARIES[type]
+    },
+    required: ["identity"],
+    anyOf: [{ required: ["data"] }, { required: ["error"] }]
+  });
+}
+var RESULT_SCHEMAS = Object.freeze(
+  Object.fromEntries(
+    [...RESULT_TYPES, "error"].map((type) => [type, schemaFor(type)])
+  )
+);
+
+// src/setup.ts
+function setupFor(dependencies, contract2) {
+  const { setup } = contract2.guidance;
+  const scansPackage = dependencies.includes(setup.package_source.when);
+  return {
+    tailwind: setup.tailwind,
+    packages: setup.packages.map(({ name, range, dev, why }) => ({
+      name,
+      range: range ?? "latest",
+      dev,
+      why
+    })),
+    stylesheet: [
+      ...setup.stylesheet,
+      ...scansPackage ? [{ line: setup.package_source.line, why: setup.package_source.why }] : []
+    ],
+    root_import: { line: setup.root_import, note: setup.root_import_note },
+    not_needed: setup.not_needed
+  };
+}
+function renderSetup(setup, copiedPackageImports) {
+  const named = ({ name, range }) => range === "latest" ? name : `${name}@${range}`;
+  const runtime = setup.packages.filter(({ dev: dev2 }) => !dev2).map(named);
+  const dev = setup.packages.filter(({ dev: isDev }) => isDev).map(named);
+  return [
+    `Setup, once per project: ${setup.tailwind}`,
+    `  Install: ${runtime.join(", ")}; as dev dependencies: ${dev.join(", ")}.`,
+    "  In the stylesheet that imports tailwindcss, after the import:",
+    ...setup.stylesheet.map(({ line }) => `    ${line}`),
+    ...copiedPackageImports ? ["      (the @source path is relative to the stylesheet)"] : [
+      "      (source copied into the project is scanned by Tailwind 4 without an @source line)"
+    ],
+    `  At the application root, from JavaScript, before the stylesheet: ${setup.root_import.line}`,
+    ...setup.not_needed.map(({ name, why }) => `  Not needed: ${name}. ${why}`)
+  ];
+}
+
 // src/agent-commands.ts
-var envelope = (type, data) => ({ apiVersion: 1, type, data });
+function renderInstall(result, setup) {
+  const lines = [
+    `${result.dryRun ? "Dry run" : "Installed"}: ${result.entries.join(", ")}`,
+    `Output: ${result.outputDirectory}`,
+    ...result.files.map((file) => `  ${file.action.padEnd(9)} ${file.path}`)
+  ];
+  const versioned = (name) => result.ranges[name] === void 0 ? name : `${name}@${result.ranges[name]}`;
+  const runtime = result.dependencies.filter((name) => !result.devDependencies.includes(name));
+  lines.push("", `Dependencies: ${runtime.map(versioned).join(", ")}`);
+  if (result.devDependencies.length > 0)
+    lines.push(
+      `Dev dependencies (types only): ${result.devDependencies.map(versioned).join(", ")}`
+    );
+  lines.push(
+    "",
+    ...renderSetup(setup, setup.stylesheet.length > 1),
+    "",
+    "Install what is missing yourself. No package configuration or stylesheet was changed."
+  );
+  return `${lines.join("\n")}
+`;
+}
 function runAgentCommand(command, context) {
   const { contract: contract2, registry: registry2, cwd } = context;
   switch (command.command) {
@@ -1153,14 +2030,15 @@ function runAgentCommand(command, context) {
             ({ name, purpose, parts }) => `${name}${parts.length > 0 ? ` (${parts.join(", ")})` : ""}: ${purpose}
 `
           ).join(""),
-          json: envelope("component.list", { components }),
+          json: envelope("component.list", { components }, contract2),
           exitCode: 0
         };
       }
       const details = command.names.map((name) => componentDetail(contract2, name));
+      const data = details.map((detail) => componentData(detail, command.dense));
       return {
         text: details.map((detail) => renderComponent(detail, { dense: command.dense })).join("\n"),
-        json: details.length === 1 ? envelope("component.detail", details[0]) : envelope("component.batch", { components: details }),
+        json: data.length === 1 ? envelope("component.detail", data[0], contract2) : envelope("component.batch", { components: data }, contract2),
         exitCode: 0
       };
     }
@@ -1173,7 +2051,11 @@ function runAgentCommand(command, context) {
   ${next}
 `
         ).join(""),
-        json: envelope("search", { query: command.query, matchCount: results.length, results }),
+        json: envelope(
+          "search",
+          { query: command.query, limit: command.limit, matchCount: results.length, results },
+          contract2
+        ),
         exitCode: 0
       };
     }
@@ -1184,146 +2066,328 @@ function runAgentCommand(command, context) {
         ...result.files.map(({ path, action }) => `  ${action.padEnd(9)} ${path}`),
         command.remove ? "The block was taken out; the rest of each file is as it was." : "Run oprt init again after an upgrade to refresh the block."
       ];
-      return { text: `${lines.join("\n")}
-`, json: envelope("init", result), exitCode: 0 };
+      return {
+        text: `${lines.join("\n")}
+`,
+        json: envelope("init", result, contract2),
+        exitCode: 0
+      };
     }
     case "check": {
       const report = checkPaths(command.paths, { cwd, contract: contract2 });
-      const { errors, warnings } = report.summary;
-      const lines = report.findings.map(
-        ({ file, line, column, severity, code, message }) => `${file}:${line}:${column}  ${severity}  ${code}  ${message}`
-      );
-      const count = (amount, word) => `${amount} ${word}${amount === 1 ? "" : "s"}`;
-      lines.push(
-        `${count(errors, "error")}, ${count(warnings, "warning")} in ${count(report.files, "file")}.`
-      );
       return {
-        text: `${lines.join("\n")}
-`,
-        json: envelope("check", report),
+        text: renderCheckText(report),
+        json: envelope("check", report, contract2),
         // Warnings fail the run only when asked to: they are house rules, or may be native attributes.
-        exitCode: errors > 0 || command.strict && warnings > 0 ? 1 : 0
+        exitCode: checkExitCode(report, { strict: command.strict })
       };
     }
     case "doctor": {
-      const report = doctor({ cwd, contract: contract2 });
-      const lines = report.checks.flatMap(({ status, message, fix }) => [
-        `[${status}] ${message}`,
-        ...fix === void 0 ? [] : [`       fix: ${fix}`]
-      ]);
+      const report = doctor({
+        cwd,
+        contract: contract2,
+        ...context.parser ? { parser: context.parser } : {}
+      });
+      const { lookup, check_code: checking } = report.operations;
+      const lines = [
+        "Readiness",
+        `  lookups        ${lookup.status.padEnd(8)} ${lookup.message}`,
+        `  code checking  ${checking.status.padEnd(8)} ${checking.message}`,
+        ...checking.fix === void 0 ? [] : [`                          fix: ${checking.fix}`],
+        "",
+        "Setup"
+      ];
+      lines.push(
+        ...report.checks.flatMap(({ status, message, fix }) => [
+          `[${status}] ${message}`,
+          ...fix === void 0 ? [] : [`       fix: ${fix}`]
+        ])
+      );
       lines.push(
         `${report.summary.ok} ok, ${report.summary.warn} to look at, ${report.summary.fail} failed.`
       );
       return {
         text: `${lines.join("\n")}
 `,
-        json: envelope("doctor", report),
+        json: envelope("doctor", report, contract2),
         exitCode: report.summary.fail > 0 ? 1 : 0
       };
     }
+    case "list": {
+      const lines = [`OPERATOR ${VERSION}`, ""];
+      for (const kind of ["component", "recipe"]) {
+        const entries = registry2.entries.filter((entry) => entry.kind === kind);
+        lines.push(`${kind === "component" ? "Components" : "Recipes"} (${entries.length})`);
+        for (const entry of entries) lines.push(`  ${entry.slug.padEnd(22)} ${entry.description}`);
+        lines.push("");
+      }
+      return {
+        text: `${lines.join("\n")}
+`,
+        json: envelope(
+          "list",
+          { version: VERSION, entries: registry2.entries, ranges: registry2.ranges ?? {} },
+          contract2
+        ),
+        exitCode: 0
+      };
+    }
+    case "add": {
+      const result = installSources(command, { cwd, registry: registry2 });
+      const setup = setupFor(result.dependencies, contract2);
+      return {
+        text: renderInstall(result, setup),
+        json: envelope("add", { ...result, setup }, contract2),
+        exitCode: 0
+      };
+    }
   }
 }
 
 // src/mcp.ts
 var import_node_readline = require("readline");
+
+// src/validate.ts
+var KNOWN = /* @__PURE__ */ new Set([
+  "type",
+  "description",
+  "default",
+  "enum",
+  "minimum",
+  "maximum",
+  "minLength",
+  "maxLength"
+]);
+var typeName = (value) => value === null ? "null" : Array.isArray(value) ? "an array" : typeof value === "object" ? "an object" : typeof value === "number" ? "a number" : typeof value === "string" ? "a string" : typeof value === "boolean" ? "a boolean" : typeof value;
+function describeValue(value) {
+  if (typeof value === "string")
+    return `${JSON.stringify(value.length > 40 ? `${value.slice(0, 37)}...` : value)} (a string)`;
+  if (typeof value === "number") return Number.isNaN(value) ? "NaN" : String(value);
+  if (value === null || typeof value === "boolean" || value === void 0) return String(value);
+  return `${typeName(value)} (${JSON.stringify(value)?.slice(0, 40) ?? ""})`;
+}
+function expectation(schema) {
+  switch (schema.type) {
+    case "boolean":
+      return "true or false";
+    case "integer":
+    case "number": {
+      const noun = schema.type === "integer" ? "a whole number" : "a number";
+      if (schema.minimum !== void 0 && schema.maximum !== void 0)
+        return `${noun} from ${schema.minimum} to ${schema.maximum}`;
+      if (schema.minimum !== void 0) return `${noun} of at least ${schema.minimum}`;
+      if (schema.maximum !== void 0) return `${noun} of at most ${schema.maximum}`;
+      return noun;
+    }
+    case "string": {
+      if (schema.enum !== void 0) return `one of ${schema.enum.map(String).join(", ")}`;
+      const { minLength, maxLength } = schema;
+      if (minLength !== void 0 && maxLength !== void 0)
+        return `a string of ${minLength} to ${maxLength.toLocaleString("en-US")} characters`;
+      if (maxLength !== void 0)
+        return `a string of at most ${maxLength.toLocaleString("en-US")} characters`;
+      return "a string";
+    }
+  }
+}
+function accepts(schema, value) {
+  switch (schema.type) {
+    case "boolean":
+      return typeof value === "boolean";
+    case "string":
+      return typeof value === "string" && (schema.minLength === void 0 || value.length >= schema.minLength) && (schema.maxLength === void 0 || value.length <= schema.maxLength) && (schema.enum === void 0 || schema.enum.includes(value));
+    case "integer":
+    case "number":
+      return typeof value === "number" && Number.isFinite(value) && (schema.type === "number" || Number.isInteger(value)) && (schema.minimum === void 0 || value >= schema.minimum) && (schema.maximum === void 0 || value <= schema.maximum);
+  }
+}
+function validateArguments(tool, schema, args) {
+  for (const [field, property] of Object.entries(schema.properties))
+    for (const key of Object.keys(property))
+      if (!KNOWN.has(key))
+        throw new Error(`${tool}.${field}: the schema uses "${key}", which is not enforced.`);
+  if (typeof args !== "object" || args === null || Array.isArray(args))
+    return `${tool}: arguments must be an object.`;
+  const given = args;
+  const required = schema.required ?? [];
+  const blank = (value) => typeof value === "string" && value.trim() === "";
+  const missing = [];
+  const wrong = [];
+  const unknown = [];
+  for (const field of required)
+    if (given[field] === void 0 || blank(given[field])) missing.push(field);
+  for (const [field, value] of Object.entries(given)) {
+    const property = Object.hasOwn(schema.properties, field) ? schema.properties[field] : void 0;
+    if (property === void 0) unknown.push(field);
+    else if (value !== void 0 && !(required.includes(field) && blank(value))) {
+      if (!accepts(property, value))
+        wrong.push(`${field} must be ${expectation(property)}, but got ${describeValue(value)}`);
+    }
+  }
+  const reject = schema.additionalProperties === false ? unknown : [];
+  const names2 = Object.keys(schema.properties);
+  if (missing.length === 1 && wrong.length === 0 && reject.length === 0)
+    return `${tool} needs ${missing[0]}, ${expectation({ type: schema.properties[missing[0]].type })}.`;
+  const fragments = [
+    ...missing.map(
+      (field) => `${field} is required (${expectation({ type: schema.properties[field].type })})`
+    ),
+    ...wrong,
+    ...reject.map(
+      (field) => `unknown argument ${JSON.stringify(field)}. It takes${names2.length > 0 ? `: ${names2.join(", ")}` : " none"}`
+    )
+  ];
+  return fragments.length === 0 ? null : `${tool}: ${fragments.join("; ")}.`;
+}
+
+// src/mcp.ts
 var VERSIONS = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
 var text = (value) => ({ type: "text", text: value });
-var string = (description) => ({ type: "string", description });
+var LIMITS = { query: 500, name: 100, code: 2e5 };
+var ANSWERS = {
+  search: "search",
+  get_component: "component.detail",
+  list_components: "component.list",
+  get_instructions: "instructions",
+  check_code: "check"
+};
+var readOnly = { readOnlyHint: true };
+var define = (tool) => ({
+  ...tool,
+  outputSchema: outputSchemaFor(ANSWERS[tool.name]),
+  annotations: readOnly
+});
 var TOOLS = [
-  {
+  define({
     name: "search",
-    description: "Find the OPERATOR component or recipe that answers a need, such as 'show a status' or 'table with selection'. Call this before writing interface code.",
+    description: "Find the OPERATOR component or recipe for a need, such as 'show a status' or 'table with selection'. Call before writing interface code.",
     inputSchema: {
       type: "object",
       properties: {
-        query: string("The need, in plain words."),
-        limit: { type: "number", description: "How many results to return. Default 10." }
+        query: {
+          type: "string",
+          minLength: 1,
+          maxLength: LIMITS.query,
+          description: "The need, in plain words."
+        },
+        limit: {
+          type: "integer",
+          minimum: 1,
+          maximum: SEARCH_LIMIT_MAX,
+          default: SEARCH_LIMIT_DEFAULT,
+          description: `Results to return, 1 to ${SEARCH_LIMIT_MAX}.`
+        }
       },
-      required: ["query"]
+      required: ["query"],
+      additionalProperties: false
     }
-  },
-  {
+  }),
+  define({
     name: "get_component",
-    description: "One OPERATOR component: what it is for, what to use instead, every prop and option value, its nesting rules and an example. Call this before using a component.",
+    description: "One component's contract: what it is for, what to use instead, every prop and option value, nesting rules, an example. Call before using a component.",
     inputSchema: {
       type: "object",
       properties: {
-        name: string("The component's name, such as Button or DataGrid."),
+        name: {
+          type: "string",
+          minLength: 1,
+          maxLength: LIMITS.name,
+          description: "Component name, such as Button."
+        },
         dense: {
           type: "boolean",
-          description: "The short form, which is the default. Pass false for full descriptions."
+          default: true,
+          description: "Compact form (every constraint, one sentence per prop). False: full prose."
         }
       },
-      required: ["name"]
+      required: ["name"],
+      additionalProperties: false
     }
-  },
-  {
+  }),
+  define({
     name: "list_components",
     description: "Every OPERATOR component in one line each, with its parts.",
-    inputSchema: { type: "object", properties: {} }
-  },
-  {
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  }),
+  define({
     name: "get_instructions",
-    description: "OPERATOR's house rules, its component index and its recipes: what to read once before building with it.",
-    inputSchema: { type: "object", properties: {} }
-  },
-  {
+    description: "OPERATOR's house rules, component index and recipes: read once before building.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false }
+  }),
+  define({
     name: "check_code",
-    description: "Check TSX code against OPERATOR's contract: option values, nesting, required props and the house rules. Call this on what you wrote before you finish.",
+    description: "Check TSX against OPERATOR's contract: option values, nesting, required props, house rules. Call before you finish. Read evaluation_status: only evaluated_clean means every file was read in full with nothing found. Types and rendering are not checked.",
     inputSchema: {
       type: "object",
-      properties: { code: string("The TSX source of one file.") },
-      required: ["code"]
+      properties: {
+        code: {
+          type: "string",
+          minLength: 1,
+          maxLength: LIMITS.code,
+          description: "The TSX source of one file."
+        }
+      },
+      required: ["code"],
+      additionalProperties: false
     }
-  }
+  })
 ];
 function runTool(name, args, context) {
   const { contract: contract2, registry: registry2 } = context;
-  const required = (key) => {
-    const value = args[key];
-    if (typeof value !== "string" || value.trim() === "")
-      throw new Error(`${name} needs ${key}, a string.`);
-    return value;
-  };
+  const definition = TOOLS.find((tool) => tool.name === name);
+  if (definition === void 0) throw new UnknownTool(name);
+  const problem = validateArguments(name, definition.inputSchema, args);
+  if (problem !== null) throw new CliError(problem, 2, { code: "ERR_INVALID_ARGUMENT" });
   switch (name) {
     case "search": {
-      const query = required("query");
-      const results = search(
-        contract2,
-        registry2,
-        query,
-        typeof args.limit === "number" ? args.limit : 10
-      );
-      return results.length === 0 ? `Nothing matches ${JSON.stringify(query)}. Call list_components to see what there is.` : results.map(
-        ({ kind, name: found, purpose, why, next }) => `${found} (${kind}): ${purpose}${why === void 0 ? "" : ` [${why}]`}
+      const query = args["query"];
+      const limit = args["limit"] ?? SEARCH_LIMIT_DEFAULT;
+      const results = search(contract2, registry2, query, limit);
+      return {
+        text: results.length === 0 ? `Nothing matches ${JSON.stringify(query)}. Call list_components to see what there is.` : results.map(
+          ({ kind, name: found, purpose, why, next }) => `${found} (${kind}): ${purpose}${why === void 0 ? "" : ` [${why}]`}
   ${next}`
-      ).join("\n");
+        ).join("\n"),
+        structured: envelope(
+          "search",
+          { query, limit, matchCount: results.length, results },
+          contract2
+        )
+      };
+    }
+    case "get_component": {
+      const dense = args["dense"] ?? true;
+      const detail = componentDetail(contract2, args["name"]);
+      return {
+        text: renderComponent(detail, { dense }),
+        structured: envelope("component.detail", componentData(detail, dense), contract2)
+      };
+    }
+    case "list_components": {
+      const components = componentIndex(contract2);
+      return {
+        text: components.map(
+          ({ name: component, purpose, parts }) => `${component}${parts.length > 0 ? ` (${parts.join(", ")})` : ""}: ${purpose}`
+        ).join("\n"),
+        structured: envelope("component.list", { components }, contract2)
+      };
     }
-    case "get_component":
-      return renderComponent(componentDetail(contract2, required("name")), {
-        dense: args.dense !== false
-      });
-    case "list_components":
-      return componentIndex(contract2).map(
-        ({ name: component, purpose, parts }) => `${component}${parts.length > 0 ? ` (${parts.join(", ")})` : ""}: ${purpose}`
-      ).join("\n");
     case "get_instructions":
-      return renderAgentBlock(contract2).split("\n").filter((line) => line !== START && line !== END && !line.startsWith("<!-- Written by")).join("\n");
+      return {
+        text: renderAgentBlock(contract2).split("\n").filter((line) => line !== START && line !== END && !line.startsWith("<!-- Written by")).join("\n"),
+        structured: envelope("instructions", instructionsData(contract2), contract2)
+      };
     case "check_code": {
-      const code = required("code");
-      const ts = context.typescript === void 0 ? findTypeScript(context.cwd ?? process.cwd()) : context.typescript;
-      if (ts === null)
-        throw new Error("check_code reads code with TypeScript, and found none installed.");
-      const findings = checkSource(ts, contract2, "snippet.tsx", code);
-      if (findings.length === 0) return "No findings.";
-      const errors = findings.filter(({ severity }) => severity === "error").length;
-      const count = (amount, word) => `${amount} ${word}${amount === 1 ? "" : "s"}`;
-      return [
-        ...findings.map(
-          ({ line, column, severity, code: finding, message }) => `${line}:${column}  ${severity}  ${finding}  ${message}`
-        ),
-        `${count(errors, "error")}, ${count(findings.length - errors, "warning")}.`
-      ].join("\n");
+      const { typescript, parser } = resolveParser(
+        context.cwd ?? process.cwd(),
+        context.typescript,
+        "check_code"
+      );
+      const report = buildCheckReport(
+        [checkSource(typescript, contract2, "snippet.tsx", args["code"])],
+        { parser }
+      );
+      return { text: renderCheckText(report), structured: envelope("check", report, contract2) };
     }
     default:
       throw new UnknownTool(name);
@@ -1337,24 +2401,28 @@ var UnknownTool = class extends Error {
   }
 };
 function handleMessage(raw, context) {
-  const failure = (id2, code, message) => ({
+  const failure2 = (id2, code, message) => ({
     jsonrpc: "2.0",
     id: id2 ?? null,
     error: { code, message }
   });
-  if (typeof raw !== "object" || raw === null) return failure(null, -32700, "Parse error");
+  if (typeof raw !== "object" || raw === null) return failure2(null, -32700, "Parse error");
   const { id, method, params } = raw;
-  if (typeof method !== "string") return failure(id, -32600, "Invalid request");
+  if (typeof method !== "string") return failure2(id, -32600, "Invalid request");
   if (id === void 0) return null;
   const result = (value) => ({ jsonrpc: "2.0", id, result: value });
   switch (method) {
     case "initialize": {
       const asked = params?.protocolVersion;
+      const identity = identityOf(context.contract);
       return result({
         protocolVersion: asked !== void 0 && VERSIONS.includes(asked) ? asked : VERSIONS[0],
         capabilities: { tools: {} },
-        serverInfo: { name: "oprt", version: context.contract.version },
-        instructions: "OPERATOR design system. Call get_instructions once, search for the component that answers a need, get_component before using one, and check_code before you finish."
+        // The program's version, not the contract's: the contract has its own, in `_meta` and in
+        // the identity of every result.
+        serverInfo: { name: "oprt", version: VERSION },
+        instructions: "OPERATOR design system. Call get_instructions once, search for the component that answers a need, get_component before using one, and check_code before you finish. check_code says how much it could read: only evaluated_clean means the code was read in full with nothing found.",
+        _meta: { "dev.oprt/identity": identity }
       });
     }
     case "ping":
@@ -1364,17 +2432,23 @@ function handleMessage(raw, context) {
     case "tools/call": {
       const { name, arguments: args } = params ?? {};
       try {
-        return result({ content: [text(runTool(String(name), args ?? {}, context))] });
+        const output = runTool(String(name), args ?? {}, context);
+        return result({
+          content: [text(output.text)],
+          structuredContent: output.structured
+        });
       } catch (error) {
-        if (error instanceof UnknownTool) return failure(id, -32602, error.message);
+        if (error instanceof UnknownTool) return failure2(id, -32602, error.message);
+        const failed = errorEnvelope(error, context.contract);
         return result({
-          content: [text(error instanceof Error ? error.message : String(error))],
+          content: [text(failed.error)],
+          structuredContent: failed,
           isError: true
         });
       }
     }
     default:
-      return failure(id, -32601, `Method not found: ${method}`);
+      return failure2(id, -32601, `Method not found: ${method}`);
   }
 }
 function serve(input, output, context) {
@@ -1395,10 +2469,9 @@ function serve(input, output, context) {
 }
 
 // src/index.ts
-var VERSION = package_default.version;
 function loadRegistry() {
-  const here = (0, import_node_path6.dirname)((0, import_node_url3.fileURLToPath)(importMetaUrl));
-  const candidates = [(0, import_node_path6.join)(here, "registry.json"), (0, import_node_path6.join)(here, "../generated/registry.json")];
+  const here = (0, import_node_path7.dirname)((0, import_node_url3.fileURLToPath)(importMetaUrl));
+  const candidates = [(0, import_node_path7.join)(here, "registry.json"), (0, import_node_path7.join)(here, "../generated/registry.json")];
   const found = candidates.find((candidate) => (0, import_node_fs6.existsSync)(candidate));
   if (found === void 0) {
     throw new Error(
@@ -1420,26 +2493,38 @@ function install(options, context = {}) {
 0 && (module.exports = {
   CliError,
   DEFAULT_OUT,
+  RESULT_SCHEMAS,
+  RESULT_SCHEMA_VERSION,
+  RESULT_TYPES,
   TOOLS,
   VERSION,
   applyBlock,
   blockVersion,
+  buildCheckReport,
+  checkExitCode,
   checkPaths,
   checkSource,
   componentDetail,
   componentIndex,
   contract,
+  contractDigest,
   doctor,
+  envelope,
+  errorEnvelope,
   handleMessage,
+  identityOf,
   init,
   install,
+  outputSchemaFor,
   parseArgs,
   registry,
   removeBlock,
   renderAgentBlock,
+  renderCheckText,
   renderComponent,
   resolveEntries,
   runAgentCommand,
+  schemaFor,
   search,
   serve
 });