@reqvire-org/ads 0.3.2 → 0.3.5

package/dist/mcp/server.mjs

@@ -1,10 +1,11 @@
 import { existsSync, readFileSync, statSync } from "node:fs";
 import path from "node:path";
 import { Server, ProtocolError, INVALID_PARAMS, ResourceNotFoundError } from "@modelcontextprotocol/server";
-import { serveStdio } from "@modelcontextprotocol/server/stdio";
+import { serveStdio, StdioServerTransport } from "@modelcontextprotocol/server/stdio";
 import { z } from "zod";
 import { checkProject } from "../check.mjs";
 import { loadConfig, sourceFiles } from "../config.mjs";
+import { behaviorStatus, createVerificationController, BEHAVIOR_URI } from "../verification.mjs";
 import { inspectTokens } from "../tokens.mjs";
 import { inspectScenarios } from "../scenarios.mjs";
 import { startShowcaseHost } from "./showcase-host.mjs";
@@ -33,6 +34,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
   const cache = inspection ?? {};
   const skills = cache.skills ??= createSkillStore(skillDirectory);
   const edits = cache.edits ??= createMutationController(root);
+  const verification = cache.verification ??= createVerificationController(root);
   let options = loadConfig(root);
   const signature = `${root}:${JSON.stringify(options.config)}`;
   if (cache.signature !== signature) {
@@ -43,7 +45,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
   const project = () => { const context = projectContext(options); context.showcase.url = getShowcaseUrl(); return context; };
   const subscribed = new Set();
   const server = new Server({ name: "reqvire-ads", version: pkg.version }, {
-    instructions: `${serverInstructions} ${mutations ? "Guarded editing is enabled: discover one owner with ads_units, read relevant ranges with ads_read_file and send only a Git unified diff to ads_apply_patch with that unit ID. Include its own scenarios/fixtures and required re-exports together, never unrelated units. Token manifests list companionFiles for canonical foundation import changes required by token files created/deleted in the same patch. The server validates architecture, registered Oxlint and project checks before writing. Fix rejected patches in their owner. Intentional settings, project guards and builders use the configuration unit; mandatory ADS gates still run." : "Source mutation tools are disabled; source edits use the client's editor/filesystem tools."}`,
+    instructions: `${serverInstructions} ${mutations ? "Guarded editing is enabled: discover one owner with ads_units, read relevant ranges with ads_read_file and send only a Git unified diff to ads_apply_patch with that unit ID. Include its own scenarios/fixtures and required re-exports together, never unrelated units. Manifests list companionFiles: required canonical token imports, or only the selected runtime owner's style-boundary entries in ds.config.json alongside its source. Unused style permissions fail validation. The server validates architecture, registered Oxlint and project checks before writing. Fix rejected patches in their owner. Intentional settings, project guards and builders use the configuration unit; mandatory ADS gates still run." : "Source mutation tools are disabled; source edits use the client's editor/filesystem tools."}`,
     capabilities: { tools: { listChanged: true }, resources: { listChanged: true, subscribe: true }, prompts: {},
       extensions: { "io.modelcontextprotocol/ui": { mimeTypes: [APP_MIME] }, ...(era === "modern" ? { [SKILLS_EXTENSION]: { directoryRead: true } } : {}) } },
   });
@@ -77,11 +79,13 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     const skillEntries = new Set(skills.skills.map((skill) => skill.uri));
     return [
       { uri: GUIDE_URI, name: "Start here: design-system workflow", description: "Read first for UI/ADS tasks, especially when only resource access is exposed. Explains the exact workspace, tool sequence, skill selection, previews, project commands and fallback.", mimeType: "text/markdown" },
+      { uri: "ads://guides/behaviors", name: "Controller and behavioral verification guide", mimeType: "text/markdown" },
       { uri: `${PROJECT_URI}/status`, name: "ADS project status", mimeType: "application/json" },
       { uri: BUILD_URI, name: "Preview build status and diagnostics", mimeType: "application/json" },
       { uri: `${PROJECT_URI}/tokens`, name: "Project token values and themes", mimeType: "application/json" },
       { uri: `${PROJECT_URI}/catalog`, name: "Public components and patterns", mimeType: "application/json" },
       { uri: `${PROJECT_URI}/scenarios`, name: "Independently mountable scenarios", mimeType: "application/json" },
+      { uri: BEHAVIOR_URI, name: "Behavior contracts, demonstrations and current verification evidence", mimeType: "application/json" },
       { uri: `${PROJECT_URI}/checks`, name: "Current ADS architecture diagnostics", mimeType: "application/json" },
       { uri: TOKENS_APP_URI, name: "Experimental token widget", mimeType: APP_MIME },
       { uri: SCENARIO_APP_URI, name: "Experimental scenario widget", mimeType: APP_MIME },
@@ -98,18 +102,20 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     const context = project();
     return { projectRoot: root, workflow: workflow([...previews(), ...scenarioApps()]), project: context,
       package: pkg.name, version: pkg.version, dsDir: options.config.dsDir, publicAlias: options.config.publicAlias,
-      components: getCatalog().filter((item) => item.kind === "components").length,
-      patterns: getCatalog().filter((item) => item.kind === "patterns").length,
+      components: getCatalog().filter((item) => item.kind === "components" && item.apiKind === "ui").length,
+      patterns: getCatalog().filter((item) => item.kind === "patterns" && item.apiKind === "ui").length,
       tokenCount: inspectTokens(root).tokens.length, showcaseUrl: getShowcaseUrl(),
       previewWatch: previewWatch?.status() ?? { state: "disabled" },
       mutations: mutations ? edits.status() : { enabled: false },
       build: summarizeBuild(builds()),
       previews: previews(), skills: skills.skills.map(({ uri, frontmatter }) => ({ uri, name: frontmatter.name, description: frontmatter.description })),
       scenarios: { count: getRegistry().scenarios.length, diagnostics: getRegistry().diagnostics, resourceUri: `${PROJECT_URI}/scenarios`, tool: "ads_show_scenario" },
+      behaviors: { resourceUri: BEHAVIOR_URI, discoveryTool: "ads_behaviors", verificationTool: "ads_verify", ...verification.status() },
       experimental: { apps: true, nativeSkills: era === "modern", nativeSkillActivation: "host-controlled" } };
   }
   async function read(uri, signal) {
     if (uri === GUIDE_URI) return { contents: [{ uri, mimeType: "text/markdown", text: projectGuide(project(), [...previews(), ...scenarioApps()]) }] };
+    if (uri === "ads://guides/behaviors") return { contents: [{ uri, mimeType: "text/markdown", text: readFileSync(new URL("../../docs/BEHAVIORS.md", import.meta.url), "utf8") }] };
     if (skills.files.has(uri)) return { contents: [skills.read(uri)] };
     let value;
     if (uri === `${PROJECT_URI}/status`) value = status();
@@ -118,6 +124,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     else if (uri === `${PROJECT_URI}/catalog`) value = { items: getCatalog() };
     else if (uri === `${PROJECT_URI}/scenarios`) value = getRegistry();
     else if (uri === `${PROJECT_URI}/checks`) value = checkProject(root);
+    else if (uri === BEHAVIOR_URI) value = behaviorStatus(options);
     else if (uri === PREVIEW_MANIFEST_URI && options.config.mcp.previewManifest) {
       value = readPreviewManifest(options);
       if (!value) throw new Error("Preview resources are not built yet. Invoke ads_show_scenario to start the managed compiler.");
@@ -153,13 +160,13 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
   function tools() {
     return [
       { name: "ads_status", description: "Start here for UI/ADS work: components, patterns, tokens/themes/branding, layout, behavior, motion and showcase review. Returns the exact project root/public API, workflow, project commands, editing mode and build diagnostics. When mutations.enabled, use guarded ads_apply_patch for ADS edits; otherwise use local editing tools.", schema: empty, call: () => json(status()) },
-      { name: "ads_catalog", description: "Before creating/changing UI, find existing public components/patterns with a small query/limit. Returns import alias and exact source/guide URIs so you can reuse or edit the owner. Read ads_status first for workspace/workflow. Metadata only; does not render UI.", schema: query.extend({ kind: z.enum(["components", "patterns"]).optional() }), call: ({ query: search = "", limit, kind }) => {
+      { name: "ads_catalog", description: "Before creating/changing UI or behavior, find existing public components/patterns/controllers and hooks with a small query/limit. Returns import alias and exact source/guide URIs so you can reuse or edit the owner. Read ads_status first for workspace/workflow. Metadata only; does not render UI.", schema: query.extend({ kind: z.enum(["components", "patterns", "controllers"]).optional() }), call: ({ query: search = "", limit, kind }) => {
         const matches = getCatalog().filter((item) => (!kind || item.kind === kind) && item.name.toLowerCase().includes(search.toLowerCase()));
         const units = edits.units();
         return json({ total: matches.length, items: matches.slice(0, limit).map(item => ({ ...item, unit: units.find(unit => unit.files.includes(item.file))?.id ?? null })), resourceUri: `${PROJECT_URI}/catalog` });
       } },
-      { name: "ads_scenarios", description: "Find an independently mountable token, component, pattern or composition preview. IDs derive from source filenames; covers lists public UI and tokens lists the real token inputs. Use ads_show_scenario with an exact returned id. Showcase and MCP use this same registry.", schema: query.extend({ kind: z.enum(["tokens", "components", "patterns", "composition"]).optional(), offset: z.number().int().min(0).default(0) }), call: ({ query: search = "", limit, kind, offset }) => {
-        const matches = getRegistry().scenarios.filter(item => (!kind || item.kind === kind) && `${item.id} ${item.title} ${item.covers.join(" ")} ${item.tokens.join(" ")}`.toLowerCase().includes(search.toLowerCase()));
+      { name: "ads_scenarios", description: "Find an independently mountable token, component, pattern or composition preview. IDs derive from source filenames; covers lists rendered public UI, exercises lists behavioral APIs and tokens lists the real token inputs. Use ads_show_scenario with an exact returned id. Showcase and MCP use this same registry.", schema: query.extend({ kind: z.enum(["tokens", "components", "patterns", "composition"]).optional(), offset: z.number().int().min(0).default(0) }), call: ({ query: search = "", limit, kind, offset }) => {
+        const matches = getRegistry().scenarios.filter(item => (!kind || item.kind === kind) && `${item.id} ${item.title} ${item.covers.join(" ")} ${(item.exercises ?? []).join(" ")} ${item.tokens.join(" ")}`.toLowerCase().includes(search.toLowerCase()));
         const units = edits.units();
         return json({ total: matches.length, scenarios: matches.slice(offset, offset + limit).map(item => ({ ...item, unit: units.find(unit => unit.files.includes(item.file))?.id ?? null })), ...(offset + limit < matches.length ? { nextOffset: offset + limit } : {}), diagnostics: getRegistry().diagnostics, resourceUri: `${PROJECT_URI}/scenarios` });
       } },
@@ -181,11 +188,11 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         const matches = inventory.tokens.filter((token) => token.name.toLowerCase().includes(search.toLowerCase()));
         return json({ total: matches.length, tokens: matches.slice(0, limit), categories: tokenScenarios(), diagnosticCount: inventory.diagnostics.length, resourceUri: `${PROJECT_URI}/tokens` });
       } },
-      { name: "ads_check", description: "Run read-only core ADS architecture checks. Project Oxlint, typecheck, build and browser tests remain separate.", schema: z.object({ limit: z.number().int().min(1).max(50).default(20) }).strict(), call: ({ limit }) => {
+      { name: "ads_check", description: "Run read-only core ADS architecture checks; returns blocking diagnostics separately from nonblocking review advisories. Project Oxlint, typecheck, build and browser tests remain separate.", schema: z.object({ limit: z.number().int().min(1).max(50).default(20) }).strict(), call: ({ limit }) => {
         const result = checkProject(root);
-        return json({ ok: result.ok, total: result.diagnostics.length, diagnostics: result.diagnostics.slice(0, limit), resourceUri: `${PROJECT_URI}/checks` });
+        return json({ ok: result.ok, total: result.diagnostics.length, diagnostics: result.diagnostics.slice(0, limit), advisoryCount: result.advisories?.length ?? 0, advisories: (result.advisories ?? []).slice(0, limit), resourceUri: `${PROJECT_URI}/checks` });
       } },
-      { name: "ads_skills", description: "Select one ADS workflow after ads_status: ads-designer for building/refining/debugging UI; ads-assimilate for a library reference; ads-import for another project's ADS; ads-motion for animation; ads-break-ui for stress testing. Then read that workflow with ads_read_skill. Listing does not activate a native skill.", schema: empty, call: () => json({ skills: skills.skills.map(({ uri, frontmatter }) => ({ uri, ...frontmatter })) }) },
+      { name: "ads_skills", description: "Select one ADS workflow after ads_status: ads-designer for building/refining/debugging UI; ads-migrate for a library reference; ads-import for another project's ADS; ads-motion for animation; ads-break-ui for stress testing. Then read that workflow with ads_read_skill. Listing does not activate a native skill.", schema: empty, call: () => json({ skills: skills.skills.map(({ uri, frontmatter }) => ({ uri, ...frontmatter })) }) },
       { name: "ads_read_skill", description: "Read a selected skill or relative supporting text file in bounded chunks. This is explicit instruction access, not automatic native skill activation/install.", schema: z.object({ name: z.string().max(64), file: z.string().max(300).default("SKILL.md"), offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(8000).default(6000) }).strict(), call: ({ name, file, offset, limit }) => {
         const skill = skills.skills.find((entry) => entry.frontmatter.name === name);
         if (!skill) throw new Error("Unknown ADS skill name.");
@@ -214,19 +221,36 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
         }
         return json({ widget: { resourceUri: TOKENS_APP_URI }, category: null, tokenCount: inspectTokens(root).tokens.length, dataUri: `${PROJECT_URI}/tokens`, showcaseUrl: getShowcaseUrl() });
       } },
-      { name: "ads_units", description: "Discover editable ADS units and their files: components/patterns with colocated previews; composition; tokens; foundation shared files; documentation; assets/brand, assets/fonts and asset groups; configuration with ds.config.json, package/build/lint configuration and registered project guard/compiler sources. List summaries with query, or pass an exact unit ID for its manifest. Token manifests include companionFiles with the foundation entry path and allowed import changes. Imported peers stay separate. New owners follow the existing colocation convention.", schema: query.extend({ unit: z.string().min(1).max(256).optional() }), call: ({ unit, query: search = "", limit }) => {
+      { name: "ads_behaviors", description: "Discover owner-local behavioral guarantees for public hooks/APIs or private controllers, their scenario demonstrations, registered checks/profiles and fresh or stale execution evidence. Optional exercises links behavioral APIs to scenarios; covers remains rendered UI. Metadata and reachable calls do not prove a guarantee passed. Use ads_verify for selected registered checks.", schema: query.extend({ unit: z.string().max(256).optional(), api: z.string().max(200).optional() }), call: ({ query: search = "", limit, unit, api }) => {
+        const inventory = behaviorStatus(options);
+        const matches = inventory.contracts.filter(item => (!unit || item.unit === unit) && (!api || Object.values(item.subjects).some(subject => subject.api === api)) && JSON.stringify(item).toLowerCase().includes(search.toLowerCase()));
+        return json({ total: matches.length, contracts: matches.slice(0, limit).map(item => {
+          if (unit) return item;
+          const apis = Object.values(item.subjects).filter(subject => subject.api).map(subject => subject.api);
+          const demonstrations = [...new Set(Object.values(item.demonstrations).flat())];
+          return { unit: item.unit, file: item.file, apis: apis.slice(0, 20), apiCount: apis.length,
+            guarantees: item.guarantees.slice(0, 5).map(guarantee => ({ id: guarantee.id, result: guarantee.result })), guaranteeCount: item.guarantees.length,
+            demonstrations: demonstrations.slice(0, 10), demonstrationCount: demonstrations.length, checkCount: Object.keys(item.checks).length };
+        }), diagnostics: inventory.diagnostics.slice(0, 50), resourceUri: BEHAVIOR_URI });
+      } },
+      { name: "ads_verify", description: "Run one owner's registered development behavior checks using its configured runner/profile. Executes trusted project commands with bounded output, cancellation and process-tree cleanup; installs nothing. Browser profiles use an isolated managed showcase/MCP App. React StrictMode requires a project development harness, not a production widget. Missing/skipped cases, stale inputs and process exit alone cannot produce passing evidence. Discover exact unit/check IDs with ads_behaviors first.", schema: z.object({ unit: z.string().min(1).max(256), checks: z.array(z.string().min(1).max(100)).min(1).max(100).optional() }).strict(), annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: false }, call: async (args, signal) => {
+        const result = await verification.run(args, signal);
+        await refresh();
+        return { ...json(result), ...(!result.ok ? { isError: true } : {}) };
+      } },
+      { name: "ads_units", description: "Discover editable ADS units and their files: components/patterns with colocated previews; shared controllers; composition; tokens; foundation shared files; documentation; assets/brand, assets/fonts and asset groups; configuration with ds.config.json, package/build/lint configuration and registered project guard/compiler sources. List summaries with query, or pass an exact unit ID for its manifest. Manifests include companionFiles with permitted shared-entry or owner-only style-boundary bookkeeping; preserve peer permissions and unrelated configuration. Imported peers stay separate. New owners follow the existing colocation convention.", schema: query.extend({ unit: z.string().min(1).max(256).optional() }), call: ({ unit, query: search = "", limit }) => {
         const matches = edits.units().filter(item => unit ? item.id === unit : item.id.toLowerCase().includes(search.toLowerCase()));
         return json({ total: matches.length, units: matches.slice(0, limit).map(item => ({ id: item.id, kind: item.kind, fileCount: item.files.length, ...(unit ? { files: item.files.slice(0, 200), filesTruncated: item.files.length > 200, ...(item.companionFiles ? { companionFiles: item.companionFiles } : {}) } : {}) })) });
       } },
       { name: "ads_read_file", description: "Read a bounded range of ADS or registered configuration/extension source. Returns unit, full-file digest, startLine and nextOffset; default/max is 12000 UTF-16 characters. Binary assets return byte count/digest and no encoded content. Paths come from ads_units or discovery. Missing new paths return digest null. Read only relevant context before preparing a Git patch.", schema: z.object({ path: z.string().min(1).max(500), offset: z.number().int().min(0).default(0), limit: z.number().int().min(1).max(mutationLimits.readChars).default(mutationLimits.readChars) }).strict(), call: ({ path: file, ...range }) => json(edits.read(file, range)) },
-      ...(mutations ? [{ name: "ads_apply_patch", description: "Apply one Git diff to one ADS unit from ads_units. Pass exactly one of patch (inline) or patchFile (a regular .patch/.diff under .ds/patches/, for large/binary diffs without model-context bytes). Text uses --- a/path, +++ b/path and exact @@ hunks; /dev/null creates/deletes. Git binary patches require git diff --binary --full-index and installed Git. A unit owns its implementation, previews and fixtures; imported peers are separate. Foundation, documentation, assets and configuration are editable too. Configuration changes may register/edit project guards and builders; the proposed schema, mandatory core/Oxlint and candidate project checks must pass. Only selected-unit public re-exports may change; preserve unrelated statements including export {};. A tokens patch may include its companionFiles foundation entry only to add/remove canonical imports required by token files created/deleted in this patch, preserving other imports/comments and canonical order. Set dryRun true to validate without writing. Fix rejected patches and inspect current previews after acceptance.",
+      ...(mutations ? [{ name: "ads_apply_patch", description: "Apply one Git diff to one ADS unit from ads_units. Pass exactly one of patch (inline) or patchFile (a regular .patch/.diff under .ds/patches/, for large/binary diffs without model-context bytes). Text uses --- a/path, +++ b/path and exact @@ hunks; /dev/null creates/deletes. Git binary patches require git diff --binary --full-index and installed Git. A unit owns its implementation, previews and fixtures; imported peers are separate. Foundation, documentation, assets and configuration are editable too. Configuration changes may register/edit project guards and builders; the proposed schema, mandatory core/Oxlint and candidate project checks must pass. Only selected-unit public re-exports may change; preserve unrelated statements. A real selected-unit re-export may remove a redundant export {}; placeholder. A tokens patch may include its companionFiles foundation entry only to add/remove canonical imports required by token files created/deleted in this patch, preserving other imports/comments and canonical order. A runtime owner patch may also include its ds.config.json companion solely for that owner's inlineStyleFiles/styleWrites entries alongside its source. Unused permissions fail validation. Set dryRun true to validate without writing. Fix rejected patches and inspect current previews after acceptance.",
         schema: z.object({ unit: z.string().min(1).max(256), dryRun: z.boolean(), patch: z.string().min(1).max(mutationLimits.patchBytes).optional(), patchFile: z.string().min(1).max(500).optional() }).strict().refine(args => (args.patch !== undefined) !== (args.patchFile !== undefined), "Provide exactly one of patch or patchFile."),
         annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false }, _meta: { ui: { visibility: ["model"] } },
         call: async (args, signal) => {
           const result = await edits.apply(args, signal);
           if (result.applied) {
             try {
-              if (result.unit === "configuration") await previewWatch?.reconfigure?.(loadConfig(root).config.mcp, true);
+              if (result.changes.some(change => change.path === "ds.config.json") || result.unit === "configuration") await previewWatch?.reconfigure?.(loadConfig(root).config.mcp, true);
               await refresh(true);
             }
             catch (error) { result.warnings = [...(result.warnings ?? []), { rule: "mutation-notification", message: `Changes were applied, but preview refresh failed: ${error.message.slice(0, 2000)}. Recheck ads_status and reopen the scenario.` }]; }
@@ -295,7 +319,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
       try { const stat = statSync(file); return `${file}:${stat.mtimeMs}:${stat.size}`; } catch { return `${file}:missing`; }
     }).join("\n");
   }
-  const fingerprint = () => fileFingerprint([...sourceFiles(options.dsRoot), ...getDocuments().map((doc) => doc.file), path.join(root, "ds.config.json"), path.join(root, "package.json")]);
+  const fingerprint = () => fileFingerprint([...sourceFiles(options.dsRoot), ...getDocuments().map((doc) => doc.file), path.join(root, "ds.config.json"), path.join(root, "package.json"), path.join(root, ".ds/behavior-results.json")]);
   const artifactFingerprint = () => fileFingerprint(allApps().map(app => path.resolve(root, app.file)));
   const assetFingerprint = () => resourceAssets().map(asset => asset.uri).sort().join("\n");
   let previous = fingerprint();
@@ -330,7 +354,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
     previousAssets = assetFingerprint();
     previousBuild = JSON.stringify(builds());
     const targets = filesChanged ? era === "modern" ? resources().map((entry) => entry.uri).filter((uri) => !skills.files.has(uri)) : [...subscribed]
-      : [BUILD_URI, `${PROJECT_URI}/status`, ...(options.config.mcp.previewManifest ? [PREVIEW_MANIFEST_URI] : []), ...(artifactsChanged ? allApps().map(app => appUri(app.id)) : [])].filter((uri) => era === "modern" || subscribed.has(uri));
+      : [BUILD_URI, BEHAVIOR_URI, `${PROJECT_URI}/status`, ...(options.config.mcp.previewManifest ? [PREVIEW_MANIFEST_URI] : []), ...(artifactsChanged ? allApps().map(app => appUri(app.id)) : [])].filter((uri) => era === "modern" || subscribed.has(uri));
     for (const uri of targets) { if (notifications) notifications.resourceUpdated(uri); else await server.sendResourceUpdated({ uri }); }
     return true;
   }
@@ -338,7 +362,7 @@ export function createAdsMcp(directory, { era = "legacy", skillDirectory, pollIn
   timer?.unref();
   server.oninitialized = () => previewWatch?.start();
   server.onclose = () => { if (timer) clearInterval(timer); };
-  return { server, refresh, async close() { if (timer) clearInterval(timer); await server.close(); } };
+  return { server, refresh, async close() { if (timer) clearInterval(timer); if (!inspection) await verification.close(); await server.close(); } };
 }
 
 export async function startAdsMcp(directory = process.cwd(), { stdio = true, showcase = true, port = 0, mutations = false } = {}) {
@@ -353,24 +377,37 @@ export async function startAdsMcp(directory = process.cwd(), { stdio = true, sho
       { port, observe: notifications => createAdsMcp(directory, { era: "modern", previewWatch, showcaseUrl, inspection, mutations, notifications }) });
     process.stderr.write(`ADS showcase: ${host.url}\n`);
   }
-  const handle = stdio ? serveStdio(({ era }) => createAdsMcp(directory, { era, previewWatch, showcaseUrl, inspection, mutations }).server, { legacy: "serve", onerror: (error) => process.stderr.write(`ads mcp: ${error.message}\n`) }) : null;
+  const transport = stdio ? new StdioServerTransport() : null;
+  const handle = stdio ? serveStdio(({ era }) => createAdsMcp(directory, { era, previewWatch, showcaseUrl, inspection, mutations }).server, { transport, legacy: "serve", onerror: (error) => process.stderr.write(`ads mcp: ${error.message}\n`) }) : null;
   let closing;
   function close() {
     return closing ??= (async () => {
       inspection.edits?.cancel();
-      await host?.close();
-      await previewWatch.stop();
-      await handle?.close();
-      process.stdin.removeListener("end", disconnect);
+      // Stop every owned resource even if another close fails or has in-flight RPCs.
+      const results = await Promise.allSettled([
+        Promise.resolve().then(() => host?.close()),
+        previewWatch.stop(),
+        Promise.resolve().then(() => inspection.verification?.close()),
+        Promise.resolve().then(() => handle?.close()),
+      ]);
+      for (const event of ["end", "close", "error"]) process.stdin.removeListener(event, disconnect);
       for (const signal of ["SIGINT", "SIGTERM"]) process.removeListener(signal, disconnect);
       process.removeListener("exit", forceCleanup);
+      const errors = results.filter(result => result.status === "rejected").map(result => result.reason);
+      if (errors.length) throw new AggregateError(errors, "ADS shutdown failed");
     })();
   }
-  function disconnect() { void close(); }
+  function disconnect() { void close().catch(error => { process.stderr.write(`ads mcp: ${error.message}\n`); process.exitCode = 1; }); }
   function forceCleanup() { previewWatch.kill(); }
   // Probe instances have no managed child; a real connection activates it.
-  // stdin EOF also cleans up the compiler when the host drops the transport.
-  if (stdio) process.stdin.once("end", disconnect);
+  // The SDK also closes its wire on stdout failure. Closing a probe instance
+  // must not shut the runtime down, so observe the wire, not server.onclose.
+  if (transport) {
+    const wireClosed = transport.onclose;
+    transport.onclose = () => { try { wireClosed?.(); } finally { disconnect(); } };
+    for (const event of ["end", "close", "error"]) process.stdin.once(event, disconnect);
+    if (process.stdin.readableEnded || process.stdin.destroyed) disconnect();
+  }
   for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, disconnect);
   process.once("exit", forceCleanup);
   return { close, url: host?.url };

package/dist/mcp/showcase-host.mjs

@@ -56,13 +56,17 @@ export async function startShowcaseHost(factory, { port = 0, observe } = {}) {
   let closing;
   return { url: `http://127.0.0.1:${web.address().port}/`, close() {
     return closing ??= (async () => {
-      for (const request of requests) request.abort();
-      await observer?.close();
-      await handler.close();
-      await sandbox?.close();
+      // Close sockets first: live subscriptions and preview requests must not
+      // hold shutdown open while protocol instances wait for cancellation.
       const stopped = new Promise(resolve => web.close(resolve));
+      for (const request of requests) request.abort();
       web.closeAllConnections();
-      await stopped;
+      const results = await Promise.allSettled([stopped,
+        Promise.resolve().then(() => observer?.close()),
+        handler.close(), sandbox?.close(),
+      ]);
+      const errors = results.filter(result => result.status === "rejected").map(result => result.reason);
+      if (errors.length) throw new AggregateError(errors, "Showcase shutdown failed");
     })();
   } };
 }

package/dist/oxlint.mjs

@@ -66,7 +66,7 @@ export default {
       },
     },
     "no-inline-style": {
-      meta: { type: "problem", schema, messages: { inline: "Move visual policy into the local ADS, or document a narrow exception in inlineStyleFiles." } },
+      meta: { type: "problem", schema, messages: { inline: "Own visual styles in component/pattern Linaria. Put demo-only sizing and framing in a public review/layout pattern. Reserve inlineStyleFiles for documented measured geometry; add component props for deliberate product API needs." } },
       create(context) {
         const { root, config } = options(context);
         const allowed = config.inlineStyleFiles.some((file) => path.resolve(root, file) === path.resolve(context.getFilename()));

package/dist/public-api.mjs

@@ -0,0 +1,39 @@
+import path from "node:path";
+import ts from "typescript";
+import { isDevelopmentFile, isInside } from "./config.mjs";
+import { uiOperation } from "./ui-framework.mjs";
+
+export function publicApi(program, options) {
+  const checker = program.getTypeChecker();
+  const entry = program.getSourceFile(path.join(options.dsRoot, options.config.publicEntry));
+  const module = entry && checker.getSymbolAtLocation(entry);
+  const items = [];
+  for (const exported of module ? checker.getExportsOfModule(module) : []) {
+    let symbol = exported;
+    if (symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
+    if (!declaration || !(symbol.flags & ts.SymbolFlags.Value)) continue;
+    const file = declaration.getSourceFile().fileName;
+    if (isDevelopmentFile(file, options)) continue;
+    const kind = isInside(path.join(options.dsRoot, "components"), file) ? "components" : isInside(path.join(options.dsRoot, "patterns"), file) ? "patterns" : isInside(path.join(options.dsRoot, "controllers"), file) ? "controllers" : null;
+    if (!kind) continue;
+    let renderable = false;
+    function visit(node) {
+      if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) renderable = true;
+      if (ts.isCallExpression(node) && ["createElement", "forwardRef", "memo"].includes(uiOperation(node.expression, checker))) renderable = true;
+      if (ts.isTaggedTemplateExpression(node)) {
+        let tag = node.tag;
+        if (ts.isCallExpression(tag)) tag = tag.expression;
+        let base = tag;
+        while (ts.isPropertyAccessExpression(base)) base = base.expression;
+        const symbol = checker.getSymbolAtLocation(base);
+        if (symbol?.declarations?.some(item => ts.isImportSpecifier(item) && (item.propertyName ?? item.name).text === "styled" && item.parent.parent.parent.moduleSpecifier.text.startsWith("@linaria/") || ts.isNamespaceImport(item) && item.parent.parent.moduleSpecifier.text.startsWith("@linaria/") && /^\.styled(?:\.|$)/.test(tag.getText().slice(base.getText().length)))) renderable = true;
+      }
+      ts.forEachChild(node, visit);
+    }
+    visit(declaration);
+    const type = checker.getTypeOfSymbolAtLocation(symbol, declaration);
+    items.push({ name: exported.name, kind, file, declaration, renderable: kind !== "controllers" && renderable, behavioral: !!(type.getCallSignatures().length || type.getConstructSignatures().length) });
+  }
+  return items;
+}

package/dist/scenarios-compiler.mjs

@@ -126,6 +126,16 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       cache.validate(stamp);
     });
   }
+  async function checkedBuild(stamp, build) {
+    const started = generation;
+    let checking = true, compiling = true;
+    function progress() { if (started === generation) reporter.progress(checking && compiling ? "validation-and-compilation" : checking ? "validation" : compiling ? "compilation" : "publication"); }
+    progress();
+    return Promise.allSettled([
+      gate(stamp).finally(() => { checking = false; progress(); }),
+      Promise.resolve().then(build).finally(() => { compiling = false; progress(); }),
+    ]);
+  }
   async function compile(entry) {
     if (buildGraph) return compileGraph();
     const revision = reporter.begin(entry.id);
@@ -154,16 +164,18 @@ export async function runScenarioCompiler(directory, { watched = false, validate
           if (path.isAbsolute(file) && existsSync(file)) dependencies.add(file);
         }
       } };
-      const outcomes = await Promise.allSettled([gate(stamp), reuse ? Promise.resolve() : build(entry, options, track)]);
+      const outcomes = await checkedBuild(stamp, () => reuse ? undefined : build(entry, options, track));
       const failure = outcomes.find(outcome => outcome.status === "rejected");
       if (failure) throw failure.reason;
       cache.assertCompiler();
       if (stopped || started !== generation || stamp !== cache.inputs()) return; // Watch queued a newer revision.
       if (!reuse) cache.record(entry, dependencies);
       reporter.ready(entry.id, revision);
+      reporter.progress("idle");
     } catch (error) {
       if (started !== generation) return;
       reporter.error(entry.id, revision, error);
+      reporter.progress("idle");
       console.error(error);
       if (!watched) process.exitCode = 1;
     }
@@ -192,7 +204,7 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       cache.assertCompiler();
       let reusable = entries.every(entry => cache.reusable(entry));
       if (reusable) { try { reusable = Boolean(readPreviewManifest(options, { verify: true })); } catch { reusable = false; } }
-      const outcomes = await Promise.allSettled([gate(stamp), reusable ? Promise.resolve(null) : buildGraph(entries, options, track)]);
+      const outcomes = await checkedBuild(stamp, () => reusable ? null : buildGraph(entries, options, track));
       const failure = outcomes.find(outcome => outcome.status === "rejected");
       if (failure) throw failure.reason;
       cache.assertCompiler();
@@ -209,9 +221,11 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       }
       for (const entry of entries) { pending.delete(entry.id); reporter.ready(entry.id, revisions.get(entry.id)); }
       publishedStamp = stamp;
+      reporter.progress("idle");
     } catch (error) {
       if (started !== generation) return;
       for (const entry of entries) { pending.delete(entry.id); reporter.error(entry.id, revisions.get(entry.id), error); }
+      reporter.progress("idle");
       console.error(error);
       if (!watched) process.exitCode = 1;
     }
@@ -261,6 +275,7 @@ export async function runScenarioCompiler(directory, { watched = false, validate
     clearTimeout(timer);
     timer = setTimeout(() => {
       ++generation;
+      reporter.progress("queued");
       validation = undefined;
       const changes = [...changed]; changed.clear();
       try {

package/dist/scenarios.mjs

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { existsSync } from "node:fs";
 import ts from "typescript";
+import { publicApi } from "./public-api.mjs";
 import { uiOperation } from "./ui-framework.mjs";
 import { isDevelopmentFile, isInside, isScenarioFile, sourceFiles } from "./config.mjs";
 import { projectCompilerOptions } from "./boundaries.mjs";
@@ -27,46 +28,17 @@ function literal(node, checker, seen = new Set()) {
 }
 
 export function publicUi(program, options) {
-  const checker = program.getTypeChecker();
-  const entry = program.getSourceFile(path.join(options.dsRoot, options.config.publicEntry));
-  const module = entry && checker.getSymbolAtLocation(entry);
-  const items = [];
-  for (const exported of module ? checker.getExportsOfModule(module) : []) {
-    let symbol = exported;
-    if (symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
-    const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
-    if (!declaration || !(symbol.flags & ts.SymbolFlags.Value)) continue;
-    const file = declaration.getSourceFile().fileName;
-    if (isDevelopmentFile(file, options)) continue;
-    const kind = isInside(path.join(options.dsRoot, "components"), file) ? "components" : isInside(path.join(options.dsRoot, "patterns"), file) ? "patterns" : null;
-    if (!kind) continue;
-    let renderable = false;
-    function visit(node) {
-      if (ts.isJsxElement(node) || ts.isJsxSelfClosingElement(node) || ts.isJsxFragment(node)) renderable = true;
-      if (ts.isCallExpression(node) && ["createElement", "forwardRef", "memo"].includes(uiOperation(node.expression, checker))) renderable = true;
-      if (ts.isTaggedTemplateExpression(node)) {
-        let tag = node.tag;
-        if (ts.isCallExpression(tag)) tag = tag.expression;
-        let base = tag;
-        while (ts.isPropertyAccessExpression(base)) base = base.expression;
-        const symbol = checker.getSymbolAtLocation(base);
-        if (symbol?.declarations?.some(item => ts.isImportSpecifier(item) && (item.propertyName ?? item.name).text === "styled" && item.parent.parent.parent.moduleSpecifier.text.startsWith("@linaria/") || ts.isNamespaceImport(item) && item.parent.parent.moduleSpecifier.text.startsWith("@linaria/") && /^\.styled(?:\.|$)/.test(tag.getText().slice(base.getText().length)))) renderable = true;
-      }
-      ts.forEachChild(node, visit);
-    }
-    visit(declaration);
-    items.push({ name: exported.name, kind, file, declaration, renderable });
-  }
-  return items;
+  return publicApi(program, options).filter(item => item.kind !== "controllers");
 }
 
 /** Discover metadata statically. The MCP process never imports scenario modules. */
 export function inspectScenarios(options, suppliedProgram) {
   const { root, dsRoot } = options;
   const files = sourceFiles(dsRoot).filter(isScenarioFile);
-  const program = suppliedProgram ?? ts.createProgram([path.join(dsRoot, options.config.publicEntry), ...files], projectCompilerOptions(options));
+  const program = suppliedProgram ?? ts.createProgram([path.join(dsRoot, options.config.publicEntry), ...files], { ...projectCompilerOptions(options), allowJs: true });
   const known = new Map(publicUi(program, options).map((item) => [item.name, item]));
   const checker = program.getTypeChecker();
+  const behaviorApis = new Map(publicApi(program, options).filter(item => !item.renderable && item.behavioral).map(item => [item.name, item]));
   const tokenNames = new Set(inspectTokens(root).tokens.map(token => token.name));
   const scenarios = [];
   const diagnostics = [];
@@ -105,21 +77,22 @@ export function inspectScenarios(options, suppliedProgram) {
     }
     const fixtureBase = path.basename(file).startsWith("Scenario.") ? path.join(path.dirname(file), "fixture") : file.replace(/\.scenario\.[^.]+$/, ".fixture");
     if (![".ts", ".tsx", ".js", ".jsx", ".mts", ".cts", ".mjs", ".cjs", ".json"].some(extension => existsSync(fixtureBase + extension))) report(file, "Keep this scenario's inputs beside it: fixture.ts (directory entry) or <Owner>.fixture.ts (flat entry). An empty fixture is valid for a component without inputs.");
-    if (!metadata || Object.keys(metadata).some((key) => !["title", "covers", "tokens", "samples"].includes(key)) || typeof metadata.title !== "string" || !metadata.title.trim() || !Array.isArray(metadata.covers) || !metadata.covers.length || metadata.covers.some((name) => typeof name !== "string" || !known.get(name)?.renderable)
+    if (!metadata || Object.keys(metadata).some((key) => !["title", "covers", "exercises", "tokens", "samples"].includes(key)) || typeof metadata.title !== "string" || !metadata.title.trim() || !Array.isArray(metadata.covers) || !metadata.covers.length || metadata.covers.some((name) => typeof name !== "string" || !known.get(name)?.renderable)
+      || Object.hasOwn(metadata, "exercises") && (!Array.isArray(metadata.exercises) || metadata.exercises.some(name => typeof name !== "string" || !behaviorApis.has(name)))
       || Object.hasOwn(metadata, "tokens") && (!Array.isArray(metadata.tokens) || metadata.tokens.some(name => typeof name !== "string" || !name.startsWith("--")))
       || kind === "tokens" && (Object.hasOwn(metadata, "tokens") || !validTokenSamples(metadata.samples) || !metadata.covers.some(name => known.get(name)?.kind === "patterns"))
       || Object.hasOwn(metadata, "samples") && !validTokenSamples(metadata.samples)) {
-      report(file, "Export static metadata with nonempty covers. Token scenarios must render a project-owned public review pattern and declare samples: fixture.samples, a literal list of { token, property, probe } CSS samples. A plain value list or covers: [] is incomplete."); continue;
+      report(file, "Export static metadata with nonempty covers naming rendered public UI. Optional exercises names public behavioral APIs, not rendered UI. Token scenarios must render a project-owned public review pattern and declare samples: fixture.samples, a literal list of { token, property, probe } CSS samples. A plain value list or covers: [] is incomplete."); continue;
     }
     if (!["composition", "tokens"].includes(kind) && metadata.covers.some((name) => known.get(name).kind !== kind)) report(file, "Component scenarios cover primitives; pattern scenarios cover patterns. Use composition/ for larger interfaces.");
     const tokens = [...new Set([...(metadata.tokens ?? []), ...(metadata.samples ?? []).map(sample => sample.token)])];
     for (const name of tokens) if (!tokenNames.has(name)) diagnostics.push({ file: path.relative(root, file).replaceAll("\\", "/"), rule: "token-scenario-reference", line: 1, column: 1, message: `Scenario references undeclared token ${name}. Use a real foundation token.` });
-    scenarios.push({ id, kind, title: metadata.title, covers: [...new Set(metadata.covers)], tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
+    scenarios.push({ id, kind, title: metadata.title, covers: [...new Set(metadata.covers)], ...(metadata.exercises ? { exercises: [...new Set(metadata.exercises)] } : {}), tokens, ...(metadata.samples ? { samples: metadata.samples } : {}), file: path.relative(root, file).replaceAll("\\", "/"), artifact: path.relative(root, scenarioArtifact(root, id)).replaceAll("\\", "/") });
   }
   return { scenarios: scenarios.sort((a, b) => a.id.localeCompare(b.id)), diagnostics };
 }
 
-export function inspectScenarioCoverage(options, program, report) {
+export function inspectScenarioCoverage(options, program, report, advise = () => {}) {
   const registry = inspectScenarios(options, program);
   for (const item of registry.diagnostics) report(path.join(options.root, item.file), item.rule, item.message, item.line, item.column);
   const checker = program.getTypeChecker();
@@ -153,7 +126,7 @@ export function inspectScenarioCoverage(options, program, report) {
     return symbol.declarations?.length ? symbol : null;
   }
   const identities = new Map();
-  for (const item of ui) {
+  for (const item of publicApi(program, options)) {
     if (!identities.has(item.declaration)) identities.set(item.declaration, new Set());
     identities.get(item.declaration).add(item.name);
   }
@@ -165,12 +138,16 @@ export function inspectScenarioCoverage(options, program, report) {
   for (const scenario of registry.scenarios) {
     const source = program.getSourceFile(path.join(options.root, scenario.file));
     const rendered = new Set();
+    const exercised = new Set(), referencedApis = new Set();
     const referencedTokens = new Set();
     let samplesPassed = false;
     const visited = new Set();
     function visit(node, reached = false) {
       if (!node || visited.has(node)) return;
-      if (!reached && (ts.isFunctionDeclaration(node) || ts.isVariableDeclaration(node))) return;
+      if (!reached && ts.isFunctionDeclaration(node)) return;
+      // Calls/construction in a mounted adapter execute even when only a result
+      // property is read later. Unused literal fixture fields still do not count.
+      if (!reached && ts.isVariableDeclaration(node) && !(node.initializer && (ts.isCallExpression(node.initializer) || ts.isNewExpression(node.initializer)))) return;
       if (!reached && (ts.isArrowFunction(node) || ts.isFunctionExpression(node)) && !ts.isCallExpression(node.parent) && !ts.isJsxExpression(node.parent)) return;
       visited.add(node);
       if (ts.isStringLiteralLike(node) && (isSharedToken(node.text) || scenario.tokens.includes(node.text))) referencedTokens.add(node.text);
@@ -180,18 +157,25 @@ export function inspectScenarioCoverage(options, program, report) {
       if (expression) {
         const symbol = canonical(symbolOf(expression));
         const names = identities.get(symbol?.valueDeclaration ?? symbol?.declarations?.[0]);
-        for (const name of names ?? []) rendered.add(name);
+        for (const name of names ?? []) { rendered.add(name); exercised.add(name); }
         if (scenario.kind === "tokens" && [...names ?? []].some(name => scenario.covers.includes(name))) {
           const attributes = ts.isCallExpression(node) ? literal(node.arguments[1], checker) : Object.assign({}, ...node.attributes.properties.map(attribute => ts.isJsxSpreadAttribute(attribute) ? literal(attribute.expression, checker) : ts.isJsxAttribute(attribute) && ts.isIdentifier(attribute.name) && attribute.initializer && ts.isJsxExpression(attribute.initializer) ? { [attribute.name.text]: literal(attribute.initializer.expression, checker) } : {}));
           if (JSON.stringify(attributes?.samples) === JSON.stringify(scenario.samples)) samplesPassed = true;
         }
       }
+      if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
+        let expression = node.expression;
+        if (ts.isPropertyAccessExpression(expression) && ["call", "apply"].includes(expression.name.text)) expression = expression.expression;
+        const symbol = canonical(symbolOf(expression));
+        for (const name of identities.get(symbol?.valueDeclaration ?? symbol?.declarations?.[0]) ?? []) exercised.add(name);
+      }
       // Follow local adapters reachable from the default entry. Unused example
       // functions do not satisfy coverage; production implementations are never
       // traversed to manufacture coverage for their internal dependencies.
       if (ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node) || ts.isIdentifier(node) && !(ts.isPropertyAccessExpression(node.parent) || ts.isElementAccessExpression(node.parent))) {
         const symbol = canonical(symbolOf(node));
         const declaration = symbol?.valueDeclaration;
+        for (const name of identities.get(declaration ?? symbol?.declarations?.[0]) ?? []) referencedApis.add(name);
         if (declaration && isDevelopmentFile(declaration.getSourceFile().fileName, options)) visit(declaration, true);
       }
       ts.forEachChild(node, child => visit(child, reached && (ts.isExportAssignment(node) || ts.isVariableDeclaration(node))));
@@ -201,6 +185,10 @@ export function inspectScenarioCoverage(options, program, report) {
       if (!rendered.has(name)) report(source.fileName, "scenario-render", `${name} is declared in covers but has no public render reference in this scenario. Render the real API; an import alone does not count.`);
       else covered.add(name);
     }
+    for (const name of scenario.exercises ?? []) {
+      if (!exercised.has(name) && !referencedApis.has(name)) report(source.fileName, "scenario-exercise", `${name} is declared in exercises but has no reachable behavioral use. Imports and unused adapters do not count.`);
+      else if (!exercised.has(name)) advise(source.fileName, "scenario-exercise-review", `${name} is referenced dynamically. Verify its invocation in the registered browser/behavior checks; a reference alone does not prove execution.`);
+    }
     for (const name of referencedTokens) if (!declaredTokens.has(name)) report(source.fileName, "token-scenario-reference", `Reachable scenario input references undeclared token ${name}.`);
     if (scenario.kind === "tokens" && !samplesPassed) report(source.fileName, "token-scenario-render", "Pass the declared fixture.samples into a rendered public review pattern's samples prop. Printing token names or reading unused fixtures is not sample coverage.");
     for (const name of scenario.tokens) {

package/dist/skills/README.md

@@ -3,13 +3,13 @@
 Install the skills you need with `npx skills`:
 
 ```sh
-npx skills add reqvire-org/ads --skill ads-designer --skill ads-import --skill ads-assimilate --skill ads-break-ui --skill ads-motion
+npx skills add reqvire-org/ads --skill ads-designer --skill ads-import --skill ads-migrate --skill ads-break-ui --skill ads-motion
 ```
 
 For local development, install from this checkout:
 
 ```sh
-npx skills add ./skills --skill ads-designer --skill ads-import --skill ads-assimilate --skill ads-break-ui --skill ads-motion
+npx skills add ./skills --skill ads-designer --skill ads-import --skill ads-migrate --skill ads-break-ui --skill ads-motion
 ```
 
 Each skill includes its own instructions and references. `ads-designer` also
@@ -36,7 +36,7 @@ the browser, and provides a running URL or exact command for review. See the
 |-------|-----|---------|
 | [ads-designer](ads-designer/SKILL.md) | Bootstrap or build UI using the local ADS, with craft/mobile guidance | `$ads-designer build a settings page using this project's ADS` |
 | [ads-import](ads-import/SKILL.md) | Import selected external ADS source, brand artwork, or compatible source token values | `$ads-import /path/to/source-repo component Toast` |
-| [ads-assimilate](ads-assimilate/SKILL.md) | Study an external component library and implement a native counterpart | `$ads-assimilate https://github.com/emilkowalski/sonner` |
+| [ads-migrate](ads-migrate/SKILL.md) | Study an external component library and implement a native counterpart | `$ads-migrate https://github.com/emilkowalski/sonner` |
 | [ads-break-ui](ads-break-ui/SKILL.md) | Stress-test real components/patterns; optionally fix demonstrated failures | `$ads-break-ui AppShell +fix` |
 | [ads-motion](ads-motion/SKILL.md) | Implement, review, audit, or profile motion | `$ads-motion review Toast` |