Wikismith

Build and validate verified knowledge bases your tools and agents can trust.

What it is

Wikismith is a CLI that builds and validates OKF-native knowledge bundles: structured, verifiable collections of knowledge pages your tools and agents can draw on with confidence.

OKF (Open Knowledge Format) is a structured container for knowledge pages. Every page carries typed frontmatter, cross-references are written as named wikilinks, and the whole bundle is self-describing and readable by any markdown-aware tool. The format is permissive by design. Wikismith enforces a quality bar above that floor: link integrity, provenance attestation, licensing, and verification counts. The result is a bundle trustworthy enough to sign and ship.

You (or your CLI agent) author the content. Wikismith owns the structure. It regenerates indexes and link graphs deterministically, enforces a closed-world referential integrity guarantee, and catches broken references before they can leave your workspace.

Why this matters

The LLM-wiki pattern works, but telling an agent to “comply with the template” is inference-dependent and rarely fully correct. Wikismith makes compliance a binary-enforced invariant, not a hope. The same guarantee holds whether a human or an agent authored the pages.

When to use it

Reach for Wikismith whenever you want a knowledge base that a tool or agent can draw on reliably:

• Compliance control catalogs, policy bodies, or regulatory knowledge
• Domain knowledge for a field, project, or team
• Curated research references an agent should cite
• Any LLM-wiki where structure and link correctness must be guaranteed

The output is portable, signed, and in standard markdown. Any tool that can read markdown can traverse it.

What you get

A Wikismith bundle is a directory with a predictable layout:

my-bundle/
├── wiki/                     # your knowledge pages
│   ├── index.md              # auto-generated; do not hand-edit
│   ├── log.md                # auto-appended; do not hand-edit
│   ├── concepts/
│   ├── entities/
│   ├── syntheses/
│   └── sources/
├── raw/sources/              # immutable source provenance
├── bom/                      # bill of materials (emitted and signed)
└── .wiki/
    ├── config.yaml           # mode, stale threshold, license, vocabulary
    ├── manifest.json         # integrity hashes for out-of-band edit detection
    ├── sources.yaml          # per-source licenses for the BOM
    └── seal                  # version + digest + signature when sealed

index.md and log.md are derived files that wikismith build regenerates on every run. Do not hand-edit them.

How to use it

Install

Build the CLI from source:

target/release/wikismith

cargo build --release
# UI binary:    target/release/wikismith-ui

Put wikismith on your PATH before running any other commands. If the binary is not on PATH, every command accepts --bundle <path> to specify the bundle root explicitly.

Author a bundle

1. Create a new bundle

wikismith init ./my-bundle --license MIT

The --license flag attests an SPDX license expression upfront. You can set or change it later with wikismith license set <spdx>. A bundle without an attested license fails the validation gate.

2. Add source material

Copy your source documents into raw/sources/. Treat that folder as immutable provenance. wikismith never modifies files there.

3. Scaffold pages

wikismith new concept     attention
wikismith new synthesis   transformer-architecture
wikismith new entity      openai
wikismith new source-summary  attention-paper --source raw/sources/attention.md

The four built-in page types are concept, synthesis, entity, and source-summary. You can declare a custom type vocabulary in .wiki/config.yaml under types:. The validation gate enforces that every page’s type is in the declared set.

Edit the body of each scaffolded page freely in any text editor or through your CLI agent. Use [[slug]] wikilinks to cross-reference other pages in the same bundle. Do not edit index.md or log.md.

4. Rebuild derived files

wikismith build

Regenerates index.md, the log, and the link graph. This command is idempotent. Run it whenever you add or rename pages.

5. Validate

wikismith validate

The validation gate classifies every finding into blocking errors or advisory warnings.

Errors (block distribution): unparseable frontmatter, a missing or empty type field, broken cross-links, a missing bundle license, a custom LicenseRef- with no resolvable license text.

Warnings (informational): orphan pages with no inbound links, stale timestamps, low confidence scores, stub pages that have never been authored, missing source citations, out-of-band edits detected on locked or sealed bundles.

Resolve every error before distributing. Warnings do not block distribution but surface real quality gaps worth addressing.

Machine-readable output for tooling

Pass --json to receive a single JSON object on stdout instead of human-readable lines:

wikismith validate --json

{
  "ok": false,
  "error_count": 1,
  "warning_count": 2,
  "errors": [
    "wiki/concepts/attention.md: link [[transformer]] has no target page; create it with `wikismith new <type> transformer` or fix the slug"
  ],
  "warnings": [
    "wiki/concepts/attention.md: no sources cited",
    "wiki/entities/openai.md: orphan (no inbound links)"
  ]
}

In --json mode the process exits 0 even when errors are present. Key off ok, not the exit code, so your tooling can always parse the body.

6. Emit distributable output

wikismith emit okf          # OKF v0.1 bundle under dist/
wikismith emit llms-txt     # llms.txt format for LLM context windows
wikismith emit schema-org   # Schema.org JSON-LD under dist/
wikismith emit bom          # CycloneDX 1.6 + SPDX 3.0.1 + NOTICE under dist/bom/

emit okf converts [[wikilinks]] to standard relative markdown links so any reader can traverse the output without knowing the authoring format. At the emit gate, dangling cross-links and undeclared external namespaces that were warnings during authoring become hard errors.

Staged review mode

When you want human approval before anything goes live, switch the bundle to staged mode in .wiki/config.yaml:

mode: staged

In staged mode, wikismith new routes pages to .wiki/pending/ instead of publishing them immediately:

wikismith new concept  retrieval-augmented-generation
wikismith pending                                       # list what is waiting
wikismith approve --all                                 # publish everything pending
wikismith reject  retrieval-augmented-generation        # or discard one

Seal for distribution

Once validation passes with zero errors, seal the bundle for distribution:

wikismith keygen --out publisher.key           # generate an Ed25519 keypair
wikismith seal --sign publisher.key            # stamp a version + whole-bundle digest
wikismith verify --key publisher.pub           # confirm integrity and authenticity

A sealed bundle is read-only. To revise it, run wikismith unseal, make your changes, re-validate, and re-seal. Re-sealing increments the version automatically.

For a single distributable image:

wikismith pack --sign publisher.key --version 1
wikismith verify --image bundle.squashfs

Identical content produces byte-identical images, so a third party can independently rebuild and compare.

The UI workspace

wikismith-ui is a local web interface that makes the validation verdict visible without running CLI commands directly.

wikismith-ui             # binds http://127.0.0.1:7979 by default
wikismith-ui --port 8080

If wikismith is not on your PATH, tell the UI where to find it:

WIKISMITH_BIN=/path/to/wikismith wikismith-ui

The UI shows a VERIFIED / NOT VERIFIED verdict, a count of errors and warnings with their full messages, and a browse list of every knowledge node (title, type, and path). It calls wikismith validate --json internally. It adds no validation logic of its own. The CLI is the sole source of truth.

Common pitfalls

Editing index.md or log.md by hand. These are derived files that wikismith build regenerates and overwrites. Any edits to them are lost on the next build. Author content only in the page files under concepts/, entities/, syntheses/, or sources/.

Forgetting to set a bundle license. A bundle without an attested license fails the validation gate with a blocking error. Set it once at init (wikismith init --license MIT) or afterward with wikismith license set MIT.

Using a custom LicenseRef- without providing the license text. A LicenseRef-<id> requires either a LICENSE file at the bundle root or a .wiki/licenses/<id>.txt file. Without it, validate reports a blocking error. The built-in LicenseRef-Proprietary ships with canonical text, so the no-action path is always complete.

Writing [[slug]] links to pages that do not exist yet. During authoring, a dangling cross-link is a warning tagged (blocks emit/seal until resolved). At the distribution gate (emit, seal, pack), it becomes a hard error. Create the target page with wikismith new or correct the slug before you distribute.

Using a page type not in the declared vocabulary. If .wiki/config.yaml declares a types: list, every page’s type frontmatter field must appear in that list. An undeclared type warns during authoring and errors at the distribution gate. Add the type to types: in config.yaml to declare it, making the act of extending the vocabulary explicit.

Citing a source file that is outside the bundle. Source paths must live inside the bundle root. Paths with .. segments that climb above the root, absolute paths, and paths that resolve through a symlink to a location outside the bundle are hard errors regardless of mode.

Hand-editing a locked or sealed bundle. A locked or sealed bundle reports out-of-band edits as warnings at the next validate run. To revise a sealed bundle, run wikismith unseal first.

Dangling links become hard errors at the distribution gate

A [[wikilink]] to a missing page is a warning while authoring, but becomes a blocking error when you run emit, seal, or pack. Resolve every dangling link before distributing.

Troubleshooting

Symptom	Cause	Fix
error: bundle has no license	No license was attested in .wiki/config.yaml	Run wikismith license set <SPDX> (for example, wikismith license set MIT)
error: link [[slug]] has no target page	A wikilink points to a page that does not exist	Create the page with wikismith new <type> <slug>, or correct the slug in the source file
error: type '<value>' is not in this bundle's vocabulary	The page’s type field is not in the declared types: list	Add the type to types: in .wiki/config.yaml, or change the page’s type to a declared value
error: bundle license <id> is a custom LicenseRef with no text	A LicenseRef-<id> license has no text file to resolve to	Add a LICENSE file at the bundle root, or a .wiki/licenses/<id>.txt file
warning: orphan (no inbound links)	A page has no other pages linking to it	Add a [[slug]] link from a related page, or accept the warning if the page is intentionally standalone
warning: no sources cited	A page cites no source and does not declare provenance: original	Add sources: [raw/sources/your-file.md] to the page frontmatter, or add provenance: original if the content is first-party
warning: stub (no authored content)	A scaffolded page body still contains only the placeholder comment	Replace the <!-- author content here --> placeholder with real content
error: sources.yaml failed to parse	.wiki/sources.yaml contains malformed YAML	Fix the YAML syntax in .wiki/sources.yaml and re-run validate
error: config.yaml failed to parse	.wiki/config.yaml has a mistyped key (for example refernces instead of references)	Fix the key name in .wiki/config.yaml and re-run validate
wikismith-ui shows “wikismith binary unavailable”	The wikismith CLI is not on PATH	Set WIKISMITH_BIN=/path/to/wikismith before starting wikismith-ui
wikismith-ui validate call returns a parse error	The installed wikismith build does not support --json	Rebuild wikismith from source to get v1.0.2 or later, which added --json support
warning: out-of-band edit detected	A file in a locked or sealed bundle was changed outside the CLI	Run wikismith unseal to return the bundle to a writable state, make your changes through the CLI, and re-seal

First-party content does not need a source citation

If a page contains knowledge you authored yourself rather than derived from an external source, add provenance: original to its frontmatter. Wikismith will not warn about missing source citations for pages with that declaration.