@reqvire-org/ads 0.3.1 → 0.3.2

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/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

@@ -251,6 +251,25 @@ 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.
+Put skin/state/animation in the Linaria owner, and scenario layout variations in
+the public review pattern's typed API. 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

package/dist/skills/ads-assimilate/references/cli.md

@@ -55,7 +55,7 @@ If no published distribution exists, build and pack the tooling checkout with
 From inside an existing test project:
 
 ```sh
-ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.1.tgz"
+ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.2.tgz"
 npx --yes --package "$ads_tool_package" ads --help
 npx --yes --package "$ads_tool_package" ads init --framework react --tool-package "$ads_tool_package"
 npm install
@@ -93,7 +93,8 @@ component rules through the project's plugin adapter and `ds.config.json`, then
 run its actual build. Use `lint-config` directly for custom pipeline integration
 or debugging, not as a separate routine setup step.
 
-Use ADS 0.3.1 or later for the shared-resource preview compiler. `mcp` starts stdio
+Use ADS 0.3.2 or later for the closed foundation contract and recoverable
+shared-resource preview compiler. `mcp` starts stdio
 plus its local website; `showcase` starts the browser-only MCP runtime. Open the existing runtime URL from `ads_status` when
 connected; otherwise use `npm run dev:showcase` or the installed `ads showcase`.
 The tool client discovers entries and renders MCP Apps. Init adds the launch

package/dist/skills/ads-break-ui/SKILL.md

@@ -203,6 +203,25 @@ 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.
+Put skin/state/animation in the Linaria owner, and scenario layout variations in
+the public review pattern's typed API. 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

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

@@ -341,6 +341,25 @@ 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.
+Put skin/state/animation in the Linaria owner, and scenario layout variations in
+the public review pattern's typed API. 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

package/dist/skills/ads-designer/assets/bootstrap-ds/ADS.md

@@ -40,6 +40,35 @@ Token names and prefixes are fixed by ADS architecture; foreign brand prefixes
 are rejected. Shared assignments belong in token files. Components own
 `--ds-*`, patterns `--ux-*`, and the showcase `--showcase-*`; token files cannot
 assign those local variables or override component state.
+
+Foundation roles are enforced by `foundation-role`, `foundation-selector` and
+`foundation-import`, alongside the regular token checks. Shared definitions
+belong on the document root or explicit root themes; ordinary declarations belong
+in `base.css`, and font-face descriptors in optional `fonts.css`. The entry imports
+canonical sheets; those sheets cannot import another styling layer. Component
+classes, IDs, data/ARIA hooks, contextual selectors, keyframes and scoped UI rules
+are rejected in the foundation, including nested functional selectors. Raw visual
+values and undefined token references are checked in native defaults too; literal
+font-face metadata keeps its separate asset role.
+
+`base.css` has three closed roles:
+
+- Document defaults: root/body typography, canvas colors and theme behavior,
+  global text selection and document scrollbars.
+- Native resets: permitted normalization properties and values, such as zero
+  spacing, inherited control typography, list resets and responsive replaced media.
+- Global accessibility: universal `:focus-visible` outline rules, and reduced-motion
+  overrides inside `@media (prefers-reduced-motion: reduce)`.
+
+The `foundation-role` check validates every selector branch, property and value.
+Native selectors are not a bypass: token-backed button backgrounds, flex/grid
+layout, component-specific focus rules and hover/disabled skins are rejected.
+Shared token definitions belong in value sheets, not `base.css`. No project token
+names are embedded in this policy. A zero-specificity `:where()` wrapper does not
+change ownership. Put component design and animation in Linaria owners, and
+scenario layout variations in typed public review-pattern props. Browser review
+still checks the effects and accessibility of permitted defaults.
+
 Own primitive markup, focus, hover, selected, disabled, loading, and motion in
 the primitive. Use typed props for variations. Keep reusable structure and skin
 in colocated Linaria blocks using `css` and `cx` from `@linaria/atomic`.

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/tokens/base.css

@@ -1,3 +1,6 @@
+:root { color-scheme: light; }
+:root[data-theme="dark"] { color-scheme: dark; }
+
 *,
 *::before,
 *::after {
@@ -5,7 +8,7 @@
 }
 
 body {
-  margin: var(--space-0);
+  margin: 0;
   background: var(--bg-canvas);
   color: var(--text-body);
   font-family: var(--font-sans);

package/dist/skills/ads-designer/assets/bootstrap-ds/design-system/tokens/colors.css

@@ -1,5 +1,5 @@
 :root {
-  color-scheme: light;
+
   --bg-canvas: #faf9f6;
   --bg-surface: #fff;
   --bg-hover: #f1efea;
@@ -15,7 +15,7 @@
 }
 
 :root[data-theme="dark"] {
-  color-scheme: dark;
+
   --bg-canvas: #17191e;
   --bg-surface: #20232a;
   --bg-hover: #2c3039;

package/dist/skills/ads-designer/references/cli.md

@@ -55,7 +55,7 @@ If no published distribution exists, build and pack the tooling checkout with
 From inside an existing test project:
 
 ```sh
-ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.1.tgz"
+ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.2.tgz"
 npx --yes --package "$ads_tool_package" ads --help
 npx --yes --package "$ads_tool_package" ads init --framework react --tool-package "$ads_tool_package"
 npm install
@@ -93,7 +93,8 @@ component rules through the project's plugin adapter and `ds.config.json`, then
 run its actual build. Use `lint-config` directly for custom pipeline integration
 or debugging, not as a separate routine setup step.
 
-Use ADS 0.3.1 or later for the shared-resource preview compiler. `mcp` starts stdio
+Use ADS 0.3.2 or later for the closed foundation contract and recoverable
+shared-resource preview compiler. `mcp` starts stdio
 plus its local website; `showcase` starts the browser-only MCP runtime. Open the existing runtime URL from `ads_status` when
 connected; otherwise use `npm run dev:showcase` or the installed `ads showcase`.
 The tool client discovers entries and renders MCP Apps. Init adds the launch

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

@@ -308,6 +308,25 @@ 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.
+Put skin/state/animation in the Linaria owner, and scenario layout variations in
+the public review pattern's typed API. 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

package/dist/skills/ads-import/references/cli.md

@@ -55,7 +55,7 @@ If no published distribution exists, build and pack the tooling checkout with
 From inside an existing test project:
 
 ```sh
-ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.1.tgz"
+ads_tool_package="/absolute/path/to/reqvire-org-ads-0.3.2.tgz"
 npx --yes --package "$ads_tool_package" ads --help
 npx --yes --package "$ads_tool_package" ads init --framework react --tool-package "$ads_tool_package"
 npm install
@@ -93,7 +93,8 @@ component rules through the project's plugin adapter and `ds.config.json`, then
 run its actual build. Use `lint-config` directly for custom pipeline integration
 or debugging, not as a separate routine setup step.
 
-Use ADS 0.3.1 or later for the shared-resource preview compiler. `mcp` starts stdio
+Use ADS 0.3.2 or later for the closed foundation contract and recoverable
+shared-resource preview compiler. `mcp` starts stdio
 plus its local website; `showcase` starts the browser-only MCP runtime. Open the existing runtime URL from `ads_status` when
 connected; otherwise use `npm run dev:showcase` or the installed `ads showcase`.
 The tool client discovers entries and renders MCP Apps. Init adds the launch

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

@@ -198,6 +198,25 @@ 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.
+Put skin/state/animation in the Linaria owner, and scenario layout variations in
+the public review pattern's typed API. 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