wiki-studio 0.1.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.1.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/.

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

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.

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.