wiki-studio 0.2.0

Karpathy-pattern LLM wiki maintainer: a curated markdown knowledge base (index.md, log.md, typed pages with cited sources) that agents ingest into, query from and lint. Standard library only; the LLM backends are copilot CLIs the tool shells out to.

The code was extracted from gosha70/code-copilot-team (see NOTICE); the page schema is shared with memkernel's wiki bridge.

Install

pip install wiki-studio          # Python 3.11–3.13, no runtime dependencies
wiki-studio --help
wiki-studio --version           # 0.2.0

From a checkout: poetry install, then poetry run wiki-studio --help.

Layout

With no flags and no variables wiki-studio reproduces the original code-copilot-team layout under the git toplevel of the current directory:

Flags beat variables, variables beat defaults. The three flags are accepted before or after the verb. Relative flag and variable values are taken from the current directory.

Verbs

wiki-studio ingest <source>

Runs the four-question gate over a source file and writes a patch-set (plan.json plus preview/<page>.md for every page it would create or update) under <proposals-dir>/<date>-<source-stem>/, then appends one line to the ingest audit log.

wiki-studio promote <proposal-dir>

Applies a patch-set to the wiki atomically. The staged tree is validated page by page and by the structural linter before anything is written; on success the proposal directory moves to <proposals-dir>/.applied/ and the accepted proposal is archived under <wiki-dir>/.audit/proposals/. This is the only code path that writes into the wiki.

wiki-studio query "<question>"

Reads index.md first, loads the most relevant linked pages, asks the backend, and prints the answer; citations and the pages loaded go to stderr and the pages-loaded set is appended to the query log.

wiki-studio lint

Structural lint of every page: frontmatter present and well formed with the required keys; page_type known; slug equals the file name and is unique; the page lives in its type's directory; intra-wiki links resolve; every page except index.md and log.md is reachable from index.md. The audit tree under .audit/ is always checked against schema/audit-rules.md as well.

wiki-studio audit-flush

Commits pending lines of the ingest audit log. The only verb that runs git commit; never invoked automatically.

Exit codes

Backends

Resolution order: --backend, then WIKI_STUDIO_BACKEND, then auto-detect, which probes PATH for claude, codex, pi (only when enabled), cursor in that order. WIKI_INGEST_BACKEND is still accepted and prints a deprecation warning on stderr.

Backend stderr may echo source content, so error messages carry a redacted fingerprint of it unless --debug-unsafe-output is given.

Environment variables

Schema

The page schema (page-types.md, ingest-rules.md, citation-rules.md, lint-rules.md, audit-rules.md, WIKI_MAINTAINER.md) ships inside the package and is what the prompts and the linter follow. A project may carry its own copy under <wiki-dir>/schema/; when that directory exists it is used instead of the packaged one. The schema is a published contract shared with memkernel's WikiExporter and WikiImporter; changing frontmatter keys, page types or directory names needs a decision record in docs/adr/.

The same facts are available as code in wiki_studio.schema: PAGE_TYPES maps each page type to a PageTypeSpec (directory, required_sections, promotable, sources_required), and VALID_PAGE_TYPES, PAGE_TYPE_DIRS and REQUIRED_KEYS are derived from it. The linter and the validators read this module; a consumer that keeps its own copy can test it against PAGE_TYPES, and a test here keeps the module in step with page-types.md.

Library

from pathlib import Path

from wiki_studio import api
from wiki_studio.paths import WikiPaths

paths = WikiPaths.for_root(Path("."))                 # or WikiPaths.resolve(wiki_dir="kb")

result = api.ingest(Path("notes/2026-10-12-outage.md"), paths, backend="claude")
print(result.disposition, result.written, result.edits)

api.promote(result.written, paths)                     # PromoteResult
answer = api.query("what caused the outage?", paths, backend="claude").answer
print(answer.answer, [c.page for c in answer.citations])

report = api.lint(paths, health=True, strict=True)     # LintResult
print(report.passed, report.violations, report.health.findings)

api.audit_flush(paths, dry_run=True)                   # AuditFlushResult

A caller that composes pages itself (memkernel's exporter, a migration script) hands them to propose and gets a proposal directory promote accepts, so they pass the same gate as a backend's draft:

from wiki_studio.api import PageEdit

edits = [
    PageEdit("concepts/retry-budget.md", "create", page_markdown, "New concept."),
    PageEdit("index.md", "append-index", "- [Retry budget](concepts/retry-budget.md) — draft.", "Index it."),
    PageEdit("log.md", "append-log", "- 2026-10-15 — created retry-budget (concept): draft.", "Log it."),
]
proposal = api.propose(edits, paths, name="2026-10-15-retry-budget")   # Path; ContractViolationError on bad edits
api.promote(proposal, paths)

The functions raise the exceptions in wiki_studio.errors; each carries the exit code the CLI would use. backend may be a name, None (resolution order as above) or any object with call(prompt) -> dict.

The api functions and their keywords, the result dataclasses, PageEdit, PageAction, WikiPatchSet and the proposal directory format (docs/patch-set-format.md) are public and follow semantic versioning: removals and renames only in a major version, additions with defaults in a minor one.

Consumer recipes for code-copilot-team, memkernel and document-assistant are in docs/consumers.md.

Development

poetry install
poetry run ruff check src/ tests/ && poetry run ruff format --check src/ tests/
poetry run mypy src/
poetry run pytest -q --cov=wiki_studio --cov-fail-under=80
poetry build

License

Apache-2.0. See LICENSE and NOTICE.