@panaversity/ksor 0.0.1 → 0.0.3

package/templates/scaffold/.claude/skills/intake-interview/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: intake-interview
+description: The first conversation with the owner of this Knowledge System of Record — six questions that define what it is authoritative for and who may read it, then write instance.md together. Use when the owner asks to set up, configure, or "get started with" this project, when instance.md still contains its scaffold placeholder text, or when the scope of the corpus is unclear.
+metadata:
+  version: "1.2.0"
+---
+
+# Intake interview
+
+`instance.md` is the identity of this Knowledge System of Record, and its
+prose will one day be the agent surface's system prompt. Do not draft it from
+guesses — interview the owner, one question at a time, and write down what
+they actually say.
+
+## The six questions
+
+Ask these one at a time; follow up until each answer is concrete enough to
+act on:
+
+1. **Authority** — "What should this record be the _final word_ on? Finish
+   the sentence: when someone here disagrees with this corpus, the corpus
+   wins about ___."
+2. **Boundary** — "What is explicitly _outside_ it — near-miss topics people
+   will ask about that this record should refuse rather than guess at?"
+3. **Audience** — "Who reads it — people, agents, both? In what situations,
+   making what decisions?"
+4. **Sources** — "Which existing materials are authoritative inputs (name
+   the actual documents, systems, people), and which are explicitly _not_
+   trusted?"
+5. **Strictness** — "When the record doesn't cover a question, how firmly
+   should it decline? ('Not in this corpus' is a correct answer here —
+   confirm the owner wants that behavior and where they want it softened.)"
+6. **Audiences** — "Does every reader of this record see every document? If
+   not, what are the audiences, from most public to most restricted?" A yes
+   is the common answer and the whole answer: write no `audiences:` key and
+   nothing about the project changes. A list means writing it into
+   `instance.md`'s frontmatter — ordered least- to most-restricted with
+   `public` first, plus `default_visibility:` naming the audience a document
+   takes when it says nothing (there is no safe guess, so the checker
+   requires it). Tell the owner what the key does and does not do:
+   documents carry `visibility:` and builds are made per audience, but
+   anyone who can clone the repository reads everything in it — if someone
+   must not read a document and can clone, that document belongs in a
+   different repository.
+
+## Then write
+
+- Rewrite `instance.md`'s body from the answers: first the `# H1` — the
+  record's **display title**, the human name every page will lead with
+  ("Acme Operations Handbook", not the slug) — then the authority sentence,
+  boundary, audience, and strictness — plain prose, written for a reader
+  who must act on it. Leave the frontmatter keys alone, with one exception:
+  an audience model from question 6 is written there as `audiences:` (a
+  list) and `default_visibility:`, and `pnpm check` will hold the record to
+  it from that moment on.
+- Restart `pnpm dev` afterwards so the site picks the new title up, and
+  show the owner their name on the page.
+- Offer to capture the source list from question 4 as the first real
+  documents (the add-sources skill takes it from there).
+- Read the result back to the owner and get an explicit yes before
+  finishing. Their words, tightened — never your invention.

package/templates/scaffold/.gemini/settings.json

@@ -0,0 +1,5 @@
+{
+  "context": {
+    "fileName": ["AGENTS.md", "GEMINI.md"]
+  }
+}

package/templates/scaffold/.gitattributes

@@ -0,0 +1,5 @@
+# Checkout bytes are provenance bytes: markdown is LF on every platform so
+# the same commit hashes identically on Windows, macOS, and Linux.
+* text=auto
+*.md text eol=lf
+instance.md text eol=lf

package/templates/scaffold/.github/workflows/validate.yml

@@ -0,0 +1,23 @@
+name: Validate knowledge
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Format checker
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "24"
+      # The checker is dependency-free Node — no install step needed.
+      - run: node .agents/skills/format-checker/check.mjs

package/templates/scaffold/AGENTS.md

@@ -0,0 +1,133 @@
+# AGENTS.md
+
+The working contract for this Knowledge System of Record. CLAUDE.md points
+here; every coding agent reads this file first.
+
+## The two worlds
+
+| Path          | What it is                                                                                                                                                                                                                                                                                                                                  |
+| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `knowledge/`  | **the record** — governed markdown, the owner's world, the product                                                                                                                                                                                                                                                                          |
+| `system/`     | **the system** — all code that serves the record                                                                                                                                                                                                                                                                                            |
+| `instance.md` | what this SoR is authoritative for; its prose is the future agent surface's system prompt. Its `name:` is the machine identity (llms.txt, future citations) and its body `# H1` is the DISPLAY TITLE every page leads with — both read when the server or build STARTS, so restart `pnpm dev` after changing either (found live 2026-08-18) |
+
+The record survives the system: `knowledge/` must stay readable and complete
+even if `system/` is deleted. Dependency flows one way — the system reads the
+record; the record never references the system.
+
+`instance.md` carries a closed key set — `format`, `name`, `ksor`, `site`,
+and the optional pair `audiences` + `default_visibility` (the record's reader
+audiences, ordered least- to most-restricted with `public` first, and the one
+a document takes when it names none — declared together or not at all) — and
+everything that matters about it is the prose below that frontmatter;
+`pnpm check` names any other key rather than ignoring it.
+
+## Critical rules
+
+1. **The site never contains authored content.** Knowledge goes in
+   `knowledge/`, always. Never create markdown, MDX, or content pages inside
+   `system/site` — the site _renders_ the record, it never _holds_ it.
+2. **`knowledge/` is CommonMark `.md` only.** No `.mdx`, no `meta.json`, no
+   framework files. A document must read cleanly in any markdown viewer.
+3. **Never edit generated files** — `system/site/.source/`, `.next/`, `out/`,
+   `system/site/.staged-knowledge/` (a build's per-audience copy of the
+   record — edit `knowledge/`, or the next build erases the change),
+   lockfiles by hand.
+
+## Commands (run at the repo root)
+
+```sh
+pnpm install     # once, after cloning or scaffolding
+pnpm dev         # the site, hot-reloading, at http://localhost:3000
+pnpm build       # static site into system/site/out/
+pnpm check       # the format checker — run before handing off any knowledge change
+```
+
+## Publishing
+
+`pnpm build` emits a fully static site (`system/site/out/`) deployable to
+any host — Vercel reads the shipped `vercel.json` (deploy from the repo
+ROOT, never `system/site/`), and every other host just serves the folder.
+`KSOR_BASE_PATH=/repo pnpm build` targets sub-path hosting. With
+`audiences:` declared, plain `pnpm build` is always the public tier;
+`KSOR_AUDIENCE=<audience> pnpm build` builds a wider tier that belongs
+behind that audience's own access control, never on a public host.
+Details in README → Deploying.
+
+## Writing knowledge
+
+- One document per file under `knowledge/`; the path is the document's
+  identity and its URL — ascii lowercase, digits, hyphens; no spaces or
+  special characters; no two files differing only in case; never both
+  `foo.md` and `foo/index.md`. The `title:` carries the document's real
+  name in any language — the filename is the address, not the name.
+- The frontmatter `title` IS the rendered page heading — never repeat it as
+  an `# h1` in the body, and quote any value containing a colon
+  (`title: "Note: quoting"`).
+- Frontmatter: `title` and `status` (`draft | review | approved | superseded`)
+  are required. `owner` and `provenance` (a list naming real sources) are
+  strongly encouraged — they become required as this project climbs the
+  governance ladder. `description`, `visibility` (below), `order` (sidebar
+  position), `effective` (the date the document takes effect) and `superseded`
+  (a legacy marker — prefer `status`) are available. No other keys; never
+  `id:` or `name:` — the path is the identity.
+- `visibility:` names the one audience a document belongs to — a single value
+  from `instance.md`'s `audiences:`, never a list, and orthogonal to `status:`
+  (an approved document can be restricted, and a draft is not hidden). Leave
+  it off and the document takes `default_visibility`. The key does nothing
+  until `instance.md` declares `audiences:`; once it does, `pnpm check`
+  refuses any link or `superseded_by:` pointing from a wider audience at a
+  narrower one — the leak no single build can catch, because the build that
+  publishes the link has already dropped its target.
+
+  **Publication, not authorship: anyone who can clone the repository reads
+  every document regardless of frontmatter; if someone must not read a
+  document and can clone, the answer is a second repository.**
+
+- A replaced document is marked `status: superseded` with `superseded_by:`
+  pointing at its successor — superseded documents are never deleted.
+- Images and assets live in `knowledge/` beside the document that uses them,
+  referenced by relative links. A relative link must never leave `knowledge/`.
+- Copy load-bearing values (numbers, thresholds, dates) exactly from their
+  source, and name the source in `provenance`.
+
+### Structuring the record
+
+- A folder per topic; its front page is `<folder>/index.md`, and the folder
+  takes the position that page declares.
+- Sidebar position is the governed `order:` key: documents that declare it come
+  first, ascending; the rest follow in name order.
+- One order drives the sidebar, `llms.txt`, and the home page's first-document
+  link — set it once and every surface agrees.
+- Never `meta.json` or `sidebar_position`: the checker refuses framework files
+  in the record, which has to read the same without the site.
+
+## Skills
+
+- `.agents/skills/intake-interview/` — first run: interview the owner and
+  write `instance.md` together.
+- `.agents/skills/add-sources/` — turn source material (documents, pages,
+  notes) into governed knowledge.
+- `.agents/skills/format-checker/` — the rules above, as a program;
+  `pnpm check` runs it and its errors explain how to fix themselves.
+
+## Customizing the site
+
+You own `system/site/` outright — these are the seams, cheapest first:
+
+- **Display title** — `instance.md`'s body `# H1` (the intake interview
+  writes it). Headline, navbar, and browser title follow on restart.
+- **Accent color** — the one brand pair in `system/site/app/global.css`
+  (`--color-fd-primary`, light and dark); every accented element follows.
+- **Logo and favicon** — replace `system/site/app/icon.png`; the tab icon
+  and the home-page mark are the same file.
+- **Anything deeper** — edit the site like the Next.js app it is; the only
+  rule that survives customization is critical rule 1. The whole shell is
+  replaceable behind a five-clause contract (a themed Docusaurus shell with
+  a swap recipe lives in the ksor repository under `workbench/shells/`).
+
+## What this project owns
+
+Everything. The scaffold was emitted by `ksor init` (version recorded in
+`instance.md`) and belongs to this repository outright — change anything in
+`system/` deliberately; the knowledge in `knowledge/` was always yours.

package/templates/scaffold/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/templates/scaffold/README.md

@@ -0,0 +1,90 @@
+# KSOR-STAMP-NAME
+
+A **Knowledge System of Record**: the governed source of knowledge this
+project's people and AI agents operate from.
+
+Two worlds live here:
+
+- **`knowledge/` — the record.** Plain governed markdown. Yours forever,
+  readable anywhere, portable without this repository's code.
+- **`system/` — the system.** The site (and later, services) that serve the
+  record. Replaceable machinery.
+
+## Working here
+
+```sh
+pnpm install
+pnpm dev        # browse the knowledge at http://localhost:3000
+```
+
+No pnpm? Run `npm install -g pnpm` — or `corepack enable pnpm` on Node
+versions that bundle corepack.
+
+Then talk to your coding agent — `AGENTS.md` carries the working rules, and
+the agent kit in `.agents/skills/` knows how to interview you
+(`intake-interview`), convert your source material (`add-sources`), and keep
+the record well-formed (`format-checker`, also `pnpm check`).
+
+## The files, explained
+
+Nothing here is decoration, and the dotfiles are not ceremony — each one is a
+different coding agent's way of finding the same working contract.
+
+| Entry                            | What it is                                                                                                                                                                                                                       |
+| -------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `knowledge/`                     | **the record** — your governed markdown. The product; everything else serves it.                                                                                                                                                 |
+| `system/`                        | the code that serves the record: the site today, more as you need it.                                                                                                                                                            |
+| `instance.md`                    | what this record is authoritative for; its `name:` is the identity every surface publishes (read at server/build start — restart `pnpm dev` after renaming). When the agent surface ships, this prose becomes its system prompt. |
+| `AGENTS.md`                      | the working contract every coding agent reads first — the rules for writing knowledge here.                                                                                                                                      |
+| `CLAUDE.md`                      | one line, pointing at `AGENTS.md`. Claude Code looks for this filename, not that one.                                                                                                                                            |
+| `.agents/skills/`                | the agent kit: `intake-interview` (define the record with you), `add-sources` (turn source material into governed documents), `format-checker` (the rules, as a program).                                                        |
+| `.claude/skills/`                | byte-identical copies of the kit — Claude Code discovers skills only here. The checker enforces the mirror, so the two cannot drift.                                                                                             |
+| `.gemini/settings.json`          | points Gemini CLI at `AGENTS.md`; Gemini does not read that filename on its own.                                                                                                                                                 |
+| `.github/workflows/validate.yml` | your CI: runs the same checker on every pull request and push to main.                                                                                                                                                           |
+| `.gitattributes`                 | markdown is checked out byte-stable on every platform, so the same commit hashes the same everywhere.                                                                                                                            |
+| `.gitignore`                     | keeps build output, `node_modules/`, and `.env*` out of the record's history.                                                                                                                                                    |
+| `package.json`                   | the `pnpm dev` / `pnpm build` / `pnpm check` commands, and the pnpm version this project pins.                                                                                                                                   |
+| `pnpm-workspace.yaml`            | where the workspace looks for code (`system/site`, plus reserved `system/gateways/*` and `system/packages/*`), and the supply-chain policy for installs.                                                                         |
+| `pnpm-lock.yaml`                 | the exact dependency versions — the reason two machines build the same site.                                                                                                                                                     |
+
+`format-checker` deliberately contains a program, `check.mjs`, and not only
+prose: rules that are only written down cannot refuse anything. `pnpm check`
+runs it, and every failure it reports says what is wrong, why the rule exists,
+and how to fix it.
+
+Everything here is yours to change. The kit exists so that any coding agent can
+operate this project without being taught it first.
+
+## Deploying
+
+The built site is a folder of files — 2 MB of HTML, JS and CSS with zero
+host-specific dependencies. `pnpm build` writes it to `system/site/out/`,
+and anything that can serve files can serve it.
+
+- **Vercel** — connect the repository (or run `vercel`); the shipped
+  `vercel.json` answers the setup interview: deploy from the repo root
+  (never pin `system/site` as the root directory — the record lives
+  outside it), build with `pnpm build`, serve `system/site/out/`. If the
+  build image's pnpm predates the `packageManager` pin, set the
+  `ENABLE_EXPERIMENTAL_COREPACK=1` build environment variable.
+- **GitHub Pages, nginx, S3, anything static** — run `pnpm build` and
+  upload `system/site/out/`. Hosted under a sub-path (like
+  `user.github.io/repo`)? Build with `KSOR_BASE_PATH=/repo pnpm build`.
+- **Verify any deploy** the same way: the home page, one document page,
+  and `/llms.txt` all load; nothing else is required.
+
+If `instance.md` declares `audiences:`, what you deploy is a **tier**.
+Plain `pnpm build` always builds the public tier — safe for any host.
+`KSOR_AUDIENCE=<audience> pnpm build` builds a wider tier for that
+audience's own deployment, and that build carries an
+"— not for publication" label because it must never reach a public host:
+put it behind access control you already trust (VPN, SSO proxy,
+authenticated host). The tiers govern what a build contains; where each
+build may be served is yours to enforce.
+
+## Ownership
+
+Everything here is yours. The scaffold was generated by
+[ksor](https://github.com/panaversity/ksor) (version in `instance.md`) and is
+granted without attribution or licence obligations; your knowledge was never
+anyone else's to license.

package/templates/scaffold/gitignore

@@ -0,0 +1,16 @@
+# scratch space for ksor verbs — everything transient lives under one roof
+.ksor/
+
+node_modules/
+system/site/.next/
+system/site/.source/
+system/site/out/
+# the per-audience copy of the record a build stages — a filtered derivative,
+# never a second record; committing it would publish what a build excluded
+system/site/.staged-knowledge/
+*.tsbuildinfo
+
+# secrets never enter the record — system/ is their future home (serve)
+.env*
+
+.DS_Store

package/templates/scaffold/instance.md

@@ -0,0 +1,26 @@
+---
+format: 1
+name: KSOR-STAMP-NAME
+ksor:
+  requires: ">=KSOR-STAMP-VERSION"
+  scaffolded: "KSOR-STAMP-VERSION"
+---
+
+# Knowledge System of Record
+
+The heading above is this record's **display title** — the human name every
+page leads with. The intake interview replaces it with the real one
+("Acme Operations Handbook"); the machine identity stays `KSOR-STAMP-NAME`
+in the frontmatter, and that is what agents and citations use.
+
+This Knowledge System of Record is authoritative for — _fill this in; it is
+the single most important sentence in the project._
+
+Everything below this frontmatter is the identity of this instance: what the
+corpus covers, who it serves, and how strictly it should decline questions it
+does not cover. When the agent surface ships, this prose becomes its system
+prompt — write it for a reader who must act on it.
+
+Ask your coding agent to run the **intake interview** (it knows how — see
+`.agents/skills/intake-interview/`), answer its questions, and let it write
+this document with you.

package/templates/scaffold/knowledge/example.md

@@ -0,0 +1,23 @@
+---
+title: Your first governed document
+status: draft
+order: 1
+---
+
+This file exists so the record is never empty: browse it with `pnpm dev`,
+then replace it with real knowledge.
+
+A governed document is plain markdown with a small frontmatter header. This
+one carries the two required keys — `title` and `status: draft`. As the
+knowledge matures, documents gain `owner` and `provenance` (who stands behind
+this, and which sources it came from), move to `status: approved`, and — when
+replaced — are marked `superseded`, never deleted.
+
+It also carries `order: 1`, which is how the record decides reading order: a
+document that declares `order` sorts ahead of every document that does not, so
+this one stays first in the sidebar, first in `llms.txt`, and the document the
+home page opens.
+
+Ask your coding agent to run the **intake interview** to define what this
+Knowledge System of Record is authoritative for, then start adding documents
+with the **add-sources** skill. `pnpm check` keeps every document honest.

package/templates/scaffold/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "KSOR-STAMP-NAME",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "pnpm -C system/site dev",
+    "build": "pnpm -C system/site build",
+    "check": "node .agents/skills/format-checker/check.mjs"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "packageManager": "pnpm@11.22.0"
+}