@reqvire-org/ads 0.0.0-stage → 0.2.9

package/dist/mcp/apps.mjs

@@ -0,0 +1,53 @@
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import { isInside, projectPath } from "../config.mjs";
+import { PREVIEW_APP_URI } from "../preview-resources.mjs";
+export { PREVIEW_APP_URI };
+
+export const APP_MIME = "text/html;profile=mcp-app";
+export const TOKENS_APP_URI = "ui://ads/tokens";
+export const SCENARIO_APP_URI = "ui://ads/scenario";
+export const appUri = (id) => `ui://ads/previews/${id.split("/").map(encodeURIComponent).join("/")}`;
+const safeJson = (value) => JSON.stringify(value).replaceAll("<", "\\u003c");
+const bridge = (project = false) => readFileSync(new URL(project ? "./project-widget.bundle.js" : "./widget.bundle.js", import.meta.url), "utf8").replaceAll("</script", "<\\/script");
+
+export function previewApp(selection) {
+  const script = readFileSync(new URL("./preview-widget.bundle.js", import.meta.url), "utf8").replaceAll("</script", "<\\/script");
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>ADS preview</title><style>html,body,#root{height:100%;margin:0}body{overflow:hidden}#ads-preview-status{position:fixed;inset:12px 12px auto;z-index:2147483647;padding:12px;border:1px solid GrayText;background:Canvas;color:CanvasText;font:13px system-ui;white-space:pre-wrap}#ads-preview-status[hidden]{display:none}</style></head><body><aside id="ads-preview-status" role="status" hidden></aside><div id="root"></div>${selection ? `<script type="application/json" id="ads-preview-selection">${safeJson(selection)}</script>` : ""}<script type="module">${script}</script></body></html>`;
+}
+
+export function tokenWidgetData(inventory) {
+  const scopes = new Map();
+  for (const token of inventory.tokens) for (const definition of token.definitions) {
+    // Conditional definitions are displayed verbatim; simple theme selectors
+    // also drive the in-frame browser samples, including alias resolution.
+    if (definition.scope.includes("@") || definition.scope.includes(" > ")) continue;
+    if (!scopes.has(definition.scope)) scopes.set(definition.scope, []);
+    scopes.get(definition.scope).push(`${token.name}:${definition.value};`);
+  }
+  return { ...inventory, css: [...scopes].map(([selector, declarations]) => `${selector}{${declarations.join("")}}`).join("\n") };
+}
+
+export function tokensApp(data) {
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>ADS tokens</title><style>
+html{color-scheme:light dark;background:Canvas;color:CanvasText;font:13px/1.55 system-ui}html,body{height:100%}body{margin:0}#ads-token-root{padding:32px}#ads-scenario-root{height:100%}header{display:flex;gap:8px;flex-wrap:wrap;align-items:center}h1{font-size:18px;margin:0 auto 0 0}button,input,select{font:inherit;color:CanvasText;background:Canvas;border:1px solid GrayText;border-radius:4px;padding:6px 8px}ul{padding:0;list-style:none}li{margin:12px 0}summary{cursor:pointer;display:flex;gap:16px;align-items:baseline;flex-wrap:wrap}code{font:12px monospace;overflow-wrap:anywhere}dl{border:1px solid GrayText;padding:12px;overflow-wrap:anywhere}dt{font-weight:600}dd{margin:2px 0 12px}footer{display:flex;gap:8px;align-items:center}iframe{display:block;width:100%;height:100%;border:0}[hidden]{display:none!important}:root[data-theme="light"]{color-scheme:light}:root[data-theme="dark"]{color-scheme:dark}
+  </style></head><body><p id="ads-scenario-status" role="status" hidden></p><main id="ads-scenario-root" hidden></main><main id="ads-token-root"><header><h1>Token definitions</h1><input id="ads-token-search" type="search" aria-label="Find token" placeholder="Find a token"><select id="ads-token-theme" aria-label="Preview theme"><option value="light">Light</option><option value="dark">Dark</option></select><button id="ads-token-refresh" type="button" disabled>Refresh</button></header><p id="ads-widget-status" role="status">Connecting to the Apps host…</p><ul id="ads-token-list"></ul><footer><button id="ads-token-prev" type="button">Previous</button><span id="ads-token-count"></span><button id="ads-token-next" type="button">Next</button></footer></main><script type="application/json" id="ads-token-seed">${safeJson(data)}</script><script type="module">${bridge()}</script></body></html>`;
+}
+
+export function scenarioApp() {
+  return `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>ADS scenario</title><style>html{color-scheme:light dark;background:Canvas;color:CanvasText;font:14px system-ui}html,body,#ads-scenario-root{height:100%}body{margin:0}#ads-widget-status{margin:12px}iframe{display:block;border:0;width:100%;height:100%}</style></head><body><p id="ads-widget-status" role="status">Waiting for a scenario selection…</p><main id="ads-scenario-root"></main><script type="module">${bridge()}</script></body></html>`;
+}
+
+export function projectApp(options, app, build) {
+  const file = projectPath(options.root, app.file, "mcp.apps.file");
+  const real = realpathSync(file);
+  if (real !== file || !isInside(options.root, real)) throw new Error("Preview HTML cannot resolve through a symlink or outside the project.");
+  if (statSync(file).size > 2 * 1024 * 1024) throw new Error("Preview exceeds 2 MiB. Build a focused component/pattern example.");
+  const html = readFileSync(file, "utf8");
+  if (!/<\/body\s*>/i.test(html) || /<script\b[^>]*\bsrc\s*=|<link\b[^>]*\brel\s*=\s*["']?stylesheet\b/i.test(html)) throw new Error("Preview must be built as self-contained HTML, with JavaScript and styles inlined.");
+  const seed = { id: app.id, session: build?.session ?? null, revision: build?.current ? build.revision : null, state: build?.state ?? "unreported" };
+  return html.replace(/<\/body\s*>/i, () => `<script type="application/json" id="ads-preview-seed">${safeJson(seed)}</script><script type="module">${bridge(true)}</script></body>`);
+}
+
+export function appMetadata({ nested = false } = {}) {
+  return { ui: { csp: { connectDomains: [], resourceDomains: ["data:", "blob:"], ...(nested ? { frameDomains: ["about:"] } : {}) } } };
+}

package/dist/mcp/build-status.mjs

@@ -0,0 +1,164 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, realpathSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { isInside, projectPath } from "../config.mjs";
+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 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.");
+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.");
+  return `sha256:${createHash("sha256").update(readFileSync(file)).digest("hex")}`;
+};
+
+function normalizeDiagnostic(root, error) {
+  const location = error?.loc ?? error?.location;
+  const source = location?.file ?? error?.id ?? error?.file;
+  const file = typeof source === "string" ? source.split("?")[0] : null;
+  const line = location?.line ?? error?.line;
+  const column = location?.column !== undefined ? location.column + 1 : error?.column;
+  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) } : {}) };
+}
+
+/** One publisher per project compiler; no dependency on a UI framework. */
+export function createBuildReporter(directory, { apps, session = process.env.ADS_MCP_BUILD_SESSION ?? randomUUID(), file = process.env.ADS_MCP_BUILD_STATUS } = {}) {
+  const root = path.resolve(directory);
+  const target = file ?? buildStatusFile(root);
+  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;
+  function save() {
+    const value = { schemaVersion: 1, session, sequence: ++sequence, updatedAt: new Date().toISOString(), previews: [...entries.values()] };
+    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.
+    if (Buffer.byteLength(text) > maxBytes) {
+      const diagnosticSets = [], sets = new Map();
+      const previews = value.previews.map(entry => {
+        if (!entry.diagnostics.length) return entry;
+        const key = JSON.stringify(entry.diagnostics);
+        if (!sets.has(key)) { sets.set(key, diagnosticSets.length); diagnosticSets.push(entry.diagnostics); }
+        return { ...entry, diagnostics: [], diagnosticSet: sets.get(key) };
+      });
+      text = JSON.stringify(snapshot.parse({ ...value, previews, diagnosticSets }));
+    }
+    if (Buffer.byteLength(text) > maxBytes) throw new Error("Build status exceeds 256 KiB. Keep diagnostics bounded.");
+    mkdirSync(path.dirname(target), { recursive: true });
+    if (realpathSync(path.dirname(target)) !== path.dirname(target)) throw new Error("Build status cannot resolve through a symlink.");
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    try { writeFileSync(temporary, text); renameSync(temporary, target); }
+    finally { rmSync(temporary, { force: true }); }
+  }
+  function entry(id, revision) {
+    const value = entries.get(id);
+    if (!value) throw new Error(`Unknown preview ID: ${id}`);
+    return revision === undefined || value.revision === revision ? value : null;
+  }
+  save();
+  return {
+    session,
+    setApps(next) {
+      const ids = new Set(next.map(app => app.id));
+      for (const id of entries.keys()) if (!ids.has(id)) entries.delete(id);
+      for (const app of next) if (!entries.has(app.id)) entries.set(app.id, { id: app.id, state: "idle", revision: 0, lastSuccessfulRevision: null, artifactDigest: null, diagnostics: [] });
+      apps = next;
+      save();
+    },
+    begin(id) {
+      const value = entry(id);
+      value.state = "building";
+      value.revision++;
+      value.diagnostics = [];
+      save();
+      return value.revision;
+    },
+    ready(id, revision) {
+      const value = entry(id, revision);
+      if (!value) return false; // An older build cannot clear a newer failure/invalidation.
+      const app = apps.find((app) => app.id === id);
+      value.artifactDigest = artifactDigest(projectPath(root, app.file, "mcp.apps.file"));
+      value.state = "ready";
+      value.lastSuccessfulRevision = revision;
+      value.diagnostics = [];
+      save();
+      return true;
+    },
+    error(id, revision, failure) {
+      const value = entry(id, revision);
+      if (!value) return false;
+      value.state = "error";
+      value.diagnostics = (Array.isArray(failure) ? failure : [failure]).slice(0, 20).map((error) => normalizeDiagnostic(root, error));
+      save();
+      return true;
+    },
+  };
+}
+
+/** Read durable build events; a running process alone never means a fresh build. */
+export function inspectBuildStatus(root, config, { session, processState } = {}) {
+  let report;
+  let reportError;
+  const file = buildStatusFile(root);
+  try {
+    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")));
+      if (session && report.session !== session) report = undefined;
+    }
+  } catch (error) { reportError = `Invalid preview build status: ${error.message.slice(0, 500)}`; }
+  let graphError;
+  if (config.previewManifest && report?.previews.some(entry => entry.state === "ready")) {
+    try {
+      if (!readPreviewManifest({ root, config: { mcp: config } }, { verify: true })) throw new Error("Preview resource manifest is missing.");
+    } catch (error) { graphError = `Invalid preview resource graph: ${error.message}`; }
+  }
+  const previews = config.apps.map((app) => {
+    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 ?? [];
+    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 }]; }
+    if (state === "ready") {
+      try {
+        if (value.lastSuccessfulRevision !== value.revision || artifactDigest(path.resolve(root, app.file)) !== value.artifactDigest) throw new Error("Preview output does not match its successful build. Rebuild before reviewing it.");
+      } catch (error) { state = "error"; diagnostics = [{ message: error.message }]; }
+    }
+    if (processState?.state === "failed") { state = "error"; diagnostics = [{ message: processState.error ?? "Preview watcher exited." }, ...diagnostics].slice(0, 20); }
+    if (["stopped", "stopping", "idle"].includes(processState?.state)) state = "unreported";
+    const current = state === "ready";
+    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 };
+}
+
+export class PreviewBuildError extends Error {
+  constructor(message, build) { super(message); this.build = build; }
+}
+
+/** Keep diagnostics useful in model-visible tool results; resources retain detail. */
+export function summarizeBuild(build) {
+  function bounded(value) {
+    const diagnostics = value.diagnostics.slice(0, 3).map((entry) => ({ ...entry, message: entry.message.slice(0, 1000) }));
+    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 };
+}
+
+export function buildFailure(build) {
+  const summary = summarizeBuild(build);
+  const details = summary.diagnostics.map((entry) => `${entry.file ?? ""}${entry.line ? `:${entry.line}` : ""}${entry.file ? ": " : ""}${entry.message}`).join("\n");
+  return new PreviewBuildError(`Preview build failed. ${details}${summary.diagnosticsTruncated ? `\nMore diagnostic detail: ${BUILD_URI}` : ""}`, summary);
+}

package/dist/mcp/catalog.mjs

@@ -0,0 +1,65 @@
+import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+import { isInside, sourceFiles } from "../config.mjs";
+import { projectCompilerOptions } from "../boundaries.mjs";
+import { publicUi } from "../scenarios.mjs";
+import { projectGuideFiles } from "../project-documents.mjs";
+
+export const PROJECT_URI = "ads://project";
+export const sourceUri = (file) => `${PROJECT_URI}/files/${file.split("/").map(encodeURIComponent).join("/")}`;
+
+export function projectDocuments(options) {
+  const { root, dsRoot } = options;
+  const files = sourceFiles(dsRoot);
+  function docs(directory) {
+    // Documentation is intentionally confined to the ADS; no arbitrary filesystem reader.
+    for (const name of ["README.md", "readme.md", "SKILL.md", "LICENSE", "LICENSE.md"]) {
+      const file = path.join(directory, name);
+      if (existsSync(file) && statSync(file).isFile()) files.push(file);
+    }
+  }
+  for (const directory of new Set(files.map((file) => path.dirname(file)))) docs(directory);
+  docs(dsRoot);
+  for (const name of projectGuideFiles(root)) files.push(path.join(root, name));
+  return [...new Set(files)].filter((file) => isInside(root, realpathSync(file))).sort().map((file) => {
+    const relative = path.relative(root, file).replaceAll("\\", "/");
+    return { uri: sourceUri(relative), name: relative, mimeType: file.endsWith(".md") ? "text/markdown" : "text/plain", file };
+  });
+}
+
+export function inspectCatalog(options, scenarios = []) {
+  const { root, dsRoot, config } = options;
+  const entry = path.join(dsRoot, config.publicEntry);
+  if (!existsSync(entry)) return [];
+  const program = ts.createProgram([entry], projectCompilerOptions(options));
+  const checker = program.getTypeChecker();
+  const source = program.getSourceFile(entry);
+  const module = source && checker.getSymbolAtLocation(source);
+  if (!module) return [];
+  const documents = projectDocuments(options);
+  const items = [];
+  const renderable = new Set(publicUi(program, options).filter(item => item.renderable).map(item => item.name));
+  for (const exported of checker.getExportsOfModule(module)) {
+    let symbol = exported;
+    if (symbol.flags & ts.SymbolFlags.Alias) symbol = checker.getAliasedSymbol(symbol);
+    const declaration = symbol.valueDeclaration ?? symbol.declarations?.[0];
+    if (!(symbol.flags & ts.SymbolFlags.Value) || !declaration || !renderable.has(exported.name)) continue;
+    const file = declaration.getSourceFile().fileName;
+    const kind = isInside(path.join(dsRoot, "components"), file) ? "components" : isInside(path.join(dsRoot, "patterns"), file) ? "patterns" : null;
+    if (!kind) continue;
+    const relative = path.relative(root, file).replaceAll("\\", "/");
+    const line = declaration.getSourceFile().getLineAndCharacterOfPosition(declaration.getStart()).line + 1;
+    const guides = documents.filter((doc) => doc.file.endsWith(".md") && path.dirname(doc.file) === path.dirname(file)).map((doc) => doc.uri);
+    items.push({ name: exported.name, kind, importFrom: config.publicAlias, file: relative, line, sourceUri: sourceUri(relative), guides,
+      previews: scenarios.filter(item => item.covers.includes(exported.name)).map(item => item.id) });
+  }
+  return items.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+export function readProjectDocument(document) {
+  // Recheck after discovery so replacing an allowed file with a symlink cannot escape.
+  if (realpathSync(document.file) !== document.file) throw new Error("Project resource cannot resolve through a symlink.");
+  if (statSync(document.file).size > 2 * 1024 * 1024) throw new Error("Project resource exceeds the 2 MiB limit.");
+  return readFileSync(document.file, "utf8");
+}

package/dist/mcp/context.mjs

@@ -0,0 +1,69 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { sourceUri } from "./catalog.mjs";
+import { projectGuideFiles } from "../project-documents.mjs";
+
+export const GUIDE_URI = "ads://project/guide";
+// Put the task triggers and entry path first: some hosts shorten server guidance.
+export const serverInstructions = "Use ADS for UI work: components, patterns, tokens, themes, branding, layout, interaction, accessibility, motion and showcase review. Start with ads_status; if tools are not exposed, read ads://project/guide then ads://project/status. Use the returned projectRoot and commands. When ads_status.mutations.enabled, use ads_units and guarded ads_apply_patch for one owner at a time. Find existing public UI with ads_catalog; discover its previews with ads_scenarios and open ads_show_scenario. Starting ADS also serves its built-in showcase: use ads_status.showcaseUrl for browser review instead of starting another runtime/compiler or project browser app. Read one relevant ADS skill before editing. Inspect the real preview, edit its owned source, check the build and review again. Scope source/guides to the project, its instruction ancestry and user-selected import/reference sources; broad searches of /mnt or home are not ADS discovery. Domain-model/requirements work is a separate project workflow. MCP source checks do not replace browser tests; direct edits still need project checks. Reading HTML is not rendering, and reading a skill is not native activation. A running watcher is not proof of current source: inspect ads_status.build or ads://project/build after edits. Notifications may not reach the agent. Only explicitly enabled mutation tools edit project-owned ADS units after validation. Checks and compiler commands come from validated project configuration, never an ad hoc command argument.";
+
+function manager(root, pkg) {
+  if (typeof pkg.packageManager === "string") return pkg.packageManager.split("@")[0];
+  const candidates = [["bun", "bun.lock"], ["bun", "bun.lockb"], ["npm", "package-lock.json"], ["pnpm", "pnpm-lock.yaml"], ["yarn", "yarn.lock"]];
+  const found = [...new Set(candidates.filter(([, file]) => existsSync(path.join(root, file))).map(([name]) => name))];
+  return found.length > 1 ? null : found[0] ?? "npm";
+}
+
+export function projectContext(options) {
+  const { root, dsRoot, sourceRoot, config } = options;
+  let pkg = {};
+  try { pkg = JSON.parse(readFileSync(path.join(root, "package.json"), "utf8")); } catch { /* A partial ADS can still be inspected. */ }
+  const packageManager = manager(root, pkg);
+  const scripts = pkg.scripts ?? {};
+  const commands = ["ads-mcp", "ads-read-mcp", "dev:showcase", "build:showcase", "build:mcp-previews", "lint:ds", "lint", "lint:style", "typecheck", "test", "build"].filter((name) => typeof scripts[name] === "string").map((script) => ({ script, cwd: root, args: packageManager ? [packageManager, "run", script] : null }));
+  const guides = [...projectGuideFiles(root), path.join(config.dsDir, "README.md"), path.join(config.dsDir, "readme.md"), path.join(config.dsDir, "SKILL.md")].filter((file) => existsSync(path.join(root, file))).map((file) => ({ file: file.replaceAll("\\", "/"), uri: sourceUri(file.replaceAll("\\", "/")) }));
+  return { name: pkg.name ?? path.basename(root), projectRoot: root, dsRoot, sourceRoot, framework: config.framework,
+    publicEntry: path.join(dsRoot, config.publicEntry), publicEntryUri: existsSync(path.join(dsRoot, config.publicEntry)) ? sourceUri(path.relative(root, path.join(dsRoot, config.publicEntry)).replaceAll("\\", "/")) : null,
+    stylesEntry: path.join(dsRoot, config.stylesEntry), packageManager, commands, guides,
+    showcase: { client: "tool-owned-mcp", url: config.mcp.showcaseUrl, title: config.mcp.showcaseTitle ?? `${pkg.name ?? path.basename(root)} · Design System` },
+    runtime: { node: process.execPath, nodeBinDir: path.dirname(process.execPath), nodeVersion: process.version,
+      shellHint: "The agent shell may have a different PATH from MCP. If npm is missing, check this Node bin directory and prepend it to the shell PATH when npm is installed there; do not search the whole machine or assume a reinstall is needed." } };
+}
+
+export function workflow(previews) {
+  return { guideUri: GUIDE_URI,
+    next: "Find the requested public UI with ads_catalog (query + kind + small limit), then read its source/guide and one selected ADS skill. For a broad UI request, inspect the public barrel and targeted application entry files in sourceRoot.",
+    skills: [
+      { task: "Build, refine or debug UI using the project ADS", name: "ads-designer" },
+      { task: "Adapt a component-library reference", name: "ads-assimilate" },
+      { task: "Import from another project's design-system", name: "ads-import" },
+      { task: "Implement or review motion", name: "ads-motion" },
+      { task: "Stress-test layout, states and interactions", name: "ads-break-ui" },
+    ],
+    preview: previews.length ? "Use ads_scenarios to select an exact path-derived id, then ads_show_scenario. Public UI and related parts share addressable scenarios; composition/ holds larger scenarios. Showcase and MCP mount the same source with colocated fixtures. The showcase is the tool's minimal MCP client and Apps host; it discovers these entries and invokes the same preview tools. Both transports share the managed project compiler. A reusable sandboxed App loads selected modules and shared runtime/CSS/fonts through MCP resources; no project code or styling belongs in the outer host. Check build freshness after changes."
+      : "No component scenarios or legacy Apps are registered. Token inspection is available in the built-in showcase. Existing components need colocated independently mountable scenarios/fixtures and a project compiler before MCP can render them. Do not create a replica or separate browser app to get a preview.",
+    validation: "Use ads_check for core architecture diagnostics, then run the project's registered lint/typecheck/build and relevant tests from projectRoot. Core checks do not replace those commands. Review real UI in both themes; HTML delivery and compilation do not prove visual/behavioral correctness." };
+}
+
+export function projectGuide(context, previews) {
+  const route = workflow(previews);
+  return `# Start here: project design-system work
+
+Use this server for UI components/patterns, tokens/themes/branding, layout, interaction, accessibility, motion and showcase review. Domain-model/requirements workflows are separate. Follow the project's actual instructions; this guide does not override them.
+
+1. Call ads_status (or read ads://project/status) to establish the exact workspace and capabilities. Project root: ${context.projectRoot}. ADS source: ${context.dsRoot}. Application source: ${context.sourceRoot}. The MCP project root may differ from the client's repository root.
+2. ${route.next} Public barrel resource: ${context.publicEntryUri ?? "missing; run ads_check and use ads-designer for setup"}. Normal targeted filesystem reads remain useful for editing and application integration; do not scan /mnt or home directories to rediscover this ADS.
+3. Select one workflow with ads_skills, then ads_read_skill. ${route.skills.map((skill) => `${skill.task}: ${skill.name}`).join("; ")}. Native skill activation is host-controlled. Relative skill references resolve from its SKILL.md URI. Read support files only when relevant.
+4. ${route.preview} Token samples: ads_scenarios(kind: tokens), then ads_show_scenario or ads_show_tokens(category: id). Token source inspection: ads_tokens with a focused query. Registered previews: ${previews.map((preview) => `${preview.id}: ${preview.tool ?? "ads_show_scenario"}`).join(", ") || "none"}. Showcase URL: ${context.showcase.url ?? "not configured; use the project's showcase command"}.
+   Inspection connects a public export to its owning source, available guides, token values and discovered preview IDs. Bounded tools keep discovery focused; explicit resource reads supply detail. Source metadata does not prove layout, interaction or motion. A scenario renders the real public implementation and its fixture context in either review surface.
+5. Check ads_status.mutations. When enabled, discover one owner with ads_units, read relevant source ranges with ads_read_file and submit only a Git unified diff through ads_apply_patch({unit, patch, dryRun}). Include that owner's scenarios, fixtures and required public re-exports, never peer units. tokens is the foundation unit. Dry-run to inspect validation; apply only a passing patch. Fix rejected patches in the owning unit. Intentional project setup, registered guard/compiler code and exceptions use configuration; shared globals use foundation, guides documentation and assets their discovered assets/* unit. Keep mandatory ADS gates. Binary/large Git diffs may use patchFile under .ds/patches/ to avoid model-context bytes. In read-only mode, source edits use the client editor/filesystem tools. Reuse the local public API (${context.publicEntry}). Edit presentation in its ADS owner; keep application data/services/routing in application code and development fixtures beside their scenario; larger scenarios live in composition/. Linaria extracts owned styling. Inspect relevant tokens with ads_tokens and source/owning guides before edits.
+6. ${route.validation} Registered commands: ${context.commands.map((command) => command.args?.join(" ") ?? `choose the project package manager for ${command.script}`).join("; ") || "none discovered; inspect the project's build setup"}. Run them from ${context.projectRoot}.
+7. After edits, inspect ads_status.build or ads://project/build explicitly. Running/unreported/old output is not a current successful preview. Fix diagnostics in owned source, wait for rebuilding and invoke the preview tool again. Notifications may not start an agent turn.
+
+Project guide resources: ${context.guides.map((guide) => `${guide.file}: ${guide.uri}`).join("; ") || "none discovered"}.
+
+Node executable: ${context.runtime.node}. Node bin directory: ${context.runtime.nodeBinDir}. ${context.runtime.shellHint}
+
+If the client exposes resources but no ADS tools, this guide and the project status/public-barrel/guide resources provide the entry path. Use the returned local paths for scoped source inspection and project commands. Do not claim a resource-only connection offers ADS tool calls, native Skills activation or a rendered App. Configure/enable the tools in the client when required; project edits still use local editor/filesystem tools.
+`;
+}