@panaversity/ksor 0.0.26 → 0.0.28

package/templates/scaffold/system/site/lib/stage-knowledge.ts

@@ -11,6 +11,7 @@ import {
 } from "node:fs";
 import path from "node:path";
 
+import { ATTACHMENT_SUFFIXES, isAttachment, parentDocumentOf } from "./attachment-rule";
 import { audienceModel, buildAudience, refuse, visibleInBuild } from "./audience";
 import { isDenied, recordPathFrom, stableIdFrom, type DenylistManifest } from "./denial-rule";
 import { appName, instanceFrontmatter } from "./shared";
@@ -316,11 +317,22 @@ function stableIdOf(recordDir: string, file: string, text: string): string {
   );
 }
 
+/**
+ * The suffixes staging probes for — DERIVED from the shared rule, so a new
+ * attachment kind cannot be added there and forgotten here.
+ */
+const ATTACHMENT_SUFFIXES_FOR_STAGE: readonly string[] = ATTACHMENT_SUFFIXES.map((e) => e.suffix);
+
 function planStage(recordDir: string, denied: DenylistManifest): StagePlan {
   const documents: string[] = [];
   const assets = new Set<string>();
   let total = 0;
   for (const file of walkFiles(recordDir)) {
+    // An attachment is not a document: it is neither counted nor filtered on
+    // its own terms. It rides in below, with the parent that survived — which
+    // is the whole of governance inheritance, obtained by POSITION rather than
+    // by a second rule that could disagree with this one.
+    if (isAttachment(path.basename(file))) continue;
     if (!file.toLowerCase().endsWith(".md")) continue;
     total += 1;
     const text = readFileSync(file, "utf8");
@@ -332,6 +344,13 @@ function planStage(recordDir: string, denied: DenylistManifest): StagePlan {
     if (isDenied(denied, stableIdOf(recordDir, file, text), recordPathOf(recordDir, file)))
       continue;
     documents.push(file);
+    // The parent survived BOTH filters, so its attachments may be published.
+    // Reached only here: a filtered or denied parent never gets this far, so
+    // there is no path on which an attachment is staged without its parent.
+    for (const suffix of ATTACHMENT_SUFFIXES_FOR_STAGE) {
+      const attachment = file.replace(/\.mdx?$/i, "") + suffix;
+      if (existsSync(attachment)) assets.add(attachment);
+    }
     // Body only: frontmatter carries no links in the record grammar, and
     // scanning it here while the other shell strips it staged different
     // asset sets from one record (review finding, 2026-08-18).
@@ -539,6 +558,53 @@ function fillStage(recordDir: string, stageDir: string, denied: DenylistManifest
  * deleted or mistyped `audiences:` block would otherwise publish every
  * restricted document on a green build (vis-docusaurus, 2026-08-18).
  */
+/**
+ * Attachments the record cannot publish, refused at the BUILD.
+ *
+ * Staging never depends on the checker having run, so both rules need a home
+ * here as well as in `pnpm check` — the checker is where they get a good
+ * message, this is where they are guaranteed.
+ *
+ * Runs on every path, including the level-0 fast path that stages nothing:
+ * an orphan is a governance hole whether or not this record declares
+ * audiences.
+ */
+function assertAttachmentsWellFormed(recordDir: string): void {
+  for (const file of walkFiles(recordDir)) {
+    const base = path.basename(file);
+    if (!isAttachment(base)) continue;
+    const rel = path.relative(recordDir, file);
+
+    const parent = parentDocumentOf(base);
+    if (parent !== null && !existsSync(path.join(path.dirname(file), parent))) {
+      refuse(
+        "ksor-attachment-orphan",
+        `${rel} is an attachment of ${parent}, which is not in the record`,
+        "an attachment inherits its parent's governance — with no parent there is nothing to inherit, so it would be published under no tier and covered by no takedown",
+        `add ${path.join(path.dirname(rel), parent)}, or remove ${rel}`,
+      );
+    }
+
+    // No frontmatter, at all. One rule kills the whole widening class:
+    // no `visibility:` claiming a tier the parent does not have, no `sor_id:`
+    // escaping the parent's takedown, no `status:`/`owner:` claiming
+    // governance a thing with no id cannot carry.
+    if (base.toLowerCase().endsWith(".md") || base.toLowerCase().endsWith(".mdx")) {
+      const text = readFileSync(file, "utf8")
+        .replace(/^\uFEFF/, "")
+        .replaceAll("\r\n", "\n");
+      if (text.startsWith("---\n")) {
+        refuse(
+          "ksor-attachment-frontmatter",
+          `${rel} declares frontmatter`,
+          "an attachment is part of its parent and carries none of its own governance — a key here would look like it governs something and would govern nothing",
+          `remove the frontmatter block from ${rel}; ${parent ?? "its parent"} is what carries the governance`,
+        );
+      }
+    }
+  }
+}
+
 function refuseVisibilityWithoutAudiences(recordDir: string): void {
   for (const file of walkFiles(recordDir)) {
     if (!file.toLowerCase().endsWith(".md")) continue;
@@ -640,9 +706,11 @@ export function knowledgeSourceDir(): string {
     // taking a lock on every build.
     if (existsSync(stageDir)) withStageLock(stageDir, () => removeStage(stageDir));
     refuseVisibilityWithoutAudiences(recordDir);
+    assertAttachmentsWellFormed(recordDir);
     return RECORD_DIR;
   }
   if (audienceModel === null) refuseVisibilityWithoutAudiences(recordDir);
+  assertAttachmentsWellFormed(recordDir);
   fillStage(recordDir, stageDir, denied);
   watchRecord(recordDir, stageDir);
   return STAGE_DIR;

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

@@ -1,6 +1,7 @@
-import { defineConfig, defineDocs } from "fumadocs-mdx/config";
+import { defineCollections, defineConfig, defineDocs } from "fumadocs-mdx/config";
 import { metaSchema, pageSchema } from "fumadocs-core/source/schema";
 import { z } from "zod";
+import { DeckSchema } from "./lib/deck";
 import { knowledgeSourceDir } from "./lib/stage-knowledge";
 
 // The record lives at <repo>/knowledge — two levels up from this site.
@@ -15,6 +16,15 @@ import { knowledgeSourceDir } from "./lib/stage-knowledge";
 export const docs = defineDocs({
   dir: knowledgeSourceDir(),
   docs: {
+    // ONE exclusion, and it is the whole of "an attachment is not a document".
+    // The route table, the sidebar, llms.txt, llms-full.txt, /md/, the search
+    // index and the caveat map ALL read `source`, and `source` reads exactly
+    // this collection — so subtracting attachments here subtracts them from
+    // every surface at once. Doing it per-surface instead is the failure mode
+    // research/visibility.md §4-§5 is cited for; pruning the page tree is not
+    // even sufficient, because getSortedPages() deliberately re-adds what the
+    // tree dropped and the search index never consults the tree.
+    files: ["**/*.md", "**/*.mdx", "!**/*.summary.md", "!**/*.summary.mdx"],
     schema: pageSchema
       .extend({
         status: z.string().optional(),
@@ -30,10 +40,53 @@ export const docs = defineDocs({
     },
   },
   meta: {
+    // PINNED, and not optional. The default meta glob is `**/*.{yaml,json}`,
+    // which swallows every `<doc>.flashcards.yaml` in the record and fails the
+    // build with a zod error naming neither the file's purpose nor the rule
+    // (verified against the real record: the default glob returned the deck).
+    files: ["**/meta.{json,yaml}"],
     schema: metaSchema,
   },
 });
 
+/**
+ * A document's summary, rendered on the document's own page.
+ *
+ * Its own collection rather than a page: it goes through the SAME MDX pipeline
+ * as the record — the same prose voice, code handling and heading anchors — but
+ * is never handed to `loader()`, so it has no route and appears on no agent
+ * surface. The parent's own bytes are untouched by its presence.
+ */
+export const summaries = defineCollections({
+  type: "doc",
+  dir: knowledgeSourceDir(),
+  files: ["**/*.summary.md"],
+  postprocess: {
+    // So the page can count the summary's words for its reading time without
+    // reading the file again. `getText("raw")` would go back to disk, and it
+    // resolves against the working directory rather than the collection's dir
+    // — which fails the export outright (found live: ENOENT on
+    // knowledge/<doc>.md during prerender).
+    includeProcessedMarkdown: true,
+  },
+});
+
+/**
+ * A document's recall deck.
+ *
+ * `type: "meta"` because fumadocs parses YAML for meta collections itself
+ * (dist/meta-BR_rkCyY.js: `.yaml` -> yaml.parse, `.json` -> JSON.parse, and
+ * anything else throws). That is why this needs no YAML parser and no new
+ * dependency — `yaml` is already fumadocs-mdx's own — and why the extension is
+ * exactly `.yaml`: `.yml` reaches that `throw` and names only the path.
+ */
+export const decks = defineCollections({
+  type: "meta",
+  dir: knowledgeSourceDir(),
+  files: ["**/*.flashcards.yaml"],
+  schema: DeckSchema,
+});
+
 export default defineConfig({
   mdxOptions: {
     // MDX options

package/templates/scaffold/system/site/components/copy-markdown.tsx

@@ -1,70 +0,0 @@
-"use client";
-
-import { useCopyButton } from "fumadocs-ui/utils/use-copy-button";
-import { Check, Copy } from "lucide-react";
-import { useState, type ReactElement } from "react";
-
-/**
- * Hand this document to an agent: copy the governed markdown, verbatim.
- *
- * The record's second audience reads bytes, and until now a reader who wanted
- * to give an agent a document had to open its markdown twin and select the
- * page. This fetches that same twin — the one `/md/<path>.md` already serves,
- * so there is no second rendering of the document to drift — and puts it on the
- * clipboard.
- *
- * Fumadocs ships an `ai/page-actions` component that does this alongside "Open
- * in ChatGPT" and "Open in Claude". Those two are deliberately NOT taken: this
- * product's claim is that one corpus answers in ANY assistant because the
- * surface is an open standard, and hardcoding two vendors into every adopter's
- * page argues the opposite. What is taken is the shell's own `useCopyButton`,
- * which owns the copied-state timing — the only part worth not rewriting.
- *
- * It rests in the muted grey the rest of the row's metadata wears and takes the
- * accent only when it has actually copied. An accent at REST said "link" on a
- * row of facts and added to a page that was already too blue; an accent on the
- * state CHANGE is the one thing the accent is for.
- */
-export function CopyMarkdown({ href }: { href: string }): ReactElement {
-  const [failed, setFailed] = useState(false);
-  const [copied, onClick] = useCopyButton(async () => {
-    setFailed(false);
-    try {
-      // `navigator.clipboard` exists only in a secure context, so a site served
-      // over plain http on a LAN address has no clipboard at all. Saying so
-      // beats a button that reports success it did not have.
-      if (navigator.clipboard === undefined) throw new Error("no clipboard");
-      const response = await fetch(href);
-      if (!response.ok) throw new Error(`markdown twin returned ${response.status}`);
-      await navigator.clipboard.writeText(await response.text());
-    } catch {
-      setFailed(true);
-    }
-  });
-
-  return (
-    <button
-      type="button"
-      onClick={onClick}
-      // aria-live, because the label is the only feedback: a screen reader that
-      // does not hear "Copied" is told nothing happened at all.
-      aria-live="polite"
-      // The hover tone is dropped while copied, not overridden: a `hover:`
-      // variant is a class AND a pseudo-class, so it outranks a plain colour
-      // class — and the pointer is by definition still over the button at the
-      // moment it has just been clicked, so the success colour never showed
-      // (measured 2026-08-22: lab(4.41), the foreground, where the accent
-      // belonged).
-      className={`inline-flex items-center gap-1.5 rounded-md px-2 py-1 font-mono text-[0.6875rem] tracking-[0.14em] uppercase transition-colors hover:bg-fd-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-fd-ring ${
-        copied ? "text-fd-primary" : "text-fd-muted-foreground hover:text-fd-foreground"
-      }`}
-    >
-      {copied ? (
-        <Check aria-hidden className="size-3.5" />
-      ) : (
-        <Copy aria-hidden className="size-3.5" />
-      )}
-      {failed ? "Copy failed" : copied ? "Copied" : "Copy"}
-    </button>
-  );
-}