@panaversity/ksor 0.0.1 → 0.0.3

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 { FooterMark } from "@/components/footer-mark";
+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">
+          <FooterMark />
+        </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 { FooterMark } from "@/components/footer-mark";
+
+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>
+  );
+}

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/footer-mark.tsx

@@ -0,0 +1,22 @@
+import type { ReactElement } from "react";
+import { BuiltWith } from "@/components/built-with";
+import { audienceNotice } from "@/lib/audience";
+
+/**
+ * The foot of the site chrome: who built it, and — on any build below the
+ * public tier — which audience that build was for, so a screenshot of an
+ * internal site names itself and a page that escapes carries its own
+ * warning.
+ *
+ * The public build renders the attribution ALONE, exactly as a site with no
+ * audience model does: the one build with nothing to disclose must not even
+ * carry the shape of a disclosure.
+ */
+export function FooterMark(): ReactElement {
+  if (audienceNotice === null) return <BuiltWith />;
+  return (
+    <>
+      <BuiltWith /> &middot; <span className="text-fd-muted-foreground">{audienceNotice}</span>
+    </>
+  );
+}

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/audience.ts

@@ -0,0 +1,178 @@
+import { instanceFrontmatter } from "./shared";
+
+/**
+ * The audience model, declared in instance.md — the record says who its
+ * readers are, and the build enforces it:
+ *
+ *     audiences:
+ *       - public
+ *       - internal
+ *       - restricted
+ *     default_visibility: public
+ *
+ * Ordered least- to most-restricted, so "build the internal site" means
+ * "public and internal included" with no further configuration. A record
+ * that declares no audiences has no model and publishes every document —
+ * the behaviour of every instance written before this key existed.
+ */
+export interface AudienceModel {
+  /** Least- to most-restricted, `public` first. */
+  readonly audiences: readonly string[];
+  /** The tier of a document that declares no `visibility:`. */
+  readonly defaultVisibility: string;
+}
+
+function unquote(raw: string): string {
+  const trimmed = raw.trim();
+  return /^(['"])(.*)\1$/.exec(trimmed)?.[2] ?? trimmed;
+}
+
+/** Every refusal this feature makes: a slug a pipeline can match, then the remedy. */
+export function refuse(slug: string, what: string, why: string, fix: string): never {
+  // The slug leads, so a pipeline can match on it, and the three lines below
+  // it are the whole remedy — an operator never has to read this file.
+  throw new Error(`${slug}: ${what}\n  why: ${why}\n  fix: ${fix}`);
+}
+
+function readAudienceModel(): AudienceModel | null {
+  const block = instanceFrontmatter();
+  // Top-level key only: `^` under /m cannot match an indented child.
+  if (!/^audiences:/m.test(block)) return null;
+
+  // The grammar mirrors the checker's exactly — CRLF-tolerant, list items at
+  // ANY indent (YAML allows unindented block sequences), and a ` #` comment
+  // ends an unquoted entry (all three found live 2026-08-18: records the
+  // checker blessed either failed this build or silently lost a tier).
+  const stripComment = (value: string): string =>
+    /^["']/.test(value.trim()) ? value : value.replace(/\s+#.*$/, "");
+  // A line scanner, not a block regex: a blank line among the items or a
+  // comment on the key line broke the block capture and refused every build
+  // of a checker-green record (review finding, 2026-08-19).
+  const flow = /^audiences:[ \t]*\[(.*)\][ \t]*(?:#.*)?$/m.exec(block)?.[1];
+  let items: string[] = [];
+  if (flow !== undefined) {
+    items = flow.split(",");
+  } else {
+    const lines = block.split("\n");
+    const start = lines.findIndex((line) => /^audiences:[ \t]*(?:#.*)?$/.test(line));
+    if (start !== -1) {
+      for (const line of lines.slice(start + 1)) {
+        if (line.trim() === "") continue;
+        const item = /^[ \t]*-[ \t]+(.*)$/.exec(line);
+        if (item === null) break;
+        items.push(item[1] ?? "");
+      }
+    }
+  }
+  const audiences = items
+    .map(stripComment)
+    .map(unquote)
+    .filter((value) => value !== "");
+
+  // A declared-but-unreadable model must never read as "no model": that is
+  // the one parse failure that publishes the whole record.
+  if (audiences.length === 0) {
+    refuse(
+      "ksor-audiences-unreadable",
+      "instance.md declares `audiences:` but no audience could be read from it",
+      "an unreadable model reads as no model, and no model publishes every document — the one parse failure that leaks",
+      "write the audiences as a list, least-restricted first:\n    audiences:\n      - public\n      - internal",
+    );
+  }
+
+  // The staging never depends on the checker having run: a
+  // most-restrictive-first model would make plain `pnpm build` publish
+  // every restricted document with no label (review finding, 2026-08-18).
+  if (audiences[0] !== "public") {
+    refuse(
+      "ksor-audiences-misordered",
+      `audiences: must start with public (it starts with "${audiences[0]}")`,
+      "the list is ordered least- to most-restricted, and an unset KSOR_AUDIENCE builds the FIRST entry — any other first entry makes the default build the leak",
+      "reorder audiences: with public first",
+    );
+  }
+  if (new Set(audiences).size !== audiences.length) {
+    refuse(
+      "ksor-audiences-duplicate",
+      `audiences: declares a tier twice (${audiences.join(", ")})`,
+      "a duplicated tier has two positions in the ordering, and which one a build honours is undefined",
+      "remove the duplicate entry",
+    );
+  }
+  const defaultVisibility = unquote(
+    stripComment(/^default_visibility:[ \t]*(.*)$/m.exec(block)?.[1] ?? ""),
+  );
+  if (defaultVisibility === "") {
+    refuse(
+      "ksor-default-visibility-missing",
+      "instance.md declares `audiences:` without `default_visibility:`",
+      "there is no safe guess: assuming the widest tier leaks on the first document that forgets the key, assuming the narrowest hides the record",
+      `add the tier a document without a visibility: key belongs to, e.g. default_visibility: ${audiences[0]}`,
+    );
+  }
+  if (!audiences.includes(defaultVisibility)) {
+    refuse(
+      "ksor-default-visibility-undeclared",
+      `default_visibility: ${defaultVisibility} is not one of the declared audiences (${audiences.join(", ")})`,
+      "every document without a visibility: key belongs to this tier — a tier no build understands is a record no build can publish honestly",
+      `set default_visibility: to one of ${audiences.join(", ")}, or declare ${defaultVisibility} in audiences:`,
+    );
+  }
+
+  return { audiences, defaultVisibility };
+}
+
+/** The declared model, or null when this record declares none. */
+export const audienceModel: AudienceModel | null = readAudienceModel();
+
+function resolveBuildAudience(model: AudienceModel | null): string {
+  const requested = process.env.KSOR_AUDIENCE?.trim() ?? "";
+  if (model === null) {
+    if (requested !== "") {
+      refuse(
+        "ksor-audiences-not-declared",
+        `KSOR_AUDIENCE="${requested}" was requested, but instance.md declares no audiences`,
+        "this build would publish every document — a build that cannot filter must never look like one that did",
+        "declare the model in instance.md (audiences: + default_visibility:), or build without KSOR_AUDIENCE",
+      );
+    }
+    return "";
+  }
+  // Unset means the least-restricted tier: the only default that cannot leak,
+  // so `pnpm build` keeps publishing the public site out of the box.
+  if (requested === "") return model.audiences[0] as string;
+  if (!model.audiences.includes(requested)) {
+    refuse(
+      "ksor-audience-undeclared",
+      `KSOR_AUDIENCE="${requested}" is not an audience this record declares (${model.audiences.join(", ")})`,
+      "an unrecognized audience could only be honoured by publishing more than the record names — so it refuses instead of widening",
+      `build with one of ${model.audiences.join(", ")}, or add "${requested}" to instance.md's audiences: list`,
+    );
+  }
+  return requested;
+}
+
+/** The audience this build publishes for; "" when the record has no model. */
+export const buildAudience: string = resolveBuildAudience(audienceModel);
+
+/** Whether a document of this visibility belongs in THIS build. */
+export function visibleInBuild(visibility: string | null): boolean {
+  if (audienceModel === null) return true;
+  const value =
+    visibility === null || visibility === "" ? audienceModel.defaultVisibility : visibility;
+  const rank = audienceModel.audiences.indexOf(value);
+  // An undeclared visibility is refused, never published: a value no build
+  // understands is a typo, and a typo reads as a restriction.
+  if (rank === -1) return false;
+  return rank <= audienceModel.audiences.indexOf(buildAudience);
+}
+
+/**
+ * What a non-public build calls itself, in the site chrome — so a leaked
+ * screenshot of an internal site says which audience it was built for. The
+ * public build (the least-restricted tier) says nothing new.
+ */
+export const audienceNotice: string | null =
+  audienceModel === null || buildAudience === audienceModel.audiences[0]
+    ? null
+    : `${buildAudience} build — not for publication`;

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,60 @@
+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).",
+  );
+}
+
+/**
+ * instance.md's frontmatter block — the configuration every surface reads
+ * (identity here, the audience model in lib/audience.ts). Only this block:
+ * body prose that looks like a key must never become configuration (review
+ * finding, 2026-08-18).
+ */
+export function instanceFrontmatter(): string {
+  const text = readFileSync(findInstance(process.cwd()), "utf8");
+  // The checker's boundary exactly: BOM stripped, CRLF normalized, lax close.
+  const normalized = text.replace(/^\uFEFF/, "").replaceAll("\r\n", "\n");
+  return /^---\n([\s\S]*?)\n---/.exec(normalized)?.[1] ?? "";
+}
+
+function readInstanceName(): string {
+  const raw = /^name:[ \t]*(.*)$/m.exec(instanceFrontmatter())?.[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();