@reqvire-org/ads 0.3.1 → 0.3.3

package/dist/mcp/build-status.mjs

@@ -8,9 +8,9 @@ import { readPreviewManifest } from "../preview-resources.mjs";
 export const BUILD_URI = "ads://project/build";
 export const buildStatusFile = (root) => path.join(root, ".ds/build-status.json");
 const maxBytes = 256 * 1024;
-const diagnostic = z.object({ message: z.string().max(4000), file: z.string().max(1000).optional(), line: z.number().int().positive().optional(), column: z.number().int().positive().optional(), plugin: z.string().max(200).optional() }).strict();
+const diagnostic = z.object({ message: z.string().max(4000), file: z.string().max(1000).optional(), line: z.number().int().positive().optional(), column: z.number().int().positive().optional(), plugin: z.string().max(200).optional(), code: z.string().max(100).optional() }).strict();
 const preview = z.object({ id: z.string().max(256), state: z.enum(["idle", "building", "ready", "error"]), revision: z.number().int().nonnegative(), lastSuccessfulRevision: z.number().int().positive().nullable(), artifactDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/).nullable(), diagnostics: z.array(diagnostic).max(20), diagnosticSet: z.number().int().nonnegative().optional() }).strict();
-const snapshot = z.object({ schemaVersion: z.literal(1), session: z.string().regex(/^[\w-]{1,100}$/), sequence: z.number().int().nonnegative(), updatedAt: z.string().datetime(), previews: z.array(preview), diagnosticSets: z.array(z.array(diagnostic).max(20)).optional() }).strict().refine(value => value.previews.every(entry => entry.diagnosticSet === undefined || value.diagnosticSets?.[entry.diagnosticSet]), "Invalid shared diagnostic reference.");
+const snapshot = z.object({ schemaVersion: z.literal(1), session: z.string().regex(/^[\w-]{1,100}$/), sequence: z.number().int().nonnegative(), updatedAt: z.string().datetime(), previews: z.array(preview), diagnostics: z.array(diagnostic).max(20).optional(), diagnosticSets: z.array(z.array(diagnostic).max(20)).optional() }).strict().refine(value => value.previews.every(entry => entry.diagnosticSet === undefined || value.diagnosticSets?.[entry.diagnosticSet]), "Invalid shared diagnostic reference.");
 export const artifactDigest = (file) => {
   if (realpathSync(file) !== file) throw new Error("Preview output cannot resolve through a symlink.");
   if (statSync(file).size > 2 * 1024 * 1024) throw new Error("Preview exceeds 2 MiB.");
@@ -26,7 +26,7 @@ function normalizeDiagnostic(root, error) {
   return { message: String(error?.message ?? error).slice(0, 4000),
     ...(file ? { file: (path.isAbsolute(file) ? path.relative(root, file) : file).replaceAll("\\", "/").slice(0, 1000) } : {}),
     ...(Number.isInteger(line) && line > 0 ? { line } : {}), ...(Number.isInteger(column) && column > 0 ? { column } : {}),
-    ...(typeof error?.plugin === "string" ? { plugin: error.plugin.slice(0, 200) } : {}) };
+    ...(typeof error?.plugin === "string" ? { plugin: error.plugin.slice(0, 200) } : {}), ...(typeof error?.code === "string" ? { code: error.code.slice(0, 100) } : {}) };
 }
 
 /** One publisher per project compiler; no dependency on a UI framework. */
@@ -36,8 +36,9 @@ export function createBuildReporter(directory, { apps, session = process.env.ADS
   if (!isInside(root, target)) throw new Error("Build status must stay inside the project.");
   const entries = new Map(apps.map((app) => [app.id, { id: app.id, state: "idle", revision: 0, lastSuccessfulRevision: null, artifactDigest: null, diagnostics: [] }]));
   let sequence = 0;
+  let diagnostics = [];
   function save() {
-    const value = { schemaVersion: 1, session, sequence: ++sequence, updatedAt: new Date().toISOString(), previews: [...entries.values()] };
+    const value = { schemaVersion: 1, session, sequence: ++sequence, updatedAt: new Date().toISOString(), previews: [...entries.values()], ...(diagnostics.length ? { diagnostics } : {}) };
     let text = JSON.stringify(snapshot.parse(value));
     // A shared graph failure applies to every scenario. Store repeated details
     // once only when necessary; ordinary reports retain inline diagnostics.
@@ -66,6 +67,17 @@ export function createBuildReporter(directory, { apps, session = process.env.ADS
   save();
   return {
     session,
+    failure(error) {
+      diagnostics = (Array.isArray(error) ? error : [error]).slice(0, 20).map(error => normalizeDiagnostic(root, error));
+      for (const value of entries.values()) { value.state = "error"; ++value.revision; value.diagnostics = []; }
+      save();
+    },
+    clearFailure() {
+      if (!diagnostics.length) return;
+      diagnostics = [];
+      for (const value of entries.values()) if (value.state === "error" && !value.diagnostics.length) value.state = "idle";
+      save();
+    },
     setApps(next) {
       const ids = new Set(next.map(app => app.id));
       for (const id of entries.keys()) if (!ids.has(id)) entries.delete(id);
@@ -104,11 +116,11 @@ export function createBuildReporter(directory, { apps, session = process.env.ADS
 }
 
 /** Read durable build events; a running process alone never means a fresh build. */
-export function inspectBuildStatus(root, config, { session, processState } = {}) {
+export function inspectBuildStatus(root, config, { session, processState, file = buildStatusFile(root) } = {}) {
   let report;
   let reportError;
-  const file = buildStatusFile(root);
   try {
+    if (!isInside(root, path.resolve(file))) throw new Error("Build status must stay inside the project.");
     if (existsSync(file)) {
       if (realpathSync(file) !== file || statSync(file).size > maxBytes) throw new Error("Build status must be a real project file under 256 KiB.");
       report = snapshot.parse(JSON.parse(readFileSync(file, "utf8")));
@@ -125,6 +137,7 @@ export function inspectBuildStatus(root, config, { session, processState } = {})
     const value = report?.previews.find((entry) => entry.id === app.id);
     let state = value?.state ?? "unreported";
     let diagnostics = value?.diagnosticSet !== undefined ? report.diagnosticSets[value.diagnosticSet] : value?.diagnostics ?? [];
+    if (report?.diagnostics?.length) { state = "error"; diagnostics = [...report.diagnostics, ...diagnostics].slice(0, 20); }
     const available = existsSync(path.resolve(root, app.file));
     if (reportError) { state = "error"; diagnostics = [{ message: reportError }]; }
     if (graphError && app.id.includes("/")) { state = "error"; diagnostics = [{ message: graphError }]; }
@@ -139,8 +152,8 @@ export function inspectBuildStatus(root, config, { session, processState } = {})
     return { id: app.id, state, session: report?.session ?? null, revision: value?.revision ?? null, lastSuccessfulRevision: value?.lastSuccessfulRevision ?? null,
       current, stale: state === "unreported" ? null : !current, available, diagnostics };
   });
-  const state = previews.some((entry) => entry.state === "error") ? "error" : previews.some((entry) => entry.state === "building") ? "building" : previews.some((entry) => entry.state === "unreported") ? "unreported" : previews.some(entry => entry.current) ? "ready" : previews.length ? "idle" : "disabled";
-  return { state, reported: Boolean(report), session: report?.session ?? null, sequence: report?.sequence ?? null, updatedAt: report?.updatedAt ?? null, previews, resourceUri: BUILD_URI };
+  const state = reportError || report?.diagnostics?.length || previews.some((entry) => entry.state === "error") ? "error" : previews.some((entry) => entry.state === "building") ? "building" : previews.some((entry) => entry.state === "unreported") ? "unreported" : previews.some(entry => entry.current) ? "ready" : previews.length ? "idle" : "disabled";
+  return { state, reported: Boolean(report), session: report?.session ?? null, sequence: report?.sequence ?? null, updatedAt: report?.updatedAt ?? null, previews, ...(report?.diagnostics?.length ? { diagnostics: report.diagnostics } : {}), resourceUri: BUILD_URI };
 }
 
 export class PreviewBuildError extends Error {
@@ -154,7 +167,7 @@ export function summarizeBuild(build) {
     return { ...value, diagnostics, diagnosticCount: value.diagnostics.length,
       diagnosticsTruncated: value.diagnostics.length > 3 || value.diagnostics.some((entry) => entry.message.length > 1000) };
   }
-  return build.previews ? { ...build, previews: build.previews.map(bounded) } : { ...bounded(build), resourceUri: BUILD_URI };
+  return build.previews ? { ...build, ...(build.diagnostics ? bounded(build) : {}), previews: build.previews.map(bounded) } : { ...bounded(build), resourceUri: BUILD_URI };
 }
 
 export function buildFailure(build) {

package/dist/mcp/mutations.mjs

@@ -291,7 +291,7 @@ export function createMutationController(directory) {
         }
         const warnings = [];
         if (!dryRun && (unit.startsWith("assets") || unit === "configuration")) { try { await generateBrandAssets(root); } catch (error) { warnings.push({ rule: "mutation-assets", message: `Source was applied; generated brand output needs recovery: ${error.message}` }); } }
-        return lastResult = { ok: true, unit, applied: !dryRun, changes: changes.map(change => ({ path: change.path, operation: change.content === null ? "delete" : change.expectedDigest === null ? "create" : "update", digest: change.content === null ? null : digest(Buffer.from(change.content)) })), checks: verified, ...(warnings.length ? { warnings } : {}),
+        return lastResult = { ok: true, unit, applied: !dryRun, changes: changes.map(change => ({ path: change.path, operation: change.content === null ? "delete" : change.expectedDigest === null ? "create" : "update", digest: change.content === null ? null : digest(Buffer.from(change.content)) })), checks: verified, ...(result.advisories?.length ? { advisories: result.advisories.slice(0, 50), advisoryCount: result.advisories.length } : {}), ...(warnings.length ? { warnings } : {}),
           preview: "Source validation passed. Inspect the managed preview build and rendered scenario after applying; validation is not visual verification." };
       } catch (error) {
         return lastResult = { ok: false, applied: false, diagnostics: [error.diagnostic ?? { rule: "mutation-error", message: error.message }], checks: verified };

package/dist/mcp/preview-watch.mjs

@@ -2,7 +2,7 @@ import { spawn } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { statSync, mkdirSync, writeFileSync, renameSync, rmSync, realpathSync } from "node:fs";
 import path from "node:path";
-import { buildFailure, buildStatusFile, inspectBuildStatus } from "./build-status.mjs";
+import { buildFailure, inspectBuildStatus } from "./build-status.mjs";
 
 function stamp(file) {
   try { const stat = statSync(file); return `${stat.mtimeMs}:${stat.ctimeMs}:${stat.size}`; }
@@ -13,7 +13,7 @@ function stamp(file) {
 export function createPreviewWatch(root, config, { log = process.stderr, buildTimeout = 30000 } = {}) {
   config = { ...config, apps: [...config.apps] };
   const command = config.previewWatch;
-  const session = randomUUID();
+  let session = randomUUID();
   let state = command ? "idle" : "disabled";
   let child;
   let error;
@@ -21,11 +21,14 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
   let childClosed = false;
   let killTimer;
   let stopping;
+  let restarting;
+  let disposed = false;
   const baselines = new Map();
   const ready = new Set();
   const requests = new Set();
   let active;
-  const requestFile = path.join(root, ".ds", `preview-requests-${session}.json`);
+  let requestFile = path.join(root, ".ds", `preview-requests-${session}.json`);
+  let reportFile = path.join(root, ".ds", `build-status-${session}.json`);
   function request(file) {
     if (!command || requests.has(file) && active === file) return;
     requests.add(file);
@@ -48,7 +51,7 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
     } catch (failure) { if (failure.code !== "ESRCH") throw failure; }
   }
   function start() {
-    if (state !== "idle") return;
+    if (disposed || state !== "idle") return;
     for (const app of config.apps) {
       const file = path.resolve(root, app.file);
       baselines.set(file, stamp(file));
@@ -57,7 +60,7 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
     // No shell: configured arguments remain literal. Child stdin cannot consume
     // the MCP channel, and both output streams go exclusively to diagnostics.
     const executable = command.command === "node" ? process.execPath : command.command;
-    const env = { ...process.env, ADS_MCP_BUILD_SESSION: session, ADS_MCP_BUILD_STATUS: buildStatusFile(root), ADS_MCP_REQUEST_FILE: requestFile, PATH: [path.join(root, "node_modules/.bin"), path.dirname(process.execPath), process.env.PATH ?? ""].join(path.delimiter) };
+    const env = { ...process.env, ADS_MCP_BUILD_SESSION: session, ADS_MCP_BUILD_STATUS: reportFile, ADS_MCP_REQUEST_FILE: requestFile, PATH: [path.join(root, "node_modules/.bin"), path.dirname(process.execPath), process.env.PATH ?? ""].join(path.delimiter) };
     try {
       child = spawn(executable, command.args, { cwd: root, env, shell: false, detached: process.platform !== "win32", stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
     } catch (failure) {
@@ -76,7 +79,7 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
       clearTimeout(killTimer);
       if (state !== "stopping") {
         state = "failed";
-        error ??= `Preview watcher exited (${signal ?? code}). Restart MCP after fixing the configured command.`;
+        error ??= `Preview watcher exited (${signal ?? code}). Fix the builder and invoke the preview again to restart it; MCP inspection remains available.`;
         log.write(`ads mcp: ${error}\n`);
       } else state = "stopped";
       resolve();
@@ -91,16 +94,36 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
     child.once("error", (failure) => { error = `Cannot start preview watcher: ${failure.message}`; });
   }
 
+  function restart() {
+    return restarting ??= (async () => {
+      await stopChild();
+      if (disposed) return;
+      session = randomUUID();
+      requestFile = path.join(root, ".ds", `preview-requests-${session}.json`);
+      reportFile = path.join(root, ".ds", `build-status-${session}.json`);
+      state = "idle"; error = undefined; child = closed = stopping = undefined; childClosed = false;
+      ready.clear(); baselines.clear(); active = undefined;
+      start();
+    })().finally(() => { restarting = undefined; });
+  }
+
   async function ensure(file, signal) {
+    if (signal?.aborted) throw new Error("Preview request cancelled.");
+    if (state === "failed" || restarting) await restart();
+    if (disposed) throw new Error("Preview watcher is stopped.");
     start();
     request(file);
     if (signal?.aborted) throw new Error("Preview request cancelled.");
     const app = config.apps.find((entry) => path.resolve(root, entry.file) === file);
-    const baseline = baselines.get(file) ?? null;
+    let baseline = baselines.get(file) ?? null;
     const deadline = Date.now() + buildTimeout;
+    let restarted = false;
     while (Date.now() < deadline) {
       if (signal?.aborted) throw new Error("Preview request cancelled.");
       const build = buildStatus().previews.find((entry) => entry.id === app?.id);
+      if (!restarted && build?.diagnostics.some(item => item.code === "ADS_PREVIEW_RESTART")) {
+        restarted = true; await restart(); request(file); baseline = baselines.get(file) ?? null; continue;
+      }
       if (build?.state === "error") throw buildFailure(build);
       if (command && state !== "running") throw new Error(error ?? "Preview watcher is stopped.");
       if (build?.current) return build;
@@ -113,23 +136,23 @@ export function createPreviewWatch(root, config, { log = process.stderr, buildTi
   }
 
   const status = () => ({ state, ...(child?.pid ? { pid: child.pid } : {}), ...(error ? { error } : {}) });
-  const buildStatus = () => inspectBuildStatus(root, config, command ? { session, processState: status() } : {});
+  const buildStatus = () => inspectBuildStatus(root, config, command ? { session, file: reportFile, processState: status() } : {});
 
-  async function stop() {
+  async function stopChild() {
     rmSync(requestFile, { force: true });
     if (stopping) return stopping;
-    if (!child || childClosed) { if (command) state = "stopped"; return; }
+    if (!child || childClosed) { if (command) state = "stopped"; rmSync(reportFile, { force: true }); return; }
     if (state === "stopped") return;
     state = "stopping";
     stopping = (async () => {
       kill("SIGTERM");
       clearTimeout(killTimer);
       const timer = setTimeout(() => kill("SIGKILL"), 1500);
-      try { await closed; } finally { clearTimeout(timer); }
+      try { await closed; } finally { clearTimeout(timer); rmSync(reportFile, { force: true }); }
     })();
     return stopping;
   }
-  return { start, ensure, stop, kill: () => kill("SIGKILL"), status, buildStatus, setApps(apps) {
+  return { start, ensure, async stop() { disposed = true; await restarting; return stopChild(); }, kill: () => kill("SIGKILL"), status, buildStatus, setApps(apps) {
     for (const app of apps) {
       const file = path.resolve(root, app.file);
       if (!baselines.has(file)) baselines.set(file, stamp(file));

package/dist/mcp/prompts.mjs

@@ -2,7 +2,7 @@ export const reasoning = `ADS is development tooling. The project owns its compo
 Start with ads_status and use its projectRoot, workflow and project commands; the MCP workspace may be nested inside the client repository. If ADS tools are not exposed, read ads://project/guide then ads://project/status. Find existing public UI with ads_catalog and load one relevant ADS workflow via ads_skills/ads_read_skill. UI implementation/refinement uses ads-designer; library adaptation ads-assimilate; ADS transfer ads-import; motion ads-motion; stress testing ads-break-ui. Domain-model workflows are separate. Inspect the relevant public API, local guide, token definitions and real showcase fixture before proposing changes. Keep source/instruction discovery scoped to the target project, ancestry and selected external sources; broad scans of /mnt or home are not needed to discover this ADS.
 When ads_status.mutations.enabled, discover one owner with ads_units, read relevant ranges with ads_read_file and send only a Git unified diff through ads_apply_patch({unit,patch,dryRun}). A unit includes its own scenarios/fixtures; imported peers remain separate. tokens is the token foundation unit. Only that owner's public re-exports may change in the shared entry; preserve unrelated statements including export {};. Token manifests list companionFiles: include required foundation import changes only for canonical token files created/deleted in the same patch, preserving other imports/comments and canonical order. Use dryRun to review validation. Rejected patches leave source unchanged; fix diagnostics rather than bypassing checks with direct writes. Shared globals use foundation; guides use documentation; assets use discovered assets/* units. Intentional configuration, registered project guards/builders and rule exceptions use configuration, which validates the proposed settings and refreshes its compiler. Keep mandatory ADS gates. For large/binary diffs, pass patchFile pointing to .ds/patches/<name>.patch rather than loading bytes into context; Git binary patches require installed Git. When editing is disabled, use local editing tools.
 Reason through Data (design-token values, semantic roles and relationships), UX (structure, behavior, accessibility, states and layout), and Skin (token-backed identity and visual states). Business data is a separate application-owned input, supplied through typed props or injected callbacks/services. The project uses Linaria extraction for owned styles; MCP adds no production runtime.
-Choose an existing public component or pattern first. Keep application data/routing/effects in the application and fixture data/state beside its scenario. Change presentation in its owning ADS implementation, then demonstrate the same public API in the showcase. Do not create a widget-only replica or override component internals.
+Choose an existing public component or pattern first. Keep application data/routing/effects in the application and fixture data/state beside its scenario. Change presentation in its owning ADS implementation, then demonstrate the same public API in the showcase. Put demo-only sizing and framing in a public review/layout pattern; add component props for deliberate runtime API needs and preserve required behavior. Do not create a widget-only replica or override component internals.
 For token source inspection, call ads_tokens with a focused query. For token samples, components, patterns and composition, use ads_scenarios to select a path-derived id and invoke ads_show_scenario. Showcase and MCP mount that exact entry and its colocated fixture; no page initialization is required. The showcase is a minimal tool-owned shell plus an MCP client and Apps host. Its menus come from tools; it invokes the same entry tools and refreshes the active scenario through notifications. The reusable App loads framework runtime, foundation CSS, fonts and selected modules via MCP resources inside its sandbox. Keep project execution and styles out of the outer host; preserve mount/unmount cleanup and lazy dependencies. Use the existing ads_status showcase URL, or ads showcase when no MCP runtime is connected. Projects supply scenarios/fixtures and the compiler, not browser page files or another shell. Tool metadata selects an MCP App; a resources/read of HTML alone is not proof of rendered UI. If the host has no Apps view, give the configured showcase URL and use text/resources.
 Check ads_status.previewWatch before launching a separate preview builder. A configured watcher is managed by ads mcp. Check ads_status.build or ads://project/build after changes: running does not mean ready, and unreported freshness is not evidence of current source. Reported preview failures include structured diagnostics; fix the owning source and wait for a successful rebuild, then invoke the preview tool again. Notifications may not reach the agent, so read status explicitly. Build revisions identify reported compilation attempts, not proof of runtime/visual correctness. Do not invent replacement UI to bypass a failed preview.
 Skills: use ads_skills to select a workflow and read its SKILL.md with ads_read_skill. Resolve relative supporting files from that skill URI. Reading instructions does not prove native skill activation or authorize unrelated actions.

package/dist/mcp/server.mjs

@@ -43,7 +43,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 } } : {}) } },
   });
@@ -181,9 +181,9 @@ 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_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 }) => {
@@ -214,19 +214,19 @@ 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_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. 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.` }]; }

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/scenarios-compiler.mjs

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, watch, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import path from "node:path";
 import { loadConfig, isInside } from "./config.mjs";
 import { inspectScenarios } from "./scenarios.mjs";
@@ -71,7 +71,7 @@ export function createPreviewCache(options, compilerFiles = []) {
   }
   return { inputs, reusable, validated: stamp => value.validation === stamp,
     assertCompiler() {
-      if (adapterDigest() !== loadedAdapter) throw new Error("Preview compiler code or dependencies changed. Restart ADS MCP/showcase to load the updated compiler before reviewing previews.");
+      if (adapterDigest() !== loadedAdapter) throw Object.assign(new Error("Preview compiler code or dependencies changed. Invoke the preview again to restart the builder and load current code."), { code: "ADS_PREVIEW_RESTART" });
     },
     validate(stamp) { value.validation = stamp; save(); },
     record(entry, dependencies) {
@@ -93,12 +93,17 @@ export async function runScenarioCompiler(directory, { watched = false, validate
   function registry() {
     options = loadConfig(root);
     const result = inspectScenarios(options);
-    if (result.diagnostics.length) throw new Error(result.diagnostics.map(item => `${item.file}: ${item.message}`).join("\n"));
+    if (result.diagnostics.length) throw Object.assign(new Error(result.diagnostics.map(item => `${item.file}: ${item.message}`).join("\n")), { scenarios: result.scenarios });
     mkdirSync(path.join(root, ".ds/scenarios"), { recursive: true });
     writeFileSync(path.join(root, ".ds/scenarios/manifest.json"), JSON.stringify({ schemaVersion: 1, scenarios: result.scenarios }, null, 2));
     return result.scenarios;
   }
-  let entries = registry();
+  let entries = [], registryFailure;
+  try { entries = registry(); }
+  catch (error) {
+    if (!watched) throw error;
+    registryFailure = error; entries = error.scenarios ?? [];
+  }
   const reporter = createBuildReporter(root, { apps: entries.map(entry => ({ id: entry.id, file: entry.artifact })) });
   const requested = new Set();
   const pending = new Set();
@@ -108,6 +113,12 @@ export async function runScenarioCompiler(directory, { watched = false, validate
   let generation = 0;
   let publishedStamp;
   let validation;
+  function failure(error) {
+    try { reporter.failure(error); } catch (reportError) { console.error(reportError); }
+    console.error(error);
+    if (!watched) process.exitCode = 1;
+  }
+  if (registryFailure) failure(registryFailure);
   function gate(stamp) {
     if (cache.validated(stamp)) return Promise.resolve();
     return validation ??= Promise.resolve().then(validate).then(() => {
@@ -119,8 +130,8 @@ export async function runScenarioCompiler(directory, { watched = false, validate
     if (buildGraph) return compileGraph();
     const revision = reporter.begin(entry.id);
     const started = generation;
-    const stamp = cache.inputs();
     try {
+      const stamp = cache.inputs();
       cache.assertCompiler();
       const reuse = cache.reusable(entry);
       const dependencies = new Set();
@@ -147,7 +158,7 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       const failure = outcomes.find(outcome => outcome.status === "rejected");
       if (failure) throw failure.reason;
       cache.assertCompiler();
-      if (started !== generation || stamp !== cache.inputs()) return; // Watch queued a newer revision.
+      if (stopped || started !== generation || stamp !== cache.inputs()) return; // Watch queued a newer revision.
       if (!reuse) cache.record(entry, dependencies);
       reporter.ready(entry.id, revision);
     } catch (error) {
@@ -160,24 +171,24 @@ export async function runScenarioCompiler(directory, { watched = false, validate
   async function compileGraph() {
     const revisions = new Map(entries.map(entry => [entry.id, reporter.begin(entry.id)]));
     const started = generation;
-    const stamp = cache.inputs();
-    const dependencies = new Set();
-    function assets(directory) {
-      for (const item of readdirSync(directory, { withFileTypes: true })) {
-        if (item.isSymbolicLink() || ["node_modules", ".ds", ".vite", "dist"].includes(item.name)) continue;
-        const file = path.join(directory, item.name);
-        if (item.isDirectory()) assets(file);
-        else if (/\.(?:css|svg|png|jpe?g|webp|gif|woff2?|ttf|otf)$/.test(file)) dependencies.add(file);
-      }
-    }
-    assets(options.dsRoot);
-    const track = { name: "ads-preview-graph-dependencies", generateBundle() {
-      for (const id of this.getModuleIds()) {
-        const file = id.split("?")[0];
-        if (path.isAbsolute(file) && existsSync(file)) dependencies.add(file);
-      }
-    } };
     try {
+      const stamp = cache.inputs();
+      const dependencies = new Set();
+      function assets(directory) {
+        for (const item of readdirSync(directory, { withFileTypes: true })) {
+          if (item.isSymbolicLink() || ["node_modules", ".ds", ".vite", "dist"].includes(item.name)) continue;
+          const file = path.join(directory, item.name);
+          if (item.isDirectory()) assets(file);
+          else if (/\.(?:css|svg|png|jpe?g|webp|gif|woff2?|ttf|otf)$/.test(file)) dependencies.add(file);
+        }
+      }
+      assets(options.dsRoot);
+      const track = { name: "ads-preview-graph-dependencies", generateBundle() {
+        for (const id of this.getModuleIds()) {
+          const file = id.split("?")[0];
+          if (path.isAbsolute(file) && existsSync(file)) dependencies.add(file);
+        }
+      } };
       cache.assertCompiler();
       let reusable = entries.every(entry => cache.reusable(entry));
       if (reusable) { try { reusable = Boolean(readPreviewManifest(options, { verify: true })); } catch { reusable = false; } }
@@ -185,7 +196,7 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       const failure = outcomes.find(outcome => outcome.status === "rejected");
       if (failure) throw failure.reason;
       cache.assertCompiler();
-      if (started !== generation || stamp !== cache.inputs()) return;
+      if (stopped || started !== generation || stamp !== cache.inputs()) return;
       const publication = outcomes[1].value;
       if (publication) {
         publication.publish(reporter.session);
@@ -209,15 +220,16 @@ export async function runScenarioCompiler(directory, { watched = false, validate
     if (compiling) return;
     compiling = true;
     try {
-      while (pending.size && !stopped) {
+      while (pending.size && !registryFailure && !stopped) {
         const id = pending.has(active) ? active : pending.values().next().value;
         pending.delete(id);
         const entry = entries.find(entry => entry.id === id);
         if (entry) await compile(entry);
       }
-    } finally { compiling = false; }
+    } catch (error) { failure(error); }
+    finally { compiling = false; }
   }
-  function request() {
+  function request(startBuild = true) {
     const file = process.env.ADS_MCP_REQUEST_FILE;
     if (!file || !existsSync(file)) return;
     try {
@@ -231,8 +243,8 @@ export async function runScenarioCompiler(directory, { watched = false, validate
           if (!buildGraph || publishedStamp !== cache.inputs()) pending.add(entry.id);
         }
       }
-      void drain();
-    } catch (error) { console.error(`Preview requests: ${error.message}`); }
+      if (startBuild) void drain();
+    } catch (error) { failure(error); }
   }
   if (!watched) {
     for (const entry of entries) pending.add(entry.id);
@@ -241,8 +253,8 @@ export async function runScenarioCompiler(directory, { watched = false, validate
   }
   let timer;
   const changed = new Set();
-  function sourceChanged(_event, file) {
-    if (!file || !/\.(?:[cm]?[jt]sx?|css|html|json|md|svg|png|jpe?g|webp|gif|woff2?|ttf|otf|lock|lockb)$/.test(file)) return;
+  function sourceChanged(_event, file, topology = false) {
+    if (!file || !topology && !/\.(?:[cm]?[jt]sx?|css|html|json|md|svg|png|jpe?g|webp|gif|woff2?|ttf|otf|lock|lockb)$/.test(file)) return;
     const absolute = path.join(root, file);
     if (file.split(path.sep).some(name => ["node_modules", ".git", ".ds", ".vite", "coverage"].includes(name)) || options.config.assets.generatedPaths.some(base => isInside(path.resolve(root, base), absolute))) return;
     changed.add(absolute);
@@ -253,7 +265,10 @@ export async function runScenarioCompiler(directory, { watched = false, validate
       const changes = [...changed]; changed.clear();
       try {
         entries = registry();
+        registryFailure = undefined;
         reporter.setApps(entries.map(entry => ({ id: entry.id, file: entry.artifact })));
+        reporter.clearFailure();
+        request(false);
         for (const id of requested) if (!entries.some(entry => entry.id === id)) { requested.delete(id); pending.delete(id); }
         // Every source change needs validation; unaffected artifacts need no
         // compilation. Check active first, then rebuild only changed dependencies.
@@ -263,25 +278,53 @@ export async function runScenarioCompiler(directory, { watched = false, validate
         }
         if (changes.length) void drain();
       } catch (error) {
-        for (const id of requested) { const revision = reporter.begin(id); reporter.error(id, revision, error); }
-        console.error(error);
+        registryFailure = error; failure(error);
       }
     }, 100);
   }
   // Do not allocate recursive OS watches for node_modules or generated trees.
-  const watchers = [watch(root, sourceChanged)];
-  for (const entry of readdirSync(root, { withFileTypes: true })) {
-    const directory = path.join(root, entry.name);
-    if (!entry.isDirectory() || entry.isSymbolicLink() || ["node_modules", ".git", ".ds", ".vite", "coverage"].includes(entry.name)
-      || options.config.assets.generatedPaths.some(base => isInside(path.resolve(root, base), directory))) continue;
-    watchers.push(watch(directory, { recursive: true }, (event, file) => sourceChanged(event, file && path.join(entry.name, file))));
+  const watchers = new Map();
+  function addWatch(directory, callback, recursive = false) {
+    if (stopped) return false;
+    try {
+      const stat = statSync(directory), identity = `${stat.dev}:${stat.ino}`;
+      if (watchers.get(directory)?.identity === identity) return false;
+      watchers.get(directory)?.watcher.close();
+      const watcher = watch(directory, { recursive }, callback);
+      watchers.set(directory, { watcher, identity });
+      watcher.on("error", error => {
+        watcher.close();
+        if (watchers.get(directory)?.watcher === watcher) watchers.delete(directory);
+        failure(error);
+      });
+      return true;
+    } catch (error) { failure(error); }
   }
-  const requestWatch = watch(path.join(root, ".ds"), (_event, file) => {
-    if (file === path.basename(process.env.ADS_MCP_REQUEST_FILE ?? "")) request();
-  });
+  function reconcileWatches(initial = false) {
+    if (stopped) return;
+    try {
+      addWatch(root, sourceChanged);
+      const wanted = new Set([root, path.join(root, ".ds")]);
+      for (const entry of readdirSync(root, { withFileTypes: true })) {
+        const directory = path.join(root, entry.name);
+        if (!entry.isDirectory() || entry.isSymbolicLink() || ["node_modules", ".git", ".ds", ".vite", "coverage"].includes(entry.name)
+          || options.config.assets.generatedPaths.some(base => isInside(path.resolve(root, base), directory))) continue;
+        wanted.add(directory);
+        if (addWatch(directory, (event, file) => sourceChanged(event, file && path.join(entry.name, file)), true) && !initial) sourceChanged("rename", entry.name, true);
+      }
+      mkdirSync(path.join(root, ".ds"), { recursive: true });
+      addWatch(path.join(root, ".ds"), (_event, file) => { if (file === path.basename(process.env.ADS_MCP_REQUEST_FILE ?? "")) request(); });
+      for (const [directory, { watcher }] of watchers) if (!wanted.has(directory) || !existsSync(directory)) {
+        watcher.close(); watchers.delete(directory);
+        if (!initial && directory !== root && directory !== path.join(root, ".ds")) sourceChanged("rename", path.relative(root, directory), true);
+      }
+    } catch (error) { failure(error); }
+  }
+  reconcileWatches(true);
+  const reconcileTimer = setInterval(reconcileWatches, 1000);
   request();
   console.log(`Scenario compiler ready: ${entries.length} entries; builds are requested on demand.`);
   for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => {
-    stopped = true; clearTimeout(timer); for (const watcher of watchers) watcher.close(); requestWatch.close();
+    stopped = true; clearTimeout(timer); clearInterval(reconcileTimer); for (const { watcher } of watchers.values()) watcher.close();
   });
 }

package/dist/skills/ads-assimilate/SKILL.md

@@ -27,7 +27,11 @@ unrelated statements. Its real re-export may accompany removal of a redundant
 `export {};` placeholder; do not add empty exports. A `tokens` manifest lists the foundation
 entry in `companionFiles`: when creating/deleting a canonical token file such as
 `fonts.css`, include only its required import change there in the same patch.
-Preserve other imports/comments and the canonical order. Use `dryRun: true` to
+Preserve other imports/comments and the canonical order. Runtime owner manifests
+also list a `ds.config.json` companion: change only that owner's `inlineStyleFiles`
+and `boundaries.styleWrites` entries together with its source. Unused permissions
+fail the core checks; do not pre-register a boundary without its implementation.
+Use `dryRun: true` to
 inspect validation; applying re-runs the gates. Fix rejected patches in their
 owner. Report unsupported coupled changes instead of bypassing a rejection with
 direct source writes. Shared styles/helpers use `foundation`, root guides use
@@ -241,6 +245,15 @@ source definitions and values; inspecting definitions does not prove UI parity.
 The tool keeps the shared naming contract; sample templates and their token
 lists belong to the project.
 
+A public review pattern may be covered by real token or composition scenarios;
+it needs no redundant standalone entry. Remove an optional scenario only while
+retaining reachable render coverage. Keep directory ownership anchored by its
+runtime entry (`index` or a file matching the directory name) or colocated fixture.
+Import colocated image/font fixtures so MCP serves them through asset resources.
+For a broken-image case, use a local failing fixture, rather than an external
+network failure or a domain-specific CSP exception. Production asset APIs remain
+unrestricted by this fixture guidance.
+
 Scenarios, colocated fixtures and helpers are development-only. Never export them
 from the runtime barrel or import them in production, including through aliases,
 re-exports or dynamic imports. They may not import application stores, routers,
@@ -251,6 +264,27 @@ Use local simulated services in fixtures. Tests may import fixtures; load real
 foundation CSS rather than assigning shared token values in JavaScript. Keep
 full-app integration harnesses and workflow coverage in application test support.
 
+Foundation CSS is checked, not an escape hatch. Value sheets define shared tokens
+on the document root/themes; `fonts.css` holds font-face metadata. `base.css` has
+three closed roles: root/body typography, canvas and theme defaults; limited native
+normalization; and global focus indicators/reduced-motion rules. Every selector
+branch, property and value must fit its role. Token-backed control skins, layout,
+interactive state rules and owner hooks are rejected even through `:where()`.
+Do not copy an unchecked upstream preflight or turn a component repair into a reset.
+Keep behavior and skin in their runtime owner. Put demo-only sizing and framing
+in a public review/layout pattern; add component props for a deliberate runtime
+API need. Preserve required capabilities while following ownership rules.
+Browser review still verifies the effects.
+
+Invalid metadata and source failures keep the managed compiler alive for repairs.
+Read `ads_status.build` or `ads://project/build`, fix the owner, then wait for current
+successful output. If the builder exited, fix its command and invoke the preview
+again; ADS starts one fresh child without an MCP reconnect. Compiler-code changes
+also reload on the next preview invocation. Reconnect the client when upgrading
+the ADS server package itself. Persistent SSE/notification streams make
+`networkidle` unsuitable: wait for the App's current ready/error state instead.
+
+
 
 
 Register component/project Oxlint plugins and rules in `ds.config.json`. Use
@@ -258,7 +292,14 @@ scoped `oxlint.overrides` for justified file-specific settings; never edit
 `.ds/oxlintrc.json`. These overrides configure Oxlint, not the independent
 architecture checks in `ads check`. Measured renderer properties and documented
 non-state hooks use explicit `boundaries`; shared token writes and primitive
-state overrides cannot be allowlisted. Add generic architectural protections to
+state overrides cannot be allowlisted. When migrating JSX inline geometry to
+imperative writes, port the source and replace its own boundary entries together
+in the owner's patch. Remove obsolete `inlineStyleFiles` entries and unused
+`styleWrites` properties; do not broaden permissions to keep a migration passing.
+Pointer-capture advisories call for review of cancellation, capture loss and
+teardown, including cleanup delegated to hooks. Verify actual cleanup in a browser;
+a locally present handler alone does not prove correctness.
+Add generic architectural protections to
 ADS core and keep domain/component-specific rules registered in project setup.
 
 Update meaningful variants, states, content, themes, and container sizes in the