design-rover 0.2.0 → 0.3.0

package/dist/bin.js

@@ -27,7 +27,7 @@ var init_constants = __esm({
     MODEL_VERSION = 1;
     PRODUCT_NAME = "Design Rover";
     CLI_PACKAGE = "design-rover";
-    CLI_VERSION = "0.2.0";
+    CLI_VERSION = "0.3.0";
     SPEC_DIR = ".design-rover";
     MANAGED_START = "<!-- design-rover:start -->";
     MANAGED_END = "<!-- design-rover:end -->";
@@ -99,7 +99,7 @@ var init_ids = __esm({
 
 // ../model/src/schema.ts
 import { z } from "zod";
-var KnowledgeStatusSchema, ConfidenceSchema, SourceKindSchema, TokenCategorySchema, EntityKindSchema, DiagnosticSeveritySchema, SyncStateSchema, SourceLocationSchema, EvidenceSchema, KnowledgeMetaSchema, TokenRecordSchema, ComponentPropSchema, ComponentUsageSchema, ComponentRecordSchema, PatternOccurrenceSchema, PatternRecordSchema, ConventionRecordSchema, IntentRecordSchema, ExceptionRecordSchema, RejectionRecordSchema, BaselineFindingSchema, BaselineRecordSchema, ExternalSourceSchema, SourceDiscrepancySchema, GeneratedFileSchema, HistoryEventSchema, FrameworkInfoSchema, StylingInfoSchema, EnforcementInfoSchema, SystemRecordSchema, CanonicalModelSchema, ObservedSnapshotSchema, ChangeKindSchema, ModelChangeSchema, SystemDiffSchema, DiagnosticSchema, CheckReportSchema, StatusReportSchema;
+var KnowledgeStatusSchema, ConfidenceSchema, SourceKindSchema, TokenCategorySchema, EntityKindSchema, DiagnosticSeveritySchema, SyncStateSchema, SourceLocationSchema, EvidenceSchema, KnowledgeMetaSchema, TokenRecordSchema, ComponentPropSchema, ComponentUsageSchema, ComponentPropsResolutionSchema, ComponentRecordSchema, PatternOccurrenceSchema, PatternRecordSchema, ConventionRecordSchema, IntentRecordSchema, ExceptionRecordSchema, RejectionRecordSchema, BaselineFindingSchema, BaselineRecordSchema, ExternalSourceSchema, SourceDiscrepancySchema, GeneratedFileSchema, HistoryEventSchema, FrameworkInfoSchema, StylingInfoSchema, EnforcementInfoSchema, SystemRecordSchema, CanonicalModelSchema, ObservedSnapshotSchema, ChangeKindSchema, ModelChangeSchema, SystemDiffSchema, DiagnosticSchema, CheckReportSchema, StatusReportSchema;
 var init_schema = __esm({
   "../model/src/schema.ts"() {
     "use strict";
@@ -160,6 +160,10 @@ var init_schema = __esm({
       file: z.string(),
       count: z.number().int()
     });
+    ComponentPropsResolutionSchema = z.object({
+      status: z.enum(["resolved", "partial", "unresolved", "untyped"]),
+      issues: z.array(z.string()).default([])
+    });
     ComponentRecordSchema = KnowledgeMetaSchema.extend({
       id: z.string(),
       name: z.string(),
@@ -167,6 +171,7 @@ var init_schema = __esm({
       importPath: z.string(),
       exportName: z.string(),
       props: z.array(ComponentPropSchema).default([]),
+      propsResolution: ComponentPropsResolutionSchema.optional(),
       variants: z.array(z.string()).default([]),
       sizes: z.array(z.string()).default([]),
       composition: z.array(z.string()).default([]),
@@ -502,10 +507,189 @@ var init_hash = __esm({
   }
 });
 
-// ../core/src/component-resolution.ts
+// ../core/src/local-modules.ts
 import path2 from "path";
+import ts from "typescript";
+function scriptKind(file) {
+  if (file.endsWith(".tsx")) return ts.ScriptKind.TSX;
+  if (file.endsWith(".jsx")) return ts.ScriptKind.JSX;
+  return /\.(?:js|mjs|cjs)$/.test(file) ? ts.ScriptKind.JS : ts.ScriptKind.TS;
+}
+function localModules(evidence) {
+  let graph = graphs.get(evidence);
+  if (!graph) {
+    graph = new LocalModules(evidence);
+    graphs.set(evidence, graph);
+  }
+  return graph;
+}
+var graphs, extensions, normalize, LocalModules;
+var init_local_modules = __esm({
+  "../core/src/local-modules.ts"() {
+    "use strict";
+    init_esm_shims();
+    graphs = /* @__PURE__ */ new WeakMap();
+    extensions = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx"];
+    normalize = (file) => path2.posix.normalize(file.replaceAll("\\", "/"));
+    LocalModules = class {
+      constructor(evidence) {
+        this.evidence = evidence;
+        for (const file of evidence.files) if (file.kind === "script") this.files.set(normalize(file.relative), file.content);
+        const config = evidence.files.find((file) => file.relative === "tsconfig.json");
+        const options = config ? ts.parseConfigFileTextToJson("tsconfig.json", config.content).config?.compilerOptions : void 0;
+        this.baseUrl = typeof options?.baseUrl === "string" ? normalize(options.baseUrl) : ".";
+      }
+      evidence;
+      files = /* @__PURE__ */ new Map();
+      modules = /* @__PURE__ */ new Map();
+      resolutions = /* @__PURE__ */ new Map();
+      baseUrl;
+      source(file) {
+        return this.module(file)?.source;
+      }
+      resolveModule(from, specifier) {
+        const candidates = [];
+        if (specifier.startsWith(".")) candidates.push(path2.posix.join(path2.posix.dirname(from), specifier));
+        else {
+          const aliases = Object.entries(this.evidence.tsconfigPaths).sort(([a], [b]) => Number(a.includes("*")) - Number(b.includes("*")) || b.indexOf("*") - a.indexOf("*") || a.localeCompare(b));
+          for (const [alias, values] of aliases) {
+            const star = alias.indexOf("*");
+            if (star < 0) {
+              if (alias === specifier) {
+                candidates.push(...values.map((value) => path2.posix.join(this.baseUrl, value)));
+                break;
+              }
+            } else {
+              const prefix = alias.slice(0, star);
+              const suffix = alias.slice(star + 1);
+              if (specifier.startsWith(prefix) && specifier.endsWith(suffix)) {
+                const rest = specifier.slice(prefix.length, suffix ? -suffix.length : void 0);
+                candidates.push(...values.map((value) => path2.posix.join(this.baseUrl, value.replace("*", rest))));
+                break;
+              }
+            }
+          }
+          if (this.baseUrl !== ".") candidates.push(path2.posix.join(this.baseUrl, specifier));
+        }
+        for (const candidate of candidates) {
+          const normalized = normalize(candidate);
+          if (normalized === ".." || normalized.startsWith("../") || path2.posix.isAbsolute(normalized)) continue;
+          const direct = [];
+          if (/\.jsx?$/.test(normalized)) direct.push(normalized.replace(/\.jsx?$/, ".ts"), normalized.replace(/\.jsx?$/, ".tsx"));
+          if (normalized.endsWith(".mjs")) direct.push(normalized.replace(/\.mjs$/, ".mts"));
+          if (normalized.endsWith(".cjs")) direct.push(normalized.replace(/\.cjs$/, ".cts"));
+          direct.push(normalized);
+          direct.push(...extensions.map((extension) => `${normalized}${extension}`), ...extensions.map((extension) => `${normalized}/index${extension}`));
+          const found = direct.find((file) => this.files.has(file));
+          if (found) return found;
+        }
+        return void 0;
+      }
+      resolveExport(from, specifier, name, kind) {
+        const module = this.resolveModule(from, specifier);
+        if (!module) return { targets: [], issues: [`Cannot resolve local ${kind} import ${JSON.stringify(specifier)} from ${from}. External package declarations are not loaded.`] };
+        const key = JSON.stringify([module, name, kind]);
+        const cached = this.resolutions.get(key);
+        if (cached) return cached;
+        const result = this.exported(module, name, kind, /* @__PURE__ */ new Set());
+        const distinct = [...new Map(result.targets.map((target) => [JSON.stringify(target), target])).values()];
+        const issues = [...new Set(result.issues)];
+        if (distinct.length > 1) issues.push(`Ambiguous ${kind} export ${name} in ${module}; multiple declarations match.`);
+        const resolution = { module, targets: distinct, issues };
+        this.resolutions.set(key, resolution);
+        return resolution;
+      }
+      module(file) {
+        file = normalize(file);
+        const cached = this.modules.get(file);
+        if (cached) return cached;
+        const content = this.files.get(file);
+        if (content === void 0) return void 0;
+        const source = ts.createSourceFile(path2.resolve(this.evidence.root || ".", file), content, ts.ScriptTarget.Latest, true, scriptKind(file));
+        const module = { source, locals: /* @__PURE__ */ new Map(), imports: /* @__PURE__ */ new Map(), exports: /* @__PURE__ */ new Map(), stars: [] };
+        this.modules.set(file, module);
+        const addExport = (name, binding) => module.exports.set(name, [...module.exports.get(name) ?? [], binding]);
+        const addLocal = (name, declaration) => module.locals.set(name, [...module.locals.get(name) ?? [], declaration]);
+        for (const statement of source.statements) {
+          if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier)) {
+            const clause = statement.importClause;
+            const specifier = statement.moduleSpecifier.text;
+            if (clause?.name) module.imports.set(clause.name.text, { source: specifier, imported: "default", typeOnly: clause.isTypeOnly });
+            const bindings = clause?.namedBindings;
+            if (bindings && ts.isNamedImports(bindings)) for (const binding of bindings.elements) {
+              module.imports.set(binding.name.text, { source: specifier, imported: binding.propertyName?.text ?? binding.name.text, typeOnly: Boolean(clause?.isTypeOnly || binding.isTypeOnly) });
+            }
+            if (bindings && ts.isNamespaceImport(bindings)) module.imports.set(bindings.name.text, { source: specifier, imported: "*", typeOnly: Boolean(clause?.isTypeOnly) });
+            continue;
+          }
+          if (ts.isExportDeclaration(statement)) {
+            const specifier = statement.moduleSpecifier && ts.isStringLiteral(statement.moduleSpecifier) ? statement.moduleSpecifier.text : void 0;
+            if (statement.exportClause && ts.isNamedExports(statement.exportClause)) {
+              for (const binding of statement.exportClause.elements) addExport(binding.name.text, { source: specifier, imported: binding.propertyName?.text ?? binding.name.text, typeOnly: statement.isTypeOnly || binding.isTypeOnly });
+            } else if (!statement.exportClause && specifier) module.stars.push({ source: specifier, typeOnly: statement.isTypeOnly });
+            continue;
+          }
+          if (ts.isExportAssignment(statement) && !statement.isExportEquals && ts.isIdentifier(statement.expression)) {
+            addExport("default", { imported: statement.expression.text, typeOnly: false });
+            continue;
+          }
+          const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : void 0;
+          const exported = modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.ExportKeyword);
+          const isDefault = modifiers?.some((modifier) => modifier.kind === ts.SyntaxKind.DefaultKeyword);
+          if (ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations) if (ts.isIdentifier(declaration.name)) {
+              addLocal(declaration.name.text, { type: false, value: true });
+              if (exported) addExport(declaration.name.text, { imported: declaration.name.text, typeOnly: false });
+            }
+          } else if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement) || ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isEnumDeclaration(statement)) && statement.name) {
+            const name = statement.name.text;
+            const type = !ts.isFunctionDeclaration(statement);
+            const value = !ts.isInterfaceDeclaration(statement) && !ts.isTypeAliasDeclaration(statement);
+            addLocal(name, { type, value });
+            if (exported) addExport(isDefault ? "default" : name, { imported: name, typeOnly: !value });
+          }
+        }
+        return module;
+      }
+      local(file, name, kind, seen) {
+        const module = this.module(file);
+        if (!module) return { targets: [], issues: [] };
+        if (module.locals.get(name)?.some((declaration) => declaration[kind])) return { targets: [{ file, name }], issues: [] };
+        const binding = module.imports.get(name);
+        if (binding?.source && !(kind === "value" && binding.typeOnly)) return this.binding(file, binding, kind, seen);
+        return { targets: [], issues: [] };
+      }
+      binding(file, binding, kind, seen) {
+        if (kind === "value" && binding.typeOnly) return { targets: [], issues: [] };
+        if (!binding.source) return this.local(file, binding.imported, kind, seen);
+        const target = this.resolveModule(file, binding.source);
+        if (!target) return { targets: [], issues: [`Cannot resolve local ${kind} re-export ${JSON.stringify(binding.source)} from ${file}.`] };
+        if (binding.imported === "*") return { targets: [], issues: [`Namespace re-export in ${file} requires an explicit exported member.`] };
+        return this.exported(target, binding.imported, kind, seen);
+      }
+      exported(file, name, kind, seen) {
+        const key = JSON.stringify([file, name, kind]);
+        if (seen.has(key)) return { targets: [], issues: [] };
+        const next = new Set(seen).add(key);
+        const module = this.module(file);
+        if (!module) return { targets: [], issues: [] };
+        const explicit = module.exports.get(name)?.filter((binding) => !(kind === "value" && binding.typeOnly));
+        if (explicit?.length) {
+          const results2 = explicit.map((binding) => this.binding(file, binding, kind, next));
+          return { targets: results2.flatMap((result) => result.targets), issues: results2.flatMap((result) => result.issues) };
+        }
+        if (name === "default") return { targets: [], issues: [] };
+        const results = module.stars.filter((star) => !(kind === "value" && star.typeOnly)).map((star) => this.binding(file, { source: star.source, imported: name, typeOnly: star.typeOnly }, kind, next));
+        return { targets: results.flatMap((result) => result.targets), issues: results.flatMap((result) => result.issues) };
+      }
+    };
+  }
+});
+
+// ../core/src/component-resolution.ts
+import path3 from "path";
 function targets(evidence, file, source) {
-  if (source.startsWith(".")) return [path2.posix.normalize(path2.posix.join(path2.posix.dirname(file), source))];
+  if (source.startsWith(".")) return [path3.posix.normalize(path3.posix.join(path3.posix.dirname(file), source))];
   const found = [];
   for (const [alias, values] of Object.entries(evidence.tsconfigPaths)) {
     const star = alias.indexOf("*");
@@ -520,7 +704,7 @@ function targets(evidence, file, source) {
       }
     }
   }
-  return found.map((value) => path2.posix.normalize(value.replace(/^\.\//, "")));
+  return found.map((value) => path3.posix.normalize(value.replace(/^\.\//, "")));
 }
 function resolveComponent(evidence, file, tag, components, options = {}) {
   if (tag.split(".").length > 2) return void 0;
@@ -528,6 +712,7 @@ function resolveComponent(evidence, file, tag, components, options = {}) {
   const imports = file.imports.filter((item) => !item.isTypeOnly);
   let bound = false;
   const matches = /* @__PURE__ */ new Set();
+  const graph = localModules(evidence);
   for (const item of imports) {
     const bindings = item.bindings ?? [
       ...item.names.map((name) => ({ local: name, imported: name })),
@@ -536,8 +721,16 @@ function resolveComponent(evidence, file, tag, components, options = {}) {
     const binding = bindings.find((value) => value.local === local);
     if (!binding) continue;
     bound = true;
+    if (binding.isTypeOnly) continue;
     if (binding.imported === "*" !== Boolean(member)) continue;
     const exported = member ?? binding.imported;
+    const resolution = graph.resolveExport(file.relative, item.source, exported, "value");
+    if (resolution.module) {
+      if (resolution.issues.length || resolution.targets.length !== 1) continue;
+      const target = resolution.targets[0];
+      for (const component of components) if (component.source === target.file && component.name === target.name) matches.add(component);
+      continue;
+    }
     const modules = targets(evidence, file.relative, item.source);
     for (const component of components) {
       const moduleMatch = !item.source.startsWith(".") && component.importPath === item.source || modules.some((target) => {
@@ -561,12 +754,307 @@ var init_component_resolution = __esm({
   "../core/src/component-resolution.ts"() {
     "use strict";
     init_esm_shims();
+    init_local_modules();
     withoutExtension = (file) => file.replace(/\.(?:tsx?|jsx?|mts|cts|mjs|cjs)$/, "");
   }
 });
 
+// ../core/src/type-resolution.ts
+import path4 from "path";
+import ts2 from "typescript";
+function unwrap(node) {
+  if (ts2.isArrowFunction(node) || ts2.isFunctionExpression(node)) return { fn: node };
+  if (ts2.isParenthesizedExpression(node) || ts2.isAsExpression(node) || ts2.isSatisfiesExpression(node)) return unwrap(node.expression);
+  if (ts2.isCallExpression(node)) {
+    const name = ts2.isIdentifier(node.expression) ? node.expression.text : ts2.isPropertyAccessExpression(node.expression) ? node.expression.name.text : "";
+    if (name === "memo" || name === "forwardRef") {
+      const first = node.arguments[0];
+      if (first) return { ...unwrap(first), type: name === "forwardRef" ? node.typeArguments?.[1] : node.typeArguments?.[0] };
+    }
+  }
+  return {};
+}
+function componentInput(source, component) {
+  let input;
+  const visit = (node) => {
+    if (input) return;
+    const line2 = source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
+    if (ts2.isFunctionDeclaration(node) && node.name?.text === component.name && line2 === component.startLine) {
+      input = { fn: node, type: node.parameters[0]?.type };
+      return;
+    }
+    if (ts2.isVariableDeclaration(node) && ts2.isIdentifier(node.name) && node.name.text === component.name && line2 === component.startLine && node.initializer) {
+      const unwrapped = unwrap(node.initializer);
+      if (!unwrapped.fn) return;
+      let annotation;
+      if (node.type && ts2.isTypeReferenceNode(node.type) && /(?:^|\.)(?:FC|FunctionComponent|ComponentType)$/.test(node.type.typeName.getText())) annotation = node.type.typeArguments?.[0];
+      if (node.type && ts2.isFunctionTypeNode(node.type)) annotation = node.type.parameters[0]?.type;
+      input = { fn: unwrapped.fn, type: unwrapped.fn.parameters[0]?.type ?? unwrapped.type ?? annotation };
+      return;
+    }
+    ts2.forEachChild(node, visit);
+  };
+  visit(source);
+  return input;
+}
+function resolveComponentProps(evidence, component) {
+  let resolver = resolvers.get(evidence);
+  if (!resolver) {
+    resolver = new TypeResolver(evidence);
+    resolvers.set(evidence, resolver);
+  }
+  return resolver.props(component);
+}
+var resolvers, MAX_PROPS, normalize2, nameOf, TypeResolver;
+var init_type_resolution = __esm({
+  "../core/src/type-resolution.ts"() {
+    "use strict";
+    init_esm_shims();
+    init_local_modules();
+    resolvers = /* @__PURE__ */ new WeakMap();
+    MAX_PROPS = 256;
+    normalize2 = (file) => path4.resolve(file).replaceAll("\\", "/");
+    nameOf = (name) => ts2.isIdentifier(name) || ts2.isStringLiteral(name) || ts2.isNumericLiteral(name) ? name.text : name.getText();
+    TypeResolver = class {
+      constructor(evidence) {
+        this.evidence = evidence;
+        this.graph = localModules(evidence);
+        this.root = path4.resolve(evidence.root || ".");
+        this.libDirectory = normalize2(path4.dirname(ts2.getDefaultLibFilePath({})));
+      }
+      evidence;
+      program;
+      graph;
+      root;
+      libDirectory;
+      semantic = /* @__PURE__ */ new Map();
+      relative(file) {
+        return path4.relative(this.root, file).replaceAll("\\", "/");
+      }
+      isLibrary(file) {
+        return normalize2(file).startsWith(`${this.libDirectory}/`) && /\/lib\.[^/]+\.d\.ts$/.test(normalize2(file));
+      }
+      compiler() {
+        if (this.program) return this.program;
+        const options = {
+          target: ts2.ScriptTarget.ES2022,
+          module: ts2.ModuleKind.ESNext,
+          moduleResolution: ts2.ModuleResolutionKind.Bundler,
+          jsx: ts2.JsxEmit.Preserve,
+          strict: true,
+          noEmit: true,
+          allowJs: true,
+          checkJs: false,
+          skipLibCheck: true,
+          types: [],
+          lib: ["lib.es2022.d.ts"]
+        };
+        const original = ts2.createCompilerHost(options, true);
+        const read = (file) => this.graph.files.get(this.relative(file)) ?? (this.isLibrary(file) ? ts2.sys.readFile(file) : void 0);
+        const host = {
+          ...original,
+          getCurrentDirectory: () => this.root,
+          getCanonicalFileName: normalize2,
+          useCaseSensitiveFileNames: () => true,
+          readFile: read,
+          fileExists: (file) => read(file) !== void 0,
+          getSourceFile: (file, languageVersion) => {
+            const source = this.graph.source(this.relative(file));
+            if (source) return source;
+            const text = this.isLibrary(file) ? ts2.sys.readFile(file) : void 0;
+            return text === void 0 ? void 0 : ts2.createSourceFile(file, text, languageVersion, true);
+          },
+          writeFile: () => {
+            throw new Error("Design Rover's type resolver never emits application code.");
+          },
+          resolveModuleNames: (names, containingFile) => names.map((name) => {
+            const target = this.graph.resolveModule(this.relative(containingFile), name);
+            if (!target) return void 0;
+            return { resolvedFileName: path4.resolve(this.root, target), isExternalLibraryImport: false };
+          }),
+          resolveTypeReferenceDirectives: (names) => names.map(() => void 0)
+        };
+        this.program = ts2.createProgram([...this.graph.files.keys()].map((file) => path4.resolve(this.root, file)), options, host);
+        return this.program;
+      }
+      props(component) {
+        const source = this.graph.source(component.file);
+        const input = source && componentInput(source, component);
+        if (!input) return { props: component.props, resolution: { status: "unresolved", issues: ["The component's function declaration could not be matched to its source location."] } };
+        const parameter = input.fn.parameters[0];
+        if (!parameter && !input.type) return { props: [], resolution: { status: "resolved", issues: [] } };
+        const defaults = /* @__PURE__ */ new Map();
+        const untyped = [];
+        if (parameter && ts2.isObjectBindingPattern(parameter.name)) {
+          for (const binding of parameter.name.elements) {
+            if (binding.dotDotDotToken) continue;
+            const name = binding.propertyName ? nameOf(binding.propertyName) : binding.name.getText();
+            if (binding.initializer) defaults.set(name, binding.initializer.getText());
+            untyped.push({ name, required: !binding.initializer, defaultValue: binding.initializer?.getText() });
+          }
+        }
+        if (!input.type) return { props: untyped, resolution: { status: "untyped", issues: ["The props parameter has no explicit supported type annotation. Destructured bindings are not a complete component API."] } };
+        const program = this.compiler();
+        const checker = program.getTypeChecker();
+        const issues = /* @__PURE__ */ new Set();
+        const visited = /* @__PURE__ */ new Set();
+        let unsafeDependency = false;
+        const diagnostics = (node) => {
+          const source2 = node.getSourceFile();
+          let all = this.semantic.get(source2.fileName);
+          if (!all) {
+            all = [...program.getSyntacticDiagnostics(source2), ...program.getSemanticDiagnostics(source2)];
+            this.semantic.set(source2.fileName, all);
+          }
+          const start = node.getStart(source2);
+          const end = node.getEnd();
+          for (const diagnostic of all) if (diagnostic.category === ts2.DiagnosticCategory.Error && diagnostic.start !== void 0 && diagnostic.start >= start && diagnostic.start < end) {
+            issues.add(`${this.relative(source2.fileName)}: ${ts2.flattenDiagnosticMessageText(diagnostic.messageText, " ")}`);
+          }
+        };
+        const importType = (node) => {
+          const argument = node.argument;
+          if (!ts2.isLiteralTypeNode(argument) || !ts2.isStringLiteral(argument.literal) || !node.qualifier || !ts2.isIdentifier(node.qualifier)) {
+            return { targets: [], issues: ["An import type must identify one explicit local exported member; computed or nested import-type members are unsupported."] };
+          }
+          return this.graph.resolveExport(this.relative(node.getSourceFile().fileName), argument.literal.text, node.qualifier.text, node.isTypeOf ? "value" : "type");
+        };
+        const reference = (name) => {
+          const current = name.getSourceFile();
+          const file = this.relative(current.fileName);
+          const parts = name.getText(current).split(".");
+          const first = parts[0];
+          for (const statement of current.statements) {
+            if (!ts2.isImportDeclaration(statement) || !ts2.isStringLiteral(statement.moduleSpecifier)) continue;
+            const clause = statement.importClause;
+            const bindings = clause?.namedBindings;
+            let imported;
+            if (parts.length === 1 && clause?.name?.text === first) imported = "default";
+            if (parts.length === 1 && bindings && ts2.isNamedImports(bindings)) {
+              const binding = bindings.elements.find((item) => item.name.text === first);
+              if (binding) imported = binding.propertyName?.text ?? binding.name.text;
+            }
+            if (parts.length === 2 && bindings && ts2.isNamespaceImport(bindings) && bindings.name.text === first) imported = parts[1];
+            if (imported) {
+              const resolution = this.graph.resolveExport(file, statement.moduleSpecifier.text, imported, "type");
+              for (const issue of resolution.issues) issues.add(issue);
+              if (resolution.targets.length !== 1 && !resolution.issues.length) issues.add(`Cannot resolve a unique local type export ${imported} from ${statement.moduleSpecifier.text}.`);
+              if (resolution.issues.length || resolution.targets.length !== 1) unsafeDependency = true;
+            }
+          }
+          let symbol = checker.getSymbolAtLocation(name);
+          if (symbol?.flags && symbol.flags & ts2.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+          if (!symbol || !symbol.declarations?.length) {
+            issues.add(`Cannot resolve type ${name.getText(current)} in ${file}.`);
+            unsafeDependency = true;
+            return;
+          }
+          for (const declaration of symbol.declarations) {
+            if (this.isLibrary(declaration.getSourceFile().fileName)) continue;
+            if (!this.graph.files.has(this.relative(declaration.getSourceFile().fileName))) {
+              issues.add(`Type ${name.getText(current)} is declared outside scanned repository files.`);
+              continue;
+            }
+            if (ts2.isTypeAliasDeclaration(declaration) || ts2.isInterfaceDeclaration(declaration) || ts2.isClassDeclaration(declaration)) walk(declaration);
+          }
+        };
+        const walk = (node) => {
+          if (visited.has(node)) return;
+          visited.add(node);
+          diagnostics(node);
+          if (ts2.isClassDeclaration(node)) issues.add("Class-based props contracts are only partially supported; inherited and runtime-initialized members require inspection.");
+          if (ts2.isTypeReferenceNode(node)) reference(node.typeName);
+          if (ts2.isExpressionWithTypeArguments(node)) reference(node.expression);
+          if (ts2.isImportTypeNode(node)) {
+            const resolution = importType(node);
+            for (const issue of resolution.issues) issues.add(issue);
+            if (resolution.issues.length || resolution.targets.length !== 1) {
+              unsafeDependency = true;
+              if (!resolution.issues.length) issues.add("The import type does not identify a unique local exported declaration.");
+            } else if (node.qualifier) {
+              let symbol = checker.getSymbolAtLocation(node.qualifier);
+              if (symbol?.flags && symbol.flags & ts2.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+              for (const declaration of symbol?.declarations ?? []) if (ts2.isTypeAliasDeclaration(declaration) || ts2.isInterfaceDeclaration(declaration) || ts2.isClassDeclaration(declaration)) walk(declaration);
+            }
+          }
+          ts2.forEachChild(node, walk);
+        };
+        walk(input.type);
+        const type = checker.getTypeFromTypeNode(input.type);
+        const primitive = ts2.TypeFlags.StringLike | ts2.TypeFlags.NumberLike | ts2.TypeFlags.BooleanLike | ts2.TypeFlags.BigIntLike | ts2.TypeFlags.ESSymbolLike | ts2.TypeFlags.Null | ts2.TypeFlags.Undefined | ts2.TypeFlags.Void;
+        const nonObject = Boolean(type.flags & primitive) || type.isUnion() && type.types.some((member) => Boolean(member.flags & primitive));
+        if (nonObject) issues.add("The props annotation includes a non-object type; primitive members are not a component property API.");
+        if (type.flags & (ts2.TypeFlags.Any | ts2.TypeFlags.Unknown | ts2.TypeFlags.TypeParameter | ts2.TypeFlags.Conditional | ts2.TypeFlags.Never)) issues.add("The props object type could not be resolved to a concrete local contract.");
+        if (type.isUnion()) issues.add("Union props expose only common properties; branch-specific contracts remain unresolved.");
+        if (checker.getIndexInfosOfType(type).length) issues.add("The props type has an index signature; arbitrary property names are not enumerated.");
+        const proven = (node, seen) => {
+          if (seen.has(node)) return [];
+          const next = new Set(seen).add(node);
+          if (ts2.isParenthesizedTypeNode(node)) return proven(node.type, next);
+          if (ts2.isIntersectionTypeNode(node)) return node.types.flatMap((member) => proven(member, next));
+          if (ts2.isTypeLiteralNode(node)) return checker.getPropertiesOfType(checker.getTypeFromTypeNode(node));
+          if (ts2.isInterfaceDeclaration(node) || ts2.isClassDeclaration(node)) {
+            const own = node.members.flatMap((member) => member.name && !(ts2.canHaveModifiers(member) && ts2.getModifiers(member)?.some((modifier) => modifier.kind === ts2.SyntaxKind.StaticKeyword)) ? [checker.getSymbolAtLocation(member.name)].filter((symbol) => Boolean(symbol)) : []);
+            return [...own, ...(node.heritageClauses ?? []).flatMap((clause) => clause.types.flatMap((base) => proven(base, next)))];
+          }
+          if (ts2.isTypeAliasDeclaration(node)) return proven(node.type, next);
+          if (ts2.isImportTypeNode(node)) {
+            const resolution = importType(node);
+            if (resolution.issues.length || resolution.targets.length !== 1) return [];
+            let symbol = node.qualifier && checker.getSymbolAtLocation(node.qualifier);
+            if (symbol?.flags && symbol.flags & ts2.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+            return (symbol?.declarations ?? []).filter((declaration) => !this.isLibrary(declaration.getSourceFile().fileName)).flatMap((declaration) => proven(declaration, next));
+          }
+          if (ts2.isTypeReferenceNode(node) || ts2.isExpressionWithTypeArguments(node)) {
+            const name = ts2.isTypeReferenceNode(node) ? node.typeName : node.expression;
+            const file = this.relative(node.getSourceFile().fileName);
+            const parts = name.getText().split(".");
+            for (const statement of node.getSourceFile().statements) {
+              if (!ts2.isImportDeclaration(statement) || !ts2.isStringLiteral(statement.moduleSpecifier)) continue;
+              const clause = statement.importClause;
+              const bindings = clause?.namedBindings;
+              let imported = parts.length === 1 && clause?.name?.text === parts[0] ? "default" : void 0;
+              if (parts.length === 1 && bindings && ts2.isNamedImports(bindings)) {
+                const binding = bindings.elements.find((member) => member.name.text === parts[0]);
+                if (binding) imported = binding.propertyName?.text ?? binding.name.text;
+              }
+              if (parts.length === 2 && bindings && ts2.isNamespaceImport(bindings) && bindings.name.text === parts[0]) imported = parts[1];
+              if (imported) {
+                const resolution = this.graph.resolveExport(file, statement.moduleSpecifier.text, imported, "type");
+                if (resolution.issues.length || resolution.targets.length !== 1) return [];
+              }
+            }
+            let symbol = checker.getSymbolAtLocation(name);
+            if (symbol?.flags && symbol.flags & ts2.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+            return (symbol?.declarations ?? []).filter((declaration) => !this.isLibrary(declaration.getSourceFile().fileName)).flatMap((declaration) => proven(declaration, next));
+          }
+          return [];
+        };
+        const candidates = nonObject ? [] : unsafeDependency || type.flags & (ts2.TypeFlags.Any | ts2.TypeFlags.Unknown) ? proven(input.type, /* @__PURE__ */ new Set()) : checker.getPropertiesOfType(type);
+        const symbols = [...new Map(candidates.map((symbol) => [symbol.name, symbol])).values()];
+        if (symbols.length > MAX_PROPS) issues.add(`The props contract exceeds ${MAX_PROPS} properties; only the first ${MAX_PROPS} are included.`);
+        const props = symbols.slice(0, MAX_PROPS).map((symbol) => {
+          const propertyType = checker.getTypeOfSymbolAtLocation(symbol, input.type);
+          const required = !(symbol.flags & ts2.SymbolFlags.Optional);
+          const members = propertyType.isUnion() ? propertyType.types.filter((member) => required || !(member.flags & ts2.TypeFlags.Undefined)) : [propertyType];
+          if (members.some((member) => member.flags & (ts2.TypeFlags.TypeParameter | ts2.TypeFlags.Conditional | ts2.TypeFlags.IndexedAccess))) issues.add(`Property ${symbol.name} depends on unresolved generic type information.`);
+          const values = members.length && members.every((member) => member.isStringLiteral()) ? members.map((member) => member.value).sort() : void 0;
+          return {
+            name: symbol.name,
+            type: members.map((member) => checker.typeToString(member, input.type, ts2.TypeFormatFlags.NoTruncation | ts2.TypeFormatFlags.InTypeAlias)).join(" | ") || "undefined",
+            required,
+            values,
+            defaultValue: defaults.get(symbol.name)
+          };
+        }).sort((a, b) => a.name.localeCompare(b.name));
+        return { props, resolution: { status: issues.size ? props.length ? "partial" : "unresolved" : "resolved", issues: [...issues].sort() } };
+      }
+    };
+  }
+});
+
 // ../core/src/analyzers/components.ts
-import path3 from "path";
+import path5 from "path";
 function isUiPath(file) {
   return /(^|\/)(components\/ui|ui\/|components\/primitives)\//.test(file);
 }
@@ -579,7 +1067,7 @@ function isPageFile(file) {
 function importPathFor(evidence, file, name) {
   const aliases = evidence.componentsJson?.aliases ?? {};
   if (aliases.ui && isUiPath(file)) {
-    const base = path3.posix.basename(file).replace(/\.(tsx|jsx|ts|js)$/, "");
+    const base = path5.posix.basename(file).replace(/\.(tsx|jsx|ts|js)$/, "");
     return `${aliases.ui}/${base}`;
   }
   if (aliases.components && file.includes("components/")) {
@@ -646,18 +1134,21 @@ function analyzeComponents(evidence, tokenNames) {
   return records.sort((a, b) => a.id.localeCompare(b.id));
 }
 function toRecord(evidence, component, usage, architecture, local, id, tokenNames) {
+  const api = resolveComponentProps(evidence, component);
   return {
     id,
     name: component.name,
     source: component.file,
     importPath: importPathFor(evidence, component.file, component.name),
     exportName: component.isDefault ? "default" : component.exportName,
-    props: component.props.map((prop) => ({
+    props: api.props.map((prop) => ({
       name: prop.name,
       type: prop.type,
       required: prop.required,
-      values: prop.values
+      values: prop.values,
+      defaultValue: prop.defaultValue
     })),
+    propsResolution: api.resolution,
     variants: component.variants,
     sizes: component.sizes,
     composition: component.composition,
@@ -668,7 +1159,7 @@ function toRecord(evidence, component, usage, architecture, local, id, tokenName
     architecture,
     local,
     status: "observed",
-    confidence: "high",
+    confidence: api.resolution.status === "resolved" ? "high" : api.resolution.status === "partial" ? "medium" : "low",
     originKind: "implementation",
     evidence: [
       {
@@ -677,7 +1168,13 @@ function toRecord(evidence, component, usage, architecture, local, id, tokenName
         description: `${component.name} declared in ${component.file}`,
         location: { file: component.file, startLine: component.startLine },
         count: usage.length
-      }
+      },
+      ...api.resolution.issues.map((description, index) => ({
+        id: `${id}:api-${index}`,
+        kind: "component-api-resolution",
+        description,
+        location: { file: component.file, startLine: component.startLine }
+      }))
     ]
   };
 }
@@ -688,6 +1185,7 @@ var init_components = __esm({
     init_src();
     init_hash();
     init_component_resolution();
+    init_type_resolution();
   }
 });
 
@@ -1444,37 +1942,37 @@ var init_tokens = __esm({
 });
 
 // ../core/src/paths.ts
-import path4 from "path";
+import path6 from "path";
 function specDir(root) {
-  return path4.join(root, SPEC_DIR);
+  return path6.join(root, SPEC_DIR);
 }
 function specPaths(root) {
   const dir = specDir(root);
   return {
     dir,
-    system: path4.join(dir, "system.json"),
-    tokens: path4.join(dir, "tokens"),
-    components: path4.join(dir, "components"),
-    patterns: path4.join(dir, "patterns"),
-    intents: path4.join(dir, "intents"),
-    conventions: path4.join(dir, "conventions"),
-    exceptions: path4.join(dir, "exceptions"),
-    generated: path4.join(dir, "generated"),
-    history: path4.join(dir, "history"),
-    historyLog: path4.join(dir, "history", "events.jsonl"),
-    rejections: path4.join(dir, "rejections.json"),
-    baseline: path4.join(dir, "baseline.json"),
-    sources: path4.join(dir, "sources.json"),
-    discrepancies: path4.join(dir, "discrepancies.json"),
-    cache: path4.join(dir, "cache"),
-    gitignore: path4.join(dir, ".gitignore")
+    system: path6.join(dir, "system.json"),
+    tokens: path6.join(dir, "tokens"),
+    components: path6.join(dir, "components"),
+    patterns: path6.join(dir, "patterns"),
+    intents: path6.join(dir, "intents"),
+    conventions: path6.join(dir, "conventions"),
+    exceptions: path6.join(dir, "exceptions"),
+    generated: path6.join(dir, "generated"),
+    history: path6.join(dir, "history"),
+    historyLog: path6.join(dir, "history", "events.jsonl"),
+    rejections: path6.join(dir, "rejections.json"),
+    baseline: path6.join(dir, "baseline.json"),
+    sources: path6.join(dir, "sources.json"),
+    discrepancies: path6.join(dir, "discrepancies.json"),
+    cache: path6.join(dir, "cache"),
+    gitignore: path6.join(dir, ".gitignore")
   };
 }
 function toPosix(filePath) {
-  return filePath.split(path4.sep).join("/");
+  return filePath.split(path6.sep).join("/");
 }
 function relativePosix(root, filePath) {
-  return toPosix(path4.relative(root, filePath));
+  return toPosix(path6.relative(root, filePath));
 }
 var init_paths = __esm({
   "../core/src/paths.ts"() {
@@ -1499,7 +1997,7 @@ __export(fs_exports, {
 });
 import { execFile } from "child_process";
 import { promisify } from "util";
-import path5 from "path";
+import path7 from "path";
 import fs from "fs/promises";
 async function isGitRepo(root) {
   try {
@@ -1592,7 +2090,7 @@ async function readText(filePath) {
   }
 }
 async function writeText(filePath, content) {
-  await fs.mkdir(path5.dirname(filePath), { recursive: true });
+  await fs.mkdir(path7.dirname(filePath), { recursive: true });
   await fs.writeFile(filePath, content, "utf8");
 }
 async function readJsonFile(filePath, fallback) {
@@ -1607,7 +2105,7 @@ async function readJsonFile(filePath, fallback) {
 async function listJsonFiles(dir) {
   try {
     const entries = await fs.readdir(dir, { withFileTypes: true });
-    return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => path5.join(dir, entry.name)).sort();
+    return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => path7.join(dir, entry.name)).sort();
   } catch {
     return [];
   }
@@ -1624,37 +2122,37 @@ var init_fs = __esm({
 });
 
 // ../core/src/parse.ts
-import ts from "typescript";
+import ts3 from "typescript";
 import postcss from "postcss";
-function scriptKind(file) {
-  if (file.endsWith(".tsx")) return ts.ScriptKind.TSX;
-  if (file.endsWith(".jsx")) return ts.ScriptKind.JSX;
+function scriptKind2(file) {
+  if (file.endsWith(".tsx")) return ts3.ScriptKind.TSX;
+  if (file.endsWith(".jsx")) return ts3.ScriptKind.JSX;
   if (file.endsWith(".js") || file.endsWith(".mjs") || file.endsWith(".cjs")) {
-    return ts.ScriptKind.JS;
+    return ts3.ScriptKind.JS;
   }
-  return ts.ScriptKind.TS;
+  return ts3.ScriptKind.TS;
 }
 function lineOf(source, node) {
   return source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1;
 }
 function isJsx(node) {
-  return ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node);
+  return ts3.isJsxElement(node) || ts3.isJsxSelfClosingElement(node) || ts3.isJsxFragment(node);
 }
 function nodeReturnsJsx(node) {
   let found = false;
   const visit = (child) => {
     if (found) return;
-    if (ts.isReturnStatement(child) && child.expression && containsJsx(child.expression)) {
+    if (ts3.isReturnStatement(child) && child.expression && containsJsx(child.expression)) {
       found = true;
       return;
     }
-    if (ts.isArrowFunction(child) || ts.isFunctionExpression(child) || ts.isFunctionDeclaration(child)) {
+    if (ts3.isArrowFunction(child) || ts3.isFunctionExpression(child) || ts3.isFunctionDeclaration(child)) {
       return;
     }
-    ts.forEachChild(child, visit);
+    ts3.forEachChild(child, visit);
   };
-  ts.forEachChild(node, visit);
-  if (ts.isArrowFunction(node) && node.body && containsJsx(node.body)) return true;
+  ts3.forEachChild(node, visit);
+  if (ts3.isArrowFunction(node) && node.body && containsJsx(node.body)) return true;
   return found;
 }
 function containsJsx(node) {
@@ -1666,9 +2164,9 @@ function containsJsx(node) {
       found = true;
       return;
     }
-    ts.forEachChild(child, visit);
+    ts3.forEachChild(child, visit);
   };
-  ts.forEachChild(node, visit);
+  ts3.forEachChild(node, visit);
   return found;
 }
 function isComponentName(name) {
@@ -1676,18 +2174,18 @@ function isComponentName(name) {
 }
 function collectClassesFromExpr(expr) {
   if (!expr) return { classes: [], dynamic: false };
-  if (ts.isStringLiteral(expr) || ts.isNoSubstitutionTemplateLiteral(expr)) {
+  if (ts3.isStringLiteral(expr) || ts3.isNoSubstitutionTemplateLiteral(expr)) {
     return { classes: splitClasses(expr.text), dynamic: false };
   }
-  if (ts.isTemplateExpression(expr)) {
+  if (ts3.isTemplateExpression(expr)) {
     const parts = [expr.head.text, ...expr.templateSpans.map((span) => span.literal.text)];
     return { classes: splitClasses(parts.join(" ")), dynamic: true };
   }
-  if (ts.isCallExpression(expr)) {
+  if (ts3.isCallExpression(expr)) {
     const name = callName(expr);
     if (name && CLASS_FNS.has(name)) {
       const merged = expr.arguments.map(
-        (arg) => ts.isExpression(arg) ? collectClassesFromExpr(arg) : { classes: [], dynamic: false }
+        (arg) => ts3.isExpression(arg) ? collectClassesFromExpr(arg) : { classes: [], dynamic: false }
       );
       return {
         classes: merged.flatMap((item) => item.classes),
@@ -1696,7 +2194,7 @@ function collectClassesFromExpr(expr) {
     }
     return { classes: [], dynamic: true };
   }
-  if (ts.isConditionalExpression(expr)) {
+  if (ts3.isConditionalExpression(expr)) {
     const left = collectClassesFromExpr(expr.whenTrue);
     const right = collectClassesFromExpr(expr.whenFalse);
     return {
@@ -1704,7 +2202,7 @@ function collectClassesFromExpr(expr) {
       dynamic: true
     };
   }
-  if (ts.isBinaryExpression(expr)) {
+  if (ts3.isBinaryExpression(expr)) {
     const left = collectClassesFromExpr(expr.left);
     const right = collectClassesFromExpr(expr.right);
     return {
@@ -1712,13 +2210,13 @@ function collectClassesFromExpr(expr) {
       dynamic: left.dynamic || right.dynamic
     };
   }
-  if (ts.isParenthesizedExpression(expr)) {
+  if (ts3.isParenthesizedExpression(expr)) {
     return collectClassesFromExpr(expr.expression);
   }
-  if (ts.isObjectLiteralExpression(expr)) {
+  if (ts3.isObjectLiteralExpression(expr)) {
     const classes = [];
     for (const prop of expr.properties) {
-      if (ts.isPropertyAssignment(prop) && ts.isStringLiteral(prop.initializer)) {
+      if (ts3.isPropertyAssignment(prop) && ts3.isStringLiteral(prop.initializer)) {
         classes.push(...splitClasses(prop.initializer.text));
       }
     }
@@ -1727,17 +2225,17 @@ function collectClassesFromExpr(expr) {
   return { classes: [], dynamic: true };
 }
 function callName(expr) {
-  if (ts.isIdentifier(expr.expression)) return expr.expression.text;
-  if (ts.isPropertyAccessExpression(expr.expression)) return expr.expression.name.text;
+  if (ts3.isIdentifier(expr.expression)) return expr.expression.text;
+  if (ts3.isPropertyAccessExpression(expr.expression)) return expr.expression.name.text;
   return void 0;
 }
 function unionValues(typeNode) {
   if (!typeNode) return void 0;
-  if (ts.isUnionTypeNode(typeNode)) {
-    const values = typeNode.types.map((item) => ts.isLiteralTypeNode(item) && ts.isStringLiteral(item.literal) ? item.literal.text : void 0).filter((item) => Boolean(item));
+  if (ts3.isUnionTypeNode(typeNode)) {
+    const values = typeNode.types.map((item) => ts3.isLiteralTypeNode(item) && ts3.isStringLiteral(item.literal) ? item.literal.text : void 0).filter((item) => Boolean(item));
     return values.length ? values : void 0;
   }
-  if (ts.isLiteralTypeNode(typeNode) && ts.isStringLiteral(typeNode.literal)) {
+  if (ts3.isLiteralTypeNode(typeNode) && ts3.isStringLiteral(typeNode.literal)) {
     return [typeNode.literal.text];
   }
   return void 0;
@@ -1745,7 +2243,7 @@ function unionValues(typeNode) {
 function propsFromTypeLiteral(literal) {
   const props = [];
   for (const member of literal.members) {
-    if (!ts.isPropertySignature(member) || !member.name) continue;
+    if (!ts3.isPropertySignature(member) || !member.name) continue;
     const name = member.name.getText();
     props.push({
       name,
@@ -1758,22 +2256,22 @@ function propsFromTypeLiteral(literal) {
 }
 function findInterface(source, name) {
   for (const stmt of source.statements) {
-    if (ts.isInterfaceDeclaration(stmt) && stmt.name.text === name) return stmt;
-    if (ts.isTypeAliasDeclaration(stmt) && stmt.name.text === name) return stmt;
+    if (ts3.isInterfaceDeclaration(stmt) && stmt.name.text === name) return stmt;
+    if (ts3.isTypeAliasDeclaration(stmt) && stmt.name.text === name) return stmt;
   }
   return void 0;
 }
 function propsFromType(source, typeNode) {
   if (!typeNode) return [];
-  if (ts.isTypeLiteralNode(typeNode)) return propsFromTypeLiteral(typeNode);
-  if (ts.isTypeReferenceNode(typeNode) && ts.isIdentifier(typeNode.typeName)) {
+  if (ts3.isTypeLiteralNode(typeNode)) return propsFromTypeLiteral(typeNode);
+  if (ts3.isTypeReferenceNode(typeNode) && ts3.isIdentifier(typeNode.typeName)) {
     const decl = findInterface(source, typeNode.typeName.text);
     if (!decl) return [];
-    if (ts.isInterfaceDeclaration(decl)) {
-      const fake = ts.factory.createTypeLiteralNode(decl.members);
+    if (ts3.isInterfaceDeclaration(decl)) {
+      const fake = ts3.factory.createTypeLiteralNode(decl.members);
       return propsFromTypeLiteral(fake);
     }
-    if (ts.isTypeAliasDeclaration(decl) && decl.type && ts.isTypeLiteralNode(decl.type)) {
+    if (ts3.isTypeAliasDeclaration(decl) && decl.type && ts3.isTypeLiteralNode(decl.type)) {
       return propsFromTypeLiteral(decl.type);
     }
   }
@@ -1783,7 +2281,7 @@ function propsFromFunction(source, fn) {
   const first = fn.parameters[0];
   if (!first) return [];
   if (first.type) return propsFromType(source, first.type);
-  if (ts.isObjectBindingPattern(first.name)) {
+  if (ts3.isObjectBindingPattern(first.name)) {
     return first.name.elements.map((el) => ({
       name: el.name.getText(),
       required: !el.dotDotDotToken
@@ -1791,15 +2289,15 @@ function propsFromFunction(source, fn) {
   }
   return [];
 }
-function unwrap(node) {
-  if (ts.isCallExpression(node)) {
+function unwrap2(node) {
+  if (ts3.isCallExpression(node)) {
     const name = callName(node);
     if (name === "forwardRef" || name === "memo") {
       const arg = node.arguments[0];
-      if (arg && ts.isExpression(arg)) return unwrap(arg);
+      if (arg && ts3.isExpression(arg)) return unwrap2(arg);
     }
   }
-  if (ts.isParenthesizedExpression(node)) return unwrap(node.expression);
+  if (ts3.isParenthesizedExpression(node)) return unwrap2(node.expression);
   return node;
 }
 function extractCva(node) {
@@ -1807,24 +2305,24 @@ function extractCva(node) {
   const sizes = [];
   const classes = [];
   const base = node.arguments[0];
-  if (base && ts.isExpression(base)) {
+  if (base && ts3.isExpression(base)) {
     classes.push(...collectClassesFromExpr(base).classes);
   }
   const config = node.arguments[1];
-  if (config && ts.isObjectLiteralExpression(config)) {
+  if (config && ts3.isObjectLiteralExpression(config)) {
     for (const prop of config.properties) {
-      if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue;
-      if (prop.name.text !== "variants" || !ts.isObjectLiteralExpression(prop.initializer)) continue;
+      if (!ts3.isPropertyAssignment(prop) || !ts3.isIdentifier(prop.name)) continue;
+      if (prop.name.text !== "variants" || !ts3.isObjectLiteralExpression(prop.initializer)) continue;
       for (const group of prop.initializer.properties) {
-        if (!ts.isPropertyAssignment(group) || !ts.isIdentifier(group.name)) continue;
+        if (!ts3.isPropertyAssignment(group) || !ts3.isIdentifier(group.name)) continue;
         const groupName = group.name.text;
-        if (!ts.isObjectLiteralExpression(group.initializer)) continue;
-        const keys = group.initializer.properties.map((item) => ts.isPropertyAssignment(item) ? item.name.getText().replace(/['"]/g, "") : void 0).filter((item) => Boolean(item));
+        if (!ts3.isObjectLiteralExpression(group.initializer)) continue;
+        const keys = group.initializer.properties.map((item) => ts3.isPropertyAssignment(item) ? item.name.getText().replace(/['"]/g, "") : void 0).filter((item) => Boolean(item));
         if (groupName === "size") sizes.push(...keys);
         else if (groupName === "variant") variants.push(...keys);
         else variants.push(...keys.map((key) => `${groupName}:${key}`));
         for (const item of group.initializer.properties) {
-          if (ts.isPropertyAssignment(item) && ts.isExpression(item.initializer)) {
+          if (ts3.isPropertyAssignment(item) && ts3.isExpression(item.initializer)) {
             classes.push(...collectClassesFromExpr(item.initializer).classes);
           }
         }
@@ -1839,11 +2337,11 @@ function tagName(node) {
 function jsxAttributes(node) {
   const attrs = {};
   for (const attr of node.properties) {
-    if (!ts.isJsxAttribute(attr) || !attr.initializer) continue;
+    if (!ts3.isJsxAttribute(attr) || !attr.initializer) continue;
     const name = attr.name.getText();
-    if (ts.isStringLiteral(attr.initializer)) attrs[name] = attr.initializer.text;
-    else if (ts.isJsxExpression(attr.initializer) && attr.initializer.expression) {
-      if (ts.isStringLiteral(attr.initializer.expression)) {
+    if (ts3.isStringLiteral(attr.initializer)) attrs[name] = attr.initializer.text;
+    else if (ts3.isJsxExpression(attr.initializer) && attr.initializer.expression) {
+      if (ts3.isStringLiteral(attr.initializer.expression)) {
         attrs[name] = attr.initializer.expression.text;
       }
     }
@@ -1851,28 +2349,28 @@ function jsxAttributes(node) {
   return attrs;
 }
 function opening(node) {
-  return ts.isJsxElement(node) ? node.openingElement : node;
+  return ts3.isJsxElement(node) ? node.openingElement : node;
 }
 function walkJsxTree(node, tags, components, families, depth) {
   let childCount = 0;
   let maxDepth = depth;
-  const children = ts.isJsxFragment(node) ? node.children : ts.isJsxElement(node) ? node.children : [];
-  if (!ts.isJsxFragment(node)) {
+  const children = ts3.isJsxFragment(node) ? node.children : ts3.isJsxElement(node) ? node.children : [];
+  if (!ts3.isJsxFragment(node)) {
     const open = opening(node);
     const name = tagName(open.tagName);
     if (isComponentName(name)) components.push(name);
     else tags.push(name);
     const classAttr = open.attributes.properties.find(
-      (prop) => ts.isJsxAttribute(prop) && prop.name.getText() === "className"
+      (prop) => ts3.isJsxAttribute(prop) && prop.name.getText() === "className"
     );
-    if (classAttr && ts.isJsxAttribute(classAttr)) {
+    if (classAttr && ts3.isJsxAttribute(classAttr)) {
       const expr = classAttr.initializer;
-      const collected = expr && ts.isJsxExpression(expr) ? collectClassesFromExpr(expr.expression) : expr && ts.isStringLiteral(expr) ? { classes: splitClasses(expr.text), dynamic: false } : { classes: [], dynamic: false };
+      const collected = expr && ts3.isJsxExpression(expr) ? collectClassesFromExpr(expr.expression) : expr && ts3.isStringLiteral(expr) ? { classes: splitClasses(expr.text), dynamic: false } : { classes: [], dynamic: false };
       for (const cls of collected.classes) families.add(classFamily(cls));
     }
   }
   for (const child of children) {
-    if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child) || ts.isJsxFragment(child)) {
+    if (ts3.isJsxElement(child) || ts3.isJsxSelfClosingElement(child) || ts3.isJsxFragment(child)) {
       childCount += 1;
       const nested = walkJsxTree(child, tags, components, families, depth + 1);
       childCount += nested.childCount;
@@ -1887,25 +2385,25 @@ function variantsOwnerName(name) {
   return `${base[0].toUpperCase()}${base.slice(1)}`;
 }
 function findComponent(components, name) {
-  const owner = variantsOwnerName(name);
+  const owner2 = variantsOwnerName(name);
   return components.find(
-    (item) => item.name === name || item.name === owner || item.name.toLowerCase() === name.toLowerCase()
+    (item) => item.name === name || item.name === owner2 || item.name.toLowerCase() === name.toLowerCase()
   );
 }
 function headingFrom(node) {
   let heading;
   const visit = (child) => {
     if (heading) return;
-    if (ts.isJsxElement(child)) {
+    if (ts3.isJsxElement(child)) {
       const name = tagName(child.openingElement.tagName);
       if (/^h[1-3]$/.test(name)) {
-        heading = child.children.map((item) => ts.isJsxText(item) ? item.getText() : "").join("").trim();
+        heading = child.children.map((item) => ts3.isJsxText(item) ? item.getText() : "").join("").trim();
         return;
       }
     }
-    ts.forEachChild(child, visit);
+    ts3.forEachChild(child, visit);
   };
-  ts.forEachChild(node, visit);
+  ts3.forEachChild(node, visit);
   return heading || void 0;
 }
 function isPlaceholderSrc(src) {
@@ -1931,14 +2429,14 @@ function cssVariables(content, file) {
 }
 function commentsFromSource(source, relative) {
   const hits = [];
-  const trivia = ts.getLeadingCommentRanges(source.text, 0) ?? [];
+  const trivia = ts3.getLeadingCommentRanges(source.text, 0) ?? [];
   const ranges = [...trivia];
   const visit = (node) => {
-    const leading = ts.getLeadingCommentRanges(source.text, node.pos) ?? [];
+    const leading = ts3.getLeadingCommentRanges(source.text, node.pos) ?? [];
     ranges.push(...leading);
-    ts.forEachChild(node, visit);
+    ts3.forEachChild(node, visit);
   };
-  ts.forEachChild(source, visit);
+  ts3.forEachChild(source, visit);
   const seen = /* @__PURE__ */ new Set();
   for (const range of ranges) {
     if (seen.has(range.pos)) continue;
@@ -1973,12 +2471,12 @@ function extractFileEvidence(input) {
     empty.comments = input.content.split("\n").map((text, index) => ({ file: input.relative, text, startLine: index + 1 })).filter((item) => /TODO|FIXME|placeholder/i.test(item.text));
     return empty;
   }
-  const source = ts.createSourceFile(
+  const source = ts3.createSourceFile(
     input.relative,
     input.content,
-    ts.ScriptTarget.Latest,
+    ts3.ScriptTarget.Latest,
     true,
-    scriptKind(input.relative)
+    scriptKind2(input.relative)
   );
   const components = [];
   const classes = [];
@@ -1989,29 +2487,29 @@ function extractFileEvidence(input) {
   const exportedClassConstants = [];
   const interfaces = /* @__PURE__ */ new Map();
   for (const stmt of source.statements) {
-    if (ts.isInterfaceDeclaration(stmt)) {
-      interfaces.set(stmt.name.text, propsFromTypeLiteral(ts.factory.createTypeLiteralNode(stmt.members)));
+    if (ts3.isInterfaceDeclaration(stmt)) {
+      interfaces.set(stmt.name.text, propsFromTypeLiteral(ts3.factory.createTypeLiteralNode(stmt.members)));
     }
   }
   function maybeComponent(name, node, exported, isDefault, start) {
     if (!isComponentName(name)) return;
-    const fn = ts.isFunctionLike(node) ? node : void 0;
-    const expr = !fn && ts.isExpression(node) ? unwrap(node) : node;
+    const fn = ts3.isFunctionLike(node) ? node : void 0;
+    const expr = !fn && ts3.isExpression(node) ? unwrap2(node) : node;
     const bodyNode = fn ?? expr;
-    if (!nodeReturnsJsx(bodyNode) && !(ts.isFunctionLike(bodyNode) && bodyNode.body && containsJsx(bodyNode.body))) {
-      if (!(ts.isArrowFunction(expr) && expr.body && containsJsx(expr.body))) return;
+    if (!nodeReturnsJsx(bodyNode) && !(ts3.isFunctionLike(bodyNode) && bodyNode.body && containsJsx(bodyNode.body))) {
+      if (!(ts3.isArrowFunction(expr) && expr.body && containsJsx(expr.body))) return;
     }
-    const props = fn ? propsFromFunction(source, fn) : ts.isFunctionLike(expr) ? propsFromFunction(source, expr) : [];
+    const props = fn ? propsFromFunction(source, fn) : ts3.isFunctionLike(expr) ? propsFromFunction(source, expr) : [];
     const composition = /* @__PURE__ */ new Set();
     const classNames = [];
     const visitComp = (child) => {
-      if (ts.isJsxOpeningElement(child) || ts.isJsxSelfClosingElement(child)) {
+      if (ts3.isJsxOpeningElement(child) || ts3.isJsxSelfClosingElement(child)) {
         const tag = tagName(child.tagName);
         if (isComponentName(tag)) composition.add(tag);
       }
-      ts.forEachChild(child, visitComp);
+      ts3.forEachChild(child, visitComp);
     };
-    ts.forEachChild(bodyNode, visitComp);
+    ts3.forEachChild(bodyNode, visitComp);
     components.push({
       name,
       file: input.relative,
@@ -2028,7 +2526,7 @@ function extractFileEvidence(input) {
   }
   const cvaPending = /* @__PURE__ */ new Map();
   function visit(node) {
-    if (ts.isImportDeclaration(node) && ts.isStringLiteral(node.moduleSpecifier)) {
+    if (ts3.isImportDeclaration(node) && ts3.isStringLiteral(node.moduleSpecifier)) {
       const names = [];
       const importedBindings = [];
       let defaultName;
@@ -2038,13 +2536,13 @@ function extractFileEvidence(input) {
         importedBindings.push({ local: defaultName, imported: "default" });
       }
       const bindings = clause?.namedBindings;
-      if (bindings && ts.isNamedImports(bindings)) {
+      if (bindings && ts3.isNamedImports(bindings)) {
         for (const el of bindings.elements) {
           names.push(el.name.text);
-          importedBindings.push({ local: el.name.text, imported: el.propertyName?.text ?? el.name.text });
+          importedBindings.push({ local: el.name.text, imported: el.propertyName?.text ?? el.name.text, isTypeOnly: el.isTypeOnly || void 0 });
         }
       }
-      if (bindings && ts.isNamespaceImport(bindings)) importedBindings.push({ local: bindings.name.text, imported: "*" });
+      if (bindings && ts3.isNamespaceImport(bindings)) importedBindings.push({ local: bindings.name.text, imported: "*" });
       imports.push({
         file: input.relative,
         source: node.moduleSpecifier.text,
@@ -2054,16 +2552,16 @@ function extractFileEvidence(input) {
         isTypeOnly: Boolean(clause?.isTypeOnly)
       });
     }
-    if (ts.isFunctionDeclaration(node) && node.name) {
-      const exported = Boolean(node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword));
-      maybeComponent(node.name.text, node, exported, Boolean(node.modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword)), node);
+    if (ts3.isFunctionDeclaration(node) && node.name) {
+      const exported = Boolean(node.modifiers?.some((m) => m.kind === ts3.SyntaxKind.ExportKeyword));
+      maybeComponent(node.name.text, node, exported, Boolean(node.modifiers?.some((m) => m.kind === ts3.SyntaxKind.DefaultKeyword)), node);
     }
-    if (ts.isVariableStatement(node)) {
-      const exported = Boolean(node.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword));
+    if (ts3.isVariableStatement(node)) {
+      const exported = Boolean(node.modifiers?.some((m) => m.kind === ts3.SyntaxKind.ExportKeyword));
       for (const decl of node.declarationList.declarations) {
-        if (!ts.isIdentifier(decl.name) || !decl.initializer) continue;
+        if (!ts3.isIdentifier(decl.name) || !decl.initializer) continue;
         const name = decl.name.text;
-        if (/class|classes|className/i.test(name) && (ts.isStringLiteral(decl.initializer) || ts.isNoSubstitutionTemplateLiteral(decl.initializer))) {
+        if (/class|classes|className/i.test(name) && (ts3.isStringLiteral(decl.initializer) || ts3.isNoSubstitutionTemplateLiteral(decl.initializer))) {
           exportedClassConstants.push(name);
           classes.push({
             file: input.relative,
@@ -2074,39 +2572,39 @@ function extractFileEvidence(input) {
             startLine: lineOf(source, decl)
           });
         }
-        const init = unwrap(decl.initializer);
-        if (ts.isCallExpression(decl.initializer) && callName(decl.initializer) && CVA_NAMES.has(callName(decl.initializer))) {
+        const init = unwrap2(decl.initializer);
+        if (ts3.isCallExpression(decl.initializer) && callName(decl.initializer) && CVA_NAMES.has(callName(decl.initializer))) {
           const extracted = extractCva(decl.initializer);
-          const owner = variantsOwnerName(name);
+          const owner2 = variantsOwnerName(name);
           classes.push({
             file: input.relative,
             classes: extracted.classes,
             dynamic: false,
             exported,
             kind: "cva",
-            componentName: owner,
+            componentName: owner2,
             startLine: lineOf(source, decl)
           });
-          const existing = findComponent(components, owner);
+          const existing = findComponent(components, owner2);
           if (existing) {
             existing.variants = extracted.variants;
             existing.sizes = extracted.sizes;
             existing.classNames.push(...extracted.classes);
           } else {
-            cvaPending.set(owner, extracted);
+            cvaPending.set(owner2, extracted);
           }
         }
         maybeComponent(name, init, exported, false, decl);
       }
     }
-    if (ts.isExportAssignment(node) && ts.isIdentifier(node.expression)) {
+    if (ts3.isExportAssignment(node) && ts3.isIdentifier(node.expression)) {
       const target = components.find((item) => item.name === node.expression.getText());
       if (target) {
         target.isDefault = true;
         target.exported = true;
       }
     }
-    if (ts.isCallExpression(node) && callName(node) && CVA_NAMES.has(callName(node))) {
+    if (ts3.isCallExpression(node) && callName(node) && CVA_NAMES.has(callName(node))) {
       const extracted = extractCva(node);
       classes.push({
         file: input.relative,
@@ -2117,8 +2615,8 @@ function extractFileEvidence(input) {
         startLine: lineOf(source, node)
       });
     }
-    if (ts.isJsxAttribute(node) && node.name.getText() === "className") {
-      const collected = node.initializer && ts.isJsxExpression(node.initializer) ? collectClassesFromExpr(node.initializer.expression) : node.initializer && ts.isStringLiteral(node.initializer) ? { classes: splitClasses(node.initializer.text), dynamic: false } : { classes: [], dynamic: false };
+    if (ts3.isJsxAttribute(node) && node.name.getText() === "className") {
+      const collected = node.initializer && ts3.isJsxExpression(node.initializer) ? collectClassesFromExpr(node.initializer.expression) : node.initializer && ts3.isStringLiteral(node.initializer) ? { classes: splitClasses(node.initializer.text), dynamic: false } : { classes: [], dynamic: false };
       if (collected.classes.length) {
         classes.push({
           file: input.relative,
@@ -2130,14 +2628,14 @@ function extractFileEvidence(input) {
         });
       }
     }
-    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node)) {
+    if (ts3.isJsxElement(node) || ts3.isJsxSelfClosingElement(node)) {
       const open = opening(node);
       const tag = tagName(open.tagName);
       const attrs = jsxAttributes(open.attributes);
       const classAttr = open.attributes.properties.find(
-        (prop) => ts.isJsxAttribute(prop) && prop.name.getText() === "className"
+        (prop) => ts3.isJsxAttribute(prop) && prop.name.getText() === "className"
       );
-      const collected = classAttr && ts.isJsxAttribute(classAttr) ? classAttr.initializer && ts.isJsxExpression(classAttr.initializer) ? collectClassesFromExpr(classAttr.initializer.expression) : classAttr.initializer && ts.isStringLiteral(classAttr.initializer) ? { classes: splitClasses(classAttr.initializer.text), dynamic: false } : { classes: [], dynamic: false } : { classes: [], dynamic: false };
+      const collected = classAttr && ts3.isJsxAttribute(classAttr) ? classAttr.initializer && ts3.isJsxExpression(classAttr.initializer) ? collectClassesFromExpr(classAttr.initializer.expression) : classAttr.initializer && ts3.isStringLiteral(classAttr.initializer) ? { classes: splitClasses(classAttr.initializer.text), dynamic: false } : { classes: [], dynamic: false } : { classes: [], dynamic: false };
       jsx.push({
         file: input.relative,
         tag,
@@ -2145,7 +2643,7 @@ function extractFileEvidence(input) {
         classes: collected.classes,
         attributes: attrs,
         startLine: lineOf(source, node),
-        selfClosing: ts.isJsxSelfClosingElement(node)
+        selfClosing: ts3.isJsxSelfClosingElement(node)
       });
       if (tag === "img" || tag === "Image") {
         images.push({
@@ -2168,7 +2666,7 @@ function extractFileEvidence(input) {
         });
       }
       const structural = !isComponentName(tag) && (tag === "section" || tag === "article" || tag === "header" || tag === "aside" || tag === "main" || tag === "div" && collected.classes.some((cls) => /^(flex|grid|space-y|rounded|border)/.test(cls)));
-      if (structural && ts.isJsxElement(node)) {
+      if (structural && ts3.isJsxElement(node)) {
         const tags = [];
         const comps = [];
         const families = /* @__PURE__ */ new Set();
@@ -2187,7 +2685,7 @@ function extractFileEvidence(input) {
         }
       }
     }
-    ts.forEachChild(node, visit);
+    ts3.forEachChild(node, visit);
   }
   visit(source);
   for (const [name, extracted] of cvaPending) {
@@ -2199,8 +2697,8 @@ function extractFileEvidence(input) {
     }
   }
   for (const stmt of source.statements) {
-    if (ts.isFunctionDeclaration(stmt) && stmt.name && isComponentName(stmt.name.text) && nodeReturnsJsx(stmt)) {
-      const exported = Boolean(stmt.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword));
+    if (ts3.isFunctionDeclaration(stmt) && stmt.name && isComponentName(stmt.name.text) && nodeReturnsJsx(stmt)) {
+      const exported = Boolean(stmt.modifiers?.some((m) => m.kind === ts3.SyntaxKind.ExportKeyword));
       if (!exported && /page|layout|route/i.test(input.relative)) {
         const tags = [];
         const comps = [];
@@ -2237,13 +2735,13 @@ function extractFileEvidence(input) {
 }
 function walkJsxTreeFromBody(body, tags, components, families) {
   const visit = (node) => {
-    if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) {
+    if (ts3.isJsxElement(node) || ts3.isJsxSelfClosingElement(node) || ts3.isJsxFragment(node)) {
       walkJsxTree(node, tags, components, families, 1);
       return;
     }
-    ts.forEachChild(node, visit);
+    ts3.forEachChild(node, visit);
   };
-  ts.forEachChild(body, visit);
+  ts3.forEachChild(body, visit);
 }
 var CVA_NAMES, CLASS_FNS, PASCAL;
 var init_parse = __esm({
@@ -2259,13 +2757,14 @@ var init_parse = __esm({
 
 // ../core/src/scan.ts
 import fs2 from "fs/promises";
-import path6 from "path";
+import path8 from "path";
 import fg from "fast-glob";
 import ignore from "ignore";
+import ts4 from "typescript";
 async function discoverFiles(root) {
   const ig = ignore();
   ig.add(DEFAULT_IGNORE);
-  const gitignore = await readText(path6.join(root, ".gitignore"));
+  const gitignore = await readText(path8.join(root, ".gitignore"));
   if (gitignore) ig.add(gitignore);
   const found = await fg(
     [
@@ -2291,7 +2790,7 @@ async function discoverFiles(root) {
   return found.map((file) => toPosix(file)).filter((file) => !ig.ignores(file)).sort();
 }
 async function loadPackageJson(root) {
-  const raw = await readText(path6.join(root, "package.json"));
+  const raw = await readText(path8.join(root, "package.json"));
   if (!raw) return void 0;
   try {
     return JSON.parse(raw);
@@ -2300,7 +2799,7 @@ async function loadPackageJson(root) {
   }
 }
 async function loadComponentsJson(root) {
-  const raw = await readText(path6.join(root, "components.json"));
+  const raw = await readText(path8.join(root, "components.json"));
   if (!raw) return void 0;
   try {
     return JSON.parse(raw);
@@ -2309,11 +2808,13 @@ async function loadComponentsJson(root) {
   }
 }
 async function loadTsconfigPaths(root) {
-  const raw = await readText(path6.join(root, "tsconfig.json"));
+  const raw = await readText(path8.join(root, "tsconfig.json"));
   if (!raw) return {};
   try {
-    const parsed = JSON.parse(raw);
-    return parsed.compilerOptions?.paths ?? {};
+    const parsed = ts4.parseConfigFileTextToJson("tsconfig.json", raw).config;
+    const paths = parsed?.compilerOptions?.paths;
+    if (!paths || typeof paths !== "object" || Array.isArray(paths)) return {};
+    return Object.fromEntries(Object.entries(paths).filter((entry) => Array.isArray(entry[1]) && entry[1].every((value) => typeof value === "string")));
   } catch {
     return {};
   }
@@ -2329,9 +2830,9 @@ async function collectEvidence(root, options = {}) {
   const files = [];
   const excluded = ignore().add(DEFAULT_IGNORE);
   for (const relative of relativeFiles) {
-    const abs = path6.join(root, relative);
-    const fromRoot = path6.relative(path6.resolve(root), path6.resolve(abs));
-    if (fromRoot === ".." || fromRoot.startsWith(`..${path6.sep}`) || path6.isAbsolute(fromRoot)) {
+    const abs = path8.join(root, relative);
+    const fromRoot = path8.relative(path8.resolve(root), path8.resolve(abs));
+    if (fromRoot === ".." || fromRoot.startsWith(`..${path8.sep}`) || path8.isAbsolute(fromRoot)) {
       throw new Error(`Source path is outside the repository: ${relative}`);
     }
     if (excluded.ignores(relative)) continue;
@@ -2346,7 +2847,7 @@ async function collectEvidence(root, options = {}) {
       content = content.replace(/<!-- design-rover:start -->[\s\S]*?<!-- design-rover:end -->/g, (block) => "\n".repeat(block.split("\n").length - 1));
       if (!content.trim()) continue;
     }
-    const ext = path6.extname(relative);
+    const ext = path8.extname(relative);
     const kind = SCRIPT_EXT.has(ext) ? "script" : STYLE_EXT.has(ext) || relative.endsWith(".module.css") ? "style" : relative.endsWith(".json") || relative.endsWith(".md") || relative.endsWith(".mdc") ? "json" : "other";
     const normalizedKind = kind === "script" || kind === "style" ? kind : "other";
     const hash = sha256(content);
@@ -2404,12 +2905,12 @@ var init_scan = __esm({
 });
 
 // ../core/src/cache.ts
-import path7 from "path";
+import path9 from "path";
 import fs3 from "fs/promises";
 import { randomUUID } from "crypto";
 import { z as z2 } from "zod";
 async function loadCache(root) {
-  const file = path7.join(specPaths(root).cache, "evidence.json");
+  const file = path9.join(specPaths(root).cache, "evidence.json");
   const raw = await readText(file);
   if (!raw) return void 0;
   try {
@@ -2417,7 +2918,7 @@ async function loadCache(root) {
     if (!parsed.success) return void 0;
     const paths = parsed.data.files.map((item) => item.relative);
     if (new Set(paths).size !== paths.length) return void 0;
-    if (paths.some((relative) => path7.isAbsolute(relative) || relative.split(/[\\/]/).includes(".."))) return void 0;
+    if (paths.some((relative) => path9.isAbsolute(relative) || relative.split(/[\\/]/).includes(".."))) return void 0;
     if (parsed.data.files.some((item) => item.hash !== sha256(item.content))) return void 0;
     if (parsed.data.hash !== sha256(parsed.data.files.map((item) => `${item.relative}\0${item.hash}`).join("\0"))) return void 0;
     return parsed.data;
@@ -2427,9 +2928,9 @@ async function loadCache(root) {
 }
 async function saveCache(root, cache) {
   const directory = specPaths(root).cache;
-  const file = path7.join(directory, "evidence.json");
+  const file = path9.join(directory, "evidence.json");
   await fs3.mkdir(directory, { recursive: true });
-  const temporary = path7.join(directory, `evidence-${randomUUID()}.tmp`);
+  const temporary = path9.join(directory, `evidence-${randomUUID()}.tmp`);
   try {
     await fs3.writeFile(temporary, `${JSON.stringify(cache)}
 `, "utf8");
@@ -2476,7 +2977,7 @@ var init_cache = __esm({
       cssVariables: z2.array(z2.object({ name: z2.string(), value: z2.string(), line: z2.number().int().optional(), scope: z2.string().optional(), mode: z2.string().optional(), important: z2.boolean().optional() }).passthrough()),
       exportedClassConstants: strings
     }).passthrough();
-    cacheSchema = z2.object({ version: z2.literal(3), hash: z2.string(), files: z2.array(evidenceSchema) });
+    cacheSchema = z2.object({ version: z2.literal(4), hash: z2.string(), files: z2.array(evidenceSchema) });
   }
 });
 
@@ -2521,7 +3022,7 @@ async function analyzeRepository(root, options = {}) {
     documentation: framework.documentation
   };
   const nextCache = {
-    version: 3,
+    version: 4,
     hash: sha256(merged.files.map((file) => `${file.relative}\0${file.hash}`).join("\0")),
     files: merged.files
   };
@@ -2548,7 +3049,7 @@ var init_analyze = __esm({
 });
 
 // ../core/src/context.ts
-import path8 from "path";
+import path10 from "path";
 function renderContext(model, options = {}) {
   const directory = options.directory ?? SPEC_DIR;
   const body = [
@@ -2556,7 +3057,7 @@ function renderContext(model, options = {}) {
     "",
     "Before changing UI:",
     "1. Run `design-rover status --json` to inspect freshness and pending review.",
-    "2. Use `design-rover query <name> --json` to find components, tokens, conventions and exceptions. Use `design-rover explain <id>` for details and source locations.",
+    "2. Use `design-rover context <task> --path <file-or-directory> --json` for bounded, relevant components, tokens and approved decisions. Inspect coverage and omission warnings; raise --max-chars or narrow the request when approved decisions are omitted. Use `design-rover query <id> --json` for whole records or `design-rover explain <id>` for readable details and source locations.",
     "3. Read the relevant implementation before using its imports, props and variants. A component name can exist in several packages; choose by ID and source.",
     "4. Use approved conventions and exceptions in their documented scope. Observed code is evidence; inferred or suggested entries need review before becoming policy.",
     "5. Match the relevant token scope and theme. Missing or unresolved information is not permission to invent an API or claim a rule was checked.",
@@ -2651,7 +3152,7 @@ async function writeGenerated(root, model, options = {}) {
   const writes = [];
   for (const entry of entries) {
     if (options.writeRepoFiles === false && !entry.rel.startsWith(`${directory}/generated/`)) continue;
-    const current = await readText(path8.join(root, entry.rel));
+    const current = await readText(path10.join(root, entry.rel));
     if (entry.wrap) {
       writes.push({ rel: entry.rel, content: wrapManaged(current, entry.content) });
       continue;
@@ -2664,10 +3165,10 @@ async function writeGenerated(root, model, options = {}) {
   }
   const files = [];
   for (const write of writes) {
-    if (!options.dryRun) await writeText(path8.join(root, write.rel), write.content);
+    if (!options.dryRun) await writeText(path10.join(root, write.rel), write.content);
     files.push({ path: write.rel, hash: sha256(write.content), managed: true });
   }
-  if (!options.dryRun) await writeText(path8.join(specPaths(root).generated, "projections.json"), `${JSON.stringify({ files }, null, 2)}
+  if (!options.dryRun) await writeText(path10.join(specPaths(root).generated, "projections.json"), `${JSON.stringify({ files }, null, 2)}
 `);
   return { ...rendered, files };
 }
@@ -2681,7 +3182,7 @@ async function generatedHashes(root, model) {
       stale.push(entry.rel);
       continue;
     }
-    const current = await readText(path8.join(root, entry.rel));
+    const current = await readText(path10.join(root, entry.rel));
     if (current === void 0) {
       stale.push(entry.rel);
       continue;
@@ -2732,7 +3233,8 @@ function componentSig(record) {
     })).sort((a, b) => a.name.localeCompare(b.name)),
     source: record.source,
     importPath: record.importPath,
-    exportName: record.exportName
+    exportName: record.exportName,
+    propsResolution: record.propsResolution
   };
 }
 function tokenSig(record) {
@@ -3197,6 +3699,221 @@ var init_check = __esm({
   }
 });
 
+// ../core/src/retrieval.ts
+import path11 from "path";
+import ignore3 from "ignore";
+function normalizePath(value) {
+  const input = value.trim().replace(/\\/g, "/");
+  if (!input || input.length > 512 || input.includes("\0") || input.startsWith("/") || /^[a-z]:/i.test(input)) throw new Error("Context path must be a repository-relative file or directory (at most 512 characters).");
+  const normalized = path11.posix.normalize(input).replace(/\/$/, "");
+  if (normalized === ".." || normalized.startsWith("../")) throw new Error("Context path cannot leave the repository.");
+  return normalized;
+}
+function owner(file) {
+  const parts = file.split("/");
+  return (parts[0] === "apps" || parts[0] === "packages") && parts[1] ? `${parts[0]}/${parts[1]}` : void 0;
+}
+function under(file, selected) {
+  return selected === "." || file === selected || file.startsWith(`${selected}/`);
+}
+function sourceFiles(record) {
+  const files = record.evidence.flatMap((item) => item.location?.file ? [item.location.file] : []);
+  if ("source" in record) files.push(record.source);
+  if ("origin" in record) files.push(record.origin);
+  if ("occurrences" in record) files.push(...record.occurrences.map((item) => item.file));
+  if ("sourceRefs" in record) files.push(...record.sourceRefs.flatMap((item) => item.location?.file ? [item.location.file] : []));
+  return [...new Set(files.map((file) => file.replace(/\\/g, "/")).filter(Boolean))].sort(compare);
+}
+function lexicalScore(record, query, words) {
+  const name = "name" in record ? record.name : record.subject;
+  if (query.toLowerCase() === record.id.toLowerCase()) return 300;
+  const title = normalizeText(`${record.id} ${name}`);
+  const text = normalizeText(JSON.stringify(record));
+  let score = query.toLowerCase() === name.toLowerCase() ? 150 : 0;
+  for (const word of words) {
+    if (title.includes(word)) score += 20;
+    else if (text.includes(word)) score += 4;
+  }
+  return score;
+}
+function approvedDecision(match) {
+  return match.record.status === "approved" && match.kind !== "component" && match.kind !== "token";
+}
+function visible(kind, record, includePending) {
+  return record.status === "approved" || kind !== "exception" && record.status === "observed" || Boolean(includePending && (record.status === "inferred" || record.status === "suggested"));
+}
+function pathScopeMatches(patterns, selected, allowDescendants = true) {
+  if (selected === ".") return "potential";
+  const result = ignore3().add(patterns).test(selected);
+  if (result.ignored) return "direct";
+  if (result.unignored) return void 0;
+  if (allowDescendants && patterns.some((pattern) => {
+    if (pattern.startsWith("!")) return false;
+    const rawPrefix = pattern.replace(/^\//, "").split(/[?*\[]/, 1)[0];
+    const prefix = rawPrefix.replace(/\/$/, "");
+    return !prefix || under(prefix, selected) || under(selected, prefix) || !rawPrefix.endsWith("/") && selected.startsWith(rawPrefix);
+  })) return "potential";
+  return void 0;
+}
+function retrieveContext(model, options = {}) {
+  const query = options.query?.trim() ?? "";
+  if (query.length > 512) throw new Error("Context query must be at most 512 characters.");
+  const selected = options.path === void 0 ? void 0 : normalizePath(options.path);
+  if (!query && selected === void 0) throw new Error("Provide a context query or a repository-relative path.");
+  const limit = options.limit ?? 20;
+  const maxChars = options.maxChars ?? 12e3;
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) throw new Error("Context limit must be an integer from 1 to 100.");
+  if (!Number.isInteger(maxChars) || maxChars < 1024 || maxChars > 1e5) throw new Error("Context maxChars must be an integer from 1024 to 100000.");
+  const includePending = options.includePending ?? false;
+  const words = [...new Set(lexicalWords(query))].slice(0, 32);
+  const matches = [];
+  const relevantComponents = /* @__PURE__ */ new Set();
+  const relevantPaths = /* @__PURE__ */ new Set();
+  const relevantOwners = /* @__PURE__ */ new Set();
+  const relevantComponentSources = /* @__PURE__ */ new Set();
+  const tokenNames = /* @__PURE__ */ new Set();
+  function relevance(kind, record) {
+    if (!visible(kind, record, includePending)) return void 0;
+    const files = sourceFiles(record);
+    const lexical = query ? lexicalScore(record, query, words) : 0;
+    let pathScore = selected !== void 0 && files.some((file) => under(file, selected)) ? 100 : 0;
+    const reasons = [];
+    if (kind === "component" && selected !== void 0 && "usage" in record && record.usage.some((item) => under(item.file, selected))) {
+      pathScore = Math.max(pathScore, 120);
+      reasons.push("used-in-path");
+    }
+    const connected = kind === "token" && "origin" in record && (tokenNames.has(record.id) || tokenNames.has(record.name) && (owner(record.origin) === void 0 || relevantOwners.has(owner(record.origin)) || selected !== void 0 && owner(record.origin) === owner(selected)));
+    if (connected) {
+      pathScore = Math.max(pathScore, 80);
+      reasons.push("component-token");
+    }
+    const globalDecision = (kind === "convention" || kind === "pattern" || kind === "intent") && !files.length;
+    if (kind !== "component" && kind !== "token" && files.some((file) => relevantComponentSources.has(file))) {
+      pathScore = Math.max(pathScore, 110);
+      reasons.push("component-source-decision");
+    }
+    let applicable = false;
+    if (kind === "exception" && "scope" in record && typeof record.scope === "object") {
+      const scope = record.scope;
+      const componentsMatch = !scope.components.length || scope.components.some((item) => relevantComponents.has(item));
+      let pathsMatch;
+      let potentialScope = false;
+      try {
+        const matched = selected !== void 0 ? pathScopeMatches(scope.paths, selected) : [...relevantPaths].map((file) => pathScopeMatches(scope.paths, file, false)).find(Boolean);
+        pathsMatch = !scope.paths.length || Boolean(matched);
+        potentialScope = scope.paths.length > 0 && matched === "potential";
+      } catch (error) {
+        throw new Error(`Cannot safely resolve exception scope ${record.id}: ${String(error)}`);
+      }
+      const pathRelevant = scope.paths.length > 0 && pathsMatch;
+      applicable = Boolean((scope.paths.length || scope.components.length) && componentsMatch && pathsMatch);
+      if (selected !== void 0 && !applicable && !pathRelevant) return void 0;
+      if (applicable || pathRelevant) {
+        pathScore = Math.max(pathScore, 140);
+        reasons.push(potentialScope ? "path-exception-may-apply" : applicable ? "applicable-exception" : "path-exception-component-scope-unresolved");
+      }
+    }
+    if (selected !== void 0) {
+      const selectedOwner = owner(selected);
+      const foreign = files.length > 0 && files.every((file) => owner(file) !== void 0 && owner(file) !== selectedOwner);
+      if (foreign && !pathScore && !applicable) return void 0;
+      if (files.length && !pathScore && lexical < 20 && !globalDecision && !applicable) return void 0;
+    }
+    if (!lexical && !pathScore && !globalDecision) return void 0;
+    if (lexical) reasons.push("query-match");
+    if (pathScore && !reasons.length) reasons.push("source-in-path");
+    if (globalDecision) reasons.push("repository-decision");
+    const name = "name" in record ? record.name : record.subject;
+    const explicitMatch = query.toLowerCase() === record.id.toLowerCase() || query.toLowerCase() === name.toLowerCase();
+    const nameWords = lexicalWords(name);
+    const requestedComponent = kind === "component" && nameWords.length > 0 && nameWords.every((word) => words.includes(word));
+    const requestBoost = explicitMatch ? 3e3 : requestedComponent ? 2e3 : 0;
+    if (requestBoost) reasons.push("requested-record");
+    const decisionBoost = record.status === "approved" && kind !== "component" && kind !== "token" ? 1e3 : 0;
+    return { kind, score: requestBoost + decisionBoost + pathScore + lexical, reasons, sourceRefs: files, record };
+  }
+  for (const component of model.components) {
+    const match = relevance("component", component);
+    if (!match) continue;
+    matches.push(match);
+    relevantComponents.add(component.id);
+    relevantComponents.add(component.name);
+    relevantPaths.add(component.source);
+    relevantOwners.add(owner(component.source));
+    relevantComponentSources.add(component.source);
+    for (const usage of component.usage) relevantPaths.add(usage.file);
+    for (const token of component.relatedTokens) tokenNames.add(token);
+  }
+  const collections = { token: model.tokens, pattern: model.patterns, convention: model.conventions, intent: model.intents, exception: model.exceptions };
+  for (const kind of ["token", "pattern", "convention", "intent", "exception"]) {
+    for (const record of collections[kind]) {
+      const match = relevance(kind, record);
+      if (match) matches.push(match);
+    }
+  }
+  matches.sort((left, right) => right.score - left.score || compare(left.kind, right.kind) || compare(left.record.id, right.record.id));
+  const decisionCount = matches.filter(approvedDecision).length;
+  function packet(items, omittedByBudget2, omittedByLimit2) {
+    const returnedDecisions = items.filter(approvedDecision).length;
+    const omittedDecisions = decisionCount - returnedDecisions;
+    const result2 = {
+      version: 1,
+      repository: model.system.repository.name,
+      scope: { query: query || null, path: selected ?? null, includePending },
+      limits: { limit, maxChars, outputChars: 0, unit: "UTF-16 code units including JSON formatting and final newline" },
+      freshness: { checked: false, canonicalUpdatedAt: model.system.updatedAt, lastAnalyzedAt: model.system.lastAnalyzedAt ?? null, recordedSyncStatus: model.system.syncStatus },
+      coverage: { matched: matches.length, returned: items.length, complete: items.length === matches.length, omittedByLimit: omittedByLimit2, omittedByBudget: omittedByBudget2, approvedDecisions: { matched: decisionCount, returned: returnedDecisions, omitted: omittedDecisions } },
+      warnings: ["Canonical snapshot only; run status to check source freshness."],
+      matches: items
+    };
+    if (omittedDecisions) result2.warnings.push("Applicable approved decisions were omitted. Retrieve them before treating this context as complete.");
+    if (items.length < matches.length) result2.warnings.push("Whole records were omitted by the stated limits; raise the bounds or narrow the query/path. No record was sliced.");
+    if (items.some((item) => item.reasons.some((reason) => reason === "path-exception-may-apply" || reason === "path-exception-component-scope-unresolved"))) result2.warnings.push("Some exception scopes may apply to descendants or unresolved components. Inspect their recorded scope before applying them.");
+    for (let pass = 0; pass < 4; pass += 1) {
+      const length = serializeContext(result2).length;
+      if (length === result2.limits.outputChars) break;
+      result2.limits.outputChars = length;
+    }
+    return result2;
+  }
+  const selectedMatches = [];
+  let omittedByBudget = 0;
+  let omittedByLimit = 0;
+  if (serializeContext(packet([], matches.length, 0)).length > maxChars) throw new Error("Context metadata exceeds maxChars. Increase the bound or shorten the query/path.");
+  for (const match of matches) {
+    if (selectedMatches.length >= limit) {
+      omittedByLimit += 1;
+      continue;
+    }
+    const candidate = packet([...selectedMatches, match], omittedByBudget, matches.length - selectedMatches.length - 1 - omittedByBudget);
+    if (serializeContext(candidate).length <= maxChars) selectedMatches.push(match);
+    else omittedByBudget += 1;
+  }
+  let result = packet(selectedMatches, omittedByBudget, omittedByLimit);
+  while (serializeContext(result).length > maxChars && selectedMatches.length) {
+    selectedMatches.pop();
+    omittedByBudget += 1;
+    result = packet(selectedMatches, omittedByBudget, omittedByLimit);
+  }
+  if (serializeContext(result).length > maxChars) throw new Error("Context metadata exceeds maxChars. Increase the bound.");
+  return result;
+}
+function serializeContext(packet) {
+  return `${JSON.stringify(packet, null, 2)}
+`;
+}
+var STOP_WORDS, normalizeText, lexicalWords, compare;
+var init_retrieval = __esm({
+  "../core/src/retrieval.ts"() {
+    "use strict";
+    init_esm_shims();
+    STOP_WORDS = /* @__PURE__ */ new Set(["a", "an", "the", "to", "for", "with", "on", "in", "and", "or", "of", "this", "that", "please", "build", "create", "edit", "update", "change", "add", "implement", "make", "use", "using"]);
+    normalizeText = (value) => value.replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+    lexicalWords = (value) => normalizeText(value).split(/[^a-z0-9_-]+/).filter((word) => word && !STOP_WORDS.has(word));
+    compare = (left, right) => left < right ? -1 : left > right ? 1 : 0;
+  }
+});
+
 // ../core/src/explain.ts
 function explain(model, query) {
   const q = query.trim().toLowerCase();
@@ -3221,6 +3938,8 @@ ${componentMatches.map((item) => `${item.id} \u2014 ${item.source}`).join("\n")}
       `Variants: ${component.variants.join(", ") || "none"}`,
       `Sizes: ${component.sizes.join(", ") || "none"}`,
       `Props: ${component.props.map((prop) => `${prop.name}${prop.required ? "" : "?"}: ${prop.type ?? "unresolved"}${prop.defaultValue ? ` = ${prop.defaultValue}` : ""}`).join(", ") || "none"}`,
+      `Props resolution: ${component.propsResolution?.status ?? "not recorded"}`,
+      ...component.propsResolution?.issues.map((issue) => `  ${issue}`) ?? [],
       `Architecture: ${component.architecture}`,
       `Usage: ${component.usage.reduce((sum, item) => sum + item.count, 0)} call sites in ${component.usage.length} files`,
       `Status: ${component.status}`
@@ -3310,11 +4029,11 @@ var init_explain = __esm({
 
 // ../core/src/store.ts
 import fs4 from "fs/promises";
-import path9 from "path";
+import path12 from "path";
 async function listJsonFiles2(dir) {
   try {
     const entries = await fs4.readdir(dir, { withFileTypes: true });
-    return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => path9.join(dir, entry.name)).sort();
+    return entries.filter((entry) => entry.isFile() && entry.name.endsWith(".json")).map((entry) => path12.join(dir, entry.name)).sort();
   } catch (error) {
     if (error.code === "ENOENT") return [];
     throw new Error(`Cannot read canonical directory ${dir}: ${String(error)}`);
@@ -3394,7 +4113,7 @@ async function isInitialized(root) {
 }
 async function loadCanonicalUnlocked(root) {
   const paths = specPaths(root);
-  const recoveryMarker = path9.join(paths.dir, ".recovery-required.json");
+  const recoveryMarker = path12.join(paths.dir, ".recovery-required.json");
   if (await pathExists(recoveryMarker)) throw new Error(`Canonical storage needs recovery. Inspect ${recoveryMarker} before continuing.`);
   if (!await pathExists(paths.system)) return void 0;
   const system = await readJsonStrict(paths.system, void 0);
@@ -3423,7 +4142,7 @@ async function loadCanonicalUnlocked(root) {
 async function loadCanonical(root) {
   const paths = specPaths(root);
   if (!await pathExists(paths.dir)) return void 0;
-  const lockFile = path9.join(paths.dir, ".write.lock");
+  const lockFile = path12.join(paths.dir, ".write.lock");
   let lock;
   try {
     lock = await fs4.open(lockFile, "wx");
@@ -3444,7 +4163,7 @@ async function saveCanonical(root, model) {
   model = validateCanonical(model);
   const paths = specPaths(root);
   await fs4.mkdir(paths.dir, { recursive: true });
-  const lockFile = path9.join(paths.dir, ".write.lock");
+  const lockFile = path12.join(paths.dir, ".write.lock");
   let lock;
   try {
     lock = await fs4.open(lockFile, "wx");
@@ -3476,9 +4195,9 @@ async function saveCanonical(root, model) {
       [paths.intents, model.intents],
       [paths.exceptions, model.exceptions]
     ]) {
-      const keep = new Set(records.map((record) => path9.join(dir, recordFileName(record.id))));
+      const keep = new Set(records.map((record) => path12.join(dir, recordFileName(record.id))));
       for (const file of await listJsonFiles2(dir)) if (!keep.has(file)) obsolete.push(file);
-      for (const record of records) writes.set(path9.join(dir, recordFileName(record.id)), stableStringify(record));
+      for (const record of records) writes.set(path12.join(dir, recordFileName(record.id)), stableStringify(record));
     }
     let currentIgnore = "";
     try {
@@ -3505,16 +4224,16 @@ async function saveCanonical(root, model) {
     }
     writes.set(paths.historyLog, history2.map((event) => JSON.stringify(event)).join("\n") + (history2.length ? "\n" : ""));
     writes.set(paths.system, stableStringify(model.system));
-    staging = await fs4.mkdtemp(path9.join(paths.dir, ".write-"));
+    staging = await fs4.mkdtemp(path12.join(paths.dir, ".write-"));
     const staged = [];
     for (const [destination, content] of writes) {
-      const temporary = path9.join(staging, `new-${staged.length}`);
+      const temporary = path12.join(staging, `new-${staged.length}`);
       await fs4.writeFile(temporary, content, "utf8");
       staged.push([temporary, destination]);
     }
     const recovery = [];
     for (const destination of /* @__PURE__ */ new Set([...writes.keys(), ...obsolete])) {
-      const backup = path9.join(staging, `old-${recovery.length}`);
+      const backup = path12.join(staging, `old-${recovery.length}`);
       try {
         await fs4.copyFile(destination, backup);
         recovery.push({ destination, backup });
@@ -3523,13 +4242,13 @@ async function saveCanonical(root, model) {
         recovery.push({ destination, backup: null });
       }
     }
-    await fs4.writeFile(path9.join(staging, "recovery.json"), JSON.stringify({
+    await fs4.writeFile(path12.join(staging, "recovery.json"), JSON.stringify({
       canonicalDirectory: paths.dir,
-      files: recovery.map((item) => ({ path: path9.relative(paths.dir, item.destination), backup: item.backup ? path9.basename(item.backup) : null }))
+      files: recovery.map((item) => ({ path: path12.relative(paths.dir, item.destination), backup: item.backup ? path12.basename(item.backup) : null }))
     }, null, 2));
     try {
       for (const [temporary, destination] of staged) {
-        await fs4.mkdir(path9.dirname(destination), { recursive: true });
+        await fs4.mkdir(path12.dirname(destination), { recursive: true });
         await fs4.rename(temporary, destination);
       }
       for (const file of obsolete) await fs4.rm(file);
@@ -3540,9 +4259,9 @@ async function saveCanonical(root, model) {
         try {
           if (item.backup === null) await fs4.rm(item.destination, { force: true });
           else {
-            const temporary = path9.join(staging, `restore-${index}`);
+            const temporary = path12.join(staging, `restore-${index}`);
             await fs4.copyFile(item.backup, temporary);
-            await fs4.mkdir(path9.dirname(item.destination), { recursive: true });
+            await fs4.mkdir(path12.dirname(item.destination), { recursive: true });
             await fs4.rename(temporary, item.destination);
           }
         } catch (rollbackError) {
@@ -3551,8 +4270,8 @@ async function saveCanonical(root, model) {
       }
       if (failures.length) {
         retainRecovery = true;
-        const marker = path9.join(paths.dir, ".recovery-required.json");
-        await fs4.writeFile(marker, JSON.stringify({ backup: staging, manifest: path9.join(staging, "recovery.json") }, null, 2));
+        const marker = path12.join(paths.dir, ".recovery-required.json");
+        await fs4.writeFile(marker, JSON.stringify({ backup: staging, manifest: path12.join(staging, "recovery.json") }, null, 2));
         throw new AggregateError([error, ...failures], `Canonical save and rollback failed. Retained recovery backup at ${staging}; inspect ${marker}.`);
       }
       throw error;
@@ -3564,12 +4283,12 @@ async function saveCanonical(root, model) {
   }
 }
 function emptyCanonical(root, name) {
-  const ts2 = nowIso();
+  const ts5 = nowIso();
   return {
     system: {
       version: 1,
-      createdAt: ts2,
-      updatedAt: ts2,
+      createdAt: ts5,
+      updatedAt: ts5,
       repository: { name, root },
       framework: { name: "unknown" },
       styling: { systems: [] },
@@ -3609,7 +4328,7 @@ var init_store = __esm({
 });
 
 // ../core/src/integrations-local.ts
-import path10 from "path";
+import path13 from "path";
 import fs5 from "fs/promises";
 import { execFile as execFile2 } from "child_process";
 import { promisify as promisify2 } from "util";
@@ -3651,7 +4370,7 @@ async function installGitHook(root) {
   } catch {
     throw new Error("Cannot install a Git hook outside a Git repository.");
   }
-  const dest = path10.resolve(root, hooksPath);
+  const dest = path13.resolve(root, hooksPath);
   const existing = await fs5.readFile(dest, "utf8").catch((error) => {
     if (error.code === "ENOENT") return void 0;
     throw error;
@@ -3667,7 +4386,7 @@ async function installGitHook(root) {
       if (error.code !== "ENOENT") throw error;
     }
   }
-  await fs5.mkdir(path10.dirname(dest), { recursive: true });
+  await fs5.mkdir(path13.dirname(dest), { recursive: true });
   const temporary = `${dest}.${randomUUID2()}.tmp`;
   let moved = false;
   try {
@@ -3714,7 +4433,7 @@ jobs:
 }
 async function installGithubWorkflow(root) {
   const { writeText: writeText2 } = await Promise.resolve().then(() => (init_fs(), fs_exports));
-  const current = path10.join(root, ".github/workflows/design-rover.yml");
+  const current = path13.join(root, ".github/workflows/design-rover.yml");
   const read = async (file) => fs5.readFile(file, "utf8").catch((error) => {
     if (error.code === "ENOENT") return void 0;
     throw error;
@@ -3905,9 +4624,9 @@ var init_sync = __esm({
 });
 
 // ../core/src/engine.ts
-import path11 from "path";
+import path14 from "path";
 function repoName(root) {
-  return path11.basename(root);
+  return path14.basename(root);
 }
 async function createEngine(root) {
   const initialized = await isInitialized(root);
@@ -4050,6 +4769,11 @@ async function createEngine(root) {
       if (!model) return void 0;
       return searchModel(model, query);
     },
+    context: async (options = {}) => {
+      const model = await loadCanonical(root);
+      if (!model) throw new Error("Design Rover is not initialized. Run `design-rover init` before retrieving context.");
+      return retrieveContext(model, options);
+    },
     history: () => history(root),
     checkSnippet: async (code, fileName) => {
       const model = await loadCanonical(root);
@@ -4071,6 +4795,7 @@ var init_engine = __esm({
     "use strict";
     init_esm_shims();
     init_src();
+    init_retrieval();
     init_analyze();
     init_check();
     init_usage_check();
@@ -4111,9 +4836,11 @@ __export(src_exports, {
   pathExists: () => pathExists,
   readText: () => readText,
   renderContext: () => renderContext,
+  retrieveContext: () => retrieveContext,
   saveCanonical: () => saveCanonical,
   searchModel: () => searchModel,
   seedCanonical: () => seedCanonical,
+  serializeContext: () => serializeContext,
   specDir: () => specDir,
   specPaths: () => specPaths,
   usageDiagnostics: () => usageDiagnostics,
@@ -4127,6 +4854,7 @@ var init_src2 = __esm({
     init_analyze();
     init_check();
     init_context();
+    init_retrieval();
     init_diff();
     init_engine();
     init_explain();
@@ -4213,7 +4941,7 @@ async function createMcpServer(root) {
     async ({ includePending }) => {
       const model = await requireModel();
       return {
-        content: [{ type: "text", text: JSON.stringify(model.conventions.filter((item) => visible(item, includePending)), null, 2) }]
+        content: [{ type: "text", text: JSON.stringify(model.conventions.filter((item) => visible2(item, includePending)), null, 2) }]
       };
     }
   );
@@ -4224,7 +4952,7 @@ async function createMcpServer(root) {
     async ({ includePending }) => {
       const model = await requireModel();
       return {
-        content: [{ type: "text", text: JSON.stringify(model.intents.filter((item) => visible(item, includePending)), null, 2) }]
+        content: [{ type: "text", text: JSON.stringify(model.intents.filter((item) => visible2(item, includePending)), null, 2) }]
       };
     }
   );
@@ -4246,7 +4974,7 @@ async function createMcpServer(root) {
     async ({ query, includePending }) => {
       await requireModel();
       const result = await engine.search(query);
-      const filtered = Object.fromEntries(Object.entries(result ?? {}).map(([kind, records]) => [kind, records.filter((item) => visible(item, includePending))]));
+      const filtered = Object.fromEntries(Object.entries(result ?? {}).map(([kind, records]) => [kind, records.filter((item) => visible2(item, includePending))]));
       return {
         content: [{ type: "text", text: JSON.stringify(filtered, null, 2) }]
       };
@@ -4264,6 +4992,25 @@ async function createMcpServer(root) {
       };
     }
   );
+  server.registerTool(
+    "get_context",
+    {
+      description: "Retrieve bounded canonical design context for a task/query and/or repository-relative path. Whole records are ranked deterministically; inspect coverage and omission warnings before relying on it. Does not scan source or check freshness.",
+      inputSchema: {
+        query: z3.string().max(512).optional(),
+        path: z3.string().max(512).optional(),
+        includePending: z3.boolean().optional(),
+        limit: z3.number().int().min(1).max(100).optional(),
+        maxChars: z3.number().int().min(1024).max(1e5).optional()
+      },
+      annotations: { readOnlyHint: true }
+    },
+    async (options) => {
+      const model = await requireModel();
+      const packet = retrieveContext(model, options);
+      return { content: [{ type: "text", text: serializeContext(packet) }] };
+    }
+  );
   server.tool(
     "explain_violation",
     "Explain a component, pattern, convention, or diagnostic in context.",
@@ -4279,7 +5026,7 @@ async function createMcpServer(root) {
 function trusted(item) {
   return item.status === "approved" || item.status === "observed";
 }
-function visible(item, includePending) {
+function visible2(item, includePending) {
   return trusted(item) || Boolean(includePending && (item.status === "inferred" || item.status === "suggested"));
 }
 function approvedModel(model) {
@@ -4312,7 +5059,7 @@ init_esm_shims();
 init_src2();
 init_src();
 import { parseArgs } from "util";
-import path12 from "path";
+import path15 from "path";
 
 // ../integrations/src/index.ts
 init_esm_shims();
@@ -4762,6 +5509,7 @@ Usage
   design-rover diff            Show canonical system changes
   design-rover explain <name>  Explain a component, pattern, convention, or intent
   design-rover query <q>       Search the canonical model
+  design-rover context [task]  Retrieve bounded design context for a task and/or path
   design-rover generate        Write AGENTS.md / CLAUDE.md / Cursor rules / skill
   design-rover history         Show how the canonical system changed
   design-rover baseline        Capture current findings as existing debt
@@ -4783,6 +5531,10 @@ Options
   --version       Print the CLI version
   --cwd <path>    Repository root
   --base <ref>    Git base for incremental / PR / CI
+  --path <path>   Context: repository-relative file or directory
+  --limit <n>     Context: maximum whole records (default 20, maximum 100)
+  --max-chars <n> Context: maximum formatted JSON characters (default 12000)
+  --include-pending  Context: include inferences and suggestions for review
   --fail-on <level>   CI: error (default) | warning | none
 `;
 async function main() {
@@ -4796,6 +5548,10 @@ async function main() {
       version: { type: "boolean", short: "v", default: false },
       cwd: { type: "string" },
       base: { type: "string" },
+      path: { type: "string" },
+      limit: { type: "string" },
+      "max-chars": { type: "string" },
+      "include-pending": { type: "boolean", default: false },
       "fail-on": { type: "string", default: "error" },
       approve: { type: "boolean", default: false },
       generate: { type: "boolean", default: false },
@@ -4814,7 +5570,7 @@ async function main() {
 `);
     return;
   }
-  const root = path12.resolve(parsed.values.cwd ?? process.cwd());
+  const root = path15.resolve(parsed.values.cwd ?? process.cwd());
   const command = parsed.positionals[0] ?? "status";
   const rest = parsed.positionals.slice(1);
   const engine = await createEngine(root);
@@ -4830,7 +5586,7 @@ async function main() {
       generate: Boolean(parsed.values.generate)
     });
     printInitSummary({
-      directory: path12.relative(root, engine.specDir),
+      directory: path15.relative(root, engine.specDir),
       framework: result.snapshot.framework.name,
       styling: result.snapshot.styling.systems,
       counts: {
@@ -4953,6 +5709,17 @@ async function main() {
     }
     return;
   }
+  if (command === "context") {
+    const packet = await engine.context({
+      query: rest.join(" ") || void 0,
+      path: parsed.values.path,
+      includePending: Boolean(parsed.values["include-pending"]),
+      limit: parsed.values.limit === void 0 ? void 0 : Number(parsed.values.limit),
+      maxChars: parsed.values["max-chars"] === void 0 ? void 0 : Number(parsed.values["max-chars"])
+    });
+    process.stdout.write(serializeContext(packet));
+    return;
+  }
   if (command === "query") {
     const query = rest.join(" ");
     if (!query) fail("Usage: design-rover query <text>");
@@ -5131,7 +5898,7 @@ async function main() {
     const mapping = mapShadcnLint(model);
     if (rest[0] === "install") {
       const { writeText: writeText2 } = await Promise.resolve().then(() => (init_src2(), src_exports));
-      const dest = path12.join(engine.specDir, "generated/oxlintrc.shadcn.json");
+      const dest = path15.join(engine.specDir, "generated/oxlintrc.shadcn.json");
       await writeText2(dest, oxlintFromMap(mapping));
       header();
       line(`  Wrote ${dest}`);