@panaversity/ksor 0.0.38 → 0.0.40

package/CHANGELOG.md

@@ -1,5 +1,111 @@
 # @panaversity/ksor
 
+## 0.0.40
+
+### Patch Changes
+
+- cd42f81: Three readability changes to a document's page.
+
+  A long line in a code block can be **unwrapped by the reader**, with a button
+  that appears only on a block that actually overflows. The record's commands run
+  to hundreds of characters, and in a docs column that was a scrollbar with the
+  left edge of every line going out of view. Wrapping is not the default, because
+  it is worse for the blocks that do not need it.
+
+  A table's rows **alternate**, faintly, so a row holds together across three
+  columns of wrapped prose.
+
+  A callout carries a **rule down its left edge**, in its kind's colour — the
+  same device a verbatim block uses, so "this passage is set apart" looks the
+  same everywhere it happens.
+
+- e19f226: A passage a reader must not miss can now be a callout. Write GitHub's alert
+  syntax — a blockquote whose first line is `[!WARNING]` — and the site renders a
+  styled panel tinted with that kind's own colour:
+
+  ```markdown
+  > [!TIP]
+  > Climb one rung at a time, and only when something has gone wrong without it.
+  ```
+
+  It stays a plain blockquote everywhere else the record is read, carrying a
+  visible label, and `/md/` and `llms-full.txt` keep the author's blockquote
+  rather than this site's component.
+
+  Not `:::warning`: a dialect renders as literal punctuation everywhere outside
+  this site.
+
+- 704e949: A document can now show something running, where the prose puts it. Give a link
+  the title `embed` and the site renders it as a click-to-load frame:
+
+  ```markdown
+  [Play run-until-done](goal-loop.sim.html "embed")
+  ```
+
+  It stays an ordinary CommonMark link everywhere else — GitHub, a plain editor,
+  `/md/`, `llms-full.txt` — so nothing was added to `knowledge/`.
+
+  Prefer carrying the page in. A `<name>.sim.html` beside its document, exactly
+  like a figure, is published by the build and served from your own site: it
+  works offline, tells nobody outside what someone is reading, and is versioned
+  with the document. An `https:` link works too, but many hosts send
+  `X-Frame-Options: SAMEORIGIN` and a browser will refuse to frame them.
+
+  Nothing is requested until a reader clicks, so a built page still makes zero
+  external requests. A carried page is measured, so the frame is exactly as tall
+  as what it holds — you never write a height into a document.
+
+- a55e93e: A numbered list now counts in the record's accent, and the term a list item
+  defines takes it too — `**Heartbeat:** a schedule that…` puts the term in
+  accent and leaves the sentence in ink. The markers were grey at regular weight,
+  lighter than the text they counted, so a list of six steps read as six
+  paragraphs that happened to start with digits.
+- a59a7af: The documented way to run `ksor init` pins a version, so a stale runner cache
+  can no longer decide which ksor an adopter meets.
+
+  `npx @panaversity/ksor init my-sor` is spec `*`, and any cached version
+  satisfies it — so npx runs whatever that machine already has without consulting
+  the registry. Found live on a Windows box following the README: it replayed
+  `0.0.0`, the name-reservation stub published on the first day of the project,
+  whose whole implementation prints "the name is reserved; this is not a release"
+  and exits 2. Thirty-nine releases later, the first command in the README
+  produced a placeholder, and nothing in that output points at the cause.
+
+  Both READMEs now say `@panaversity/ksor@latest`. The three "Start here" forms
+  change together — `pnpm dlx` reuses its cache for 24 hours by default and
+  `bunx` resolves from the install cache before the registry, so pinning only npx
+  would have left two of the three supported managers in the trap. `npm install
+-g` is unchanged: an install resolves the `latest` dist-tag by definition.
+
+  If you have run ksor before, your own cache is still warm. Run the `@latest`
+  form once and it resolves the current release.
+
+- 9e92e9e: A document with no summary no longer carries an empty view strip. The reading
+  time moved into the governance row, beside the owner and the effective date,
+  so the commonest document — one with no summary — gets one bar of facts rather
+  than a second bar holding a single number at the far end of a rule.
+- d723487: A table's head now reads as a head: the record's accent as a wash behind it,
+  the column labels in that accent's ink, and an accent rule under the band. They
+  were grey on near-white, so on a three-column table the eye had to work out
+  which row was the label.
+- 8ec1a10: A fenced block with no language is set as a passage to reproduce rather than as
+  code: prose leading, and the record's accent down its left edge. Prompts,
+  commands to say and messages to paste were arriving as walls of tight
+  monospace, set for scanning columns of code when what is in them is sentences.
+
+  Nothing to author — the highlighter's own output is the signal, so a block that
+  was never highlighted is the one that changes.
+
+## 0.0.39
+
+### Patch Changes
+
+- b6a3853: A malformed `KSOR_SNAPSHOT_KEYS` entry no longer has its text echoed into the
+  refusal message. The likeliest operator mistake — pasting a bare secret without
+  its `kid=` prefix — put that secret verbatim into an error that lands in
+  whatever collects logs. The refusal now names the entry's position and length
+  only, and keeps the remedy line.
+
 ## 0.0.38
 
 ### Patch Changes

package/README.md

@@ -10,7 +10,7 @@ when the corpus does not cover the question.
 ## Start
 
 ```bash
-npx @panaversity/ksor init my-sor
+npx @panaversity/ksor@latest init my-sor
 cd my-sor
 pnpm install
 pnpm dev        # the site, live at http://localhost:3000
@@ -32,6 +32,22 @@ scaffold is deterministic and offline, and every refusal explains itself.
 > and the released version number are authoritative for the exact released
 > functionality.
 
+### What a document can do
+
+`knowledge/` is CommonMark, and stays CommonMark — every affordance below is
+syntax that other readers already handle, so a record renders honestly on
+GitHub, in a plain editor, at `/md/` and in `llms-full.txt`.
+
+| Write | The site renders |
+| ----- | ---------------- |
+| `> [!WARNING]` as a blockquote's first line | a callout, tinted in that kind's colour |
+| ` ```bash tab="Claude Code" ` on consecutive fences | one tab group, the choice remembered |
+| a fence with no language | a passage to reproduce, set for reading |
+
+Nothing to author for the rest: a table's head reads as a head, a numbered list
+counts in the record's accent, and a code block wider than the column gets a
+button that unwraps it.
+
 ### Study attachments
 
 A document may carry companions named after it, and the site renders each on
@@ -72,7 +88,7 @@ Full concept, design goals, and project status:
 
 ```bash
 npm install -g @panaversity/ksor   # command installed: ksor
-npx @panaversity/ksor              # or run without installing
+npx @panaversity/ksor@latest       # or run without installing
 ```
 
 ## License

package/dist/cli.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { n as resolveCommand, r as verbs, t as exitCodes } from "./src-pl4aOpVs.mjs";
-import { A as runProbe$1, C as keyRingFromEnv, D as prewarmPool, E as pooledEndpointFor, F as withPgRetry$1, I as withProbeDeadline$1, L as z$1, M as storedTextSearchConfig, N as tlsPosture, O as readHandler, P as visibleTiers$1, S as embedQueryVlit, T as parseInstanceText$1, _ as buildShippedProvider$1, a as MAX_OUTLINE_LIMIT, b as contentPool$1, c as MissingProviderKeyError$1, d as READ_OUTPUT, f as SEARCH_OUTPUT, g as assertSchemaCompatible, h as assertGovernanceServable$1, i as GovernanceGateError$1, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, m as TextSearchConfigMismatch, n as EmbeddingSpaceMismatch$1, p as SchemaVersionError, r as FLOOR, s as McpServer$1, t as ContentStoreError$1, u as READ_ONLY, v as checkEmbeddingSpace$1, w as outlineHandler, x as contentPoolMin, y as composeInstructions } from "./gateway-api-6nC9x54K-BWFTI_6U.mjs";
+import { A as runProbe$1, C as keyRingFromEnv, D as prewarmPool, E as pooledEndpointFor, F as withPgRetry$1, I as withProbeDeadline$1, L as z$1, M as storedTextSearchConfig, N as tlsPosture, O as readHandler, P as visibleTiers$1, S as embedQueryVlit, T as parseInstanceText$1, _ as buildShippedProvider$1, a as MAX_OUTLINE_LIMIT, b as contentPool$1, c as MissingProviderKeyError$1, d as READ_OUTPUT, f as SEARCH_OUTPUT, g as assertSchemaCompatible, h as assertGovernanceServable$1, i as GovernanceGateError$1, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, m as TextSearchConfigMismatch, n as EmbeddingSpaceMismatch$1, p as SchemaVersionError, r as FLOOR, s as McpServer$1, t as ContentStoreError$1, u as READ_ONLY, v as checkEmbeddingSpace$1, w as outlineHandler, x as contentPoolMin, y as composeInstructions } from "./gateway-api-CmIthmJS-IUA9qS-T.mjs";
 import { chmodSync, copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { InMemoryTransport, LATEST_PROTOCOL_VERSION, createMcpHandler } from "@modelcontextprotocol/server";
@@ -16,7 +16,7 @@ import { bodyLimit } from "hono/body-limit";
 import { execFileSync, spawnSync } from "node:child_process";
 import { parseArgs } from "node:util";
 import { readFile, readdir, stat } from "node:fs/promises";
-//#region ../content-gateway/dist/main-DdIuyneg.mjs
+//#region ../content-gateway/dist/main-Cc5BU8p-.mjs
 /**
 * The default registration — and the ORIGINAL of the file `ksor init` emits.
 *
@@ -1583,7 +1583,7 @@ async function withPgRetry(op, options = {}) {
 	throw lastError;
 }
 //#endregion
-//#region ../content/dist/commands-mZxv9bLG.mjs
+//#region ../content/dist/commands-NwtLt0OE.mjs
 /**
 * EVAL-LOCKED constants, quarried verbatim from the oracle
 * (sor-agentfactory @ b554f91, config.py) — changing any of these is a

package/dist/{gateway-api-6nC9x54K-BWFTI_6U.mjs → gateway-api-CmIthmJS-IUA9qS-T.mjs}

@@ -5,7 +5,7 @@ import { z, z as z$1 } from "zod";
 import pg from "pg";
 import path from "node:path";
 import { createHash, createHmac, randomBytes, timingSafeEqual } from "node:crypto";
-//#region ../content-gateway/dist/gateway-api-6nC9x54K.mjs
+//#region ../content-gateway/dist/gateway-api-CmIthmJS.mjs
 /**
 * The record's system prompt: instance.md's body, preserved beneath a framework
 * floor. Lifted out of server.ts so the public gateway surface can re-export
@@ -1352,9 +1352,9 @@ function keyRingFromEnv(raw) {
 	}
 	const keys = /* @__PURE__ */ new Map();
 	let active = null;
-	for (const part of raw.split(",")) {
+	for (const [i, part] of raw.split(",").entries()) {
 		const eq = part.indexOf("=");
-		if (eq <= 0 || eq === part.length - 1) throw new Error(`KSOR_SNAPSHOT_KEYS entry ${JSON.stringify(part)} is not kid=secret — a half-parsed key ring would mint tokens nothing can validate; write comma-separated kid=secret pairs, first one active`);
+		if (eq <= 0 || eq === part.length - 1) throw new Error(`KSOR_SNAPSHOT_KEYS entry ${i + 1} (${part.length} chars) is not kid=secret — a half-parsed key ring would mint tokens nothing can validate; write comma-separated kid=secret pairs, first one active`);
 		const kid = part.slice(0, eq).trim();
 		keys.set(kid, Buffer.from(part.slice(eq + 1), "utf8"));
 		active = active ?? kid;

package/dist/gateway.mjs

@@ -1,2 +1,2 @@
-import { L as z$1, O as readHandler, a as MAX_OUTLINE_LIMIT, d as READ_OUTPUT, f as SEARCH_OUTPUT, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, o as MAX_SEARCH_K, r as FLOOR, s as McpServer$1, u as READ_ONLY, w as outlineHandler, y as composeInstructions } from "./gateway-api-6nC9x54K-BWFTI_6U.mjs";
+import { L as z$1, O as readHandler, a as MAX_OUTLINE_LIMIT, d as READ_OUTPUT, f as SEARCH_OUTPUT, j as searchHandler, k as recordIsUndescribed, l as OUTLINE_OUTPUT, o as MAX_SEARCH_K, r as FLOOR, s as McpServer$1, u as READ_ONLY, w as outlineHandler, y as composeInstructions } from "./gateway-api-CmIthmJS-IUA9qS-T.mjs";
 export { FLOOR, MAX_OUTLINE_LIMIT, MAX_SEARCH_K, McpServer$1 as McpServer, OUTLINE_OUTPUT, READ_ONLY, READ_OUTPUT, SEARCH_OUTPUT, composeInstructions, outlineHandler, readHandler, recordIsUndescribed, searchHandler, z$1 as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@panaversity/ksor",
-  "version": "0.0.38",
+  "version": "0.0.40",
   "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",
@@ -71,8 +71,8 @@
     "tsdown": "0.22.14",
     "typescript": "7.0.2",
     "vitest": "^4.1.10",
-    "@panaversity/ksor-content-gateway": "0.0.0",
-    "@panaversity/ksor-content": "0.0.0"
+    "@panaversity/ksor-content": "0.0.0",
+    "@panaversity/ksor-content-gateway": "0.0.0"
   },
   "engines": {
     "node": ">=24"

package/templates/scaffold/AGENTS.md

@@ -449,12 +449,14 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   publishes that as fact) and `superseded` (a legacy marker — prefer `status`)
   are available. No other keys; never
   `id:` or `name:` — the path is the identity.
-- **Each page says how long it takes to read**, just above the body, counted from the
-  document's own words when the site is built. Fenced code and frontmatter do
-  not count toward it, so a short page carrying a long example is not reported
-  as a long read. Nothing to author — it is derived. A document with a summary
-  shows the figure on both tabs, so a reader can see at a glance how much the
-  summary saves them.
+- **Each page says how long it takes to read**, counted from the document's own
+  words when the site is built. Fenced code and frontmatter do not count toward
+  it, so a short page carrying a long example is not reported as a long read.
+  Nothing to author — it is derived. It sits with the owner and the effective
+  date, in the row under the title; a document with a SUMMARY moves it onto
+  that view's own strip instead, where it reports the view you are reading
+  rather than the document. Each tab names its own figure to a screen reader,
+  so the cost of each view is available without switching to it.
 - **The governance keys are rendered, so they are worth filling in.** Each
   page shows its owner and effective date under the title, lists every
   `provenance` entry separately at the foot, and — for a superseded document —
@@ -664,6 +666,57 @@ CI — and a first deploy without it serves an empty record. Full walkthrough:
   renders in the site's accent. The list lives in `system/site/app/global.css`
   and is yours — adding a tool is one colour and one mark.
 
+- **A passage the reader must not miss, as a CALLOUT.** GitHub's alert syntax —
+  a blockquote whose first line is the kind in brackets:
+
+  ```markdown
+  > [!WARNING]
+  > This threshold changed in March. The figure below is the old one.
+  ```
+
+  Five kinds: `NOTE`, `TIP`, `IMPORTANT`, `WARNING`, `CAUTION`. The site tints
+  the panel in that kind's colour and rules its left edge; every other reader
+  of the record — GitHub, a plain editor, `/md/`, `llms-full.txt` — shows an
+  ordinary blockquote carrying a visible label, so nothing is lost and nothing
+  becomes punctuation.
+
+  **Not `:::warning`.** That form is a dialect: a record written in one renders
+  as literal colons in every reader except the one site that understands it.
+
+- **A long line is the reader's to unwrap.** Nothing to author — a fenced block
+  wider than the column gets a button beside its copy button that wraps it, and
+  a block that fits gets no button at all.
+- **Something running, as an embed.** A document that wants to show a page in
+  motion — a simulation, a player, a dashboard — links to it and gives the link
+  the title `embed`:
+
+  ```markdown
+  [Play run-until-done](goal-loop.sim.html "embed")
+  ```
+
+  Still CommonMark: a link title is a tooltip everywhere else, so GitHub, a
+  plain editor, `/md/` and `llms-full.txt` all show the author's link. Nothing
+  loads until a reader clicks, which is what keeps a built page free of
+  external requests — and the panel names what it is about to reach, so the
+  click is informed.
+
+  **You do not state a height.** A page carried in the record is measured, so
+  the frame is exactly as tall as what it holds — on this record's own seven,
+  to the pixel. A number written into a document would be a number some other
+  measure makes wrong.
+
+  **Carry the page in where you can.** A file named `<name>.sim.html`, sitting
+  beside its document exactly like a figure, is published by the build and
+  served from this site — so it works offline, tells nobody outside what
+  someone is reading, and is versioned with the document instead of changing
+  under it. It is an ASSET, not an attachment: named freely, as many per
+  document as the prose needs.
+
+  An `https:` link works too, for a page you cannot carry. It is the weaker
+  option for a reason worth knowing: many hosts send `X-Frame-Options:
+SAMEORIGIN`, which forbids any other site from framing them, and a browser
+  enforces that whatever this record does. Check before you rely on one.
+
 - Copy load-bearing values (numbers, thresholds, dates) exactly from their
   source, and name the source in `provenance`.
 

package/templates/scaffold/gitignore

@@ -11,6 +11,9 @@ system/site/.staged-knowledge/
 # and the lock that keeps one evaluation of a build staging at a time; it only
 # outlives a build that was killed mid-stage, and the next build clears it
 system/site/.staged-knowledge.lock
+# a build's copy of every `.sim.html` in the record, put where it can be
+# SERVED; the record owns the sim, this is only where the site publishes it
+system/site/public/sims/
 *.tsbuildinfo
 
 # secrets never enter the record — system/ is their future home (serve)

package/templates/scaffold/knowledge/governance-ladder.md

@@ -18,6 +18,11 @@ record of such documents is already publishable, searchable and citable.
 
 Each rung is worth climbing when the domain asks for it, and not before.
 
+> [!TIP]
+> Climb one rung at a time, and only when something has gone wrong without it.
+> A record that adds owners before anyone disputes a document spends review
+> effort buying nothing.
+
 ### Owners and sources
 
 An owner names who stands behind a document. Provenance names where its claims

package/templates/scaffold/knowledge/surfaces/for-agents.md

@@ -22,6 +22,12 @@ be checked against the document that carries it rather than taken on trust.
 "Not in this record" is a correct answer. It is never an error, and never a
 licence to fall back on what a model happens to remember.
 
+> [!WARNING]
+>
+> An agent that fills a gap from its own memory has not used this record — it
+> has used it as an opening paragraph. Nothing in the answer says which half
+> came from where.
+
 ## Files beside the interface
 
 The build publishes the same knowledge as plain files an agent can fetch without

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

@@ -130,7 +130,15 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
         <DocsTitle>{page.data.title}</DocsTitle>
         <DocsDescription>{page.data.description}</DocsDescription>
         {showGovernance ? (
-          <GovernanceMeta governance={governance} replaces={replaces} markdownUrl={markdownUrl} />
+          <GovernanceMeta
+            governance={governance}
+            replaces={replaces}
+            markdownUrl={markdownUrl}
+            // 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

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

@@ -678,13 +678,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 +771,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 +894,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/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>
+  );
+}