@stackwright-pro/mcp 0.2.0-alpha.90 → 0.2.0-alpha.95

package/dist/server.js

@@ -144,8 +144,8 @@ function registerDataExplorerTools(server2) {
       lines.push("    endpoints:");
       if (result.filter.include && result.filter.include.length > 0) {
         lines.push("      include:");
-        for (const path3 of result.filter.include) {
-          lines.push(`        - ${path3}`);
+        for (const path4 of result.filter.include) {
+          lines.push(`        - ${path4}`);
         }
       }
       if (result.filter.exclude && result.filter.exclude.length > 0) {
@@ -1619,6 +1619,9 @@ var OTTER_NAME_TO_PHASE = [
   ["dashboard", "dashboard"],
   ["data", "data"],
   ["page", "pages"],
+  // swp-4071: workflow-otter renamed to form-wizard-otter; keep 'workflow' for
+  // any in-flight session that still uses the old name (belt-and-suspenders)
+  ["form-wizard", "workflow"],
   ["workflow", "workflow"],
   ["services", "services"],
   ["polish", "polish"],
@@ -1633,7 +1636,7 @@ var PHASE_TO_OTTER = {
   pages: "stackwright-pro-page-otter",
   dashboard: "stackwright-pro-dashboard-otter",
   data: "stackwright-pro-data-otter",
-  workflow: "stackwright-pro-workflow-otter",
+  workflow: "stackwright-pro-form-wizard-otter",
   services: "stackwright-services-otter",
   polish: "stackwright-pro-polish-otter",
   geo: "stackwright-pro-geo-otter"
@@ -1891,8 +1894,8 @@ function registerOrchestrationTools(server2) {
     {
       buildContext: import_zod9.z.string().describe("Free-text description of what the user wants to build")
     },
-    async ({ buildContext }) => {
-      const { text, isError } = handleSaveBuildContext({ buildContext });
+    async ({ buildContext: buildContext2 }) => {
+      const { text, isError } = handleSaveBuildContext({ buildContext: buildContext2 });
       return {
         content: [{ type: "text", text }],
         isError
@@ -2020,8 +2023,8 @@ function registerOrchestrationTools(server2) {
 
 // src/tools/pipeline.ts
 var import_zod13 = require("zod");
-var import_fs5 = require("fs");
-var import_path5 = require("path");
+var import_fs6 = require("fs");
+var import_path6 = require("path");
 var import_crypto3 = require("crypto");
 
 // src/artifact-signing.ts
@@ -2683,6 +2686,223 @@ function registerGetSchemaTool(server2) {
   );
 }
 
+// src/tools/pipeline-graph.ts
+var import_fs5 = require("fs");
+var import_path5 = require("path");
+var MANIFEST_NAME_TO_PHASE = {
+  "stackwright-pro-designer-otter": "designer",
+  "stackwright-pro-theme-otter": "theme",
+  "stackwright-pro-scaffold-otter": "scaffold",
+  "stackwright-pro-api-otter": "api",
+  "stackwright-pro-auth-otter": "auth",
+  "stackwright-pro-data-otter": "data",
+  "stackwright-pro-page-otter": "pages",
+  "stackwright-pro-dashboard-otter": "dashboard",
+  "stackwright-pro-form-wizard-otter": "workflow",
+  "stackwright-pro-geo-otter": "geo",
+  "stackwright-pro-polish-otter": "polish",
+  "stackwright-services-otter": "services"
+};
+function manifestNameToPhase(name) {
+  return MANIFEST_NAME_TO_PHASE[name] ?? null;
+}
+var OTTER_SEARCH_PATHS = [
+  "node_modules/@stackwright-pro/otters/src/",
+  // production: installed package
+  "packages/otters/src/",
+  // monorepo: run from repo root
+  "../otters/src/"
+  // monorepo: run from packages/mcp/
+];
+function resolveOtterDirFromCwd() {
+  const cwd = process.cwd();
+  for (const relative of OTTER_SEARCH_PATHS) {
+    const candidate = (0, import_path5.join)(cwd, relative);
+    try {
+      (0, import_fs5.lstatSync)(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  throw new Error(
+    `Cannot locate otter directory. Searched: ${OTTER_SEARCH_PATHS.join(", ")} (relative to ${cwd}). Make sure @stackwright-pro/otters is installed.`
+  );
+}
+function loadOtterManifestsFromDir(otterDir) {
+  const entries = (0, import_fs5.readdirSync)(otterDir);
+  const manifests = [];
+  for (const filename of entries) {
+    if (!filename.endsWith("-otter.json")) continue;
+    const filePath = (0, import_path5.join)(otterDir, filename);
+    if ((0, import_fs5.lstatSync)(filePath).isSymbolicLink()) continue;
+    try {
+      const raw = (0, import_fs5.readFileSync)(filePath, "utf-8");
+      const manifest = JSON.parse(raw);
+      manifests.push(manifest);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      throw new Error(`Failed to load otter manifest "${filename}": ${msg}`, { cause: err });
+    }
+  }
+  return manifests;
+}
+function topologicalSort(dependencies) {
+  const phases = Object.keys(dependencies);
+  const inDegree = {};
+  const adjList = {};
+  for (const phase of phases) {
+    inDegree[phase] ??= 0;
+    adjList[phase] ??= [];
+  }
+  for (const phase of phases) {
+    for (const dep of dependencies[phase] ?? []) {
+      inDegree[phase] = (inDegree[phase] ?? 0) + 1;
+      adjList[dep] ??= [];
+      adjList[dep].push(phase);
+    }
+  }
+  const queue = phases.filter((p) => (inDegree[p] ?? 0) === 0);
+  const result = [];
+  while (queue.length > 0) {
+    const node = queue.shift();
+    result.push(node);
+    for (const dependent of adjList[node] ?? []) {
+      inDegree[dependent] -= 1;
+      if (inDegree[dependent] === 0) {
+        queue.push(dependent);
+      }
+    }
+  }
+  if (result.length !== phases.length) {
+    const cycleNodes = phases.filter((p) => (inDegree[p] ?? 0) > 0);
+    throw new Error(
+      `Pipeline dependency cycle detected involving: [${cycleNodes.join(", ")}]. Check otter pipeline declarations for circular dependencies.`
+    );
+  }
+  return result;
+}
+function buildPipelineGraph(manifests) {
+  const sinkProducers = {};
+  const artifactProducers = {};
+  for (const m of manifests) {
+    const phase = manifestNameToPhase(m.name);
+    if (!phase) continue;
+    const out = m.pipeline?.outputs;
+    if (!out) continue;
+    for (const sink of out.sinks ?? []) {
+      if (sinkProducers[sink]) {
+        throw new Error(
+          `Sink "${sink}" is produced by both "${sinkProducers[sink]}" and "${phase}". Each sink must have exactly one producer.`
+        );
+      }
+      sinkProducers[sink] = phase;
+    }
+    if (out.artifact) {
+      if (artifactProducers[out.artifact]) {
+        throw new Error(
+          `Artifact "${out.artifact}" is produced by both "${artifactProducers[out.artifact]}" and "${phase}". Each artifact must have exactly one producer.`
+        );
+      }
+      artifactProducers[out.artifact] = phase;
+    }
+  }
+  const dependencies = {};
+  for (const m of manifests) {
+    const phase = manifestNameToPhase(m.name);
+    if (!phase) continue;
+    const deps = /* @__PURE__ */ new Set();
+    const inp = m.pipeline?.inputs;
+    if (inp) {
+      for (const sink of inp.sinks ?? []) {
+        const producer = sinkProducers[sink];
+        if (!producer) {
+          throw new Error(
+            `Phase "${phase}" declares sink input "${sink}" but no otter produces it. Add an otter with outputs.sinks including "${sink}".`
+          );
+        }
+        if (producer !== phase) deps.add(producer);
+      }
+      for (const artifact of inp.artifacts ?? []) {
+        const producer = artifactProducers[artifact];
+        if (!producer) {
+          throw new Error(
+            `Phase "${phase}" declares artifact input "${artifact}" but no otter produces it. Add an otter with outputs.artifact = "${artifact}".`
+          );
+        }
+        if (producer !== phase) deps.add(producer);
+      }
+    }
+    dependencies[phase] = Array.from(deps);
+  }
+  const order = topologicalSort(dependencies);
+  return { dependencies, order, sinkProducers, artifactProducers };
+}
+var DISTRIBUTED_NAMESPACES = ["@stackwright-pro", "@stackwright"];
+function loadDistributedOtterManifests(cwd) {
+  const results = [];
+  for (const namespace of DISTRIBUTED_NAMESPACES) {
+    const nsDir = (0, import_path5.join)(cwd, "node_modules", namespace);
+    let pkgDirNames;
+    try {
+      pkgDirNames = (0, import_fs5.readdirSync)(nsDir);
+    } catch {
+      continue;
+    }
+    for (const pkgDirName of pkgDirNames) {
+      const pkgDir = (0, import_path5.join)(nsDir, pkgDirName);
+      const packageName = `${namespace}/${pkgDirName}`;
+      let otterRelPaths;
+      try {
+        const raw = (0, import_fs5.readFileSync)((0, import_path5.join)(pkgDir, "package.json"), "utf-8");
+        const pkgJson = JSON.parse(raw);
+        const declared = pkgJson.stackwright?.otters;
+        if (!Array.isArray(declared) || declared.length === 0) continue;
+        otterRelPaths = declared;
+      } catch {
+        continue;
+      }
+      for (const relPath of otterRelPaths) {
+        const otterFilePath = (0, import_path5.join)(pkgDir, relPath);
+        try {
+          const raw = (0, import_fs5.readFileSync)(otterFilePath, "utf-8");
+          const manifest = JSON.parse(raw);
+          results.push({ manifest, packageName });
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          console.warn(
+            `[pipeline-graph] Failed to load distributed otter at "${otterFilePath}" from "${packageName}": ${msg}`
+          );
+        }
+      }
+    }
+  }
+  return results;
+}
+function _mergeManifestPools(central, distributed) {
+  const centralNames = new Set(central.map((m) => m.name));
+  const merged = [...central];
+  for (const { manifest, packageName } of distributed) {
+    if (centralNames.has(manifest.name)) {
+      console.warn(
+        `[pipeline-graph] Otter "${manifest.name}" declared by both @stackwright-pro/otters and ${packageName} \u2014 using @stackwright-pro/otters version.`
+      );
+    } else {
+      merged.push(manifest);
+    }
+  }
+  return merged;
+}
+var _cachedGraph = null;
+function loadPipelineGraph() {
+  if (_cachedGraph) return _cachedGraph;
+  const otterDir = resolveOtterDirFromCwd();
+  const central = loadOtterManifestsFromDir(otterDir);
+  const distributed = loadDistributedOtterManifests(process.cwd());
+  const manifests = _mergeManifestPools(central, distributed);
+  _cachedGraph = buildPipelineGraph(manifests);
+  return _cachedGraph;
+}
+
 // src/tools/pipeline.ts
 var PHASE_ORDER = [
   "designer",
@@ -2691,45 +2911,15 @@ var PHASE_ORDER = [
   // generates app/ directory from config
   "api",
   "data",
+  "auth",
+  // moved earlier — only depends on design-language.json (designer)
   "geo",
   "workflow",
   "services",
   "pages",
   "dashboard",
-  "auth",
   "polish"
 ];
-var PHASE_DEPENDENCIES = {
-  designer: [],
-  theme: ["designer"],
-  scaffold: ["designer", "theme"],
-  // needs stackwright.yml + theme-tokens
-  api: [],
-  data: ["api"],
-  geo: ["data"],
-  // workflow: no hard deps — uses service: references with Prism mock fallback
-  // when API artifacts aren't available; roles come from user answers
-  workflow: [],
-  // services: needs API endpoints to know what to wire, and optionally
-  // workflow states as trigger sources. Produces OpenAPI specs consumed
-  // by pages and dashboard for typed data wiring.
-  services: ["api", "workflow"],
-  // pages/dashboard: depend on services for typed endpoint wiring (OpenAPI
-  // specs) and on geo so the specialist prompt includes geo-manifest.json
-  // — page/dashboard otters see which page slugs are already claimed and
-  // won't attempt to overwrite them (swp-73c). 'api' is still transitive
-  // through 'data'; auth removed — page-otter has graceful fallback.
-  pages: ["designer", "theme", "data", "services", "geo", "scaffold"],
-  dashboard: ["designer", "theme", "data", "services", "geo", "scaffold"],
-  // auth is the penultimate phase — runs after all content-producing phases
-  // so it can read pages, dashboard, workflow, and geo artifacts for route
-  // protection and RBAC wiring. Skipped upstream phases still satisfy deps
-  // (the foreman marks them executed=true), so auth always runs.
-  auth: ["pages", "dashboard", "workflow", "geo"],
-  // polish is the terminal phase — runs after auth so the landing page and
-  // nav reflect the final set of protected routes and all generated pages.
-  polish: ["auth"]
-};
 var PHASE_ARTIFACT = {
   designer: "design-language.json",
   theme: "theme-tokens.json",
@@ -2753,7 +2943,7 @@ var PHASE_TO_OTTER2 = {
   data: "stackwright-pro-data-otter",
   pages: "stackwright-pro-page-otter",
   dashboard: "stackwright-pro-dashboard-otter",
-  workflow: "stackwright-pro-workflow-otter",
+  workflow: "stackwright-pro-form-wizard-otter",
   services: "stackwright-services-otter",
   polish: "stackwright-pro-polish-otter",
   geo: "stackwright-pro-geo-otter"
@@ -2786,11 +2976,11 @@ function createDefaultState() {
   };
 }
 function statePath(cwd) {
-  return (0, import_path5.join)(cwd, ".stackwright", "pipeline-state.json");
+  return (0, import_path6.join)(cwd, ".stackwright", "pipeline-state.json");
 }
 function readState(cwd) {
   const p = statePath(cwd);
-  if (!(0, import_fs5.existsSync)(p)) return createDefaultState();
+  if (!(0, import_fs6.existsSync)(p)) return createDefaultState();
   const raw = JSON.parse(safeReadSync(p));
   if (typeof raw !== "object" || raw === null || raw.version !== "1.0") {
     return createDefaultState();
@@ -2798,26 +2988,26 @@ function readState(cwd) {
   return raw;
 }
 function safeWriteSync(filePath, content) {
-  if ((0, import_fs5.existsSync)(filePath)) {
-    const stat = (0, import_fs5.lstatSync)(filePath);
+  if ((0, import_fs6.existsSync)(filePath)) {
+    const stat = (0, import_fs6.lstatSync)(filePath);
     if (stat.isSymbolicLink()) {
       throw new Error(`Refusing to write to symlink: ${filePath}`);
     }
   }
-  (0, import_fs5.writeFileSync)(filePath, content);
+  (0, import_fs6.writeFileSync)(filePath, content);
 }
 function safeReadSync(filePath) {
-  if ((0, import_fs5.existsSync)(filePath)) {
-    const stat = (0, import_fs5.lstatSync)(filePath);
+  if ((0, import_fs6.existsSync)(filePath)) {
+    const stat = (0, import_fs6.lstatSync)(filePath);
     if (stat.isSymbolicLink()) {
       throw new Error(`Refusing to read symlink: ${filePath}`);
     }
   }
-  return (0, import_fs5.readFileSync)(filePath, "utf-8");
+  return (0, import_fs6.readFileSync)(filePath, "utf-8");
 }
 function writeState(cwd, state) {
-  const dir = (0, import_path5.join)(cwd, ".stackwright");
-  (0, import_fs5.mkdirSync)(dir, { recursive: true });
+  const dir = (0, import_path6.join)(cwd, ".stackwright");
+  (0, import_fs6.mkdirSync)(dir, { recursive: true });
   state.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
   safeWriteSync(statePath(cwd), JSON.stringify(state, null, 2) + "\n");
 }
@@ -2838,8 +3028,8 @@ function handleGetPipelineState(_cwd) {
   const cwd = _cwd ?? process.cwd();
   try {
     const state = readState(cwd);
-    const keyPath = (0, import_path5.join)(cwd, ".stackwright", "pipeline-keys.json");
-    if (!(0, import_fs5.existsSync)(keyPath)) {
+    const keyPath = (0, import_path6.join)(cwd, ".stackwright", "pipeline-keys.json");
+    if (!(0, import_fs6.existsSync)(keyPath)) {
       try {
         const { fingerprint } = initPipelineKeys(cwd);
         state["signingKeyFingerprint"] = fingerprint;
@@ -2942,8 +3132,8 @@ function handleCheckExecutionReady(_cwd, phase) {
         isError: true
       };
     }
-    const answerFile = (0, import_path5.join)(cwd, ".stackwright", "answers", `${phase}.json`);
-    if (!(0, import_fs5.existsSync)(answerFile)) {
+    const answerFile = (0, import_path6.join)(cwd, ".stackwright", "answers", `${phase}.json`);
+    if (!(0, import_fs6.existsSync)(answerFile)) {
       return {
         text: JSON.stringify({ ready: false, phase, reason: "Answer file not found" }),
         isError: false
@@ -2967,12 +3157,12 @@ function handleCheckExecutionReady(_cwd, phase) {
     }
   }
   try {
-    const answersDir = (0, import_path5.join)(cwd, ".stackwright", "answers");
+    const answersDir = (0, import_path6.join)(cwd, ".stackwright", "answers");
     const answeredPhases = [];
     const missingPhases = [];
     for (const phase2 of PHASE_ORDER) {
-      const answerFile = (0, import_path5.join)(answersDir, `${phase2}.json`);
-      if ((0, import_fs5.existsSync)(answerFile)) {
+      const answerFile = (0, import_path6.join)(answersDir, `${phase2}.json`);
+      if ((0, import_fs6.existsSync)(answerFile)) {
         try {
           const raw = safeReadSync(answerFile);
           const parsed = JSON.parse(raw);
@@ -3005,6 +3195,7 @@ function handleGetReadyPhases(_cwd) {
   const cwd = _cwd ?? process.cwd();
   try {
     const state = readState(cwd);
+    const graph = loadPipelineGraph();
     const completed = [];
     const ready = [];
     const blocked = [];
@@ -3014,7 +3205,7 @@ function handleGetReadyPhases(_cwd) {
         completed.push(phase);
         continue;
       }
-      const deps = PHASE_DEPENDENCIES[phase];
+      const deps = graph.dependencies[phase] ?? [];
       const unmetDeps = deps.filter((dep) => !state.phases[dep]?.executed);
       if (unmetDeps.length === 0) {
         ready.push(phase);
@@ -3040,7 +3231,7 @@ function handleGetReadyPhases(_cwd) {
 function handleListArtifacts(_cwd) {
   const cwd = _cwd ?? process.cwd();
   try {
-    const artifactsDir = (0, import_path5.join)(cwd, ".stackwright", "artifacts");
+    const artifactsDir = (0, import_path6.join)(cwd, ".stackwright", "artifacts");
     let manifest = null;
     try {
       manifest = loadSignatureManifest(cwd);
@@ -3050,8 +3241,8 @@ function handleListArtifacts(_cwd) {
     let completedCount = 0;
     for (const phase of PHASE_ORDER) {
       const expectedFile = PHASE_ARTIFACT[phase];
-      const fullPath = (0, import_path5.join)(artifactsDir, expectedFile);
-      const exists = (0, import_fs5.existsSync)(fullPath);
+      const fullPath = (0, import_path6.join)(artifactsDir, expectedFile);
+      const exists = (0, import_fs6.existsSync)(fullPath);
       if (exists) completedCount++;
       let signed = false;
       let signatureValid = null;
@@ -3104,9 +3295,9 @@ function handleWritePhaseQuestions(input) {
       }
     } catch {
     }
-    const questionsDir = (0, import_path5.join)(cwd, ".stackwright", "questions");
-    (0, import_fs5.mkdirSync)(questionsDir, { recursive: true });
-    const filePath = (0, import_path5.join)(questionsDir, `${phase}.json`);
+    const questionsDir = (0, import_path6.join)(cwd, ".stackwright", "questions");
+    (0, import_fs6.mkdirSync)(questionsDir, { recursive: true });
+    const filePath = (0, import_path6.join)(questionsDir, `${phase}.json`);
     const payload = {
       version: "1.0",
       phase,
@@ -3146,14 +3337,14 @@ function handleBuildSpecialistPrompt(input) {
     };
   }
   try {
-    const answersPath = (0, import_path5.join)(cwd, ".stackwright", "answers", `${phase}.json`);
+    const answersPath = (0, import_path6.join)(cwd, ".stackwright", "answers", `${phase}.json`);
     let answers = {};
-    if ((0, import_fs5.existsSync)(answersPath)) {
+    if ((0, import_fs6.existsSync)(answersPath)) {
       answers = JSON.parse(safeReadSync(answersPath));
     }
     let buildContextText = "";
-    const buildContextPath = (0, import_path5.join)(cwd, ".stackwright", "build-context.json");
-    if ((0, import_fs5.existsSync)(buildContextPath)) {
+    const buildContextPath = (0, import_path6.join)(cwd, ".stackwright", "build-context.json");
+    if ((0, import_fs6.existsSync)(buildContextPath)) {
       try {
         const bcRaw = JSON.parse(safeReadSync(buildContextPath));
         if (typeof bcRaw.buildContext === "string" && bcRaw.buildContext.trim().length > 0) {
@@ -3162,13 +3353,14 @@ function handleBuildSpecialistPrompt(input) {
       } catch {
       }
     }
-    const deps = PHASE_DEPENDENCIES[phase];
+    const graph = loadPipelineGraph();
+    const deps = graph.dependencies[phase] ?? [];
     const artifactSections = [];
     const missingDependencies = [];
     for (const dep of deps) {
       const artifactFile = PHASE_ARTIFACT[dep];
-      const artifactPath = (0, import_path5.join)(cwd, ".stackwright", "artifacts", artifactFile);
-      if ((0, import_fs5.existsSync)(artifactPath)) {
+      const artifactPath = (0, import_path6.join)(cwd, ".stackwright", "artifacts", artifactFile);
+      if ((0, import_fs6.existsSync)(artifactPath)) {
         const rawContent = safeReadSync(artifactPath);
         const rawBytes = Buffer.from(rawContent, "utf-8");
         const content = JSON.parse(rawContent);
@@ -3233,8 +3425,8 @@ ${JSON.stringify(content, null, 2)}`
       parts.push("BUILD_CONTEXT:", buildContextText, "");
     }
     if (phase === "auth") {
-      const initContextPath = (0, import_path5.join)(cwd, ".stackwright", "init-context.json");
-      if ((0, import_fs5.existsSync)(initContextPath)) {
+      const initContextPath = (0, import_path6.join)(cwd, ".stackwright", "init-context.json");
+      if ((0, import_fs6.existsSync)(initContextPath)) {
         try {
           const initContext = JSON.parse(safeReadSync(initContextPath));
           if (initContext.devOnly === true || initContext.nonInteractive === true) {
@@ -3466,7 +3658,7 @@ var PHASE_ARTIFACT_SCHEMA = {
   workflow: JSON.stringify(
     {
       version: "1.0",
-      generatedBy: "stackwright-pro-workflow-otter",
+      generatedBy: "stackwright-pro-form-wizard-otter",
       // Root key is `workflow` — NOT `workflowConfig` (see swp-k7cl)
       workflow: {
         id: "procurement-approval",
@@ -3676,6 +3868,57 @@ function handleValidateArtifact(input) {
         const issues = result.error.issues.slice(0, 3).map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
         return { success: false, error: { message: issues } };
       }
+      const rbacRoles = authConfig["rbacRoles"];
+      const rbacDefaultRole = authConfig["rbacDefaultRole"];
+      const protectedRoutes = authConfig["protectedRoutes"];
+      if (Array.isArray(rbacRoles) && rbacRoles.length > 2 && Array.isArray(protectedRoutes) && protectedRoutes.length > 0 && typeof rbacDefaultRole === "string") {
+        const uniqueRoles = new Set(
+          protectedRoutes.map(
+            (r) => typeof r === "string" ? rbacDefaultRole : r.requiredRole ?? rbacDefaultRole
+          )
+        );
+        if (uniqueRoles.size === 1 && uniqueRoles.has(rbacDefaultRole)) {
+          return {
+            success: false,
+            error: {
+              message: `RBAC theatre detected: all ${protectedRoutes.length} protectedRoutes require '${rbacDefaultRole}' (the defaultRole), but ${rbacRoles.length} roles are defined. This defeats the RBAC hierarchy. Each route MUST have the minimum role required for its function. See auth-otter PER-ROUTE RBAC GRANULARITY section.`
+            }
+          };
+        }
+      }
+      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.
+    // Skips gracefully when wizard-otter didn't run (Pro-only install) or declared no hooks.
+    services: (artifact2) => {
+      const workflowArtifactPath = (0, import_path6.join)(cwd, ".stackwright", "artifacts", "workflow-config.json");
+      if (!(0, import_fs6.existsSync)(workflowArtifactPath)) {
+        return { success: true };
+      }
+      let workflowArtifact;
+      try {
+        workflowArtifact = JSON.parse((0, import_fs6.readFileSync)(workflowArtifactPath, "utf-8"));
+      } catch {
+        return { success: true };
+      }
+      const declaredHooks = workflowArtifact.serviceHooks ?? [];
+      if (declaredHooks.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));
+      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."
+          }
+        };
+      }
       return { success: true };
     }
   };
@@ -3693,10 +3936,10 @@ function handleValidateArtifact(input) {
     }
   }
   try {
-    const artifactsDir = (0, import_path5.join)(cwd, ".stackwright", "artifacts");
-    (0, import_fs5.mkdirSync)(artifactsDir, { recursive: true });
+    const artifactsDir = (0, import_path6.join)(cwd, ".stackwright", "artifacts");
+    (0, import_fs6.mkdirSync)(artifactsDir, { recursive: true });
     const artifactFile = PHASE_ARTIFACT[phase];
-    const artifactPath = (0, import_path5.join)(artifactsDir, artifactFile);
+    const artifactPath = (0, import_path6.join)(artifactsDir, artifactFile);
     const serialized = JSON.stringify(artifact, null, 2) + "\n";
     const artifactBytes = Buffer.from(serialized, "utf-8");
     safeWriteSync(artifactPath, serialized);
@@ -3813,10 +4056,10 @@ function registerPipelineTools(server2) {
             isError: true
           };
         }
-        const questionsDir = (0, import_path5.join)(process.cwd(), ".stackwright", "questions");
-        (0, import_fs5.mkdirSync)(questionsDir, { recursive: true });
-        const outPath = (0, import_path5.join)(questionsDir, `${phase}.json`);
-        (0, import_fs5.writeFileSync)(
+        const questionsDir = (0, import_path6.join)(process.cwd(), ".stackwright", "questions");
+        (0, import_fs6.mkdirSync)(questionsDir, { recursive: true });
+        const outPath = (0, import_path6.join)(questionsDir, `${phase}.json`);
+        (0, import_fs6.writeFileSync)(
           outPath,
           JSON.stringify({ phase, questions, writtenAt: (/* @__PURE__ */ new Date()).toISOString() }, null, 2)
         );
@@ -3867,8 +4110,8 @@ function registerPipelineTools(server2) {
 
 // src/tools/safe-write.ts
 var import_zod14 = require("zod");
-var import_fs6 = require("fs");
-var import_path6 = require("path");
+var import_fs7 = require("fs");
+var import_path7 = require("path");
 var OTTER_WRITE_ALLOWLISTS = {
   "stackwright-pro-designer-otter": [
     { prefix: ".stackwright/artifacts/", suffix: ".json", description: "Design language artifact" }
@@ -3883,8 +4126,11 @@ var OTTER_WRITE_ALLOWLISTS = {
   ],
   "stackwright-pro-auth-otter": [
     { prefix: ".stackwright/artifacts/", suffix: ".json", description: "Auth config artifact" },
-    { prefix: "config/", suffix: ".yml", description: "Auth YAML config" },
-    { prefix: "config/", suffix: ".yaml", description: "Auth YAML config" },
+    {
+      prefix: "stackwright.auth.",
+      suffix: ".yml",
+      description: "Auth config YAML (stackwright.auth.yml \u2014 compiled to _auth.json)"
+    },
     {
       prefix: ".env",
       suffix: "",
@@ -3903,7 +4149,11 @@ var OTTER_WRITE_ALLOWLISTS = {
   ],
   "stackwright-pro-data-otter": [
     { prefix: ".stackwright/artifacts/", suffix: ".json", description: "Data config artifact" },
-    { prefix: "stackwright.yml", suffix: "", description: "Stackwright config" }
+    {
+      prefix: "stackwright.collections.",
+      suffix: ".yml",
+      description: "Collections config YAML (stackwright.collections.yml \u2014 compiled to _collections.json)"
+    }
   ],
   "stackwright-pro-page-otter": [
     { prefix: "pages/", suffix: "/content.yml", description: "Page content YAML" },
@@ -3915,7 +4165,7 @@ var OTTER_WRITE_ALLOWLISTS = {
     { prefix: "pages/", suffix: "/content.yaml", description: "Dashboard content YAML" },
     { prefix: ".stackwright/artifacts/", suffix: ".json", description: "Dashboard manifest" }
   ],
-  "stackwright-pro-workflow-otter": [
+  "stackwright-pro-form-wizard-otter": [
     { prefix: "workflows/", suffix: ".yml", description: "Workflow definition" },
     { prefix: "workflows/", suffix: ".yaml", description: "Workflow definition" },
     { prefix: ".stackwright/artifacts/", suffix: ".json", description: "Workflow config" }
@@ -3929,7 +4179,12 @@ var OTTER_WRITE_ALLOWLISTS = {
     }
   ],
   "stackwright-pro-api-otter": [
-    { prefix: ".stackwright/artifacts/", suffix: ".json", description: "API config artifact" }
+    { prefix: ".stackwright/artifacts/", suffix: ".json", description: "API config artifact" },
+    {
+      prefix: "stackwright.integrations.",
+      suffix: ".yml",
+      description: "Integrations config YAML (stackwright.integrations.yml \u2014 compiled to _integrations.json)"
+    }
   ],
   "stackwright-pro-geo-otter": [
     { prefix: ".stackwright/artifacts/", suffix: ".json", description: "Geo manifest artifact" },
@@ -3992,7 +4247,7 @@ function getMaxBytesForPath(filePath) {
 }
 var PAGE_REGISTRY_FILE = ".stackwright/page-registry.json";
 function extractPageSlug(filePath) {
-  const match = (0, import_path6.normalize)(filePath).match(/^pages\/(.+?)\/content\.ya?ml$/);
+  const match = (0, import_path7.normalize)(filePath).match(/^pages\/(.+?)\/content\.ya?ml$/);
   return match?.[1] ?? null;
 }
 function extractContentTypes(yamlContent) {
@@ -4008,27 +4263,27 @@ function extractContentTypes(yamlContent) {
   return types.length > 0 ? types : ["unknown"];
 }
 function readPageRegistry(cwd) {
-  const regPath = (0, import_path6.join)(cwd, PAGE_REGISTRY_FILE);
-  if (!(0, import_fs6.existsSync)(regPath)) return {};
+  const regPath = (0, import_path7.join)(cwd, PAGE_REGISTRY_FILE);
+  if (!(0, import_fs7.existsSync)(regPath)) return {};
   try {
-    const stat = (0, import_fs6.lstatSync)(regPath);
+    const stat = (0, import_fs7.lstatSync)(regPath);
     if (stat.isSymbolicLink()) return {};
-    return JSON.parse((0, import_fs6.readFileSync)(regPath, "utf-8"));
+    return JSON.parse((0, import_fs7.readFileSync)(regPath, "utf-8"));
   } catch {
     return {};
   }
 }
 function writePageRegistry(cwd, registry) {
-  const dir = (0, import_path6.join)(cwd, ".stackwright");
-  (0, import_fs6.mkdirSync)(dir, { recursive: true });
-  const regPath = (0, import_path6.join)(cwd, PAGE_REGISTRY_FILE);
-  if ((0, import_fs6.existsSync)(regPath)) {
-    const stat = (0, import_fs6.lstatSync)(regPath);
+  const dir = (0, import_path7.join)(cwd, ".stackwright");
+  (0, import_fs7.mkdirSync)(dir, { recursive: true });
+  const regPath = (0, import_path7.join)(cwd, PAGE_REGISTRY_FILE);
+  if ((0, import_fs7.existsSync)(regPath)) {
+    const stat = (0, import_fs7.lstatSync)(regPath);
     if (stat.isSymbolicLink()) {
       throw new Error("Refusing to write page registry through symlink");
     }
   }
-  (0, import_fs6.writeFileSync)(regPath, JSON.stringify(registry, null, 2) + "\n", { encoding: "utf-8" });
+  (0, import_fs7.writeFileSync)(regPath, JSON.stringify(registry, null, 2) + "\n", { encoding: "utf-8" });
 }
 function checkPageOwnership(cwd, slug, callerOtter) {
   const registry = readPageRegistry(cwd);
@@ -4043,15 +4298,15 @@ function checkPageOwnership(cwd, slug, callerOtter) {
   };
 }
 var NEXTJS_BRACKET_SEGMENT_RE = /\[\[\.{3}[a-zA-Z_][a-zA-Z0-9_]*\]\]|\[\.{3}[a-zA-Z_][a-zA-Z0-9_]*\]|\[[a-zA-Z_][a-zA-Z0-9_]*\]/g;
-function stripNextjsBracketSegments(path3) {
-  return path3.replace(NEXTJS_BRACKET_SEGMENT_RE, "");
+function stripNextjsBracketSegments(path4) {
+  return path4.replace(NEXTJS_BRACKET_SEGMENT_RE, "");
 }
 function checkPathAllowed(callerOtter, filePath) {
-  const normalized = (0, import_path6.normalize)(filePath);
+  const normalized = (0, import_path7.normalize)(filePath);
   if (stripNextjsBracketSegments(normalized).includes("..")) {
     return { allowed: false, error: 'Path traversal detected: ".." segments are not allowed' };
   }
-  if ((0, import_path6.isAbsolute)(normalized)) {
+  if ((0, import_path7.isAbsolute)(normalized)) {
     return {
       allowed: false,
       error: "Absolute paths are not allowed \u2014 use paths relative to project root"
@@ -4193,11 +4448,11 @@ function handleSafeWrite(input) {
     };
     return { text: JSON.stringify(result), isError: true };
   }
-  const normalized = (0, import_path6.normalize)(filePath);
-  const fullPath = (0, import_path6.join)(cwd, normalized);
-  if ((0, import_fs6.existsSync)(fullPath)) {
+  const normalized = (0, import_path7.normalize)(filePath);
+  const fullPath = (0, import_path7.join)(cwd, normalized);
+  if ((0, import_fs7.existsSync)(fullPath)) {
     try {
-      const stat = (0, import_fs6.lstatSync)(fullPath);
+      const stat = (0, import_fs7.lstatSync)(fullPath);
       if (stat.isSymbolicLink()) {
         const result = {
           success: false,
@@ -4238,9 +4493,9 @@ function handleSafeWrite(input) {
   }
   try {
     if (createDirectories) {
-      (0, import_fs6.mkdirSync)((0, import_path6.dirname)(fullPath), { recursive: true });
+      (0, import_fs7.mkdirSync)((0, import_path7.dirname)(fullPath), { recursive: true });
     }
-    (0, import_fs6.writeFileSync)(fullPath, content, { encoding: "utf-8" });
+    (0, import_fs7.writeFileSync)(fullPath, content, { encoding: "utf-8" });
     if (pageSlug) {
       try {
         const registry = readPageRegistry(cwd);
@@ -4300,8 +4555,8 @@ function registerSafeWriteTools(server2) {
 
 // src/tools/auth.ts
 var import_zod15 = require("zod");
-var import_fs7 = require("fs");
-var import_path7 = require("path");
+var import_fs8 = require("fs");
+var import_path8 = require("path");
 function buildHierarchy(roles) {
   const h = {};
   for (let i = 0; i < roles.length - 1; i++) {
@@ -4315,17 +4570,22 @@ function hierarchyToYaml(hierarchy, indent) {
   return entries.map(([role, subs]) => `${indent}${role}: [${subs.join(", ")}]`).join("\n");
 }
 function rolesToYaml(roles, indent) {
-  return roles.map((r) => `${indent}- ${r}`).join("\n");
+  return roles.map((r) => `${indent}- name: ${r}`).join("\n");
 }
-function routesToYaml(routes, defaultRole, indent) {
-  return routes.map((r) => `${indent}- pattern: ${r}
-${indent}  requiredRole: ${defaultRole}`).join("\n");
+function normalizeRoutes(routes, defaultRole) {
+  return routes.map(
+    (r) => typeof r === "string" ? { pattern: r, requiredRole: defaultRole } : { pattern: r.pattern, requiredRole: r.requiredRole ?? defaultRole }
+  );
+}
+function routesToYaml(routes, indent) {
+  return routes.map((r) => `${indent}- pattern: ${r.pattern}
+${indent}  requiredRole: ${r.requiredRole}`).join("\n");
 }
 function detectNextMajorVersion(cwd) {
   try {
-    const pkgPath = (0, import_path7.join)(cwd, "package.json");
-    if (!(0, import_fs7.existsSync)(pkgPath)) return null;
-    const pkg = JSON.parse((0, import_fs7.readFileSync)(pkgPath, "utf8"));
+    const pkgPath = (0, import_path8.join)(cwd, "package.json");
+    if (!(0, import_fs8.existsSync)(pkgPath)) return null;
+    const pkg = JSON.parse((0, import_fs8.readFileSync)(pkgPath, "utf8"));
     const nextVersion = pkg.dependencies?.next ?? pkg.devDependencies?.next;
     if (!nextVersion) return null;
     const match = nextVersion.match(/(\d+)/);
@@ -4334,25 +4594,6 @@ function detectNextMajorVersion(cwd) {
     return null;
   }
 }
-function upsertAuthBlock(existing, authYaml) {
-  const lines = existing.split("\n");
-  let authStart = -1;
-  let authEnd = lines.length;
-  for (let i = 0; i < lines.length; i++) {
-    if (/^auth:/.test(lines[i])) {
-      authStart = i;
-    } else if (authStart >= 0 && i > authStart && /^\S/.test(lines[i]) && lines[i].trim() !== "") {
-      authEnd = i;
-      break;
-    }
-  }
-  if (authStart < 0) {
-    return existing.trimEnd() + "\n" + authYaml + "\n";
-  }
-  const before = lines.slice(0, authStart);
-  const after = lines.slice(authEnd);
-  return [...before, ...authYaml.trimEnd().split("\n"), ...after.length ? after : []].join("\n");
-}
 function generateMiddlewareContent(method, params, roles, defaultRole, hierarchy, auditEnabled, auditRetentionDays, protectedRoutes) {
   const rbacBlock = `  rbac: {
     roles: ${JSON.stringify(roles)},
@@ -4363,9 +4604,10 @@ function generateMiddlewareContent(method, params, roles, defaultRole, hierarchy
     enabled: ${auditEnabled},
     retentionDays: ${auditRetentionDays},
   },`;
-  const routesBlock = `  protectedRoutes: ${JSON.stringify(protectedRoutes)},`;
+  const patterns = protectedRoutes.map((r) => r.pattern);
+  const routesBlock = `  protectedRoutes: ${JSON.stringify(patterns)},`;
   const configBlock = `export const config = {
-  matcher: ${JSON.stringify(protectedRoutes)},
+  matcher: ${JSON.stringify(patterns)},
 };`;
   if (method === "cac") {
     const caBundle = params.cacCaBundle ?? "./certs/dod-ca-bundle.pem";
@@ -4448,9 +4690,10 @@ function generateProxyContent(method, params, roles, defaultRole, hierarchy, aud
     enabled: ${auditEnabled},
     retentionDays: ${auditRetentionDays},
   },`;
-  const routesBlock = `  protectedRoutes: ${JSON.stringify(protectedRoutes)},`;
+  const patterns = protectedRoutes.map((r) => r.pattern);
+  const routesBlock = `  protectedRoutes: ${JSON.stringify(patterns)},`;
   const configBlock = `export const config = {
-  matcher: ${JSON.stringify(protectedRoutes)},
+  matcher: ${JSON.stringify(patterns)},
 };`;
   if (method === "cac") {
     const caBundle = params.cacCaBundle ?? "./certs/dod-ca-bundle.pem";
@@ -4550,36 +4793,33 @@ OAUTH2_CLIENT_SECRET=your-client-secret
 `;
 }
 function generateYamlBlock(method, params, roles, defaultRole, hierarchy, auditEnabled, auditRetentionDays, protectedRoutes, useProxy) {
-  const rbacSection = `  rbac:
-    roles:
-${rolesToYaml(roles, "      ")}
-    defaultRole: ${defaultRole}
-    hierarchy:
-${hierarchyToYaml(hierarchy, "      ")}`;
-  const auditSection = `  audit:
-    enabled: ${auditEnabled}
-    retentionDays: ${auditRetentionDays}`;
-  const routesSection = `  protectedRoutes:
-${routesToYaml(protectedRoutes, "    ", defaultRole)}`.replace(/\n\s+,/g, "");
-  const routeLines = protectedRoutes.map((r) => `    - pattern: ${r}
-      requiredRole: ${defaultRole}`).join("\n");
-  const providerLine = params.provider ? `  provider: ${params.provider}
+  const rbacSection = `rbac:
+  roles:
+${rolesToYaml(roles, "    ")}
+  defaultRole: ${defaultRole}
+  hierarchy:
+${hierarchyToYaml(hierarchy, "    ")}`;
+  const auditSection = `audit:
+  enabled: ${auditEnabled}
+  retentionDays: ${auditRetentionDays}`;
+  const routeLines = routesToYaml(protectedRoutes, "  ");
+  const providerLine = params.provider ? `provider: ${params.provider}
 ` : "";
   if (method === "cac") {
     const caBundle = params.cacCaBundle ?? "./certs/dod-ca-bundle.pem";
     const edipiLookup = params.cacEdipiLookup ?? "./config/edipi-lookup.json";
     const ocspEndpoint = params.cacOcspEndpoint ?? "https://ocsp.disa.mil";
     const certHeader = params.cacCertHeader ?? "X-SSL-Client-Cert";
-    return `auth:
-  method: cac
-${providerLine}  ${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
-  cac:
-    caBundle: \${CAC_CA_BUNDLE}
-    edipiLookup: ${edipiLookup}
-    ocspEndpoint: \${CAC_OCSP_ENDPOINT}
-    certHeader: ${certHeader}
+    return `# stackwright.auth.yml \u2014 generated by Auth Otter
+method: cac
+${providerLine}${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
+cac:
+  caBundle: \${CAC_CA_BUNDLE}
+  edipiLookup: ${edipiLookup}
+  ocspEndpoint: \${CAC_OCSP_ENDPOINT}
+  certHeader: ${certHeader}
 ${rbacSection}
-  protectedRoutes:
+protectedRoutes:
 ${routeLines}
 ${auditSection}
 `;
@@ -4587,33 +4827,33 @@ ${auditSection}
   if (method === "oidc") {
     const scopes2 = params.oidcScopes ?? "openid profile email";
     const roleClaim = params.oidcRoleClaim ?? "roles";
-    return `auth:
-  method: oidc
-${providerLine}  ${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
-  oidc:
-    discoveryUrl: \${OIDC_DISCOVERY_URL}
-    clientId: \${OIDC_CLIENT_ID}
-    clientSecret: \${OIDC_CLIENT_SECRET}
-    scopes: ${scopes2}
-    roleClaim: ${roleClaim}
+    return `# stackwright.auth.yml \u2014 generated by Auth Otter
+method: oidc
+${providerLine}${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
+oidc:
+  discoveryUrl: \${OIDC_DISCOVERY_URL}
+  clientId: \${OIDC_CLIENT_ID}
+  clientSecret: \${OIDC_CLIENT_SECRET}
+  scopes: ${scopes2}
+  roleClaim: ${roleClaim}
 ${rbacSection}
-  protectedRoutes:
+protectedRoutes:
 ${routeLines}
 ${auditSection}
 `;
   }
   const scopes = params.oauth2Scopes ?? "read write";
-  return `auth:
-  method: oauth2
-${providerLine}  ${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
-  oauth2:
-    authorizationUrl: \${OAUTH2_AUTH_URL}
-    tokenUrl: \${OAUTH2_TOKEN_URL}
-    clientId: \${OAUTH2_CLIENT_ID}
-    clientSecret: \${OAUTH2_CLIENT_SECRET}
-    scopes: ${scopes}
+  return `# stackwright.auth.yml \u2014 generated by Auth Otter
+method: oauth2
+${providerLine}${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
+oauth2:
+  authorizationUrl: \${OAUTH2_AUTH_URL}
+  tokenUrl: \${OAUTH2_TOKEN_URL}
+  clientId: \${OAUTH2_CLIENT_ID}
+  clientSecret: \${OAUTH2_CLIENT_SECRET}
+  scopes: ${scopes}
 ${rbacSection}
-  protectedRoutes:
+protectedRoutes:
 ${routeLines}
 ${auditSection}
 `;
@@ -4628,9 +4868,10 @@ function generateDevOnlyMiddlewareContent(method, params, roles, defaultRole, hi
     enabled: ${auditEnabled},
     retentionDays: ${auditRetentionDays},
   },`;
-  const routesBlock = `  protectedRoutes: ${JSON.stringify(protectedRoutes)},`;
+  const patterns = protectedRoutes.map((r) => r.pattern);
+  const routesBlock = `  protectedRoutes: ${JSON.stringify(patterns)},`;
   const configBlock = `export const config = {
-  matcher: ${JSON.stringify(protectedRoutes)},
+  matcher: ${JSON.stringify(patterns)},
 };`;
   const devHeader = [
     "// middleware.ts \u2014 generated by @stackwright-pro/auth-nextjs (dev-only mock)",
@@ -4717,9 +4958,10 @@ function generateDevOnlyProxyContent(method, params, roles, defaultRole, hierarc
     enabled: ${auditEnabled},
     retentionDays: ${auditRetentionDays},
   },`;
-  const routesBlock = `  protectedRoutes: ${JSON.stringify(protectedRoutes)},`;
+  const patterns = protectedRoutes.map((r) => r.pattern);
+  const routesBlock = `  protectedRoutes: ${JSON.stringify(patterns)},`;
   const configBlock = `export const config = {
-  matcher: ${JSON.stringify(protectedRoutes)},
+  matcher: ${JSON.stringify(patterns)},
 };`;
   const devHeader = [
     "// proxy.ts -- generated by @stackwright-pro/auth (Next.js >=16, dev-only mock)",
@@ -4797,35 +5039,35 @@ ${configBlock}
 `;
 }
 function generateDevOnlyYamlBlock(method, params, roles, defaultRole, hierarchy, auditEnabled, auditRetentionDays, protectedRoutes, useProxy) {
-  const rbacSection = `  rbac:
-    roles:
-${rolesToYaml(roles, "      ")}
-    defaultRole: ${defaultRole}
-    hierarchy:
-${hierarchyToYaml(hierarchy, "      ")}`;
-  const auditSection = `  audit:
-    enabled: ${auditEnabled}
-    retentionDays: ${auditRetentionDays}`;
-  const routeLines = protectedRoutes.map((r) => `    - pattern: ${r}
-      requiredRole: ${defaultRole}`).join("\n");
-  const providerLine = params.provider ? `  provider: ${params.provider}
+  const rbacSection = `rbac:
+  roles:
+${rolesToYaml(roles, "    ")}
+  defaultRole: ${defaultRole}
+  hierarchy:
+${hierarchyToYaml(hierarchy, "    ")}`;
+  const auditSection = `audit:
+  enabled: ${auditEnabled}
+  retentionDays: ${auditRetentionDays}`;
+  const routeLines = protectedRoutes.map((r) => `  - pattern: ${r.pattern}
+    requiredRole: ${r.requiredRole}`).join("\n");
+  const providerLine = params.provider ? `provider: ${params.provider}
 ` : "";
   if (method === "cac") {
     const caBundle = params.cacCaBundle ?? "./certs/dod-ca-bundle.pem";
     const edipiLookup = params.cacEdipiLookup ?? "./config/edipi-lookup.json";
     const ocspEndpoint = params.cacOcspEndpoint ?? "https://ocsp.disa.mil";
     const certHeader = params.cacCertHeader ?? "X-SSL-Client-Cert";
-    return `auth:
-  method: cac
-  devOnly: true
-${providerLine}  ${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
-  cac:
-    caBundle: ${caBundle}
-    edipiLookup: ${edipiLookup}
-    ocspEndpoint: ${ocspEndpoint}
-    certHeader: ${certHeader}
+    return `# stackwright.auth.yml \u2014 generated by Auth Otter
+method: cac
+devOnly: true
+${providerLine}${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
+cac:
+  caBundle: ${caBundle}
+  edipiLookup: ${edipiLookup}
+  ocspEndpoint: ${ocspEndpoint}
+  certHeader: ${certHeader}
 ${rbacSection}
-  protectedRoutes:
+protectedRoutes:
 ${routeLines}
 ${auditSection}
 `;
@@ -4833,35 +5075,35 @@ ${auditSection}
   if (method === "oidc") {
     const scopes2 = params.oidcScopes ?? "openid profile email";
     const roleClaim = params.oidcRoleClaim ?? "roles";
-    return `auth:
-  method: oidc
-  devOnly: true
-${providerLine}  ${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
-  oidc:
-    discoveryUrl: https://dev-mock-oidc/.well-known/openid-configuration
-    clientId: dev-mock-client
-    clientSecret: dev-mock-secret
-    scopes: ${scopes2}
-    roleClaim: ${roleClaim}
+    return `# stackwright.auth.yml \u2014 generated by Auth Otter
+method: oidc
+devOnly: true
+${providerLine}${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
+oidc:
+  discoveryUrl: https://dev-mock-oidc/.well-known/openid-configuration
+  clientId: dev-mock-client
+  clientSecret: dev-mock-secret
+  scopes: ${scopes2}
+  roleClaim: ${roleClaim}
 ${rbacSection}
-  protectedRoutes:
+protectedRoutes:
 ${routeLines}
 ${auditSection}
 `;
   }
   const scopes = params.oauth2Scopes ?? "read write";
-  return `auth:
-  method: oauth2
-  devOnly: true
-${providerLine}  ${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
-  oauth2:
-    authorizationUrl: https://dev-mock-oauth2/authorize
-    tokenUrl: https://dev-mock-oauth2/token
-    clientId: dev-mock-client
-    clientSecret: dev-mock-secret
-    scopes: ${scopes}
+  return `# stackwright.auth.yml \u2014 generated by Auth Otter
+method: oauth2
+devOnly: true
+${providerLine}${useProxy ? "proxy" : "middleware"}: ./${useProxy ? "proxy" : "middleware"}.ts
+oauth2:
+  authorizationUrl: https://dev-mock-oauth2/authorize
+  tokenUrl: https://dev-mock-oauth2/token
+  clientId: dev-mock-client
+  clientSecret: dev-mock-secret
+  scopes: ${scopes}
 ${rbacSection}
-  protectedRoutes:
+protectedRoutes:
 ${routeLines}
 ${auditSection}
 `;
@@ -4940,6 +5182,7 @@ async function configureAuthHandler(params, cwd) {
   } = params;
   const roles = rbacRoles;
   const defaultRole = params.rbacDefaultRole ?? roles[roles.length - 1];
+  const normalizedRoutes = normalizeRoutes(protectedRoutes, defaultRole);
   const hierarchy = buildHierarchy(roles);
   const detectedVersion = params.nextMajorVersion ?? detectNextMajorVersion(cwd);
   const useProxy = (detectedVersion ?? 0) >= 16;
@@ -4976,7 +5219,7 @@ async function configureAuthHandler(params, cwd) {
       hierarchy,
       auditEnabled,
       auditRetentionDays,
-      protectedRoutes
+      normalizedRoutes
     ) : generateDevOnlyMiddlewareContent(
       effectiveMethod,
       params,
@@ -4985,7 +5228,7 @@ async function configureAuthHandler(params, cwd) {
       hierarchy,
       auditEnabled,
       auditRetentionDays,
-      protectedRoutes
+      normalizedRoutes
     ) : useProxy ? generateProxyContent(
       effectiveMethod,
       params,
@@ -4994,7 +5237,7 @@ async function configureAuthHandler(params, cwd) {
       hierarchy,
       auditEnabled,
       auditRetentionDays,
-      protectedRoutes
+      normalizedRoutes
     ) : generateMiddlewareContent(
       effectiveMethod,
       params,
@@ -5003,9 +5246,9 @@ async function configureAuthHandler(params, cwd) {
       hierarchy,
       auditEnabled,
       auditRetentionDays,
-      protectedRoutes
+      normalizedRoutes
     );
-    (0, import_fs7.writeFileSync)((0, import_path7.join)(cwd, conventionFile), authFileContent, "utf8");
+    (0, import_fs8.writeFileSync)((0, import_path8.join)(cwd, conventionFile), authFileContent, "utf8");
     filesWritten.push(conventionFile);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
@@ -5025,12 +5268,12 @@ async function configureAuthHandler(params, cwd) {
   if (!devOnly) {
     try {
       const envBlock = generateEnvBlock(effectiveMethod, params);
-      const envPath = (0, import_path7.join)(cwd, ".env.example");
-      if ((0, import_fs7.existsSync)(envPath)) {
-        const existing = (0, import_fs7.readFileSync)(envPath, "utf8");
-        (0, import_fs7.writeFileSync)(envPath, existing.trimEnd() + "\n\n" + envBlock, "utf8");
+      const envPath = (0, import_path8.join)(cwd, ".env.example");
+      if ((0, import_fs8.existsSync)(envPath)) {
+        const existing = (0, import_fs8.readFileSync)(envPath, "utf8");
+        (0, import_fs8.writeFileSync)(envPath, existing.trimEnd() + "\n\n" + envBlock, "utf8");
       } else {
-        (0, import_fs7.writeFileSync)(envPath, envBlock, "utf8");
+        (0, import_fs8.writeFileSync)(envPath, envBlock, "utf8");
       }
       filesWritten.push(".env.example");
     } catch (err) {
@@ -5048,10 +5291,10 @@ async function configureAuthHandler(params, cwd) {
   }
   if (devOnly) {
     try {
-      const mockAuthDir = (0, import_path7.join)(cwd, "lib");
-      (0, import_fs7.mkdirSync)(mockAuthDir, { recursive: true });
+      const mockAuthDir = (0, import_path8.join)(cwd, "lib");
+      (0, import_fs8.mkdirSync)(mockAuthDir, { recursive: true });
       const mockAuthContent = generateMockAuthContent(roles, mockUsers);
-      (0, import_fs7.writeFileSync)((0, import_path7.join)(mockAuthDir, "mock-auth.ts"), mockAuthContent, "utf8");
+      (0, import_fs8.writeFileSync)((0, import_path8.join)(mockAuthDir, "mock-auth.ts"), mockAuthContent, "utf8");
       filesWritten.push("lib/mock-auth.ts");
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
@@ -5069,11 +5312,11 @@ async function configureAuthHandler(params, cwd) {
       };
     }
     try {
-      const pkgPath = (0, import_path7.join)(cwd, "package.json");
-      if ((0, import_fs7.existsSync)(pkgPath)) {
-        const existingPkg = (0, import_fs7.readFileSync)(pkgPath, "utf8");
+      const pkgPath = (0, import_path8.join)(cwd, "package.json");
+      if ((0, import_fs8.existsSync)(pkgPath)) {
+        const existingPkg = (0, import_fs8.readFileSync)(pkgPath, "utf8");
         const updatedPkg = updatePackageJsonScripts(existingPkg, roles, mockUsers);
-        (0, import_fs7.writeFileSync)(pkgPath, updatedPkg, "utf8");
+        (0, import_fs8.writeFileSync)(pkgPath, updatedPkg, "utf8");
         filesWritten.push("package.json");
       }
     } catch (err) {
@@ -5101,7 +5344,7 @@ async function configureAuthHandler(params, cwd) {
       hierarchy,
       auditEnabled,
       auditRetentionDays,
-      protectedRoutes,
+      normalizedRoutes,
       useProxy
     ) : generateYamlBlock(
       effectiveMethod,
@@ -5111,24 +5354,21 @@ async function configureAuthHandler(params, cwd) {
       hierarchy,
       auditEnabled,
       auditRetentionDays,
-      protectedRoutes,
+      normalizedRoutes,
       useProxy
     );
-    const ymlPath = (0, import_path7.join)(cwd, "stackwright.yml");
-    if (!(0, import_fs7.existsSync)(ymlPath)) {
-      (0, import_fs7.writeFileSync)(ymlPath, authYaml, "utf8");
-    } else {
-      const existing = (0, import_fs7.readFileSync)(ymlPath, "utf8");
-      (0, import_fs7.writeFileSync)(ymlPath, upsertAuthBlock(existing, authYaml), "utf8");
-    }
-    filesWritten.push("stackwright.yml");
+    (0, import_fs8.writeFileSync)((0, import_path8.join)(cwd, "stackwright.auth.yml"), authYaml, "utf8");
+    filesWritten.push("stackwright.auth.yml");
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return {
       content: [
         {
           type: "text",
-          text: JSON.stringify({ success: false, error: `Failed writing stackwright.yml: ${msg}` })
+          text: JSON.stringify({
+            success: false,
+            error: `Failed writing stackwright.auth.yml: ${msg}`
+          })
         }
       ],
       isError: true
@@ -5173,7 +5413,7 @@ async function configureAuthHandler(params, cwd) {
 function registerAuthTools(server2) {
   server2.tool(
     "stackwright_pro_configure_auth",
-    "Generate authentication middleware and configuration for a Next.js Stackwright application. Writes `middleware.ts` from a secure template, appends/updates the `auth:` section in `stackwright.yml`, and generates `.env.example` with required environment variables. \u26A0\uFE0F For CAC/PKI: generated `middleware.ts` carries a SECURITY REVIEW REQUIRED comment \u2014 certificate chain validation must be verified by a DoD security officer before production deployment. This is the ONLY approved path to generating `middleware.ts`. Never write TypeScript auth files directly.",
+    "Generate authentication middleware and configuration for a Next.js Stackwright application. Writes `middleware.ts` (or `proxy.ts` for Next.js >=16) from a secure template, writes a standalone `stackwright.auth.yml` sibling file, and generates `.env.example` with required environment variables. \u26A0\uFE0F For CAC/PKI: generated `middleware.ts` carries a SECURITY REVIEW REQUIRED comment \u2014 certificate chain validation must be verified by a DoD security officer before production deployment. This is the ONLY approved path to generating `middleware.ts`. Never write TypeScript auth files directly.",
     {
       method: import_zod15.z.enum(["cac", "oidc", "oauth2", "none"]),
       provider: import_zod15.z.enum(["azure-ad", "okta", "ping", "cognito", "custom"]).optional(),
@@ -5200,8 +5440,15 @@ function registerAuthTools(server2) {
       // Audit
       auditEnabled: boolCoerce(import_zod15.z.boolean().optional()),
       auditRetentionDays: numCoerce(import_zod15.z.number().int().positive().optional()),
-      // Routes
-      protectedRoutes: jsonCoerce(import_zod15.z.array(import_zod15.z.string()).optional()),
+      // Routes — accepts bare strings (backward-compat) or per-route objects (swp-owu0)
+      protectedRoutes: jsonCoerce(
+        import_zod15.z.array(
+          import_zod15.z.union([
+            import_zod15.z.string(),
+            import_zod15.z.object({ pattern: import_zod15.z.string(), requiredRole: import_zod15.z.string().optional() })
+          ])
+        ).optional()
+      ),
       // Injection for tests
       _cwd: import_zod15.z.string().optional(),
       devOnly: boolCoerce(import_zod15.z.boolean().optional()),
@@ -5217,28 +5464,28 @@ function registerAuthTools(server2) {
 
 // src/integrity.ts
 var import_crypto4 = require("crypto");
-var import_fs8 = require("fs");
-var import_path8 = require("path");
+var import_fs9 = require("fs");
+var import_path9 = require("path");
 var _checksums = /* @__PURE__ */ new Map([
   [
     "stackwright-pro-api-otter.json",
-    "df79f4389a576c2885efa07b04f613c60eb8ebf4a8b1d4c7da5e4bb6ee4248dd"
+    "822b35d7a330ed8ac0b42a63b0f70a41885aa9b5ea23cc5b8b998b549da4c05c"
   ],
   [
     "stackwright-pro-auth-otter.json",
-    "07134125ab4f8c82ee015f27587e4d84bdeefca5ec211d1563bcb25b8aa61eb3"
+    "d6cd5732667018d99456be77d5955e454da7a0999a0330b5f03a483aa1b9b33f"
   ],
   [
     "stackwright-pro-dashboard-otter.json",
-    "160af221e04200f53709f8c3e249ca6dafb38a325b232fabd478b28f5492ab01"
+    "e3b82555fcffbd77285bd304828814e9f9f7257130797c9de3785de97527668c"
   ],
   [
     "stackwright-pro-data-otter.json",
-    "709c8e49328908549fe87de181a5991e09c918ef24bbfe6948f9888f0c758c25"
+    "bb66eaab31c6872536dca4d3ff145724a46356946dd0665cc4f0346714d3bacb"
   ],
   [
     "stackwright-pro-designer-otter.json",
-    "1364b2c235c07b0b798e9aab90a68604f60019a5508d41ba576977f173e20cd9"
+    "b54121c6a2ab5b1ad68c1262c58b2e04e6315feacd6bb8de8e78eb36f2fa6be6"
   ],
   [
     "stackwright-pro-domain-expert-otter.json",
@@ -5246,35 +5493,35 @@ var _checksums = /* @__PURE__ */ new Map([
   ],
   [
     "stackwright-pro-foreman-otter.json",
-    "438b03d2c35f64536055c68b3a9044fe3b5e4f2889acde4500dd801fad724be1"
+    "abb1cc5e40a8c5ff98057273f43a9e90e2791a15951090cd4d98407c0c3618e3"
+  ],
+  [
+    "stackwright-pro-form-wizard-otter.json",
+    "975ad68e8fb6fe5a10373be278946fa4d9d7ec2238a0b2bd9e4a412e5b1fdd6d"
   ],
   [
     "stackwright-pro-geo-otter.json",
-    "2ec83c26a08c413d9553ff8b8f0f0f643c1a8da043741b356e27106cad78f05f"
+    "ac440da786d8c5ab1feddbf861449c3be3a433a04370578e1b2d35bf6ae7a601"
   ],
   [
     "stackwright-pro-page-otter.json",
-    "0057ea97f7c2e33a8673140f59a0237eb627d82c676af3fae4faa31033598e03"
+    "b70bd6e5d2a40230f7c24ff4a6113585a1614e5b6a215ece2bd47ff053c30f58"
   ],
   [
     "stackwright-pro-polish-otter.json",
-    "bd87327b9a9a62fabaee8837492ce943feae8bfc15e5d43b45ba0e84619daec3"
+    "48ef3cf7f29ac6b5e8ab2004d4d41e2fb899e781689178d3905993241c84095a"
   ],
   [
     "stackwright-pro-scaffold-otter.json",
-    "91de5861f1406043d1d387388302fb1492211b81e2eea9777dec60e48f317f2a"
+    "e8662b63bbc9ce38851d94f9656bbebefdb7843d038862adb9fde2c23f9e77c2"
   ],
   [
     "stackwright-pro-theme-otter.json",
-    "fe10108e3ba67106751ea662f512bb5f4eb58f7abda26880ef4cf6b0f9feb944"
-  ],
-  [
-    "stackwright-pro-workflow-otter.json",
-    "5f6209fadc1355580e2455a16386f06bd7d5814f047b2dd5b33800abf6a48ff8"
+    "fb62e56642f7f94c50ce173f3e1ce978b3f20ab1567e87403b901d6dd991a7db"
   ],
   [
     "stackwright-services-otter.json",
-    "c013d7fc2475e62d0af54d57bc988182feee7766bac0edf841cbfad5c73e9261"
+    "0a5dac670482871c718099767b30bf23d8ec57e942bd40a00ce295926d82c6bd"
   ]
 ]);
 Object.freeze(_checksums);
@@ -5296,14 +5543,14 @@ function safeEqual(a, b) {
   return (0, import_crypto4.timingSafeEqual)(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
 }
 function verifyOtterFile(filePath) {
-  const filename = (0, import_path8.basename)(filePath);
+  const filename = (0, import_path9.basename)(filePath);
   const expected = CANONICAL_CHECKSUMS.get(filename);
   if (expected === void 0) {
     return { verified: false, filename, error: `Unknown otter file: not in canonical set` };
   }
   let stat;
   try {
-    stat = (0, import_fs8.lstatSync)(filePath);
+    stat = (0, import_fs9.lstatSync)(filePath);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { verified: false, filename, error: `Cannot stat file: ${msg}` };
@@ -5321,7 +5568,7 @@ function verifyOtterFile(filePath) {
   }
   let raw;
   try {
-    raw = (0, import_fs8.readFileSync)(filePath);
+    raw = (0, import_fs9.readFileSync)(filePath);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return { verified: false, filename, error: `Cannot read file: ${msg}` };
@@ -5371,7 +5618,7 @@ function verifyAllOtters(otterDir) {
   const unknown = [];
   let entries;
   try {
-    entries = (0, import_fs8.readdirSync)(otterDir);
+    entries = (0, import_fs9.readdirSync)(otterDir);
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
     return {
@@ -5382,9 +5629,9 @@ function verifyAllOtters(otterDir) {
   }
   const otterFiles = entries.filter((f) => f.endsWith("-otter.json"));
   for (const filename of otterFiles) {
-    const filePath = (0, import_path8.join)(otterDir, filename);
+    const filePath = (0, import_path9.join)(otterDir, filename);
     try {
-      if ((0, import_fs8.lstatSync)(filePath).isSymbolicLink()) {
+      if ((0, import_fs9.lstatSync)(filePath).isSymbolicLink()) {
         failed.push({ filename, error: "Skipped: symlink" });
         continue;
       }
@@ -5410,9 +5657,9 @@ var DEFAULT_SEARCH_PATHS = ["node_modules/@stackwright-pro/otters/src/", "packag
 function resolveOtterDir() {
   const cwd = process.cwd();
   for (const relative of DEFAULT_SEARCH_PATHS) {
-    const candidate = (0, import_path8.join)(cwd, relative);
+    const candidate = (0, import_path9.join)(cwd, relative);
     try {
-      (0, import_fs8.lstatSync)(candidate);
+      (0, import_fs9.lstatSync)(candidate);
       return candidate;
     } catch {
     }
@@ -5491,13 +5738,13 @@ function registerIntegrityTools(server2) {
 
 // src/tools/domain.ts
 var import_zod16 = require("zod");
-var import_fs9 = require("fs");
-var import_path9 = require("path");
+var import_fs10 = require("fs");
+var import_path10 = require("path");
 function handleListCollections(input) {
   const cwd = input._cwd ?? process.cwd();
   const sources = [
     {
-      path: (0, import_path9.join)(cwd, ".stackwright", "artifacts", "data-config.json"),
+      path: (0, import_path10.join)(cwd, ".stackwright", "artifacts", "data-config.json"),
       source: "data-config.json",
       parse: (raw) => {
         const parsed = JSON.parse(raw);
@@ -5508,15 +5755,15 @@ function handleListCollections(input) {
       }
     },
     {
-      path: (0, import_path9.join)(cwd, "stackwright.yml"),
+      path: (0, import_path10.join)(cwd, "stackwright.yml"),
       source: "stackwright.yml",
       parse: extractCollectionsFromYaml
     }
   ];
-  for (const { path: path3, source, parse } of sources) {
-    if (!(0, import_fs9.existsSync)(path3)) continue;
+  for (const { path: path4, source, parse } of sources) {
+    if (!(0, import_fs10.existsSync)(path4)) continue;
     try {
-      const collections = parse((0, import_fs9.readFileSync)(path3, "utf8"));
+      const collections = parse((0, import_fs10.readFileSync)(path4, "utf8"));
       return {
         text: JSON.stringify({ collections, source, collectionCount: collections.length }),
         isError: false
@@ -5667,8 +5914,8 @@ function handleValidateWorkflow(input) {
   if (input.workflow && Object.keys(input.workflow).length > 0) {
     raw = input.workflow;
   } else {
-    const artifactPath = (0, import_path9.join)(cwd, ".stackwright", "artifacts", "workflow-config.json");
-    if (!(0, import_fs9.existsSync)(artifactPath)) {
+    const artifactPath = (0, import_path10.join)(cwd, ".stackwright", "artifacts", "workflow-config.json");
+    if (!(0, import_fs10.existsSync)(artifactPath)) {
       return fail([
         {
           code: "NO_WORKFLOW",
@@ -5677,7 +5924,7 @@ function handleValidateWorkflow(input) {
       ]);
     }
     try {
-      raw = JSON.parse((0, import_fs9.readFileSync)(artifactPath, "utf8"));
+      raw = JSON.parse((0, import_fs10.readFileSync)(artifactPath, "utf8"));
     } catch (err) {
       return fail([{ code: "INVALID_JSON", message: `Failed to parse workflow artifact: ${err}` }]);
     }
@@ -5789,12 +6036,12 @@ function handleValidateWorkflow(input) {
   return { text: JSON.stringify({ valid: errors.length === 0, errors, warnings }), isError: false };
 }
 function validateTransitionTargets(step, stepId, stepIds, errors) {
-  const check = (target, path3) => {
+  const check = (target, path4) => {
     if (typeof target === "string" && !stepIds.has(target)) {
       errors.push({
         code: "ORPHANED_TRANSITION",
         message: `Step "${stepId}" transitions to "${target}" which does not exist`,
-        path: path3
+        path: path4
       });
     }
   };
@@ -5833,11 +6080,11 @@ function validateTransitionTargets(step, stepId, stepIds, errors) {
 }
 function collectServiceWarnings(step, stepId, warnings) {
   const isService = (val) => typeof val === "string" && val.startsWith("service:");
-  const warn = (path3) => {
+  const warn = (path4) => {
     warnings.push({
       code: "WARN_SERVICE_REFERENCE",
-      message: `service: reference at "${path3}" requires @stackwright-pro/services. Prism mock fallback will be used until services layer is configured.`,
-      path: path3
+      message: `service: reference at "${path4}" requires @stackwright-pro/services. Prism mock fallback will be used until services layer is configured.`,
+      path: path4
     });
   };
   const onSubmit = step.on_submit;
@@ -5915,7 +6162,7 @@ function buildTypeSchemaSummary() {
           "TransitionConditionSchema",
           "PersistenceSchema"
         ],
-        otter: "stackwright-pro-workflow-otter",
+        otter: "stackwright-pro-form-wizard-otter",
         artifactKey: "workflowConfig"
       },
       auth: {
@@ -5985,8 +6232,8 @@ function registerTypeSchemasTool(server2) {
 }
 
 // src/tools/scaffold-cleanup.ts
-var import_fs10 = require("fs");
-var import_path10 = require("path");
+var import_fs11 = require("fs");
+var import_path11 = require("path");
 var SCAFFOLD_FILES_TO_DELETE = [
   "content/posts/getting-started.yaml",
   "content/posts/hello-world.yaml"
@@ -6011,12 +6258,12 @@ var FALLBACK_COLORS = {
   mutedForeground: "#737373"
 };
 function readThemeColors(cwd) {
-  const tokenPath = (0, import_path10.join)(cwd, ".stackwright", "artifacts", "theme-tokens.json");
-  if (!(0, import_fs10.existsSync)(tokenPath)) return { ...FALLBACK_COLORS };
-  const stat = (0, import_fs10.lstatSync)(tokenPath);
+  const tokenPath = (0, import_path11.join)(cwd, ".stackwright", "artifacts", "theme-tokens.json");
+  if (!(0, import_fs11.existsSync)(tokenPath)) return { ...FALLBACK_COLORS };
+  const stat = (0, import_fs11.lstatSync)(tokenPath);
   if (stat.isSymbolicLink()) return { ...FALLBACK_COLORS };
   try {
-    const raw = JSON.parse((0, import_fs10.readFileSync)(tokenPath, "utf-8"));
+    const raw = JSON.parse((0, import_fs11.readFileSync)(tokenPath, "utf-8"));
     const css = raw?.cssVariables ?? {};
     const toHsl = (hslValue) => {
       if (!hslValue || typeof hslValue !== "string") return null;
@@ -6076,15 +6323,15 @@ function generateNotFoundPage(colors) {
 `;
 }
 function isSafePath(fullPath) {
-  if (!(0, import_fs10.existsSync)(fullPath)) return true;
-  const stat = (0, import_fs10.lstatSync)(fullPath);
+  if (!(0, import_fs11.existsSync)(fullPath)) return true;
+  const stat = (0, import_fs11.lstatSync)(fullPath);
   return !stat.isSymbolicLink();
 }
 function isDirEmpty(dirPath) {
-  if (!(0, import_fs10.existsSync)(dirPath)) return false;
-  const stat = (0, import_fs10.lstatSync)(dirPath);
+  if (!(0, import_fs11.existsSync)(dirPath)) return false;
+  const stat = (0, import_fs11.lstatSync)(dirPath);
   if (!stat.isDirectory()) return false;
-  return (0, import_fs10.readdirSync)(dirPath).length === 0;
+  return (0, import_fs11.readdirSync)(dirPath).length === 0;
 }
 function handleCleanupScaffold(_cwd) {
   const cwd = _cwd ?? process.cwd();
@@ -6097,8 +6344,8 @@ function handleCleanupScaffold(_cwd) {
     cleanupWarnings: []
   };
   for (const relPath of SCAFFOLD_FILES_TO_DELETE) {
-    const fullPath = (0, import_path10.join)(cwd, relPath);
-    if (!(0, import_fs10.existsSync)(fullPath)) {
+    const fullPath = (0, import_path11.join)(cwd, relPath);
+    if (!(0, import_fs11.existsSync)(fullPath)) {
       result.skipped.push(relPath);
       continue;
     }
@@ -6107,7 +6354,7 @@ function handleCleanupScaffold(_cwd) {
       continue;
     }
     try {
-      (0, import_fs10.unlinkSync)(fullPath);
+      (0, import_fs11.unlinkSync)(fullPath);
       result.deleted.push(relPath);
     } catch (err) {
       result.errors.push(`Failed to delete ${relPath}: ${String(err)}`);
@@ -6115,19 +6362,19 @@ function handleCleanupScaffold(_cwd) {
   }
   {
     const relPath = "pages/getting-started/content.yml";
-    const fullPath = (0, import_path10.join)(cwd, relPath);
-    if (!(0, import_fs10.existsSync)(fullPath)) {
+    const fullPath = (0, import_path11.join)(cwd, relPath);
+    if (!(0, import_fs11.existsSync)(fullPath)) {
       result.skipped.push(relPath);
     } else if (!isSafePath(fullPath)) {
       result.errors.push(`Refusing to delete symlink: ${relPath}`);
     } else {
-      const content = (0, import_fs10.readFileSync)(fullPath, "utf-8");
+      const content = (0, import_fs11.readFileSync)(fullPath, "utf-8");
       const isScaffoldDefault = GETTING_STARTED_SCAFFOLD_FINGERPRINTS.some(
         (marker) => content.includes(marker)
       );
       if (isScaffoldDefault) {
         try {
-          (0, import_fs10.unlinkSync)(fullPath);
+          (0, import_fs11.unlinkSync)(fullPath);
           result.deleted.push(relPath);
         } catch (err) {
           result.errors.push(`Failed to delete ${relPath}: ${String(err)}`);
@@ -6141,21 +6388,21 @@ function handleCleanupScaffold(_cwd) {
   }
   {
     const relPath = `content/posts/${POSTS_COLLECTION_FILE}`;
-    const fullPath = (0, import_path10.join)(cwd, relPath);
-    const postsDir = (0, import_path10.join)(cwd, "content/posts");
-    if (!(0, import_fs10.existsSync)(fullPath)) {
+    const fullPath = (0, import_path11.join)(cwd, relPath);
+    const postsDir = (0, import_path11.join)(cwd, "content/posts");
+    if (!(0, import_fs11.existsSync)(fullPath)) {
       result.skipped.push(relPath);
     } else if (!isSafePath(fullPath)) {
       result.errors.push(`Refusing to delete symlink: ${relPath}`);
-    } else if (!(0, import_fs10.existsSync)(postsDir)) {
+    } else if (!(0, import_fs11.existsSync)(postsDir)) {
       result.skipped.push(relPath);
     } else {
-      const userPostFiles = (0, import_fs10.readdirSync)(postsDir).filter(
+      const userPostFiles = (0, import_fs11.readdirSync)(postsDir).filter(
         (f) => f !== POSTS_COLLECTION_FILE && POST_FILE_EXTENSIONS.some((ext) => f.endsWith(ext))
       );
       if (userPostFiles.length === 0) {
         try {
-          (0, import_fs10.unlinkSync)(fullPath);
+          (0, import_fs11.unlinkSync)(fullPath);
           result.deleted.push(relPath);
         } catch (err) {
           result.errors.push(`Failed to delete ${relPath}: ${String(err)}`);
@@ -6168,15 +6415,15 @@ function handleCleanupScaffold(_cwd) {
     }
   }
   for (const relDir of SCAFFOLD_DIRS_TO_PRUNE) {
-    const fullDir = (0, import_path10.join)(cwd, relDir);
-    if (!(0, import_fs10.existsSync)(fullDir)) continue;
+    const fullDir = (0, import_path11.join)(cwd, relDir);
+    if (!(0, import_fs11.existsSync)(fullDir)) continue;
     if (!isSafePath(fullDir)) {
       result.errors.push(`Refusing to prune symlink directory: ${relDir}`);
       continue;
     }
     if (isDirEmpty(fullDir)) {
       try {
-        (0, import_fs10.rmdirSync)(fullDir);
+        (0, import_fs11.rmdirSync)(fullDir);
         result.prunedDirs.push(relDir);
       } catch (err) {
         result.errors.push(`Failed to prune directory ${relDir}: ${String(err)}`);
@@ -6184,8 +6431,8 @@ function handleCleanupScaffold(_cwd) {
     }
   }
   {
-    const fullPath = (0, import_path10.join)(cwd, NOT_FOUND_PATH);
-    if (!(0, import_fs10.existsSync)(fullPath)) {
+    const fullPath = (0, import_path11.join)(cwd, NOT_FOUND_PATH);
+    if (!(0, import_fs11.existsSync)(fullPath)) {
       result.skipped.push(NOT_FOUND_PATH);
     } else if (!isSafePath(fullPath)) {
       result.errors.push(`Refusing to rewrite symlink: ${NOT_FOUND_PATH}`);
@@ -6193,9 +6440,9 @@ function handleCleanupScaffold(_cwd) {
       try {
         const colors = readThemeColors(cwd);
         const content = generateNotFoundPage(colors);
-        const dir = (0, import_path10.dirname)(fullPath);
-        (0, import_fs10.mkdirSync)(dir, { recursive: true });
-        (0, import_fs10.writeFileSync)(fullPath, content, "utf-8");
+        const dir = (0, import_path11.dirname)(fullPath);
+        (0, import_fs11.mkdirSync)(dir, { recursive: true });
+        (0, import_fs11.writeFileSync)(fullPath, content, "utf-8");
         result.rewritten.push(NOT_FOUND_PATH);
       } catch (err) {
         result.errors.push(`Failed to rewrite ${NOT_FOUND_PATH}: ${String(err)}`);
@@ -6462,11 +6709,256 @@ function registerContrastTools(server2) {
   );
 }
 
+// src/tools/compile.ts
+var import_zod19 = require("zod");
+var import_fs12 = __toESM(require("fs"));
+var import_path12 = __toESM(require("path"));
+var import_server = require("@stackwright-pro/pulse/server");
+var import_server2 = require("@stackwright-pro/auth-nextjs/server");
+var import_server3 = require("@stackwright-pro/openapi/server");
+function buildContext(projectRoot) {
+  return {
+    projectRoot,
+    contentOutDir: import_path12.default.join(projectRoot, "public", "stackwright-content"),
+    imagesDir: import_path12.default.join(projectRoot, "public", "images"),
+    siteConfig: loadSiteConfig(projectRoot)
+  };
+}
+function loadSiteConfig(projectRoot) {
+  try {
+    const sitePath = import_path12.default.join(projectRoot, "public", "stackwright-content", "_site.json");
+    return JSON.parse(import_fs12.default.readFileSync(sitePath, "utf8"));
+  } catch {
+    return {};
+  }
+}
+function formatDuration(startMs) {
+  const ms = Date.now() - startMs;
+  return ms < 1e3 ? `${ms}ms` : `${(ms / 1e3).toFixed(2)}s`;
+}
+async function tryOssCompile(fn, ctx, extra) {
+  try {
+    const bsPath = import_path12.default.join(ctx.projectRoot, "node_modules", "@stackwright", "build-scripts");
+    if (!import_fs12.default.existsSync(bsPath)) {
+      return {
+        ok: false,
+        error: `@stackwright/build-scripts not found at ${bsPath}. Is it installed in your project?`
+      };
+    }
+    const bs = await import(bsPath);
+    if (typeof bs[fn] !== "function") {
+      return { ok: false, error: `${fn} not exported from @stackwright/build-scripts` };
+    }
+    await bs[fn](ctx, ...extra ? [extra] : []);
+    return { ok: true };
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+function registerCompileTools(server2) {
+  const projectRootArg = import_zod19.z.string().optional().describe("Absolute path to project root (defaults to cwd)");
+  server2.tool(
+    "stackwright_pro_compile_collections",
+    "Compile stackwright.collections.yml \u2192 public/stackwright-content/_collections.json. Reads and validates the live-collections sidecar config file and emits the JSON sink consumed at runtime by PulseCollectionProvider.",
+    { projectRoot: projectRootArg },
+    async ({ projectRoot }) => {
+      const start = Date.now();
+      const root = projectRoot ?? process.cwd();
+      try {
+        await (0, import_server.compileCollections)(buildContext(root));
+        return {
+          content: [
+            {
+              type: "text",
+              text: ` _collections.json written (${formatDuration(start)})`
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: ` compile_collections failed: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server2.tool(
+    "stackwright_pro_compile_auth",
+    "Compile stackwright.auth.yml \u2192 public/stackwright-content/_auth.json. Reads and validates the auth sidecar config file and emits the JSON sink consumed at app startup to configure auth middleware.",
+    { projectRoot: projectRootArg },
+    async ({ projectRoot }) => {
+      const start = Date.now();
+      const root = projectRoot ?? process.cwd();
+      try {
+        await (0, import_server2.compileAuth)(buildContext(root));
+        return {
+          content: [
+            {
+              type: "text",
+              text: ` _auth.json written (${formatDuration(start)})`
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: ` compile_auth failed: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server2.tool(
+    "stackwright_pro_compile_integrations",
+    "Compile stackwright.integrations.yml \u2192 public/stackwright-content/_integrations.json. If no yml file exists, falls back to extracting integration metadata from _site.json (collections data is excluded \u2014 it lives in _collections.json).",
+    { projectRoot: projectRootArg },
+    async ({ projectRoot }) => {
+      const start = Date.now();
+      const root = projectRoot ?? process.cwd();
+      try {
+        await (0, import_server3.compileIntegrations)(buildContext(root));
+        return {
+          content: [
+            {
+              type: "text",
+              text: ` _integrations.json written (${formatDuration(start)})`
+            }
+          ]
+        };
+      } catch (err) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: ` compile_integrations failed: ${err instanceof Error ? err.message : String(err)}`
+            }
+          ]
+        };
+      }
+    }
+  );
+  server2.tool(
+    "stackwright_pro_compile_all",
+    "Run all Pro compile sinks (collections + auth + integrations) in sequence. Equivalent to running compile_collections, compile_auth, and compile_integrations individually. Use this for a full Pro prebuild pass.",
+    { projectRoot: projectRootArg },
+    async ({ projectRoot }) => {
+      const start = Date.now();
+      const root = projectRoot ?? process.cwd();
+      const ctx = buildContext(root);
+      const results = [];
+      const errors = [];
+      for (const [label, fn] of [
+        ["collections", () => (0, import_server.compileCollections)(ctx)],
+        ["auth", () => (0, import_server2.compileAuth)(ctx)],
+        ["integrations", () => (0, import_server3.compileIntegrations)(ctx)]
+      ]) {
+        try {
+          await fn();
+          results.push(`   _${label}.json`);
+        } catch (err) {
+          errors.push(`   ${label}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+      }
+      const summary = errors.length > 0 ? ` compile_all finished with errors (${formatDuration(start)}):
+${results.join("\n")}
+Errors:
+${errors.join("\n")}` : ` compile_all complete (${formatDuration(start)}):
+${results.join("\n")}`;
+      return { content: [{ type: "text", text: summary }] };
+    }
+  );
+  server2.tool(
+    "stackwright_pro_compile_theme",
+    "Compile stackwright.yml theme config \u2192 _theme.json. Delegates to compileTheme from @stackwright/build-scripts installed in the project.",
+    { projectRoot: projectRootArg },
+    async ({ projectRoot }) => {
+      const start = Date.now();
+      const root = projectRoot ?? process.cwd();
+      const { ok, error } = await tryOssCompile("compileTheme", buildContext(root));
+      return {
+        content: [
+          {
+            type: "text",
+            text: ok ? ` _theme.json written (${formatDuration(start)})` : ` compile_theme failed: ${error}`
+          }
+        ]
+      };
+    }
+  );
+  server2.tool(
+    "stackwright_pro_compile_site",
+    "Compile stackwright.yml \u2192 _site.json. Delegates to compileSite from @stackwright/build-scripts installed in the project.",
+    { projectRoot: projectRootArg },
+    async ({ projectRoot }) => {
+      const start = Date.now();
+      const root = projectRoot ?? process.cwd();
+      const { ok, error } = await tryOssCompile("compileSite", buildContext(root));
+      return {
+        content: [
+          {
+            type: "text",
+            text: ok ? ` _site.json written (${formatDuration(start)})` : ` compile_site failed: ${error}`
+          }
+        ]
+      };
+    }
+  );
+  server2.tool(
+    "stackwright_pro_compile_pages",
+    "Compile all pages content.yml files \u2192 page JSON files. Delegates to compilePages from @stackwright/build-scripts installed in the project.",
+    { projectRoot: projectRootArg },
+    async ({ projectRoot }) => {
+      const start = Date.now();
+      const root = projectRoot ?? process.cwd();
+      const { ok, error } = await tryOssCompile("compilePages", buildContext(root));
+      return {
+        content: [
+          {
+            type: "text",
+            text: ok ? ` pages compiled (${formatDuration(start)})` : ` compile_pages failed: ${error}`
+          }
+        ]
+      };
+    }
+  );
+  server2.tool(
+    "stackwright_pro_compile_page",
+    "Compile a single page by slug. Delegates to compilePage from @stackwright/build-scripts installed in the project.",
+    {
+      slug: import_zod19.z.string().describe('Page slug (relative path under pages/, e.g. "dashboard")'),
+      projectRoot: projectRootArg
+    },
+    async ({ slug, projectRoot }) => {
+      const start = Date.now();
+      const root = projectRoot ?? process.cwd();
+      const { ok, error } = await tryOssCompile("compilePage", buildContext(root), { slug });
+      return {
+        content: [
+          {
+            type: "text",
+            text: ok ? ` page "${slug}" compiled (${formatDuration(start)})` : ` compile_page failed: ${error}`
+          }
+        ]
+      };
+    }
+  );
+}
+
 // package.json
 var package_default = {
   dependencies: {
     "@modelcontextprotocol/sdk": "^1.10.0",
+    "@stackwright-pro/auth-nextjs": "workspace:*",
     "@stackwright-pro/cli-data-explorer": "workspace:*",
+    "@stackwright-pro/openapi": "workspace:*",
+    "@stackwright-pro/pulse": "workspace:*",
     "@stackwright-pro/types": "workspace:*",
     "@types/js-yaml": "^4.0.9",
     "js-yaml": "^4.2.0",
@@ -6487,7 +6979,7 @@ var package_default = {
     "test:coverage": "vitest run --coverage"
   },
   name: "@stackwright-pro/mcp",
-  version: "0.2.0-alpha.90",
+  version: "0.2.0-alpha.95",
   description: "MCP tools for Stackwright Pro - Data Explorer, Security, ISR, and Dashboard generation",
   license: "SEE LICENSE IN LICENSE",
   main: "./dist/server.js",
@@ -6545,7 +7037,22 @@ registerValidateYamlFragmentTool(server);
 registerGetSchemaTool(server);
 registerScaffoldCleanupTools(server);
 registerContrastTools(server);
+registerCompileTools(server);
 async function main() {
+  const pipelineGraph = loadPipelineGraph();
+  const phasePosition = new Map(PHASE_ORDER.map((p, i) => [p, i]));
+  for (const [phase, deps] of Object.entries(pipelineGraph.dependencies)) {
+    const phaseIdx = phasePosition.get(phase);
+    if (phaseIdx === void 0) continue;
+    for (const dep of deps) {
+      const depIdx = phasePosition.get(dep);
+      if (depIdx !== void 0 && depIdx >= phaseIdx) {
+        throw new Error(
+          `PHASE_ORDER sanity check failed: "${dep}" (position ${depIdx}) must precede "${phase}" (position ${phaseIdx}) but it doesn't. Update PHASE_ORDER in pipeline.ts to reflect the new dependency structure.`
+        );
+      }
+    }
+  }
   const transport = new import_stdio.StdioServerTransport();
   try {
     const servicesRegisterPkg = "@stackwright-services/mcp/register";