knowledge-base

Knowledge Base pack — how to work here

This project uses the source-grounded knowledge-base layout. The whole point is a closed evidence loop: nothing canonical exists without a traceable chain back to a preserved source. This skill holds the workflow so the templates and log.md can stay clean — when you create a doc from a template you get structure, and the how lives here.

This skill is pack guidance. The platform /open-knowledge skill (read/write/preview/linking/grounding rules) still governs every markdown operation — this layers the KB workflow on top.

Link at creation

The user watches your build live — the editor follows the file you're writing, and the knowledge graph assembles on screen as pages get linked. No view management on your part; just author well: every page carries its links from the moment it's written (at minimum the hub/index page and its most related siblings — an unlinked page is invisible in the graph), and related pages share a cluster: frontmatter value (e.g. cluster: architecture) so the graph's cluster coloring makes the map read at a glance.

The three layers

external-sources/   raw sources, saved verbatim     (produced by `ingest`)
      ↓ cite
research/           provisional analysis            (produced by `research`)
      ↓ promote
articles/           canonical, decided knowledge     (produced by `consolidate`)

The loop is ingest → research → consolidate, mapped to Karpathy's three-layer knowledge-base pattern. Every downstream claim traces upstream to a preserved source. Cite local paths in external-sources/, never bare web URLs — the KB must survive link rot.

Karpathy's insight: "The tedious part of maintaining a knowledge base is not the reading or the thinking — it's the bookkeeping." Humans abandon wikis because maintenance costs exceed perceived value. These procedures exist so an agent can do the bookkeeping (fetching, summarizing, cross-linking, superseding) without fatigue. Skipping the cross-linking, supersedes chains, or raw-source preservation is what turns a useful wiki back into an abandoned one.

The three procedures

Each layer has a full, STOP-gated procedure, and each ships as its own skill so it loads only when the work calls for it. Execute the procedure yourself with the OK verbs — these are your default move over a bare write when the work fits a layer.

Procedure	Where it lives	When
ingest	Platform /open-knowledge skill (references/ingest-and-sources.md) — its Grounding rule depends on it everywhere, so it ships with every project, not just this pack.	Preserve a shared URL / PDF / file verbatim, OR you fetched a URL to ground a KB claim (binary sources preserved, not scraped).
research	Sibling skill /research-with-sources	Investigate / compare / synthesize multiple sources → provisional article with status: draft + sources:.
consolidate	Sibling skill /consolidate-notes	A decision was actually made → commit canonical source-of-truth with status: stable + a supersedes: chain.

Typical day-2 flow: user shares a URL → ingest (preserve) → user asks "now research this" → research (provisional article, ingesting more sources as needed) → decision lands → consolidate (canonical article, supersedes the research).

Don't chain silently. After ingest, ask whether to proceed to research. After research, let the user decide whether the findings are ready to consolidate. Each procedure completes on its own terms — the user drives the transitions.

Autonomy gates vs session-level autonomy. A procedure's STOP gates (research's scoping gate, consolidate's decision-confirmation gate) are NOT overridden by session-level "work without stopping for clarifying questions" hints. Those hints cover trivial back-and-forth ("which file did you mean?"); the gates exist for one-way-door decisions. When in doubt, the gate is authoritative.

Per-folder rules

external-sources/ — Raw sources saved verbatim, not just cited: the actual fetched text of URLs, extracted text of PDFs, copies of referenced files. Each file's frontmatter carries the original URL, access date, and any author/publisher metadata. Produced by the ingest procedure (applies whether the user shared the URL or you fetched it yourself to ground a claim). Immutable after capture — update only to refresh a stale fetch. No analysis here; that belongs in research/.

research/ — Provisional analysis synthesizing external sources, stored as OKF status: draft. Produced by the /research-with-sources skill. Every factual claim cites a specific doc in external-sources/ (or an inline URL if ingest was skipped); no unsourced assertions. Keep the sources: frontmatter list aligned with the docs actually linked in the body. Promote to articles/ via the /consolidate-notes skill once the team decides the findings are stable.

articles/ — Canonical knowledge, committed after a team decision and stored as OKF status: stable. Produced by the /consolidate-notes skill. Carries a supersedes: chain tying back to the research/ docs it replaces (which in turn cite external-sources/) so the full evidence chain is traceable without leaving the repo. Source-of-truth for the domain; update only when a new decision supersedes it.

Status flow

Layer	status	Set when
research/	draft	created
articles/	stable	promoted by consolidate after a decision

When a new article supersedes research, set that research to status: deprecated, add its path to the article's supersedes: list, and point it back with superseded_by:.

Legacy compatibility

Older projects may use status: provisional / canonical and string entries under sources:. Read those forms as draft / stable and source resources. Do not rewrite untouched documents; use the OKF forms above for new writes and files you are already updating.

Log discipline (MUST)

There is a log.md at the project root. Append one dated entry after any turn that creates, edits, or restructures content — one entry per turn, not per file. Silent edits break the audit trail.

Log: ingest runs (new sources), research / consolidate runs (provisional or canonical articles), direct write / edit / move / delete outside the three procedures, project-onboarding runs, folder restructures, and .ok/config.yml changes.

Reference docs as markdown links, not bare paths — [path/to/doc](./path/to/doc.md), so the entry shows up in links({ kind: "backlinks" }) for those docs. A bare path string does not register in the graph.

Because this append-only log.md is a reserved log, its broken links may be withheld from audit. When a clean result carries brokenLinkSuppression, it is filtered rather than proof that every raw link resolves; do not rewrite log history to clear those links.

Entry shape:

## YYYY-MM-DD: <short title>

- <what was done>
- Files touched: [doc-a](./path/doc-a.md), [doc-b](./path/doc-b.md)
- Sources ingested: [source-slug](./external-sources/source-slug.md)
- Open follow-ups: <topic-1>, <topic-2>

Templates

Each folder has a starter template (clip, research-log, article). Create with write({ document: { path, template: "<name>" } }). Templates carry only structure (headings + frontmatter scaffold) — the meaning of each field and section is described above, not repeated inside the document body.