add-sources

name	add-sources
description	Turn source material — documents, pages, pasted text, notes — into governed knowledge in knowledge/. Use when the owner shares material to add, says "add this to the knowledge base", or asks how to get existing content in. Not for editing the site.
metadata	{"version":"1.3.0"}

Add sources

Converting material into the record is the everyday work of this project. The rules that make it governed rather than merely stored:

Placement and shape

• One document per topic, under knowledge/, path = identity: lowercase, hyphens, a folder per natural grouping. Plain CommonMark .md — if the source is rich (tables, images), tables become markdown tables and images land beside the document with relative links.

• A folder's index.md is GENERATED by ksor build and committed — never author one. A folder's own introduction is a named document inside it, such as overview.md. Reading order is the order: frontmatter key (ordered documents first, ascending; the rest follow alphabetically) — never meta.json or sidebar_position.

• Frontmatter is the KSoR Profile of OKF. Always: type: Document, title, description (one sentence), status: draft, and ksor.audience (a list). Reach for a reserved type — Policy, Procedure, Control, Standard, Definition, Decision Record, Example, Attested Computation — when the knowledge really is one; those additionally require sources and ksor.owner, which is the point of them.

  ---
  type: Policy
  title: Purchase approval
  description: Who may approve a purchase, at which thresholds.
  status: draft
  sources:
    - id: fin-2025
      title: Finance policy manual §4.2, 2025 edition
      resource: https://intranet.example.com/finance/manual.pdf
  ksor:
    audience: [public]
    owner: team:finance
  ---
  
  A purchase above 10,000 needs a director's signature. [^fin-2025]
  
  [^fin-2025]: Finance policy manual §4.2, 2025 edition.
  

  Every source needs a resource — a URL where one exists, otherwise the scope descriptor that names it ("Finance policy manual §4.2, 2025 edition"). Precision matters: that governs; "internal docs" does not. A claim cites ONE of them by footnote, and the label must match a sources[].id or the checker refuses it.

• status: draft always, and never anything else from here: stable needs ksor.approval by an actor .ksor/governance.yaml names, and recording an approval nobody gave is the one thing this skill must never do. Ask the owner; if they approve, THEY are the approver and you write down what they said.

• When .ksor/governance.yaml registers audiences, ask the owner which of them may read the new material and list every one in ksor.audience — never guess that restricted material is public, and never write an identifier the registry does not declare (the checker refuses it, because a typo reads as a restriction).

Fidelity rules

• Copy load-bearing values exactly — numbers, thresholds, dates, names. Never round, never paraphrase a figure.
• Two disagreeing sources stay two statements, each with its own footnote — never smooth a conflict into one invented truth; flag it to the owner.
• Do not fill gaps from general knowledge. If the source doesn't cover something, the record doesn't either — that boundary is the product.
• A document replacing an older one: mark the old one status: deprecated with ksor.deprecated: { by, at } (a takedown authority the policy names, or the owner an ownership: rule resolves — never the document's own ksor.owner; ask, never guess) and ksor.superseded_by: naming the successor by id (policies/refunds-v2, no ./ and no .md) — never delete it. The successor must exist, be stable, and be readable by every reader of the deprecated one.

Finish every batch

Run pnpm check and fix what it reports (its errors explain themselves), then ksor build to regenerate every folder's index.md and write build.lock.json, and commit both with the documents. Then show the owner the rendered result (pnpm dev) — the site is the review surface: you write, they check.