@panaversity/ksor 0.0.43 → 0.0.45

package/templates/scaffold/package.json

@@ -6,6 +6,7 @@
   "scripts": {
     "dev": "pnpm -C system/site dev",
     "build": "ksor build && pnpm -C system/site build",
+    "preview": "node system/site/preview.mjs",
     "check": "node .agents/skills/format-checker/check.mjs",
     "provision": "pnpm schema && pnpm grant",
     "serve": "ksor serve",

package/templates/scaffold/system/site/preview.mjs

@@ -0,0 +1,93 @@
+/**
+ * Serve the STATIC EXPORT, so the build has somewhere to land.
+ *
+ * The site is `output: "export"` — there is no server to start, which is what
+ * makes the record hostable anywhere. But it also means the `start` script
+ * every other project has does not exist here, and running one is the first
+ * instinct after a build; the package manager then reports a missing script,
+ * which explains nothing about why there is nothing to start.
+ *
+ * So this is the answer to "and now how do I look at it". It is node:http and
+ * nothing else — no dependency to install and no network fetch, so it works
+ * offline and behind a firewall, for the same reason the build itself
+ * downloads nothing.
+ *
+ * Names no package manager on purpose: this file ships in the npm and bun
+ * scaffolds too, and those must not carry another manager's vocabulary
+ * (asserted by `init-manager.integration.test.ts`).
+ *
+ * It is a PREVIEW, not a deployment: single process, no compression, no
+ * caching headers. Put the directory behind a real web server or a static
+ * host for anything else.
+ */
+import { createReadStream, statSync } from "node:fs";
+import { createServer } from "node:http";
+import path from "node:path";
+import process from "node:process";
+
+const ROOT = path.resolve(import.meta.dirname, "out");
+const PORT = Number(process.env.PORT ?? 3000);
+
+const TYPES = new Map([
+  [".html", "text/html; charset=utf-8"],
+  [".md", "text/markdown; charset=utf-8"],
+  [".txt", "text/plain; charset=utf-8"],
+  [".json", "application/json; charset=utf-8"],
+  [".js", "text/javascript; charset=utf-8"],
+  [".css", "text/css; charset=utf-8"],
+  [".svg", "image/svg+xml"],
+  [".png", "image/png"],
+  [".jpg", "image/jpeg"],
+  [".webp", "image/webp"],
+  [".ico", "image/x-icon"],
+  [".woff2", "font/woff2"],
+]);
+
+try {
+  statSync(ROOT);
+} catch {
+  console.error(`preview: ${ROOT} does not exist — run the build first.`);
+  process.exit(3);
+}
+
+/** The file a request resolves to, or null when it escapes the export. */
+function resolve(urlPath) {
+  const decoded = decodeURIComponent(urlPath.split("?")[0]);
+  // Contain every request inside the export: a `..` that resolves outside it
+  // is refused rather than served, even in a preview.
+  const target = path.resolve(ROOT, `.${decoded}`);
+  if (target !== ROOT && !target.startsWith(ROOT + path.sep)) return null;
+
+  for (const candidate of [target, path.join(target, "index.html"), `${target}.html`]) {
+    try {
+      if (statSync(candidate).isFile()) return candidate;
+    } catch {
+      // Try the next shape.
+    }
+  }
+  return null;
+}
+
+createServer((req, res) => {
+  const file = resolve(req.url ?? "/");
+  if (file === null) {
+    const notFound = path.join(ROOT, "404.html");
+    try {
+      statSync(notFound);
+      res.writeHead(404, { "content-type": "text/html; charset=utf-8" });
+      createReadStream(notFound).pipe(res);
+      return;
+    } catch {
+      res.writeHead(404, { "content-type": "text/plain; charset=utf-8" });
+      res.end("404\n");
+      return;
+    }
+  }
+  res.writeHead(200, {
+    "content-type": TYPES.get(path.extname(file)) ?? "application/octet-stream",
+  });
+  createReadStream(file).pipe(res);
+}).listen(PORT, () => {
+  console.log(`preview: serving ${path.relative(process.cwd(), ROOT)} on http://localhost:${PORT}`);
+  console.log("  this is the STATIC EXPORT — the same bytes a host would serve.");
+});

package/templates/scaffold/knowledge/what-is-a-ksor.flashcards.yaml

@@ -1,25 +0,0 @@
-# A recall deck for what-is-a-ksor.md.
-#
-# Every card states only what its parent document states — a deck is a way of
-# rehearsing the record, never a second source. Ask your coding agent to write
-# one of these from a document, and to check each answer against it.
-deck:
-  title: What a KSoR is
-  description: Recall checks for the record's own definition of itself.
-cards:
-  - front: When a spreadsheet disagrees with the ledger, which one wins?
-    back: The ledger. A system of record is the copy that governs.
-    why: Which copy would your organization's agents trust today?
-
-  - front: A traditional system of record settles the state of a business. What does a KSoR settle?
-    back: What the organization knows and how it should operate — which policies apply, which thresholds are approved, what a term means here.
-
-  - front: What problem does a KSoR solve?
-    back: Scatter. Knowledge spread across wikis, decks, PDFs, prompts and someone's memory, with no authoritative answer to which knowledge an agent should trust.
-
-  - front: Why can an assistant not tell you which of its sentences were checked?
-    back: Because it answers from everything it has ever read. Nothing in that process distinguishes a checked claim from an unchecked one.
-    why: This is the gap the record exists to close.
-
-  - front: Does provenance prove that a document is correct?
-    back: No. Provenance proves who said what, and when. Whether the source is any good is a separate matter, and the record never claims otherwise.

package/templates/scaffold/knowledge/what-is-a-ksor.quiz.yaml

@@ -1,90 +0,0 @@
-# A quiz for what-is-a-ksor.md.
-#
-# Every question and every answer states only what its parent document states —
-# a quiz is a way of checking the record, never a second source. Ask your coding
-# agent to write one from a document, and to check each answer back against it.
-#
-# Two habits worth copying. The options are kept close in LENGTH, because if the
-# correct answer is reliably the longest one a reader passes by looking rather
-# than by reading. And the correct answer moves POSITION between questions: a
-# quiz whose answer is usually B is a quiz you can pass without the document.
-# `pnpm check` and `pnpm build` both refuse a quiz where either is true — the
-# first draft of this one was refused for putting four of five answers at B.
-quiz:
-  title: Check yourself
-  description: Five questions on what this record is, and what it is not.
-questions:
-  - question: A spreadsheet and the ledger disagree about a number. Which one is authoritative?
-    options:
-      - Whichever of the two was most recently edited
-      - The spreadsheet, being closer to the daily work
-      - The ledger, because it is the governing copy
-      - Neither, until a person reconciles the two
-    answer: 2
-    explanation: >
-      A system of record is the copy that governs, so the ledger wins by
-      definition rather than by being newer or closer to the work. Recency is
-      not authority: an edit made this morning in a spreadsheet nobody governs
-      is still ungoverned. Reconciliation is something a record makes possible,
-      not a precondition for having an answer at all.
-    source: The opening definition
-
-  - question: What does a KSoR settle that a traditional system of record does not?
-    options:
-      - The state of a business, such as its balances
-      - Which vendor an organization has chosen to use
-      - How much storage the organization is paying for
-      - What the organization knows and how it operates
-    answer: 3
-    explanation: >
-      A traditional system of record settles the state of a business — what is
-      owed, what is owned, what was transacted. A KSoR settles the layer above
-      it: which policies apply, which thresholds are approved, and what a term
-      means inside this organization. Vendor choice and storage cost are
-      consequences of running one, never what it is authoritative for.
-    source: What this record settles
-
-  - question: Why can an ordinary assistant not tell you which of its sentences were checked?
-    options:
-      - It answers from everything it has ever read
-      - It was not given enough context to work with
-      - Its answers are checked, but only in summary
-      - It lacks permission to reveal its own sources
-    answer: 0
-    explanation: >
-      It answers from everything it has ever read, and nothing in that process
-      separates a checked claim from an unchecked one. This is not a context
-      problem and not a permissions problem: more context cannot create a
-      distinction that was never recorded in the first place. The record closes
-      the gap by governing what gets read.
-    source: Why an assistant cannot answer that question
-
-  - question: What problem does a KSoR exist to solve?
-    options:
-      - Storage costs across a growing organization
-      - Scatter, with no authoritative copy to trust
-      - The speed at which an assistant can reply
-      - The difficulty of writing documentation well
-    answer: 1
-    explanation: >
-      The problem is scatter: knowledge spread across wikis, decks, PDFs,
-      prompts and somebody's memory, with no authoritative answer to which of
-      them an agent should trust. Speed and cost are not what the record
-      addresses, and writing well is valuable but does not by itself tell an
-      agent which of two documents governs.
-    source: The problem it solves
-
-  - question: Abstention — answering "not in this corpus" — is best described as what?
-    options:
-      - An error state the record should minimise
-      - A temporary gap, pending the next ingest
-      - A setting an operator turns on when ready
-      - A correct answer the record is meant to give
-    answer: 3
-    explanation: >
-      Abstention is a correct answer, never an error and never a licence to
-      fall back on general model knowledge. A record that answers everything
-      has stopped being a record of anything in particular. It is not a gap
-      waiting to be filled, and while the gate that enforces it is configured
-      deliberately, the honesty it expresses is the product itself.
-    source: What this record settles, and what it does not

package/templates/scaffold/knowledge/what-is-a-ksor.slides.yaml

@@ -1,65 +0,0 @@
-# The presentation that teaches what-is-a-ksor.md.
-#
-# These slides live IN the record: reviewed in a pull request, versioned with
-# the document, withdrawn when it is withdrawn, and rendered by the site — so
-# there is no third party, no dead link, and nothing to keep in step by hand.
-# Your coding agent writes them from the document; `.agents/skills/make-slides/`
-# is the procedure.
-#
-# A slide may only say what the document says. A deck is a way of presenting
-# the record, never a second source.
-slides:
-  title: Introducing the record
-  description: The 15-minute version, for a room.
-deck:
-  # The opening slide does NOT repeat the page title. It sits directly under
-  # it, so restating it wastes the one slide everyone actually looks at.
-  - heading: Which copy should an agent trust?
-    lead: That question is what this record exists to answer, and nothing in an ordinary assistant can.
-    note: Open with the question, not the definition. The definition lands after they feel the problem.
-
-  - heading: The problem it solves
-    bullets:
-      - Knowledge is scattered across wikis, decks, PDFs, prompts and memory
-      - No authoritative answer to the question an agent has to ask
-      - Which of these copies should I trust?
-    note: Ask the room where their real answer lives today. Wait for the disagreement — it always comes.
-
-  - heading: When two copies disagree, one wins
-    bullets:
-      - A traditional system of record settles the state of a business
-      - The ledger is authoritative; the spreadsheet is not
-      - Recency is not authority — a fresh edit to an ungoverned copy is still ungoverned
-    note: This is the whole idea. If they take one slide away, it is this one.
-
-  - heading: AI never had one
-    bullets:
-      - An assistant answers from everything it has ever read
-      - Nothing in that separates a checked claim from an unchecked one
-      - Which is exactly why it cannot tell you which of its sentences were verified
-    note: Not a criticism of the models. It is a missing layer, and that layer is what we are building.
-
-  - heading: What this record settles
-    bullets:
-      - Which policies apply, and which thresholds are approved
-      - What a term means inside this organization
-      - What to do when the answer is not known
-    note: Point at the third one. It is the one people do not expect.
-
-  - heading: Abstention is a feature
-    lead: '"Not in this corpus" is a correct answer — never an error, and never a licence to fall back on model knowledge.'
-    note: A record that answers everything has stopped being a record of anything in particular.
-
-  - heading: One source, two surfaces
-    bullets:
-      - The website is for people
-      - The MCP server is for agents
-      - Both render the same build — they can never disagree
-    note: Open llms.txt beside the page here. Seeing one source render twice lands better than describing it.
-
-  - heading: Where the edges are
-    bullets:
-      - Provenance proves who said what, and when
-      - It does not prove the source was right — that is a separate judgment
-      - Governance is a ladder, not a gate; level 0 works on day one
-    note: Say the second bullet out loud. Overselling provenance is how these systems lose trust.