@@ -0,0 +1,151 @@
+/**
+ * The architecture lint (bun run lint:arch): the imports between the layers
+ * of src/ are exactly the edges architecture.yml declares - an undeclared
+ * edge and a stale allowance both fail. gen-docs.ts renders the same
+ * declaration as the module map. dependency-cruiser was the intended tool but
+ * cannot cruise this repository: it needs the TypeScript compiler API, which
+ * the pinned typescript 7 no longer ships, so it resolves nothing.
+ *
+ * An edge is any way one file names another: the runtime loads the
+ * changed-sections scanner reads, plus type-only imports, re-exports, and
+ * `import("./x.js").T` and `import X = require("./x.js")` in type positions.
+ */
+
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { type Node, parseSync } from "oxc-parser";
+import { parse as parseYaml } from "yaml";
+import { resolveImport, scanImports } from "./changed-sections.js";
+
+export const ARCHITECTURE_PATH = "architecture.yml";
+
+export interface Architecture {
+  /** layer -> the src/ paths it owns (a `/` suffix means a directory). */
+  readonly layers: Readonly<Record<string, readonly string[]>>;
+  readonly exclude: readonly string[];
+  /** from -> the layers it may import. */
+  readonly edges: Readonly<Record<string, readonly string[]>>;
+}
+
+export function readArchitecture(root: string): Architecture {
+  return parseYaml(readFileSync(join(root, ARCHITECTURE_PATH), "utf8")) as Architecture;
+}
+
+/** The layer owning a repo-relative path, or undefined. */
+function layerOf(arch: Architecture, path: string): string | undefined {
+  return Object.entries(arch.layers).find(([, paths]) =>
+    paths.some((owned) => (owned.endsWith("/") ? path.startsWith(owned) : path === owned)),
+  )?.[0];
+}
+
+function* nodesOf(value: unknown): Generator<Node> {
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      yield* nodesOf(item);
+    }
+  } else if (typeof value === "object" && value !== null) {
+    if ("type" in value && typeof value.type === "string") {
+      yield value as Node;
+    }
+    for (const child of Object.values(value)) {
+      yield* nodesOf(child);
+    }
+  }
+}
+
+/** Every relative specifier `text` names, runtime and type-level alike. */
+export function importSpecifiers(text: string, file: string): string[] {
+  const { program, module } = parseSync(file, text);
+  const typeLevel = [...nodesOf(program)].flatMap((node) => {
+    const source =
+      node.type === "TSImportType"
+        ? node.source
+        : node.type === "TSExternalModuleReference"
+          ? node.expression
+          : undefined;
+    return source?.type === "Literal" && typeof source.value === "string" ? [source.value] : [];
+  });
+  const all = new Set([
+    ...scanImports(text, file),
+    ...module.staticImports.map((entry) => entry.moduleRequest.value),
+    ...module.staticExports.flatMap((entry) =>
+      entry.entries.flatMap((item) => (item.moduleRequest ? [item.moduleRequest.value] : [])),
+    ),
+    ...typeLevel,
+  ]);
+  return [...all].filter((specifier) => /^\.\.?\//.test(specifier));
+}
+
+/**
+ * The lint verdict for `root`: an import between layers the declaration lacks
+ * (naming both files), a declared edge no file draws, or a cruised file outside
+ * every layer. Empty means the declaration is exactly the tree.
+ */
+export function lintArchitecture(root: string, arch = readArchitecture(root)): string[] {
+  const excluded = arch.exclude.map((pattern) => new Bun.Glob(pattern));
+  const drawn = new Map<string, string[]>();
+  const problems: string[] = [];
+  for (const entry of readdirSync(join(root, "src"), { recursive: true, encoding: "utf8" })) {
+    const file = join("src", entry);
+    if (!file.endsWith(".ts") || excluded.some((glob) => glob.match(file))) {
+      continue;
+    }
+    const from = layerOf(arch, file);
+    if (from === undefined) {
+      problems.push(`${file} belongs to no layer in ${ARCHITECTURE_PATH}`);
+      continue;
+    }
+    const absolute = join(root, file);
+    for (const specifier of importSpecifiers(readFileSync(absolute, "utf8"), absolute)) {
+      const target = relative(root, resolveImport(absolute, specifier));
+      const to = layerOf(arch, target);
+      if (to === undefined) {
+        problems.push(
+          `${target} (imported by ${file}) belongs to no layer in ${ARCHITECTURE_PATH}`,
+        );
+      } else if (to !== from) {
+        const key = `${from} -> ${to}`;
+        drawn.set(key, [...(drawn.get(key) ?? []), `${file} -> ${target}`]);
+      }
+    }
+  }
+  const declared = new Set(
+    Object.entries(arch.edges).flatMap(([from, targets]) =>
+      targets.map((to) => `${from} -> ${to}`),
+    ),
+  );
+  for (const [key, sites] of [...drawn].sort()) {
+    if (!declared.has(key)) {
+      problems.push(`forbidden import ${key}: ${sites.join(", ")}; move it or declare the edge`);
+    }
+  }
+  for (const key of [...declared].sort()) {
+    if (!drawn.has(key)) {
+      problems.push(
+        `stale allowance ${key}: no file draws it; remove it from ${ARCHITECTURE_PATH}`,
+      );
+    }
+  }
+  return problems;
+}
+
+/** The module map over the DECLARED edges; a hyphen in a layer name is edge syntax to mermaid. */
+export function renderArchitectureMermaid(arch: Architecture): string {
+  const id = (layer: string): string => layer.replace(/-/g, "_");
+  return [
+    "graph TD",
+    ...Object.entries(arch.layers).map(([name, paths]) => `  ${id(name)}["${paths.join("<br>")}"]`),
+    ...Object.entries(arch.edges).flatMap(([from, targets]) =>
+      targets.map((to) => `  ${id(from)} --> ${id(to)}`),
+    ),
+  ].join("\n");
+}
+
+if (import.meta.main) {
+  const problems = lintArchitecture(join(import.meta.dir, "..", ".."));
+  if (problems.length > 0) {
+    console.error(`lint:arch: ${problems.length} problem(s)\n  ${problems.join("\n  ")}`);
+    process.exit(1);
+  }
+  console.log(`lint:arch: src/ imports match ${ARCHITECTURE_PATH}`);
+}
@@ -154,13 +154,13 @@ function assertNoComputedImports(text: string, file: string): void {
   const [error] = errors;
   if (error) {
     throw new Error(
-      `changed-sections: ${file}:${lineOf(error.labels[0]?.start ?? 0)} does not parse: ${error.message}`,
+      `${file}:${lineOf(error.labels[0]?.start ?? 0)} does not parse: ${error.message}`,
     );
   }
   for (const node of nodesOf(program)) {
     if (isComputedModuleLoad(node)) {
       throw new Error(
-        `changed-sections: ${file}:${lineOf(node.start)} loads a module through a computed specifier, which the import graph cannot follow - use a string literal`,
+        `${file}:${lineOf(node.start)} loads a module through a computed specifier, which the import graph cannot follow - use a string literal`,
       );
     }
   }
@@ -169,7 +169,9 @@ function assertNoComputedImports(text: string, file: string): void {
 /**
  * The relative specifiers `file` loads at runtime. Type-only imports are not
  * edges (erased from the bundle) and neither are bare specifiers; a
- * computed specifier throws rather than dropping an edge.
+ * computed specifier throws rather than dropping an edge. Shared with
+ * arch-lint.ts, as is resolveImport, so their errors name the file and not
+ * this tool.
  */
 export function scanImports(text: string, file: string): string[] {
   assertNoComputedImports(text, file);
@@ -194,7 +196,7 @@ export function resolveImport(importer: string, specifier: string): string {
     }
   }
   throw new Error(
-    `changed-sections: ${importer} imports "${specifier}", which resolves to no file (tried ${candidates.join(" and ")})`,
+    `${importer} imports "${specifier}", which resolves to no file (tried ${candidates.join(" and ")})`,
   );
 }
 
 
@@ -1,10 +1,11 @@
-// Emits the generated regions of COVERAGE.md, the sections and inputs reference pages, and the two
-// pages carrying the token-form link (README.md and the getting-started guide), each between
-// `<!-- BEGIN/END GENERATED: <name> -->` markers (build:docs): the Sections table, the `result`
-// list, the token-form link definition, and COVERAGE's whole body. Authored prose from the docs
-// registry + coverage-data.
+// Emits the generated regions of COVERAGE.md, the sections, inputs, and architecture reference
+// pages, and the two pages carrying the token-form link (README.md and the getting-started
+// guide), each between `<!-- BEGIN/END GENERATED: <name> -->` markers (build:docs): the Sections
+// table, the `result` list, the token-form link definition, COVERAGE's whole body, and the module
+// map rendered from architecture.yml. Authored prose from the docs registry + coverage-data.
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { MERGE_RESULT } from "../../src/action/deliver.js";
 import { REPO_RESULTS, type RepoResult } from "../../src/engine/orchestrate.js";
 import type { SectionDocs } from "../../src/sections/contract/docs.js";
 import {
@@ -17,6 +18,7 @@ import { RESOURCE_SLUGS } from "../../src/sections/contract/permissions.js";
 import { DOCS } from "../../src/sections/docs-registry.js";
 import { SECTIONS } from "../../src/sections/registry.js";
 import type { UndeclaredPolicy } from "../../src/types.js";
+import { readArchitecture, renderArchitectureMermaid } from "./arch-lint.js";
 import { COVERAGE_DATA, type CoverageData } from "./coverage-data.js";
 import {
   escapeRe,
@@ -114,7 +116,7 @@ const TABLE_HEADER =
 /** The Sections table, one row per section in the given order; a section without docs throws. */
 export function renderSectionsTable(
   sections: readonly SectionsTableRow[],
-  docs: Readonly<Record<string, Pick<SectionDocs, "readme">>>,
+  docs: Readonly<Record<string, Pick<SectionDocs, "sections_table">>>,
 ): string {
   const rows = sections.map((section) => {
     const doc = docs[section.key];
@@ -123,10 +125,10 @@ export function renderSectionsTable(
     }
     return [
       `\`${section.key}\``,
-      cell(doc.readme.endpoints, `the ${section.key} Endpoints cell`),
+      cell(doc.sections_table.endpoints, `the ${section.key} Endpoints cell`),
       cell(renderPatCell(sectionGrant(section)), `the ${section.key} PAT permission cell`),
       UNDECLARED_DEFAULT_DISPLAY[section.undeclaredDefault],
-      cell(doc.readme.notes, `the ${section.key} Notes cell`),
+      cell(doc.sections_table.notes, `the ${section.key} Notes cell`),
     ];
   });
   return [TABLE_HEADER, ...rows.map((cells) => `| ${cells.join(" | ")} |`)].join("\n");
@@ -255,8 +257,10 @@ const RESULT_DISPLAY: Record<RepoResult, "any mode" | "multi-repo only"> = {
 /** The outputs enumeration's fixed phrases, as rendered and as the region shape expects them. */
 const WORST_OF = "; worst-of across targets in multi-repo mode";
 const CAN_ALSO_APPEAR = " can also appear";
+/** The merge-mode result, a value outside RepoResult, closes the enumeration. */
+const MERGE_ONLY = `; \`${MERGE_RESULT}\` in mode: merge`;
 
-/** The `result` output's value enumeration: the any-mode values, then the multi-repo-only ones. */
+/** The `result` output's value enumeration: the any-mode values, the multi-repo-only ones, then the merge result. */
 export function renderOutputsList(results: readonly RepoResult[]): string {
   const ordered = (Object.keys(RESULT_DISPLAY) as RepoResult[]).filter((value) =>
     results.includes(value),
@@ -267,9 +271,9 @@ export function renderOutputsList(results: readonly RepoResult[]): string {
     .filter((value) => RESULT_DISPLAY[value] === "multi-repo only")
     .map(code);
   const lead = `${anyMode.join(" / ")}${WORST_OF}`;
-  return multiOnly.length === 0
-    ? lead
-    : `${lead}, where ${multiOnly.join(" and ")}${CAN_ALSO_APPEAR}`;
+  const withMulti =
+    multiOnly.length === 0 ? lead : `${lead}, where ${multiOnly.join(" and ")}${CAN_ALSO_APPEAR}`;
+  return `${withMulti}${MERGE_ONLY}`;
 }
 
 /** A section operation tagged with its section, as patFormParameters reads it. */
@@ -358,7 +362,7 @@ function outputsListRegion(name: string, heading: string): GeneratedRegion {
     name,
     placement: { kind: "under-heading", heading },
     body: new RegExp(
-      String.raw`^(?:\x60[a-z]+\x60(?: / \x60[a-z]+\x60)*${escapeRe(WORST_OF)}(?:, where \x60[a-z]+\x60(?: and \x60[a-z]+\x60)*${escapeRe(CAN_ALSO_APPEAR)})?)?$`,
+      String.raw`^(?:\x60[a-z]+\x60(?: / \x60[a-z]+\x60)*${escapeRe(WORST_OF)}(?:, where \x60[a-z]+\x60(?: and \x60[a-z]+\x60)*${escapeRe(CAN_ALSO_APPEAR)})?(?:${escapeRe(MERGE_ONLY)})?)?$`,
     ),
     render: () => renderOutputsList(REPO_RESULTS),
   };
@@ -374,13 +378,28 @@ function patUrlRegion(name: string): GeneratedRegion {
   };
 }
 
+// The module map: a mermaid fence rendered from architecture.yml's layers and edges (the lint
+// keeps that declaration equal to the tree), as region `name` under `heading`.
+function architectureMapRegion(name: string, heading: string): GeneratedRegion {
+  return {
+    name,
+    placement: { kind: "under-heading", heading },
+    body: /^\n(?:\x60{3}mermaid\n(?:[^\x60\n][^\n]*\n)*\x60{3}\n)?$/,
+    render: () =>
+      `\n\x60\x60\x60mermaid\n${renderArchitectureMermaid(readArchitecture(ROOT))}\n\x60\x60\x60\n`,
+  };
+}
+
 // Every page this generator writes besides COVERAGE.md, keyed by path: the reference tables in
 // their homes, and the token-form link definition closing the README and the getting-started guide.
 export const PAGE_REGIONS: Readonly<Record<string, readonly GeneratedRegion[]>> = {
   "README.md": [patUrlRegion("readme-pat-url")],
   "docs/start/getting-started.md": [patUrlRegion("pat-url")],
   "docs/reference/sections.md": [sectionsTableRegion("sections-table", "# Sections")],
   "docs/reference/inputs.md": [outputsListRegion("outputs-list", "## Outputs")],
+  "docs/reference/architecture.md": [
+    architectureMapRegion("architecture-map", "## The module map"),
+  ],
 };
 
 // The page at `path` with its regions checked for placement, then regenerated. The result must
 
@@ -26,6 +26,8 @@ jobs:
       - uses: ./.github/actions/fetch-test-artifacts
       - name: Lint (biome)
         run: bun run lint
+      - name: Lint (architecture)
+        run: bun run lint:arch
       - name: Typecheck
         run: bun run typecheck
       - name: Dead code (knip)
 
@@ -35,6 +35,7 @@ GitHub Settings as Code: GitHub Action applying declarative repository settings:
 <!-- END REPO-PLATFORM MANAGED -->
 
 - `lib/settings.schema.json` is the COMMITTED JSON Schema for settings.yml, generated from the zod slices in `src/sections/<key>/schema.ts` as composed into the settings document by `src/schema.ts`. Each slice is ONE declaration that produces its config type (z.infer), the section's tolerant runtime shape (the section module derives `loosen(<slice>)` itself; the factory-minted families - secrets, variables, the two setup sections, and the list sections on `listSection` - get it from their shared factory in `src/sections/shared/`, which does that derivation once), and its part of the published schema (`.meta({id})` names its definitions; the descriptions come from the `schema:` map in the section's `<key>.docs.yml`, keyed `Definition.field`, which the generator attaches and fails on when a site or a key is unmatched); `src/schema.ts` adds only the document-level wrappers and pins each property to its slice with a lockstep type. Regenerate the schema with `bun run build:schema` after a schema-affecting `src/` change - CI's schema-check job fails when it drifts. `lib/index.js`, the bundled entrypoint the action runs (node24), is NOT committed on main: every workflow that executes the action builds it first (`bun run build:bundle`), the e2e runner builds it to a temp path, and a release builds and commits it on a packaged child of the release commit, which is what every `vX.Y.Z` tag and the moving major point at (main itself stays source-only). `lib/` is exempt from the typography check (third-party unicode in the bundle; the schema descriptions are checked at source) and excluded from [biome](https://biomejs.dev).
+- The import layering of `src/` is declared in `architecture.yml` and enforced by `bun run lint:arch`, so a new cross-layer import is a deliberate edit to that file; the module map in `docs/reference/architecture.md` is generated from it.
 - The apply/check engine layout: `src/main.ts` is the thin bundled entrypoint; `src/io.ts` is the Io output port (action-layer-free; the action implements it over @actions/core); `src/types.ts` holds the leaf type vocabulary; `src/action/` is the GitHub Actions layer (inputs, settings reading, step summaries, redaction, the single- and multi-repo run flows); `src/engine/` is the per-repo pipeline (orchestrate, validate, merge, diff); `src/github/` is the REST client, pagination, and repo-file fetch; `src/discovery/` resolves multi-repo targets; `src/report/` composes the private report. Under `src/sections/`, each settings section is one self-contained DIRECTORY `src/sections/<key>/`: `index.ts` (the `SectionModule` - key, PAT grant advice, the loose shape derived from the slice, handler), `schema.ts` (the zod slice), `mock.ts` (the e2e mock fragment), `generators.ts` (the fuzz fragment; the secret and variable factory families share theirs in `test/e2e/generators.ts` instead), `<key>.test.ts` (absent where a shared factory's suite under `test/sections/` covers the section), and `scenarios/`. Beside the section directories sit `contract/` (the layered section contract: permissions/endpoints/graphql/module/errors/requests/live), `shared/` (the cross-section engines and factories, plus the schema helpers), and `registry.ts` (the single registration point). All GitHub API list calls must go through `listAll()` (bare-array endpoints) or `listAllEnveloped()` (endpoints that wrap the list in a `{total_count, <key>: []}` envelope), both backed by the single page loop in `src/github/paginate.ts`; errors through `call()`/`throwFor()` so the permission policy (`on-missing-permission`, `required-sections`) works.
 - Adding a section: create `src/sections/<key>/` with the six pieces above plus its `<key>.docs.yml` (the Sections table cells for docs/reference/sections.md, the COVERAGE.md prose, and the schema descriptions the generators render; the docs loader fails without it), compose the `SettingsFile` property from the slice and add the key to `SECTION_KEYS` in `src/schema.ts`, and add one line in `src/sections/registry.ts` - the compiler flags each forgotten step (the registry's mapped type, the mock fragment registration, the slice composition pin, and the generator aggregation are all keyed by SectionKey).
 - Adding a section endpoint: declare it in the section module's `ENDPOINTS`, add the matching handler under its `section.role` key in the section's `mock.ts` (the fragment's handler record is typed over the section's exact key union, so a missing or phantom handler fails to compile, and `assertHandlerCompleteness()` backstops at construction), add a scenario that reaches it (the coverage tripwire fails on a cold route), and regenerate the trimmed spec (`bun .github/scripts/trim-openapi.ts`; the artifact stays gitignored). `USED_PATHS` (in `test/e2e/openapi/paths.ts`) picks the new path up automatically. Core routes the action calls outside the sections (the repo fetch, the settings-file contents read, `repos: "*"` discovery, and the private-report issue channel) are served by a separate core-path handler, and a request that matches no registered section or core route fails loudly.
Original file line number	Diff line number	Diff line change
`@@ -154,13 +154,13 @@ function assertNoComputedImports(text: string, file: string): void {`
`154`	`154`	`const [error] = errors;`
`155`	`155`	`if (error) {`
`156`	`156`	`throw new Error(`
`157`		- `changed-sections: ${file}:${lineOf(error.labels[0]?.start ?? 0)} does not parse: ${error.message}`,
	`157`	+ `${file}:${lineOf(error.labels[0]?.start ?? 0)} does not parse: ${error.message}`,
`158`	`158`	`);`
`159`	`159`	`}`
`160`	`160`	`for (const node of nodesOf(program)) {`
`161`	`161`	`if (isComputedModuleLoad(node)) {`
`162`	`162`	`throw new Error(`
`163`		- `changed-sections: ${file}:${lineOf(node.start)} loads a module through a computed specifier, which the import graph cannot follow - use a string literal`,
	`163`	+ `${file}:${lineOf(node.start)} loads a module through a computed specifier, which the import graph cannot follow - use a string literal`,
`164`	`164`	`);`
`165`	`165`	`}`
`166`	`166`	`}`
`@@ -169,7 +169,9 @@ function assertNoComputedImports(text: string, file: string): void {`
`169`	`169`	`/**`
`170`	`170`	* The relative specifiers `file` loads at runtime. Type-only imports are not
`171`	`171`	`* edges (erased from the bundle) and neither are bare specifiers; a`
`172`		`- * computed specifier throws rather than dropping an edge.`
	`172`	`+ * computed specifier throws rather than dropping an edge. Shared with`
	`173`	`+ * arch-lint.ts, as is resolveImport, so their errors name the file and not`
	`174`	`+ * this tool.`
`173`	`175`	`*/`
`174`	`176`	`export function scanImports(text: string, file: string): string[] {`
`175`	`177`	`assertNoComputedImports(text, file);`
`@@ -194,7 +196,7 @@ export function resolveImport(importer: string, specifier: string): string {`
`194`	`196`	`}`
`195`	`197`	`}`
`196`	`198`	`throw new Error(`
`197`		- `changed-sections: ${importer} imports "${specifier}", which resolves to no file (tried ${candidates.join(" and ")})`,
	`199`	+ `${importer} imports "${specifier}", which resolves to no file (tried ${candidates.join(" and ")})`,
`198`	`200`	`);`
`199`	`201`	`}`
`200`	`202`