@intentius/chant 0.44.14 → 0.46.0

package/src/cli/commands/build.ts

@@ -1,5 +1,15 @@
 import { build } from "../../build";
-import { loadChantConfigUpward, resolveOwnershipMarker, resolveFoldEnabled, resolveSandboxEnabled } from "../../config";
+import {
+  loadChantConfigUpward,
+  resolveOwnershipMarker,
+  resolveOwnershipEnv,
+  ownershipEnvDisagreement,
+  isOwnershipParamRef,
+  resolveFoldEnabled,
+  resolveSandboxEnabled,
+} from "../../config";
+import { unknownEnvError } from "../../env";
+import type { OwnershipMarker } from "../../ownership";
 import { resolveCliBuildParams } from "../build-params-cli";
 import type { Serializer, SerializerResult } from "../../serializer";
 import type { LexiconPlugin } from "../../lexicon";
@@ -141,10 +151,9 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   // its default.
   const loaded = await loadChantConfigUpward(infraPath);
   const config = loaded.config;
-  const ownership = resolveOwnershipMarker(config);
+  // The ownership marker is resolved further down, after build parameters —
+  // `ownership.env` may reference one (#1396).
 
-  // Environment for policy evaluation: explicit --env wins, else ownership.env.
-  const env = options.env ?? config.ownership?.env;
   // Project-authored organizational policy checks (lint.policies), run over the
   // resolved resources during build. Resolve paths relative to the config dir.
   const configDir = loaded.configPath ? dirname(loaded.configPath) : infraPath;
@@ -197,11 +206,13 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   // missing required value, a type/enum mismatch) is reported as a chant
   // build error naming the parameter, never a thrown error from inside user
   // source (which is what loomster's hand-rolled `tierFromEnv()`-style
-  // validators did before migrating to this mechanism). Also logs every
-  // resolved value (`[param] name = value (source)`) on success.
+  // validators did before migrating to this mechanism). Also logs a one-line
+  // count on success, or every resolved value (`[param] name = value
+  // (source)`) under --verbose (#1424).
   const paramsResolution = resolveCliBuildParams(config.buildParams, {
     cli: options.params,
     paramsFile: options.paramsFile,
+    verbose: options.verbose,
   });
   if (!paramsResolution.success) {
     errors.push(...paramsResolution.errors);
@@ -228,6 +239,45 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
     );
   }
 
+  // #1396 — opt-in ownership marking, resolved AFTER build parameters so
+  // `ownership.env: { param: "env" }` takes the value `--param env=prod` (or
+  // the declared env mapping, or the default) bound to params.env — one
+  // source for the label and the marker. A reference that cannot be
+  // satisfied is a build error, not a marker silently stamped without an env.
+  let ownership: OwnershipMarker | undefined;
+  // Environment for policy evaluation: explicit --env wins, else ownership.env
+  // (read even when marking itself is off, so policy can still branch on it).
+  let env: string | undefined;
+  try {
+    ownership = resolveOwnershipMarker(config, paramsResolution.provenance);
+    env = options.env ?? resolveOwnershipEnv(config, paramsResolution.provenance);
+  } catch (err) {
+    errors.push(formatError({ message: err instanceof Error ? err.message : String(err) }));
+    return { success: false, resourceCount: 0, fileCount: 0, errors, warnings };
+  }
+  // A literal `ownership.env` next to an `env` build parameter that resolved
+  // to something else is the silent divergence #1396 reports — say so.
+  const disagreement = ownershipEnvDisagreement(config, paramsResolution.provenance);
+  if (disagreement) warnings.push(formatWarning({ message: disagreement }));
+
+  // #1221 — dynamic-env legality. `--env` is validated against the declared
+  // `environments` in cli/main.ts; a param-bound `ownership.env` supplied via
+  // `--param env=<value>` reached here unchecked, so `--param env=pord`
+  // stamped a marker for an environment the project never declared. Same
+  // check, same site of truth: literal entries match by equality, entries
+  // containing `*` (e.g. `"pr-*"`) match as glob patterns, so an unbounded
+  // family like per-PR environments is declarable without listing each name.
+  if (isOwnershipParamRef(config.ownership?.env)) {
+    const dynamicEnvErr = unknownEnvError(env, config.environments);
+    if (dynamicEnvErr) {
+      errors.push(formatError({
+        message: dynamicEnvErr,
+        hint: 'Declare it in chant.config `environments` (a "pr-*" pattern entry covers a dynamic family), or pass a declared value.',
+      }));
+      return { success: false, resourceCount: 0, fileCount: 0, errors, warnings };
+    }
+  }
+
   // #1039 — thread each loaded plugin's registered intrinsics (e.g. AWS's
   // `Sub`) through to the fold path, so a file using a registered intrinsic
   // tagged template folds instead of unconditionally falling back to run.
@@ -272,14 +322,22 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   });
 
   // #1022 — report per-file fold vs run so it's visible what still runs.
-  if (fold) {
-    for (const decision of result.foldDecisions) {
-      const rel = relative(infraPath, decision.file) || decision.file;
-      const detail =
-        decision.mode === "fold"
-          ? `${decision.resourceCount ?? 0} resource(s), no module execution`
-          : (decision.reason ?? "fell back to run");
-      console.error(formatInfo(`[fold:${decision.mode}] ${rel} — ${detail}`));
+  // #1424 — one line by default; the per-file lines and their reasons are
+  // --verbose. A file that ran is the expected outcome for source that
+  // computes values in functions, and a dozen "is not foldable" notes read
+  // like errors to someone meeting the project for the first time.
+  if (fold && result.foldDecisions.length > 0) {
+    if (options.verbose) {
+      for (const decision of result.foldDecisions) {
+        const rel = relative(infraPath, decision.file) || decision.file;
+        const detail =
+          decision.mode === "fold"
+            ? `${decision.resourceCount ?? 0} resource(s), no module execution`
+            : (decision.reason ?? "fell back to run");
+        console.error(formatInfo(`[fold:${decision.mode}] ${rel} — ${detail}`));
+      }
+    } else {
+      console.error(formatInfo(summarizeFoldDecisions(result.foldDecisions)));
     }
   }
 
@@ -587,6 +645,20 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
   };
 }
 
+/**
+ * `fold: 8 files folded, 13 ran (--verbose for reasons)` — the non-verbose
+ * report of a fold build's per-file decisions (#1424). The "(--verbose for
+ * reasons)" hint appears only when something ran, since that is the only case
+ * with a reason to read.
+ */
+export function summarizeFoldDecisions(decisions: readonly { mode: string }[]): string {
+  const folded = decisions.filter((d) => d.mode === "fold").length;
+  const ran = decisions.length - folded;
+  const files = (n: number) => `${n} file${n === 1 ? "" : "s"}`;
+  const hint = ran > 0 ? " (--verbose for reasons)" : "";
+  return `fold: ${files(folded)} folded, ${ran} ran${hint}`;
+}
+
 /**
  * Simple JSON to YAML converter
  */

package/src/cli/commands/check-lexicon-docs.ts

@@ -69,3 +69,33 @@ export function auditDocsReachability(lexiconDir: string): DocsReachability {
 
   return { hasSite: true, pages, unreachable };
 }
+
+export interface DocsClassification {
+  /** Whether this lexicon has a docs/pages/ directory at all. */
+  hasPages: boolean;
+  /** Authored page files under docs/pages/ that lack a valid `diataxis` field. */
+  unclassified: string[];
+}
+
+const QUADRANTS = new Set(["tutorial", "how-to", "reference", "explanation"]);
+
+/**
+ * Audit docs/pages/ for authored pages with no Diátaxis quadrant (#1731).
+ *
+ * The docs pipeline throws on the same condition, so this is the cheap
+ * pre-flight that reports every offender at once instead of the first one.
+ */
+export function auditDocsClassification(lexiconDir: string): DocsClassification {
+  const pagesDir = join(lexiconDir, "docs", "pages");
+  if (!existsSync(pagesDir)) return { hasPages: false, unclassified: [] };
+  const unclassified: string[] = [];
+  for (const file of readdirSync(pagesDir).sort()) {
+    if (!file.endsWith(".mdx") && !file.endsWith(".md")) continue;
+    const text = readFileSync(join(pagesDir, file), "utf-8");
+    const end = text.startsWith("---\n") ? text.indexOf("\n---", 4) : -1;
+    const fm = end === -1 ? "" : text.slice(4, end);
+    const value = fm.match(/^diataxis:\s*(.+)$/m)?.[1].trim();
+    if (!value || !QUADRANTS.has(value)) unclassified.push(file);
+  }
+  return { hasPages: true, unclassified };
+}

package/src/cli/commands/check-lexicon-examples.test.ts

@@ -1,5 +1,5 @@
 import { describe, test, expect, beforeAll, afterAll } from "vitest";
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync, symlinkSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { checkExamplesBuild } from "./check-lexicon-examples";
@@ -15,7 +15,10 @@ import { checkExamplesBuild } from "./check-lexicon-examples";
  * exactly what each example's own `npm run build` does.
  *
  * These fixtures import the real, already-installed `@intentius/chant-lexicon-aws`
- * package (workspace-linked), so no lexicon plugin needs to be faked.
+ * package (workspace-linked), so no lexicon plugin needs to be faked. The
+ * temp lexicon dir gets the repo's node_modules linked in so that bare
+ * specifier resolves from the fixture the way it does from a real lexicon
+ * (Vitest 4's module runner resolves from the importing file, not the root).
  */
 
 function writeLexiconDirWithExample(
@@ -35,18 +38,43 @@ describe("checkExamplesBuild", () => {
 
   beforeAll(() => {
     dir = mkdtempSync(join(tmpdir(), "chant-check-lexicon-examples-"));
+    symlinkSync(join(__dirname, "..", "..", "..", "..", "..", "node_modules"), join(dir, "node_modules"), "dir");
   });
   afterAll(() => rmSync(dir, { recursive: true, force: true }));
 
-  test("a clean example builds", async () => {
-    writeLexiconDirWithExample(dir, "clean", {
-      "bucket.ts": `import { Bucket } from "@intentius/chant-lexicon-aws";
+  // A bucket that satisfies the aws lexicon's error-severity checks (#1400):
+  // public access blocked (WAW018) and a TLS-only bucket policy (WAW042).
+  const cleanBucketSource = `import { Bucket, PublicAccessBlockConfiguration, S3BucketPolicy, Ref } from "@intentius/chant-lexicon-aws";
 
 export const appBucket = new Bucket({
   BucketName: "my-app-bucket",
+  PublicAccessBlockConfiguration: new PublicAccessBlockConfiguration({
+    BlockPublicAcls: true,
+    BlockPublicPolicy: true,
+    IgnorePublicAcls: true,
+    RestrictPublicBuckets: true,
+  }),
 });
-`,
-    });
+
+export const appBucketPolicy = new S3BucketPolicy({
+  Bucket: Ref(appBucket),
+  PolicyDocument: {
+    Version: "2012-10-17",
+    Statement: [
+      {
+        Effect: "Deny",
+        Principal: "*",
+        Action: "s3:*",
+        Resource: [appBucket.Arn],
+        Condition: { Bool: { "aws:SecureTransport": "false" } },
+      },
+    ],
+  },
+});
+`;
+
+  test("a clean example builds", async () => {
+    writeLexiconDirWithExample(dir, "clean", { "bucket.ts": cleanBucketSource });
 
     const results = await checkExamplesBuild(dir);
     const clean = results.find((r) => r.example === "clean");
@@ -75,6 +103,44 @@ export const dataBucket = new Bucket({
     expect(broken?.detail).toMatch(/Duplicate export name "dataBucket" found/);
   });
 
+  // chant #1400 — a bare bucket serializes fine, which is all #1067 asked,
+  // but fails the aws lexicon's own WAW018/WAW042 at error severity. This is
+  // the exact shape lambda-api and lambda-s3 shipped in.
+  test("an example that fails its own lexicon's post-synth checks at error severity fails (#1400)", async () => {
+    writeLexiconDirWithExample(dir, "insecure", {
+      "bucket.ts": `import { Bucket } from "@intentius/chant-lexicon-aws";
+
+export const plainBucket = new Bucket({
+  BucketName: "plain-bucket",
+});
+`,
+    });
+
+    const results = await checkExamplesBuild(dir);
+    const insecure = results.find((r) => r.example === "insecure");
+    expect(insecure?.ok).toBe(false);
+    expect(insecure?.detail).toMatch(/post-synth error\(s\) from the lexicon's own checks/);
+    expect(insecure?.detail).toMatch(/WAW042: \[plainBucket\]/);
+  });
+
+  test("an example's own lint.rules severity config applies to post-synth checks (#1400)", async () => {
+    writeLexiconDirWithExample(dir, "suppressed", {
+      "bucket.ts": `import { Bucket } from "@intentius/chant-lexicon-aws";
+
+export const plainBucket = new Bucket({
+  BucketName: "plain-bucket",
+});
+`,
+    });
+    writeFileSync(
+      join(dir, "examples", "suppressed", "chant.config.json"),
+      JSON.stringify({ lint: { rules: { WAW018: "warning", WAW042: "off" } } }),
+    );
+
+    const results = await checkExamplesBuild(dir);
+    expect(results.find((r) => r.example === "suppressed")).toMatchObject({ ok: true });
+  });
+
   test("an empty src/ directory is skipped, not reported as a failure", async () => {
     writeLexiconDirWithExample(dir, "empty", {});
     const results = await checkExamplesBuild(dir);

package/src/cli/commands/check-lexicon-examples.ts

@@ -1,5 +1,6 @@
 /**
- * "Every shipped example builds" (chant #1067).
+ * "Every shipped example builds" (chant #1067) and "every shipped example
+ * passes its own lexicon's post-synth checks" (chant #1400).
  *
  * `check-lexicon.ts`'s existing example checks only count directories
  * ("At least 1 example", "At least 3 examples", "At least 5 examples with
@@ -12,28 +13,29 @@
  * pipeline `chant build` runs and report whether it produced output with no
  * structural error.
  *
- * Scope, deliberately: "builds" here means discovery + serialization
- * succeed (no `DiscoveryError`/`BuildError`, real output produced) — the
- * same thing a `Duplicate export name` failure blocks. It does not
- * additionally require the output to pass every post-synth/lint check
- * (WAW0xx and friends). Those are a separate, already-gated contract
- * (`chant lint`, the post-synth pipeline) with their own severity model and
- * their own CI step; several existing AWS examples (docs-snippets,
- * lambda-api, lambda-s3, shared-alb) currently fail one or more post-synth
- * checks for reasons unrelated to this issue (e.g. WAW042, a TLS-only
- * bucket policy check added after those examples were written). Folding
- * that axis into "does it build" would fail this new check for all of them
- * on its very first run, for defects this issue never set out to fix.
- * Tracked separately; not silently absorbed here.
+ * #1067 scoped "builds" to discovery + serialization on purpose, and said
+ * so here: three aws examples (lambda-api, lambda-s3, shared-alb) failed
+ * WAW042/WAW054 at error severity at the time, for defects that issue never
+ * set out to fix. #1400 fixed those three and added the second axis: after
+ * serialization, the post-synth checks each loaded plugin ships run against
+ * that plugin's own output, exactly as `chant build` runs them (scoped per
+ * plugin, `lint.rules` from the example's chant.config applied), and any
+ * diagnostic left at `error` severity fails the example. Warnings do not.
+ * An example is what a user copies wholesale; it must not teach a pattern
+ * the lexicon it demonstrates flags as an error.
  */
 
 import { existsSync, readdirSync } from "fs";
 import { join } from "path";
-import { build } from "../../build";
+import { build, type BuildResult } from "../../build";
 import { findInfraFiles } from "../../discovery/files";
 import { detectLexicons } from "../../detectLexicon";
 import { loadChantConfig } from "../../config";
 import { loadPlugins } from "../plugins";
+import { runPostSynthChecks, type PostSynthDiagnostic } from "../../lint/post-synth";
+import { applyConfiguredSeverity } from "../../lint/config";
+import type { LexiconPlugin } from "../../lexicon";
+import type { SerializerResult } from "../../serializer";
 
 export interface ExampleBuildResult {
   example: string;
@@ -41,6 +43,43 @@ export interface ExampleBuildResult {
   detail?: string;
 }
 
+/**
+ * Run each plugin's own post-synth checks against that plugin's output —
+ * the same per-plugin scoping and `lint.rules` severity resolution
+ * `cli/commands/build.ts` applies — and return what is left at `error`
+ * severity. Project `lint.policies` are not run here: those are the
+ * example author's organizational policy, not the lexicon's contract.
+ */
+export function postSynthErrors(
+  plugins: LexiconPlugin[],
+  result: BuildResult,
+  lintRules: Parameters<typeof applyConfiguredSeverity>[1],
+): PostSynthDiagnostic[] {
+  const errors: PostSynthDiagnostic[] = [];
+  for (const plugin of plugins) {
+    if (!plugin.postSynthChecks) continue;
+    const checks = plugin.postSynthChecks();
+    if (checks.length === 0) continue;
+
+    const outputKey = plugin.serializer.name;
+    const scopedOutputs = new Map<string, string | SerializerResult>();
+    const pluginOutput = result.outputs.get(outputKey);
+    if (pluginOutput !== undefined) scopedOutputs.set(outputKey, pluginOutput);
+
+    const diags = runPostSynthChecks(checks, { ...result, outputs: scopedOutputs });
+    const { diagnostics } = applyConfiguredSeverity(diags, lintRules);
+    for (const diag of diagnostics) {
+      if (diag.severity === "error") errors.push(diag);
+    }
+  }
+  return errors;
+}
+
+function formatPostSynthError(diag: PostSynthDiagnostic): string {
+  const prefix = diag.entity ? `[${diag.entity}] ` : "";
+  return `${diag.checkId}: ${prefix}${diag.message}`;
+}
+
 /**
  * Build every non-empty example under `<lexiconDir>/examples/*\/src` and
  * report per-example pass/fail. Returns `[]` when the lexicon has no
@@ -94,7 +133,15 @@ export async function checkExamplesBuild(lexiconDir: string): Promise<ExampleBui
 
       const structuralErrors = result.errors.map((e) => e.message);
       const producedOutput = result.outputs.size > 0;
-      const ok = structuralErrors.length === 0 && producedOutput;
+      const structurallyOk = structuralErrors.length === 0 && producedOutput;
+
+      // #1400 — only once the build is structurally sound. A discovery error
+      // already explains the failure, and partial output is not the output
+      // the checks are meant to see.
+      const postSynth = structurallyOk
+        ? postSynthErrors(plugins, result, exampleConfig.lint?.rules)
+        : [];
+      const ok = structurallyOk && postSynth.length === 0;
 
       results.push({
         example: entry.name,
@@ -103,7 +150,9 @@ export async function checkExamplesBuild(lexiconDir: string): Promise<ExampleBui
           ? undefined
           : structuralErrors.length > 0
             ? structuralErrors.join("; ")
-            : "discovered source but produced no output",
+            : !producedOutput
+              ? "discovered source but produced no output"
+              : `post-synth error(s) from the lexicon's own checks: ${postSynth.map(formatPostSynthError).join("; ")}`,
       });
     } catch (err) {
       results.push({

package/src/cli/commands/check-lexicon.test.ts

@@ -1,7 +1,9 @@
 import { describe, test, expect } from "vitest";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { checkLexicon } from "./check-lexicon";
+import { checkLexicon, coverageReportCheck } from "./check-lexicon";
+import { loadLexiconFromDir } from "./check-lexicon-plugin";
+import type { LexiconPlugin } from "../../lexicon";
 
 // chant #1067 — check-lexicon.ts had zero tests before this issue, despite
 // being the tool meant to gate every lexicon's completeness. This locks in
@@ -17,7 +19,7 @@ describe("checkLexicon", () => {
   test("includes the new #1067 tier-1 checks by name", async () => {
     const result = await checkLexicon(gitlabDir);
     const names = result.items.map((i) => i.name);
-    expect(names).toContain("Every shipped example builds");
+    expect(names).toContain("Every shipped example builds and passes its own post-synth checks");
     expect(names).toContain("Registered intrinsics are exported by the package");
     expect(names).toContain("Registered intrinsics' isTag matches how they're authored");
     expect(names).toContain("dist/manifest.json declares a chantVersion");
@@ -32,3 +34,45 @@ describe("checkLexicon", () => {
     expect(matches?.pass).toBe(true);
   });
 });
+
+// chant #1330 — fountain's spec-coverage gate lived only in its own
+// coverage.test.ts, a convention rather than a check-lexicon contract. These
+// lock in the tier-1 check over the plugin's coverageReport() member: red on
+// an unaccounted kind, vacuous pass without the member, red on a throw, and
+// green against the real fountain lexicon in this repo.
+describe("coverageReportCheck", () => {
+  test("fails when the report leaves a kind unaccounted", async () => {
+    const plugin = {
+      coverageReport: async () => ({ unaccountedKinds: ["SandboxRequest"] }),
+    } as unknown as LexiconPlugin;
+    const item = await coverageReportCheck(plugin);
+    expect(item.tier).toBe(1);
+    expect(item.pass).toBe(false);
+    expect(item.detail).toContain("SandboxRequest");
+  });
+
+  test("passes vacuously when the plugin has no coverageReport", async () => {
+    const item = await coverageReportCheck({} as LexiconPlugin);
+    expect(item.pass).toBe(true);
+    expect(item.detail).toBeUndefined();
+  });
+
+  test("fails when the report throws", async () => {
+    const plugin = {
+      coverageReport: async () => {
+        throw new Error("snapshot missing");
+      },
+    } as unknown as LexiconPlugin;
+    const item = await coverageReportCheck(plugin);
+    expect(item.pass).toBe(false);
+    expect(item.detail).toContain("snapshot missing");
+  });
+
+  test("is green on the current fountain lexicon", async () => {
+    const loaded = await loadLexiconFromDir(join(repoRoot, "lexicons", "fountain"));
+    expect(loaded.plugin).toBeDefined();
+    const item = await coverageReportCheck(loaded.plugin);
+    expect(item.pass).toBe(true);
+    expect(item.detail).toBe("all spec kinds accounted for");
+  });
+});

package/src/cli/commands/check-lexicon.ts

@@ -2,10 +2,11 @@ import { existsSync, readdirSync, readFileSync } from "fs";
 import { join, basename } from "path";
 import { auditIntrinsics } from "./check-lexicon-intrinsics";
 import { checkExamplesBuild } from "./check-lexicon-examples";
-import { auditDocsReachability } from "./check-lexicon-docs";
+import { auditDocsClassification, auditDocsReachability } from "./check-lexicon-docs";
 import { auditMcpNames, lexiconNameFor } from "./check-lexicon-mcp";
 import { loadLexiconFromDir, registers, safeList } from "./check-lexicon-plugin";
 import { RULE_CATALOG } from "../../audit/catalog";
+import type { LexiconPlugin } from "../../lexicon";
 
 // ── Types ────────────────────────────────────────────────────────────
 
@@ -66,6 +67,45 @@ function countSubdirs(dir: string): number {
     .length;
 }
 
+/**
+ * #1330 — gate on the plugin's own spec-coverage accounting.
+ *
+ * fountain's `coverage.test.ts` asserts `unaccountedKinds == []` in CI, but a
+ * lexicon-local test is a convention, not a check-lexicon contract — the same
+ * class of gap #1342 closed for LSP providers. `coverageReport()` gives core
+ * the one fact to gate on: which upstream spec kinds are neither modeled nor
+ * on the lexicon's exclusion list. A lexicon without the member passes
+ * vacuously, the same conditional shape as the docs-reachability and
+ * Diátaxis checks; a report that throws fails, for the same reason `safeList`
+ * treats a throw as worse than absence.
+ */
+export async function coverageReportCheck(plugin: LexiconPlugin | undefined): Promise<CheckItem> {
+  const report = plugin?.coverageReport;
+  const hasReport = typeof report === "function";
+  let unaccounted: string[] = [];
+  let error: string | undefined;
+  if (hasReport) {
+    try {
+      unaccounted = (await report.call(plugin))?.unaccountedKinds ?? [];
+    } catch (e) {
+      error = e instanceof Error ? e.message : String(e);
+    }
+  }
+  return {
+    name: "coverageReport() leaves no spec kind unaccounted",
+    tier: 1,
+    pass: !hasReport || (error === undefined && unaccounted.length === 0),
+    detail:
+      error !== undefined
+        ? `threw: ${error}`
+        : unaccounted.length > 0
+          ? `${unaccounted.length} unaccounted: ${unaccounted.join(", ")}`
+          : hasReport
+            ? "all spec kinds accounted for"
+            : undefined,
+  };
+}
+
 // ── Check runner ─────────────────────────────────────────────────────
 
 /**
@@ -254,12 +294,14 @@ export async function checkLexicon(dir: string): Promise<CheckResult> {
   // checks only ever counted example directories; none tried to build one,
   // so `lexicons/aws/examples/core-concepts` shipped with a discovery-time
   // "Duplicate export name" error while this tool reported "All tier-1
-  // checks passed." See ./check-lexicon-examples.ts for exactly what
-  // "builds" means here (discovery + serialization, not post-synth/lint).
+  // checks passed." chant #1400 — and the built output must pass the
+  // lexicon's own post-synth checks at error severity; three aws examples
+  // taught patterns (no TLS-only bucket policy, mutable ECR tags) the
+  // lexicon flags as errors. See ./check-lexicon-examples.ts.
   const exampleBuilds = await checkExamplesBuild(dir);
   const brokenExamples = exampleBuilds.filter((e) => !e.ok);
   items.push({
-    name: "Every shipped example builds",
+    name: "Every shipped example builds and passes its own post-synth checks",
     tier: 1,
     pass: brokenExamples.length === 0,
     detail:
@@ -374,6 +416,24 @@ export async function checkLexicon(dir: string): Promise<CheckResult> {
         : undefined,
   });
 
+  // Authored pages name their Diátaxis quadrant; the sidebar is built from
+  // it, so an untagged page cannot be placed (#1731).
+  const docsClass = auditDocsClassification(dir);
+  items.push({
+    name: "Every authored doc page has a diataxis quadrant",
+    tier: 1,
+    pass: !docsClass.hasPages || docsClass.unclassified.length === 0,
+    detail:
+      docsClass.unclassified.length > 0
+        ? `${docsClass.unclassified.length} unclassified: ${docsClass.unclassified.join(", ")}`
+        : undefined,
+  });
+
+  // #1330 — fountain's spec-coverage gate lived in a lexicon-local vitest
+  // assertion, a convention rather than a check-lexicon contract. The plugin
+  // now states the fact directly via `coverageReport()`.
+  items.push(await coverageReportCheck(plugin));
+
   // ── Tier 2: Recommended ────────────────────────────────────────
 
   const pluginContent = readOr(join(dir, "src/plugin.ts"));

package/src/cli/commands/init-lexicon/templates/codegen.ts

@@ -67,7 +67,8 @@ export async function generate(options?: { verbose?: boolean; force?: boolean })
  * Write generated files to the package directory.
  */
 export function writeGeneratedFiles(result: GenerateResult, pkgDir?: string): void {
-  const dir = pkgDir ?? dirname(dirname(fileURLToPath(import.meta.url)));
+  // This file lives in src/codegen/, so the package root is three levels up.
+  const dir = pkgDir ?? dirname(dirname(dirname(fileURLToPath(import.meta.url))));
   writeGeneratedArtifacts({
     baseDir: dir,
     files: {
@@ -86,7 +87,9 @@ import { generate, writeGeneratedFiles } from "./generate";
 import { dirname } from "path";
 import { fileURLToPath } from "url";
 
-const pkgDir = dirname(dirname(fileURLToPath(import.meta.url)));
+// src/codegen/generate-cli.ts -> src/codegen -> src -> package root.
+// Two dirnames land in src/ and the first generate writes src/src/generated/ (#1614).
+const pkgDir = dirname(dirname(dirname(fileURLToPath(import.meta.url))));
 const result = await generate({ verbose: true });
 writeGeneratedFiles(result, pkgDir);
 `;

package/src/cli/commands/init-lexicon/templates/docs.ts

@@ -57,16 +57,49 @@ export default defineConfig({
 }
 
 export function generateDocsContentConfig(): string {
-  return `import { defineCollection } from 'astro:content';
+  return `import { defineCollection, z } from 'astro:content';
 import { docsLoader } from '@astrojs/starlight/loaders';
 import { docsSchema } from '@astrojs/starlight/schema';
 
 export const collections = {
-  docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }),
+  docs: defineCollection({
+    loader: docsLoader(),
+    schema: docsSchema({
+      extend: z.object({
+        // Diátaxis quadrant (https://diataxis.fr), chant #1731.
+        diataxis: z.enum(['tutorial', 'how-to', 'reference', 'explanation']).optional(),
+      }),
+    }),
+  }),
 };
 `;
 }
 
+/**
+ * First authored page. Lives under docs/pages/; the docs pipeline copies it
+ * into src/content/docs/ and builds the sidebar from its `diataxis` field.
+ */
+export function generateDocsGettingStartedMdx(name: string): string {
+  const displayName = name.charAt(0).toUpperCase() + name.slice(1);
+  return `---
+title: Getting Started
+description: First project with the ${displayName} lexicon
+diataxis: tutorial
+---
+
+Install the lexicon, declare one resource, and build it.
+
+\`\`\`bash
+npm install --save-dev @intentius/chant-lexicon-${name}
+chant build
+\`\`\`
+
+Replace this with a walkthrough a new user can follow start to finish. Other
+pages go beside this file in \`docs/pages/\`, each with a \`diataxis\` field
+(\`tutorial\`, \`how-to\`, \`reference\` or \`explanation\`).
+`;
+}
+
 export function generateDocsIndexMdx(name: string): string {
   const displayName = name.charAt(0).toUpperCase() + name.slice(1);
   return `---