@panaversity/ksor 0.0.9 → 0.0.11

package/docs/index.md

@@ -45,8 +45,9 @@ instead of their training memory. The corpus grows with each implemented verb.
 Read the scaffold's own `AGENTS.md` first — it is the working contract.
 Knowledge lives in `knowledge/` and never inside the site; frontmatter uses
 a closed key set (`title` + `status` required); `pnpm check` explains any
-violation and how to fix it. Sidebar order is the governed `order:`
-frontmatter key — never `meta.json` or `sidebar_position`. If the
+violation and how to fix it. Reading order is the governed `order:`
+frontmatter key — never `meta.json` or `sidebar_position` — and it drives
+every surface: the sidebar, `llms.txt`, and the MCP `outline` tool. If the
 instance declares an `audiences:` model, documents may carry a
 `visibility:` key and per-audience builds (`KSOR_AUDIENCE=<tier> pnpm
 build`) stage only what that tier may see — publication, not authorship:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "description": "Knowledge System of Record — compile governed markdown into a static site for people and an MCP server for AI agents, with citations and measured abstention.",
   "keywords": [
     "abstention",

package/templates/scaffold/AGENTS.md

@@ -147,19 +147,20 @@ Stand it up in this order (each step's errors explain how to fix themselves):
    `knowledge/`**: an applied schema reports "already applied", an existing
    grant reports "already granted", and ingest builds a fresh generation.
 
-   **`pnpm serve` is the only command this rung needs.** Run it the first
-   time, run it after editing `knowledge/`, run it to bring the server back —
-   it is always the right answer, so there is nothing to decide. Every step it
-   chains reports the state it found rather than failing: an applied schema
-   says "already applied", an existing grant says "already granted", and
-   unchanged chunks carry forward by content hash, so a rerun on an untouched
-   corpus makes **zero provider calls** (`embedded 0, carried N`).
-
-   A rerun on an unchanged record costs **nothing at all**: ingest compares the
-   corpus it just read against the generation already serving and, when they
-   are identical at the same commit, consumes no generation and writes no rows
-   ("unchanged — generation N already serves this corpus"). Edit a document and
-   the next run builds a generation for it, re-embedding only what changed.
+   **`pnpm refresh` after editing `knowledge/`; `pnpm serve` to bring the
+   server up.** Two commands, and the split is the point: serving must not
+   publish, or a restart, a crash-loop or an autoscaling event each republishes
+   your record. Everything is re-runnable and reports the state it found rather
+   than failing — an applied schema says "already applied", an existing grant
+   says "already granted".
+
+   A refresh on an unchanged record costs **nothing at all**: ingest compares
+   the corpus it just read against the generation already serving and, when
+   they are identical at the same commit, consumes no generation and writes no
+   rows ("unchanged — generation N already serves this corpus"). Edit a
+   document and the next refresh builds a generation for it, re-embedding only
+   what changed and carrying the rest forward by content hash — so an ordinary
+   edit makes a handful of provider calls, not a corpus-worth.
 
    Generations do accumulate as you edit. Reap the superseded ones when you
    think of it, or on a schedule:
@@ -169,10 +170,10 @@ Stand it up in this order (each step's errors explain how to fix themselves):
    ```
 
    The individual verbs (`pnpm schema`, `pnpm grant`, `pnpm ingest`,
-   `pnpm serve`) exist for pipelines and split duties — a deploy step that
-   ingests while a different process serves, or a DBA who holds the credentials
-   that authorize ingest. Reach for them when something else runs the steps;
-   not as a daily choice.
+   `pnpm gc`) are what `provision` and `refresh` are made of. Reach for them
+   when duties are split — a deploy step that ingests while a different process
+   serves, or a DBA who holds the credentials that authorize ingest — not as a
+   daily choice.
 
 4. **Turn the abstention gate on — deliberately, once it serves.** This is the
    step that makes "not in this corpus" a real answer, and it is measured, never
@@ -234,11 +235,14 @@ Two things worth being deliberate about:
 - **Set `KSOR_SSO_ISSUER` when your SSO stamps a stable `iss`.** Audience is
   always enforced against `KSOR_JWT_ALLOWED_AUDIENCES`; naming the issuer adds
   one more check for the cost of one variable.
-- **Set `KSOR_JWKS_URL` unless your SSO is Better Auth.** The signing keys are
-  fetched from `<KSOR_SSO_URL>/api/auth/jwks` by default, which is Better
-  Auth's layout. Auth0, Okta, Entra, Keycloak and Cognito publish theirs
-  elsewhere, and a wrong JWKS URL fails as a transient fetch error — the door
-  boots clean and every request 503s with nothing naming the cause.
+- **The signing keys are DISCOVERED; you rarely set `KSOR_JWKS_URL`.** The door
+  reads your SSO's own metadata document — RFC 8414
+  (`/.well-known/oauth-authorization-server`), then OpenID Discovery
+  (`/.well-known/openid-configuration`) — so Auth0, Okta, Entra, Keycloak,
+  Cognito, Google and Better Auth all work unmodified. The boot report's `keys`
+  line names which document answered and where the keys came from; set
+  `KSOR_JWKS_URL` only to override that, or when your SSO publishes no metadata
+  at all.
 
 ## Withdrawing a document — `ksor takedown`
 
@@ -257,8 +261,12 @@ pnpm exec ksor takedown --instance instance.md --revoke <stable-id>
 The stable id is what a search result reports as `provenance.stable_id` — for
 most documents that is `knowledge/<path-without-.md>`. `--subtree` withdraws a
 section and everything beneath it, including documents added later.
-`--actor NAME` names who performed the act in the ledger; it defaults to the
-operating user.
+`--actor NAME` names who performed the act in the ledger, and a denial or a
+revocation is REFUSED without it. There is no default: a name taken from the
+environment reads like a person and is whatever the shell happened to be
+(`runner` under CI, `root` in a container), which is worse than no name at all
+in the one row that exists to record who did this. Read-only modes
+(`--list`, `--ledger`, `--export`) need nothing.
 
 **The MCP door stops serving it immediately. The SITE stops at its next
 build** — the site reads a file, not the database, and `pnpm build` refreshes
@@ -328,8 +336,10 @@ Details in README → Deploying.
   takes the position that page declares.
 - Sidebar position is the governed `order:` key: documents that declare it come
   first, ascending; the rest follow in name order.
-- One order drives the sidebar, `llms.txt`, and the home page's first-document
-  link — set it once and every surface agrees.
+- One order drives every surface — the sidebar, `llms.txt`, the home page's
+  first-document link, and the MCP `outline` tool an agent reads to decide what
+  to read first. Set it once and they agree. The door picks up a reorder at the
+  next `pnpm refresh`, which costs no embedding: only the ordering changed.
 - Never `meta.json` or `sidebar_position`: the checker refuses framework files
   in the record, which has to read the same without the site.
 

package/templates/scaffold/README.md

@@ -97,7 +97,7 @@ different coding agent's way of finding the same working contract.
 | `.gitattributes`                 | markdown is checked out byte-stable on every platform, so the same commit hashes the same everywhere.                                                                                                                            |
 | `.env.example`                   | the variables the served rung needs; copy to `.env` (gitignored) and fill in. |
 | `.gitignore`                     | keeps build output, `node_modules/`, and `.env` out of the record's history.                                                                                                                                                    |
-| `package.json`                   | the two surface commands — `pnpm dev` (the site) and `pnpm serve` (the agent surface: schema → grant → ingest → serve) — plus `pnpm build` / `pnpm check`, the pinned `@panaversity/ksor` tool, and the pnpm version this project pins.                                                |
+| `package.json`                   | the surface commands — `pnpm dev` (the site) and `pnpm provision` / `pnpm refresh` / `pnpm serve` (the agent surface: set up once, publish, then serve) — plus `pnpm build` / `pnpm check`, the pinned `@panaversity/ksor` tool, and the pnpm version this project pins.                                                |
 | `pnpm-workspace.yaml`            | where the workspace looks for code (`system/site`, plus reserved `system/gateways/*` and `system/packages/*`), and the supply-chain policy for installs.                                                                         |
 | `pnpm-lock.yaml`                 | the exact dependency versions — the reason two machines build the same site.                                                                                                                                                     |
 

package/templates/scaffold/env.example

@@ -20,11 +20,12 @@ GEMINI_API_KEY=
 #   KSOR_SSO_URL=https://your-sso.example.com
 #   KSOR_MCP_RESOURCE_URL=https://your-host.example.com/mcp
 #   KSOR_JWT_ALLOWED_AUDIENCES=https://your-host.example.com/mcp
-# The JWKS endpoint defaults to <KSOR_SSO_URL>/api/auth/jwks, which is Better
-# Auth's layout. EVERY other provider — Auth0, Okta, Entra, Keycloak, Cognito —
-# publishes its keys elsewhere, and a wrong JWKS URL fails as a TRANSIENT fetch
-# error, so every request 503s with nothing naming the cause. Say where the keys
-# are:
+# The signing keys are DISCOVERED from your SSO's own metadata document —
+# RFC 8414 (/.well-known/oauth-authorization-server), then OpenID Discovery
+# (/.well-known/openid-configuration) — so Auth0, Okta, Entra, Keycloak,
+# Cognito and Google all work unmodified. The boot line says which document
+# answered and where the keys came from.
+# Set this only to override discovery, or when your SSO publishes no metadata:
 #   KSOR_JWKS_URL=https://your-sso.example.com/.well-known/jwks.json
 # Serving a public bind with auth off additionally requires
 # KSOR_ALLOW_PUBLIC_UNAUTHENTICATED=1, which serves your whole record to anyone

package/templates/scaffold/instance.md

@@ -6,7 +6,10 @@ ksor:
   scaffolded: "KSOR-STAMP-VERSION"
 # The served MCP rung needs ONE required block: the NAME of the environment
 # variable holding your Postgres DSN — never the DSN itself. Uncomment it, copy
-# .env.example to .env, then run `pnpm serve`. Nothing else here is required:
+# .env.example to .env, then: `pnpm provision` once (schema + grant), then
+# `pnpm refresh` to PUBLISH the record, then `pnpm serve`. Serving does not
+# publish — that is deliberate, and skipping refresh serves nothing.
+# Nothing else here is required:
 # `embedding:` already defaults to Gemini at 1536 dimensions, and leaving
 # `retrieval:` out starts you with the abstention gate off and honest about it
 # (turn it on afterwards with `ksor calibrate`, once the record is serving).
@@ -39,3 +42,10 @@ act on it.
 Ask your coding agent to run the **intake interview** (it knows how — see
 `.agents/skills/intake-interview/`), answer its questions, and let it write
 this document with you.
+
+Until you do, `ksor serve` says so — at boot, and to every agent that connects:
+the MCP surface replaces this template with a plain statement that the record's
+scope is unstated, rather than passing authoring guidance to a runtime agent as
+if it were instructions. Nothing breaks, and the record still answers with
+citations; it just cannot tell an agent what it is authoritative FOR, which is
+the one thing that makes an answer worth trusting.

package/templates/scaffold/system/site/app/.well-known/mcp/server.json/route.ts

@@ -1,4 +1,4 @@
-import { appName, mcpEndpoint, mcpNamespace, recordVersion } from "@/lib/shared";
+import { appName, mcpEndpoint, mcpNamespace, recordDescription, recordVersion } from "@/lib/shared";
 
 /**
  * `/.well-known/mcp/server.json` — how an agent DISCOVERS this record's MCP
@@ -33,7 +33,10 @@ export function GET(): Response {
     {
       $schema: SCHEMA,
       name: `${mcpNamespace()}/${appName}`,
-      description: `The ${appName} Knowledge System of Record: governed markdown served with citations and honest abstention.`,
+      // The record's OWN account of itself — see recordDescription. A
+      // description identical in every ksor record cannot help an agent choose
+      // one, and a record with no scope yet says so instead of guessing.
+      description: recordDescription(),
       version: recordVersion(),
       // Absent until the owner declares where the server runs — an invented
       // URL is worse than none, because an agent would try it and conclude the

package/templates/scaffold/system/site/lib/order-rule.ts

@@ -0,0 +1,107 @@
+/**
+ * Reading order — ONE rule, for the website and the MCP door alike.
+ *
+ * `order:` is the only ordering key an author may write: it is in the governed
+ * frontmatter set the format checker closes, and the checker's own remedy for a
+ * stray `meta.json` says so ("sidebar order is the `order` frontmatter key").
+ *
+ * The MCP door did not read it. The kernel's tree adapter was converted from
+ * the predecessor, where the ordering keys were Docusaurus's `position` /
+ * `sidebar_position` — neither of which a compliant record may declare, because
+ * the checker refuses them as unknown keys. So the two surfaces disagreed about
+ * the record's reading order for every corpus that ordered itself at all: the
+ * site honoured `order:` and the door fell back to filename order and called it
+ * the record's structure. On a curriculum, where reading order IS the content,
+ * an agent asking `outline` for "what do I read first" got the wrong answer
+ * (found live 2026-08-21, by an agent probing a real ingested record).
+ *
+ * That is decision 18's shape — one guarantee, two surfaces, two heads — so it
+ * gets decision 18's treatment: this file is the rule, `ORDER_CASES` is the
+ * decision table, and both surfaces are asserted against the same rows. The
+ * site cannot import the kernel, so this file is COPIED into the scaffold and
+ * the copy is asserted byte-identical rather than trusted.
+ *
+ * Four things the two surfaces disagreed about beyond the key name, each of
+ * which is a row in the table:
+ *
+ *   - the unordered sentinel. The kernel used 10_000, a real number, so
+ *     `order: 20000` sorted AFTER an unordered document in the door and BEFORE
+ *     it on the site. Unordered is not a large order; it is the absence of one.
+ *   - truncation. The kernel applied `Math.trunc`, collapsing 3.2 and 3.7 into
+ *     one position and re-sorting them by name; the site kept both.
+ *   - the tie key's extension. The kernel compared `example.md` against
+ *     `example-two.md` — where `-` (45) sorts before `.` (46) — while the site
+ *     compared the extensionless urls, where the shorter is a prefix and wins.
+ *     Two ordinary filenames, two different orders.
+ *   - case. The kernel lowercased the tie key and the site did not, so
+ *     `apple.md` and `Banana.md` came out in opposite orders.
+ *
+ * No imports: a leaf, so it is testable in isolation and safe to copy.
+ */
+
+/**
+ * A document that declares no usable `order:` sorts after every document that
+ * does. Infinity, not a large number — see above.
+ */
+export const UNORDERED: number = Number.POSITIVE_INFINITY;
+
+/**
+ * The `order:` frontmatter value as a sort key.
+ *
+ * A numeric string is accepted because YAML frontmatter is read by scanners
+ * here, not by a YAML library: `order: 3` and `order: "3"` both reach this as
+ * text on one surface and as a number on the other, and an author cannot be
+ * expected to know which. Anything that is not a finite number — a word, a
+ * boolean, an empty value — is NOT an order, and the document sorts unordered.
+ */
+export function orderValue(raw: unknown): number {
+  if (typeof raw === "number") return Number.isFinite(raw) ? raw : UNORDERED;
+  if (typeof raw === "string") {
+    const trimmed = raw.trim();
+    if (trimmed === "") return UNORDERED;
+    const parsed = Number(trimmed);
+    return Number.isFinite(parsed) ? parsed : UNORDERED;
+  }
+  return UNORDERED;
+}
+
+/**
+ * The tie key for one sibling: its name with a MARKDOWN extension removed,
+ * case PRESERVED. The extension comes off because the site compares routes,
+ * which never carry one, and `.` sorting after `-` silently reversed ordinary
+ * pairs. Only `.md`/`.mdx` come off — a directory named `v1.2` keeps its dot,
+ * because the site's route keeps it too. Case is preserved because the site
+ * compares urls, and the url is what a reader sees.
+ */
+export function tieKey(name: string): string {
+  return name.replace(/\.mdx?$/, "");
+}
+
+/** One sibling's place in its parent: what it declared, and how ties break. */
+export interface Sibling {
+  readonly order: number;
+  readonly tie: string;
+}
+
+/**
+ * Compare by code point, not by locale or UTF-16 unit: reading order must be
+ * one bytewise truth on every machine, and `<` on strings compares UTF-16 units
+ * — which differ from code points on astral names.
+ */
+export function codePointCompare(a: string, b: string): number {
+  const as = [...a];
+  const bs = [...b];
+  const n = Math.min(as.length, bs.length);
+  for (let i = 0; i < n; i += 1) {
+    const x = as[i]?.codePointAt(0) ?? 0;
+    const y = bs[i]?.codePointAt(0) ?? 0;
+    if (x !== y) return x < y ? -1 : 1;
+  }
+  return as.length === bs.length ? 0 : as.length < bs.length ? -1 : 1;
+}
+
+/** Declared order first; ties break on the tie key. Total, and stable-safe. */
+export function compareSiblings(a: Sibling, b: Sibling): number {
+  if (a.order !== b.order) return a.order < b.order ? -1 : 1;
+  return codePointCompare(a.tie, b.tie);
+}

package/templates/scaffold/system/site/lib/page-order.ts

@@ -0,0 +1,93 @@
+/**
+ * Turning the reading-order rule into a sorted page tree — the SITE's half of
+ * decision 18, and canonical here so it can be tested.
+ *
+ * It names no framework type — the page-tree node shape is declared
+ * structurally below — for two reasons: the file is byte-copied into the
+ * scaffold's site, where it runs against Fumadocs's `Node`; and a rule that can
+ * only be exercised inside a Next build is a rule nobody exercises. The kernel
+ * has no website — it carries this so the SAME ORDER_CASES rows can be run
+ * against the tree sort a reader actually sees.
+ *
+ * Structural, not nominal: any node shaped like this sorts, which is what makes
+ * one file serve both the real page tree and the table's fixtures.
+ */
+
+import { compareSiblings, UNORDERED } from "./order-rule";
+
+/** The members of a page-tree node that reading order depends on. */
+export interface OrderNode {
+  readonly type: string;
+  /** A page's route. Absent on folders. */
+  readonly url?: string;
+  /** A folder's index document, when it has one. */
+  readonly index?: { readonly url: string } | undefined;
+  readonly children?: readonly OrderNode[] | undefined;
+}
+
+function nodeOrder(node: OrderNode, orders: ReadonlyMap<string, number>): number {
+  if (node.type === "page") return orders.get(node.url ?? "") ?? UNORDERED;
+  if (node.type === "folder" && node.index) return orders.get(node.index.url) ?? UNORDERED;
+  return UNORDERED;
+}
+
+// A url that identifies this node: its own, its index's, or its first
+// descendant's — a folder with no index document has no url of its own.
+function nodeUrl(node: OrderNode): string {
+  if (node.type === "page") return node.url ?? "";
+  if (node.type === "folder") {
+    if (node.index) return node.index.url;
+    for (const child of node.children ?? []) {
+      const url = nodeUrl(child);
+      if (url !== "") return url;
+    }
+  }
+  return "";
+}
+
+// The index of a top-level document's own segment: "/docs/x" splits to
+// ["", "docs", "x"], so its segment is at 2 — the baseUrl's segment count.
+const BASE_SEGMENTS = "/docs".split("/").length;
+
+/**
+ * The tie key: the ONE path segment that distinguishes this node from its
+ * siblings — never the whole url.
+ *
+ * The tree adapter ties on the entry's own name, so a folder with no index
+ * document must tie on its folder name too. Its url comes from a descendant
+ * (`/docs/guides/first`), and comparing that whole url against a sibling
+ * `/docs/guides-x` puts them in the opposite order, because the separator `/`
+ * (47) sorts after `-` (45). Taking the segment at this depth is exactly the
+ * adapter's key.
+ */
+function tieAt(node: OrderNode, depth: number): string {
+  return nodeUrl(node).split("/")[BASE_SEGMENTS + depth] ?? "";
+}
+
+/**
+ * Children of one parent, in reading order, recursively.
+ *
+ * Generic in the node so the caller keeps its own richer type: the site passes
+ * Fumadocs `Node`s and gets `Node`s back. The one cast is the rebuilt folder —
+ * spreading a node and replacing `children` produces a value TypeScript can no
+ * longer prove is the same subtype, though it is: every other member is copied
+ * verbatim. `depth` starts at 0 for the tree's own children.
+ */
+export function sortNodes<T extends OrderNode>(
+  nodes: readonly T[],
+  orders: ReadonlyMap<string, number>,
+  depth: number,
+): T[] {
+  return nodes
+    .map((node) =>
+      node.type === "folder"
+        ? ({ ...node, children: sortNodes(node.children ?? [], orders, depth + 1) } as T)
+        : node,
+    )
+    .sort((a, b) =>
+      compareSiblings(
+        { order: nodeOrder(a, orders), tie: tieAt(a, depth) },
+        { order: nodeOrder(b, orders), tie: tieAt(b, depth) },
+      ),
+    );
+}

package/templates/scaffold/system/site/lib/shared.ts

@@ -59,6 +59,55 @@ function readInstanceTitle(): string {
 
 export const appTitle: string = readInstanceTitle();
 
+/**
+ * How this record describes ITSELF, in one line — what an agent reads in a
+ * registry listing to decide whether this record can answer its question.
+ *
+ * It comes from the record's own prose (instance.md's first real paragraph,
+ * which the intake interview writes) because the alternative is what shipped
+ * before: one hard-coded sentence, byte-identical in every ksor record ever
+ * scaffolded, telling a discovering agent nothing that distinguishes this record
+ * from any other. "Discoverability determines whether agents find you at all" is
+ * a product principle, and a description that cannot discriminate is not
+ * discoverability (found live 2026-08-21).
+ *
+ * An UNDESCRIBED record says so rather than borrowing a confident sentence it
+ * has not earned — the same answer the MCP door already gives an agent that
+ * connects, so the two surfaces do not disagree about whether this record knows
+ * what it is. The marker is the template's own unfilled placeholder, matched on
+ * the WHOLE body: a scaffold's first paragraphs are authoring guidance, and
+ * reading one of those as the record's scope is worse than admitting there is
+ * none.
+ */
+const TEMPLATE_MARKER = "_fill this in; it is";
+
+function readInstanceScope(): string | null {
+  const text = readFileSync(findInstance(process.cwd()), "utf8");
+  const body = text.replace(/^\uFEFF?---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/, "");
+  if (body.includes(TEMPLATE_MARKER)) return null;
+  const afterHeading = body.replace(/^[\s\S]*?^#[ \t]+.+$/m, "");
+  for (const para of afterHeading.split(/\n[ \t]*\n/)) {
+    const one = para.trim().replace(/\s+/g, " ");
+    if (one === "" || one.startsWith("#") || one.startsWith("-") || one.startsWith(">")) continue;
+    const sentence = /^(.+?[.!?])(\s|$)/.exec(one)?.[1] ?? one;
+    return sentence.length > 300 ? `${sentence.slice(0, 297)}...` : sentence;
+  }
+  return null;
+}
+
+/** null until the owner has written one — never a guess. */
+export const appScope: string | null = readInstanceScope();
+
+/**
+ * The one-line description every discovery surface publishes. Built here so the
+ * registry document and anything else that needs one cannot drift apart.
+ */
+export function recordDescription(): string {
+  return appScope === null
+    ? `${appTitle} — its owner has not yet described what this record covers.`
+    : `${appTitle} — ${appScope}`;
+}
+
 /**
  * Where this record's MCP surface is published, if the owner has said.
  *

package/templates/scaffold/system/site/lib/source.ts

@@ -3,6 +3,9 @@ import { loader } from "fumadocs-core/source";
 import { lucideIconsPlugin } from "fumadocs-core/source/lucide-icons";
 import type { Node, Root } from "fumadocs-core/page-tree";
 
+import { orderValue } from "./order-rule";
+import { sortNodes } from "./page-order";
+
 // See https://fumadocs.dev/docs/headless/source-api for more info
 export const source = loader({
   baseUrl: "/docs",
@@ -18,54 +21,12 @@ export type KnowledgePage = (typeof source)["$inferPage"];
 // every rendered link.
 export const basePath: string = process.env.KSOR_BASE_PATH ?? "";
 
-// `order:` is a governed frontmatter key; a document without one, or with a
-// value that is not a number, sorts after every document that declares one.
+// Reading order is ONE rule, shared with the MCP door byte-for-byte — see
+// ./order-rule.ts. The site cannot import the kernel, so the rule is copied and
+// the copy is asserted; every case both surfaces must agree on is a row in the
+// kernel's ORDER_CASES table, and this half is asserted against the same rows.
 function orderOf(page: KnowledgePage): number {
-  const raw: unknown = page.data.order;
-  const value = typeof raw === "string" ? Number(raw) : raw;
-  return typeof value === "number" && Number.isFinite(value) ? value : Number.POSITIVE_INFINITY;
-}
-
-function nodeOrder(node: Node, orders: ReadonlyMap<string, number>): number {
-  if (node.type === "page") return orders.get(node.url) ?? Number.POSITIVE_INFINITY;
-  if (node.type === "folder" && node.index) {
-    return orders.get(node.index.url) ?? Number.POSITIVE_INFINITY;
-  }
-  return Number.POSITIVE_INFINITY;
-}
-
-// The tie-break key: a page's url, a folder's index url or first page's url.
-// Ties break on it so unordered documents read in plain name order, folders
-// interleaved — the canonical reading order both shells implement (found
-// live 2026-08-18: the loader's own tie order grouped folders after loose
-// files, silently diverging from the Docusaurus shell on the same record).
-function nodeName(node: Node): string {
-  if (node.type === "page") return node.url;
-  if (node.type === "folder") {
-    if (node.index) return node.index.url;
-    for (const child of node.children) {
-      const name = nodeName(child);
-      if (name !== "") return name;
-    }
-  }
-  return "";
-}
-
-function sortNodes(nodes: readonly Node[], orders: ReadonlyMap<string, number>): Node[] {
-  return nodes
-    .map((node) =>
-      node.type === "folder" ? { ...node, children: sortNodes(node.children, orders) } : node,
-    )
-    .sort((a, b) => {
-      const left = nodeOrder(a, orders);
-      const right = nodeOrder(b, orders);
-      if (left !== right) return left < right ? -1 : 1;
-      const leftName = nodeName(a);
-      const rightName = nodeName(b);
-      // Codepoint comparison, not locale: reading order must be one bytewise
-      // truth on every machine.
-      return leftName < rightName ? -1 : leftName > rightName ? 1 : 0;
-    });
+  return orderValue(page.data.order);
 }
 
 /**
@@ -76,7 +37,7 @@ function sortNodes(nodes: readonly Node[], orders: ReadonlyMap<string, number>):
 export function getSortedPageTree(): Root {
   const orders = new Map(source.getPages().map((page) => [page.url, orderOf(page)] as const));
   const tree = source.getPageTree();
-  return { ...tree, children: sortNodes(tree.children, orders) };
+  return { ...tree, children: sortNodes(tree.children, orders, 0) };
 }
 
 function collectUrls(nodes: readonly Node[], urls: string[]): void {

package/templates/scaffold/system/site/lib/stage-knowledge.ts

@@ -343,13 +343,30 @@ function planStage(recordDir: string, denied: DenylistManifest): StagePlan {
   return { files: [...documents, ...assets], documents: documents.length, total };
 }
 
+/**
+ * Remove the stage, asking for the retries this exact failure needs.
+ *
+ * `force: true` suppresses ENOENT; it does NOT retry anything. Node retries
+ * EBUSY / EMFILE / ENFILE / ENOTEMPTY / EPERM only when `maxRetries` is set,
+ * and it defaults to zero. The build evaluates `source.config.ts` more than
+ * once when the bundler wants it in more than one place, so two runs can
+ * overlap: one removing the stage while the other is still copying into it.
+ * That surfaced as `ENOTEMPTY` out of `rmSync` and failed the whole site build
+ * (CI, 2026-08-21) — a race that is safe to lose, because the stage is a
+ * deterministic function of the record and the denylist, so redoing it produces
+ * the same bytes.
+ */
+function removeStage(stageDir: string): void {
+  rmSync(stageDir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
+}
+
 /** Fill a clean stage with exactly the set this build may publish. */
 function fillStage(recordDir: string, stageDir: string, denied: DenylistManifest): void {
   // The old stage goes first, before any refusal can throw: a refused build
   // that leaves the previous, more permissive stage on disk hands the next
   // careless build a filtered copy nothing governs (review finding,
   // 2026-08-19).
-  rmSync(stageDir, { recursive: true, force: true });
+  removeStage(stageDir);
   const plan = planStage(recordDir, denied);
   // An empty record is its own problem, reported by the page that renders it;
   // an empty AUDIENCE is a misconfiguration that would otherwise surface as
@@ -468,7 +485,7 @@ export function knowledgeSourceDir(): string {
     // A stage left behind by an earlier model would be a filtered copy of the
     // record nothing governs any more — removed before the refusal below can
     // throw, so a refused build never leaves one behind either.
-    rmSync(stageDir, { recursive: true, force: true });
+    removeStage(stageDir);
     refuseVisibilityWithoutAudiences(recordDir);
     return RECORD_DIR;
   }