Authoring a pack
A pack is small enough to write by hand and structured enough to check. This page walks the whole loop — scaffold, write a reference, bring knowledge in through whichever door fits, keep editions honest as facts change, and publish when it's worth sharing.
Your first pack
spectastic init scaffolds a corpus for you: an empty root registry and a throwaway example pack to edit into your own.
Rename the pack to your domain
Rename knowledge/example/ to something real — finance-settlement/, clinical-trials/ — and set the name / description in its SKILL.md.
Write a reference
Replace references/001-example.md with a real domain document — a distillation of a regulation, a standard, a house convention — and give it a NNN-topic slug that matches its file name.
Fill the frontmatter
Set origin, origin-url, edition, license, and converter: hand-authored. Leave content-hash for the tooling — never type a hash.
Register it
The root registry is never hand-authored — the ingester mints each KB-NNNN and its row. Run the pack you wrote through corpus adapt: it computes the content-hash and writes the registry rows. Then add the reference to the pack's SKILL.md slug-map table.
Validate
Run spectastic validate. A well-formed pack with resolvable citations comes back green; a gap in provenance or a bad license is surfaced, not swallowed.
Writing a reference
A reference is a plain markdown file: provenance frontmatter, then the distilled knowledge. The anatomy page details every field; the two habits that matter most when writing one by hand:
Distill, don't dump. A reference is a hand-authored distillation of a public fact — the settlement window, the WCAG threshold — not a verbatim reproduction of a copyrighted source. Name the source in origin / origin-url, and keep the license inside the permissive allowlist.
Never hand-type the content-hash. It's a sha256 of the document's bytes — the integrity anchor that lets a later check tell an intact reference from an edited one. There's no separate hash command: a tool door (corpus adapt, convert, or import) computes it and writes it when it files the document. The scaffold ships it as TODO precisely so you leave it alone until then — a hash typed for content that hasn't been ingested is a lie waiting to happen.
The doors
Knowledge gets into a corpus through one of several doors, chosen by where it came from. They're one contract with one variable: each records a different origin, and the doors that need a human to vouch carry a status guard. Downstream — the id, the citation, the gates — every door is identical.
Converted
A source document — a PDF, a spec — run through a user-installed converter into cited markdown.
origin: the source fileSourced
A primary text fetched from an allowlisted authority — a regulation from its canonical home.
origin: the fetch URL · pends confirmationInterviewed
Tacit house knowledge captured from a subject-matter expert, in their words.
origin: the expert's role · pends sign-offAdapted
An existing markdown folder or llms.txt reshaped into the convention.
Imported
A published pack someone else curated, installed from a marketplace.
origin: the upstream packHand-authored
You write the distillation yourself — the quickstart above. converter: hand-authored.
Each command's flags and guards are in the command reference. The status guard is the honest bit: a source or interview reference registers as pending until a human confirms it — the corpus records that it isn't yet vouched for, rather than quietly treating an unverified fetch as authoritative.
Superseding an edition
When a domain fact changes in the world, you don't overwrite the reference — you append a new edition. The prior document is retained so every citation ever written against it still resolves.
The registry's Edition column moves to the new date; the prior edition lands under references/superseded/ as <slug>@<edition>.md, keeping its own frontmatter with status: superseded. A decision still pinned to the old edition now resolves as stale — a warning to re-ground, not a broken link. Supersession is append-only: a prior edition is never overwritten. The settlement example walks this end to end →
Publishing
A pack worth sharing becomes discoverable with one command. corpus publish generates a marketplace.json from your registry, so another project can corpus import it by coordinate.
Publishing is opt-in and one-directional: it reads your registry and writes the manifest — hand-edited cells survive a re-sync. A project that only consumes packs keeps its registry and no manifest. See discoverability and the publish command.