The corpus commands
Everything the corpus needs at the command line lives under one group, spectastic corpus. The commands below are the current, shipped surface — run spectastic corpus <cmd> --help for the authoritative flags. Then there's the other half: the lifecycle verbs that read the corpus to ground their work.
The corpus group
Two jobs: bring knowledge in (by door, by where the knowledge came from), and keep the corpus healthy (migrate an old pack, publish for reuse). Every path ends the same way — a registered reference the resolver can find and validate can check.
Bringing knowledge in
Reshape an existing corpus you already have — a folder of markdown files, or an llms.txt — into the spectastic knowledge/ convention: slugs, frontmatter, a SKILL map, and registry rows.
- Flags
- --pack <name> the pack name under
knowledge/(defaults to the source folder's name) - Emits
- a two-layer pack plus its registry rows — lossy where the source lacked provenance, and it says so (fields it can't fill are left as
TODOfor you to complete).
Turn a source document — a PDF, or another format the converter supports — into a cited corpus document. The converter is a user-installed CLI (MarkItDown by default); none is bundled.
- Flags
- --pack <name>--converter markitdown|docling|marker--no-adapt--out <path>--title--description--timeout <s>
- Emits
- the converted markdown filed into a pack (or, with
--no-adapt, the raw markdown to stdout /--out).
Install a converter isolated (bare pip is blocked on modern macOS): pipx install 'markitdown[all]'. spectastic never bundles one — the conversion tool is yours to choose and trust.
Register a document fetched from an allowlisted authority as a reference — the source door for a primary text (a regulation, a standard) you retrieved from its canonical home.
- Flags
- --marketplace--plugin--slug--title--body <text>--date <YYYY-MM-DD>--allow <host>
- Origin
- records the fetch URL and date as provenance.
The standing authority allowlist is deferred — --allow <host> whitelists a host for the run; the full list is tracked as TBD-corpus-authority-allowlist.
Capture a subject-matter expert's answer as a reference — the interview door, for tacit house knowledge that isn't written down anywhere citable.
- Flags
- --marketplace--plugin--slug--title--body <text>--date <YYYY-MM-DD>
- Origin
- records the expert's role and interview date.
Running the elicitation is deferred (TBD-corpus-interview); this registers already-captured text — status not-citable-until-signed-off until the expert vouches for it.
Install a published pack from a marketplace and register its references into your root registry — the reuse door: someone else already curated this domain.
- Flags
- --from <path> register an already-fetched local checkout instead of installing one
- Emits
- registry rows for the imported pack, each assigned a fresh
KB-NNNNunder the(marketplace, plugin, slug)anchor.
The network fetcher is a seam (currently a stub); today you register a local checkout with --from <path>.
Keeping it healthy
Convert a single-layer pack — one that carries a document-level id: and a pack-local index.md — to the two-layer convention (a slug: plus a root registry row) in place.
- Safe
- idempotent — a no-op on an already-migrated pack, so it's safe to re-run.
Generate or refresh this corpus's marketplace.json from its root registry, so the corpus is discoverable without a hand-written manifest.
- Emits
marketplace.json— synced from the registry; hand-edited cells survive a re-sync. This is the publishing side; a plain consumer repo keeps the registry, not a manifest. More →
The bring-in doors are one contract with one variable: they differ only by where the knowledge came from — recorded in each reference's origin — and by a status guard on the doors that need a human to vouch (source pends confirmation, interview pends sign-off). Everything downstream — the id, the citation, the gates — is identical regardless of which door was used. The authoring guide walks each door →
How verbs consume it
The commands above build the corpus. The lifecycle verbs read it — grounding is not a separate step you invoke, it's something the everyday verbs do when a corpus is present.
When a design-bearing decision rests on a domain fact — a settlement window, a regulatory threshold, a clinical rule — design may ground it verified by citing KB-NNNN@edition in the <spec-decision>, resolved against the root registry. A local product decision — a latency target, a stack pick — is not a domain fact and must not manufacture a citation.
If a corpus is present, the change critic adds a fourth risk: a requirement in the live spec that contradicts a domain fact committed under knowledge/, citing the contradicted KB-NNNN@edition. No knowledge/ directory, and the fourth risk is skipped entirely.
When the thing being explained rests on a domain fact, explain cites the corpus — the same KB-NNNN@edition form a <spec-decision> uses — so the explanation inherits the evidence rather than re-asserting it. No corpus, no citation.
Runs the grounding gates over every citation — corpus-provenance (error), corpus-staleness and corpus-citation-form (warnings), corpus-license (warning). The gates in detail →