@panaversity/ksor 0.0.19 → 0.0.21

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

@@ -1,6 +1,12 @@
 import { HomeLayout } from "fumadocs-ui/layouts/home";
+
 import { baseOptions } from "@/lib/layout.shared";
 
+// The front door stands ALONE: a navbar with the record's name, search and the
+// theme switch, and nothing else. It wore the full docs chrome briefly
+// (2026-08-22) so the sidebar was present from the first second; the owner's
+// call is that a landing page should land — the sidebar belongs to the record's
+// pages, and `Open the record` is the door to them.
 export default function Layout({ children }: LayoutProps<"/">) {
   return <HomeLayout {...baseOptions()}>{children}</HomeLayout>;
 }

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

@@ -1,83 +1,78 @@
-import Image from "next/image";
-import Link from "next/link";
-// The same file Next serves as the favicon (app/icon.png) — one mark, one
-// asset. Replace it with your own and the tab icon changes with the page.
+import type { ReactElement } from "react";
+
 import mark from "@/app/icon.png";
 import { FooterMark } from "@/components/footer-mark";
-import { appName, appTitle } from "@/lib/shared";
-import { basePath, getSortedPages } from "@/lib/source";
+import { HomeCover } from "@/components/home-cover";
+import { appName, appPurpose, appTitle } from "@/lib/shared";
+import { entriesUnder, entryFor, getSortedPages } from "@/lib/source";
 
-export default function HomePage() {
+/**
+ * The front door of a system of record.
+ *
+ * It has four jobs and no fifth (research/site-design.md §4): say what the
+ * record is authoritative for, name the identity citations carry, open the
+ * record, and point at the surfaces agents read — the last from `/llms.txt`
+ * and each document's markdown twin, where agents already look, rather than
+ * from a list of addresses printed at a reader. Every string comes from
+ * `instance.md` or a document's own frontmatter; the site never contains
+ * authored content (scaffolded AGENTS.md, critical rule 1).
+ *
+ * One full screen, standing alone: no sidebar, no document chrome. The design
+ * lives in components/home-cover; this file's job is to hand it the record.
+ */
+export default function HomePage(): ReactElement {
   // The first document in sidebar order — never a hardcoded path, so deleting
-  // the example the scaffold ships cannot leave a link pointing at nothing.
+  // the example the scaffold ships cannot leave a link pointing at nothing, and
+  // a record that grows a root `index.md` opens on that instead with no change
+  // here.
   const pages = getSortedPages();
   const [first] = pages;
 
-  return (
-    <main className="flex flex-1 flex-col">
-      <div className="mx-auto flex w-full max-w-2xl flex-1 flex-col justify-center px-6 py-24">
-        <Image
-          src={mark}
-          alt=""
-          width={56}
-          height={56}
-          priority
-          className="mb-7 size-14 rounded-xl ring-1 ring-fd-border"
-        />
-
-        {/* The frame is KSoR's; the title is the record's. The headline is
-            instance.md's own H1 — a human name, not the machine slug — so a
-            fresh scaffold reads "Knowledge System of Record" until the
-            intake interview writes the real one. */}
-        <p className="mb-2 text-xs font-medium uppercase tracking-widest text-fd-muted-foreground">
-          KSoR
-        </p>
-        <h1 className="text-4xl font-semibold tracking-tight text-balance break-words sm:text-5xl">
-          {appTitle}
-        </h1>
-        <p className="mt-3 text-lg text-fd-muted-foreground">
-          Knowledge you can govern. Answers you can trace. Boundaries agents can respect.
+  if (first === undefined) {
+    return (
+      <main className="mx-auto w-full max-w-6xl flex-1 px-6 py-20">
+        <p className="text-fd-muted-foreground">
+          the record is empty — add a document to <code>knowledge/</code>
         </p>
+      </main>
+    );
+  }
 
-        {first ? (
-          <div className="mt-9 flex flex-col gap-4">
-            <Link
-              href={first.url}
-              className="group inline-flex w-fit items-center gap-2 rounded-lg bg-fd-primary px-4 py-2.5 text-sm font-medium text-fd-primary-foreground transition-opacity hover:opacity-90 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring"
-            >
-              Open the record
-              <span
-                aria-hidden
-                className="transition-transform group-hover:translate-x-0.5 motion-reduce:transform-none"
-              >
-                &rarr;
-              </span>
-            </Link>
-            {/* The machine identity and the agent door — the slug is what
-                citations will carry, so it stays visible where agents look. */}
-            <p className="text-xs text-fd-muted-foreground">
-              <span className="font-mono">{appName}</span> &middot; {pages.length} document
-              {pages.length === 1 ? "" : "s"} &middot; agents read{" "}
-              <a
-                href={`${basePath}/llms.txt`}
-                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"
-              >
-                llms.txt
-              </a>
-            </p>
-          </div>
-        ) : (
-          <p className="mt-9 text-fd-muted-foreground">
-            the record is empty — add a document to <code>knowledge/</code>
-          </p>
-        )}
-      </div>
+  // The record as the cover shows it: the document the button opens, then the
+  // 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);
+  const lead = entries.find((entry) => entry.url === first.url) ?? entryFor(first);
+  const behind = entries.filter((entry) => entry.url !== lead.url).slice(0, 3);
 
-      <footer className="mx-auto w-full max-w-2xl px-6 pb-10">
-        <p className="border-t border-fd-border pt-6 text-xs">
-          <FooterMark />
-        </p>
-      </footer>
+  return (
+    <main className="flex flex-1 flex-col">
+      <HomeCover
+        mark={mark}
+        name={appName}
+        // instance.md's own H1 — a human name, not the machine slug — so a
+        // fresh scaffold reads "Knowledge System of Record" until the intake
+        // interview writes the real one.
+        title={appTitle}
+        // The record's own words: instance.md's first paragraph, which is also
+        // what `ksor serve` gives the MCP server as its instructions. The
+        // framework's marketing line used to sit here, which put ksor's voice
+        // above somebody else's knowledge (research/site-design.md F7).
+        purpose={appPurpose}
+        documents={pages.length}
+        firstUrl={first.url}
+        lead={lead}
+        behind={behind}
+        // Signed from inside the cover, so the front door is one screen rather
+        // than a band with a strip of page beneath it.
+        foot={
+          <p className="mx-auto w-full max-w-6xl px-6 font-mono text-xs tracking-wider text-[var(--ksor-cover-muted)] uppercase">
+            <FooterMark />
+          </p>
+        }
+      />
     </main>
   );
 }

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

@@ -1,9 +1,20 @@
-import { source } from "@/lib/source";
+import { entriesUnder, 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 {
+  GovernanceMeta,
+  Provenance,
+  SupersededNotice,
+  type Successor,
+} from "@/components/governance";
+import { predecessorsOf, readGovernance, resolveSuccessorUrl } from "@/lib/governance";
+import { showGovernance } from "@/lib/shared";
+import { RecordToc, TocItems } from "@/components/record-toc";
 
 export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
   const params = await props.params;
@@ -11,21 +22,112 @@ export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
   if (!page) notFound();
 
   const MDX = page.data.body;
+  // What the record says about this document. The page renders it; it never
+  // supplies it — an undeclared key shows nothing (specs/ksor/site-governance).
+  const governance = readGovernance(page.data, page.path);
+
+  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
+    // 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]);
+    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,
+    allPages.map((candidate) => ({
+      path: candidate.path,
+      supersededBy: readGovernance(candidate.data, candidate.path).supersededBy,
+    })),
+  ).map((url) => ({
+    href: url,
+    label: allPages.find((candidate) => candidate.url === url)?.data.title ?? url,
+  }));
 
   return (
-    <DocsPage toc={page.data.toc} full={page.data.full}>
-      <DocsTitle>{page.data.title}</DocsTitle>
-      <DocsDescription>{page.data.description}</DocsDescription>
-      <DocsBody>
-        <MDX
-          components={getMDXComponents({
-            // relative links between documents in knowledge/ resolve to
-            // their rendered pages
-            a: createRelativeLink(source, page),
-          })}
-        />
-      </DocsBody>
-    </DocsPage>
+    <TocItems items={page.data.toc}>
+      <DocsPage
+        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.
+        slots={{
+          toc: {
+            provider: TOCProvider,
+            main: RecordToc,
+            popover: TOCPopover,
+          },
+        }}
+        // 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.
+      >
+        {successor === null ? null : <SupersededNotice successor={successor} />}
+        <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. */}
+        <DocsBody style={{ flexGrow: 0 }}>
+          <MDX
+            components={getMDXComponents({
+              // relative links between documents in knowledge/ resolve to
+              // their rendered pages
+              a: createRelativeLink(source, page),
+            })}
+          />
+        </DocsBody>
+        {/* 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}
+      </DocsPage>
+    </TocItems>
   );
 }
 
@@ -46,8 +148,14 @@ export async function generateMetadata(props: PageProps<"/docs/[[...slug]]">): P
   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);
+
   return {
     title: page.data.title,
     description: page.data.description,
+    alternates: { types: { "text/markdown": markdownUrl } },
   };
 }

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

@@ -1,24 +1,5 @@
-import { getSortedPageTree } from "@/lib/source";
-import { DocsLayout } from "fumadocs-ui/layouts/docs";
-import { baseOptions } from "@/lib/layout.shared";
-import { FooterMark } from "@/components/footer-mark";
+import { RecordShell } from "@/components/record-shell";
 
 export default function Layout({ children }: LayoutProps<"/docs">) {
-  return (
-    <DocsLayout
-      tree={getSortedPageTree()}
-      {...baseOptions()}
-      // After the spread: a future sidebar key in baseOptions must not
-      // silently swallow the attribution (review finding, 2026-08-18).
-      sidebar={{
-        footer: (
-          <p className="mt-3 text-xs">
-            <FooterMark />
-          </p>
-        ),
-      }}
-    >
-      {children}
-    </DocsLayout>
-  );
+  return <RecordShell>{children}</RecordShell>;
 }