@panaversity/ksor 0.0.39 → 0.0.41

package/templates/scaffold/pnpm-lock.yaml

@@ -46,6 +46,9 @@ importers:
       tw-animate-css:
         specifier: 1.4.0
         version: 1.4.0
+      yaml:
+        specifier: 2.9.0
+        version: 2.9.0
       zod:
         specifier: 4.4.3
         version: 4.4.3

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,83 +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} replaces={replaces} markdownUrl={markdownUrl} />
-        ) : 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. */}
+          <GovernanceMeta
+            governance={governance}
+            badge={badge}
+            replaces={replaces}
+            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}
+          />
+        ) : (
+          // …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>
   );
@@ -194,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) } } } : {}),
   };
 }