Metadata-Version: 2.4
Name: agent-wiki-cli
Version: 1.2.0
Summary: CLI tool to maintain hybrid LLM Wikis for multi-language projects.
Author-email: Denis Sivagin <denissvgn@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/Denissvgn/python-wiki-llm
Project-URL: Repository, https://github.com/Denissvgn/python-wiki-llm
Project-URL: Issues, https://github.com/Denissvgn/python-wiki-llm/issues
Keywords: llm,wiki,documentation,ai,agents,code-context
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: tomli>=2; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0; extra == "dev"
Provides-Extra: typescript
Provides-Extra: go
Provides-Extra: rust
Provides-Extra: mcp
Requires-Dist: mcp<2,>=1.27; python_version >= "3.10" and extra == "mcp"
Dynamic: license-file

# LLM Wiki CLI

LLM Wiki CLI builds and maintains a repo-local architectural wiki for coding
agents. It scans source code into a compact structural inventory, generates
Markdown pages under a wiki directory, validates those pages against the live
codebase, and prepares or triggers wiki-sync prompts after commits.

The PyPI distribution is `agent-wiki-cli`. The installed console command remains
`llm-wiki`, and the Python import package remains `llm_wiki_cli`.

## What It Creates

The default wiki lives at `docs/llm_wiki/`. Its page taxonomy is defined by the
canonical wiki surface registry:

| Surface | Role | What belongs there |
|---|---|---|
| `index.md` | mixed | Registry-backed landing page with page-kind counts and navigation for generated pages. |
| `log.md` | generated / agent-appended | Append-only architectural change log. |
| `entities/` | semantic | Class, struct, interface, and type pages with generated structure and relationship summaries. |
| `modules/` | semantic | Source-file pages with generated imports, symbols, and local dependency maps. |
| `workflows/` | mixed | Detected or manually maintained cross-module flow pages. |
| `guides/` | semantic | Agent-authored onboarding, operator, and contributor guides. |
| `flows/` | mixed | User-flow pages, one per detected entry point, with bounded generated Mermaid call and data-flow diagrams. |
| `infrastructure/` | mixed | Dockerfile, Compose, GitHub Actions, Kubernetes, and targeted runtime/config YAML pages. |
| `dependencies.md` | mixed | Optional internal and external dependency architecture page. |
| `load-order.md` | mixed | Optional load-order, cycle, and startup-caveat architecture page. |

The wiki also contains `.llm-wiki-manifest.json`, the source hash manifest used
by incremental sync and strict linting, and `.llm-wiki-surface.json`, a
deterministic machine-readable index of canonical pages, source mappings,
surface counts, flow metadata, dependency-page presence, and internal wiki
links. Generated Mermaid diagrams, including bounded call-sequence, data-flow,
dependency, and relationship diagrams when present, plus generated tables,
links, headings, canonical filenames, and machine-readable artifacts are
CLI-owned and may be regenerated by `sync`. Agents should edit semantic prose
instead:
descriptions, workflow notes, guide prose, `flows/*` `## Behavior` sections,
architecture-page `## Notes` sections, custom `index.md` notes, and concise
`log.md` summaries.
Full bootstrap renders entity `## Relationships` sections with bounded Mermaid
diagrams and compact reference tables when relationship metadata exists. When
dependency analysis is enabled, module pages also get a generated
`## Local dependency map` section with a bounded Mermaid mini-map, neighbor
tables, cycle highlighting, external package counts, and concise empty-state
notes instead of blank diagram fences. Haskell declaration entity relationship
summaries use `Module | Declaration kind` instead of Python-oriented methods
and attributes columns.

Registry-backed surfaces are distributed through the available query and mirror
interfaces. The MCP server exposes read-only resources, search, and status
counts for the same surface kinds. The supported Python API exposes source
inventory, context payloads, registry-backed page metadata, and graph queries
through `extract_source(...)`, `build_context(...)`, `list_wiki_pages(...)`, and
the documentation query wrappers. `llm-wiki obsidian export` mirrors the canonical
Markdown wiki for Obsidian, and `llm-wiki site export|check` mirrors and validates
plain, MkDocs-compatible, or Docusaurus-compatible Markdown output without
invoking external builders. Static-site output is a derived artifact; it must
not become a second editable source of truth.

The package has no required Python runtime dependencies. Optional features use
external tools when they are available on `PATH`.

## Supported Inputs

| Area | Implementation | Runtime requirement |
|---|---|---|
| Python | stdlib `ast` | Python 3.10+ |
| TypeScript / JavaScript / TSX / JSX | bundled Node script using `ts-morph` | prepared Node.js dependencies |
| Go | bundled Go extractor using `go/ast` | prepared helper binary |
| Rust | bundled Rust extractor using `syn` | prepared helper binary |
| Haskell | bundled GHC parser helper for syntax-only inventory | prepared helper binary |
| Docker / Compose | built-in parsers | none |
| Runtime/config YAML | targeted built-in parsers | none |
| MCP server | official Python MCP SDK | `agent-wiki-cli[mcp]`, Python 3.10+ |

TypeScript/JavaScript, Go, Rust, and Haskell helper setup is explicit; prepare
helper dependencies and binaries with `llm-wiki prepare-extractors`. Lint, CI,
and extract never run `npm install`, `go build`, `go run`, `cargo build`,
`cargo run`, or `ghc` automatically.

Source discovery honors `.gitignore` before extractors run. A root, unanchored
`lib/` rule is treated as a generic build-output pattern for TypeScript
projects, so `.ts`, `.tsx`, `.js`, and `.jsx` files under `src/lib/` remain
first-party source; top-level `lib/`, excluded dependency/build directories,
and explicit nested `.gitignore` rules still stay excluded. Generated agent
worktree copies such as `.claude/worktrees/**` are excluded from default
snapshots; pass an exact `--paths` entry if you intentionally want to inspect
one file there.

Haskell `.hs` and `.lhs` files are discovered as supported built-in source
files. Normal CLI extraction invokes the prepared Haskell helper to emit
syntax-only inventory for matching files. The helper does not typecheck the
target project or start Haskell Language Server. Haskell dependency
reconciliation is static: Cabal manifests are parsed without running Cabal,
Stack `extra-deps` and Nix package hints are advisory optional metadata, and
unknown imports are ignored rather than guessed. Haskell internal dependency
edges resolve through declared module names, so nested package roots can link
imports such as `HLSAnalysis.API` to the matching source entry.
Generated Haskell module pages display declared module names, import
qualification and aliases, top-level signatures and values, and type-oriented
declarations such as data, newtype, type alias, type class, and instance
entries.
GHC 9.6.x is the supported Haskell helper toolchain for this release. Newer GHC
9.x releases are best-effort, and helper preparation fails clearly when GHC
version output is malformed or older than 9.6.

## Agent Support

| Agent | Schema file | Sync mode |
|---|---|---|
| `claude` | `CLAUDE.md` | prompt hook; optional manual CLI trigger |
| `aider` | `.aider.conf.yml` | prompt hook; optional manual CLI trigger |
| `opencode` | `.opencode/instructions.md` | prompt hook; optional manual CLI trigger |
| `copilot` | `.github/copilot-instructions.md` | IDE prompt |
| `cursor` | `.cursorrules` | IDE prompt |
| `generic` | `AGENTS.md` | IDE prompt |

Installed hooks generate a reviewed prompt file for all agents. The explicit
`trigger-agent` command can still delegate to a CLI agent; for Claude, this uses
`claude -p` and leaves permission decisions to Claude's normal permission model.
Run manual CLI triggers only in repositories and execution environments you
trust.

The package also bundles agent skills — reusable `SKILL.md` workflow
directories (Claude Code-compatible) that encode the documentation and
analysis loops this tool is designed around. See [`skills`](#skills) in the
command reference.

### For autonomous agents

Agents that do not have a dedicated schema target can use the generic
instruction surface:

```bash
llm-wiki init --agent generic
llm-wiki skills export --dest exported-skills
```

`init --agent generic` writes `AGENTS.md` with the docs workflow order and
hard rules. `skills export --dest` writes the bundled skill directories into a
location any shell-capable autonomous agent can read, including
`usage-examples` for attaching validated screenshots or recordings.

## Installation

From PyPI:

```bash
pip install agent-wiki-cli
```

With MCP server support:

```bash
pip install "agent-wiki-cli[mcp]"
```

From source:

```bash
git clone https://github.com/Denissvgn/python-wiki-llm.git
cd python-wiki-llm
.venv/bin/pip install -e ".[dev]"
```

The following extras are accepted for compatibility with documented workflows,
but they do not install external TypeScript/JavaScript, Go, Rust, or Haskell
toolchains:

```bash
pip install "agent-wiki-cli[typescript,go,rust]"
```

Uninstall the Python package with:

```bash
pip uninstall agent-wiki-cli
```

## Quick Start

Initialize the wiki structure and the agent instruction file:

```bash
llm-wiki init --agent claude
```

Generate the initial wiki from an existing codebase:

```bash
llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki
```

Validate the wiki:

```bash
llm-wiki lint --wiki-dir docs/llm_wiki --src-dir .
```

Install a post-commit hook:

```bash
llm-wiki install-hook
```

`init` writes the selected agent and quality-hint setting to
`.git/.llm-wiki-agent` when the project is a Git repo. Outside Git, it falls
back to `<wiki-dir>/.llm-wiki-agent`.

## Automation

`llm-wiki install-hook` installs a `post-commit` hook that generates
`.git/llm-wiki-prompt.txt` with `llm-wiki generate-prompt` and prints a reminder
to paste that prompt into your agent chat. Generated hooks never launch CLI
agents automatically.

For advanced trusted workflows, `trigger-agent` remains available as an explicit
manual command:

```bash
llm-wiki trigger-agent --agent <agent>
```

The trigger command:

- takes `git diff HEAD~1..HEAD`;
- skips empty diffs and oversized diffs unless `--force` is used;
- uses a lock file to prevent concurrent syncs;
- opens a circuit breaker after repeated failures;
- builds deep source inventory and call-graph context;
- writes `.git/llm-wiki-prompt.txt` with owner-only permissions where supported;
- invokes the selected agent with a prompt that asks it to update, lint, and commit wiki changes.

Useful trigger options:

```bash
llm-wiki trigger-agent --agent claude --timeout 600 --max-diff-lines 2000
llm-wiki trigger-agent --agent claude --max-prompt-bytes 2000000
llm-wiki trigger-agent --agent claude --force
llm-wiki trigger-agent --reset-breaker
```

Optional strict pre-commit validation:

```bash
llm-wiki install-hook --enable-validation
```

Use `--force` when you intentionally want to replace an existing unrelated hook:

```bash
llm-wiki install-hook --force
```

## Command Reference

### `init`

Scaffold the wiki structure and agent constraint file.

```bash
llm-wiki init --agent claude
llm-wiki init --agent copilot --wiki-dir .wiki
llm-wiki init --agent cursor --no-quality-hints
```

Supported agents are `claude`, `aider`, `opencode`, `copilot`, `cursor`, and
`generic`.

### `bootstrap`

Generate a full wiki for an existing project.

```bash
llm-wiki bootstrap --src-dir . --wiki-dir docs/llm_wiki
llm-wiki bootstrap --overwrite
llm-wiki bootstrap --depth shallow
llm-wiki bootstrap --skip-workflows
llm-wiki bootstrap --skip-flows
llm-wiki bootstrap --skip-data-flow
llm-wiki bootstrap --skip-dependencies
llm-wiki bootstrap --include-tests go
llm-wiki bootstrap --helper-cache-dir .cache/llm-wiki-helpers
llm-wiki bootstrap --format json --source-adapter
```

`bootstrap` writes entity, module, workflow, flow, infrastructure, index, log,
dependency architecture, and manifest files. User-flow pages under `flows/` are
generated from detected entry points with a call sequence, generated static
`## Data flow` section, boundary-effects table, and editable `## Behavior`; use
`--skip-flows` to omit them or `--skip-data-flow` to keep flow pages without the
generated data-flow section. Large generated call-sequence diagrams are capped
to the first 30 interactions and include an omitted-interaction note so Mermaid
output stays readable on large repositories.
Dependency architecture pages are generated as `dependencies.md` and
`load-order.md`; use `--skip-dependencies` for projects that do not want those
pages or lint diagnostics. Generated `index.md` is a registry-backed landing
page with a surface overview table, per-surface counts, grouped user-flow
entries, optional dependency architecture links, and a direct log link.
`--depth full` is the default and includes
docstrings, imports, attributes, method signatures, generated relationship
sections, bounded per-module dependency mini-map summaries, and diagram data
where extractors provide it. Haskell module pages render declared module names,
qualified imports, aliases, signatures, values, and type declarations using the
same generated module/entity surfaces as other languages. Haskell declaration
entity relationship summaries show the declaration kind rather than methods and
attributes columns. Generated Mermaid diagrams and generated structure are
refreshed by the CLI; edit the semantic sections instead. Use
`--source-adapter` when callers need bootstrap to write only under `--wiki-dir`;
this skips agent constraint-file updates outside the generated wiki directory.
Use `--format json` to emit a machine-readable summary with created, updated,
and skipped files plus source counts and the manifest path.
Go `_test.go` files are excluded by default; pass `--include-tests go` when
behavior-spec or integration-test modules should be documented.
Use `--helper-cache-dir PATH` when prepared Go/Rust/Haskell helpers live in a
separate cache from the source repository.

### `sync`

Incrementally regenerate only pages whose source files changed since the last
manifest.

```bash
llm-wiki sync --src-dir . --wiki-dir docs/llm_wiki
llm-wiki sync --jobs auto --cache-stats --src-dir . --wiki-dir docs/llm_wiki
llm-wiki sync --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
llm-wiki sync --include-tests go --src-dir . --wiki-dir docs/llm_wiki
llm-wiki sync --src-dir /path/to/repo --wiki-dir docs/llm_wiki --allow-external-src
```

If an older wiki has `index.md` but no manifest, `sync` seeds
`.llm-wiki-manifest.json` without modifying pages. If neither a manifest nor an
existing wiki is present, run `bootstrap` first. Sync uses the same safe
persistent inventory cache as lint when a git directory is available. Use
`--no-cache`, `--rebuild-cache`, `--cache-dir PATH`, and `--cache-stats` to
control or inspect inventory cache behavior. Use `--helper-cache-dir PATH` to
point Go/Rust/Haskell extraction at prepared helpers in a separate cache. Use
`--jobs N` or `--jobs auto` to opt into parallel extraction for built-in
languages and plugin extractors whose manifests set `"parallel_safe": true`.
Sync repairs
manifests with invalid source hashes without touching pages, and stops unusually
broad diffs unless `--force` is used.
Pass `--include-tests go` to include Go `_test.go` files in the synced
inventory and generated module pages; the default remains production Go source
only.
For trusted source trees outside the runner workspace, pass
`--allow-external-src`; `--wiki-dir` remains constrained to the current project
root.

`sync` is deterministic: it updates AST/docstring-based page skeletons and does
not call an LLM. In agent workflows, treat sync as the first step, then inspect
created or updated pages and replace generic `_Auto-generated from ..._`,
copied-docstring-only, or knowable `—` placeholders with project-specific
semantic explanations.

For entity and module pages, `sync` also keeps generated `## Relationships` and
`## Local dependency map` sections current when another changed source file
alters relationship or dependency data, including Haskell imports resolved by
declared module name. Those generated sections are replaced without rewriting
human-authored semantic descriptions or table descriptions.
Older module pages that do not already have a local dependency map are left in
their existing shape.

When `dependencies.md` or `load-order.md` already exists, `sync` also
regenerates those architecture pages from the current dependency inventory and
keeps their human-authored `## Notes` sections unless `--no-preserve-semantic`
is set. Those notes are the agent's responsibility: document intentional cycles,
dynamic imports, side effects, and notable dependency rationale. Projects
bootstrapped with `--skip-dependencies`, or older wikis without those pages,
stay untouched.

When flow pages already exist, `sync` also refreshes generated call-sequence and
`## Data flow` content from the current inventory while preserving the
human-authored `## Behavior` section by default.

When `sync` rebuilds `index.md`, the generated landing-page overview and
per-surface link sections are replaced from the live registry and inventory.
With semantic preservation enabled, old custom top-level index sections are
kept at the end, and old free-form intro text is migrated under `## Notes`.
Use `--no-preserve-semantic` to regenerate a clean index without those custom
sections.

### `extract`

Print source inventory as JSON. All registered extractors run; missing optional
prepared helpers are skipped when there are no matching source files.

```bash
llm-wiki extract --src-dir .
llm-wiki extract --src-dir . --changed
llm-wiki extract --src-dir . --summary
llm-wiki extract --src-dir . --deep
llm-wiki extract --src-dir . --paths src/foo.py src/bar.ts
llm-wiki extract --src-dir . --package llm_wiki_cli
llm-wiki extract --src-dir . --include-empty
llm-wiki extract --src-dir . --include-tests go
llm-wiki extract --src-dir . --summary --output sources/code.json --read-only
llm-wiki extract --src-dir /path/to/repo --allow-external-src --summary
```

The JSON output includes `schema_version: "llm-wiki-extract/v1"` plus
`inventory` and optional `docker` and `unsupported_sources` objects.
Go `_test.go` files are omitted unless `--include-tests go` is supplied; Python
test files remain part of normal Python extraction.
JavaScript `.js` and `.jsx` files are handled by the TypeScript extractor
family and use `language: "javascript"` in inventory output. Prepare the same
helper with `llm-wiki prepare-extractors --language typescript`.
Plain `.js` files include named top-level function declarations in the
`functions` list even when they are local CommonJS helpers. Those functions are
rendered on module pages; JavaScript function declarations do not create entity
pages, which remain class/type/declaration oriented. Raw Node
`http.createServer` and `https.createServer` calls in JavaScript create HTTP
entry points for `extract --deep`, flow pages, and data-flow summaries. Named
handler arguments resolve to the handler symbol when available; inline
callbacks fall back to the assigned server variable such as `server`. Lint and
CI keep the non-blocking `javascript_flow_unsupported` diagnostic only for
`createServer` patterns outside the supported raw Node `http`/`https` shape.
`unsupported_sources` reports known source extensions that are visible in the
tree but not handled by an active extractor. Haskell is registered as a
built-in language, so `.hs` and `.lhs` files no longer appear in this advisory
block. When Haskell files are present, extraction requires a prepared helper and
reports a clear `prepare-extractors --language haskell` message if it is
missing. Haskell internal dependency edges resolve through declared module
names from inventory entries rather than filepath stems.
Haskell file entries are additive under `llm-wiki-extract/v1`. A Haskell entry
uses `language: "haskell"`, `imports`, `classes`, and `functions`, with `module`
present when the source declares one. Import records use `module`, `qualified`,
`alias`, and `line`. The `classes` bucket stores type-oriented declarations with
`kind` values such as `data`, `newtype`, `type`, `class`, and `instance`.
The `functions` bucket stores top-level signatures, functions, and values with
`kind` values such as `signature`, `function`, and `value`; signature entries
may include `signature`. Haskell-specific fields such as `language_pragmas`,
`exports`, and `deriving` are optional best-effort metadata and consumers must
tolerate their absence.
The Haskell helper emits syntax-only inventory without typechecking the target
project and does not start Haskell Language Server. Haskell dependency
reconciliation reads `*.cabal` `build-depends` statically, scopes nested Cabal
packages by nearest manifest directory, treats library/executable/common
dependencies as required, and treats test-suite, benchmark, setup, Stack
`extra-deps`, and Nix hints as optional.
With `--deep`, Python function entries may carry optional `data_effects` blocks
(inputs, selected global/attribute reads, writes, returns, and boundary effects
such as filesystem, environment, process, network, output, and logging calls)
and optional `calls` lists (in-body call targets, optionally with compact `args`
and `kwargs` expression summaries). The payload also gains an optional top-level
`entrypoints` array (detected user-reachable entry points: `{id, category, file,
symbol, label}`), a `data_flows` list for detected user flows, plus a top-level
`dependencies` object with internal `edges`, `cycles`, per-language external
dependency reconciliation, optional resolved-version metadata, and `load_order`.
Version metadata is best-effort and appears only when a supported lockfile or
exact pin is available: Go `go.sum`, Rust `Cargo.lock`, Python `poetry.lock`
and exact `requirements*.txt` pins, npm `package-lock.json`, and narrowly
supported `pnpm-lock.yaml` package entries. Haskell lockfile pinning is
intentionally out of scope for this metadata. When `--deep` is combined with
`--changed`, `--paths`, `--package`, or `--summary`, `data_flows` and
`dependencies` describe the emitted inventory before summary collapse. Inventory
keys are POSIX paths relative to `--src-dir`, never absolute paths. The v1
contract permits additive fields; incompatible shape changes require a new
schema version. The M3 data-flow fields are therefore optional additions under
`llm-wiki-extract/v1`, not a schema bump.
Installed `entrypoint_detector` plugin hooks also contribute to the same
`entrypoints` array in deep output. Detector failures are isolated: built-in
entry-point detection still runs, `extract` prints a warning to stderr, and the
JSON payload includes top-level `warnings` only when such diagnostics exist.

### `prepare-extractors`

Prepare TypeScript/JavaScript dependencies and cached Go/Rust/Haskell helper
binaries outside the lint/extract hot path.

```bash
llm-wiki prepare-extractors --src-dir .
llm-wiki prepare-extractors --language typescript --language go --language haskell
llm-wiki prepare-extractors --cache-dir .cache/llm-wiki-helpers
```

When `--language` is omitted, only helper languages detected in `--src-dir` are
prepared. Helper cache resolution follows `--cache-dir`, then
`LLM_WIKI_CACHE_DIR`, then `.git/llm-wiki-extractors/`. If Go is installed in a
nonstandard location or the `go` on `PATH` cannot run, set
`LLM_WIKI_GO=/path/to/go` before running `prepare-extractors`. If GHC is
installed in a nonstandard location, set `LLM_WIKI_GHC=/path/to/ghc` before
preparing Haskell helpers. GHC 9.6.x is the supported Haskell helper toolchain;
newer GHC 9.x releases are best-effort, and older or malformed GHC version
output fails during helper preparation.
Commands that consume prepared Go/Rust/Haskell helpers accept
`--helper-cache-dir PATH`.
This is separate from inventory-command `--cache-dir PATH`, which only controls
where `llm-wiki-inventory-cache.json` is read and written.

### `lint` and `ci-check`

Validate wiki links, orphan pages, entities, modules, workflows,
infrastructure, plugin lint rules, and team policy.

```bash
llm-wiki lint --wiki-dir docs/llm_wiki --src-dir .
llm-wiki lint --strict --wiki-dir docs/llm_wiki --src-dir .
llm-wiki lint --profile --wiki-dir docs/llm_wiki --src-dir .
llm-wiki lint --cache-stats --wiki-dir docs/llm_wiki --src-dir .
llm-wiki lint --cache-dir .cache/llm-wiki-inventory --helper-cache-dir .cache/llm-wiki-helpers
llm-wiki lint --include-tests go --wiki-dir docs/llm_wiki --src-dir .
llm-wiki lint --jobs auto --wiki-dir docs/llm_wiki --src-dir .
llm-wiki lint --wiki-dir docs/llm_wiki --src-dir /path/to/repo --allow-external-src
```

Strict mode also requires the core wiki structure and a fresh sync manifest.
`--profile` suppresses the human-readable lint text and prints one JSON object
to stdout containing the normal lint report, diagnostics, and phase timings.
The JSON contract is preserved for extractor failures as well; lint still exits
nonzero, but stdout remains machine-readable.
Lint uses a persistent deep-inventory cache by default when a git directory is
available, storing `.git/llm-wiki-inventory-cache.json`. Override the cache
directory with `LLM_WIKI_CACHE_DIR` or `--cache-dir PATH`; the CLI flag wins for
inventory caching. Use `--helper-cache-dir PATH` when prepared Go/Rust/Haskell
helpers live somewhere else. Use `--no-cache` to disable load/save,
`--rebuild-cache` to ignore and rewrite the cache, and `--cache-stats` to
include cache diagnostics.
Cache corruption or invalid fingerprints fall back to a full extraction without
reducing lint coverage. With `--profile --cache-stats`, the JSON payload includes a top-level
`cache` object. Use `--jobs N` or `--jobs auto` to opt into parallel extraction
for built-in languages and plugin extractors whose manifests set
`"parallel_safe": true`; the default is `--jobs 1`. Plugin extractors without
that opt-in remain sequential.
Use `--include-tests go` when a wiki intentionally documents Go `_test.go`
files; omit it to lint against the default production-source inventory.
For trusted source trees outside the runner workspace, pass
`--allow-external-src`; `--wiki-dir` remains constrained to the current project
root.

When dependency architecture pages exist, lint reruns dependency analysis and
surfaces import cycles, undeclared dependencies, and unused declared
dependencies as warning diagnostics. These warnings are visible in human output
and profile JSON but do not make `lint`, `lint --strict`, or `ci-check` fail by
themselves. Stale architecture pages with no current source modules remain hard
issues.
Python dependency reconciliation reads `pyproject.toml` and `requirements*.txt`
manifests, including nested manifests scoped to their directory. TypeScript and
JavaScript reconciliation reads the nearest scoped `package.json` and resolves
first-party imports through the nearest `tsconfig.json` `baseUrl`/`paths`
aliases before reporting undeclared external packages. Generic internal import
matching is scoped by the importer's language before external dependency
reconciliation, so same-stem files in other languages do not consume external
imports. Dependency manifests inside generated agent worktree copies,
gitignored directories, and other paths outside the default source snapshot
boundary are ignored during reconciliation. Go
`// indirect` requirements are treated as optional transitive dependencies, so
they do not produce unused-dependency warnings by themselves. Haskell
reconciliation reads Cabal `build-depends` statically, records Stack
`extra-deps` and Nix package hints as optional only, scopes nested Cabal
packages by nearest manifest directory, and reports only explicit known
module-prefix mappings such as `Data.Text` -> `text`.
When supported lockfiles are present, reconciliation also exposes optional
resolved-version metadata under each language's `versions` mapping. Missing or
unparseable lockfiles fail open by omitting version records; they do not affect
lint pass/fail behavior or undeclared/unused package diagnostics.
When generated entity/module diagram sections exist, lint validates Mermaid
`click` links as hard broken-link issues and reports over-large generated
diagrams as warning diagnostics with page and section targets.
When guide or other semantic pages embed local media, lint treats image and
video targets separately from Markdown page links. It recognizes inline
Markdown images and media links, same-page reference-style images, and raw
`<img>`, `<video>`, and `<source>` tags, including local `srcset` candidates.
Fenced code blocks are ignored by the media pass so examples do not create
media diagnostics; the general page-link check is unchanged. Missing local
media files are hard `media_link_broken` issues. Missing image alt text, media
files over the default 2 MB warning threshold, unreferenced media files under
`assets/`, media stored outside the preferred `assets/` convention,
unrecognized non-hidden files under `assets/`, and symlinked media that
resolves outside the wiki root are warning diagnostics
(`media_missing_alt_text`, `media_oversize`, `media_orphan`,
`media_outside_assets`, `asset_unrecognized_type`, and
`media_symlink_escape`). Use `--media-size-warn-bytes` to tune the size warning
for a project.
When flow pages exist, lint also reports generated data-flow gaps, such as
unresolved calls that static analysis cannot classify, as warning diagnostics.
Known but unsupported source files are reported as informational diagnostics
and do not make `lint`, `lint --strict`, or `ci-check` fail. Haskell `.hs` and
`.lhs` files are now registered as built-in source files. The prepared helper
parses syntax-only inventory during normal extraction; if the helper is missing,
commands report the Haskell preparation command instead of treating those files
as unsupported sources.

For CI:

```bash
llm-wiki ci-check --src-dir . --wiki-dir docs/llm_wiki
llm-wiki ci-check --jobs auto --src-dir . --wiki-dir docs/llm_wiki
llm-wiki ci-check --helper-cache-dir .cache/llm-wiki-helpers --src-dir . --wiki-dir docs/llm_wiki
llm-wiki ci-check --include-tests go --src-dir . --wiki-dir docs/llm_wiki
llm-wiki ci-check --src-dir /path/to/repo --wiki-dir docs/llm_wiki --allow-external-src
llm-wiki ci-check --format json --report .git/llm-wiki-ci-report.md
llm-wiki ci-check --format markdown
```

`ci-check` always runs strict validation, writes a Markdown report, records a
local metrics event, uses the same safe inventory cache when available, and
exits nonzero on validation failure. JSON output includes non-blocking
diagnostics so CI logs can show unsupported-source coverage without failing.
For trusted source trees outside the runner workspace, pass
`--allow-external-src`; `--wiki-dir` remains constrained to the current project
root.
`--report` is an output path, so explicit
absolute paths and relative artifact paths outside the project root are allowed.

### `context`

Build a token-budgeted source snapshot for agents.

```bash
llm-wiki context --budget 8000 --src-dir . --format json
llm-wiki context --budget 8000 --src-dir . --format markdown
llm-wiki context --budget 8000 --focus changed
llm-wiki context --budget 8000 --focus all
llm-wiki context --budget 12000 --format json --focus all --output context.json --read-only
```

`--focus changed` is the default. Changed files get full detail, one-hop import
neighbors get slim detail, and remaining files get names only.

External tools can use the `llm-wiki-context/v1` JSON request protocol:

```bash
llm-wiki context --request request.json --src-dir .
cat request.json | llm-wiki context --request - --src-dir .
llm-wiki context --request request.json --src-dir . --wiki-dir docs/llm_wiki
```

Example request:

```json
{
  "protocol": "llm-wiki-context/v1",
  "budget_tokens": 8000,
  "focus": ["changed", "neighbors"],
  "format": "json",
  "filters": {
    "language": "python",
    "symbol": "build_context",
    "entrypoint": "llm-wiki-context",
    "surface": "flows"
  }
}
```

`filters.language` and `filters.module` scope the budgeted `files` payload.
`filters.symbol`, `filters.entrypoint`, and `filters.surface` add bounded
`graphs` and `surface` sections without changing the file-priority budget.
`--wiki-dir` selects the wiki surface metadata used for graph page references.

`--output PATH` writes the generated JSON or Markdown directly instead of
printing it to stdout. `--read-only` documents source-adapter intent: the command
does not write wiki files, hooks, manifests, local config, or helper/cache state,
except for an explicit `--output` artifact.

### Codebase source integration

For research or indexing systems that need codebase evidence without adopting
the maintained wiki format, prefer the read-only source-adapter commands:

```bash
llm-wiki extract --src-dir <repo> --summary --read-only
llm-wiki context --src-dir <repo> --budget 12000 --format json --focus all --read-only
llm-wiki bootstrap --src-dir <repo> --wiki-dir sources/code_wikis/<source_id> --format json --source-adapter
llm-wiki sync --src-dir <repo> --wiki-dir sources/code_wikis/<source_id> --allow-external-src
llm-wiki lint --src-dir <repo> --wiki-dir sources/code_wikis/<source_id> --allow-external-src
llm-wiki ci-check --src-dir <repo> --wiki-dir sources/code_wikis/<source_id> --allow-external-src --report ci-report.md
```

By default, `--src-dir` must resolve inside the current working directory. For a
trusted source tree outside cwd, pass `--allow-external-src`; explicit
`--paths` are still constrained to the chosen source root and can opt into an
otherwise excluded generated worktree file. `sync`, `lint`, and `ci-check` use
the same opt-in to continue a source-adapter wiki generated by `bootstrap`,
while `--wiki-dir` remains constrained to the runner project.
Explicit output paths such as `--output` and `--report` may be absolute or
outside the project root because they are caller-selected artifacts.

Example `extract --summary` payload:

```json
{
  "schema_version": "llm-wiki-extract/v1",
  "inventory": {
    "models.py": {
      "language": "python",
      "package": "sample",
      "classes": ["User"],
      "functions": ["load_user"]
    }
  }
}
```

Example `context --format json` payload:

```json
{
  "budget": 12000,
  "used": 320,
  "truncated": false,
  "omitted_files": [],
  "downgraded_files": {},
  "files": {
    "models.py": {
      "priority": "high",
      "detail": "deep",
      "classes": [{"name": "User"}],
      "functions": []
    }
  }
}
```

Example `bootstrap --format json --source-adapter` summary:

```json
{
  "schema_version": "llm-wiki-bootstrap-summary/v1",
  "src_dir": "/path/to/repo",
  "generated_wiki_path": "sources/code_wikis/repo",
  "depth": "full",
  "source_files": 12,
  "classes": 8,
  "functions": 31,
  "docker_files": 1,
  "infrastructure_files": 3,
  "github_actions_files": 0,
  "kubernetes_files": 0,
  "runtime_config_files": 2,
  "runtime_config_by_type": {
    "prometheus": 1,
    "prometheus_rules": 1
  },
  "workflows": 2,
  "cross_references": 14,
  "created_files": ["sources/code_wikis/repo/index.md"],
  "updated_files": [],
  "skipped_files": [],
  "manifest_path": "sources/code_wikis/repo/.llm-wiki-manifest.json"
}
```

### `generate-prompt`

Build a sync prompt for IDE agents or for manual review.

```bash
llm-wiki generate-prompt
llm-wiki generate-prompt --print
llm-wiki generate-prompt --change-type feature
llm-wiki generate-prompt --template compact
```

The generated prompt includes change-type guidance. Installed prompt templates
can override the default prompt body. The default prompt asks agents to run
`sync` first, then perform a semantic pass on affected pages before accepting a
lint-clean wiki as complete.

### `mcp`

Run a local MCP server exposing read-only wiki tools and resources.

```bash
llm-wiki mcp --wiki-dir docs/llm_wiki --src-dir .
llm-wiki mcp --transport http --host 127.0.0.1 --port 8765
```

The MCP server exposes registry-backed wiki resources and search across index,
log, entities, modules, workflows, guides, flows, infrastructure, dependencies,
and load order. It also exposes direct page tools including `get_flow(flow_id)` and
`get_architecture_page(page)`, where `page` is `dependencies` or `load-order`.
Use `query_graph({"type": "callers", "value": "run", "limit": 20})` for
bounded graph queries; supported types are `flow_for_entrypoint`,
`data_flow_for_entrypoint`, `callers`, `callees`, `dependency_neighborhood`,
and `pages_for_symbol`. Context payloads, lint summaries, and status
information report the same canonical surfaces. HTTP mode is intended for local
use and defaults to loopback.

### `install` and `plugins`

Install and manage local plugins.

```bash
llm-wiki install ./vendor/my-plugin --yes
llm-wiki install my-catalog-plugin --dry-run
llm-wiki plugins list
llm-wiki plugins validate ./vendor/my-plugin
llm-wiki plugins remove my-plugin
```

Plugin manifests can register extractors, entry-point detectors, diagram styles,
prompt templates, lint rules, and agent skill blocks. Plugin references are
resolved from project-local paths or `.llm-wiki/catalog.json`. Extractor,
lint-rule, entry-point detector, and diagram-style entry points must resolve to
Python files inside the plugin directory; installed entry points are checked
again before runtime import. Extractor components may set `"parallel_safe": true`
to opt into `--jobs` parallel execution; omit it unless the extractor is safe to
run concurrently in a fresh instance.

A tested M4 sample plugin lives at `examples/plugins/m4-documentation-hooks` in
source checkouts. It can be inspected or installed like any other local plugin:

```bash
llm-wiki plugins validate examples/plugins/m4-documentation-hooks
llm-wiki install examples/plugins/m4-documentation-hooks --yes
```

Installed packages can export the same bundled sample before installing it:

```bash
llm-wiki plugins samples list
llm-wiki plugins samples export m4-documentation-hooks --dest vendor/m4-documentation-hooks
llm-wiki plugins validate vendor/m4-documentation-hooks
llm-wiki install vendor/m4-documentation-hooks --yes
```

The sample manifest declares `m4-documentation-hooks/worker-tasks`
(`detectors:detect_worker_tasks`) and
`m4-documentation-hooks/brand-flowcharts` (`styles:style_flowcharts`). The
detector only reads the plain inventory it receives and returns task handler
records; the style hook only returns normalized direction, class, and color
hints for generated flowcharts.

An `entrypoint_detector` hook is called with the plain extracted inventory and
returns entry-point records shaped as `{category, file, symbol, label}`. `file`
may be `null` or a relative POSIX inventory path, `label` is optional, and any
plugin-supplied `id` is ignored so core deduplication and stable id assignment
remain authoritative. Detector exceptions or invalid records become warnings in
`extract --deep`, `bootstrap`, and `sync`; built-in detectors still run.

A `diagram_style` hook is called with a plain context object such as
`{"surface": "relationships"}` or `{"surface": "data_flow"}` and may return
only bounded style hints: `direction` (`TB`, `TD`, `BT`, `RL`, or `LR`),
`node_classes` mapping exact generated node labels to safe Mermaid class names,
and `category_colors` mapping safe class names to `#RGB` or `#RRGGBB` colors.
LLM Wiki ignores invalid values and unknown keys, so plugins cannot inject
Markdown, labels, hrefs, or raw Mermaid lines. Labels and `click` hrefs remain
sanitized by the core diagram renderers.

These hooks are deterministic local extension contracts over explicit inputs;
they do not perform network discovery and they do not mutate Markdown directly.
They are not a sandbox, though: installing a plugin runs trusted project-local
Python code, so use plugins only from paths you control.

### `team`

Manage shared team policy for prompt defaults, required plugin components, and
generated-wiki conflict handling.

```bash
llm-wiki team init --wiki-dir docs/llm_wiki
llm-wiki team check --src-dir . --wiki-dir docs/llm_wiki
llm-wiki team resolve-conflicts --wiki-dir docs/llm_wiki
llm-wiki team resolve-conflicts --write --wiki-dir docs/llm_wiki
```

`resolve-conflicts` only applies conservative resolutions for generated pages.
Manual workflow conflicts are left for humans to resolve.

### `obsidian`

Export and validate an Obsidian-friendly mirror of the canonical wiki.

```bash
llm-wiki obsidian export --wiki-dir docs/llm_wiki --vault-dir ~/Vaults/project
llm-wiki obsidian check --wiki-dir docs/llm_wiki --vault-dir ~/Vaults/project
llm-wiki obsidian install-plugin --vault-dir ~/Vaults/project
```

The mirror adds frontmatter, wikilinks, related links, and sidecar human notes.
Page discovery follows the canonical surface registry, so guides, flows, and
optional architecture pages are mirrored when present. The canonical source of
truth remains `docs/llm_wiki/`; generated mirror output is not edited as an
independent documentation source.

### `site`

Export and validate a static-site-friendly mirror of the canonical wiki.

```bash
llm-wiki site export --wiki-dir docs/llm_wiki --out-dir site --format mkdocs --profile reference
llm-wiki site export --wiki-dir docs/llm_wiki --out-dir site --format mkdocs --profile user --site-name "Project Docs"
llm-wiki site export --wiki-dir docs/llm_wiki --out-dir site --format mkdocs --profile user --site-name "Project Docs" --file-friendly
llm-wiki site export --wiki-dir docs/llm_wiki --out-dir site --format mkdocs --dry-run --output-format json
llm-wiki site export --wiki-root sources/code_wikis --out-dir site --format docusaurus
llm-wiki site export --wiki sources/code_wikis/api --wiki sources/code_wikis/web --out-dir site
llm-wiki site check --wiki-dir docs/llm_wiki --out-dir site
llm-wiki site check --wiki-dir docs/llm_wiki --out-dir site --profile user --site-name "Project Docs"
llm-wiki site check --wiki-dir docs/llm_wiki --out-dir site --built-site-dir _site --link-mode http
llm-wiki site check --wiki-dir docs/llm_wiki --out-dir site --built-site-dir _site --link-mode file --profile user --site-name "Project Docs"
llm-wiki site check --wiki-root sources/code_wikis --out-dir site
llm-wiki site check --out-dir site --output-format json
```

`--format` supports `plain`, `mkdocs`, and `docusaurus`; `--output-format`
controls text versus JSON reports. `--wiki-dir` exports or checks one canonical
wiki. `--wiki-root` discovers source wikis from immediate child directories,
and repeated `--wiki` flags select explicit source wiki directories; both hub
modes write each wiki under `<out-dir>/<source_id>/` and generate a top-level
hub `index.md`. MkDocs hub exports group navigation by source ID. Docusaurus
hub exports namespace document IDs by source ID to avoid collisions.
MkDocs exports include safe `llm_wiki` front matter and a generated
`mkdocs.yml` with registry-ordered navigation. `--profile reference` is the
default agent/reference mirror. `--profile user --site-name ...` writes a
concise human landing page, expects guide pages, and moves the exhaustive
generated inventory to `generated-reference.md`; its check adds quality gates
for default site names, missing guides, bloated landing pages, and placeholder
text in primary human docs. Docusaurus exports include Docusaurus front matter
and generated `sidebars.json` metadata. When multiple exported pages share the
same Markdown heading, generated MkDocs and Docusaurus labels include page-id
context such as `agent / ArtifactStore` so static-site navigation remains
unambiguous. Plain exports can add `llm_wiki` front matter with
`--front-matter`.

MkDocs defaults target HTTP hosting. `--file-friendly` is an opt-in MkDocs mode
for direct disk handoffs: it writes `use_directory_urls: false`, a small
MkDocs theme override for file-safe home links, and reports
`distribution_mode: "file"`. After building a site, `site check
--built-site-dir _site --link-mode http|file` validates generated HTML links.
`http` mode accepts MkDocs directory URLs that resolve to `index.html`; `file`
mode requires concrete `.html` targets and reports directory-style links as
hard issues.

Agent-owned usage media should live under the semantic `assets/` surface,
using the mirrored path convention
`assets/<surface>/<page-stem>/<name>.<ext>`. Markdown image embeds and media
links, same-page reference-style images, and raw `<img>`, `<video>`, and
`<source>` tags are recognized for `.png`, `.jpg`, `.jpeg`, `.webp`, `.gif`,
`.svg`, `.mp4`, and `.webm` files; local `srcset` candidates are validated and
mirrored too. `site export` copies every referenced media file that resolves
inside the wiki root, including media kept beside a page outside `assets/`,
and reports asset operations separately from page operations. Symlinked media
that resolves outside the wiki root is warning-visible and is not mirrored.
`site check --built-site-dir` validates built HTML media targets and local
`srcset` candidates in both `http` and `file` link modes.

The service layer also exposes the same pure mirror builder for integrations:

```python
from llm_wiki_cli.services.site_export import export_site_hub, export_site_mirror

report = export_site_mirror(
    wiki_dir="docs/llm_wiki",
    out_dir="site",
    format="mkdocs",
)

hub = export_site_hub(
    wiki_root="sources/code_wikis",
    out_dir="site",
    format="docusaurus",
)
```

The builder copies registry-backed wiki pages in canonical order, preserves
Mermaid fences, rewrites resolvable internal Markdown links to remain local to
the mirror, writes MkDocs config comments that point users at a Mermaid plugin
when diagram rendering is desired, and refuses source/output overlap unless
explicitly allowed. Docusaurus exports also escape MDX-sensitive text outside
code fences and inline code spans while preserving fenced Mermaid diagrams.
`site check` validates the generated mirror without external builders: missing
pages, broken or unsafe local Markdown links, malformed generated front matter,
metadata mismatches, duplicate Docusaurus document ids, and output paths outside
the mirror are hard `issues`; mixed mirrors that omit front matter on some pages
emit non-failing `warnings` in JSON and text reports.

### `skills`

List, export, and install the agent skills bundled with the package. Each
skill is a directory holding a `SKILL.md` workflow definition (Claude
Code-compatible frontmatter plus instructions) and optional supporting files.
Thirteen skills are bundled:

- `attack-surface`: defensive security-review preparation — prepare
  extractor helpers, run `extract --deep --read-only`, seed required
  coverage from `SECURITY.md`, treat data-flow gaps as unknown surface,
  supplement with a source-level sink scan, and write a prioritized
  `AS-NNN` exposure report that hands suspicious paths to deeper review
  (reconnaissance, not a SAST replacement).
- `dep-audit`: dependency diagnostics triage — consume existing lint,
  ci-check, review JSON, and wiki dependency outputs; classify
  dependency-cycle, undeclared-dependency, and unused-dependency findings;
  verify source evidence before source, manifest, or wiki edits; and report
  deferred items explicitly.
- `dep-vuln-triage`: vulnerable-dependency exposure triage — build a
  per-language dependency inventory with lockfile-resolved versions from the
  deep extract, look up advisories per package, rank hits by import-site
  reachability, and write a severity × reachability `DVT-NNN` report with
  proposed bumps or mitigations; packages without resolved versions are
  reported as unknowns, never safe paths.
- `doc-hub`: multi-repo documentation hub aggregation — keep each source
  wiki current, export/check a multi-wiki static-site hub with
  `site export --wiki-root`/`site check`, and write one LLM-owned hub
  overview page only when the source repositories are genuinely related
  (never fabricate a cross-repo relationship that isn't real).
- `doc-review`: documentation review follow-through — start from review JSON,
  branch diffs, patch findings, lint, or sync diagnostics; validate each
  finding against source truth; update semantic wiki/source-doc surfaces; run
  lint/ci-check; and preserve unresolved findings with rationale.
- `impact-analysis`: change blast-radius tracing — run bounded
  `callers`/`callees`/`dependency_neighborhood`/`flow_for_entrypoint` graph
  queries via `context --request` or MCP, map hits to the wiki pages that
  describe them, and emit a docs-to-update checklist in the same
  classification vocabulary `doc-review` uses so its output feeds directly
  into that skill.
- `infra-review`: deployment-surface review — enumerate generated
  Dockerfile/Compose/Kubernetes/GitHub-Actions `infrastructure/` pages,
  apply a checklist for privileged containers, host mounts, exposed ports,
  plaintext secrets, and over-broad Actions permissions, reading raw source
  for the fields (K8s security context, Actions permissions) the generated
  pages don't capture.
- `onboarding-guide`: persona-scoped "start here" narratives — verify the
  wiki is current, rank the flows a newcomer actually hits, write one
  guided-tour page per persona into the agent-owned `guides/` surface with
  links into existing wiki pages, record deferred personas as an explicit
  remainder, and validate with `lint --strict` and a sync re-link pass.
- `publish-docs`: wire static-site export into an actually publishable
  site — export (single-wiki or hub), validate with `site check`, run the
  real mkdocs/docusaurus builder when installed, and hand off (never
  perform) the deploy step.
- `usage-examples`: capture evidence-linked examples for user docs — run
  documented flows in a disposable environment, attach screenshots or
  recordings under `assets/<surface>/<page-stem>/`, validate media links and
  built-site media targets, and defer honestly when capture tooling or runtime
  access is unavailable.
- `user-docs-author`: full user documentation authoring pass — run
  deterministic `sync`/`lint`/`site export --profile user`/`site check`
  evidence first, write only evidence-linked semantic wiki prose such as
  `guides/*.md`, and loop on validation-backed user-site issues without
  editing generated blocks or static-site output directly.
- `wiki-bootstrap`: the first-adoption workflow for an existing codebase —
  prepare extractor helpers, run deterministic `bootstrap --format json`, do
  a centrality-ranked semantic pass on the most central pages, write an
  explicit remainder backlog for deferred pages, validate with
  `lint --strict`/`ci-check`, and commit the wiki.
- `wiki-sync`: the post-change documentation loop — deterministic `sync`, a
  semantic-only prose pass, a `lint --strict` validation loop, and a
  separate `docs(wiki):` commit.

```bash
llm-wiki skills list
llm-wiki skills install                          # into ./.claude/skills/
llm-wiki skills install --skill wiki-sync --force
llm-wiki skills export --dest ~/.claude/skills   # personal skills directory
llm-wiki skills export --dest exported --format json
```

`install` writes into the current project (default `.claude/skills/`, must
stay inside the project root); `export` accepts any destination directory.
Both are idempotent: identical existing files are kept, and files that were
edited locally are never overwritten without `--force` — the run reports
`existing_file_differs` and exits non-zero instead, so local skill
customizations survive package upgrades by default.

### `metrics`

Show local quality and automation metrics.

```bash
llm-wiki metrics --last 30d
llm-wiki metrics --format json
```

Metrics are stored locally under `.git/llm-wiki-metrics.jsonl` when available.

### `review`

Run a static wiki-aware review of proposed code changes.

```bash
llm-wiki review --base main --head HEAD
llm-wiki review --patch change.patch --format json
```

The review command compares code changes with full-surface wiki coverage and
reports stale or missing documentation risks. Module/entity pages, source-linked
user-flow pages, workflow pages, infrastructure notes, and dependency/load-order
architecture pages all count as relevant review coverage when they describe the
changed code or dependency relationship.

### `upgrade`

Refresh framework-managed artifacts in place.

```bash
llm-wiki upgrade
llm-wiki upgrade --agent copilot
llm-wiki upgrade --wiki-dir .wiki
llm-wiki upgrade --force
llm-wiki upgrade --no-quality-hints
```

`upgrade` refreshes agent instruction blocks, wiki directories, hooks, plugin
skill blocks, and persisted local config. For older wiki layouts, it
idempotently adds registry-standard directories such as `flows/` and missing
`.gitkeep` files without rewriting existing index, log, semantic pages, or
optional `dependencies.md` / `load-order.md` pages. Run `bootstrap` or `sync`
to generate user-flow and dependency architecture pages; after upgrading,
`site export` and MCP automatically see any `flows/*.md` pages that exist.

### `migrate`

Reconcile older wiki layouts with current canonical names.

```bash
llm-wiki migrate --dry-run
llm-wiki migrate --chunk-size 50 --plan-chunks
llm-wiki migrate --chunk-size 50 --chunk 1
```

### `status`, `release`, `bump`, and `uninstall`

```bash
llm-wiki status
llm-wiki release --stage
llm-wiki bump --patch --stage
llm-wiki uninstall --dry-run
llm-wiki uninstall --remove-wiki
```

`uninstall` removes project integration artifacts. It does not uninstall the
CLI itself. To remove the Python package, run `pip uninstall agent-wiki-cli`.

## Security Model

LLM Wiki is a local automation tool. It can generate prompt files containing
diffs, source structure, and architectural context. Prompt files are written
inside `.git/` by default and use owner-only permissions where the platform
supports that mode.

Manual CLI triggers can edit files and run commands according to the selected
agent's own permission model. Review generated prompt files and wiki diffs
before trusting agent-produced changes in a shared repository.

The repository includes community health files:

- `CODE_OF_CONDUCT.md`
- `SECURITY.md`
- GitHub issue templates

## Development

Run tests from the repository root:

```bash
.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest tests/ -v
```

Run the MCP tests with the optional dependency installed:

```bash
.venv/bin/pip install -e ".[dev,mcp]"
.venv/bin/pytest tests/test_mcp.py
```

Before release, check metadata and docs:

```bash
.venv/bin/pytest tests/test_package_metadata.py tests/test_release.py -q
.venv/bin/python -m build
git diff --check
```

Release notes and package metadata record the surface, distribution,
compatibility, and local verification gates for documentation-surface work. Use
`llm-wiki release` separately when stamping a real version.

The M4 dogfood smoke exercises this repository's own documentation surface by
copying the checkout to a temp project, bootstrapping a full wiki, running
`sync`, exporting a MkDocs mirror, and checking the mirror:

```bash
.venv/bin/pytest tests/test_bootstrap.py::TestGenerateFlowMd tests/test_m4_dogfood.py -q
.venv/bin/pytest -q
```

## Contribution Policy

This project does not maintain a formal contribution process. You are welcome to
freely fork it, adapt it to your workflow, and publish your own changes under
the license terms.
