@stackwright-pro/mcp 0.2.0-alpha.80 → 0.2.0-alpha.82

package/dist/server.mjs

@@ -1589,24 +1589,28 @@ import { join as join2 } from "path";
 var OTTER_NAME_TO_PHASE = [
   ["designer", "designer"],
   ["theme", "theme"],
+  ["scaffold", "scaffold"],
   ["api", "api"],
   ["auth", "auth"],
   ["dashboard", "dashboard"],
   ["data", "data"],
   ["page", "pages"],
   ["workflow", "workflow"],
+  ["services", "services"],
   ["polish", "polish"],
   ["geo", "geo"]
 ];
 var PHASE_TO_OTTER = {
   designer: "stackwright-pro-designer-otter",
   theme: "stackwright-pro-theme-otter",
+  scaffold: "stackwright-pro-scaffold-otter",
   api: "stackwright-pro-api-otter",
   auth: "stackwright-pro-auth-otter",
   pages: "stackwright-pro-page-otter",
   dashboard: "stackwright-pro-dashboard-otter",
   data: "stackwright-pro-data-otter",
   workflow: "stackwright-pro-workflow-otter",
+  services: "stackwright-services-otter",
   polish: "stackwright-pro-polish-otter",
   geo: "stackwright-pro-geo-otter"
 };
@@ -1991,7 +1995,7 @@ function registerOrchestrationTools(server2) {
 }
 
 // src/tools/pipeline.ts
-import { z as z11 } from "zod";
+import { z as z13 } from "zod";
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync4, existsSync as existsSync5, mkdirSync as mkdirSync4, lstatSync as lstatSync5 } from "fs";
 import { join as join4 } from "path";
 import { createHash as createHash3 } from "crypto";
@@ -2335,7 +2339,355 @@ function registerArtifactSigningTools(server2) {
 }
 
 // src/tools/pipeline.ts
-import { WorkflowFileSchema, authConfigSchema } from "@stackwright-pro/types";
+import { WorkflowFileSchema, authConfigSchema as authConfigSchema3 } from "@stackwright-pro/types";
+
+// src/tools/get-schema.ts
+import { z as z12 } from "zod";
+import {
+  WorkflowStepSchema as WorkflowStepSchema2,
+  WorkflowDefinitionSchema as WorkflowDefinitionSchema2,
+  WorkflowFieldSchema as WorkflowFieldSchema2,
+  WorkflowActionSchema as WorkflowActionSchema2,
+  authConfigSchema as authConfigSchema2
+} from "@stackwright-pro/types";
+
+// src/tools/validate-yaml-fragment.ts
+import { z as z11 } from "zod";
+import { load as yamlLoad } from "js-yaml";
+import {
+  WorkflowStepSchema,
+  WorkflowDefinitionSchema,
+  WorkflowFieldSchema,
+  WorkflowActionSchema,
+  authConfigSchema
+} from "@stackwright-pro/types";
+var SUPPORTED_SCHEMA_NAMES = [
+  "workflow_step",
+  "workflow_definition",
+  "workflow_field",
+  "workflow_action",
+  "navigation_item",
+  "auth_config"
+];
+var NavigationLinkSchema = z11.lazy(
+  () => z11.object({
+    label: z11.string().min(1),
+    href: z11.string().min(1),
+    children: z11.array(NavigationLinkSchema).optional()
+  })
+);
+var NavigationSectionSchema = z11.object({
+  section: z11.string().min(1),
+  items: z11.array(NavigationLinkSchema)
+});
+var NavigationItemSchema = z11.union([
+  NavigationLinkSchema,
+  NavigationSectionSchema
+]);
+var FIELD_SYNONYMS = {
+  workflow_step: {
+    title: "label",
+    name: "label (at step level, use label: not name:)",
+    description: "message (use message: for step-level descriptive text)",
+    style: 'theme.variant \u2014 use theme: { variant: "primary" } not style: "primary"',
+    transitions: 'on_submit.transition \u2014 use on_submit: { transition: "next_step" } not transitions: [{then:...}]'
+  },
+  workflow_definition: {
+    title: "label",
+    name: "label (workflow-level label, not name:)",
+    description: "description is valid here \u2014 but message: is not (that is a step field)",
+    type: "id (workflows are identified by id:, not type:)"
+  },
+  workflow_field: {
+    id: "name (field-level identifier is name:, NOT id:)",
+    title: "label (field display text is label:, NOT title:)",
+    description: "placeholder or label (no description field on WorkflowField)"
+  },
+  workflow_action: {
+    style: 'theme.variant \u2014 use theme: { variant: "primary" } not style: "primary"',
+    then: "transition (action-level next-step is transition:, NOT then:)",
+    on_click: 'action: "service:..." (extract the service reference from on_click.action)',
+    title: "label (action display text is label:, NOT title:)",
+    name: "label (action display text is label:, NOT name:)"
+  },
+  navigation_item: {
+    children: "items (NavigationSection uses items: not children: \u2014 also use section: instead of label: for section headers)",
+    label: 'section (if this is a nav group/section, use section: "Title" and items: [...], not label:)',
+    title: "section (NavigationSection header field is section:, NOT title:)"
+  },
+  auth_config: {
+    method: 'type \u2014 auth config discriminates on type: "oidc" | "pki", NOT method:',
+    provider_type: 'type \u2014 use type: "oidc" or type: "pki"',
+    strategy: "type \u2014 top-level discriminator is type:, not strategy:"
+  }
+};
+function getSchema(name) {
+  switch (name) {
+    case "workflow_step":
+      return WorkflowStepSchema;
+    case "workflow_definition":
+      return WorkflowDefinitionSchema;
+    case "workflow_field":
+      return WorkflowFieldSchema;
+    case "workflow_action":
+      return WorkflowActionSchema;
+    case "navigation_item":
+      return NavigationItemSchema;
+    case "auth_config":
+      return authConfigSchema;
+  }
+}
+function enrichErrors(issues, synonyms) {
+  return issues.map((issue) => {
+    const pathStr = issue.path.join(".");
+    const lastSegment = issue.path[issue.path.length - 1];
+    const fieldName = typeof lastSegment === "string" ? lastSegment : void 0;
+    const didYouMean = fieldName ? synonyms[fieldName] : void 0;
+    return {
+      path: pathStr || "(root)",
+      message: issue.message,
+      ...didYouMean ? { didYouMean } : {}
+    };
+  });
+}
+function handleValidateYamlFragment(input) {
+  const { schemaName, yaml } = input;
+  if (!SUPPORTED_SCHEMA_NAMES.includes(schemaName)) {
+    return {
+      valid: false,
+      parseError: `Unknown schemaName: "${schemaName}". Supported: ${SUPPORTED_SCHEMA_NAMES.join(", ")}`
+    };
+  }
+  const name = schemaName;
+  let parsed;
+  try {
+    parsed = yamlLoad(yaml);
+  } catch (err) {
+    return {
+      valid: false,
+      parseError: `YAML parse error: ${err instanceof Error ? err.message : String(err)}`
+    };
+  }
+  const schema = getSchema(name);
+  const result = schema.safeParse(parsed);
+  if (result.success) {
+    return { valid: true };
+  }
+  const synonyms = FIELD_SYNONYMS[name];
+  const errors = enrichErrors(result.error.issues, synonyms);
+  return { valid: false, errors };
+}
+function registerValidateYamlFragmentTool(server2) {
+  server2.tool(
+    "stackwright_pro_validate_yaml_fragment",
+    'Validates a YAML snippet against a canonical Zod schema before writing to disk. Returns actionable errors with "did you mean?" suggestions for common field-name drift (title vs label, id vs name, style vs theme.variant, etc.). Call this before stackwright_pro_safe_write to catch schema violations in-session.',
+    {
+      schemaName: z11.enum(SUPPORTED_SCHEMA_NAMES).describe(
+        "Schema to validate against. One of: workflow_step, workflow_definition, workflow_field, workflow_action, navigation_item, auth_config"
+      ),
+      yaml: z11.string().describe("YAML string to validate (can also be JSON \u2014 js-yaml parses both)")
+    },
+    async ({ schemaName, yaml }) => {
+      const result = handleValidateYamlFragment({ schemaName, yaml });
+      return {
+        content: [{ type: "text", text: JSON.stringify(result, null, 2) }]
+      };
+    }
+  );
+}
+
+// src/tools/get-schema.ts
+var NavigationLinkSchema2 = z12.lazy(
+  () => z12.object({
+    label: z12.string().min(1),
+    href: z12.string().min(1),
+    children: z12.array(NavigationLinkSchema2).optional()
+  })
+);
+var NavigationSectionSchema2 = z12.object({
+  section: z12.string().min(1),
+  items: z12.array(NavigationLinkSchema2)
+});
+var NavigationItemSchema2 = z12.union([
+  NavigationLinkSchema2,
+  NavigationSectionSchema2
+]);
+function getZodSchema(name) {
+  switch (name) {
+    case "workflow_step":
+      return WorkflowStepSchema2;
+    case "workflow_definition":
+      return WorkflowDefinitionSchema2;
+    case "workflow_field":
+      return WorkflowFieldSchema2;
+    case "workflow_action":
+      return WorkflowActionSchema2;
+    case "navigation_item":
+      return NavigationItemSchema2;
+    case "auth_config":
+      return authConfigSchema2;
+  }
+}
+function formatType(node, depth = 0) {
+  if (node.const !== void 0) return JSON.stringify(node.const);
+  if (node.enum) return node.enum.map((v) => JSON.stringify(v)).join(" | ");
+  if (node.oneOf || node.anyOf) {
+    const branches = node.oneOf ?? node.anyOf ?? [];
+    return branches.map((b) => {
+      const disc = b.properties ? Object.entries(b.properties).filter(([, v]) => v.const !== void 0).map(([k, v]) => `${k}: ${JSON.stringify(v.const)}`).join(", ") : "";
+      return disc ? `{ ${disc}, ... }` : "{ ... }";
+    }).join(" | ");
+  }
+  if (node.type === "array" && node.items) {
+    return `${formatType(node.items, depth)}[]`;
+  }
+  if (node.type === "object" && node.properties && depth < 2) {
+    const inner = Object.entries(node.properties).map(([k, v]) => `${k}: ${formatType(v, depth + 1)}`).join(", ");
+    return `{ ${inner} }`;
+  }
+  const base = Array.isArray(node.type) ? node.type.join(" | ") : node.type ?? "unknown";
+  const constraints = [];
+  if (node.maxLength !== void 0) constraints.push(`max ${node.maxLength} chars`);
+  if (node.minLength !== void 0) constraints.push(`min ${node.minLength} chars`);
+  if (node.pattern) constraints.push(`pattern: ${node.pattern}`);
+  if (node.minimum !== void 0) constraints.push(`min ${node.minimum}`);
+  if (node.maximum !== void 0) constraints.push(`max ${node.maximum}`);
+  return constraints.length > 0 ? `${base} (${constraints.join(", ")})` : base;
+}
+function formatObjectSchema(node, schemaName, synonyms) {
+  const lines = [];
+  const displayName = schemaName.split("_").map((w) => w[0].toUpperCase() + w.slice(1)).join("");
+  lines.push(`${displayName}:`);
+  if (node.oneOf || node.anyOf) {
+    const branches = node.oneOf ?? node.anyOf ?? [];
+    lines.push("  Discriminated union \u2014 choose one variant:");
+    for (const branch of branches) {
+      const req = new Set(branch.required ?? []);
+      const disc = Object.entries(branch.properties ?? {}).filter(([, v]) => v.const !== void 0).map(([k, v]) => `${k}: ${JSON.stringify(v.const)}`).join(", ");
+      lines.push(`  VARIANT (${disc}):`);
+      for (const [field, fieldNode] of Object.entries(branch.properties ?? {})) {
+        if (fieldNode.const !== void 0) continue;
+        const isRequired = req.has(field);
+        const hint = synonyms[field] ? `  -- WARNING: use ${field}: not ${synonyms[field]}` : "";
+        lines.push(
+          `    ${isRequired ? "REQUIRED" : "optional"}: ${field}: ${formatType(fieldNode)}${hint}`
+        );
+      }
+    }
+    return lines.join("\n");
+  }
+  const required = new Set(node.required ?? []);
+  const properties = node.properties ?? {};
+  const requiredFields = Object.entries(properties).filter(([k]) => required.has(k));
+  const optionalFields = Object.entries(properties).filter(([k]) => !required.has(k));
+  if (requiredFields.length > 0) {
+    lines.push("  REQUIRED:");
+    for (const [field, fieldNode] of requiredFields) {
+      const typeStr = formatType(fieldNode);
+      const warn = synonyms[field] ? `  -- CAUTION: this schema uses ${field}` : "";
+      lines.push(`    ${field}: ${typeStr}${warn}`);
+    }
+  }
+  if (optionalFields.length > 0) {
+    lines.push("  OPTIONAL:");
+    for (const [field, fieldNode] of optionalFields) {
+      const typeStr = formatType(fieldNode);
+      lines.push(`    ${field}: ${typeStr}`);
+    }
+  }
+  return lines.join("\n");
+}
+function handleGetSchema(input) {
+  const { schemaName } = input;
+  if (!SUPPORTED_SCHEMA_NAMES.includes(schemaName)) {
+    return {
+      error: `Unknown schemaName: "${schemaName}". Supported: ${SUPPORTED_SCHEMA_NAMES.join(", ")}`
+    };
+  }
+  const name = schemaName;
+  const schema = getZodSchema(name);
+  const synonyms = FIELD_SYNONYMS[name];
+  let jsonSchema;
+  try {
+    const raw = z12.toJSONSchema(schema, { unrepresentable: "any" });
+    jsonSchema = raw;
+  } catch {
+    jsonSchema = { type: "object", description: "Schema introspection unavailable for this type" };
+  }
+  const summary = formatObjectSchema(jsonSchema, name, synonyms);
+  const synonymWarnings = Object.entries(synonyms).map(
+    ([wrong, correct]) => `  WARNING: use "${correct}" \u2014 NOT "${wrong}"`
+  );
+  const fullText = [
+    summary,
+    "",
+    "FIELD NAME WARNINGS (common drift patterns):",
+    ...synonymWarnings
+  ].join("\n");
+  const tokenEstimate = Math.ceil(fullText.length / 4);
+  return {
+    schemaName: name,
+    summary,
+    synonymWarnings,
+    tokenEstimate
+  };
+}
+var PHASE_SCHEMA_NAMES = {
+  workflow: ["workflow_step", "workflow_definition", "workflow_field", "workflow_action"],
+  pages: ["navigation_item"],
+  dashboard: ["navigation_item"],
+  polish: ["navigation_item"],
+  auth: ["auth_config"]
+};
+function buildSchemaReferenceBlock(phase) {
+  const schemaNames = PHASE_SCHEMA_NAMES[phase];
+  if (!schemaNames || schemaNames.length === 0) return null;
+  const sections = [
+    "CANONICAL_SCHEMA_REFERENCE (authoritative \u2014 use exact field names below):",
+    ""
+  ];
+  for (const name of schemaNames) {
+    const result = handleGetSchema({ schemaName: name });
+    if ("error" in result) continue;
+    sections.push(result.summary);
+    if (result.synonymWarnings.length > 0) {
+      sections.push("  Common mistakes to avoid:");
+      sections.push(...result.synonymWarnings);
+    }
+    sections.push("");
+  }
+  return sections.join("\n");
+}
+function registerGetSchemaTool(server2) {
+  server2.tool(
+    "stackwright_pro_get_schema",
+    'Returns a compact, LLM-friendly summary of a canonical schema derived programmatically from Zod. Includes required/optional fields, types, constraints, and "did you mean?" warnings for common field-name drift. Use before authoring YAML to confirm exact field names.',
+    {
+      schemaName: z12.enum(SUPPORTED_SCHEMA_NAMES).describe(
+        "Schema to summarize. One of: workflow_step, workflow_definition, workflow_field, workflow_action, navigation_item, auth_config"
+      )
+    },
+    async ({ schemaName }) => {
+      const result = handleGetSchema({ schemaName });
+      if ("error" in result) {
+        return {
+          content: [{ type: "text", text: JSON.stringify({ error: result.error }) }],
+          isError: true
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2)
+          }
+        ]
+      };
+    }
+  );
+}
+
+// src/tools/pipeline.ts
 var PHASE_ORDER = [
   "designer",
   "theme",
@@ -2903,6 +3255,10 @@ ${JSON.stringify(content, null, 2)}`
     const artifactSchema = PHASE_ARTIFACT_SCHEMA[phase];
     parts.push("", "REQUIRED_ARTIFACT_SCHEMA:");
     parts.push(artifactSchema);
+    const schemaRef = buildSchemaReferenceBlock(phase);
+    if (schemaRef) {
+      parts.push("", schemaRef);
+    }
     parts.push("", "Execute using these answers and the upstream artifacts provided.");
     const prompt = parts.join("\n");
     const dependenciesSatisfied = missingDependencies.length === 0;
@@ -2937,6 +3293,7 @@ var OFF_SCRIPT_PATTERNS = [
 var PHASE_REQUIRED_KEYS = {
   designer: ["designLanguage", "themeTokenSeeds"],
   theme: ["tokens"],
+  scaffold: ["version", "generatedBy", "appRouterFiles"],
   api: ["entities", "version", "generatedBy"],
   auth: ["version", "generatedBy"],
   data: ["version", "generatedBy", "strategy", "collections"],
@@ -3287,7 +3644,7 @@ function handleValidateArtifact(input) {
     auth: (artifact2) => {
       const authConfig = artifact2["authConfig"];
       if (!authConfig) return { success: true };
-      const result = authConfigSchema.safeParse(authConfig);
+      const result = authConfigSchema3.safeParse(authConfig);
       if (!result.success) {
         const issues = result.error.issues.slice(0, 3).map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
         return { success: false, error: { message: issues } };
@@ -3359,21 +3716,21 @@ function registerPipelineTools(server2) {
     "stackwright_pro_set_pipeline_state",
     `Atomic read\u2192modify\u2192write pipeline state. ${DESC}`,
     {
-      phase: z11.string().optional().describe('Phase to update, e.g. "designer"'),
-      field: z11.enum(["questionsCollected", "answered", "executed", "artifactWritten"]).optional().describe("Boolean field to set"),
-      value: boolCoerce(z11.boolean().optional()).describe(
+      phase: z13.string().optional().describe('Phase to update, e.g. "designer"'),
+      field: z13.enum(["questionsCollected", "answered", "executed", "artifactWritten"]).optional().describe("Boolean field to set"),
+      value: boolCoerce(z13.boolean().optional()).describe(
         'Value for the field \u2014 must be a JSON boolean (true/false), NOT the string "true"/"false"'
       ),
-      status: z11.enum(["setup", "questions", "execution", "done"]).optional().describe("Top-level status override"),
-      incrementRetry: boolCoerce(z11.boolean().optional()).describe(
+      status: z13.enum(["setup", "questions", "execution", "done"]).optional().describe("Top-level status override"),
+      incrementRetry: boolCoerce(z13.boolean().optional()).describe(
         "Bump retryCount by 1 \u2014 must be a JSON boolean"
       ),
       updates: jsonCoerce(
-        z11.array(
-          z11.object({
-            phase: z11.string(),
-            field: z11.enum(["questionsCollected", "answered", "executed", "artifactWritten"]),
-            value: z11.boolean()
+        z13.array(
+          z13.object({
+            phase: z13.string(),
+            field: z13.enum(["questionsCollected", "answered", "executed", "artifactWritten"]),
+            value: z13.boolean()
           })
         ).optional()
       ).describe("Batch updates \u2014 apply multiple field changes in one atomic read\u2192modify\u2192write")
@@ -3393,7 +3750,7 @@ function registerPipelineTools(server2) {
     "stackwright_pro_check_execution_ready",
     `Check all phases have answer files in .stackwright/answers/. If phase is provided, check only that phase. ${DESC}`,
     {
-      phase: z11.string().optional().describe("If provided, check only this phase's readiness. Omit to check all phases.")
+      phase: z13.string().optional().describe("If provided, check only this phase's readiness. Omit to check all phases.")
     },
     async ({ phase }) => res(handleCheckExecutionReady(void 0, phase))
   );
@@ -3413,9 +3770,9 @@ function registerPipelineTools(server2) {
     "stackwright_pro_write_phase_questions",
     `Parse otter question-collection response \u2192 .stackwright/questions/{phase}.json. Specialists may also call this directly with a parsed questions array. ${DESC}`,
     {
-      phase: z11.string().optional().describe('Phase name, e.g. "designer" (required for direct write)'),
-      responseText: z11.string().optional().describe("Raw LLM response from QUESTION_COLLECTION_MODE"),
-      questions: jsonCoerce(z11.array(z11.any()).optional()).describe(
+      phase: z13.string().optional().describe('Phase name, e.g. "designer" (required for direct write)'),
+      responseText: z13.string().optional().describe("Raw LLM response from QUESTION_COLLECTION_MODE"),
+      questions: jsonCoerce(z13.array(z13.any()).optional()).describe(
         "Questions array for direct specialist write"
       )
     },
@@ -3457,16 +3814,16 @@ function registerPipelineTools(server2) {
   server2.tool(
     "stackwright_pro_build_specialist_prompt",
     `Assemble execution prompt from answers + upstream artifacts. Foreman passes verbatim. ${DESC}`,
-    { phase: z11.string().describe('Phase to build prompt for, e.g. "pages"') },
+    { phase: z13.string().describe('Phase to build prompt for, e.g. "pages"') },
     async ({ phase }) => res(handleBuildSpecialistPrompt({ phase }))
   );
   server2.tool(
     "stackwright_pro_validate_artifact",
     `Validate and write artifact to .stackwright/artifacts/. Returns retryPrompt on failure. ${DESC}`,
     {
-      phase: z11.string().describe('Phase that produced this artifact, e.g. "designer"'),
-      responseText: z11.string().optional().describe("Raw response text from the specialist otter (Foreman-mediated path, legacy)"),
-      artifact: jsonCoerce(z11.record(z11.string(), z11.unknown()).optional()).describe(
+      phase: z13.string().describe('Phase that produced this artifact, e.g. "designer"'),
+      responseText: z13.string().optional().describe("Raw response text from the specialist otter (Foreman-mediated path, legacy)"),
+      artifact: jsonCoerce(z13.record(z13.string(), z13.unknown()).optional()).describe(
         "Artifact object to validate and write directly (specialist direct path \u2014 skips off-script detection and JSON parsing)"
       )
     },
@@ -3482,7 +3839,7 @@ function registerPipelineTools(server2) {
 }
 
 // src/tools/safe-write.ts
-import { z as z12 } from "zod";
+import { z as z14 } from "zod";
 import { writeFileSync as writeFileSync5, readFileSync as readFileSync5, existsSync as existsSync6, mkdirSync as mkdirSync5, lstatSync as lstatSync6 } from "fs";
 import { normalize, isAbsolute, dirname, join as join5 } from "path";
 var OTTER_WRITE_ALLOWLISTS = {
@@ -3558,11 +3915,20 @@ var OTTER_WRITE_ALLOWLISTS = {
       suffix: "",
       description: "Stackwright config (navigation updates)"
     },
+    {
+      prefix: "stackwright.navigation.",
+      suffix: ".yml",
+      description: "Navigation config YAML (merged at build time)"
+    },
     { prefix: "pages/", suffix: "/content.yml", description: "Landing page content" },
     { prefix: "pages/", suffix: "/content.yaml", description: "Landing page content" },
     { prefix: ".stackwright/artifacts/", suffix: ".json", description: "Polish artifact" },
     { prefix: "README.md", suffix: "", description: "Project README rewrite" }
   ],
+  // domain-expert-otter is a reader/answerer only — it writes via stackwright_pro_save_phase_answers,
+  // not via safe_write. Entry required here because the MCP tool availability guard boilerplate
+  // in its system prompt mentions stackwright_pro_safe_write (triggering the coherence test).
+  "stackwright-pro-domain-expert-otter": [],
   "stackwright-services-otter": [
     { prefix: ".stackwright/artifacts/", suffix: ".json", description: "Services config artifact" },
     { prefix: "services/", suffix: ".ts", description: "Service implementation files" },
@@ -3882,10 +4248,10 @@ function registerSafeWriteTools(server2) {
     "stackwright_pro_safe_write",
     DESC,
     {
-      callerOtter: z12.string().describe('The otter agent name requesting the write, e.g. "stackwright-pro-page-otter"'),
-      filePath: z12.string().describe('Relative path from project root, e.g. "pages/dashboard/content.yml"'),
-      content: z12.string().describe("File content to write"),
-      createDirectories: boolCoerce(z12.boolean().optional().default(true)).describe(
+      callerOtter: z14.string().describe('The otter agent name requesting the write, e.g. "stackwright-pro-page-otter"'),
+      filePath: z14.string().describe('Relative path from project root, e.g. "pages/dashboard/content.yml"'),
+      content: z14.string().describe("File content to write"),
+      createDirectories: boolCoerce(z14.boolean().optional().default(true)).describe(
         "Create parent directories if they don't exist. Default: true"
       )
     },
@@ -3902,7 +4268,7 @@ function registerSafeWriteTools(server2) {
 }
 
 // src/tools/auth.ts
-import { z as z13 } from "zod";
+import { z as z15 } from "zod";
 import { readFileSync as readFileSync6, writeFileSync as writeFileSync6, existsSync as existsSync7, mkdirSync as mkdirSync6 } from "fs";
 import { join as join6 } from "path";
 function buildHierarchy(roles) {
@@ -4774,38 +5140,38 @@ function registerAuthTools(server2) {
     "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.",
     {
-      method: z13.enum(["cac", "oidc", "oauth2", "none"]),
-      provider: z13.enum(["azure-ad", "okta", "ping", "cognito", "custom"]).optional(),
+      method: z15.enum(["cac", "oidc", "oauth2", "none"]),
+      provider: z15.enum(["azure-ad", "okta", "ping", "cognito", "custom"]).optional(),
       // CAC
-      cacCaBundle: z13.string().optional(),
-      cacEdipiLookup: z13.string().optional(),
-      cacOcspEndpoint: z13.string().optional(),
-      cacCertHeader: z13.string().optional(),
+      cacCaBundle: z15.string().optional(),
+      cacEdipiLookup: z15.string().optional(),
+      cacOcspEndpoint: z15.string().optional(),
+      cacCertHeader: z15.string().optional(),
       // OIDC
-      oidcDiscoveryUrl: z13.string().optional(),
-      oidcClientId: z13.string().optional(),
-      oidcClientSecret: z13.string().optional(),
-      oidcScopes: z13.string().optional(),
-      oidcRoleClaim: z13.string().optional(),
+      oidcDiscoveryUrl: z15.string().optional(),
+      oidcClientId: z15.string().optional(),
+      oidcClientSecret: z15.string().optional(),
+      oidcScopes: z15.string().optional(),
+      oidcRoleClaim: z15.string().optional(),
       // OAuth2
-      oauth2AuthUrl: z13.string().optional(),
-      oauth2TokenUrl: z13.string().optional(),
-      oauth2ClientId: z13.string().optional(),
-      oauth2ClientSecret: z13.string().optional(),
-      oauth2Scopes: z13.string().optional(),
+      oauth2AuthUrl: z15.string().optional(),
+      oauth2TokenUrl: z15.string().optional(),
+      oauth2ClientId: z15.string().optional(),
+      oauth2ClientSecret: z15.string().optional(),
+      oauth2Scopes: z15.string().optional(),
       // RBAC
-      rbacRoles: jsonCoerce(z13.array(z13.string()).optional()),
-      rbacDefaultRole: z13.string().optional(),
+      rbacRoles: jsonCoerce(z15.array(z15.string()).optional()),
+      rbacDefaultRole: z15.string().optional(),
       // Audit
-      auditEnabled: boolCoerce(z13.boolean().optional()),
-      auditRetentionDays: numCoerce(z13.number().int().positive().optional()),
+      auditEnabled: boolCoerce(z15.boolean().optional()),
+      auditRetentionDays: numCoerce(z15.number().int().positive().optional()),
       // Routes
-      protectedRoutes: jsonCoerce(z13.array(z13.string()).optional()),
+      protectedRoutes: jsonCoerce(z15.array(z15.string()).optional()),
       // Injection for tests
-      _cwd: z13.string().optional(),
-      devOnly: boolCoerce(z13.boolean().optional()),
-      mockUsers: jsonCoerce(z13.array(z13.object({ name: z13.string(), email: z13.string() })).optional()),
-      nextMajorVersion: numCoerce(z13.number().int().positive().optional())
+      _cwd: z15.string().optional(),
+      devOnly: boolCoerce(z15.boolean().optional()),
+      mockUsers: jsonCoerce(z15.array(z15.object({ name: z15.string(), email: z15.string() })).optional()),
+      nextMajorVersion: numCoerce(z15.number().int().positive().optional())
     },
     async (params) => {
       const cwd = params._cwd ?? process.cwd();
@@ -4821,59 +5187,59 @@ import { join as join7, basename } from "path";
 var _checksums = /* @__PURE__ */ new Map([
   [
     "stackwright-pro-api-otter.json",
-    "1b9fea59a3e5b1e1015229a4e8d1231b6b87e1d12f23a81ecbbd79fe8657a2e0"
+    "df79f4389a576c2885efa07b04f613c60eb8ebf4a8b1d4c7da5e4bb6ee4248dd"
   ],
   [
     "stackwright-pro-auth-otter.json",
-    "f91f82468da9c273fbe6481a3a40957d4c7aa3fa72528c492b6ac5d8e06a563a"
+    "539c7145e88dd2afa7f2417be8cfa8e0e7d82608d051271a20f9c7e4e77d98e7"
   ],
   [
     "stackwright-pro-dashboard-otter.json",
-    "9c319d311801730e8dc9bc142eebb8fc5a7f48da48fa0b8d8c3b7431652447be"
+    "160af221e04200f53709f8c3e249ca6dafb38a325b232fabd478b28f5492ab01"
   ],
   [
     "stackwright-pro-data-otter.json",
-    "f39061981caf0bd14e4eb83e74ac200450425536d14b8c00d60be94759a1ca9d"
+    "b135cb0013edaa40baaf8a03f1d8795920dc0ce611183f047e55104bf8cf35be"
   ],
   [
     "stackwright-pro-designer-otter.json",
-    "af09ac8f06385bdbac63e2820daa2ff7d38b8ff1ff383c161f07e3fb9d9359c5"
+    "1364b2c235c07b0b798e9aab90a68604f60019a5508d41ba576977f173e20cd9"
   ],
   [
     "stackwright-pro-domain-expert-otter.json",
-    "41e3a5838f05f6a51ed272860dd2d5b1df1f20bfc847eb8f39be109b89738e99"
+    "1f21b8ff3450bdae29a4d31b31462ba22583995a448af3c11ab0a5071f46bd72"
   ],
   [
     "stackwright-pro-foreman-otter.json",
-    "4948b8189223e4ced81b632cca7d14b79fde85f204483ab8e847182692c4ee57"
+    "438b03d2c35f64536055c68b3a9044fe3b5e4f2889acde4500dd801fad724be1"
   ],
   [
     "stackwright-pro-geo-otter.json",
-    "ff1191af8108cc70c09afe6a99b008dcb46f71e20f884da1ee424e431868a1b6"
+    "2ec83c26a08c413d9553ff8b8f0f0f643c1a8da043741b356e27106cad78f05f"
   ],
   [
     "stackwright-pro-page-otter.json",
-    "cdd878857c1d809c60263693ab0c6cbb45087fd9c3eeda5b4628bd7026d2bded"
+    "0057ea97f7c2e33a8673140f59a0237eb627d82c676af3fae4faa31033598e03"
   ],
   [
     "stackwright-pro-polish-otter.json",
-    "e5f88d054dd536646f48e5d47cbd64f825f493100002309b90c912fa69ef279e"
+    "02cfa56354bfcd33af6d634ac647f38812a2353e487816b67edc2e9eb2c3e357"
   ],
   [
     "stackwright-pro-scaffold-otter.json",
-    "c9950a34cc6a729a2ad22a4052afc3d7f9b033fe390d9edba4014b76e1d076b6"
+    "ccbc9d20a65dcf7cc2eacb5ac3060cd95a10a3ef795883170684658872299e7b"
   ],
   [
     "stackwright-pro-theme-otter.json",
-    "532d9ca7db6911a09ce5029a8c74c89360bdf6cb8ede8c2636866b509cbe06f9"
+    "a271eac375db9d014afb781536f60f2e6716a9054b12b9c35713af09a63912ff"
   ],
   [
     "stackwright-pro-workflow-otter.json",
-    "80eb6c8d3f079e00533dcb4a3c7fd6baae4d5f4192ab6c27c85d2de5359592fd"
+    "6cc800374de6e723a283e4757af97f7b8337c64ee78053d7e50a79e17314a049"
   ],
   [
     "stackwright-services-otter.json",
-    "b8a252d6a2c5090138899925d3ea95bf3339b6e49adc276a1f5f7304b4ae5134"
+    "c013d7fc2475e62d0af54d57bc988182feee7766bac0edf841cbfad5c73e9261"
   ]
 ]);
 Object.freeze(_checksums);
@@ -5089,7 +5455,7 @@ function registerIntegrityTools(server2) {
 }
 
 // src/tools/domain.ts
-import { z as z14 } from "zod";
+import { z as z16 } from "zod";
 import { readFileSync as readFileSync8, existsSync as existsSync8 } from "fs";
 import { join as join8 } from "path";
 function handleListCollections(input) {
@@ -5475,7 +5841,7 @@ function registerDomainTools(server2) {
     "stackwright_pro_resolve_data_strategy",
     "Look up the data freshness strategy configuration from the user's answer. Returns mechanism, revalidation seconds, required packages, and the exact MCP tool call to make. Replaces the strategy table in the data-otter prompt.",
     {
-      strategy: z14.string().describe(
+      strategy: z16.string().describe(
         'The data-1 answer value: "pulse-fast", "isr-fast", "isr-standard", or "isr-slow"'
       )
     },
@@ -5485,7 +5851,7 @@ function registerDomainTools(server2) {
     "stackwright_pro_validate_workflow",
     "Validate a workflow definition against the Stackwright workflow schema. Checks step ID uniqueness, transition targets, terminal state existence, and service references. Call this after the workflow otter produces output.",
     {
-      workflow: jsonCoerce(z14.record(z14.string(), z14.unknown()).optional()).describe(
+      workflow: jsonCoerce(z16.record(z16.string(), z16.unknown()).optional()).describe(
         "Parsed workflow object. If omitted, reads from .stackwright/artifacts/workflow-config.json"
       )
     },
@@ -5494,7 +5860,7 @@ function registerDomainTools(server2) {
 }
 
 // src/tools/type-schemas.ts
-import { z as z15 } from "zod";
+import { z as z17 } from "zod";
 function buildTypeSchemaSummary() {
   return {
     version: "1.0",
@@ -5571,7 +5937,7 @@ function registerTypeSchemasTool(server2) {
     "stackwright_pro_get_type_schemas",
     "Returns a structured summary of all canonical @stackwright-pro/types schemas, organized by domain. Use this to determine which otter owns a given schema and what artifact key to expect.",
     {
-      format: z15.enum(["full", "domains-only"]).optional().default("full").describe("full = complete summary with all fields; domains-only = just domain names")
+      format: z17.enum(["full", "domains-only"]).optional().default("full").describe("full = complete summary with all fields; domains-only = just domain names")
     },
     async ({ format }) => {
       const summary = buildTypeSchemaSummary();
@@ -5769,7 +6135,7 @@ function registerScaffoldCleanupTools(server2) {
 }
 
 // src/tools/contrast.ts
-import { z as z16 } from "zod";
+import { z as z18 } from "zod";
 function linearizeChannel(c255) {
   const c = c255 / 255;
   return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
@@ -5941,8 +6307,8 @@ function registerContrastTools(server2) {
     "stackwright_pro_check_contrast",
     'Compute the exact WCAG 2.1 contrast ratio between a foreground and background color. Returns the ratio and AA/AAA pass/fail flags. Use this to verify any foreground/background color pair before writing it to the token set. Accepts #RGB, #RRGGBB, hsl(...), or shadcn HSL format ("H S% L%").',
     {
-      fg: z16.string().describe("Foreground (text) color \u2014 hex or HSL"),
-      bg: z16.string().describe("Background color \u2014 hex or HSL")
+      fg: z18.string().describe("Foreground (text) color \u2014 hex or HSL"),
+      bg: z18.string().describe("Background color \u2014 hex or HSL")
     },
     async ({ fg, bg }) => {
       let result;
@@ -5972,8 +6338,8 @@ function registerContrastTools(server2) {
     "stackwright_pro_derive_accessible_palette",
     'Given a seed color (treated as a background), derive the best accessible foreground (text) color that meets the target contrast ratio. Evaluates #ffffff and #000000 against the seed and picks whichever satisfies the target ratio with the highest contrast. Use this for every {name}-foreground token derivation instead of guessing white vs black. Accepts #RGB, #RRGGBB, hsl(...), or shadcn HSL format ("H S% L%").',
     {
-      seed: z16.string().describe("Background (seed) color \u2014 hex or HSL"),
-      targetRatio: numCoerce(z16.number().default(4.5)).describe(
+      seed: z18.string().describe("Background (seed) color \u2014 hex or HSL"),
+      targetRatio: numCoerce(z18.number().default(4.5)).describe(
         "Minimum required contrast ratio (default 4.5 for WCAG AA)"
       )
     },
@@ -6010,9 +6376,11 @@ function registerContrastTools(server2) {
 // package.json
 var package_default = {
   dependencies: {
-    "@stackwright-pro/types": "workspace:*",
     "@modelcontextprotocol/sdk": "^1.10.0",
     "@stackwright-pro/cli-data-explorer": "workspace:*",
+    "@stackwright-pro/types": "workspace:*",
+    "@types/js-yaml": "^4.0.9",
+    "js-yaml": "^4.2.0",
     zod: "^4.4.3"
   },
   devDependencies: {
@@ -6030,7 +6398,7 @@ var package_default = {
     "test:coverage": "vitest run --coverage"
   },
   name: "@stackwright-pro/mcp",
-  version: "0.2.0-alpha.80",
+  version: "0.2.0-alpha.82",
   description: "MCP tools for Stackwright Pro - Data Explorer, Security, ISR, and Dashboard generation",
   license: "SEE LICENSE IN LICENSE",
   main: "./dist/server.js",
@@ -6084,6 +6452,8 @@ registerIntegrityTools(server);
 registerArtifactSigningTools(server);
 registerDomainTools(server);
 registerTypeSchemasTool(server);
+registerValidateYamlFragmentTool(server);
+registerGetSchemaTool(server);
 registerScaffoldCleanupTools(server);
 registerContrastTools(server);
 async function main() {