@panaversity/ksor 0.0.1 → 0.0.2

package/templates/scaffold/pnpm-workspace.yaml

@@ -0,0 +1,19 @@
+packages:
+  - system/site
+  # reserved homes for future system components (gateways, MCP surface, packages)
+  - system/gateways/*
+  - system/packages/*
+
+# 48-hour quarantine on newly published dependency versions — a routine
+# `pnpm install` here never picks up a day-zero compromised release.
+minimumReleaseAge: 2880
+
+# Dependency install scripts are denied by default. Flip an entry to true
+# only with a comment naming what breaks without it. esbuild and sharp are
+# reviewed and stay denied: both ship prebuilt platform binaries as
+# optionalDependencies, so their install scripts are download fallbacks the
+# site never needs — but pnpm 11 exits 1 on every install/dev until each is
+# explicitly decided. (found live: fresh-scaffold pnpm dev, 2026-08-18)
+allowBuilds:
+  esbuild: false
+  sharp: false

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

@@ -0,0 +1,6 @@
+import { HomeLayout } from "fumadocs-ui/layouts/home";
+import { baseOptions } from "@/lib/layout.shared";
+
+export default function Layout({ children }: LayoutProps<"/">) {
+  return <HomeLayout {...baseOptions()}>{children}</HomeLayout>;
+}

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

@@ -0,0 +1,83 @@
+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 mark from "@/app/icon.png";
+import { BuiltWith } from "@/components/built-with";
+import { appName, appTitle } from "@/lib/shared";
+import { basePath, getSortedPages } from "@/lib/source";
+
+export default function HomePage() {
+  // The first document in sidebar order — never a hardcoded path, so deleting
+  // the example the scaffold ships cannot leave a link pointing at nothing.
+  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.
+        </p>
+
+        {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>
+
+      <footer className="mx-auto w-full max-w-2xl px-6 pb-10">
+        <p className="border-t border-fd-border pt-6 text-xs">
+          <BuiltWith />
+        </p>
+      </footer>
+    </main>
+  );
+}

package/templates/scaffold/system/site/app/api/search/route.ts

@@ -0,0 +1,11 @@
+import { source } from "@/lib/source";
+import { createFromSource } from "fumadocs-core/search/server";
+
+// Static export: this route is prerendered into a JSON index file that the
+// search dialog downloads and queries client-side (see app/layout.tsx).
+export const revalidate = false;
+
+export const { staticGET: GET } = createFromSource(source, {
+  // https://docs.orama.com/docs/orama-js/supported-languages
+  language: "english",
+});

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

@@ -0,0 +1,53 @@
+import { source } from "@/lib/source";
+import { DocsBody, DocsDescription, DocsPage, DocsTitle } from "fumadocs-ui/layouts/docs/page";
+import { notFound } from "next/navigation";
+import { getMDXComponents } from "@/components/mdx";
+import type { Metadata } from "next";
+import { createRelativeLink } from "fumadocs-ui/mdx";
+
+export default async function Page(props: PageProps<"/docs/[[...slug]]">) {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  const MDX = page.data.body;
+
+  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>
+  );
+}
+
+export async function generateStaticParams() {
+  const params = source.generateParams();
+  if (params.length === 0) {
+    // Without this, Next fails the empty-record build with an error that
+    // names neither the record nor the rule (found live, 2026-08-18).
+    throw new Error(
+      "the record has no documents — a KSoR is never empty; add one to knowledge/ or restore one from git history (pnpm check says the same).",
+    );
+  }
+  return params;
+}
+
+export async function generateMetadata(props: PageProps<"/docs/[[...slug]]">): Promise<Metadata> {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+  };
+}

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

@@ -0,0 +1,24 @@
+import { getSortedPageTree } from "@/lib/source";
+import { DocsLayout } from "fumadocs-ui/layouts/docs";
+import { baseOptions } from "@/lib/layout.shared";
+import { BuiltWith } from "@/components/built-with";
+
+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">
+            <BuiltWith />
+          </p>
+        ),
+      }}
+    >
+      {children}
+    </DocsLayout>
+  );
+}

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

@@ -0,0 +1,26 @@
+@import "tailwindcss";
+@import "fumadocs-ui/css/neutral.css";
+@import "fumadocs-ui/css/preset.css";
+
+/* The KSoR default accent, drawn from the mark — the one brand value here.
+   Re-brand by changing this pair; every accented element follows. */
+:root {
+  --color-fd-primary: #1d4ed8;
+  --color-fd-primary-foreground: #ffffff;
+  --color-fd-ring: #1d4ed8;
+}
+
+.dark {
+  --color-fd-primary: #7fb0f9;
+  --color-fd-primary-foreground: #081226;
+  --color-fd-ring: #7fb0f9;
+}
+
+html {
+  scrollbar-gutter: stable;
+}
+
+html > body[data-scroll-locked] {
+  margin-right: 0px !important;
+  --removed-body-scroll-bar-size: 0px !important;
+}

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

@@ -0,0 +1,41 @@
+import { RootProvider } from "fumadocs-ui/provider/next";
+import "./global.css";
+import type { Metadata } from "next";
+import { appTitle } from "@/lib/shared";
+
+// No next/font/google: it fetches the face from Google at BUILD time, so a
+// scaffolded project could not build offline and two builds of one commit
+// could differ byte-wise (review finding, 2026-08-18). The system UI stack
+// costs zero bytes and zero network; replace it with a self-hosted @font-face
+// if the project wants a specific face.
+
+export const metadata: Metadata = {
+  title: {
+    default: appTitle,
+    template: `%s | ${appTitle}`,
+  },
+  description: "The Knowledge System of Record for humans and AI agents.",
+};
+
+export default function Layout({ children }: LayoutProps<"/">) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className="flex flex-col min-h-screen">
+        <RootProvider
+          search={{
+            // Static search: the browser downloads the index that
+            // app/api/search exports at build time (staticGET) and runs
+            // Orama client-side — no server needed, so search keeps
+            // working on any static host.
+            options: {
+              type: "static",
+              api: `${process.env.KSOR_BASE_PATH ?? ""}/api/search`,
+            },
+          }}
+        >
+          {children}
+        </RootProvider>
+      </body>
+    </html>
+  );
+}

package/templates/scaffold/system/site/app/llms-full.txt/route.ts

@@ -0,0 +1,10 @@
+import { getLLMText, getSortedPages } from "@/lib/source";
+
+export const revalidate = false;
+
+export async function GET(): Promise<Response> {
+  const scan = getSortedPages().map(getLLMText);
+  const scanned = await Promise.all(scan);
+
+  return new Response(scanned.join("\n\n"));
+}

package/templates/scaffold/system/site/app/llms.txt/route.ts

@@ -0,0 +1,15 @@
+import { basePath, getSortedPages } from "@/lib/source";
+import { appName } from "@/lib/shared";
+
+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.
+export function GET(): Response {
+  const lines = getSortedPages().map((page) => {
+    const link = `- [${page.data.title}](${basePath}${page.url})`;
+    return page.data.description ? `${link}: ${page.data.description}` : link;
+  });
+
+  return new Response(`# ${appName}\n\n${lines.join("\n")}\n`);
+}

package/templates/scaffold/system/site/components/built-with.tsx

@@ -0,0 +1,18 @@
+import type { ReactElement } from "react";
+
+/**
+ * The maker's mark. Attribution, not a dependency: the record and this site
+ * are yours (MIT-0) — delete this component and both keep working.
+ */
+export function BuiltWith(): ReactElement {
+  return (
+    <a
+      href="https://github.com/panaversity/ksor"
+      target="_blank"
+      rel="noreferrer"
+      className="text-fd-muted-foreground underline-offset-4 transition-colors hover:text-fd-foreground hover:underline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring"
+    >
+      Built with KSoR
+    </a>
+  );
+}

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

@@ -0,0 +1,15 @@
+import defaultMdxComponents from "fumadocs-ui/mdx";
+import type { MDXComponents } from "mdx/types";
+
+export function getMDXComponents(components?: MDXComponents) {
+  return {
+    ...defaultMdxComponents,
+    ...components,
+  } satisfies MDXComponents;
+}
+
+export const useMDXComponents = getMDXComponents;
+
+declare global {
+  type MDXProvidedComponents = ReturnType<typeof getMDXComponents>;
+}

package/templates/scaffold/system/site/lib/layout.shared.tsx

@@ -0,0 +1,17 @@
+import type { BaseLayoutProps } from "fumadocs-ui/layouts/shared";
+import { appTitle } from "./shared";
+
+export function baseOptions(): BaseLayoutProps {
+  return {
+    nav: {
+      // The record's display title (instance.md's H1), not the machine slug.
+      // Truncated: a long title forced horizontal scroll on mobile without it
+      // (found live, 2026-08-18).
+      title: (
+        <span className="max-w-[60vw] truncate font-medium tracking-tight sm:max-w-none">
+          {appTitle}
+        </span>
+      ),
+    },
+  };
+}

package/templates/scaffold/system/site/lib/shared.ts

@@ -0,0 +1,51 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+
+// The record's one identity source: instance.md's `name:` — the same file
+// every other shell reads, so renaming the instance renames every surface
+// at the next build, and no shell carries a baked-in copy (found live
+// 2026-08-18: a stamped constant survived a restore-from-templates as the
+// literal placeholder name, with every gate green).
+function findInstance(start: string): string {
+  let dir = start;
+  for (let i = 0; i < 5; i += 1) {
+    const candidate = path.join(dir, "instance.md");
+    if (existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  throw new Error(
+    "instance.md not found — it is the project's identity; build from the project (pnpm dev / pnpm build at the repo root).",
+  );
+}
+
+function readInstanceName(): string {
+  const text = readFileSync(findInstance(process.cwd()), "utf8");
+  // Only the frontmatter block: body prose mentioning `name:` must never
+  // become the site's identity (review finding, 2026-08-18).
+  const block = /^?---\r?\n([\s\S]*?)\r?\n---/.exec(text)?.[1] ?? "";
+  const raw = /^name:[ \t]*(.*)$/m.exec(block)?.[1]?.trim() ?? "";
+  const unquoted = /^(['"])(.*)\1$/.exec(raw);
+  const name = unquoted?.[2] ?? raw;
+  if (name === "") {
+    throw new Error("instance.md carries no name: — it is the project's identity; run pnpm check.");
+  }
+  return name;
+}
+
+export const appName: string = readInstanceName();
+
+/**
+ * The record's DISPLAY TITLE: instance.md's first body heading. The slug in
+ * `name:` is the machine identity (llms.txt, future citations); the H1 is
+ * the human name every page leads with. A fresh scaffold reads "Knowledge
+ * System of Record" until the intake interview writes the real one.
+ */
+function readInstanceTitle(): string {
+  const text = readFileSync(findInstance(process.cwd()), "utf8");
+  const body = text.replace(/^\uFEFF?---\r?\n[\s\S]*?\r?\n---[ \t]*\r?\n?/, "");
+  return /^#[ \t]+(.+)$/m.exec(body)?.[1]?.trim() ?? appName;
+}
+
+export const appTitle: string = readInstanceTitle();

package/templates/scaffold/system/site/lib/source.ts

@@ -0,0 +1,119 @@
+import { docs } from "collections/server";
+import { loader } from "fumadocs-core/source";
+import { lucideIconsPlugin } from "fumadocs-core/source/lucide-icons";
+import type { Node, Root } from "fumadocs-core/page-tree";
+
+// See https://fumadocs.dev/docs/headless/source-api for more info
+export const source = loader({
+  baseUrl: "/docs",
+  source: docs.toFumadocsSource(),
+  plugins: [lucideIconsPlugin()],
+});
+
+export type KnowledgePage = (typeof source)["$inferPage"];
+
+// Sub-path hosting prefix, for URLs we WRITE INTO TEXT (llms.txt,
+// llms-full.txt). Next's <Link> and the router prepend basePath themselves,
+// so this must never touch the loader's baseUrl — that would double-prefix
+// every rendered link.
+export const basePath: string = process.env.KSOR_BASE_PATH ?? "";
+
+// `order:` is a governed frontmatter key; a document without one, or with a
+// value that is not a number, sorts after every document that declares one.
+function orderOf(page: KnowledgePage): number {
+  const raw: unknown = page.data.order;
+  const value = typeof raw === "string" ? Number(raw) : raw;
+  return typeof value === "number" && Number.isFinite(value) ? value : Number.POSITIVE_INFINITY;
+}
+
+function nodeOrder(node: Node, orders: ReadonlyMap<string, number>): number {
+  if (node.type === "page") return orders.get(node.url) ?? Number.POSITIVE_INFINITY;
+  if (node.type === "folder" && node.index) {
+    return orders.get(node.index.url) ?? Number.POSITIVE_INFINITY;
+  }
+  return Number.POSITIVE_INFINITY;
+}
+
+// The tie-break key: a page's url, a folder's index url or first page's url.
+// Ties break on it so unordered documents read in plain name order, folders
+// interleaved — the canonical reading order both shells implement (found
+// live 2026-08-18: the loader's own tie order grouped folders after loose
+// files, silently diverging from the Docusaurus shell on the same record).
+function nodeName(node: Node): string {
+  if (node.type === "page") return node.url;
+  if (node.type === "folder") {
+    if (node.index) return node.index.url;
+    for (const child of node.children) {
+      const name = nodeName(child);
+      if (name !== "") return name;
+    }
+  }
+  return "";
+}
+
+function sortNodes(nodes: readonly Node[], orders: ReadonlyMap<string, number>): Node[] {
+  return nodes
+    .map((node) =>
+      node.type === "folder" ? { ...node, children: sortNodes(node.children, orders) } : node,
+    )
+    .sort((a, b) => {
+      const left = nodeOrder(a, orders);
+      const right = nodeOrder(b, orders);
+      if (left !== right) return left < right ? -1 : 1;
+      const leftName = nodeName(a);
+      const rightName = nodeName(b);
+      // Codepoint comparison, not locale: reading order must be one bytewise
+      // truth on every machine.
+      return leftName < rightName ? -1 : leftName > rightName ? 1 : 0;
+    });
+}
+
+/**
+ * The page tree with every folder's children ordered by `order:` frontmatter.
+ * Rebuilt on each call from a fresh clone — the loader's own tree is shared
+ * state and mutating it would survive a hot reload.
+ */
+export function getSortedPageTree(): Root {
+  const orders = new Map(source.getPages().map((page) => [page.url, orderOf(page)] as const));
+  const tree = source.getPageTree();
+  return { ...tree, children: sortNodes(tree.children, orders) };
+}
+
+function collectUrls(nodes: readonly Node[], urls: string[]): void {
+  for (const node of nodes) {
+    if (node.type === "page") urls.push(node.url);
+    else if (node.type === "folder") {
+      if (node.index) urls.push(node.index.url);
+      collectUrls(node.children, urls);
+    }
+  }
+}
+
+/**
+ * Every page, in the order the sidebar shows them — the one reading order the
+ * site, llms.txt and llms-full.txt all serve.
+ */
+export function getSortedPages(): KnowledgePage[] {
+  const urls: string[] = [];
+  collectUrls(getSortedPageTree().children, urls);
+
+  const remaining = new Map(source.getPages().map((page) => [page.url, page] as const));
+  const ordered: KnowledgePage[] = [];
+  for (const url of urls) {
+    const page = remaining.get(url);
+    if (page) {
+      ordered.push(page);
+      remaining.delete(url);
+    }
+  }
+  // A page the tree never displayed is still part of the record.
+  return [...ordered, ...remaining.values()];
+}
+
+export async function getLLMText(page: KnowledgePage): Promise<string> {
+  const processed = await page.data.getText("processed");
+
+  return `# ${page.data.title} (${basePath}${page.url})
+
+${processed}`;
+}

package/templates/scaffold/system/site/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/templates/scaffold/system/site/next.config.mjs

@@ -0,0 +1,32 @@
+import { createMDX } from "fumadocs-mdx/next";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const withMDX = createMDX();
+
+// The scaffold repo root, two levels up from system/site. The record
+// (<root>/knowledge) lives outside this app dir, so Turbopack's
+// module-resolution root and Next's file tracing are both anchored there —
+// resolved from this file's own location so it holds wherever the repo lands.
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../..");
+
+/** @type {import('next').NextConfig} */
+const config = {
+  reactStrictMode: true,
+  // Static export: `pnpm build` writes the whole site into out/, servable
+  // from any static host. No redirects here — they don't work under export.
+  output: "export",
+  // Emit docs/example/index.html rather than docs/example.html — the layout
+  // every static file host serves correctly, GitHub Pages included.
+  trailingSlash: true,
+  images: { unoptimized: true },
+  // Hosting under a sub-path (e.g. a GitHub Pages project site):
+  //   KSOR_BASE_PATH="/my-repo" pnpm build
+  basePath: process.env.KSOR_BASE_PATH ?? "",
+  turbopack: {
+    root: repoRoot,
+  },
+  outputFileTracingRoot: repoRoot,
+};
+
+export default withMDX(config);

package/templates/scaffold/system/site/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "site",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "build": "next build",
+    "dev": "next dev"
+  },
+  "dependencies": {
+    "fumadocs-core": "16.10.3",
+    "fumadocs-mdx": "15.0.13",
+    "fumadocs-ui": "16.10.3",
+    "lucide-react": "1.31.0",
+    "next": "16.2.9",
+    "react": "19.2.8",
+    "react-dom": "19.2.8",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "4.3.3",
+    "@types/mdx": "2.0.14",
+    "@types/node": "25.9.5",
+    "@types/react": "19.2.18",
+    "@types/react-dom": "19.2.4",
+    "postcss": "8.5.26",
+    "tailwindcss": "4.3.3",
+    "typescript": "6.0.3"
+  }
+}

package/templates/scaffold/system/site/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/templates/scaffold/system/site/source.config.ts

@@ -0,0 +1,35 @@
+import { defineConfig, defineDocs } from "fumadocs-mdx/config";
+import { metaSchema, pageSchema } from "fumadocs-core/source/schema";
+import { z } from "zod";
+
+// The record lives at <repo>/knowledge — two levels up from this site.
+// Governance frontmatter (status, owner, provenance, superseded_by) is
+// tolerated on top of the default page schema so a governed document
+// always renders; `pnpm check` at the repo root is what enforces it.
+export const docs = defineDocs({
+  dir: "../../knowledge",
+  docs: {
+    schema: pageSchema
+      .extend({
+        status: z.string().optional(),
+        owner: z.string().optional(),
+        provenance: z.array(z.string()).optional(),
+        superseded_by: z.string().optional(),
+      })
+      .catchall(z.any()),
+    postprocess: {
+      // Exposes each page's processed markdown — llms.txt/llms-full.txt
+      // depend on it.
+      includeProcessedMarkdown: true,
+    },
+  },
+  meta: {
+    schema: metaSchema,
+  },
+});
+
+export default defineConfig({
+  mdxOptions: {
+    // MDX options
+  },
+});