@panaversity/ksor 0.0.39 → 0.0.41

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);
 }
@@ -678,13 +686,53 @@ html > body[data-scroll-locked] {
   font-weight: 500;
   letter-spacing: 0.14em;
   text-transform: uppercase;
-  color: var(--color-fd-muted-foreground);
+  /* The record's own accent, at reading strength. The labels were grey on
+     near-white and the head did not read as a head at all — on a three-column
+     table the eye had to work out which row was the label. */
+  color: color-mix(in oklab, var(--color-fd-primary) 72%, var(--color-fd-foreground));
+  background: color-mix(in oklab, var(--color-fd-primary) 7%, var(--color-fd-muted));
+}
+
+/* The head is a band, so it is ruled off from the body rather than floating
+   above it — and the rule is the accent's, not the hairline's, so the two read
+   as one object. */
+#nd-page .prose thead {
+  border-bottom: 2px solid color-mix(in oklab, var(--color-fd-primary) 28%, var(--color-fd-border));
+}
+
+.dark #nd-page .prose thead th {
+  /* Against near-black the same 7% is almost nothing, and the same 72% ink is
+     too bright to sit under body text. */
+  color: color-mix(in oklab, var(--color-fd-primary) 60%, var(--color-fd-foreground));
+  background: color-mix(in oklab, var(--color-fd-primary) 12%, var(--color-fd-muted));
 }
 
 #nd-page .prose tbody tr {
   border-bottom: 1px solid var(--color-fd-border);
 }
 
+/* And every other row carries a wash. A hairline alone is enough on a
+   two-column table; across three columns of wrapped prose the eye loses which
+   cells belong together, because the gap between rows and the gap between
+   lines INSIDE a cell are the same distance. The band is what holds a row
+   together over that distance.
+
+   Faint on purpose: it groups, it does not label. Anything stronger competes
+   with the head, which is the row that is meant to be read first. */
+#nd-page .prose tbody tr:nth-child(even) {
+  background: var(--color-fd-background);
+}
+
+#nd-page .prose tbody tr:nth-child(odd) {
+  background: color-mix(in oklab, var(--color-fd-border) 14%, var(--color-fd-muted));
+}
+
+.dark #nd-page .prose tbody tr:nth-child(odd) {
+  /* A step of the same SIZE reads much stronger against near-black, so the
+     dark pair takes less of the border to land at the same apparent distance. */
+  background: color-mix(in oklab, var(--color-fd-border) 8%, var(--color-fd-muted));
+}
+
 #nd-page .prose tbody tr:last-child {
   border-bottom: 0;
 }
@@ -731,6 +779,117 @@ html > body[data-scroll-locked] {
   background: var(--color-fd-muted);
 }
 
+/* A block with no language is not code — it is a passage to reproduce
+   verbatim: a prompt to type, a command to say, a message to paste. This
+   record has eight, and they arrived as walls of tight monospace, set for
+   scanning columns of code when what is in them is sentences.
+
+   The highlighter's own output is the selector, so nothing has to be authored
+   and nothing changes for the record: shiki gives every token in a HIGHLIGHTED
+   block an inline `--shiki-light`, and a plain one has none. `:has()` asks
+   that question directly.
+
+   Prose leading, because the lines are sentences; and the accent down the left
+   edge, which is what the rest of this site uses to mark structure — here it
+   says "reproduce this exactly", which is the one thing these blocks have in
+   common. */
+#nd-page .prose figure.shiki:not(:has(code span[style*="--shiki-light"])) {
+  border-left: 3px solid color-mix(in oklab, var(--color-fd-primary) 55%, var(--color-fd-border));
+}
+
+#nd-page .prose figure.shiki:not(:has(code span[style*="--shiki-light"])) code {
+  line-height: 1.7;
+}
+
+/* Showing the whole of a long line, when the reader asks for it.
+   components/code-block.tsx puts the button on the block and sets the
+   attribute; this is what the attribute means.
+
+   `pre` is `w-max` in the shell, which sizes it to the longest line — that is
+   what makes wrapping impossible, so the width has to come back to the column
+   before `pre-wrap` can do anything. A wrapped line is then indented under its
+   own, the way a terminal marks a continuation, because otherwise a two-line
+   command reads as two commands.
+
+   Wrapping is NOT the default. It was, for one commit, and it is worse for the
+   blocks that do not need it: a yaml file rewrapped at the column reads as
+   though its indentation means something else. */
+#nd-page .prose figure.shiki[data-wrapped] pre {
+  width: 100%;
+  min-width: 0;
+}
+
+#nd-page .prose figure.shiki[data-wrapped] code > * {
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  /* The hang, plus the gutter below — so a continuation is indented from the
+     text, not from the block's edge. */
+  padding-left: calc(1rem + 2ch);
+  text-indent: -2ch;
+}
+
+/* A block needs a gutter on both sides. Unwrapped, the shell gives one on the
+   left with `ps-*` and lets a long line run under the buttons on the right,
+   because the line can always be scrolled clear of them. Wrapped, it cannot:
+   the first line ends under the copy button with no way to move it, and the
+   left edge sits on the rule (seen live). So the wrapped state pays for its
+   own margins — a gutter left, and enough right for two 24px buttons. */
+#nd-page .prose figure.shiki[data-wrapped] code {
+  padding-inline: 0 4rem;
+}
+
+#nd-page .prose figure.shiki[data-wrapped] .fd-scroll-container {
+  padding-inline-start: 0;
+}
+
+/* And a hairline where a scrollbar appears, in place of the platform's slab. */
+#nd-page .prose figure.shiki .fd-scroll-container {
+  scrollbar-width: thin;
+  scrollbar-color: var(--color-fd-border) transparent;
+}
+/* A callout has to look like a callout. The same `bg-fd-card` trap as the code
+   block above: fumadocs paints the panel with `--card`, which in this palette
+   is all but the page colour, so a Note and a Warning both arrived as a white
+   box with a coloured hair down one edge — the kind was legible only in the
+   icon.
+
+   Fumadocs already puts the kind's own colour on the element as
+   `--callout-color`, so ONE rule tints every kind: a wash of that colour over
+   `--muted`, the token that means "a surface on the page". No per-kind
+   selector, and a kind added upstream is tinted without touching this.
+
+   6% in light and 10% in dark, because the same fraction reads as a different
+   amount of colour against near-white and against near-black. Kept low on
+   purpose: this is the record's own accent discipline — the tint says which
+   kind, it does not compete with the prose. */
+#nd-page .prose [style*="--callout-color"] {
+  background: color-mix(in oklab, var(--callout-color) 6%, var(--color-fd-muted));
+  border-color: color-mix(in oklab, var(--callout-color) 20%, var(--color-fd-border));
+  /* The shadow was doing the work the colour now does, and lifted the panel
+     off the page in a way nothing else on it does. */
+  box-shadow: none;
+
+  /* THE RULE DOWN THE LEFT EDGE — the same device the verbatim block uses, so
+     "this passage is set apart" looks the same everywhere it happens, whatever
+     kind of thing is set apart. Fumadocs draws a half-pixel bar INSIDE the
+     panel instead, which is too faint to read as a marker at all.
+
+     In the kind's own colour, which for a Note — much the commonest — is the
+     accent, so the standard case is the blue line. */
+  border-left: 3px solid color-mix(in oklab, var(--callout-color) 65%, var(--color-fd-border));
+}
+
+/* And the inner bar goes, now that the edge carries it. Two rules for the same
+   job, a pixel apart, read as a mistake. */
+#nd-page .prose [style*="--callout-color"] > div[class*="w-0.5"] {
+  display: none;
+}
+
+.dark #nd-page .prose [style*="--callout-color"] {
+  background: color-mix(in oklab, var(--callout-color) 10%, var(--color-fd-muted));
+  border-color: color-mix(in oklab, var(--callout-color) 24%, var(--color-fd-border));
+}
+
 /* Re-assert the shell's own reset, which the ramp above broke. The prose
    plugin zeroes the first block's top margin, but writes that rule as
    `.prose :where(> :first-child)`, and `:where()` contributes nothing to
@@ -743,6 +902,39 @@ html > body[data-scroll-locked] {
   margin-top: 0;
 }
 
+/* A numbered list is a sequence, and its numbers should say so. The marker
+   arrived grey at regular weight, lighter than the text it counts, so a list
+   of six steps read as six paragraphs that happened to start with digits.
+
+   The accent, and only here: a number is structure, which is what this
+   record's accent is for. */
+#nd-page .prose ol > li::marker {
+  color: var(--color-fd-primary);
+  font-weight: 600;
+}
+
+/* And the TERM a list item defines. `**Heartbeat:** a schedule that…` is the
+   commonest shape in this record — a term, then what it means — and the term
+   is the thing a reader scans for.
+
+   Only the term. Bold elsewhere in the sentence stays ink, because a page
+   where every emphasis is coloured has no emphasis: the accent stops meaning
+   "this is the one to find" and starts meaning "this is bold". */
+#nd-page .prose li > strong:first-child,
+#nd-page .prose li > p:first-child > strong:first-child {
+  color: var(--color-fd-primary);
+}
+
+/* The same rule, one level in. The document's first block is not a child of
+   `.prose` — it is inside the views wrapper, and inside a tab panel when the
+   document has a summary — so the reset above never reached it and the top of
+   every document sat 20px lower than the rule above it intended (measured
+   after the empty view strip was removed, which is what exposed it). */
+#nd-page .prose > .ksor-views > :first-child,
+#nd-page .prose > .ksor-views [role="tabpanel"] > :first-child {
+  margin-top: 0;
+}
+
 /* ── The page pager ──────────────────────────────────────────────────────────
    Fumadocs lays the neighbours out as a grid that becomes two columns when both
    exist. With only one — the first or last document of the record — it stays a

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 });
 }

package/templates/scaffold/system/site/components/code-block.tsx

@@ -0,0 +1,87 @@
+"use client";
+
+import { CodeBlock, Pre } from "fumadocs-ui/components/codeblock";
+import { WrapText } from "lucide-react";
+import { useCallback, useEffect, useRef, useState, type ReactElement } from "react";
+
+/**
+ * A code block that can be asked to show the whole line.
+ *
+ * A record's commands are long — one in the fixture runs to 292 characters —
+ * and in a 672px column that is a scrollbar, with the left edge of every line
+ * going out of view as you drag it. Wrapping everything by default was tried
+ * and is worse for the blocks that do not need it: a yaml file rewrapped at
+ * the column reads as though its indentation means something else.
+ *
+ * So the reader decides, per block. The button appears ONLY on a block that
+ * actually overflows, which is measured after layout rather than guessed —
+ * most blocks fit, and a control that does nothing is worse than no control.
+ *
+ * The `Actions` slot is fumadocs' own, so the button sits with the copy button
+ * and inherits its placement rather than being positioned against it.
+ */
+export function WrappableCodeBlock(props: React.ComponentProps<"pre">): ReactElement {
+  const figure = useRef<HTMLElement>(null);
+  const [overflows, setOverflows] = useState(false);
+  const [wrapped, setWrapped] = useState(false);
+
+  const measure = useCallback((): void => {
+    const viewport = figure.current?.querySelector<HTMLElement>(".fd-scroll-container");
+    if (!viewport) return;
+    // While wrapped there is nothing to overflow, so the question is only
+    // asked in the state that can answer it — otherwise turning wrapping on
+    // would remove the button that turns it off.
+    setOverflows((was) => (wrapped ? was : viewport.scrollWidth > viewport.clientWidth + 1));
+  }, [wrapped]);
+
+  useEffect(() => {
+    measure();
+    if (typeof ResizeObserver === "undefined") return;
+    const viewport = figure.current?.querySelector<HTMLElement>(".fd-scroll-container");
+    if (!viewport) return;
+    // The column changes width with the window, and with the table of contents
+    // appearing; a block that fits at one width overflows at another.
+    const observer = new ResizeObserver(measure);
+    observer.observe(viewport);
+    return () => observer.disconnect();
+  }, [measure]);
+
+  return (
+    <CodeBlock
+      ref={figure}
+      data-wrapped={wrapped ? "" : undefined}
+      Actions={({ className, children }) => (
+        // `children` IS the copy button — fumadocs hands the default actions
+        // in, and a slot that ignores them REPLACES the copy button instead of
+        // joining it (found live: the block lost copy entirely). The wrapper
+        // mirrors the default's own `empty:hidden`, so a block with neither
+        // button still renders nothing.
+        <div className={`flex items-center empty:hidden ${className ?? ""}`}>
+          {children}
+          {overflows ? (
+            <button
+              type="button"
+              aria-pressed={wrapped}
+              onClick={() => setWrapped((on) => !on)}
+              // The copy button's own metrics — measured, not guessed: 24x24
+              // with a 3.5 icon. Mine came out 30x30 and the pair read as two
+              // controls of different importance.
+              className="inline-flex size-6 items-center justify-center rounded-lg transition-colors hover:bg-fd-accent hover:text-fd-accent-foreground [&_svg]:size-3.5"
+              // Said as what it does, not as what it is: the reader wants the
+              // rest of the line, not a setting.
+              title={wrapped ? "Show one line per line" : "Show the whole line"}
+            >
+              <WrapText aria-hidden />
+              <span className="sr-only">
+                {wrapped ? "Show one line per line" : "Show the whole line"}
+              </span>
+            </button>
+          ) : null}
+        </div>
+      )}
+      {...props}
+    >
+      <Pre>{props.children}</Pre>
+    </CodeBlock>
+  );
+}