@panaversity/ksor 0.0.39 → 0.0.41

package/templates/scaffold/system/site/components/governance.tsx

@@ -1,21 +1,29 @@
 import Link from "next/link";
 
 import { DocumentActions } from "@/components/document-actions";
+import { Clock } from "lucide-react";
 import type { ReactElement } from "react";
 
 import {
-  caveatStatus,
-  statusTone,
+  badgeAddsToStatus,
+  badgeText,
+  badgeTone,
+  dayOf,
   isCalendarDate,
+  plainBadge,
   sourceHref,
+  statusLabel,
+  statusTone,
+  trustSignal,
   type DocumentGovernance,
 } from "@/lib/governance";
+import type { LifecycleBadge } from "@/lib/lifecycle-rule";
 
 /**
  * What the record says about the document you are reading.
  *
  * The site renders the record; these render the record's governance — the
- * frontmatter `pnpm check` enforces on every document. Nothing here is
+ * profile's frontmatter `pnpm check` enforces on every concept. Nothing here is
  * authored in the site (critical rule 1) and nothing is inferred: a key the
  * document does not declare renders nothing at all.
  *
@@ -26,9 +34,9 @@ import {
  */
 
 /**
- * The successor of a superseded document: its route and the text naming it.
- * `href` is null when the pointer could not be resolved to a route, and then
- * the pointer itself is shown as text rather than as a dead link.
+ * The successor of a deprecated document: its route and the text naming it.
+ * `href` is null when the pointer could not be resolved to a route in this
+ * build, and then the pointer itself is shown as text rather than as a dead link.
  */
 export interface Successor {
   readonly href: string | null;
@@ -36,11 +44,12 @@ export interface Successor {
 }
 
 /**
- * The supersession notice. Deliberately the first thing on the page, above the
+ * The deprecation notice. Deliberately the first thing on the page, above the
  * title: a reader must not have to notice a subtle badge to learn that what
- * they are about to read has been replaced.
+ * they are about to read has been withdrawn. `successor` is null when the
+ * record deprecated the document without naming a replacement.
  */
-export function SupersededNotice({ successor }: { successor: Successor }): ReactElement {
+export function DeprecatedNotice({ successor }: { successor: Successor | null }): ReactElement {
   return (
     <aside
       // A landmark, not a note: GOV.UK ships this as role="region" with
@@ -48,7 +57,7 @@ export function SupersededNotice({ successor }: { successor: Successor }): React
       // thing on the page by landmark, rather than only meeting it in reading
       // order. role="note" is announced but not navigable.
       role="region"
-      aria-labelledby="ksor-superseded"
+      aria-labelledby="ksor-deprecated"
       // Tinted and ruled down the left edge in the CAUTION role, never
       // --color-fd-muted: the shipped light theme defines --color-fd-muted and
       // --color-fd-background as the same value, so the callout composited to
@@ -56,22 +65,29 @@ export function SupersededNotice({ successor }: { successor: Successor }): React
       // Chromium, 2026-08-20). The one thing this notice cannot be is missable.
       className="ksor-caution mb-8 rounded-lg border border-l-4 px-4 py-3 text-sm"
     >
-      <p id="ksor-superseded" className="font-medium text-fd-foreground">
-        Superseded
+      <p id="ksor-deprecated" className="font-medium text-fd-foreground">
+        Deprecated
       </p>
       <p className="mt-1 text-fd-muted-foreground">
-        This document has been replaced by{" "}
-        {successor.href === null ? (
-          <code className="break-words text-fd-foreground">{successor.label}</code>
+        {successor === null ? (
+          "The record has withdrawn this document."
         ) : (
-          <Link
-            href={successor.href}
-            className="font-medium text-fd-foreground underline underline-offset-4 transition-colors hover:text-fd-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring"
-          >
-            {successor.label}
-          </Link>
-        )}
-        . It is kept because the record never deletes what it replaces.
+          <>
+            This document has been replaced by{" "}
+            {successor.href === null ? (
+              <code className="break-words text-fd-foreground">{successor.label}</code>
+            ) : (
+              <Link
+                href={successor.href}
+                className="font-medium text-fd-foreground underline underline-offset-4 transition-colors hover:text-fd-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring"
+              >
+                {successor.label}
+              </Link>
+            )}
+            .
+          </>
+        )}{" "}
+        It is kept because the record never deletes what it replaces.
       </p>
     </aside>
   );
@@ -88,13 +104,10 @@ function Fact({
     <div className="flex items-baseline gap-2.5">
       {/* Mono, uppercase, letterspaced: these are the record's checkable facts,
           and they read as a register's column heads rather than as a form.
-
           The label is deliberately SMALLER and more letterspaced than the value
-          it introduces. Both used to be mono a single pixel apart — 11px label
-          against a 12px value — so "Owner Product Effective 2026-08-22" read as
-          one undifferentiated mono run rather than as two facts with names
-          (reported by the owner, 2026-08-22, quoting the run back verbatim).
-          The step is now 10px against 13px, and the value carries the weight. */}
+          it introduces (10px against 13px), so "Owner Product Effective
+          2026-08-22" reads as two facts with names rather than one mono run
+          (reported by the owner, 2026-08-22). */}
       <dt className="font-mono text-[0.625rem] tracking-[0.18em] text-fd-muted-foreground uppercase">
         {label}
       </dt>
@@ -105,44 +118,163 @@ function Fact({
   );
 }
 
+/** One chip: a word the record says about this document, in the register's voice. */
+function Chip({ text, tone = "" }: { text: string; tone?: string }): ReactElement {
+  return (
+    <span
+      className={`rounded-sm border border-fd-border px-1.5 py-0.5 tracking-widest whitespace-nowrap uppercase ${tone}`}
+    >
+      {text}
+    </span>
+  );
+}
+
+/** The chip a badge wears, in every listing and on the page. */
+export function BadgeChip({
+  badge,
+  effectiveFrom = null,
+}: {
+  badge: LifecycleBadge;
+  /** `ksor.effective_from`, which fills record spec §2.5's "effective from …". */
+  effectiveFrom?: string | null;
+}): ReactElement {
+  return <Chip text={badgeText(badge, effectiveFrom) ?? ""} tone={badgeTone(badge)} />;
+}
+
 /**
- * The one-line governance strip under the document's title: any caveat on its
- * status, who stands behind it, and when it took effect.
+ * The lifecycle caveat ALONE, for a page with no governance strip under its
+ * title — a record whose `site.governance` is off.
+ *
+ * That key turns off attribution, not caveats: the deprecation notice has
+ * always survived it, and the sidebar row, the folder card and the search
+ * result for this same document carry their badge whatever it says. The rule
+ * for which states reach here is `plainBadge`, beside the vocabulary itself.
+ *
+ * Typed like the strip's own values (mono, 13px), because a badge is the
+ * record speaking about a document and that is the voice it speaks in
+ * everywhere else.
+ */
+export function LifecycleCaveat({
+  badge,
+  effectiveFrom = null,
+}: {
+  badge: LifecycleBadge | null;
+  effectiveFrom?: string | null;
+}): ReactElement | null {
+  const caveat = plainBadge(badge);
+  if (caveat === null) return null;
+  return (
+    <div className="mb-7 font-mono text-[0.8125rem] font-medium text-fd-foreground">
+      <BadgeChip badge={caveat} effectiveFrom={effectiveFrom} />
+    </div>
+  );
+}
+
+/**
+ * The one-line governance strip under the document's title: what the record
+ * says about this document, and who said it.
+ *
+ * Two kinds of thing sit here and they are drawn differently on purpose. The
+ * CHIPS are states — the lifecycle status, and the date badge when the calendar
+ * keeps an otherwise current document off the machine surfaces (record spec
+ * §2.5) — and the FACTS are attributions: who owns it, who approved it, who
+ * verified it and when. A reader deciding whether to act on a document needs
+ * both halves, and the predecessor's failure was showing neither.
  */
 export function GovernanceMeta({
   governance,
+  badge,
   replaces = [],
   markdownUrl,
+  minutes,
 }: {
   governance: DocumentGovernance;
+  /** Why the machine surfaces decline this page, or null. */
+  badge: LifecycleBadge | null;
   /** Documents this one replaced — derived from the record, never declared. */
   replaces?: readonly Successor[];
-  /** The document's markdown twin, offered beside its governance. */
+  /** The document's markdown twin, offered beside its governance — only where one exists. */
   markdownUrl?: string;
-}): ReactElement | null {
-  const { owner, effective } = governance;
-  const status = caveatStatus(governance.status);
-  const bare = status === null && owner === null && effective === null && replaces.length === 0;
-  if (bare && markdownUrl === undefined) return null;
+  /**
+   * How long the document takes to read, when this row is the only place for
+   * it — a document with a summary shows it on that view's own strip instead,
+   * because there the number belongs to the view you picked.
+   */
+  minutes?: number;
+}): ReactElement {
+  const { status, owner, effectiveFrom, staleAfter, approval, deprecated } = governance;
+  const state = statusLabel(status);
+  // The badge is a SECOND chip only where it says something the status does
+  // not: `draft` and `deprecated` are both words, and printing either twice
+  // reads as two facts about one document.
+  const alsoBadge = badgeAddsToStatus(badge, status) ? badge : null;
+  const trust = trustSignal(governance.verified);
+  // …and where the badge carries the date, the fact beside it would repeat it.
+  const showEffective = effectiveFrom !== null && alsoBadge !== "effective-from";
 
+  // There is no "nothing to show" case any more: every concept has a trust
+  // tier, `unverified` included, and that is the whole point of printing it.
+  // The early return this replaced would have hidden the tier on exactly the
+  // documents whose tier is the only governance fact they have.
   return (
     <dl className="mb-7 flex flex-wrap items-baseline gap-x-8 gap-y-2.5 border-b border-fd-border pb-4">
-      {status === null ? null : (
+      {state === null && alsoBadge === null ? null : (
         <Fact label="Status">
-          <span
-            className={`rounded-sm border border-fd-border px-1.5 py-0.5 tracking-widest uppercase ${statusTone(status)}`}
-          >
-            {status}
+          <span className="flex flex-wrap items-baseline gap-1.5">
+            {state === null ? null : <Chip text={state} tone={statusTone(status)} />}
+            {alsoBadge === null ? null : (
+              <BadgeChip badge={alsoBadge} effectiveFrom={effectiveFrom} />
+            )}
           </span>
         </Fact>
       )}
+      {/* The tier OKF's own vocabulary names, on every document including the
+          unverified ones — that is the honest state of a stable, approved
+          concept nobody has reviewed, and hiding it would leave a reader unable
+          to tell "checked" from "never mentioned" (research/okf-native.md
+          §1.1). Never a colour: a tier is a fact about review, not a warning. */}
+      <Fact label="Trust">
+        <span className="flex flex-wrap items-baseline gap-1.5">
+          <Chip text={trust.tier} />
+          {trust.by === null ? null : (
+            <span className="font-normal text-fd-muted-foreground">
+              {trust.by}
+              {trust.at === null ? null : <> · {day(trust.at)}</>}
+            </span>
+          )}
+        </span>
+      </Fact>
       {owner === null ? null : <Fact label="Owner">{owner}</Fact>}
+      {/* Who let this into the record. `ksor.approval` is what makes a `stable`
+          document stable at all (record spec §2.2), so a page that showed the
+          word and not the signature would be publishing the claim without its
+          author. */}
+      {approval === null ? null : (
+        <Fact label="Approved">
+          <>
+            {approval.by} · {day(approval.at)}
+          </>
+        </Fact>
+      )}
+      {/* found live 2026-08-25: a deprecated page named its successor and said
+          nothing about WHO withdrew it, though `ksor.deprecated` is required on
+          every deprecated concept (record spec §2.2) and readGovernance already
+          refuses a document that omits it. Withdrawal is the most consequential
+          act in a document's life; publishing it unattributed is exactly the
+          gap the approver fact above closes at the other end. */}
+      {deprecated === null ? null : (
+        <Fact label="Withdrawn">
+          <>
+            {deprecated.by} · {day(deprecated.at)}
+          </>
+        </Fact>
+      )}
       {replaces.length === 0 ? null : (
         // The other half of a supersession. The withdrawn document names its
         // successor above the title; this is the successor naming what it
         // replaced, so the history the record kept is reachable from the
         // current document instead of only from the retired one.
-        <Fact label={replaces.length === 1 ? "Replaces" : "Replaces"}>
+        <Fact label="Replaces">
           <>
             {replaces.map((entry, index) => (
               <span key={entry.href ?? `${index}-${entry.label}`}>
@@ -162,77 +294,77 @@ export function GovernanceMeta({
           </>
         </Fact>
       )}
-      {effective === null ? null : (
-        <Fact label="Effective">
-          {/* The machine attribute is stamped only for a real day on the
-              calendar. A SHAPE test was not enough: the checker's own remedy
-              for `2026-06-31` is to QUOTE it, and quoted text arrives here — so
-              a shape test published `<time dateTime="2026-06-31">`, which is
-              invalid HTML and which a consumer reads as July 1st. That is the
-              precise hazard the record's date rule exists to prevent. */}
-          {isCalendarDate(effective) ? (
-            <time dateTime={effective}>{effective}</time>
-          ) : (
-            <span>{effective}</span>
-          )}
-        </Fact>
+      {effectiveFrom === null || !showEffective ? null : (
+        <Fact label="Effective from">{day(effectiveFrom)}</Fact>
       )}
+      {staleAfter === null ? null : <Fact label="Review by">{day(staleAfter)}</Fact>}
       {markdownUrl === undefined ? null : (
         // On the governance row, not as a footnote below the sources: it is
-        // how a reader hands this document to an agent, and it was previously
-        // the smallest text on the page, last (research/site-design.md F2).
-        // ONE control rather than two: opening the markdown and copying it are
-        // different acts, but two bare controls on a row of read-only facts
-        // made the row look half clickable. It wears neither the bordered badge
-        // (that means "a status the record declares") nor the accent at rest —
-        // the page had gone blue enough that the accent had stopped meaning
-        // anything (owner, 2026-08-22).
-        // RIGHT-ALIGNED (owner, and a reversal). The 2026-08-21 finding stands
-        // on its own terms: `ms-auto` once parked this 498px from the nearest
-        // thing on a two-fact document, where it read as belonging to nothing.
-        // What changed is the column beside it — the reading time now sits at
-        // the right end of the strip directly below, so the far edge is no
-        // longer empty space but a line the eye already follows. The two form
-        // a right-hand column of things you DO, against a left-hand row of
-        // things the record DECLARES.
+        // how a reader hands this document to an agent (research/site-design.md
+        // F2). Right-aligned: a column of things you DO, against a row of
+        // things the record DECLARES (owner, 2026-08-22).
         <span className="ms-auto">
           <DocumentActions href={markdownUrl} />
         </span>
       )}
+      {minutes === undefined ? null : (
+        <div className="ms-auto flex items-center gap-2 text-sm text-fd-muted-foreground">
+          <Clock aria-hidden className="size-3.5 shrink-0" />
+          <span>{minutes} min read</span>
+        </div>
+      )}
     </dl>
   );
 }
 
+/** An instant as a day, stamped as machine-readable only when it is a real one. */
+function day(instant: string): ReactElement {
+  const value = dayOf(instant);
+  return isCalendarDate(value) ? <time dateTime={value}>{value}</time> : <span>{value}</span>;
+}
+
 /**
- * Where the document came from.
- *
- * One entry per source, each independently visible — that is the whole point
- * of `provenance` being a list: a citation has to be able to point at exactly
- * one of them. Rendering them as prose would take that away.
+ * Where the document came from: `sources`, one entry each — that is the whole
+ * point of it being a list: a footnote has to be able to point at exactly one
+ * of them. Rendering them as prose would take that away.
  */
-export function Provenance({ entries }: { entries: readonly string[] }): ReactElement | null {
+export function Provenance({
+  entries,
+}: {
+  entries: readonly {
+    readonly id: string | null;
+    readonly title: string | null;
+    readonly resource: string;
+  }[];
+}): ReactElement | null {
   if (entries.length === 0) return null;
 
   return (
     <section className="mt-10 border-t border-fd-border pt-5 text-sm">
       <h2 className="ksor-section-label mb-2">Sources</h2>
-      {/* break-words, because a citation is often a long unbroken URL: on a
+      {/* break-words, because a source is often a long unbroken URL: on a
           phone it overflowed its row by 175px under an ancestor with
           `overflow-x: clip`, so the middle of the source was clipped away with
           no ellipsis and nothing to scroll (measured, 2026-08-20). A source
           nobody can read is not provenance. */}
       <ul className="space-y-1 break-words text-fd-muted-foreground">
         {entries.map((entry, index) => {
-          // An entry that IS a URL becomes followable; a citation stays text.
-          // `rel="noreferrer"` because the destination is authored in the
-          // record, not chosen by this site.
-          const href = sourceHref(entry);
+          // A resource that IS a URL becomes followable; a bundle path or a
+          // scope descriptor stays text. `rel="noreferrer"` because the
+          // destination is authored in the record, not chosen by this site.
+          const href = sourceHref(entry.resource);
+          const label = entry.title ?? entry.resource;
           return (
             // Position, not text: a record may cite the same source twice, and
             // duplicate keys are a console error on a governed page.
-            <li key={`${index}-${entry}`}>
+            <li key={`${index}-${entry.resource}`}>
+              {entry.id === null ? null : (
+                <span className="me-2 font-mono text-xs text-fd-muted-foreground">
+                  [^{entry.id}]
+                </span>
+              )}
               {href === null ? (
-                entry
+                label
               ) : (
                 <a
                   href={href}
@@ -240,7 +372,7 @@ export function Provenance({ entries }: { entries: readonly string[] }): ReactEl
                   rel="noreferrer"
                   className="underline underline-offset-4 transition-colors hover:text-fd-foreground focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring"
                 >
-                  {entry}
+                  {label}
                 </a>
               )}
             </li>

package/templates/scaffold/system/site/components/mdx.tsx

@@ -1,4 +1,7 @@
 import defaultMdxComponents from "fumadocs-ui/mdx";
+
+import { WrappableCodeBlock } from "@/components/code-block";
+import { Embed } from "@/components/embed";
 import { CodeBlockTabsTrigger } from "fumadocs-ui/components/codeblock";
 import { Tab, Tabs } from "fumadocs-ui/components/tabs";
 import type { MDXComponents } from "mdx/types";
@@ -32,9 +35,14 @@ export function getMDXComponents(components?: MDXComponents) {
     // here or a document whose page forgot to pass one serves a 500 rather
     // than a page without an aid.
     TeachingAid: () => null,
+    // A long line is the reader's to unwrap, per block — see
+    // components/code-block.tsx. Replaces fumadocs' own `pre`.
+    pre: WrappableCodeBlock,
+    // `rehypeEmbeds` (source.config.ts) rewrites a link titled `embed` into
+    // this; an unknown component fails the build, so it has to be in the map.
+    Embed,
     // `remarkCodeTab` (source.config.ts) rewrites consecutive fenced blocks
-    // that declare `tab="…"` into these, so they have to be in the map or the
-    // build fails on an unknown component rather than at authoring time.
+    // that declare `tab="…"` into these, for the same reason.
     Tabs,
     Tab,
     CodeBlockTabsTrigger: BrandedTabsTrigger,

package/templates/scaffold/system/site/components/record-index.tsx

@@ -2,7 +2,7 @@ import { ArrowRight, FileText, Folder } from "lucide-react";
 import Link from "next/link";
 import type { ReactElement } from "react";
 
-import { statusTone } from "@/lib/governance";
+import { badgeLabel, badgeTone } from "@/lib/governance";
 import type { RecordEntry } from "@/lib/source";
 
 /**
@@ -28,7 +28,7 @@ import type { RecordEntry } from "@/lib/source";
  *
  * What survives from the register is the part that was never about looks: the
  * record's serif for its own words, mono for what the record says ABOUT them —
- * who owns it, how much it holds, whether it carries a caveat — and `approved`
+ * who owns it, how much it holds, whether it carries a caveat — and `stable`
  * staying silent, because a label on every row is a label nobody reads.
  *
  * Server-rendered plain markup — it survives print, a failed bundle and
@@ -70,11 +70,11 @@ export function RecordIndex({
                     <span className="font-display text-lg leading-snug font-semibold tracking-[-0.008em] transition-colors group-hover:text-fd-primary">
                       {entry.title}
                     </span>
-                    {entry.status === null ? null : (
+                    {entry.badge === null ? null : (
                       <span
-                        className={`rounded-sm border border-fd-border px-1.5 py-0.5 font-mono text-[10px] tracking-widest text-fd-foreground uppercase ${statusTone(entry.status)}`}
+                        className={`rounded-sm border border-fd-border px-1.5 py-0.5 font-mono text-[10px] tracking-widest text-fd-foreground uppercase ${badgeTone(entry.badge)}`}
                       >
-                        {entry.status}
+                        {badgeLabel(entry.badge)}
                       </span>
                     )}
                   </span>

package/templates/scaffold/system/site/components/record-stack.tsx

@@ -1,7 +1,8 @@
 import Link from "next/link";
 import type { ReactElement } from "react";
 
-import { statusTone } from "@/lib/governance";
+import { badgeLabel, badgeTone } from "@/lib/governance";
+import type { LifecycleBadge } from "@/lib/lifecycle-rule";
 import type { RecordEntry } from "@/lib/source";
 
 /**
@@ -53,7 +54,7 @@ export function RecordStack({
           <span className="font-mono text-[10px] tracking-[0.2em] text-[var(--ksor-cover-muted)] uppercase">
             Opens here
           </span>
-          {lead.status === null ? null : <StatusChip status={lead.status} />}
+          {lead.badge === null ? null : <StatusChip badge={lead.badge} />}
         </div>
 
         <h2 className="mt-4 font-display text-2xl leading-snug font-semibold tracking-[-0.008em] transition-colors group-hover:text-fd-primary">
@@ -99,7 +100,7 @@ export function RecordStack({
               {entry.documents === 0
                 ? null
                 : `${entry.documents} ${entry.documents === 1 ? "doc" : "docs"}`}
-              {entry.status === null ? null : <StatusChip status={entry.status} />}
+              {entry.badge === null ? null : <StatusChip badge={entry.badge} />}
             </span>
           </span>
         </Link>
@@ -116,16 +117,16 @@ export function RecordStack({
 }
 
 /**
- * A caveat status, in the same chip the record's listings use — only ever
- * `draft`, `review` or `superseded`, because a reader already assumes a
- * document in the record is current.
+ * A caveat badge, in the same chip the record's listings use — only ever a
+ * state the machine surfaces decline (record spec §2.5), because a reader
+ * already assumes a document in the record is current and stable.
  */
-function StatusChip({ status }: { status: string }): ReactElement {
+function StatusChip({ badge }: { badge: LifecycleBadge }): ReactElement {
   return (
     <span
-      className={`rounded-sm border border-[var(--ksor-cover-rule)] px-1.5 py-0.5 font-mono text-[10px] tracking-widest text-[var(--ksor-cover-foreground)] uppercase ${statusTone(status)}`}
+      className={`rounded-sm border border-[var(--ksor-cover-rule)] px-1.5 py-0.5 font-mono text-[10px] tracking-widest text-[var(--ksor-cover-foreground)] uppercase ${badgeTone(badge)}`}
     >
-      {status}
+      {badgeLabel(badge)}
     </span>
   );
 }

package/templates/scaffold/system/site/components/record-views.tsx

@@ -146,23 +146,12 @@ export function RecordViews({
     [select, views],
   );
 
-  // No summary, so no tabs — but the strip row still carries the reading time.
-  // It sits here rather than up with the title because this row is about the
-  // reading you are ABOUT to do, and a lone line above the facts row read as
-  // floating between two things it belonged to neither of.
-  if (only) {
-    return (
-      <div className="ksor-views">
-        {documentMinutes === undefined ? null : (
-          <p className="mb-6 flex items-center justify-end gap-2 border-b border-fd-border pb-2.5 text-sm text-fd-muted-foreground">
-            <Clock aria-hidden className="size-3.5 shrink-0" />
-            <span>{documentMinutes} min read</span>
-          </p>
-        )}
-        {children}
-      </div>
-    );
-  }
+  // No summary, so no tabs — and so no strip. It used to keep the row anyway,
+  // for the reading time alone: a full-width rule under an empty band with one
+  // number at its far end, which is what most documents got, because most have
+  // no summary. The number moved to the governance row, where it sits with the
+  // document's other facts and needs no furniture of its own.
+  if (only) return <div className="ksor-views">{children}</div>;
 
   return (
     <div className="ksor-views">

package/templates/scaffold/system/site/components/sidebar-status.tsx

@@ -1,35 +1,36 @@
-import type { ReactElement } from "react";
+import type { ReactElement, ReactNode } from "react";
 
-import { caveatStatus, statusTone } from "@/lib/governance";
+import { badgeLabel, badgeTone } from "@/lib/governance";
+import type { LifecycleBadge } from "@/lib/lifecycle-rule";
 
 /**
- * The sidebar's status marker, rendered by the shell's own status-badges
- * plugin (`lib/source.ts`).
+ * The sidebar's badge, drawn beside a row's name (`lib/source.ts` composes it
+ * into the page tree while sorting it).
  *
  * The sidebar is where a reader chooses. Without this, a withdrawn document and
  * the one that replaced it were pixel-identical rows — the governance appeared
  * only after the click, which is the moment it is least useful
  * (research/site-design.md F3).
  *
- * Only a CAVEAT is drawn. `approved` returns null, because a reader already
- * assumes a document in the record is current and a label that never varies
- * stops being read — so the marker stays rare enough to be noticed on the rows
- * where it matters. That rule is ours; the walk over the tree is the shell's.
+ * Only a BADGE is drawn — a state the machine surfaces decline (record spec
+ * §2.5). A current document shows nothing, because a reader already assumes a
+ * document in the record is current and a label that never varies stops being
+ * read; the marker stays rare enough to be noticed on the rows where it matters.
  */
-export function renderCaveatBadge(status: string): ReactElement | null {
-  const caveat = caveatStatus(status);
-  if (caveat === null) return null;
-  // `inline-block` with the row's own wrapping, not a flex wrapper: the plugin
-  // composes `<>{name}{badge}</>` with no element around the pair, so the badge
+export function renderBadge(name: ReactNode, badge: LifecycleBadge): ReactElement {
+  // `inline-block` with the row's own wrapping, not a flex wrapper: the badge
   // has to survive beside a title that runs two lines in a ~200px column. An
   // earlier hand-rolled version pinned the chip right with `truncate`, which
   // clipped the title AND the chip to "sup…" (seen in Chromium, 2026-08-21) —
   // the marker has to fit around the name, not fight it.
   return (
-    <span
-      className={`ms-1.5 inline-block rounded border border-fd-border px-1 py-px align-middle text-[0.6rem] font-medium whitespace-nowrap text-fd-muted-foreground ${statusTone(caveat)}`}
-    >
-      {caveat}
-    </span>
+    <>
+      {name}
+      <span
+        className={`ms-1.5 inline-block rounded border border-fd-border px-1 py-px align-middle text-[0.6rem] font-medium whitespace-nowrap text-fd-muted-foreground ${badgeTone(badge)}`}
+      >
+        {badgeLabel(badge)}
+      </span>
+    </>
   );
 }