# Chapter 3: CLI Command Reference
[English](../../en/01-user-guide/03-cli-command-reference.md) | [中文](../../zh/01-user-guide/03-cli-command-reference.md)
This chapter is an executable command index. Workflow details live in later chapters; use this page to find entry points and diagnostics quickly.
When `--format json` or `--format streaming-json` is requested, parse diagnostics and runtime API failures written to stderr are JSON. Runtime API failures use the stable API error shape with `error_kind`, `message`, and optional `metadata`; text and markdown formats keep human-readable stderr messages.
To access a deployed resident service from a local CLI, use global `--remote <base-url>` or `RELAY_KNOWLEDGE_REMOTE_BASE_URL`. Remote mode covers `repo list`, `repo index`, `repo update`, `repo scope preview`, `repo status`, `repo query`, `repo graph`, `repo context`, `repo framework`, `repo feature-flags`, `repo impact`, `repo report`, `repo software`, and `repo view` for repositories already registered on the service host. `repo index --reset` and `repo index-worker` are rejected while remote mode is selected and must be run on the service host; unrelated local commands such as `status` and `health` keep using local runtime state when only the environment variable is set.
## 3.1 Common Status Commands
Project status:
```bash
relay-knowledge status --format json
```
Health check:
```bash
relay-knowledge health --format json
```
Service diagnostics:
```bash
relay-knowledge service status --format json
relay-knowledge service doctor --format json
```
`service status` and `service doctor` currently share the same unified API output, covering service mode, background update state, service definition path, agent protocol status, and refresh queue diagnostics.
Version checks:
```bash
relay-knowledge version
relay-knowledge version check --format json
```
`version` prints only the current binary version. It does not load runtime
configuration or use the network. `version check` queries GitHub Releases and
crates.io through `net::http` according to runtime configuration and caches the
result under the runtime cache directory. Ordinary interactive text/markdown CLI
commands only print a short stderr notice when a newer stable version is found;
the primary command stdout is emitted first, and they never replace the binary
automatically.
## 3.2 Provider Diagnostics
```bash
relay-knowledge provider probe --format json
```
`provider probe` reads remote embedding provider configuration through the environment boundary and performs a lightweight probe. The JSON response includes `ok`, `provider`, `model`, `dimension`, optional `latency_ms`, and on failure `error_code`, `error_message`, and `retryable`. HTTP 429, HTTP 402, and quota/backpressure-shaped HTTP 400 or HTTP 403 responses mean the endpoint, auth boundary, and model route were reachable, so they report `ok=true` while keeping `error_code=rate_limited` and `retryable=true` as observable degraded diagnostics. Plain authentication, endpoint, model, timeout, and malformed-response failures still report `ok=false`. It does not print raw API keys or bypass the `env` module.
The OpenAI-compatible embedding base URL may be a host root, a versioned API root such as `/v1` or `/v4`, or a full `/embeddings` endpoint. Non-version path prefixes keep resolving as `<prefix>/v1/embeddings`, and query or fragment suffixes are ignored during endpoint construction.
All remote embedding and provider HTTP uses the shared QoS runtime. Admission rejection occurs before network I/O, and timeout/cancellation diagnostics remain visible; the deprecated library constructor without QoS refuses remote providers.
Endpoint host, batch, timeout, concurrency, and cursor metadata belong to runtime diagnostics in `status`, `health`, or the Web Providers panel.
## 3.3 Setup Doctor and Profiles
`setup doctor` is a storage-free read-only diagnostic:
```bash
relay-knowledge setup doctor --format json
```
It reads only parsed runtime configuration. It does not open or migrate SQLite and does not refresh indexes. `configuration_ready=true` only means configuration checks passed; `live_health_checked=false` means graph storage, index freshness, and worker/service live health still need `health` or `service doctor`.
`setup profile` writes no files and installs no service. It prints recommended environment variables, commands, and notes:
```bash
relay-knowledge setup profile local --format json
relay-knowledge setup profile agent-readonly --format json
relay-knowledge setup profile service --format json
relay-knowledge setup profile external-embedding --format json
```
The profiles cover zero-config local use, read-only MCP agent access, platform service-manager preview, and external embedding provider metadata. Persisting those suggestions into a shell, service manager, or deployment tool is always explicit caller work.
## 3.4 Command Overview
```bash
relay-knowledge status
relay-knowledge help [command...] [--format text|json]
relay-knowledge ingest --source <scope> --content <text> [--entity <label>]
relay-knowledge query <text> [--source <scope>] [--limit <n>] [--freshness allow-stale|wait-until-fresh|graph-only]
relay-knowledge files index [--root <path>] [--source <scope>]
relay-knowledge files query <text> [--source <scope>] [--root <root-id>] [--freshness allow-stale|wait-until-fresh|graph-only] [--limit <n>]
relay-knowledge files content <text> [--source <scope>] [--root <root-id>] [--freshness allow-stale|wait-until-fresh|graph-only] [--limit <n>]
relay-knowledge map init [--type knowledge|codespec|all]
relay-knowledge map show [--type knowledge|codespec|all] [--topic <id>] [--directory <path>]
relay-knowledge map history [--type knowledge|codespec|all] [--from <version>] [--limit <count>]
relay-knowledge map route <topic> --type knowledge
relay-knowledge map source add --type knowledge --id <id> --topic <id> --kind repo|file|doc|config|db|ci|runtime|wiki|monitoring --uri <uri> [--scope <source_scope>] [--description <text>]
relay-knowledge map source update --type knowledge --id <id> [--topic <id>] [--kind repo|file|doc|config|db|ci|runtime|wiki|monitoring] [--uri <uri>] [--scope <source_scope>] [--description <text>]
relay-knowledge map source remove --type knowledge --id <id>
relay-knowledge map directory add --type <knowledge|codespec> --directory <path> --purpose <text> --content-scope <glob> --load-hint <hint> --update-rule <rule> [--key-file <path>] [--relation <kind=target>]
relay-knowledge map directory update --type <knowledge|codespec> --directory <path> [directory fields]
relay-knowledge map directory remove --type <knowledge|codespec> --directory <path>
relay-knowledge map migrate --type knowledge <--to-v3|--rollback>
relay-knowledge map validate [--type knowledge|codespec|all]
relay-knowledge map agent-snippet
relay-knowledge repo list
relay-knowledge repo register <path> [--alias <name>] [--path <filter>]
relay-knowledge repo remove <alias>
relay-knowledge repo index <alias> [--ref <ref>] [--dry-run|--reset]
relay-knowledge repo index-worker [--task-id <id>]
relay-knowledge repo scope preview <alias> [--ref <ref>]
relay-knowledge repo update <alias> [--base <ref>] [--head <ref>]
relay-knowledge repo query <alias> --query <text> [--kind hybrid|symbol|definition|references|callers|callees|imports|sbom] [--ref <ref>] [--path <filter>] [--language <id>] [--freshness allow-stale|wait-until-fresh|graph-only] [--limit <n>]
relay-knowledge repo graph <alias> --focus <path> --path <root> [--ref <ref>] [--depth 1|2] [--node-limit <n>] [--edge-limit <n>]
relay-knowledge repo context <alias> --query <text> [--ref <ref>] [--path <filter>] [--language <id>] [--freshness allow-stale|wait-until-fresh|graph-only] [--limit <n>] [--max-context-bytes <n>] [--no-code] [--exclude-generated]
relay-knowledge repo framework <alias> [--query <text>] [--framework angular|vue] [--kind component|directive|pipe|template|input|output|prop|emit|model|slot|template-variable|control-flow] [--ref <ref>] [--path <filter>] [--freshness allow-stale|wait-until-fresh|graph-only] [--limit <n>]
relay-knowledge repo feature-flags <alias> [--query <text>] [--ref <ref>] [--path <filter>] [--language <id>] [--limit <n>]
relay-knowledge repo impact <alias> --base <ref> --head <ref>
relay-knowledge repo report <alias> [--format markdown|json]
relay-knowledge repo software <alias> [--ref <ref>] [--kind dependencies|sdks|files|topics|relationships|build|iac|design|all] [--freshness allow-stale|wait-until-fresh|graph-only] [--limit <n>]
relay-knowledge repo business <alias> [--ref <ref>] [--domain <id>] [--query <text>] [--kind terms|mappings|all] [--freshness allow-stale|wait-until-fresh|graph-only] [--limit <n>]
relay-knowledge repo view <alias> [--kind architecture-layers|business-domains|dependency-tour|process-flow|affected-scope] [--ref <ref>] [--path <filter>] [--language <id>] [--freshness allow-stale|wait-until-fresh|graph-only] [--limit <n>] [--changed-path <path>]
relay-knowledge repo status <alias>
relay-knowledge graph inspect
relay-knowledge index refresh [--kind bm25|semantic|vector]
relay-knowledge worker status|run-once [--kind embedding|ocr|vision|extractor]
relay-knowledge proposal list [--state proposed|accepted|rejected|superseded] [--limit <n>]
relay-knowledge proposal show <proposal-id>
relay-knowledge proposal accept|reject|supersede <proposal-id> --by <actor> [--reason <text>]
relay-knowledge audit query [--operation <name>] [--limit <n>]
relay-knowledge provider probe
relay-knowledge health
relay-knowledge service status
relay-knowledge service doctor
relay-knowledge service plan install|upgrade|rollback|uninstall [--target-version <version>] [--install-dir <path>]
relay-knowledge service lifecycle install|upgrade|rollback|uninstall [--dry-run|--execute] [--target-version <version>] [--install-dir <path>]
relay-knowledge service definition write
relay-knowledge service operator status|pause|resume
relay-knowledge service worker run [--task-id <id>]
relay-knowledge service run [--web] [--mcp streamable-http]
relay-knowledge setup doctor
relay-knowledge setup profile local|agent-readonly|service|external-embedding
relay-knowledge version
relay-knowledge version check
```
Kind values are scoped to their command family:
- `repo query --kind` and `repo-set query --kind`: `hybrid`, `symbol`,
`definition`, `references`, `callers`, `callees`, `imports`, `sbom`.
- `repo framework --kind`: `component`, `directive`, `pipe`, `template`,
`input`, `output`, `prop`, `emit`, `model`, `slot`, `template-variable`,
`control-flow`.
- `repo software --kind`: `dependencies`, `sdks`, `files`, `topics`,
`relationships`, `build`, `iac`, `design`, `all`.
- `repo business --kind`: `terms`, `mappings`, `all`.
- `repo view --kind`: `architecture-layers`, `business-domains`,
`dependency-tour`, `process-flow`, `affected-scope`.
- `index refresh --kind`: `bm25`, `semantic`, `vector`; omitting `--kind`
requests all supported index families.
- `worker status|run-once --kind`: `embedding`, `ocr`, `vision`, `extractor`.
- `map source add|update --kind`: `repo`, `file`, `doc`, `config`, `db`,
`ci`, `runtime`, `wiki`, `monitoring`.
Do not pass kind values across command families. Use `repo impact` for impact
analysis, `repo framework` for Angular/Vue template semantics, and
`repo feature-flags` for feature flags; they are not
`repo query --kind` values.
`--path` is the CLI flag for a path filter. `repo register --path` stores the
indexed scope, while `repo query --path`, `repo framework --path`, and `repo feature-flags --path` narrow
reads inside that indexed scope. `repo index` does not accept `--path`; it uses
the registered scope and the selected `--ref`. Non-Git source directories use
`HEAD` for the normal moving filesystem snapshot, and status records the
resolved `filesystem:<hash>` commit. `worktree` is a Git worktree-overlay
selector, not the default for non-Git directories.
Cold full `repo index` requests return a durable task handle immediately and start a bounded background worker from the CLI process. When `--reuse-historical` is supplied for a Git repository whose target scope is not fresh, the service checks the nearest 10 commits on the target's first-parent chain. If the nearest compatible scope is published at the current fact version, the full request is pinned as a real `Incremental { base_ref, head_ref }` task; `task.mode` and the completed `base_resolved_commit_sha` expose that choice. No compatible base, or a base-to-head diff above the historical-reuse limit of 100 changed paths, falls back automatically to the checkpointed full index. Without `--reuse-historical`, `repo index` keeps the default checkpointed full-index behavior. Non-interactive agents can run `repo index-worker --task-id <id> --format json` as an explicit single-shot drain command for queued or retrying tasks; every call also advances one bounded scope-retention pass and reports `maintenance_active` plus optional `maintenance_error`. A non-null maintenance error reports that pass separately from the code-index task and makes `maintenance_active=false` inconclusive; inspect `repo status`, resolve the error, and retry a bounded pass. Without `service run`, repeat the local command until both it and `repo status` report no pending maintenance. `service worker run [--task-id <id>] --format json` is the split-worker preview entrypoint and claims at most one durable code-index task, completing or failing it through task id, lease owner, and attempt count checks; it does not expose these local retention fields. `service run` drains the same code-index queue for installed or foreground service operation. Use `repo status --format json` to inspect `active_task`, checkpoint counters, and scope retention while a cold repository index is running. `repo index <alias> --reset --format json` clears unfinished task leases for the repository without deleting completed indexed scopes or reviving terminal dead-letter history. Index writes use one live writer per repository; queries, reports, graph reads, file queries, and health diagnostics use bounded read-only connections to read committed snapshots where SQLite WAL permits it.
`repo update <alias>` submits an incremental task through that same durable queue. If omitted, `--base` is the last published clean Git commit (a worktree-overlay identity is unwrapped to its clean base) and `--head` is `HEAD`; the service resolves both to immutable commits before queueing. Without a published clean base, first run `repo index <alias> --ref HEAD`. A local CLI makes one bounded drain attempt, while remote `repo update` can return `task.state=queued` for the resident workers. A completed response `summary` includes `base_resolved_commit_sha`; a queued task exposes the pinned pair through `task.mode`. Each Git delta is limited to 512 changed paths across the commit pair before registered path filters, after which the caller must use full indexing.
Scope retention runs after successful publication. It keeps the union of the active scope and a rolling window of the two latest successful publications (normally including active), the latest successful incremental predecessor, the clean base of any active worktree overlay, plus unfinished task target/base scopes and repository-set pins. It atomically marks one older scope `retiring`, excludes it from reads and incremental-base selection, and records a durable GC job; each later maintenance transaction advances one scope-GC phase whose physical deletion is capped at 512 rows in aggregate across the affected application tables, including facts, FTS/search rows, software projections, checkpoints, workspace state, and scope metadata. Same-tree commits share content under a bounded 256-row commit-alias window. Finished task audit rows are bounded per repository to 128 successes and 64 failures/dead letters/cancellations, except that a retained scope keeps its latest success row. `repo status --format json` exposes `maintenance_pending` and each retiring job's phase, deleted-row count, and last error; `scope_listing_truncated=true` means the retained/prunable arrays and displayed counts are bounded diagnostic projections rather than exhaustive lists. A pruned ref requires a full reindex before graph queries or incremental reuse.
`repo list` is the read-only inventory of indexed repositories. It returns only repositories with at least one completed indexed scope; repositories that have only been registered and have not completed `repo index` are omitted. Text output prints one repository per line with its alias, state, file and symbol counts, stale flag, indexed commit, and root. `--format json` returns `metadata` plus a `repositories` status array in stable alias/repository-id order. With `--remote`, the command reads the service-host inventory and never falls back to local runtime state.
After a bulk code-index snapshot apply or checkpointed finalize succeeds, SQLite storage automatically runs best-effort `PRAGMA optimize` and `PRAGMA wal_checkpoint(PASSIVE)` to refresh planner statistics and fold WAL pages back into the main database. A maintenance failure does not roll back an otherwise successful index result, but `health --format json` and graph inspection expose `graph.sqlite.journal_mode`, `wal_size_bytes`, `last_maintenance_at_ms`, and `last_maintenance_error`. The timestamp and error are persisted in SQLite so they survive service restarts and one-shot worker exits. Under `partitioned_sqlite`, these fields aggregate the control database and active repository shard databases through read-only shard diagnostics; if any active shard cannot be inspected, `wal_size_bytes` is unknown and the shard error remains visible. Large-repository query-plan or indexing-performance regressions should be covered through `tools/self_iteration --categories performance` rather than uncontrolled large fixtures in ordinary CLI paths.
`repo remove <alias>` deletes the registered repository behind that alias from relay-knowledge runtime state, including all aliases for the repository id, code index scopes, code-index tasks, repository-set membership, repository-set overlays, and software projection rows. It does not delete files from the source repository on disk. Removal is rejected while the repository still has a running code-index task lease; after a successful remove, the same path or alias can be registered again.
`query` returns display-compatible `results`, an agent-oriented `context_pack`, per-family `indexes`, scoped `index_cursors`, and `index_refresh` queue/lag diagnostics. `index_refresh.stale_reasons` explains BM25, semantic, vector, and scoped cursor lag or failures; `index_cursors` reports source scope, modality, backend cursor, model metadata, indexed graph version, and last error where present. `--freshness wait-until-fresh` runs the bounded refresh path before answering; `--freshness allow-stale` may return stale read models but marks metadata and degraded reason; `--freshness graph-only` bypasses derived read models and leaves cursor/queue diagnostics empty.
`files index` scans configured or explicit authorized local roots into two read models. The low-latency path/metadata model powers `files query` and does not depend on content extraction. The bounded content model powers `files content` for Markdown, text, YAML/JSON, SQL, TOML, CSV, INI, config, and XML files within the content byte budget. Explicit roots must be absolute paths allowed by `RELAY_KNOWLEDGE_FILE_INDEX_ROOTS`; omitting `--root` scans the configured roots. `files query` and `files content` read committed local indexes rather than shelling out to Everything, Spotlight, Windows Search, locate, `rg`, or `grep`. Content hits include `content_role="user_source"`, source path, span, fingerprint, content hash, indexed graph version, ranking signals, and candidate facts; adapters must treat content as quoted source data, not as agent or system instructions. The JSON freshness response also includes `freshness.state`, `freshness.index_lag`, `freshness.cursors`, `freshness.stale_reason`, `freshness.degraded_reason`, `freshness.bounded_rescan_required`, `freshness.direct_source_read_required`, `freshness.direct_source_read_paths`, and `freshness.agent_instructions`; stale file-content cursor counts are reported through bounded root diagnostics when a derived content read model is behind, without materializing every cursor row. Content byte-budget exhaustion is reported as overflow, while eligible files that cannot be opened or decoded are reported as degraded read failures with the root last error preserved. The v1 content BM25/fact read model is refreshed synchronously during the bounded scan, so successful scans can satisfy `--freshness wait-until-fresh`; pending, stale, degraded, or overflowed file-index states still suppress answers until a bounded scan has completed. `--freshness allow-stale` may return indexed paths or content with those diagnostics; agents must directly read returned paths before editing or citing changed files when `direct_source_read_required=true`.
`repo query` runs `definition`, `references`, and `hybrid` queries through the indexed tree-sitter graph and SQLite FTS read model first. With `--freshness allow-stale`, if the target ref is still being full-indexed and has not finalized, the query reads the previous completed committed scope and marks the response stale/degraded; `wait-until-fresh` still requires the target scope to be fresh. The JSON response includes `freshness.state`, `freshness.index_lag`, `freshness.pending`, `freshness.cursor`, `freshness.direct_source_read_required`, and `freshness.agent_instructions` so agents can see checkpoint progress and know when returned paths require direct source reads before editing or citation. Only when structured layers leave a specific recall gap does the query start bounded internal exact-text source fallback against the same indexed commit. JSON hits are marked with `retrieval_layers=["lexical","text_fallback"]`; definition fallback may also include `definition`. Candidate-path lookup, candidate-file, materialized-byte, or line-length budget exhaustion degrades only the fallback layer and appears in `degraded_reason`; structured code graph results remain valid.
`repo context` is the one-call coding-agent context pack over the same committed read model. It resolves authored business terms and aliases first, uses resolved mapping ids or unresolved `target_hint` values as bounded technical seeds, and then expands through hybrid, definition, symbol, references, callers, callees, and imports. JSON adds `business_context`; business and technical candidates share the exact resolved commit/source scope and the same result, byte, truncation, and provenance budgets. The command never reads glossary YAML at query time or starts repository indexing.
`repo query --query` accepts inline filters such as `kind:function`, `lang:rust` or `language:rust`, `path:storage`, and `name:query`. Unknown `prefix:value` tokens remain ordinary search text. Inline language filters intersect explicit `--language`; `kind` and language narrow SQL candidates, while `path` and `name` filter scored hits before truncation. `name:` matches symbol identities and SBOM package identities, not arbitrary excerpt text.
`repo feature-flags` reads configuration-driven feature-flag graph facts written during indexing. By default it lists flags, configuration sources, and code-usage edges in the selected repository scope; `--query` filters by flag name, config key, path, or excerpt. Its JSON response includes the same `freshness` object as `repo query`, including pending task, checkpoint cursor, index lag, stale/degraded reason, and direct-source-read paths for returned feature-flag usage files. The extractor recognizes environment variables, config/settings keys, boolean config declarations, and common SDK evaluation calls such as OpenFeature, LaunchDarkly, and Unleash clients. It does not sync provider control-plane state, strategies, segments, or rollout variants. The command does not scan the whole source tree at query time; after extractor changes or newly added flags, run `repo index` or `repo update` before expecting new facts.
`repo framework` reads the independent Angular/Vue component-template graph written during indexing. Repeat `--framework`, `--kind`, or `--path` to intersect filters; omit them to enumerate the bounded selected scope. The graph includes typed nodes for components, templates, bindings, slots, template variables, and control flow, plus ownership, render, binding, event, read/write, directive, and slot edges. Vue SFC script symbols and imports remain available through ordinary `repo query`. The command never scans source at query time and never starts indexing; `wait-until-fresh` requires the durable indexed snapshot to include current framework facts.
`repo software` reads the software global-model projection for the selected repository scope. `--kind dependencies` returns package components derived from manifests and lockfiles plus `dependency_usages` that link declared packages to matching code/config import evidence. Repeated lockfile rows for the same repository-level package/version coordinate appear as one derived locked component with deterministic representative evidence, while declared components and raw `repo query --kind sbom` evidence remain evidence-specific. `--kind sdks` returns unresolved external import/include targets as SDK or API-surface usage candidates; `--kind files` returns whole-file nodes for code, config, docs, build manifests, deployments, tests, and templates; `--kind topics` returns topics extracted from Markdown/spec headings and `knowledge/knowledge-map.yaml`; `--kind relationships` returns cross-domain edges such as `documents`, `depends_on`, `uses_sdk`, and `configures`. `--kind build` returns package, script, target, feature, module, profile, plugin, goal, and job entries extracted from Cargo, npm, Python, Go, Maven effective `pom.xml`, Gradle, CMake, Makefile, and CI workflow evidence. `--kind iac` returns deployment and infrastructure resources extracted from Dockerfile, Compose, Kubernetes YAML, Helm charts, Terraform, systemd, launchd, and CI workflow evidence. `--kind design` returns evidence-backed software systems, modules, components, interfaces, and capabilities from README files, architecture/design Markdown, and package/module manifests. The command does not execute build tools, scan package caches, SDK directories, cloud APIs, unindexed external source, or whole-repository docs at query time; rerun `repo index` or `repo update` to refresh the projection after source-scope changes.
`repo business` reads the projection of `knowledge/glossary/business-glossary.yaml` authorized by the Knowledge Map `business-knowledge` route during indexing. `--kind terms` returns canonical terms, definitions, aliases, semantics, conflicts, and evidence; `mappings` returns `represented_by` and `calculated_from` mappings. A cross-domain homonym without `--domain` resolves as `ambiguous` instead of being guessed. Targets outside the authorized scope or unsupported in v1 retain `resolution_state=unresolved` plus `target_hint` without degrading the repository. Business definitions remain editable only through the versioned glossary and code review.
`repo view` returns graph-derived codebase understanding views as JSON. `business-domains` merges glossary-declared domains first (`evidence.kind=business_glossary`) and then adds path, route, and feature-flag inferences; the other views derive from indexed files, symbols, imports, calls, routes, dependencies, and feature flags in the selected repository scope. `affected-scope` requires one or more `--changed-path` values in deterministic v1 and returns changed files, affected modules, call edges, and nearby test/config/doc candidates. The response includes `nodes`, `edges`, `sections`, `evidence`, freshness diagnostics, and truncation budget metadata; section narratives are short derived explanations backed by evidence ids, not persisted graph facts or AI-generated source of truth.
Agent-facing MCP kind access reuses the same kind families rather than introducing parallel names. `relay_code_query` covers code graph kinds, `relay_business_query` covers authored business terms and technical mappings, `relay_software_query` covers software global-model kinds, `relay_code_feature_flags` covers configuration-driven feature flags, and `relay_codebase_view` covers the `repo view` kind family. Common agent aliases are normalized to existing kinds: `dependency` to `dependencies`, `configuration` to `relationships`, and `model` or `models` to `design`.
`map` commands maintain `codespec/codespec-map.yaml` and `knowledge/knowledge-map.yaml`. `map init`, `show`, `history`, and `validate` default to `--type all`; targeted mutations require `--type knowledge` or `--type codespec`, while source and route commands accept only Knowledge. Schema v3 adds typed `directories` while retaining content-addressed topics under `knowledge/topics/`, bounded recent history, verified `knowledge/history/` archives, and the bounded-depth history index. `map directory add|update|remove` is the supported update surface for directory governance; the five baseline directories in each map cannot be removed. `map migrate --type knowledge --to-v3` preserves v1/v2 content, publishes the visible root last, and writes a v3 redirect at the legacy path; `--rollback` restores the retained v2 root. `map validate` remains authoritative for files, digests, relationships, history, paths, built-in sources, and AGENTS references.
The CLI skill ships `references/knowledge-map.schema.json`, a JSON Schema Draft 2020-12 document covering the v2 root manifest, topic shard, history archive, and history index node. Editors and agents may use it for field discovery and structural checks after parsing YAML into a JSON-compatible value. The schema intentionally permits unknown fields to match the current Serde readers. Schema acceptance does not prove digest/content agreement, global source-id uniqueness, route completeness, history continuity, index range/height relationships, or reserved-source invariants; `relay-knowledge map validate` remains authoritative. The schema also does not authorize direct edits to CLI-generated shards, archives, or index nodes.
The skill also ships `references/business-glossary.schema.json`, a separate Draft 2020-12 schema for the authored Business Glossary v1 document. It covers domains, terms, aliases, declarative semantics, technical mappings, enums, and collection bounds while retaining the same unknown-field compatibility. JSON Schema `maxLength` is a character-count structural approximation; `relay-knowledge map validate` remains authoritative for the 4 MiB file limit, UTF-8 byte-sized fields, identity and domain-reference rules, and case-insensitive alias uniqueness. Unlike generated Knowledge Map artifacts, `knowledge/glossary/business-glossary.yaml` is intentionally edited under version control and normal code review.
The contract stores stable navigation and model-entry metadata only. It does not copy authoritative knowledge or snapshot-bound architecture/build/deployment projection rows out of documents, code, config, CI, runtime systems, or external sources. One topic can contain multiple sources, and `map source add` appends distinct source ids to that topic route order. All refs are repository-controlled relative paths; absolute paths, parent traversal, and symlink escape are rejected. Mutations share a cross-platform OS advisory writer lock, publish immutable artifacts first, and replace the root manifest last. A live writer remains exclusive, while an abnormal process exit releases ownership without requiring deletion of the persistent `.lock` inode. The first mutation also creates or extends the selected `knowledge/` or `codespec/` root's `.gitignore`; commit that nested contract with the map so canonical and prepared lock inodes remain excluded in ordinary Git repositories and linked worktrees. LLM agents update directory governance through `map directory`, use `map show` and `map route` to locate Knowledge sources, maintain those sources through `map source add/update/remove`, and run `map validate --format json` after changes. AGENTS.md keeps `CodeSpec map: codespec/codespec-map.yaml` and `Knowledge map: knowledge/knowledge-map.yaml` as stable references.
## 3.5 Read and Write Impact
Status, health, help, setup doctor/profile, provider probe, version check, `repo list`, report, map show/history/route/validate/agent-snippet, and audit query are diagnostic entry points and should not mutate graph facts. `health` is a liveness fast path: it does not queue index refresh work and does not wait for a code-index writer to finish; when storage is busy it may return stale/degraded `storage_busy`. `version check` may only refresh the version-check cache under the runtime cache directory. `ingest`, `map init`, `map directory add/update/remove`, `map migrate`, `map source add/update/remove`, `repo remove`, `repo index`, `repo update`, `index refresh`, `worker run-once`, proposal state changes, and service definition write can write runtime state, derived indexes, proposals/audit, repository navigation contracts, or service definitions.
Automated callers should read operation and read/write metadata from `help --format json` before exposing a command in CI, agents, or the Web operation surface.
## 3.6 Skill-over-CLI
The repository ships `skills/relay-knowledge-cli`, a ClawHub-compatible skill
for LLM agents that should operate relay-knowledge by invoking the local CLI and
parsing JSON output. It covers installation checks, `version check`, setup and
health diagnostics, knowledge graph ingestion/query, and code repository
registration, indexing, query, update, impact, and report workflows. Its
repository bootstrap initializes/validates the map and code map together; its
spec-grounded commit loop pins one ref and combines map routes with software,
architecture, impact, and code-context evidence.
The same skill package includes the Knowledge Map v2 schema for structural
tooling. Its metadata gate checks the Draft identifier, all four artifact
branches, key reusable definitions, open-field compatibility, and representative
positive and negative instances before release packaging.
The skill intentionally does not configure MCP, call MCP tools, or manage ACP
sessions. Use the MCP/ACP chapters for protocol-level agent access.