@markdstage/markdstage 3.0.0 → 3.2.0

package/shared/schema/README.md

@@ -9,8 +9,8 @@ fences. It supports editor completion and validation as well as automated CI val
 | `examples/*.architecture.json` | Working examples with `$schema` |
 
 This directory is **intentionally included in the distribution ZIP** so users can
-reference the schema locally. The extension does not load it at runtime (see
-`.github/RELEASING.md`).
+reference the schema locally. Browser rendering uses a generated, dependency-free
+ES-module contract rather than loading JSON Schema or a validation package.
 
 ## Usage
 
@@ -91,7 +91,7 @@ constraints, so `renderer/architecture.mjs` is authoritative:
 | Self-referencing connectors are prohibited | Same as above |
 | Each `id` is unique across the complete tree | Applies to the flattened set of nested elements |
 | 200 elements / 100 connectors / 20,000 text characters | Aggregated **after flattening**, not expressible by `maxItems` on one array |
-| 64 KiB source | String length before parsing |
+| 65,536 source code units (UTF-16) | Existing JavaScript string-length limit before parsing; distinct from UTF-8 guide-response budgets |
 | Layout fit (`children do not fit`) | Calculated dynamically from child sizes and group interior dimensions |
 | Child `width` / `height` maximum under `layout` | Maximum depends on `cellWidth` / `cellHeight` |
 | The `assets/` file referenced by `node.icon` / `image.src` exists | The parser does not access the file system; a missing file renders an empty image region |
@@ -99,6 +99,43 @@ constraints, so `renderer/architecture.mjs` is authoritative:
 `parseArchitecture` can fail even after schema validation. **The parser always
 makes the final determination of whether a diagram can render.**
 
+### Shared authoring and diagnostic boundary
+
+The bundled JSON Schema is the source of structural vocabulary, not a second
+runtime acceptance policy. A reproducible generation step derives browser-safe
+metadata for permitted fields, element types, scalar constraints, and conditional
+requirements. The compact AI reference and runtime vocabulary consume that same
+metadata. No UI or tool maintains its own permitted-field list.
+
+Rendering, editing, saving, CLI validation, and unloaded-input validation share
+the existing normalizer and semantic checks. Successfully normalized v1 input
+remains accepted even where the authoring schema is intentionally stricter.
+Such differences are authoring warnings, not new errors. On rejected input,
+the common diagnostic layer explains independently checkable structural issues
+from the derived contract and uses the same ID/reference checks as rendering.
+It neither repairs the input nor reruns the parser with deleted fields or
+invented defaults.
+
+Diagnostics carry stable codes, categories, severity, JSON Pointers, human
+messages, and nonautomatic suggestions. A conflicting replacement value is
+reported rather than overwritten. JSON parsing, structural, semantic, and
+layout stages distinguish passed, failed, and skipped work. Bounded diagnostic
+collection reports truncation explicitly; a skipped stage is not evidence that
+its constraints passed. Legacy exception messages and block-level error arrays
+remain available alongside the detailed report.
+
+Unloaded validation is a read-only boundary: it accepts explicit DSL text or
+individual Markdown slide fragments and has no authority to open a canvas,
+change its current page, read or write files, or modify editor drafts.
+API execution success is separate from content validity and completeness.
+Diagnostic budgets are not additional DSL v1 restrictions. Image existence,
+slide clipping, and visual clarity still require separate asset/output review.
+
+This preserves the existing schema/runtime responsibility split without a
+browser-side schema dependency or a parser replacement. The tradeoff is a
+generated artifact that must be kept in sync; a drift check makes that
+requirement enforceable.
+
 ### Invariant: P ⊆ A, except for documented divergences
 
 As a rule, documents accepted by the parser (P) must also be accepted by the
@@ -112,6 +149,8 @@ divergence must make the schema stricter, and every instance is listed below.**
 | # | Case | Behavior | Reason |
 | --- | --- | --- | --- |
 | 1 | A child of a group with `layout` has nonnumeric `x` / `y` | Parser accepts; schema rejects | Placement is calculated automatically under `layout`, so the parser silently discards `x` / `y` without validating their values. This likely indicates an authoring mistake that the schema should report. Tightening the parser would reject previously accepted input and would be a breaking change. |
+| 2 | A layout child has numeric `x` / `y` outside the schema range | Parser accepts; schema rejects | Parent-managed placement ignores these values just as it ignores nonnumeric coordinates. Preflight reports a compatibility warning. |
+| 3 | Root `$schema` is not a string | Parser accepts; schema rejects | v1 ignores this metadata without resolving it. Editor completion requires a string; preflight warns without changing runtime acceptance. |
 
 Divergences are recorded as `divergence` entries in `test/schema/corpus.mjs`,
 and tests fail when no reason string is present. **CI detects silent divergence.**
@@ -224,5 +263,21 @@ Because `layered` calculates hierarchy from connector direction, **do not specif
 child `x` / `y`**. This matches existing `grid` / `row` / `column` behavior.
 
 The validation library (`ajv`) is a **root devDependency**. The extension ships
-as a ZIP and must run without `node_modules`, so do not import the schema or ajv
-from `renderer/architecture.mjs`.
+as a ZIP and must run without `node_modules`, so do not import JSON Schema or
+ajv from the renderer. Regenerate the browser-safe metadata after a schema
+change with:
+
+```powershell
+node .github\extensions\markdstage\scripts\generate-architecture-contract.mjs
+```
+
+The same command with `--check` fails on drift. The authoring reference, including
+its self-contained example, must remain within 8 KiB UTF-8. Public valid examples
+are checked against both Schema and runtime; intentionally invalid examples
+remain explicitly marked as described above.
+
+The generated module has a separate distribution budget: it must stay below
+1,000,000 bytes, the conservative interpretation of the installer's 1 MB
+single-file limit. An automated size check measures the actual generated file.
+This is independent of both the 8 KiB guide-response budget and the existing
+DSL source-length limit.

package/shared/schema/architecture-contract.mjs

@@ -0,0 +1,355 @@
+const own = (value, key) => Object.prototype.hasOwnProperty.call(value, key);
+const object = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const annotations = new Set(["$schema", "$id", "$anchor", "$comment", "title", "description", "examples"]);
+const schemaMaps = new Set(["properties", "patternProperties", "dependentSchemas", "$defs"]);
+const schemaArrays = new Set(["allOf", "anyOf", "oneOf", "prefixItems"]);
+const schemaValues = new Set([
+  "items", "contains", "additionalProperties", "unevaluatedProperties", "unevaluatedItems",
+  "propertyNames", "not", "if", "then", "else", "contentSchema",
+]);
+const scalarKeywords = new Set([
+  ...annotations, "type", "enum", "const", "required", "default", "deprecated", "readOnly",
+  "writeOnly", "minimum", "maximum", "exclusiveMinimum", "exclusiveMaximum", "multipleOf",
+  "minLength", "maxLength", "pattern", "format", "minItems", "maxItems", "uniqueItems",
+  "minContains", "maxContains", "minProperties", "maxProperties", "dependentRequired",
+  "contentEncoding", "contentMediaType",
+]);
+
+function unsupported(path, message) {
+  throw new Error(`Unsupported Architecture contract derivation at ${path}: ${message}`);
+}
+
+function ordered(value) {
+  if (Array.isArray(value)) return value.map(ordered);
+  if (!object(value)) return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, ordered(value[key])]));
+}
+
+function signature(value) {
+  return JSON.stringify(ordered(value));
+}
+
+function assertions(value) {
+  if (!object(value)) return value;
+  return Object.fromEntries(Object.entries(value)
+    .filter(([key]) => !annotations.has(key))
+    .map(([key, entry]) => [
+      key,
+      schemaMaps.has(key)
+        ? Object.fromEntries(Object.entries(entry).map(([name, child]) => [name, assertions(child)]))
+        : schemaArrays.has(key) ? entry.map(assertions)
+          : schemaValues.has(key) ? assertions(entry) : entry,
+    ]));
+}
+
+function conjoin(left, right, path) {
+  if (left === true) return right;
+  if (right === true) return left;
+  if (left === false || right === false) return false;
+  for (const [closed, other] of [[left, right], [right, left]]) {
+    if (closed.additionalProperties === false &&
+        Object.keys(other.properties ?? {}).some((key) => !own(closed.properties ?? {}, key))) {
+      unsupported(path, "allOf cannot widen a closed object's permitted properties");
+    }
+  }
+  const result = { ...left };
+  // Keep complete conditional clauses together; independently merging their if/then/else
+  // keywords would change which assertion a branch applies to.
+  if (own(left, "if") && own(right, "if")) {
+    const condition = Object.fromEntries(["if", "then", "else"]
+      .filter((key) => own(right, key)).map((key) => [key, right[key]]));
+    right = Object.fromEntries(Object.entries(right)
+      .filter(([key]) => !["if", "then", "else"].includes(key)));
+    result.allOf = [...(result.allOf ?? []), condition];
+  }
+  for (const [key, value] of Object.entries(right)) {
+    if (!own(result, key) || annotations.has(key)) {
+      result[key] = value;
+    } else if (key === "properties") {
+      result.properties = { ...result.properties };
+      for (const [name, property] of Object.entries(value)) {
+        result.properties[name] = own(result.properties, name)
+          ? conjoin(result.properties[name], property, `${path}/properties/${name}`)
+          : property;
+      }
+    } else if (key === "required") {
+      result.required = [...new Set([...result.required, ...value])];
+    } else if (key === "allOf") {
+      result.allOf = [...result.allOf, ...value];
+    } else if (key === "enum") {
+      result.enum = result.enum.filter((entry) => value.some((other) => signature(entry) === signature(other)));
+      if (!result.enum.length) unsupported(path, "allOf has disjoint enums");
+    } else if (key === "type") {
+      const types = [result.type].flat().filter((entry) => [value].flat().includes(entry));
+      if (!types.length) unsupported(path, "allOf has disjoint types");
+      result.type = types.length === 1 ? types[0] : types;
+    } else if (/^(minimum|exclusiveMinimum|minLength|minItems|minContains|minProperties)$/.test(key)) {
+      result[key] = Math.max(result[key], value);
+    } else if (/^(maximum|exclusiveMaximum|maxLength|maxItems|maxContains|maxProperties)$/.test(key)) {
+      result[key] = Math.min(result[key], value);
+    } else if (signature(result[key]) !== signature(value)) {
+      unsupported(path, `cannot flatten conflicting ${key} assertions without losing information`);
+    }
+  }
+  if (own(result, "const") && result.enum) {
+    if (!result.enum.some((entry) => signature(entry) === signature(result.const))) {
+      unsupported(path, "const is excluded by enum");
+    }
+    delete result.enum;
+  }
+  return result;
+}
+
+function createResolver(schema) {
+  function dereference(ref) {
+    if (typeof ref !== "string" || !ref.startsWith("#/")) {
+      unsupported(String(ref), "only local JSON Pointer $ref values are supported");
+    }
+    let target = schema;
+    for (const part of ref.slice(2).split("/")) {
+      const key = part.replace(/~1/g, "/").replace(/~0/g, "~");
+      if (!object(target) || !own(target, key)) unsupported(ref, "unresolved $ref");
+      target = target[key];
+    }
+    return target;
+  }
+
+  function discriminator(input, seen = new Set()) {
+    if (!object(input)) return null;
+    if (input.$ref) {
+      if (seen.has(input.$ref)) unsupported(input.$ref, "recursive discriminator");
+      return discriminator(dereference(input.$ref), new Set([...seen, input.$ref]));
+    }
+    return input.properties?.type?.enum ?? null;
+  }
+
+  function resolve(input, path = "#", stack = []) {
+    if (typeof input === "boolean") return input;
+    if (!object(input)) unsupported(path, "expected a JSON Schema object or boolean");
+    let result = {};
+    if (input.$ref) {
+      if (stack.includes(input.$ref)) unsupported(path, "recursive $ref outside an element array");
+      result = resolve(dereference(input.$ref), input.$ref, [...stack, input.$ref]);
+    }
+    const local = {};
+    for (const [key, value] of Object.entries(input)) {
+      if (key === "$ref" || key === "allOf") continue;
+      if (schemaMaps.has(key)) {
+        local[key] = Object.fromEntries(Object.entries(value)
+          .map(([name, child]) => [name, resolve(child, `${path}/${key}/${name}`, stack)]));
+      } else if (schemaArrays.has(key)) {
+        local[key] = value.map((child, index) => resolve(child, `${path}/${key}/${index}`, stack));
+      } else if (schemaValues.has(key)) {
+        // Element arrays are the tree boundary. Keep their standard local references rather
+        // than unrolling every nesting level (or a future recursive element definition).
+        if (key === "items" && object(value) && value.$ref && discriminator(value)) {
+          dereference(value.$ref);
+          if (Object.keys(value).some((name) => name !== "$ref")) {
+            unsupported(`${path}/items`, "element-array $ref siblings need explicit derivation support");
+          }
+          local[key] = { $ref: value.$ref };
+        } else {
+          local[key] = resolve(value, `${path}/${key}`, stack);
+        }
+      } else if (scalarKeywords.has(key)) {
+        local[key] = structuredClone(value);
+      } else {
+        unsupported(`${path}/${key}`, "unrecognized JSON Schema keyword");
+      }
+    }
+    result = conjoin(result, local, path);
+    for (const [index, branch] of (input.allOf ?? []).entries()) {
+      const resolved = resolve(branch, `${path}/allOf/${index}`, stack);
+      if (object(resolved) && ["if", "anyOf", "oneOf", "not"].some((key) => own(resolved, key))) {
+        result = conjoin(result, { allOf: [resolved] }, path);
+      } else {
+        result = conjoin(result, resolved, path);
+      }
+    }
+    return result;
+  }
+  return { resolve, discriminator };
+}
+
+function typeGuard(condition, path) {
+  if (!condition?.properties?.type) return null;
+  const allowed = new Set(["type", "properties", "required"]);
+  if (Object.keys(condition).some((key) => !allowed.has(key))
+      || Object.keys(condition.properties).some((key) => key !== "type")
+      || condition.required?.length !== 1 || condition.required[0] !== "type"
+      || (condition.type !== undefined && condition.type !== "object")) {
+    unsupported(path, "element discriminator must test only the required type field");
+  }
+  const value = condition.properties.type;
+  if (Object.keys(value).length !== 1 || (!own(value, "const") && !own(value, "enum"))) {
+    unsupported(path, "element discriminator must use const or enum");
+  }
+  return own(value, "const") ? [value.const] : value.enum;
+}
+
+function elementVariants(table, path) {
+  const types = table.properties?.type?.enum;
+  if (!Array.isArray(types) || !types.length || types.some((type) => typeof type !== "string")) {
+    unsupported(path, "element items must declare a nonempty string type enum");
+  }
+  const selected = {};
+  for (const type of types) {
+    let matched = false;
+    function select(input) {
+      if (!object(input)) unsupported(path, "boolean element branches are not supported");
+      if (input.anyOf || input.oneOf || input.not) unsupported(path, "ambiguous element object composition");
+      let result = Object.fromEntries(Object.entries(input).filter(([key]) => key !== "allOf"));
+      if (input.if) {
+        const guard = typeGuard(input.if, path);
+        if (guard) {
+          result = Object.fromEntries(Object.entries(result)
+            .filter(([key]) => !["if", "then", "else"].includes(key)));
+          const applies = guard.includes(type);
+          matched ||= applies && own(input, "then");
+          const branch = applies ? input.then : input.else;
+          if (branch !== undefined) result = conjoin(result, select(branch), path);
+        }
+      }
+      for (const branch of input.allOf ?? []) result = conjoin(result, select(branch), path);
+      return result;
+    }
+    selected[type] = select(table);
+    if (!matched) unsupported(path, `no conditional element branch for ${JSON.stringify(type)}`);
+    if (selected[type].additionalProperties !== false) {
+      unsupported(path, `${type} must explicitly bound its permitted properties`);
+    }
+  }
+  return selected;
+}
+
+function fields(descriptor, path) {
+  const result = { ...(descriptor.properties ?? {}) };
+  function conditional(input) {
+    if (!object(input)) return;
+    if (input.anyOf || input.oneOf) unsupported(path, "conditional object unions need explicit field derivation");
+    for (const [name, value] of Object.entries(input.properties ?? {})) {
+      // A conditional assertion may narrow an existing field (connector.points, for example).
+      // The complete condition stays on the element and in definitions; it is not an
+      // unconditional restriction on the property descriptor.
+      if (!own(result, name)) {
+        if (descriptor.additionalProperties === false) {
+          unsupported(path, `conditional field ${name} is outside the closed object's permitted properties`);
+        }
+        result[name] = value;
+      }
+    }
+    for (const branch of input.allOf ?? []) conditional(branch);
+    if (input.then) conditional(input.then);
+    if (input.else) conditional(input.else);
+  }
+  conditional(descriptor);
+  return result;
+}
+
+function elementConditions(descriptor) {
+  return Object.fromEntries(["if", "then", "else", "allOf"]
+    .filter((key) => own(descriptor, key)).map((key) => [key, descriptor[key]]));
+}
+
+function conditionSignature(conditions, resolver) {
+  // Child selectors vary by nesting depth; their exact rules remain in definitions.
+  // All other element-level conditions must agree across fixed/flow contexts.
+  return JSON.stringify(ordered(assertions(conditions)), (key, value) =>
+    key === "items" && resolver.discriminator(value) ? {} : value);
+}
+
+function childTables(descriptor, resolver, path) {
+  const result = [];
+  function visit(input, mode) {
+    if (!object(input)) return;
+    for (const property of Object.values(input.properties ?? {})) {
+      if (property.items && resolver.discriminator(property.items)) {
+        result.push({ items: property.items, mode });
+      }
+    }
+    for (const branch of input.allOf ?? []) visit(branch, mode);
+    if (input.if) {
+      const before = result.length;
+      visit(input.then, "flow");
+      visit(input.else, "fixed");
+      if (result.length !== before && (
+        input.if.type !== "object" || input.if.required?.length !== 1
+        || input.if.required[0] !== "layout"
+        || Object.keys(input.if).some((key) => !["type", "required"].includes(key))
+      )) {
+        unsupported(path, "child layout context must be selected by presence of the parent's layout");
+      }
+    }
+  }
+  visit(descriptor, "fixed");
+  return result;
+}
+
+/**
+ * Derive vocabulary from JSON Schema, not an independent validator. The fixed/flow projection
+ * follows the schema's parent-layout branches. Element conditions and resolved definitions
+ * retain JSON Schema keywords; depth-specific child selectors remain in definitions.
+ * Unsupported projections fail rather than silently publishing partial metadata.
+ */
+export function deriveArchitectureContract(schema) {
+  if (!object(schema) || !object(schema.$defs)) unsupported("#", "expected a schema with $defs");
+  const resolver = createResolver(schema);
+  const { $defs, ...rootSchema } = schema;
+  const root = resolver.resolve(rootSchema);
+  if (root.type !== "object" || root.additionalProperties !== false || !root.properties?.elements?.items) {
+    unsupported("#", "expected a closed root object with elements.items");
+  }
+  if (root.if || root.allOf || root.anyOf || root.oneOf) {
+    unsupported("#", "conditional root fields need explicit derivation support");
+  }
+  const elements = {};
+  const queue = [{ items: root.properties.elements.items, mode: "fixed" }];
+  const visited = new Set();
+  while (queue.length) {
+    const { items, mode } = queue.shift();
+    const key = `${mode}:${signature(items)}`;
+    if (visited.has(key)) continue;
+    visited.add(key);
+    const variants = elementVariants(resolver.resolve(items), key);
+    for (const [type, descriptor] of Object.entries(variants)) {
+      const properties = fields(descriptor, `${key}/${type}`);
+      const required = descriptor.required ?? [];
+      const conditions = elementConditions(descriptor);
+      if (required.some((name) => !own(properties, name))) unsupported(key, `${type} requires an undeclared field`);
+      const existing = elements[type] ??= { properties, required: {}, ...conditions };
+      if (signature(assertions({ properties: existing.properties })) !== signature(assertions({ properties }))) {
+        unsupported(key, `${type} properties vary by parent context; cannot publish one field record`);
+      }
+      if (conditionSignature(elementConditions(existing), resolver) !== conditionSignature(conditions, resolver)) {
+        unsupported(key, `${type} conditional rules vary by parent context beyond child element arrays`);
+      }
+      if (existing.required[mode] && signature([...existing.required[mode]].sort()) !== signature([...required].sort())) {
+        unsupported(key, `${type} requirements vary within ${mode} context`);
+      }
+      existing.required[mode] = required;
+      queue.push(...childTables(descriptor, resolver, `${key}/${type}`));
+    }
+  }
+  for (const [type, element] of Object.entries(elements)) {
+    if (!element.required.fixed || !element.required.flow) {
+      unsupported("#/properties/elements", `${type} has no reachable fixed and flow variants`);
+    }
+  }
+  return {
+    root: { properties: root.properties, required: root.required ?? [] },
+    elements,
+    definitions: Object.fromEntries(Object.entries($defs)
+      .map(([name, definition]) => [name, resolver.resolve(definition, `#/$defs/${name}`)])),
+  };
+}
+
+export function architectureContractModule(schema) {
+  // Declaration order is also the runtime's diagnostic field/type order.
+  return [
+    "// Generated from schema/architecture-v1.schema.json. Do not edit.",
+    "// Regenerate: node .github/extensions/markdstage/scripts/generate-architecture-contract.mjs",
+    "// Structural metadata only; renderer/architecture.mjs remains the semantic authority.",
+    `export const architectureContract = ${JSON.stringify(deriveArchitectureContract(schema), null, 2)};`,
+    "",
+  ].join("\n");
+}

package/shared/scripts/generate-architecture-contract.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+import { readFile, writeFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import { architectureContractModule } from "../schema/architecture-contract.mjs";
+
+const schemaUrl = new URL("../schema/architecture-v1.schema.json", import.meta.url);
+const outputUrl = new URL("../renderer/architecture-contract.mjs", import.meta.url);
+
+export async function generateArchitectureContract({
+  check = false,
+  source = schemaUrl,
+  output = outputUrl,
+} = {}) {
+  const expected = architectureContractModule(JSON.parse(await readFile(source, "utf8")));
+  let current;
+  try {
+    current = await readFile(output, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+  }
+  const changed = expected !== current?.replace(/\r\n/g, "\n");
+  if (changed && check) {
+    throw new Error("Architecture contract is out of date. Run npm run generate:architecture.");
+  }
+  if (changed) await writeFile(output, expected, "utf8");
+  return { changed, checked: check };
+}
+
+if (process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url) {
+  try {
+    const args = process.argv.slice(2);
+    if (args.some((arg) => arg !== "--check") || args.length > 1) {
+      throw new Error("Usage: node generate-architecture-contract.mjs [--check]");
+    }
+    const result = await generateArchitectureContract({ check: args.includes("--check") });
+    console.log(`Architecture contract ${result.checked ? "is current" : result.changed ? "generated" : "unchanged"}.`);
+  } catch (error) {
+    console.error(error.message);
+    process.exitCode = 1;
+  }
+}

package/src/commands/validate.mjs

@@ -3,6 +3,7 @@
 import {
   MarkdStageError,
   architectureValidationErrors,
+  architectureValidationReport,
   createDeckSession,
   createUrlToken,
   hasFrontMatter,
@@ -27,10 +28,24 @@ export async function validateCommand(options) {
       code: error.code,
       message: error.message,
     });
-    return { ok: false, file: options.file, total: 0, errors, warnings };
+    return {
+      ok: false,
+      valid: false,
+      complete: false,
+      truncated: false,
+      file: options.file,
+      total: 0,
+      errors,
+      warnings,
+      stages: { json: "skipped", structure: "skipped", semantic: "skipped", layout: "skipped" },
+      diagnostics: [],
+      diagnosticCount: 0,
+      blocks: [],
+    };
   }
 
-  for (const issue of architectureValidationErrors(session.slides)) {
+  const validation = architectureValidationReport(session.slides);
+  for (const issue of architectureValidationErrors(session.slides, { validation })) {
     errors.push({
       code: issue.code,
       page: issue.page,
@@ -38,6 +53,12 @@ export async function validateCommand(options) {
       message: issue.message,
     });
   }
+  if (validation.truncated) {
+    errors.push({
+      code: "validation_incomplete",
+      message: `Architecture validation reached inspection limits (${validation.budget.limitsReached.join(", ")}). Validate smaller inputs before treating the deck as valid.`,
+    });
+  }
 
   session.slides.forEach((slide, index) => {
     if (!hasFrontMatter(slide)) {
@@ -51,7 +72,10 @@ export async function validateCommand(options) {
   });
 
   return {
-    ok: errors.length === 0,
+    ok: errors.length === 0 && validation.valid,
+    valid: errors.length === 0 && validation.valid,
+    complete: validation.complete,
+    truncated: validation.truncated,
     file: session.file,
     workspace: session.workspaceRoot,
     total: session.slides.length,
@@ -59,6 +83,13 @@ export async function validateCommand(options) {
     themeFile: session.customThemeFile || undefined,
     errors,
     warnings,
+    stages: validation.stages,
+    diagnostics: validation.diagnostics,
+    diagnosticCount: validation.diagnosticCount,
+    blocks: validation.blocks,
+    skipped: validation.skipped,
+    limits: validation.limits,
+    budget: validation.budget,
   };
 }
 
@@ -74,6 +105,11 @@ export function formatValidateReport(report) {
   for (const warning of report.warnings) {
     lines.push(`  warn   slide ${warning.page}: ${warning.message}`);
   }
+  if (report.complete === false) {
+    lines.push(report.truncated
+      ? "  Validation incomplete: inspection limits were reached; unchecked content is not valid."
+      : "  Architecture validation incomplete: fix the reported errors and validate again.");
+  }
   lines.push(report.ok ? "  OK: the deck is valid." : `  ${report.errors.length} error(s) found.`);
   return lines.join("\n");
 }

package/src/runtime.mjs

@@ -48,6 +48,7 @@ const [
   guide,
   presenterWindow,
   markdownFiles,
+  architectureValidation,
 ] = await Promise.all([
   load("runtime/errors.mjs"),
   load("runtime/deck-session.mjs"),
@@ -58,6 +59,7 @@ const [
   load("markdstage-guide.mjs"),
   load("presenter-window.mjs"),
   load("scripts/markdown-files.mjs"),
+  load("architecture-validation.mjs"),
 ]);
 
 export const { MarkdStageError } = errors;
@@ -75,9 +77,11 @@ export const { findChromiumBrowser, terminateProcessTree, isProcessRunning } = b
 export const { captureDirectoryName, pdfNameForSource, pptxNameForSource } = outputPaths;
 export const {
   architectureValidationErrors,
+  architectureValidationReport,
   deckValidationFeedback,
   hasFrontMatter,
   readGuide,
 } = guide;
+export const { validateArchitectureInput, createArchitectureValidationTool } = architectureValidation;
 export const { buildPresenterBrowserArgs } = presenterWindow;
 export const { isMarkdownPath, MARKDOWN_MAX_BYTES } = markdownFiles;

package/src/skills.mjs

@@ -73,11 +73,15 @@ what the MarkdStage canvas and MarkdStage Desktop render.
    required diagrams, and output format.
 2. Read only the relevant guidance. Start with
    \`markdstage guide slide-format\`, then retrieve \`themes\`,
-   \`custom-themes\`, or \`architecture-dsl\` when needed.
+   \`custom-themes\`, or \`architecture-schema\` when needed. Before drafting
+   Architecture DSL, read the compact \`architecture-schema\` contract first;
+   use \`architecture-dsl\` for advanced behavior.
 3. Create the complete deck as one Markdown source file (see
    \`references/slide-format.md\`).
 4. Validate structure, themes, and Architecture DSL before visual review:
-   \`markdstage validate slides.md --json\`.
+   \`markdstage validate slides.md --json\`. Review diagnostic codes, JSON Pointers,
+   and completeness, fix independent issues together, and preserve the same
+   validated content when presenting. Suggestions are never automatic repairs.
 5. Use \`markdstage preview slides.md --watch\` for live source-backed authoring.
    It reloads on save without losing the current slide and keeps the last valid
    deck while a save is incomplete.