@panaversity/ksor 0.0.40 → 0.0.41

package/templates/scaffold/system/gateways/content.ts

@@ -32,6 +32,7 @@ import {
   readHandler,
   SEARCH_OUTPUT,
   searchHandler,
+  TRUST_TIERS,
   z,
   type ServiceContext,
 } from "@panaversity/ksor/gateway";
@@ -75,6 +76,18 @@ export default function buildGateway(ctx: ServiceContext, version: string): McpS
           .max(MAX_SEARCH_K)
           .default(10)
           .describe(`Maximum passages to return (1–${MAX_SEARCH_K})`),
+        // The caller's trust floor. Keep it: dropping the parameter does not
+        // weaken the record — the handler still applies `unverified` and this
+        // deployment's own floor — but it takes away the only way a caller can
+        // ask to be answered ONLY from what a human reviewed, and the door says
+        // so at boot instead of failing quietly.
+        min_trust_tier: z
+          .enum(TRUST_TIERS)
+          .optional()
+          .describe(
+            "Lowest trust tier to answer from (default unverified). This deployment's own " +
+              "floor still applies: it can only be raised here, never lowered.",
+          ),
       }),
       outputSchema: SEARCH_OUTPUT,
       annotations: READ_ONLY,

package/templates/scaffold/system/site/app/(home)/page.tsx

@@ -42,8 +42,8 @@ export default function HomePage(): ReactElement {
   // entries standing behind it. The lead is looked up among the top-level
   // entries so a folder keeps the count of what it holds, and falls back to
   // building an entry directly — the first document in governed order can sit
-  // BELOW the top level, where `entriesUnder(null)` would never return it.
-  const entries = entriesUnder(null);
+  // BELOW the top level, where the root's own listing would never return it.
+  const entries = entriesUnder("");
   const lead = entries.find((entry) => entry.url === first.url) ?? entryFor(first);
   const behind = entries.filter((entry) => entry.url !== lead.url).slice(0, 3);
 

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

@@ -1,4 +1,5 @@
 import { appName, mcpEndpoint, mcpNamespace, recordDescription, recordVersion } from "@/lib/shared";
+import { readStageManifest } from "@/lib/stage-manifest";
 
 /**
  * `/.well-known/mcp/server.json` — how an agent DISCOVERS this record's MCP
@@ -16,6 +17,10 @@ import { appName, mcpEndpoint, mcpNamespace, recordDescription, recordVersion }
  *                `name:` has no slash, so it was rejected outright.
  *   version      REQUIRED. Absent, the document failed validation on its own.
  *   capabilities NOT a field in the schema; it was invented here.
+ *   _meta        the schema's extension point, namespaced by reverse DNS —
+ *                where the build's stamps go (build spec §3, R14), so a
+ *                validating client still accepts the document and a consumer
+ *                can connect it to the publication it describes.
  *
  * (Checked against the 2025-12-11 schema, round-6 review of #43, which built
  * the scaffold and validated the emitted file.)
@@ -27,11 +32,16 @@ export const dynamic = "force-static";
 
 const SCHEMA = "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json";
 
+/** The `_meta` key the stamps live under: a namespace this project controls. */
+const META_KEY = "com.panaversity.ksor/build";
+
 export function GET(): Response {
   const endpoint = mcpEndpoint();
+  const { build_id, source_commit, dirty, ksor_version, unstamped } = readStageManifest().stamps;
   return Response.json(
     {
       $schema: SCHEMA,
+      _meta: { [META_KEY]: { build_id, source_commit, dirty, ksor_version, unstamped } },
       name: `${mcpNamespace()}/${appName}`,
       // The record's OWN account of itself — see recordDescription. A
       // description identical in every ksor record cannot help an agent choose

package/templates/scaffold/system/site/app/docs/[[...slug]]/page.tsx

@@ -1,19 +1,31 @@
-import { entriesUnder, getSortedPages, markdownPath, source } from "@/lib/source";
+import {
+  basePath,
+  entriesUnder,
+  folderHeading,
+  folderOfRoute,
+  folderSlugs,
+  getSortedPages,
+  markdownPath,
+  source,
+} from "@/lib/source";
 import { RecordIndex } from "@/components/record-index";
 import { DocsBody, DocsDescription, DocsPage, DocsTitle } from "fumadocs-ui/layouts/docs/page";
 import { TOCPopover, TOCProvider } from "fumadocs-ui/layouts/docs/page/slots/toc";
 import { notFound } from "next/navigation";
 import { getMDXComponents } from "@/components/mdx";
 import type { Metadata } from "next";
-import { createRelativeLink } from "fumadocs-ui/mdx";
+import type { ReactElement } from "react";
+import { recordLink } from "@/lib/record-link";
 import {
+  DeprecatedNotice,
   GovernanceMeta,
+  LifecycleCaveat,
   Provenance,
-  SupersededNotice,
   type Successor,
 } from "@/components/governance";
 import { predecessorsOf, readGovernance, resolveSuccessorUrl } from "@/lib/governance";
 import { showGovernance } from "@/lib/shared";
+import { stagePageOf } from "@/lib/stage-manifest";
 import { RecordBreadcrumb } from "@/components/record-breadcrumb";
 import { RecordToc, TocItems } from "@/components/record-toc";
 import { RecordViews } from "@/components/record-views";
@@ -24,10 +36,53 @@ import { StudyAids } from "@/components/study-aids";
 import { deckFor, quizFor, slidesFor, summaryFor } from "@/lib/attachments";
 import { readingMinutes } from "@/lib/reading-time";
 
+/** The route a slug names: `/docs`, or `/docs/a/b`. */
+function routeOf(slug: readonly string[] | undefined): string {
+  return slug === undefined || slug.length === 0 ? "/docs" : `/docs/${slug.join("/")}`;
+}
+
+/**
+ * Every page reads `rel="describedby"`: the record describes itself in
+ * `llms.txt`, and a consumer that follows the link learns what this record is
+ * authoritative for before it reads a page of it (build spec §3).
+ */
+function DescribedBy(): ReactElement {
+  return <link rel="describedby" href={`${basePath}/llms.txt`} type="text/markdown" />;
+}
+
+/**
+ * A directory's page: the regenerated `index.md` of this viewer's stage,
+ * rendered as a listing. A folder has no body and no governance of its own
+ * (record spec §1) — it is admitted iff a descendant is, and its page is the
+ * list of what it holds. Excluded from the docs collection, so it has no
+ * twin, no `llms.txt` line and no search entry.
+ */
+function FolderPage({ dir }: { dir: string }): ReactElement {
+  return (
+    <TocItems items={[]}>
+      <DocsPage
+        toc={[]}
+        slots={{
+          breadcrumb: RecordBreadcrumb,
+          toc: { provider: TOCProvider, main: RecordToc, popover: TOCPopover },
+        }}
+      >
+        <DescribedBy />
+        <DocsTitle>{folderHeading(dir)}</DocsTitle>
+        <RecordIndex entries={entriesUnder(dir)} heading="In this section" />
+      </DocsPage>
+    </TocItems>
+  );
+}
+
 export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
   const params = await props.params;
   const page = source.getPage(params.slug);
-  if (!page) notFound();
+  if (!page) {
+    const dir = folderOfRoute(routeOf(params.slug));
+    if (dir === null) notFound();
+    return <FolderPage dir={dir} />;
+  }
 
   const MDX = page.data.body;
   // Attachments of THIS document, found by suffix on its own path. Null is the
@@ -39,40 +94,35 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
   const presentation = slidesFor(page.path);
   // Counted at BUILD time from the document's own markdown, so the figure is in
   // the shipped HTML for a reader with a failed bundle, a crawler and an agent
-  // alike. The predecessor measured the rendered DOM after paint, which put it
-  // out of reach of all three.
+  // alike.
   const minutes = readingMinutes(await page.data.getText("processed"));
   const summaryMinutes =
     summary === null ? null : readingMinutes(await summary.getText("processed"));
   // What the record says about this document. The page renders it; it never
-  // supplies it — an undeclared key shows nothing (specs/ksor/site-governance).
+  // supplies it — an undeclared key shows nothing.
   const governance = readGovernance(page.data, page.path);
+  // What staging decided about it: the badge, and whether a twin exists.
+  const staged = stagePageOf(page.path);
+  const badge = staged?.badge ?? null;
+  const twin = staged?.machine === true ? markdownPath(page.url) : undefined;
 
+  const allPages = getSortedPages();
   let successor: Successor | null = null;
   // Gated on the STATUS, not on the pointer: a document the record calls
-  // current must never be published under a "Superseded" banner, whatever
-  // stale successor pointer it still carries (`pnpm check` refuses that
-  // combination too — this is the second lock on the same door).
-  if (governance.status === "superseded" && governance.supersededBy !== null) {
-    const pages = getSortedPages();
-    // Against page.path, not page.url: a route cannot tell a file from a
-    // folder index, and `./terms.md` means a different document in each.
-    const href = resolveSuccessorUrl(governance.supersededBy, page.path, pages);
-    // Name the successor by its title, not by its path: the notice is for a
+  // current must never be published under a "Deprecated" banner, whatever
+  // stale successor pointer it still carries.
+  if (governance.status === "deprecated" && governance.supersededBy !== null) {
+    const href = resolveSuccessorUrl(governance.supersededBy, allPages);
+    // Name the successor by its title, not by its id: the notice is for a
     // reader, and the pointer is only the fallback when the route did not
     // resolve — never a dead link.
-    const target = href === null ? undefined : pages.find((c) => c.url === href.split("#")[0]);
+    const target = href === null ? undefined : allPages.find((c) => c.url === href.split("#")[0]);
     successor = { href, label: target?.data.title ?? governance.supersededBy };
   }
 
   // What this document replaced, derived by asking every document in the record
   // where its successor pointer lands (research/site-design.md F4). No new
   // frontmatter key: the record already says it, in the other direction.
-  // The same address `generateMetadata` advertises, shown to a person as well:
-  // the human surface handing an agent the record's own bytes is a better
-  // demonstration of the product than any copy on the home page.
-  const markdownUrl = markdownPath(page.url);
-  const allPages = getSortedPages();
   const replaces = predecessorsOf(
     page.url,
     allPages,
@@ -91,16 +141,9 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
         toc={page.data.toc}
         full={page.data.full}
         // The rail is ours; the provider and the small-screen popover stay the
-        // shell's. Its own rail marks a heading active when 90% of it is visible
-        // anywhere in the viewport and then highlights whichever became active
-        // last, which on this record's short-sectioned documents ran two to four
-        // headings AHEAD of the reader. The observer's options are not
-        // configurable and the observer is not exported, so the selection could
-        // only be replaced — `slots.toc.main` is the seam for that.
-        // The breadcrumb is ours for one reason, recorded in the component:
-        // the shell's renders nothing at all on a top-level document, so the
-        // block above the title came and went as a reader moved through the
-        // record.
+        // shell's (its own rail ran two to four headings ahead of the reader on
+        // this record's short-sectioned documents). The breadcrumb is ours
+        // because the shell's renders nothing on a top-level document.
         slots={{
           breadcrumb: RecordBreadcrumb,
           toc: {
@@ -110,91 +153,68 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
           },
         }}
         // The table-of-contents column is HELD on every page, including the many
-        // in a governed record that have no headings at all and render nothing
-        // into it. Collapsing it for those documents (which this file did, from
-        // 2026-08-21) bought a wider column at the price of a moving one: the
-        // article is centred in whatever the column leaves, so the prose jumped
-        // 134px sideways between a document with headings and one without
-        // (measured at 1728px: text at x=446 against x=580). A reader clicking
-        // through a record saw the page slide under them.
-        //
-        // Held, the grid is `0 | 268 | main | 268 | 0` — sidebar and rail the
-        // same width, so the main column is centred in the viewport and the
-        // reading measure capped in global.css sits centred inside it, in the
-        // same place on every document. The rail is the natural home for the
-        // governance facts this record already carries; until it holds them it
-        // is quiet space on the side, which is what the earlier collapse was
-        // really objecting to — the 900px measure beside it, since fixed.
+        // in a governed record that have no headings, so the prose sits in the
+        // same place on every document (measured 134px of drift without it).
       >
-        {successor === null ? null : <SupersededNotice successor={successor} />}
+        <DescribedBy />
+        {governance.status === "deprecated" ? <DeprecatedNotice successor={successor} /> : null}
         <DocsTitle>{page.data.title}</DocsTitle>
         <DocsDescription>{page.data.description}</DocsDescription>
         {showGovernance ? (
           <GovernanceMeta
             governance={governance}
+            badge={badge}
             replaces={replaces}
-            markdownUrl={markdownUrl}
+            markdownUrl={twin}
             // Only when there is no view strip to carry it — with a summary,
             // the number belongs to the view the reader picked, not to the
             // document as a whole.
             minutes={summary === null ? minutes : undefined}
           />
-        ) : null}
-        {/* grow-0, against the shell's own `flex-1`: the article is a flex column
-          stretched to the viewport, so the body inflated from ~150px of text to
-          402px and pushed Sources and everything after it to the bottom of the
-          screen — a governance block floating 400px below the document it
-          describes (measured, 2026-08-21). Short documents now end where their
-          text ends. */}
+        ) : (
+          // …and with the strip off, the CAVEAT still shows. `site.governance`
+          // hides attribution, not the record's word on whether this document
+          // is in force — which the sidebar, the folder listing and the search
+          // result all keep saying about this same page (`plainBadge`).
+          <LifecycleCaveat badge={badge} effectiveFrom={governance.effectiveFrom} />
+        )}
+        {/* grow-0, against the shell's own `flex-1`: short documents end where
+          their text ends rather than pushing Sources to the bottom of the
+          screen (measured, 2026-08-21). */}
         <DocsBody style={{ flexGrow: 0 }}>
           {/* The summary panel is built HERE, on the server, and handed to the
             client tab strip as a prop — so it is in the shipped HTML whether or
-            not the bundle runs, which is what an agent parsing the page and a
-            reader with a failed bundle both depend on. Presence-driven: with no
-            summary, RecordViews renders the body alone and no tab strip exists
-            (specs/ksor/study-attachments C3, C20). */}
+            not the bundle runs. Presence-driven: with no summary, RecordViews
+            renders the body alone and no tab strip exists. */}
           <RecordViews
             documentMinutes={minutes}
             summaryMinutes={summaryMinutes ?? undefined}
             summary={
               Summary === null ? null : (
-                <Summary components={getMDXComponents({ a: createRelativeLink(source, page) })} />
+                <Summary components={getMDXComponents({ a: recordLink(source, page) })} />
               )
             }
           >
             <MDX
               components={getMDXComponents({
-                // relative links between documents in knowledge/ resolve to
-                // their rendered pages
-                a: createRelativeLink(source, page),
+                // links between documents in knowledge/, in both OKF forms,
+                // resolve to their rendered pages
+                a: recordLink(source, page),
                 // The deck, rendered where the record's own shape puts it:
-                // after the introduction, before the first section. The
-                // rehype plugin marks the place on every document and this
-                // decides whether there is anything to put there — so "does
-                // this document have a teaching aid" stays one question,
-                // answered by the attachment, not two.
+                // after the introduction, before the first section.
                 TeachingAid: () =>
                   presentation === null ? null : <Slides slides={presentation} />,
               })}
             />
           </RecordViews>
         </DocsBody>
-        {/* What a reader DOES with this document once they have read it. One
-          region, so the quiz that will sit beside the deck is a child here and
-          not a new argument about where it goes. Renders nothing at all when
-          the document has no study aids. */}
-        {/* Recall first, then the check on it — and each renders only if the
-            document carries one, so a page with just a quiz shows just a quiz. */}
+        {/* What a reader DOES with this document once they have read it.
+          Renders nothing at all when the document has no study aids. */}
         <StudyAids>
           {deck === null ? null : <Flashcards deck={deck} />}
           {quiz === null ? null : <Quiz quiz={quiz} />}
         </StudyAids>
-        {/* A folder's index page lists what the folder holds. Without it the
-          page ended at its own sentence and the documents below it were
-          reachable only from the sidebar (research/site-design.md F5). Empty
-          for a leaf document, which renders nothing. */}
-        <RecordIndex entries={entriesUnder(page.url)} heading="In this section" />
-        {showGovernance ? <Provenance entries={governance.provenance} /> : null}
+        {showGovernance ? <Provenance entries={governance.sources} /> : null}
       </DocsPage>
     </TocItems>
   );
@@ -202,29 +222,44 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
 
 export async function generateStaticParams() {
   const params = source.generateParams();
-  if (params.length === 0) {
+  // Every directory this viewer's stage holds an index for is a page too —
+  // the root included, which is the record's own map.
+  const folders = folderSlugs().map((slug) => ({ slug }));
+  if (params.length === 0 && folders.length === 0) {
     // Without this, Next fails the empty-record build with an error that
     // names neither the record nor the rule (found live, 2026-08-18).
+    //
+    // NOT the same state as "this build publishes no document". The emitted
+    // starter is all drafts by design (R25), and build spec §4 acceptance 4
+    // requires it to BUILD and publish none of them — so a stage with the root
+    // index and no page is a record waiting for its first approval, and
+    // throwing here failed `pnpm build` on every freshly scaffolded project
+    // (found live 2026-08-25 through the scaffold e2e). What is left is the
+    // genuinely impossible state: no page AND no index, which means the stage
+    // itself is missing.
     throw new Error(
-      "the record has no documents — a KSoR is never empty; add one to knowledge/ or restore one from git history (pnpm check says the same).",
+      "the staged record holds neither a document nor a folder index — the stage is missing or empty; run `ksor build` and check knowledge/ (`pnpm check` says the same).",
     );
   }
-  return params;
+  return [...params, ...folders];
 }
 
 export async function generateMetadata(props: PageProps<"/docs/[[...slug]]">): Promise<Metadata> {
   const params = await props.params;
   const page = source.getPage(params.slug);
-  if (!page) notFound();
-
-  // The markdown twin, advertised rather than left to be guessed: a consumer
-  // that follows `rel="alternate"` reaches the record's own bytes instead of
-  // scraping this page (research/site-design.md F2).
-  const markdownUrl = markdownPath(page.url);
+  if (!page) {
+    const dir = folderOfRoute(routeOf(params.slug));
+    if (dir === null) notFound();
+    return { title: folderHeading(dir) };
+  }
 
+  // The markdown twin, advertised rather than left to be guessed — and only
+  // where one exists: a page the machine surfaces decline has no twin, and
+  // advertising one would be a dead link (build spec §3).
+  const twin = stagePageOf(page.path)?.machine === true;
   return {
     title: page.data.title,
     description: page.data.description,
-    alternates: { types: { "text/markdown": markdownUrl } },
+    ...(twin ? { alternates: { types: { "text/markdown": markdownPath(page.url) } } } : {}),
   };
 }

package/templates/scaffold/system/site/app/global.css

@@ -262,7 +262,7 @@ html > body[data-scroll-locked] {
 /* The caution colour is a TOKEN, declared as a light/dark pair on the root
    rather than inside the one class that first used it. Every surface that has
    to say "the record withdrew this" now spends the same colour — the banner
-   over a superseded document, and the chip that marks it in the sidebar, the
+   over a deprecated document, and the chip that marks it in the sidebar, the
    listings, the front door and search. Declared in both themes deliberately:
    a colour written only on `:root` leaks into dark, because `:root` and
    `.dark` have equal specificity and whichever comes later wins. */
@@ -489,10 +489,10 @@ html > body[data-scroll-locked] {
 }
 
 /* A withdrawn document's status chip, wherever one renders. A `draft` chip and
-   a `superseded` chip were pixel-identical — the same hairline border and the
+   a `deprecated` chip were pixel-identical — the same hairline border and the
    same muted text — so the two statuses that mean the most different things
    looked the same at the moment a reader picks between two documents. The
-   colour is additive, never the whole signal: the word "superseded" is beside
+   colour is additive, never the whole signal: the word "deprecated" is beside
    it in every one of these places (GOV.UK's rule — never rely on colour alone).
    Unlayered, so it beats the Tailwind utility that sets the chip's border and
    text colour; the banner class above has always worked this way. */
@@ -519,8 +519,16 @@ html > body[data-scroll-locked] {
 }
 
 /* …and in search too, where a reader is choosing between results. The chip is
-   drawn by `content`, so the tone has to be set on the same pseudo-element. */
-[data-ksor-status="superseded"]::after {
+   drawn by `content`, so the tone has to be set on the same pseudo-element.
+
+   found live 2026-08-25: this selector still read `superseded`, the PRE-PROFILE
+   status word. Under the profile the withdrawn state is `deprecated` (record
+   spec §2.2), so it matched nothing and a withdrawn document's search row wore
+   the ordinary grey chip — on the one surface whose snippet quotes the
+   withdrawn figure, which is why the rule exists. The value here is
+   `lifecycleBadge`'s, not `status`'s; the two agree on this word and the badge
+   is what the map carries. */
+[data-ksor-status="deprecated"]::after {
   border-color: color-mix(in oklab, var(--ksor-caution) 45%, transparent);
   color: var(--ksor-caution);
 }

package/templates/scaffold/system/site/app/layout.tsx

@@ -2,7 +2,8 @@ import { RootProvider } from "fumadocs-ui/provider/next";
 import "./global.css";
 import type { Metadata } from "next";
 import { appTitle } from "@/lib/shared";
-import { basePath, caveatStatusByUrl } from "@/lib/source";
+import { basePath, badgeByUrl } from "@/lib/source";
+import { readStageManifest } from "@/lib/stage-manifest";
 import KsorSearchDialog from "@/components/search-dialog";
 
 // No next/font/google: it fetches the face from Google at BUILD time, so a
@@ -17,13 +18,17 @@ export const metadata: Metadata = {
     template: `%s | ${appTitle}`,
   },
   description: "The Knowledge System of Record for humans and AI agents.",
+  // A build that shows drafts (`KSOR_DRAFTS=show`) is a preview, and a static
+  // site's pages are open-web artefacts: it says so to every crawler rather
+  // than letting a draft be indexed under the record's name (build spec §3).
+  ...(readStageManifest().drafts === "shown" ? { robots: { index: false, follow: false } } : {}),
 };
 
 export default function Layout({ children }: LayoutProps<"/">) {
   return (
     <html lang="en" suppressHydrationWarning>
       <body className="flex flex-col min-h-screen">
-        {/* Which documents carry a caveat status, for the search dialog — it
+        {/* Which documents carry a badge, for the search dialog — it
             runs in the browser over a static index that has no field for it.
             Delivered in the document rather than as a dialog prop because
             RootProvider types `options` against the SHIPPED dialog's props, and
@@ -34,7 +39,7 @@ export default function Layout({ children }: LayoutProps<"/">) {
           type="application/json"
           id="ksor-statuses"
           dangerouslySetInnerHTML={{
-            __html: JSON.stringify(caveatStatusByUrl()).replaceAll("<", "\\u003c"),
+            __html: JSON.stringify(badgeByUrl()).replaceAll("<", "\\u003c"),
           }}
         />
         <RootProvider

package/templates/scaffold/system/site/app/llms-full.txt/route.ts

@@ -1,12 +1,18 @@
-import { getLLMText, getSortedPages } from "@/lib/source";
+import { getLLMText, getMachinePages } from "@/lib/source";
+import { stampLines } from "@/lib/governance";
+import { appName, appTitle } from "@/lib/shared";
+import { readStageManifest } from "@/lib/stage-manifest";
 
 export const revalidate = false;
 
+/**
+ * The whole machine-admitted record in one file, opened by the stamps that
+ * connect it to one publication (R14) — so a consumer holding a copy can say
+ * which build it came from — then every document with its own governance
+ * block, exactly as its twin serves it.
+ */
 export async function GET(): Promise<Response> {
-  // The whole set is threaded through so each document's successor pointer
-  // resolves to a route rather than the `./x.md` a consumer cannot follow.
-  const pages = getSortedPages();
-  const scanned = await Promise.all(pages.map((page) => getLLMText(page, pages)));
-
-  return new Response(scanned.join("\n\n"));
+  const head = `---\ntitle: ${JSON.stringify(appTitle)}\nname: ${appName}\n${stampLines(readStageManifest().stamps).join("\n")}\n---`;
+  const scanned = getMachinePages().map((page) => getLLMText(page));
+  return new Response([head, ...scanned].join("\n\n"));
 }

package/templates/scaffold/system/site/app/llms.txt/route.ts

@@ -3,15 +3,20 @@ import { recordIndexText } from "@/lib/source";
 export const revalidate = false;
 
 // The agent-facing index of the record: this instance's name, then every
-// document in sidebar order, each link usable as-is on a sub-path host — and
-// each carrying its governance when the governance is a caveat.
+// document a MACHINE surface may carry, in sidebar order, each link usable
+// as-is on a sub-path host.
 //
-// Without that last part a withdrawn document and the one that replaced it are
-// two adjacent entries told apart only by whatever a human happened to type
-// into a title, and an agent picks either (research/site-design.md F1).
+// There is no caveat marker any more, because there is nothing to mark: the
+// §2.5 table admits only stable, effective, unexpired, undenied concepts here,
+// so a draft, a deprecated document and one past its `stale_after` are not
+// entries at all. That replaced marking with exclusion — the older worry was a
+// withdrawn document and its replacement sitting adjacent, told apart only by
+// whatever a human typed into a title (research/site-design.md F1), and an
+// agent picking either.
 //
-// The bytes are built in lib/source (`recordIndexText`) because the home page
-// shows this same index to a reader — one index, one spelling.
+// The set is decided ONCE, by staging, and read back here: the bytes are built
+// in lib/source (`recordIndexText`) because the home page shows this same index
+// to a reader — one index, one spelling.
 export function GET(): Response {
   return new Response(recordIndexText());
 }

package/templates/scaffold/system/site/app/md/[[...slug]]/route.ts

@@ -1,36 +1,38 @@
 import { notFound } from "next/navigation";
 
-import { getLLMText, getSortedPages, source } from "@/lib/source";
+import { getLLMText, getMachinePages, rootIndexTwin, source } from "@/lib/source";
+import { machineAdmits } from "@/lib/stage-manifest";
 
 export const revalidate = false;
 
 /**
- * Every document as markdown, at a stable address derived from its path:
- * `/docs/policies/purchase-approval` is also served at
- * `/md/policies/purchase-approval.md`.
+ * Every MACHINE-admitted document as markdown, at a stable address derived
+ * from its path: `/docs/policies/purchase-approval` is also served at
+ * `/md/policies/purchase-approval.md`, and the record's own index at
+ * `/md/index.md` — the one index with a twin (build spec §3).
  *
  * The record already IS markdown; without this an agent handed a document URL
  * had to scrape a React app to reach text the record holds verbatim
- * (research/site-design.md F2). The body carries the document's governance as
- * frontmatter, exactly as `llms-full.txt` does, so a consumer reading one
- * document knows its status, owner, sources and successor.
+ * (research/site-design.md F2). The body carries the document's governance and
+ * the build's stamps as frontmatter, exactly as `llms-full.txt` does.
  *
- * Why a `/md/` prefix rather than appending `.md` to the document's own URL,
- * which is the convention the field has settled on: under `output: "export"` a
- * Route Handler cannot share a route segment with a Page, and there is no
- * middleware to rewrite one onto the other. The prefix is the shape that
+ * A page the machine surfaces decline — a draft, a deprecated, a not-yet-
+ * effective or a stale concept (record spec §2.5) — has no twin at all: the
+ * decision is staging's, read back here, never re-derived.
+ *
+ * Why a `/md/` prefix rather than appending `.md` to the document's own URL:
+ * under `output: "export"` a Route Handler cannot share a route segment with a
+ * Page, and there is no middleware to rewrite one onto the other. The prefix
  * survives a static host, and the page advertises it in a `rel="alternate"`
- * link so a consumer discovers it rather than guessing. Appending `.md` to the
- * canonical URL becomes possible the day a build emits these artifacts itself.
+ * link so a consumer discovers it rather than guessing.
  */
 export function generateStaticParams(): { slug: string[] }[] {
-  return source.generateParams().map(({ slug }) => {
-    const segments = slug ?? [];
-    const last = segments.at(-1);
-    return {
-      slug: last === undefined ? ["index.md"] : [...segments.slice(0, -1), `${last}.md`],
-    };
+  const twins = getMachinePages().map((page) => {
+    const segments = page.url.replace(/^\/docs\/?/, "").split("/");
+    const last = segments.at(-1) ?? "";
+    return { slug: [...segments.slice(0, -1), `${last}.md`] };
   });
+  return [{ slug: ["index.md"] }, ...twins];
 }
 
 export async function GET(
@@ -40,12 +42,11 @@ export async function GET(
   const { slug = [] } = await params;
   const last = slug.at(-1);
   if (last === undefined || !last.endsWith(".md")) notFound();
-  const docSlug = last === "index.md" ? [] : [...slug.slice(0, -1), last.slice(0, -".md".length)];
+  const headers = { "content-type": "text/markdown; charset=utf-8" };
+  if (slug.length === 1 && last === "index.md") return new Response(rootIndexTwin(), { headers });
 
-  const page = source.getPage(docSlug);
-  if (!page) notFound();
+  const page = source.getPage([...slug.slice(0, -1), last.slice(0, -".md".length)]);
+  if (!page || !machineAdmits(page.path)) notFound();
 
-  return new Response(await getLLMText(page, getSortedPages()), {
-    headers: { "content-type": "text/markdown; charset=utf-8" },
-  });
+  return new Response(getLLMText(page), { headers });
 }