@stackwright-pro/mcp 0.2.0-alpha.107 → 0.2.0-alpha.109

package/dist/server.mjs

@@ -1310,6 +1310,10 @@ function answersToManifestFormat(answers, questions) {
 // src/validation.ts
 var SAFE_PHASE = /^[a-z][a-z0-9-]{0,30}$/;
 var SAFE_QUESTION_ID = /^[a-z0-9][a-z0-9-]{0,63}$/i;
+var SAFE_SLUG = /^[a-z0-9][a-z0-9-]{0,79}$/;
+function isValidSlug(slug) {
+  return SAFE_SLUG.test(slug);
+}
 function isValidPhase(phase) {
   return SAFE_PHASE.test(phase);
 }
@@ -1999,9 +2003,9 @@ function registerOrchestrationTools(server2) {
 
 // src/tools/pipeline.ts
 import { z as z13 } from "zod";
-import { readFileSync as readFileSync6, writeFileSync as writeFileSync4, existsSync as existsSync6, mkdirSync as mkdirSync4, lstatSync as lstatSync6 } from "fs";
+import { readFileSync as readFileSync7, writeFileSync as writeFileSync4, existsSync as existsSync7, mkdirSync as mkdirSync4, lstatSync as lstatSync6, readdirSync as readdirSync5 } from "fs";
 import { lockSync } from "proper-lockfile";
-import { join as join6 } from "path";
+import { join as join7 } from "path";
 import { createHash as createHash3 } from "crypto";
 
 // src/artifact-signing.ts
@@ -2544,6 +2548,234 @@ function formatPulseRetryPrompt(result) {
   return lines.join("\n");
 }
 
+// src/tools/validate-api-integration.ts
+var CANONICAL_API_AUTH_TYPES = ["apiKey", "bearer", "oauth2", "oidc", "none"];
+var CANONICAL_SET = new Set(CANONICAL_API_AUTH_TYPES);
+var VALID_SET_DISPLAY = CANONICAL_API_AUTH_TYPES.map((t) => `\`${t}\``).join(", ");
+var RENAME_MAP = {
+  // apiKey variants
+  "api-key": "apiKey",
+  api_key: "apiKey",
+  apikey: "apiKey",
+  // lowercase of 'apiKey' / 'APIKEY'
+  // oauth2 variants
+  "oauth-2": "oauth2",
+  oauth_2: "oauth2",
+  // oidc variants
+  "open-id-connect": "oidc",
+  "openid-connect": "oidc",
+  openidconnect: "oidc",
+  // lowercase of 'openIdConnect'
+  openidconnect_: "oidc",
+  // belt-and-suspenders
+  openIdConnect: "oidc",
+  // exact camelCase as emitted by some tooling
+  // bearer variants
+  "bearer-token": "bearer",
+  bearer_token: "bearer"
+};
+function renameSuggestion(badLiteral) {
+  return RENAME_MAP[badLiteral] ?? RENAME_MAP[badLiteral.toLowerCase()];
+}
+function validateAuthType(authType, yamlPath, artifactPath) {
+  if (authType === void 0 || authType === null) return null;
+  if (typeof authType !== "string") {
+    return [
+      `${artifactPath}: \`${yamlPath}\` must be a string, got \`${typeof authType}\`.`,
+      `Valid values: ${VALID_SET_DISPLAY}.`,
+      "Fix this value and re-call stackwright_pro_validate_artifact."
+    ].join("\n");
+  }
+  if (CANONICAL_SET.has(authType)) return null;
+  const suggestion = renameSuggestion(authType);
+  const lines = [
+    `${artifactPath}: \`${yamlPath}\` has non-canonical value \`"${authType}"\`.`,
+    `Valid values: ${VALID_SET_DISPLAY}.`
+  ];
+  if (suggestion) {
+    lines.push(`Did you mean: \`${suggestion}\`?`);
+  }
+  lines.push("Fix this value and re-call stackwright_pro_validate_artifact.");
+  return lines.join("\n");
+}
+function validateApiIntegration(artifact, integrationName) {
+  const artifactFile = integrationName ? `api-config-${integrationName}.json` : "api-config.json";
+  const artifactPath = `.stackwright/artifacts/${artifactFile}`;
+  if (artifact === null || typeof artifact !== "object") {
+    return { valid: true };
+  }
+  const obj = artifact;
+  const errors = [];
+  if ("auth" in obj && obj["auth"] !== null && typeof obj["auth"] === "object") {
+    const auth = obj["auth"];
+    const err = validateAuthType(auth["type"], "auth.type", artifactPath);
+    if (err) errors.push(err);
+  }
+  if ("securitySchemes" in obj && obj["securitySchemes"] !== null && typeof obj["securitySchemes"] === "object" && !Array.isArray(obj["securitySchemes"])) {
+    const schemes = obj["securitySchemes"];
+    for (const [schemeName, scheme] of Object.entries(schemes)) {
+      if (scheme !== null && typeof scheme === "object") {
+        const s = scheme;
+        const err = validateAuthType(s["type"], `securitySchemes.${schemeName}.type`, artifactPath);
+        if (err) errors.push(err);
+      }
+    }
+  }
+  if (errors.length === 0) return { valid: true };
+  const retryPrompt = [
+    `API integration auth validation failed: ${errors.length} violation(s) in ${artifactPath}.`,
+    "",
+    "You MUST fix ALL violations and re-call stackwright_pro_validate_artifact.",
+    "",
+    ...errors.flatMap((e) => [e, ""]),
+    `Canonical auth.type values: ${VALID_SET_DISPLAY}.`,
+    "Do NOT use hyphenated or underscored variants (api-key, oauth-2, bearer-token, etc.)."
+  ].join("\n");
+  return { valid: false, retryPrompt };
+}
+
+// src/tools/validate-auth-config.ts
+var KNOWN_NESTED_STRATEGIES = ["oidc", "pki"];
+var NESTED_STRATEGY_FIELD_EXAMPLES = {
+  oidc: ["discoveryUrl", "clientId", "clientSecret"],
+  pki: ["profile", "source", "headerPrefix"]
+};
+function nestedBlockError(strategy, nestedObj, artifactPath) {
+  const exampleFields = NESTED_STRATEGY_FIELD_EXAMPLES[strategy];
+  const actualKeys = Object.keys(nestedObj).slice(0, 2);
+  const showField0 = actualKeys[0] ?? exampleFields[0];
+  const showField1 = actualKeys[1] ?? exampleFields[1];
+  return [
+    `${artifactPath}: \`authConfig.${strategy}\` must not be a nested provider block.`,
+    `Hoist \`authConfig.${strategy}.*\` fields to \`authConfig.*\`. The canonical AuthConfig`,
+    `schema does not nest provider-specific fields under a named sub-object.`,
+    ``,
+    `Bad (nested block):`,
+    `  "authConfig": {`,
+    `    "type": "${strategy}",`,
+    `    "${strategy}": {`,
+    `      "${showField0}": "...",`,
+    `      "${showField1}": "...",`,
+    `      ...`,
+    `    }`,
+    `  }`,
+    ``,
+    `Correct (hoisted to root of authConfig):`,
+    `  "authConfig": {`,
+    `    "type": "${strategy}",`,
+    `    "${exampleFields[0]}": "...",`,
+    `    "${exampleFields[1]}": "...",`,
+    `    "${exampleFields[2]}": "...",`,
+    `    ...`,
+    `  }`,
+    ``,
+    `Move every key from \`authConfig.${strategy}\` up to \`authConfig\` and remove the \`"${strategy}"\` sub-object.`
+  ].join("\n");
+}
+function discriminatorKeyError(methodVal, artifactPath) {
+  return [
+    `${artifactPath}: \`authConfig.method\` is not a valid key in the canonical AuthConfig schema.`,
+    `Rename \`authConfig.method\` \u2192 \`authConfig.type\`. The canonical AuthConfig schema uses`,
+    `\`type\` as the auth-strategy discriminator, matching the api-config \`auth.type\` convention`,
+    `shipped in swp-fimq.`,
+    ``,
+    `Bad:`,
+    `  "authConfig": { "method": "${methodVal}", ... }`,
+    ``,
+    `Correct:`,
+    `  "authConfig": { "type": "${methodVal}", ... }`
+  ].join("\n");
+}
+function ambiguousDiscriminatorError(methodVal, typeVal, artifactPath) {
+  return [
+    `${artifactPath}: \`authConfig\` has both \`method: "${methodVal}"\` and \`type: "${typeVal}"\` \u2014 ambiguous discriminator.`,
+    `Remove \`authConfig.method\` and keep only \`authConfig.type\`. The canonical AuthConfig`,
+    `schema uses \`type\` as the sole auth-strategy discriminator.`
+  ].join("\n");
+}
+function validateAuthConfig(artifact, artifactPath) {
+  if (artifact === null || typeof artifact !== "object") {
+    return { valid: true };
+  }
+  const obj = artifact;
+  if (!("authConfig" in obj) || obj["authConfig"] === void 0 || obj["authConfig"] === null) {
+    return { valid: true };
+  }
+  if (typeof obj["authConfig"] !== "object" || Array.isArray(obj["authConfig"])) {
+    return { valid: true };
+  }
+  const authConfig = obj["authConfig"];
+  const errors = [];
+  const hasMethod = "method" in authConfig && authConfig["method"] !== void 0;
+  const hasType = "type" in authConfig && authConfig["type"] !== void 0;
+  if (hasMethod && hasType) {
+    errors.push(
+      ambiguousDiscriminatorError(
+        String(authConfig["method"]),
+        String(authConfig["type"]),
+        artifactPath
+      )
+    );
+  } else if (hasMethod && !hasType) {
+    errors.push(discriminatorKeyError(String(authConfig["method"]), artifactPath));
+  }
+  for (const strategy of KNOWN_NESTED_STRATEGIES) {
+    const nested = authConfig[strategy];
+    if (nested !== null && nested !== void 0 && typeof nested === "object" && !Array.isArray(nested)) {
+      errors.push(nestedBlockError(strategy, nested, artifactPath));
+    }
+  }
+  if (errors.length === 0) return { valid: true };
+  const retryPrompt = [
+    `Auth config validation failed: ${errors.length} violation(s) in ${artifactPath}.`,
+    ``,
+    `You MUST fix ALL violations and re-call stackwright_pro_validate_artifact.`,
+    ``,
+    ...errors.flatMap((e) => [e, ""]),
+    `The canonical authConfig shape uses \`type\` (not \`method\`) as the discriminator,`,
+    `with all provider-specific fields hoisted to the root of \`authConfig\`.`,
+    `AuthConfig is a discriminated union on \`type: 'oidc' | 'pki'\`.`
+  ].join("\n");
+  return { valid: false, retryPrompt };
+}
+
+// src/tools/auth-manifest-aggregator.ts
+import { existsSync as existsSync6, readFileSync as readFileSync5, readdirSync as readdirSync3 } from "fs";
+import { join as join5 } from "path";
+function extractPatternBaseSlug(pattern) {
+  const stripped = pattern.replace(/^\//, "");
+  if (!stripped) return null;
+  return stripped.split("/")[0] ?? null;
+}
+function extractManifestSlugs(artifactsDir) {
+  const slugs = /* @__PURE__ */ new Set();
+  if (!existsSync6(artifactsDir)) return slugs;
+  let entries;
+  try {
+    entries = readdirSync3(artifactsDir);
+  } catch {
+    return slugs;
+  }
+  for (const entry of entries) {
+    if (!entry.endsWith("-manifest.json")) continue;
+    try {
+      const content = JSON.parse(readFileSync5(join5(artifactsDir, entry), "utf-8"));
+      const pages = content.pages;
+      if (!Array.isArray(pages)) continue;
+      for (const page of pages) {
+        if (typeof page.slug !== "string" || !page.slug) continue;
+        const firstSeg = page.slug.split("/")[0];
+        if (firstSeg) slugs.add(firstSeg);
+        if (!page.slug.includes("[") && !page.slug.includes(":")) {
+          slugs.add(page.slug);
+        }
+      }
+    } catch {
+    }
+  }
+  return slugs;
+}
+
 // src/tools/pipeline.ts
 import { WorkflowFileSchema, authConfigSchema as authConfigSchema3 } from "@stackwright-pro/types";
 
@@ -2894,8 +3126,8 @@ function registerGetSchemaTool(server2) {
 }
 
 // src/tools/pipeline-graph.ts
-import { readFileSync as readFileSync5, readdirSync as readdirSync3, lstatSync as lstatSync5 } from "fs";
-import { join as join5 } from "path";
+import { readFileSync as readFileSync6, readdirSync as readdirSync4, lstatSync as lstatSync5 } from "fs";
+import { join as join6 } from "path";
 var MANIFEST_NAME_TO_PHASE = {
   "stackwright-pro-designer-otter": "designer",
   "stackwright-pro-theme-otter": "theme",
@@ -2925,7 +3157,7 @@ var OTTER_SEARCH_PATHS = [
 function resolveOtterDirFromCwd() {
   const cwd = process.cwd();
   for (const relative2 of OTTER_SEARCH_PATHS) {
-    const candidate = join5(cwd, relative2);
+    const candidate = join6(cwd, relative2);
     try {
       lstatSync5(candidate);
       return candidate;
@@ -2937,14 +3169,14 @@ function resolveOtterDirFromCwd() {
   );
 }
 function loadOtterManifestsFromDir(otterDir) {
-  const entries = readdirSync3(otterDir);
+  const entries = readdirSync4(otterDir);
   const manifests = [];
   for (const filename of entries) {
     if (!filename.endsWith("-otter.json")) continue;
-    const filePath = join5(otterDir, filename);
+    const filePath = join6(otterDir, filename);
     if (lstatSync5(filePath).isSymbolicLink()) continue;
     try {
-      const raw = readFileSync5(filePath, "utf-8");
+      const raw = readFileSync6(filePath, "utf-8");
       const manifest = JSON.parse(raw);
       manifests.push(manifest);
     } catch (err) {
@@ -3049,19 +3281,19 @@ var DISTRIBUTED_NAMESPACES = ["@stackwright-pro", "@stackwright"];
 function loadDistributedOtterManifests(cwd) {
   const results = [];
   for (const namespace of DISTRIBUTED_NAMESPACES) {
-    const nsDir = join5(cwd, "node_modules", namespace);
+    const nsDir = join6(cwd, "node_modules", namespace);
     let pkgDirNames;
     try {
-      pkgDirNames = readdirSync3(nsDir);
+      pkgDirNames = readdirSync4(nsDir);
     } catch {
       continue;
     }
     for (const pkgDirName of pkgDirNames) {
-      const pkgDir = join5(nsDir, pkgDirName);
+      const pkgDir = join6(nsDir, pkgDirName);
       const packageName = `${namespace}/${pkgDirName}`;
       let otterRelPaths;
       try {
-        const raw = readFileSync5(join5(pkgDir, "package.json"), "utf-8");
+        const raw = readFileSync6(join6(pkgDir, "package.json"), "utf-8");
         const pkgJson = JSON.parse(raw);
         const declared = pkgJson.stackwright?.otters;
         if (!Array.isArray(declared) || declared.length === 0) continue;
@@ -3070,9 +3302,9 @@ function loadDistributedOtterManifests(cwd) {
         continue;
       }
       for (const relPath of otterRelPaths) {
-        const otterFilePath = join5(pkgDir, relPath);
+        const otterFilePath = join6(pkgDir, relPath);
         try {
-          const raw = readFileSync5(otterFilePath, "utf-8");
+          const raw = readFileSync6(otterFilePath, "utf-8");
           const manifest = JSON.parse(raw);
           results.push({ manifest, packageName });
         } catch (err) {
@@ -3190,11 +3422,11 @@ function createDefaultState() {
   };
 }
 function statePath(cwd) {
-  return join6(cwd, ".stackwright", "pipeline-state.json");
+  return join7(cwd, ".stackwright", "pipeline-state.json");
 }
 function readState(cwd) {
   const p = statePath(cwd);
-  if (!existsSync6(p)) return createDefaultState();
+  if (!existsSync7(p)) return createDefaultState();
   const raw = JSON.parse(safeReadSync(p));
   if (typeof raw !== "object" || raw === null || raw.version !== "1.0") {
     return createDefaultState();
@@ -3202,7 +3434,7 @@ function readState(cwd) {
   return raw;
 }
 function safeWriteSync(filePath, content) {
-  if (existsSync6(filePath)) {
+  if (existsSync7(filePath)) {
     const stat = lstatSync6(filePath);
     if (stat.isSymbolicLink()) {
       throw new Error(`Refusing to write to symlink: ${filePath}`);
@@ -3211,25 +3443,25 @@ function safeWriteSync(filePath, content) {
   writeFileSync4(filePath, content);
 }
 function safeReadSync(filePath) {
-  if (existsSync6(filePath)) {
+  if (existsSync7(filePath)) {
     const stat = lstatSync6(filePath);
     if (stat.isSymbolicLink()) {
       throw new Error(`Refusing to read symlink: ${filePath}`);
     }
   }
-  return readFileSync6(filePath, "utf-8");
+  return readFileSync7(filePath, "utf-8");
 }
 function writeState(cwd, state) {
-  const dir = join6(cwd, ".stackwright");
+  const dir = join7(cwd, ".stackwright");
   mkdirSync4(dir, { recursive: true });
   state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
   safeWriteSync(statePath(cwd), JSON.stringify(state, null, 2) + "\n");
 }
 function updateStateAtomic(cwd, mutator) {
-  const dir = join6(cwd, ".stackwright");
+  const dir = join7(cwd, ".stackwright");
   mkdirSync4(dir, { recursive: true });
   const path5 = statePath(cwd);
-  if (!existsSync6(path5)) {
+  if (!existsSync7(path5)) {
     safeWriteSync(path5, JSON.stringify(createDefaultState(), null, 2) + "\n");
   }
   const release = lockSync(path5, {
@@ -3263,8 +3495,8 @@ function handleGetPipelineState(_cwd) {
   const cwd = _cwd ?? process.cwd();
   try {
     const state = readState(cwd);
-    const keyPath = join6(cwd, ".stackwright", "pipeline-keys.json");
-    if (!existsSync6(keyPath)) {
+    const keyPath = join7(cwd, ".stackwright", "pipeline-keys.json");
+    if (!existsSync7(keyPath)) {
       try {
         const { fingerprint } = initPipelineKeys(cwd);
         state["signingKeyFingerprint"] = fingerprint;
@@ -3395,8 +3627,8 @@ function handleCheckExecutionReady(_cwd, phase) {
         isError: true
       };
     }
-    const answerFile = join6(cwd, ".stackwright", "answers", `${phase}.json`);
-    if (!existsSync6(answerFile)) {
+    const answerFile = join7(cwd, ".stackwright", "answers", `${phase}.json`);
+    if (!existsSync7(answerFile)) {
       return {
         text: JSON.stringify({ ready: false, phase, reason: "Answer file not found" }),
         isError: false
@@ -3420,12 +3652,12 @@ function handleCheckExecutionReady(_cwd, phase) {
     }
   }
   try {
-    const answersDir = join6(cwd, ".stackwright", "answers");
+    const answersDir = join7(cwd, ".stackwright", "answers");
     const answeredPhases = [];
     const missingPhases = [];
     for (const phase2 of PHASE_ORDER) {
-      const answerFile = join6(answersDir, `${phase2}.json`);
-      if (existsSync6(answerFile)) {
+      const answerFile = join7(answersDir, `${phase2}.json`);
+      if (existsSync7(answerFile)) {
         try {
           const raw = safeReadSync(answerFile);
           const parsed = JSON.parse(raw);
@@ -3494,7 +3726,7 @@ function handleGetReadyPhases(_cwd) {
 function handleListArtifacts(_cwd) {
   const cwd = _cwd ?? process.cwd();
   try {
-    const artifactsDir = join6(cwd, ".stackwright", "artifacts");
+    const artifactsDir = join7(cwd, ".stackwright", "artifacts");
     let manifest = null;
     try {
       manifest = loadSignatureManifest(cwd);
@@ -3504,8 +3736,8 @@ function handleListArtifacts(_cwd) {
     let completedCount = 0;
     for (const phase of PHASE_ORDER) {
       const expectedFile = PHASE_ARTIFACT[phase];
-      const fullPath = join6(artifactsDir, expectedFile);
-      const exists = existsSync6(fullPath);
+      const fullPath = join7(artifactsDir, expectedFile);
+      const exists = existsSync7(fullPath);
       if (exists) completedCount++;
       let signed = false;
       let signatureValid = null;
@@ -3558,9 +3790,9 @@ function handleWritePhaseQuestions(input) {
       }
     } catch {
     }
-    const questionsDir = join6(cwd, ".stackwright", "questions");
+    const questionsDir = join7(cwd, ".stackwright", "questions");
     mkdirSync4(questionsDir, { recursive: true });
-    const filePath = join6(questionsDir, `${phase}.json`);
+    const filePath = join7(questionsDir, `${phase}.json`);
     const payload = {
       version: "1.0",
       phase,
@@ -3600,14 +3832,14 @@ function handleBuildSpecialistPrompt(input) {
     };
   }
   try {
-    const answersPath = join6(cwd, ".stackwright", "answers", `${phase}.json`);
+    const answersPath = join7(cwd, ".stackwright", "answers", `${phase}.json`);
     let answers = {};
-    if (existsSync6(answersPath)) {
+    if (existsSync7(answersPath)) {
       answers = JSON.parse(safeReadSync(answersPath));
     }
     let buildContextText = "";
-    const buildContextPath = join6(cwd, ".stackwright", "build-context.json");
-    if (existsSync6(buildContextPath)) {
+    const buildContextPath = join7(cwd, ".stackwright", "build-context.json");
+    if (existsSync7(buildContextPath)) {
       try {
         const bcRaw = JSON.parse(safeReadSync(buildContextPath));
         if (typeof bcRaw.buildContext === "string" && bcRaw.buildContext.trim().length > 0) {
@@ -3622,8 +3854,8 @@ function handleBuildSpecialistPrompt(input) {
     const missingDependencies = [];
     for (const dep of deps) {
       const artifactFile = PHASE_ARTIFACT[dep];
-      const artifactPath = join6(cwd, ".stackwright", "artifacts", artifactFile);
-      if (existsSync6(artifactPath)) {
+      const artifactPath = join7(cwd, ".stackwright", "artifacts", artifactFile);
+      if (existsSync7(artifactPath)) {
         const rawContent = safeReadSync(artifactPath);
         const rawBytes = Buffer.from(rawContent, "utf-8");
         const content = JSON.parse(rawContent);
@@ -3688,8 +3920,8 @@ ${JSON.stringify(content, null, 2)}`
       parts.push("BUILD_CONTEXT:", buildContextText, "");
     }
     if (phase === "auth") {
-      const initContextPath = join6(cwd, ".stackwright", "init-context.json");
-      if (existsSync6(initContextPath)) {
+      const initContextPath = join7(cwd, ".stackwright", "init-context.json");
+      if (existsSync7(initContextPath)) {
         try {
           const initContext = JSON.parse(safeReadSync(initContextPath));
           if (initContext.devOnly === true || initContext.nonInteractive === true) {
@@ -4140,7 +4372,87 @@ function _validateArtifactInner(input) {
     };
     return { text: JSON.stringify(result), isError: false };
   }
+  if (phase === "auth") {
+    const authArtifactPath = `.stackwright/artifacts/${PHASE_ARTIFACT["auth"]}`;
+    const authShapeResult = validateAuthConfig(artifact, authArtifactPath);
+    if (!authShapeResult.valid) {
+      const result = {
+        valid: false,
+        phase,
+        violation: "schema-mismatch",
+        retryPrompt: authShapeResult.retryPrompt
+      };
+      return { text: JSON.stringify(result), isError: false };
+    }
+  }
+  if (phase === "auth") {
+    const rawUncovered = artifact["uncoveredSlugs"];
+    if (Array.isArray(rawUncovered) && rawUncovered.length > 0) {
+      const otterFromSource = (source) => {
+        if (source === "geo-manifest.json") return "geo-otter";
+        if (source === "dashboard-manifest.json") return "dashboard-otter";
+        if (source === "pages-manifest.json") return "page-otter";
+        return source || "(unknown)";
+      };
+      const slugLines = rawUncovered.map((entry) => {
+        const e = entry ?? {};
+        const source = typeof e["source"] === "string" ? e["source"] : "(unknown)";
+        const slug = typeof e["slug"] === "string" ? e["slug"] : "(unknown)";
+        return `  ${source}  \u2192  ${slug}  (emitted by ${otterFromSource(source)})`;
+      });
+      const retryPrompt = [
+        "Auth-config cannot be finalized: the following page slugs have no auth declaration in their emitting otter's manifest:",
+        "",
+        ...slugLines,
+        "",
+        "This is a HARD build-gate failure \u2014 auth-otter cannot self-correct because the root cause is upstream.",
+        "",
+        "Fix: update the offending emitter otter to declare `authRequired: true` + `requiredRoles: [...]`",
+        "(and optionally `tier`, `authRationale`) in the manifest entry for each listed slug.",
+        "",
+        "For map pages: geo-otter (see swp-1114).",
+        "For dashboard pages: dashboard-otter (see swp-52lk).",
+        "For page pages: page-otter (already does this \u2014 check for regressions).",
+        "For workflow pages: form-wizard-otter emits routes but auth is derived from the pages-manifest",
+        "workflow-wrapper entry \u2014 check page-otter didn't skip a workflow-wrapper.",
+        "",
+        "After updating the offending manifest, re-run the pipeline from the affected phase."
+      ].join("\n");
+      const result = {
+        valid: false,
+        phase,
+        violation: "uncovered-slugs",
+        retryPrompt
+      };
+      return { text: JSON.stringify(result), isError: false };
+    }
+  }
   const PHASE_ZOD_VALIDATORS = {
+    // 5.0 Theme defaultColorMode hygiene (swp-0ryn / swp-mw97)
+    //
+    // DHL raft runs produced `defaultColorMode: "auto"` (not a valid value) and
+    // `defaultColorMode: "dark"` when the designer said "respect OS preference".
+    // This validator catches the `auto` literal at write-time so the otter
+    // self-corrects before the artifact lands on disk.
+    //
+    // Valid values: 'light' | 'dark' | 'system'
+    // Omitting the key entirely is also valid (app shell honors prefers-color-scheme).
+    theme: (artifact2) => {
+      const dcm = artifact2["defaultColorMode"];
+      if (dcm === void 0 || dcm === null) {
+        return { success: true };
+      }
+      const VALID_COLOR_MODES = ["light", "dark", "system"];
+      if (!VALID_COLOR_MODES.includes(dcm)) {
+        return {
+          success: false,
+          error: {
+            message: `theme-tokens.json: \`defaultColorMode: "${String(dcm)}"\` is not a valid value. Valid values are \`light\`, \`dark\`, or \`system\`. Use \`system\` for OS-following behavior (respects \`prefers-color-scheme\`). Alternatively, OMIT the \`defaultColorMode\` key entirely when the designer has specified in design-language.json operationalNotes that OS preference should be respected (trigger phrases: "respect OS preference", "no forced default").`
+          }
+        };
+      }
+      return { success: true };
+    },
     workflow: (artifact2) => {
       const workflowData = artifact2["workflow"];
       if (!workflowData) {
@@ -4190,33 +4502,60 @@ function _validateArtifactInner(input) {
       return { success: true };
     },
     // swp-4071 — opt-in cross-reference validator for the services phase.
-    // If workflow-config exists and declares serviceHooks, every hook ref must resolve
-    // to a flow or state-machine in this services-config artifact.
+    // Collects serviceHooks from ALL workflow-config-*.json artifacts (swp-x8sm fan-out)
+    // plus the legacy single-file workflow-config.json (backward compat).
+    // If any workflow declared serviceHooks, every ref must resolve to a flow or
+    // state-machine in this services-config artifact.
     // Skips gracefully when wizard-otter didn't run (Pro-only install) or declared no hooks.
     services: (artifact2) => {
-      const workflowArtifactPath = join6(cwd, ".stackwright", "artifacts", "workflow-config.json");
-      if (!existsSync6(workflowArtifactPath)) {
-        return { success: true };
+      const artifactsDir = join7(cwd, ".stackwright", "artifacts");
+      const workflowArtifactFiles = [];
+      if (existsSync7(artifactsDir)) {
+        try {
+          const entries = readdirSync5(artifactsDir);
+          for (const entry of entries) {
+            if (entry.startsWith("workflow-config-") && entry.endsWith(".json")) {
+              workflowArtifactFiles.push(join7(artifactsDir, entry));
+            }
+          }
+        } catch {
+        }
       }
-      let workflowArtifact;
-      try {
-        workflowArtifact = JSON.parse(readFileSync6(workflowArtifactPath, "utf-8"));
-      } catch {
+      const legacyPath = join7(artifactsDir, "workflow-config.json");
+      if (existsSync7(legacyPath)) {
+        workflowArtifactFiles.push(legacyPath);
+      }
+      if (workflowArtifactFiles.length === 0) {
         return { success: true };
       }
-      const declaredHooks = workflowArtifact.serviceHooks ?? [];
-      if (declaredHooks.length === 0) {
+      const declaredHooks = [];
+      for (const filePath of workflowArtifactFiles) {
+        try {
+          const parsed = JSON.parse(readFileSync7(filePath, "utf-8"));
+          if (Array.isArray(parsed.serviceHooks)) {
+            declaredHooks.push(...parsed.serviceHooks);
+          }
+        } catch {
+        }
+      }
+      const seenRefs = /* @__PURE__ */ new Set();
+      const uniqueHooks = declaredHooks.filter((h) => {
+        if (seenRefs.has(h.ref)) return false;
+        seenRefs.add(h.ref);
+        return true;
+      });
+      if (uniqueHooks.length === 0) {
         return { success: true };
       }
       const flows = artifact2["flows"] ?? [];
       const workflows = artifact2["workflows"] ?? [];
       const flowNames = /* @__PURE__ */ new Set([...flows.map((f) => f.name), ...workflows.map((w) => w.name)]);
-      const unresolved = declaredHooks.filter((h) => !flowNames.has(h.ref));
+      const unresolved = uniqueHooks.filter((h) => !flowNames.has(h.ref));
       if (unresolved.length > 0) {
         return {
           success: false,
           error: {
-            message: `Workflow declared ${declaredHooks.length} service hook(s) but ${unresolved.length} unresolved by services-config: ` + unresolved.map((h) => `${h.ref} (${h.kind ?? "unknown"}: ${h.purpose ?? "no purpose"})`).join("; ") + ". Either add matching flows to services-config OR remove the hooks from the workflow YAML."
+            message: `Workflow(s) declared ${uniqueHooks.length} service hook(s) but ${unresolved.length} unresolved by services-config: ` + unresolved.map((h) => `${h.ref} (${h.kind ?? "unknown"}: ${h.purpose ?? "no purpose"})`).join("; ") + ". Either add matching flows to services-config OR remove the hooks from the workflow YAML."
           }
         };
       }
@@ -4282,11 +4621,55 @@ function _validateArtifactInner(input) {
       return { text: JSON.stringify(result), isError: false };
     }
   }
+  if (phase === "api") {
+    const apiAuthResult = validateApiIntegration(artifact, input.integrationName);
+    if (!apiAuthResult.valid) {
+      const result = {
+        valid: false,
+        phase,
+        violation: "schema-mismatch",
+        retryPrompt: apiAuthResult.retryPrompt
+      };
+      return { text: JSON.stringify(result), isError: false };
+    }
+  }
+  if (phase === "workflow" && input.workflowName !== void 0) {
+    if (!isValidSlug(input.workflowName)) {
+      const result = {
+        valid: false,
+        phase,
+        violation: "schema-mismatch",
+        retryPrompt: `workflowName "${input.workflowName}" is not a valid slug. Use lowercase kebab-case (a-z, 0-9, hyphens only, no spaces or path separators). Example: "patient-evacuation", "ambulance-crew-dispatch".`
+      };
+      return { text: JSON.stringify(result), isError: false };
+    }
+  }
+  let authOrphanWarning;
+  if (phase === "auth") {
+    const authCfg = artifact["authConfig"];
+    const routes = authCfg?.["protectedRoutes"];
+    if (Array.isArray(routes) && routes.length > 0) {
+      const artifactsDir = join7(cwd, ".stackwright", "artifacts");
+      const knownSlugs = extractManifestSlugs(artifactsDir);
+      const orphanPatterns = [];
+      for (const route of routes) {
+        const pattern = typeof route === "string" ? route : route.pattern ?? "";
+        if (!pattern) continue;
+        const baseSlug = extractPatternBaseSlug(pattern);
+        if (baseSlug && !knownSlugs.has(baseSlug)) {
+          orphanPatterns.push(pattern);
+        }
+      }
+      if (orphanPatterns.length > 0) {
+        authOrphanWarning = `The following protectedRoute patterns don't match any known page slug: ${orphanPatterns.map((p) => `"${p}"`).join(", ")}. If these are intentional cross-cutting rules (e.g., /admin/:path*, /audit/:path*), keep them; otherwise remove.`;
+      }
+    }
+  }
   try {
-    const artifactsDir = join6(cwd, ".stackwright", "artifacts");
+    const artifactsDir = join7(cwd, ".stackwright", "artifacts");
     mkdirSync4(artifactsDir, { recursive: true });
-    const artifactFile = phase === "api" && input.integrationName ? `api-config-${input.integrationName}.json` : PHASE_ARTIFACT[phase];
-    const artifactPath = join6(artifactsDir, artifactFile);
+    const artifactFile = phase === "api" && input.integrationName ? `api-config-${input.integrationName}.json` : phase === "workflow" && input.workflowName ? `workflow-config-${input.workflowName}.json` : PHASE_ARTIFACT[phase];
+    const artifactPath = join7(artifactsDir, artifactFile);
     const serialized = JSON.stringify(artifact, null, 2) + "\n";
     const artifactBytes = Buffer.from(serialized, "utf-8");
     safeWriteSync(artifactPath, serialized);
@@ -4309,7 +4692,8 @@ function _validateArtifactInner(input) {
       valid: true,
       phase,
       artifactPath,
-      summary: `Wrote ${artifactFile} (keys: ${topKeys}${Object.keys(artifact).length > 5 ? ", ..." : ""})${signed ? " [signed]" : ""}`
+      summary: `Wrote ${artifactFile} (keys: ${topKeys}${Object.keys(artifact).length > 5 ? ", ..." : ""})${signed ? " [signed]" : ""}`,
+      ...authOrphanWarning ? { retryPrompt: authOrphanWarning } : {}
     };
     return { text: JSON.stringify(result), isError: false };
   } catch (err) {
@@ -4505,9 +4889,9 @@ function registerPipelineTools(server2) {
             isError: true
           };
         }
-        const questionsDir = join6(process.cwd(), ".stackwright", "questions");
+        const questionsDir = join7(process.cwd(), ".stackwright", "questions");
         mkdirSync4(questionsDir, { recursive: true });
-        const outPath = join6(questionsDir, `${phase}.json`);
+        const outPath = join7(questionsDir, `${phase}.json`);
         writeFileSync4(
           outPath,
           JSON.stringify({ phase, questions, writtenAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)
@@ -4547,15 +4931,19 @@ function registerPipelineTools(server2) {
       ),
       integrationName: z13.string().optional().describe(
         'When phase="api": write to api-config-<integrationName>.json instead of api-config.json. Enables concurrent per-spec fan-out without collision (swp-530y).'
+      ),
+      workflowName: z13.string().optional().describe(
+        `When phase="workflow": write to workflow-config-<workflowName>.json instead of workflow-config.json. Enables concurrent per-workflow fan-out without collision (swp-x8sm). Must be a kebab-case slug matching the workflow's id field.`
       )
     },
-    async ({ phase, responseText, artifact, integrationName }) => {
+    async ({ phase, responseText, artifact, integrationName, workflowName }) => {
       if (artifact) {
         return res(
           handleValidateArtifact({
             phase,
             artifact,
-            ...integrationName ? { integrationName } : {}
+            ...integrationName ? { integrationName } : {},
+            ...workflowName ? { workflowName } : {}
           })
         );
       }
@@ -4563,7 +4951,8 @@ function registerPipelineTools(server2) {
         handleValidateArtifact({
           phase,
           responseText: responseText ?? "",
-          ...integrationName ? { integrationName } : {}
+          ...integrationName ? { integrationName } : {},
+          ...workflowName ? { workflowName } : {}
         })
       );
     }
@@ -4595,8 +4984,8 @@ function registerPipelineTools(server2) {
 
 // src/tools/safe-write.ts
 import { z as z14 } from "zod";
-import { writeFileSync as writeFileSync5, readFileSync as readFileSync7, existsSync as existsSync7, mkdirSync as mkdirSync5, lstatSync as lstatSync7 } from "fs";
-import { normalize, isAbsolute, dirname, join as join7 } from "path";
+import { writeFileSync as writeFileSync5, readFileSync as readFileSync8, existsSync as existsSync8, mkdirSync as mkdirSync5, lstatSync as lstatSync7 } from "fs";
+import { normalize, isAbsolute, dirname, join as join8 } from "path";
 import { emit as emit2 } from "@stackwright-pro/telemetry";
 var OTTER_WRITE_ALLOWLISTS = {
   "stackwright-pro-designer-otter": [
@@ -4608,6 +4997,11 @@ var OTTER_WRITE_ALLOWLISTS = {
       prefix: "stackwright.theme.",
       suffix: ".yml",
       description: "Theme config YAML (merged at build time)"
+    },
+    {
+      prefix: "stackwright.yml",
+      suffix: "",
+      description: "Stackwright config (themeName + customTheme writeback)"
     }
   ],
   "stackwright-pro-auth-otter": [
@@ -4662,6 +5056,17 @@ var OTTER_WRITE_ALLOWLISTS = {
       prefix: ".stackwright/artifacts/",
       suffix: ".json",
       description: "Scaffold manifest artifact"
+    },
+    // swp-89w5: scaffold-otter initialises mock backend wiring via stackwright_pro_emit_env_local
+    {
+      prefix: ".env.local",
+      suffix: "",
+      description: "Dotenv runtime config (mock backend wiring: NEXT_PUBLIC_MOCK_BACKEND + per-integration mock keys)"
+    },
+    {
+      prefix: ".env.local.example",
+      suffix: "",
+      description: "Dotenv template (schema for real production values)"
     }
   ],
   "stackwright-pro-api-otter": [
@@ -4778,21 +5183,21 @@ function extractContentTypes(yamlContent) {
   return types.length > 0 ? types : ["unknown"];
 }
 function readPageRegistry(cwd) {
-  const regPath = join7(cwd, PAGE_REGISTRY_FILE);
-  if (!existsSync7(regPath)) return {};
+  const regPath = join8(cwd, PAGE_REGISTRY_FILE);
+  if (!existsSync8(regPath)) return {};
   try {
     const stat = lstatSync7(regPath);
     if (stat.isSymbolicLink()) return {};
-    return JSON.parse(readFileSync7(regPath, "utf-8"));
+    return JSON.parse(readFileSync8(regPath, "utf-8"));
   } catch {
     return {};
   }
 }
 function writePageRegistry(cwd, registry) {
-  const dir = join7(cwd, ".stackwright");
+  const dir = join8(cwd, ".stackwright");
   mkdirSync5(dir, { recursive: true });
-  const regPath = join7(cwd, PAGE_REGISTRY_FILE);
-  if (existsSync7(regPath)) {
+  const regPath = join8(cwd, PAGE_REGISTRY_FILE);
+  if (existsSync8(regPath)) {
     const stat = lstatSync7(regPath);
     if (stat.isSymbolicLink()) {
       throw new Error("Refusing to write page registry through symlink");
@@ -4964,8 +5369,8 @@ function _safeWriteInner(input) {
     return { text: JSON.stringify(result), isError: true };
   }
   const normalized = normalize(filePath);
-  const fullPath = join7(cwd, normalized);
-  if (existsSync7(fullPath)) {
+  const fullPath = join8(cwd, normalized);
+  if (existsSync8(fullPath)) {
     try {
       const stat = lstatSync7(fullPath);
       if (stat.isSymbolicLink()) {
@@ -5095,8 +5500,8 @@ function registerSafeWriteTools(server2) {
 
 // src/tools/auth.ts
 import { z as z15 } from "zod";
-import { readFileSync as readFileSync8, writeFileSync as writeFileSync6, existsSync as existsSync8, mkdirSync as mkdirSync6 } from "fs";
-import { join as join8 } from "path";
+import { readFileSync as readFileSync9, writeFileSync as writeFileSync6, existsSync as existsSync9, mkdirSync as mkdirSync6 } from "fs";
+import { join as join9 } from "path";
 function buildHierarchy(roles) {
   const h = {};
   for (let i = 0; i < roles.length - 1; i++) {
@@ -5123,9 +5528,9 @@ ${indent}  requiredRole: ${r.requiredRole}`).join("\n");
 }
 function detectNextMajorVersion(cwd) {
   try {
-    const pkgPath = join8(cwd, "package.json");
-    if (!existsSync8(pkgPath)) return null;
-    const pkg = JSON.parse(readFileSync8(pkgPath, "utf8"));
+    const pkgPath = join9(cwd, "package.json");
+    if (!existsSync9(pkgPath)) return null;
+    const pkg = JSON.parse(readFileSync9(pkgPath, "utf8"));
     const nextVersion = pkg.dependencies?.next ?? pkg.devDependencies?.next;
     if (!nextVersion) return null;
     const match = nextVersion.match(/(\d+)/);
@@ -5789,7 +6194,7 @@ async function configureAuthHandler(params, cwd) {
       auditRetentionDays,
       normalizedRoutes
     );
-    writeFileSync6(join8(cwd, conventionFile), authFileContent, "utf8");
+    writeFileSync6(join9(cwd, conventionFile), authFileContent, "utf8");
     filesWritten.push(conventionFile);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -5809,9 +6214,9 @@ async function configureAuthHandler(params, cwd) {
   if (!devOnly) {
     try {
       const envBlock = generateEnvBlock(effectiveMethod, params);
-      const envPath = join8(cwd, ".env.example");
-      if (existsSync8(envPath)) {
-        const existing = readFileSync8(envPath, "utf8");
+      const envPath = join9(cwd, ".env.example");
+      if (existsSync9(envPath)) {
+        const existing = readFileSync9(envPath, "utf8");
         writeFileSync6(envPath, existing.trimEnd() + "\n\n" + envBlock, "utf8");
       } else {
         writeFileSync6(envPath, envBlock, "utf8");
@@ -5832,10 +6237,10 @@ async function configureAuthHandler(params, cwd) {
   }
   if (devOnly) {
     try {
-      const mockAuthDir = join8(cwd, "lib");
+      const mockAuthDir = join9(cwd, "lib");
       mkdirSync6(mockAuthDir, { recursive: true });
       const mockAuthContent = generateMockAuthContent(roles, mockUsers);
-      writeFileSync6(join8(mockAuthDir, "mock-auth.ts"), mockAuthContent, "utf8");
+      writeFileSync6(join9(mockAuthDir, "mock-auth.ts"), mockAuthContent, "utf8");
       filesWritten.push("lib/mock-auth.ts");
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -5853,9 +6258,9 @@ async function configureAuthHandler(params, cwd) {
       };
     }
     try {
-      const pkgPath = join8(cwd, "package.json");
-      if (existsSync8(pkgPath)) {
-        const existingPkg = readFileSync8(pkgPath, "utf8");
+      const pkgPath = join9(cwd, "package.json");
+      if (existsSync9(pkgPath)) {
+        const existingPkg = readFileSync9(pkgPath, "utf8");
         const updatedPkg = updatePackageJsonScripts(existingPkg, roles, mockUsers);
         writeFileSync6(pkgPath, updatedPkg, "utf8");
         filesWritten.push("package.json");
@@ -5898,7 +6303,7 @@ async function configureAuthHandler(params, cwd) {
       normalizedRoutes,
       useProxy
     );
-    writeFileSync6(join8(cwd, "stackwright.auth.yml"), authYaml, "utf8");
+    writeFileSync6(join9(cwd, "stackwright.auth.yml"), authYaml, "utf8");
     filesWritten.push("stackwright.auth.yml");
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -6011,8 +6416,8 @@ function registerAuthTools(server2) {
 
 // src/integrity.ts
 import { createHash as createHash4, timingSafeEqual as timingSafeEqual2 } from "crypto";
-import { readFileSync as readFileSync9, readdirSync as readdirSync4, lstatSync as lstatSync8 } from "fs";
-import { join as join9, basename } from "path";
+import { readFileSync as readFileSync10, readdirSync as readdirSync6, lstatSync as lstatSync8 } from "fs";
+import { join as join10, basename } from "path";
 var _checksums = /* @__PURE__ */ new Map([
   [
     "stackwright-pro-api-otter.json",
@@ -6020,11 +6425,11 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-auth-otter.json",
-    "1a21d9f23e250f23291124307e5a2a32af5a716566319a3290372dae3d02e637"
+    "69fa03c5532ef617c86fe7af41e8174c168d282baf602b1b269a7e933ea86b7c"
   ],
   [
     "stackwright-pro-dashboard-otter.json",
-    "4a9ac39e929866ae3c929aa5bcbba3d9483a1c251c35f26f267f3e7433506f0c"
+    "f55081bf4d6545e5435128919f6f9233956ba37671fc9f85300f240ad2497ab6"
   ],
   [
     "stackwright-pro-data-otter.json",
@@ -6040,19 +6445,19 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-foreman-otter.json",
-    "9d68b7b20af7a8a1668e2a693b4a2b05cf37acce1e9f6298a0966c97a3417e9f"
+    "88c4101154d44a7c5470ded13562402a39323ee570ed3a90a73b8d85d7fd2817"
   ],
   [
     "stackwright-pro-form-wizard-otter.json",
-    "7f6f94192f26face57dc8b2e22e0a49d23ceeeb356ca4ebde05492f1b25e3c47"
+    "cb350297a0068ead2424e703e8c775d91c0b87249ea6904f43b903baf8a84b79"
   ],
   [
     "stackwright-pro-geo-otter.json",
-    "fc3d18e02a6147d95d3dd9093ce74c0e8fffaecc2f9ecdbd19c163a80129d264"
+    "3032fbd27de36c0cdc0e19e46a32d771208d8e86714482f5a368d46342c8317a"
   ],
   [
     "stackwright-pro-page-otter.json",
-    "879e8ff4aa645bac2c63dc962cad1a549876983c257aec756e95293c3b22ce7e"
+    "cc0db24b00f0130f8b4ec8d385c73ea1bcf5d57ba45aca6b986bcbd5da328930"
   ],
   [
     "stackwright-pro-polish-otter.json",
@@ -6064,15 +6469,15 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-scaffold-otter.json",
-    "92930c732547c90a19e89ee0e25b5f037b7366f770941f0a01e148ff240a1b6d"
+    "90272bab51bd8ed9e25c0fb6481cdd4252386850f64192edfe1e2eff44166e2d"
   ],
   [
     "stackwright-pro-theme-otter.json",
-    "01d16d0597d475db60362e3b8020035e140817d197c36f4307a48b95f4b28b60"
+    "afb47f8381907145c0e098bdcaae4dd9f5c4ff825a8e88d00a218d2f6858820b"
   ],
   [
     "stackwright-services-otter.json",
-    "2a50ceb3fad166251d0ad8709a34a32118645713e0e34628165d16dced1d5c93"
+    "4351348806aeb98404a2bacb044209ca411be5e35e2f2c3d03eb4d28a07fde78"
   ]
 ]);
 Object.freeze(_checksums);
@@ -6120,7 +6525,7 @@ function verifyOtterFile(filePath) {
   }
   let raw;
   try {
-    raw = readFileSync9(filePath);
+    raw = readFileSync10(filePath);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { verified: false, filename, error: `Cannot read file: ${msg}` };
@@ -6170,7 +6575,7 @@ function verifyAllOtters(otterDir) {
   const unknown = [];
   let entries;
   try {
-    entries = readdirSync4(otterDir);
+    entries = readdirSync6(otterDir);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return {
@@ -6181,7 +6586,7 @@ function verifyAllOtters(otterDir) {
   }
   const otterFiles = entries.filter((f) => f.endsWith("-otter.json"));
   for (const filename of otterFiles) {
-    const filePath = join9(otterDir, filename);
+    const filePath = join10(otterDir, filename);
     try {
       if (lstatSync8(filePath).isSymbolicLink()) {
         failed.push({ filename, error: "Skipped: symlink" });
@@ -6209,7 +6614,7 @@ var DEFAULT_SEARCH_PATHS = ["node_modules/@stackwright-pro/otters/src/", "packag
 function resolveOtterDir() {
   const cwd = process.cwd();
   for (const relative2 of DEFAULT_SEARCH_PATHS) {
-    const candidate = join9(cwd, relative2);
+    const candidate = join10(cwd, relative2);
     try {
       lstatSync8(candidate);
       return candidate;
@@ -6290,13 +6695,13 @@ function registerIntegrityTools(server2) {
 
 // src/tools/domain.ts
 import { z as z16 } from "zod";
-import { readFileSync as readFileSync10, existsSync as existsSync9 } from "fs";
-import { join as join10 } from "path";
+import { readFileSync as readFileSync11, existsSync as existsSync10 } from "fs";
+import { join as join11 } from "path";
 function handleListCollections(input) {
   const cwd = input._cwd ?? process.cwd();
   const sources = [
     {
-      path: join10(cwd, ".stackwright", "artifacts", "data-config.json"),
+      path: join11(cwd, ".stackwright", "artifacts", "data-config.json"),
       source: "data-config.json",
       parse: (raw) => {
         const parsed = JSON.parse(raw);
@@ -6307,15 +6712,15 @@ function handleListCollections(input) {
       }
     },
     {
-      path: join10(cwd, "stackwright.yml"),
+      path: join11(cwd, "stackwright.yml"),
       source: "stackwright.yml",
       parse: extractCollectionsFromYaml
     }
   ];
   for (const { path: path5, source, parse } of sources) {
-    if (!existsSync9(path5)) continue;
+    if (!existsSync10(path5)) continue;
     try {
-      const collections = parse(readFileSync10(path5, "utf8"));
+      const collections = parse(readFileSync11(path5, "utf8"));
       return {
         text: JSON.stringify({ collections, source, collectionCount: collections.length }),
         isError: false
@@ -6466,8 +6871,8 @@ function handleValidateWorkflow(input) {
   if (input.workflow && Object.keys(input.workflow).length > 0) {
     raw = input.workflow;
   } else {
-    const artifactPath = join10(cwd, ".stackwright", "artifacts", "workflow-config.json");
-    if (!existsSync9(artifactPath)) {
+    const artifactPath = join11(cwd, ".stackwright", "artifacts", "workflow-config.json");
+    if (!existsSync10(artifactPath)) {
       return fail([
         {
           code: "NO_WORKFLOW",
@@ -6476,7 +6881,7 @@ function handleValidateWorkflow(input) {
       ]);
     }
     try {
-      raw = JSON.parse(readFileSync10(artifactPath, "utf8"));
+      raw = JSON.parse(readFileSync11(artifactPath, "utf8"));
     } catch (err) {
       return fail([{ code: "INVALID_JSON", message: `Failed to parse workflow artifact: ${err}` }]);
     }
@@ -6914,16 +7319,16 @@ function registerProPageTools(server2) {
 
 // src/tools/scaffold-cleanup.ts
 import {
-  existsSync as existsSync11,
+  existsSync as existsSync12,
   lstatSync as lstatSync9,
   unlinkSync as unlinkSync2,
-  readFileSync as readFileSync11,
+  readFileSync as readFileSync12,
   writeFileSync as writeFileSync8,
-  readdirSync as readdirSync5,
+  readdirSync as readdirSync7,
   rmdirSync,
   mkdirSync as mkdirSync8
 } from "fs";
-import { join as join12, dirname as dirname3 } from "path";
+import { join as join13, dirname as dirname3 } from "path";
 var SCAFFOLD_FILES_TO_DELETE = [
   "content/posts/getting-started.yaml",
   "content/posts/hello-world.yaml"
@@ -6948,12 +7353,12 @@ var FALLBACK_COLORS = {
   mutedForeground: "#737373"
 };
 function readThemeColors(cwd) {
-  const tokenPath = join12(cwd, ".stackwright", "artifacts", "theme-tokens.json");
-  if (!existsSync11(tokenPath)) return { ...FALLBACK_COLORS };
+  const tokenPath = join13(cwd, ".stackwright", "artifacts", "theme-tokens.json");
+  if (!existsSync12(tokenPath)) return { ...FALLBACK_COLORS };
   const stat = lstatSync9(tokenPath);
   if (stat.isSymbolicLink()) return { ...FALLBACK_COLORS };
   try {
-    const raw = JSON.parse(readFileSync11(tokenPath, "utf-8"));
+    const raw = JSON.parse(readFileSync12(tokenPath, "utf-8"));
     const css = raw?.cssVariables ?? {};
     const toHsl = (hslValue) => {
       if (!hslValue || typeof hslValue !== "string") return null;
@@ -7013,15 +7418,15 @@ function generateNotFoundPage(colors) {
 `;
 }
 function isSafePath(fullPath) {
-  if (!existsSync11(fullPath)) return true;
+  if (!existsSync12(fullPath)) return true;
   const stat = lstatSync9(fullPath);
   return !stat.isSymbolicLink();
 }
 function isDirEmpty(dirPath) {
-  if (!existsSync11(dirPath)) return false;
+  if (!existsSync12(dirPath)) return false;
   const stat = lstatSync9(dirPath);
   if (!stat.isDirectory()) return false;
-  return readdirSync5(dirPath).length === 0;
+  return readdirSync7(dirPath).length === 0;
 }
 function handleCleanupScaffold(_cwd) {
   const cwd = _cwd ?? process.cwd();
@@ -7034,8 +7439,8 @@ function handleCleanupScaffold(_cwd) {
     cleanupWarnings: []
   };
   for (const relPath of SCAFFOLD_FILES_TO_DELETE) {
-    const fullPath = join12(cwd, relPath);
-    if (!existsSync11(fullPath)) {
+    const fullPath = join13(cwd, relPath);
+    if (!existsSync12(fullPath)) {
       result.skipped.push(relPath);
       continue;
     }
@@ -7052,13 +7457,13 @@ function handleCleanupScaffold(_cwd) {
   }
   {
     const relPath = "pages/getting-started/content.yml";
-    const fullPath = join12(cwd, relPath);
-    if (!existsSync11(fullPath)) {
+    const fullPath = join13(cwd, relPath);
+    if (!existsSync12(fullPath)) {
       result.skipped.push(relPath);
     } else if (!isSafePath(fullPath)) {
       result.errors.push(`Refusing to delete symlink: ${relPath}`);
     } else {
-      const content = readFileSync11(fullPath, "utf-8");
+      const content = readFileSync12(fullPath, "utf-8");
       const isScaffoldDefault = GETTING_STARTED_SCAFFOLD_FINGERPRINTS.some(
         (marker) => content.includes(marker)
       );
@@ -7078,16 +7483,16 @@ function handleCleanupScaffold(_cwd) {
   }
   {
     const relPath = `content/posts/${POSTS_COLLECTION_FILE}`;
-    const fullPath = join12(cwd, relPath);
-    const postsDir = join12(cwd, "content/posts");
-    if (!existsSync11(fullPath)) {
+    const fullPath = join13(cwd, relPath);
+    const postsDir = join13(cwd, "content/posts");
+    if (!existsSync12(fullPath)) {
       result.skipped.push(relPath);
     } else if (!isSafePath(fullPath)) {
       result.errors.push(`Refusing to delete symlink: ${relPath}`);
-    } else if (!existsSync11(postsDir)) {
+    } else if (!existsSync12(postsDir)) {
       result.skipped.push(relPath);
     } else {
-      const userPostFiles = readdirSync5(postsDir).filter(
+      const userPostFiles = readdirSync7(postsDir).filter(
         (f) => f !== POSTS_COLLECTION_FILE && POST_FILE_EXTENSIONS.some((ext) => f.endsWith(ext))
       );
       if (userPostFiles.length === 0) {
@@ -7105,8 +7510,8 @@ function handleCleanupScaffold(_cwd) {
     }
   }
   for (const relDir of SCAFFOLD_DIRS_TO_PRUNE) {
-    const fullDir = join12(cwd, relDir);
-    if (!existsSync11(fullDir)) continue;
+    const fullDir = join13(cwd, relDir);
+    if (!existsSync12(fullDir)) continue;
     if (!isSafePath(fullDir)) {
       result.errors.push(`Refusing to prune symlink directory: ${relDir}`);
       continue;
@@ -7121,8 +7526,8 @@ function handleCleanupScaffold(_cwd) {
     }
   }
   {
-    const fullPath = join12(cwd, NOT_FOUND_PATH);
-    if (!existsSync11(fullPath)) {
+    const fullPath = join13(cwd, NOT_FOUND_PATH);
+    if (!existsSync12(fullPath)) {
       result.skipped.push(NOT_FOUND_PATH);
     } else if (!isSafePath(fullPath)) {
       result.errors.push(`Refusing to rewrite symlink: ${NOT_FOUND_PATH}`);
@@ -7643,14 +8048,14 @@ ${results.join("\n")}`;
 
 // src/tools/strip-legacy-integrations.ts
 import { z as z21 } from "zod";
-import { existsSync as existsSync12, readFileSync as readFileSync12, writeFileSync as writeFileSync9 } from "fs";
-import { join as join13 } from "path";
+import { existsSync as existsSync13, readFileSync as readFileSync13, writeFileSync as writeFileSync9 } from "fs";
+import { join as join14 } from "path";
 function handleStripLegacyIntegrations(input) {
   const { projectRoot } = input;
-  const ymlPath = join13(projectRoot, "stackwright.yml");
-  const yamlPath = join13(projectRoot, "stackwright.yaml");
-  if (!existsSync12(ymlPath)) {
-    if (existsSync12(yamlPath)) {
+  const ymlPath = join14(projectRoot, "stackwright.yml");
+  const yamlPath = join14(projectRoot, "stackwright.yaml");
+  if (!existsSync13(ymlPath)) {
+    if (existsSync13(yamlPath)) {
       return {
         changed: false,
         removedEntries: 0,
@@ -7663,7 +8068,7 @@ function handleStripLegacyIntegrations(input) {
       message: "stackwright.yml not found \u2014 no-op."
     };
   }
-  const raw = readFileSync12(ymlPath, "utf-8");
+  const raw = readFileSync13(ymlPath, "utf-8");
   const isCRLF = raw.includes("\r\n");
   const content = isCRLF ? raw.replace(/\r\n/g, "\n") : raw;
   const lines = content.split("\n");
@@ -7718,15 +8123,15 @@ function registerStripLegacyIntegrationsTool(server2) {
 
 // src/tools/emitters.ts
 import { z as z22 } from "zod";
-import { readFileSync as readFileSync13, existsSync as existsSync13, readdirSync as readdirSync6 } from "fs";
-import { join as join14 } from "path";
+import { readFileSync as readFileSync14, existsSync as existsSync14, readdirSync as readdirSync8 } from "fs";
+import { join as join15 } from "path";
 import yaml from "js-yaml";
 import { emitEnvLocal, emitProvidersFile, emitMockPorts } from "@stackwright-pro/emitters";
 function readIntegrations(cwd) {
-  const filePath = join14(cwd, "stackwright.integrations.yml");
-  if (!existsSync13(filePath)) return [];
+  const filePath = join15(cwd, "stackwright.integrations.yml");
+  if (!existsSync14(filePath)) return [];
   try {
-    const raw = yaml.load(readFileSync13(filePath, "utf-8"));
+    const raw = yaml.load(readFileSync14(filePath, "utf-8"));
     if (!raw?.integrations || !Array.isArray(raw.integrations)) return [];
     return raw.integrations.filter((i) => typeof i.name === "string").map((i) => ({
       name: i.name,
@@ -7737,15 +8142,15 @@ function readIntegrations(cwd) {
   }
 }
 function readServiceTokenRefs(cwd) {
-  const servicesDir = join14(cwd, "services");
-  if (!existsSync13(servicesDir)) return [];
+  const servicesDir = join15(cwd, "services");
+  if (!existsSync14(servicesDir)) return [];
   try {
-    const files = readdirSync6(servicesDir).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"));
+    const files = readdirSync8(servicesDir).filter((f) => f.endsWith(".yml") || f.endsWith(".yaml"));
     const refs = [];
     for (const file of files) {
       try {
         const raw = yaml.load(
-          readFileSync13(join14(servicesDir, file), "utf-8")
+          readFileSync14(join15(servicesDir, file), "utf-8")
         );
         if (raw?.tokenEnv && typeof raw.tokenEnv === "string") {
           refs.push({
@@ -7895,8 +8300,8 @@ This is the third concrete instance of the swp-zf9y deterministic emitter patter
 
 // src/tools/list-specs.ts
 import { z as z23 } from "zod";
-import { readdirSync as readdirSync7, readFileSync as readFileSync14, statSync as statSync2, existsSync as existsSync14 } from "fs";
-import { join as join15, extname, basename as basename2 } from "path";
+import { readdirSync as readdirSync9, readFileSync as readFileSync15, statSync as statSync2, existsSync as existsSync15 } from "fs";
+import { join as join16, extname, basename as basename2 } from "path";
 var STRIP_SUFFIXES = ["-openapi", "-asyncapi", "-api", "-spec"];
 var ALLOWED_EXTS = /* @__PURE__ */ new Set([".yaml", ".yml", ".json"]);
 function deriveIntegrationName(fileName) {
@@ -7918,18 +8323,18 @@ function detectFormat(snippet) {
 }
 function handleListSpecs(input) {
   const { projectRoot } = input;
-  const specsDir = join15(projectRoot, "specs");
+  const specsDir = join16(projectRoot, "specs");
   const empty = { projectRoot, specs: [], totalCount: 0 };
-  if (!existsSync14(specsDir)) return empty;
+  if (!existsSync15(specsDir)) return empty;
   let entries;
   try {
-    entries = readdirSync7(specsDir);
+    entries = readdirSync9(specsDir);
   } catch {
     return empty;
   }
   const specs = [];
   for (const entry of entries) {
-    const fullPath = join15(specsDir, entry);
+    const fullPath = join16(specsDir, entry);
     let stat;
     try {
       stat = statSync2(fullPath);
@@ -7940,7 +8345,7 @@ function handleListSpecs(input) {
     if (!ALLOWED_EXTS.has(extname(entry).toLowerCase())) continue;
     let snippet = "";
     try {
-      snippet = readFileSync14(fullPath, "utf-8").slice(0, 2048);
+      snippet = readFileSync15(fullPath, "utf-8").slice(0, 2048);
     } catch {
     }
     specs.push({
@@ -7972,9 +8377,9 @@ function registerListSpecsTool(server2) {
 
 // src/tools/consolidate-integrations.ts
 import { z as z24 } from "zod";
-import { readdirSync as readdirSync8, readFileSync as readFileSync15, writeFileSync as writeFileSync10, existsSync as existsSync15, mkdirSync as mkdirSync9 } from "fs";
+import { readdirSync as readdirSync10, readFileSync as readFileSync16, writeFileSync as writeFileSync10, existsSync as existsSync16, mkdirSync as mkdirSync9 } from "fs";
 import { lockSync as lockSync2 } from "proper-lockfile";
-import { join as join16, basename as basename3 } from "path";
+import { join as join17, basename as basename3 } from "path";
 import yaml2 from "js-yaml";
 var BASE_MOCK_PORT = 4011;
 var STRIP_SUFFIXES2 = ["-openapi", "-asyncapi", "-api", "-spec"];
@@ -7987,13 +8392,13 @@ function deriveNameFromFilename(filename) {
 }
 function handleConsolidateIntegrations(input) {
   const { projectRoot } = input;
-  const artifactsDir = join16(projectRoot, ".stackwright", "artifacts");
-  if (!existsSync15(artifactsDir)) {
+  const artifactsDir = join17(projectRoot, ".stackwright", "artifacts");
+  if (!existsSync16(artifactsDir)) {
     return { written: false, integrationCount: 0, reason: "no per-spec artifacts found" };
   }
   let entries;
   try {
-    entries = readdirSync8(artifactsDir).filter(
+    entries = readdirSync10(artifactsDir).filter(
       (f) => f.startsWith("api-config-") && f.endsWith(".json") && f !== "api-config.json"
     );
   } catch {
@@ -8004,14 +8409,22 @@ function handleConsolidateIntegrations(input) {
   }
   entries.sort();
   const integrationsByName = /* @__PURE__ */ new Map();
+  const skippedIntegrationsList = [];
   entries.forEach((filename, index) => {
     let artifact = {};
     try {
-      const raw = readFileSync15(join16(artifactsDir, filename), "utf-8");
+      const raw = readFileSync16(join17(artifactsDir, filename), "utf-8");
       artifact = JSON.parse(raw);
     } catch {
     }
     const name = artifact.integrationName ?? deriveNameFromFilename(filename);
+    if (artifact.skipped && artifact.skipped.length > 0) {
+      skippedIntegrationsList.push({
+        name,
+        reason: artifact.skipped[0]?.reason ?? "explicitly skipped by api-otter"
+      });
+      return;
+    }
     const spec = artifact.integrationSpec ?? artifact.specPath ?? `./specs/${name}.yaml`;
     const mockUrl = artifact.mockUrl ?? `http://localhost:${BASE_MOCK_PORT + index}`;
     const baseUrl = artifact.baseUrl ?? "";
@@ -8032,20 +8445,20 @@ function handleConsolidateIntegrations(input) {
     integrationsByName.set(name, entry);
   });
   const integrations = Array.from(integrationsByName.values());
-  const dedupedCount = entries.length - integrations.length;
-  const integrationsYmlPath = join16(projectRoot, "stackwright.integrations.yml");
+  const dedupedCount = entries.length - skippedIntegrationsList.length - integrations.length;
+  const integrationsYmlPath = join17(projectRoot, "stackwright.integrations.yml");
   let existing = {};
-  if (existsSync15(integrationsYmlPath)) {
+  if (existsSync16(integrationsYmlPath)) {
     try {
-      const raw = readFileSync15(integrationsYmlPath, "utf-8");
+      const raw = readFileSync16(integrationsYmlPath, "utf-8");
       existing = yaml2.load(raw) ?? {};
     } catch {
       existing = {};
     }
   }
   const merged = { ...existing, integrations };
-  mkdirSync9(join16(projectRoot), { recursive: true });
-  if (!existsSync15(integrationsYmlPath)) {
+  mkdirSync9(join17(projectRoot), { recursive: true });
+  if (!existsSync16(integrationsYmlPath)) {
     writeFileSync10(integrationsYmlPath, "", "utf-8");
   }
   const release = lockSync2(integrationsYmlPath, {
@@ -8064,7 +8477,11 @@ function handleConsolidateIntegrations(input) {
     written: true,
     integrationCount: integrations.length,
     path: "stackwright.integrations.yml",
-    ...dedupedCount > 0 ? { dedupedCount } : {}
+    ...dedupedCount > 0 ? { dedupedCount } : {},
+    ...skippedIntegrationsList.length > 0 ? {
+      skippedCount: skippedIntegrationsList.length,
+      skippedIntegrations: skippedIntegrationsList
+    } : {}
   };
 }
 function registerConsolidateIntegrationsTool(server2) {
@@ -8138,7 +8555,7 @@ var package_default = {
     "test:coverage": "vitest run --coverage"
   },
   name: "@stackwright-pro/mcp",
-  version: "0.2.0-alpha.107",
+  version: "0.2.0-alpha.109",
   description: "MCP tools for Stackwright Pro - Data Explorer, Security, ISR, and Dashboard generation",
   license: "SEE LICENSE IN LICENSE",
   main: "./dist/server.js",