--- generator: "vaultspec-marketing discovery" title: "vaultspec-core CLI reference - vaultspec-core documentation" description: "Complete command-line interface (CLI) reference for vaultspec-core. See the framework manual for workflows and concepts." url: "https://vaultspec.neve.md/docs/core/cli.html" component: "vaultspec-core" source_repository: "https://github.com/nevenincs/vaultspec-core" source_path: "docs/CLI.md" source_commit: "213637c2377fe9e51e2a7d57988453852c1b0f84" date_modified: "2026-10-12T11:04:37+02:00" --- [View as Markdown]() # vaultspec-core CLI reference Complete command-line interface (CLI) reference for `vaultspec-core`. See the [framework manual]() for workflows and concepts. ## Contents - [Entry points]() - invoking the CLI and the MCP server. - [Global options]() - flags accepted across commands. - [Outcome vocabulary]() - the words and glyphs that report results. - [JSON output envelope]() - the shape of `--json` output. - [Surface provenance]() - what is on this branch and not yet in a release. - [Command index]() - every command, grouped, with a one-line summary. - [Settings resolution]() - the one rung order every setting resolves through. - [Workspace commands]() - install, uninstall, and sync. - [Vault commands]() - create, query, and edit vault documents and plans. - [Spec commands]() - manage rules, skills, agents, hooks, triggers, MCPs, and the system prompt. - [Migration commands]() - inspect and run schema migrations. - [Config commands]() - read and write local project settings. - [Environment variables]() - the `VAULTSPEC_` settings. ## Entry points - `vaultspec-core` - Workspace management, vault operations, resource sync. - `vaultspec-core-mcp` - Console script that launches the stdio Model Context Protocol (MCP) server. - `uv run --no-sync python -P -m vaultspec_core.mcp_server.app` - Module invocation of the MCP server (avoids binary locking on Windows; `--no-sync` keeps a client connect from mutating the environment; `-P` keeps the working directory off `sys.path`). See [MCP reference](). ## Global options These options apply at the top level unless noted. `--debug` and `--version` are top-level only. `--target` is accepted by target-aware workspace commands, `vaultspec-core vault ...`, `vaultspec-core spec ...`, and `vaultspec-core migrations ...`. `--json` is command-specific and appears only on commands that support JavaScript Object Notation (JSON) output. - `--target DIR` (`-t`, default discovered) - Target workspace directory. Overrides `VAULTSPEC_TARGET_DIR`. With neither set, the root is discovered from the working directory: the `.gt/` container root, then the worktree root, then the repository root, and the working directory itself only when none of those is found. - `--debug` (`-d`, default off) - Enable DEBUG-level logging (top-level flag). - `--verbose` (`-v`, default off) - Enable INFO-level logging (top-level flag). `--debug` outranks it when both are given. - `--version` (`-V`) - Print version and exit (top-level flag). ## Outcome vocabulary Commands that change files report what happened to each one with the same set of words, so results read the same no matter which command ran. The sync-style commands - `vaultspec-core install`, `vaultspec-core sync`, the `vaultspec-core spec sync` commands, and `vaultspec-core migrations run` - print one line per file, each marked with its glyph, then a count of each outcome. With `--json`, those per-file outcomes appear under `data.items`, and the envelope’s top-level `status` is the outcome for the whole run. - `created` (`+`) - A new file or directory was written. - `updated` (`~`) - An existing file was changed. - `unchanged` (`=`) - The file already matched its source, so nothing was written. - `removed` (`-`) - An existing file was deleted. - `restored` (`*`) - A file was reset to its original version. - `skipped` (`s`) - A file was left untouched because a rule or precondition excluded it; the reason is always reported. - `failed` (`x`) - A write was attempted and failed. A `--json` `status` of `mixed` means one run produced more than one outcome. `unchanged` is a successful no-op, not a failure. Only `failed` stops a pipeline. ## JSON output envelope Every command that accepts `--json` emits one uniform envelope, so a consumer parses one shape regardless of which command produced it: **Captured output** ```json { "schema": "vaultspec..v1", "status": "", "data": { }, "hints": { } } ``` - `schema` (required) - Namespaced identifier of the command plus a monotonic version integer. - `status` (required) - The canonical outcome word for the whole invocation (one of the seven words above, or `mixed`). - `data` (required) - The command-specific payload. Read-only commands report their content here under stable keys. - `hints` (optional) - Structured next-step guidance. Absent when no hint applies; its presence never changes `status`. The `schema` value follows the convention `vaultspec..v1` - for example `vaultspec.sync.v1`, `vaultspec.vault.stats.v1`, or `vaultspec.spec.rules.add.v1`. Every schema is at version `v1` except `vaultspec.vault.graph.v2`, documented with `vaultspec-core vault graph` below. Adding new keys under `data` is additive and does not bump the version; renaming or removing a key bumps the integer (`v2`, …). Schema bumps are recorded in the release notes. Failures under `--json` emit the same envelope with the fixed schema `vaultspec.error.v1` and `status` set to `failed`; `data.message` carries the human-readable reason and `data.hint` carries remediation guidance when one is available. A `status` of `failed` always pairs with a non-zero exit code. Under `--json`, stdout contains only the envelope; diagnostics go to stderr. Output is compact by default. For indentation, see [environment variables](). Use the top-level `status` field to check success. ## Surface provenance The block below compares this reference with the latest published release at the time it was generated: what it lists is documented here and absent from that release. It is computed from the surface recorded from that release’s published distribution, so it covers every affected command rather than the ones somebody remembered. The record is written after publication, from the release’s own distribution, through `vaultspec-core spec reference snapshot --record`, and never by hand. Run `vaultspec-core spec reference generate` to refresh the block; do not hand-edit between the markers. Measured against `0.3.5`, the latest published release when this reference was generated: every command, flag, and tool documented here is in it. ## Command index Every `vaultspec-core` command with its arguments. Run any command with `--help` for its full options. ### Top-level commands - [`vaultspec-core install`]() - Install Vaultspec resources for the selected providers. - [`vaultspec-core uninstall`]() - Remove the vaultspec framework from the target directory. - [`vaultspec-core sync`]() - Sync rules, skills, agents, configs, system prompts, and MCPs. - [`vaultspec-core commit-gate`]() - Check the files a commit stages, in one read-only process. - [`vaultspec-core doctor`]() - Diagnose overall workspace and vault health. - [`vaultspec-core status`]() - Orient in a vaultspec vault: rollup, or a grounding trace for a target. ### Vault - [`vaultspec-core vault set-body`]() - Replace only the body prose of a document, keeping its frontmatter. - [`vaultspec-core vault set-frontmatter`]() - Edit selected frontmatter fields, keeping the body byte-for-byte. - [`vaultspec-core vault edit`]() - Set body and/or frontmatter in one atomic write (single round-trip). - [`vaultspec-core vault rename`]() - Rename a document’s file and re-point incoming related references. - [`vaultspec-core vault search`]() - Ask the vault a question and read the passages that answer it. - [`vaultspec-core vault add`]() - Create a new .vault/ document from a template. - [`vaultspec-core vault stats`]() - Show vault statistics and metrics. - [`vaultspec-core vault list`]() - List vault documents, optionally filtered by type. - [`vaultspec-core vault graph`]() - Render the vault document graph. - [`vaultspec-core vault repair`]() - Run the operator repair pipeline for vault content. #### Feature - [`vaultspec-core vault feature list`]() - List all feature tags in the vault. - [`vaultspec-core vault feature index`]() - Generate or update feature index documents. - [`vaultspec-core vault feature archive`]() - Archive all documents for a feature tag. - [`vaultspec-core vault feature unarchive`]() - Restore all archived documents for a feature tag. - [`vaultspec-core vault feature rename`]() - Atomically rename a feature tag across every vault surface. #### Check - [`vaultspec-core vault check all`]() - Run all vault health checks. - [`vaultspec-core vault check body-links`]() - Find wiki-links and markdown path links in document body text. - [`vaultspec-core vault check exec-mapping`]() - Pair ledger rows with plan Steps and flag closed Steps without evidence. - [`vaultspec-core vault check body-sections`]() - Check document bodies carry the sections their template mandates. - [`vaultspec-core vault check annotations`]() - Find generated template annotations in vault documents. - [`vaultspec-core vault check markdown`]() - Check and optionally fix markdown hygiene (whitespace, blank runs, newline). - [`vaultspec-core vault check placeholders`]() - Find unreplaced {…} template placeholders in document body prose. - [`vaultspec-core vault check dangling`]() - Find wiki-links in related: frontmatter that resolve to no document. - [`vaultspec-core vault check orphans`]() - Find documents with no incoming wiki-links. - [`vaultspec-core vault check frontmatter`]() - Validate document frontmatter against vault schema. - [`vaultspec-core vault check modified-stamp`]() - Validate and reconcile the modified recency stamp on every document. - [`vaultspec-core vault check links`]() - Check wiki-links follow Obsidian convention (no .md extension). - [`vaultspec-core vault check features`]() - Check feature tag completeness - missing doc types. - [`vaultspec-core vault check references`]() - Check for missing cross-references within features. - [`vaultspec-core vault check schema`]() - Check ADR evidence links and active plans’ linked decision status. - [`vaultspec-core vault check adr-status`]() - Validate ADR status against the canonical taxonomy. - [`vaultspec-core vault check code-boundary`]() - Scan source files for references to the project’s own vault records. - [`vaultspec-core vault check structure`]() - Check vault directory structure and filename conventions. - [`vaultspec-core vault check rename-integrity`]() - Check name/filename integrity for rules, skills, and agents. - [`vaultspec-core vault check encoding`]() - Surface .vault/ documents that are not valid UTF-8 (detection only). - [`vaultspec-core vault check feature-rename-integrity`]() - Surface exec folders whose feature disagrees with their records’ tag. - [`vaultspec-core vault check foreign`]() - Warn about files the framework did not place inside managed roots. #### Sanitize - [`vaultspec-core vault sanitize annotations`]() - Strip generated template annotations from vault documents. #### Rule - [`vaultspec-core vault rule promote`]() - Promote an audit finding to a team-shared rule. #### Adr - [`vaultspec-core vault adr crossref`]() - Find the ADRs a decision should cross-reference, within fixed bounds. - [`vaultspec-core vault adr supersede`]() - Supersede an old ADR with a new ADR. #### Plan - [`vaultspec-core vault plan status`]() - Report plan health, structure, and completion. - [`vaultspec-core vault plan check`]() - Validate convention compliance; with `--fix`, apply autofixes. - [`vaultspec-core vault plan query`]() - Filter Step rows by container scope and open/closed predicate. - [`vaultspec-core vault plan step toggle`]() - Flip the Step’s checkbox state. - [`vaultspec-core vault plan step check`]() - Mark the Step closed (idempotent). - [`vaultspec-core vault plan step uncheck`]() - Mark the Step open (idempotent). - [`vaultspec-core vault plan step add`]() - Append a new Step at the next-available canonical id. - [`vaultspec-core vault plan step insert`]() - Insert a Step at a named position relative to an existing anchor. - [`vaultspec-core vault plan step edit`]() - Edit the Step’s action and / or scope without changing its identifier. - [`vaultspec-core vault plan step move`]() - Re-parent and / or re-position a Step per the move-flag precedence rule. - [`vaultspec-core vault plan step remove`]() - Remove a Step; its identifier is retired and never reused. - [`vaultspec-core vault plan phase add`]() - Append a new Phase at the next-available canonical id. - [`vaultspec-core vault plan phase insert`]() - Insert a Phase at a named position; parent Wave inferred from anchor. - [`vaultspec-core vault plan phase edit`]() - Edit the Phase’s title and / or intent paragraph in place. - [`vaultspec-core vault plan phase move`]() - Re-parent and / or re-position a Phase. - [`vaultspec-core vault plan phase renumber`]() - Reassign a Phase’s canonical id; descendant Step display paths recompute. - [`vaultspec-core vault plan phase remove`]() - Remove a Phase; descendant Step ids cascade-retire. - [`vaultspec-core vault plan wave add`]() - Append a new Wave at the next-available canonical id (L3+ only). - [`vaultspec-core vault plan wave insert`]() - Insert a Wave at a named position relative to an existing anchor. - [`vaultspec-core vault plan wave edit`]() - Edit the Wave’s title and / or intent paragraph in place. - [`vaultspec-core vault plan wave move`]() - Re-position a Wave in document order. - [`vaultspec-core vault plan wave remove`]() - Remove a Wave; descendant Phase and Step ids cascade-retire. - [`vaultspec-core vault plan epic intent show`]() - Print the Epic intent paragraph (L4 plans only). - [`vaultspec-core vault plan epic intent edit`]() - Replace the Epic intent paragraph (L4 plans only). - [`vaultspec-core vault plan tier show`]() - Print the plan’s declared tier. - [`vaultspec-core vault plan tier promote`]() - Promote the plan tier transitively (L1 -> … -> L4). - [`vaultspec-core vault plan tier demote`]() - Demote the plan tier; refuses multi-child collapse without `--force`. - [`vaultspec-core vault plan trailer emit`]() - Print a well-formed commit-linkage trailer line. - [`vaultspec-core vault plan trailer validate`]() - Validate the commit-linkage trailers in a commit-message file. #### Link - [`vaultspec-core vault link list`]() - List related: edges in the vault document graph. - [`vaultspec-core vault link add`]() - Add a related: edge from *src* to *dst*. - [`vaultspec-core vault link remove`]() - Remove a related: edge from *src* to *dst*. #### Exec - [`vaultspec-core vault exec relink`]() - Relink one execution record to a live Step in its existing parent plan. - [`vaultspec-core vault exec retire`]() - Archive one record only when its current Step is retired by its parent plan. - [`vaultspec-core vault exec detach`]() - Remove a Step claim only when it resolves to neither a live nor retired Step. - [`vaultspec-core vault exec log`]() - Append a Step’s rows to its plan’s ledger. - [`vaultspec-core vault exec fold`]() - Fold a feature’s per-Step execution records into its plan’s ledger. #### Archive - [`vaultspec-core vault archive documents`]() - Archive exactly the documents named in a UTF-8 manifest. - [`vaultspec-core vault archive restore`]() - Restore exactly the archived documents named in a UTF-8 manifest. ### Spec - [`vaultspec-core spec doctor`]() - Diagnose workspace health and report issues. #### Rules - [`vaultspec-core spec rules list`]() - List all available rules. - [`vaultspec-core spec rules add`]() - Add a new custom rule source under .vaultspec/. - [`vaultspec-core spec rules show`]() - Display a rule’s content. - [`vaultspec-core spec rules edit`]() - Open a rule in the configured editor. - [`vaultspec-core spec rules remove`]() - Delete a rule. - [`vaultspec-core spec rules rename`]() - Rename an existing rule atomically. - [`vaultspec-core spec rules sync`]() - Sync only rule files; use vaultspec-core sync for complete refresh. - [`vaultspec-core spec rules restore`]() - Restore a rule to its snapshotted original. - [`vaultspec-core spec rules status`]() - Report rules sync status against provider destinations. #### Skills - [`vaultspec-core spec skills list`]() - List all available skills. - [`vaultspec-core spec skills add`]() - Add a new skill. - [`vaultspec-core spec skills show`]() - Display a skill’s content. - [`vaultspec-core spec skills edit`]() - Open a skill in the configured editor. - [`vaultspec-core spec skills remove`]() - Delete a skill. - [`vaultspec-core spec skills rename`]() - Rename an existing skill atomically. - [`vaultspec-core spec skills sync`]() - Sync only skill files; use vaultspec-core sync for complete refresh. - [`vaultspec-core spec skills restore`]() - Restore a skill to its snapshotted original. - [`vaultspec-core spec skills status`]() - Report skills sync status against provider destinations. #### Agents - [`vaultspec-core spec agents list`]() - List all available agents. - [`vaultspec-core spec agents add`]() - Add a new agent definition. - [`vaultspec-core spec agents show`]() - Display an agent’s content. - [`vaultspec-core spec agents edit`]() - Open an agent in the configured editor. - [`vaultspec-core spec agents remove`]() - Delete an agent definition. - [`vaultspec-core spec agents rename`]() - Rename an existing agent definition atomically. - [`vaultspec-core spec agents sync`]() - Sync only agent files; use vaultspec-core sync for complete refresh. - [`vaultspec-core spec agents restore`]() - Restore an agent to its snapshotted original. - [`vaultspec-core spec agents status`]() - Report agents sync status against provider destinations. #### System - [`vaultspec-core spec system show`]() - Display system prompt parts and targets. - [`vaultspec-core spec system sync`]() - Sync only system prompts; use vaultspec-core sync for complete refresh. #### Hooks - [`vaultspec-core spec hooks list`]() - List this workspace’s hooks and the providers they render into. - [`vaultspec-core spec hooks show`]() - Show one hook’s source file. - [`vaultspec-core spec hooks status`]() - Report parse errors and events no installed provider can run. - [`vaultspec-core spec hooks sync`]() - Render this workspace’s hooks into each provider’s native config. - [`vaultspec-core spec hooks trust`]() - Approve this workspace’s hooks to be rendered into your agents’ configs. - [`vaultspec-core spec hooks add`]() - Deprecated - use ‘spec triggers add’; this alias goes next release. - [`vaultspec-core spec hooks run`]() - Deprecated - use ‘spec triggers run’; this alias goes next release. #### Triggers - [`vaultspec-core spec triggers list`]() - List this workspace’s lifecycle triggers. - [`vaultspec-core spec triggers add`]() - Add a new lifecycle trigger under .vaultspec/triggers/. - [`vaultspec-core spec triggers show`]() - Display a trigger’s source file. - [`vaultspec-core spec triggers edit`]() - Open a trigger in the configured editor. - [`vaultspec-core spec triggers rename`]() - Rename an existing trigger atomically. - [`vaultspec-core spec triggers remove`]() - Delete a trigger. - [`vaultspec-core spec triggers status`]() - Report trigger parse errors and unsupported events. - [`vaultspec-core spec triggers run`]() - Fire this workspace’s triggers for one lifecycle event. - [`vaultspec-core spec triggers trust`]() - Approve this workspace’s triggers to run their shell commands as you. #### Precommit - [`vaultspec-core spec precommit disable`]() - Decline vaultspec-managed .pre-commit-config.yaml scaffolding. - [`vaultspec-core spec precommit enable`]() - Restore vaultspec-managed .pre-commit-config.yaml scaffolding. - [`vaultspec-core spec precommit migrate`]() - Transplant the canonical vaultspec hooks into prek.toml. #### Gitignore - [`vaultspec-core spec gitignore disable`]() - Decline the vaultspec-managed .gitignore block for the whole project. - [`vaultspec-core spec gitignore enable`]() - Restore the vaultspec-managed .gitignore block for the whole project. #### Gitattributes - [`vaultspec-core spec gitattributes disable`]() - Decline the vaultspec-managed .gitattributes block for the whole project. - [`vaultspec-core spec gitattributes enable`]() - Restore the vaultspec-managed .gitattributes block for the whole project. #### Mcps - [`vaultspec-core spec mcps list`]() - List canonical MCP server definitions. - [`vaultspec-core spec mcps status`]() - Inspect provider-native MCP enrollment status. - [`vaultspec-core spec mcps add`]() - Add or replace a canonical MCP server definition. - [`vaultspec-core spec mcps remove`]() - Remove a canonical MCP server definition. - [`vaultspec-core spec mcps sync`]() - Reconcile canonical definitions into provider-native enrollment. - [`vaultspec-core spec mcps trust`]() - Approve exact MCP commands for enrollment after reviewing them at a terminal. - [`vaultspec-core spec mcps uninstall`]() - Remove Vaultspec-owned provider-native MCP enrollment. #### Reference - [`vaultspec-core spec reference generate`]() - Regenerate the generator-owned regions of the bundled CLI reference. - [`vaultspec-core spec reference snapshot`]() - Record or report the published command and MCP tool surface. ### Migrations - [`vaultspec-core migrations status`]() - Show registered migrations and which entries are pending. - [`vaultspec-core migrations run`]() - Run pending schema migrations and bump the manifest version. ### Config - [`vaultspec-core config get`]() - Read a local configuration value. - [`vaultspec-core config set`]() - Write a local configuration value. - [`vaultspec-core config unset`]() - Clear a local configuration entry. - [`vaultspec-core config list`]() - Enumerate all known configuration entries and current values. ### Project - [`vaultspec-core project context`]() - Read local work and optional GitHub state; propose a bounded attention order. ### Review - [`vaultspec-core review context`]() - Read a diff and explicit source locators; optionally rank supporting passages. ## Workspace commands ### install **Usage synopsis** ```bash vaultspec-core install [OPTIONS] [PROVIDER] ``` Deploy the vaultspec framework into the target directory. #### Arguments - `PROVIDER` (default `all`) - `all`, `core`, `claude`, `gemini`, `antigravity`, `codex`. #### Options - `--upgrade` (default off) - Refresh everything install owns, idempotently: re-scaffolds any missing directory, runs pending migrations, re-infers the provisioning mode for a legacy workspace that declares none, syncs, and migrates the MCP launch shape. - `--dry-run` (default off) - Preview without writing. - `--force` (default off) - Overwrite existing installation. - `--skip` (default `[]`) - Skip specific sync passes (repeatable). - `--mode` (default auto) - Select generated hook and MCP launchers: `tool` uses `uvx`; `dependency` and `dev` use `uv run --no-sync`. Selection order: explicit `--mode`, saved mode in `.vaultspec/workspace.json`, dependency detection in `pyproject.toml`, then `tool`. This option doesn’t change package dependency declarations. - `--env NAME` - Import a supported variable from the process environment. Repeatable. `--env NAME=VALUE` supplies a non-secret setting directly. Secret values on the command line are refused; import them by name or file. - `--env-file PATH` - Import supported names from a UTF-8 dotenv file (maximum 64 KiB). Explicit `--env` entries override file entries; the last repeated entry wins. - `--no-hints` (default off) - Suppress next-step advisory hints. - `--json` (default off) - Emit machine-readable output. `core` installs `.vaultspec/` only, without any provider config. Exit codes: `0` success, `1` failure, `2` completed with a required step skipped. The three are shared by every vaultspec package’s install surface; core has no step that reports `2` today. #### Local environment provisioning **Usage synopsis** ```bash vaultspec-core install --env VAULTSPEC_CORE_TYPESAFE_API_KEY vaultspec-core install --upgrade --env-file /private/vaultspec.env --env VAULTSPEC_NO_HINTS=1 ``` The first command imports an already exported key without putting its value in shell history. Only supplied keys replace existing values. Installation, adoption, upgrade, `--force`, and sync preserve unmentioned settings; a failed install does not replace them. Existing installations still require `--upgrade` or `--force`. Dry runs report names and planned outcomes without writing. Outputs never show imported values. Values already present in the process environment affect this invocation but are not saved to the project unless you import them explicitly. Core validates `--env` and `--env-file` before provisioning. After a real install or upgrade returns without errors, Core merges supplied values into `.vaultspec/.env`; a dry run reports outcomes without writing. An import does not change the current process environment or the target, provider, or launch mode already selected for this command; stored values are available to later Core commands. The final report can already reflect imported `VAULTSPEC_JSON_PRETTY` and `VAULTSPEC_NO_HINTS` settings. Values are stored in `.vaultspec/.env`, outside the vault. The installer establishes mandatory ignore rules, refuses tracked or redirected storage paths, and writes atomically with owner-only permissions (a restricted DACL on Windows). Ignore protection remains required when managed-block maintenance is disabled. The commit gate rejects force-added local environment files. Full framework uninstall removes this local store. Protect the original import file separately; installation never rewrites it. Supported imports are `VAULTSPEC_CORE_TYPESAFE_API_KEY`, `VAULTSPEC_IO_BUFFER_SIZE`, `VAULTSPEC_TERMINAL_OUTPUT_LIMIT`, `VAULTSPEC_LOCK_TIMEOUT_SECONDS`, `VAULTSPEC_JSON_PRETTY`, and `VAULTSPEC_NO_HINTS`. Other names are refused. Dotenv imports support comments, `export`, and single-line quoted or unquoted values, with no variable interpolation or shell evaluation. Double-quoted backslashes and quotes may be escaped. For persistable settings, `.vaultspec/.env` is the third rung of the [settings resolution]() order: after explicit command options and the process environment, before the trusted workspace-root `.env` credential fallback, persisted configuration, derived and external defaults, and shipped defaults. A blank value is unset in the store as everywhere else, and falls through. Both CLI and MCP use this resolver, scoped to the selected workspace; file and environment changes refresh its cache. Local settings work in all install modes, while the root `.env` fallback keeps the trust restrictions described under settings resolution. Provisioning does not copy secrets into generated MCP configuration or change the parent shell’s environment. A running MCP server keeps its inherited process environment until restarted, and that environment continues to override local file edits. #### Examples - **Install the framework for all supported provider layers in the current directory**: **Command** ```bash vaultspec-core install all ``` --- ### uninstall **Usage synopsis** ```bash vaultspec-core uninstall [OPTIONS] [PROVIDER] ``` Remove the vaultspec framework from the target directory. #### Arguments - `PROVIDER` (default `all`) - `all`, `core`, `claude`, `gemini`, `antigravity`, `codex`. #### Options - `--remove-vault` (default off) - Also remove `.vault/`. - `--dry-run` (default off) - Preview without deleting. - `--force` (default off) - Required to execute (uninstall is destructive). - `--skip` (default `[]`) - Skip specific removal passes (repeatable). - `--json` (default off) - Emit machine-readable output. `.vault/` is preserved by default. `--remove-vault` deletes it; commit or back up its records first. Exit codes: `0` success, `1` failure, `2` completed with a required step skipped. The three are shared by every vaultspec package’s install surface; core has no step that reports `2` today. #### Examples - **Preview removal while keeping feature records**: **Command** ```bash vaultspec-core uninstall all --dry-run ``` - **After reviewing the preview, remove the harness and keep feature records**: **Command** ```bash vaultspec-core uninstall all --force ``` --- ### sync **Usage synopsis** ```bash vaultspec-core sync [OPTIONS] [PROVIDER] ``` Authoritative complete sync from `.vaultspec/` to enrolled provider outputs: rules, skills, agents, system prompts, provider config stubs, and MCP entries. After editing or adding framework source files, this is the normal propagation command. #### Arguments - `PROVIDER` (default `all`) - `all`, `claude`, `gemini`, `antigravity`, `codex`. `core` is not a valid sync target because sync reads from `.vaultspec/`. Use `vaultspec-core install --upgrade` or `vaultspec-core install --force` for framework/provider scaffolding repair, not as the normal propagation path after source edits. #### Options - `--dry-run` (default off) - Preview changes without writing. - `--force` (default off) - Prune stale files and overwrite user-authored content. - `--skip` (default `[]`) - Skip specific sync passes (repeatable). - `--json` (default off) - Emit machine-readable output. #### Examples - **Synchronize modified rule and agent source files to all provider workspaces**: **Command** ```bash vaultspec-core sync all ``` --- ### commit-gate **Usage synopsis** ```bash vaultspec-core commit-gate [OPTIONS] [PATHS]... ``` The read-only check the generated pre-commit hook runs. It checks each staged vault document with the checkers that judge a document on its own, and blocks only on errors the commit introduces: an error the document’s committed version already carries is printed as advisory and does not block. It also blocks staged per-machine files, such as the install manifest, snapshots, lock sentinels, and local vault caches, and every `.env` or `.env.*` file other than an `.env.example` template. It never writes, and it never runs the whole-vault checks; `vaultspec-core vault check all` remains the corpus-wide gate for CI and explicit runs. #### Arguments - `PATHS` (optional) - Files to check, relative to the workspace root. The hook passes the staged files; with none given, the staged files are read from git. #### Options - `--target DIR` (`-t`, default discovered) - Check a directory other than the current one. - `--json` (default off) - Output as JSON. Exit codes: `0` = nothing blocks, `1` = something blocks. #### Examples - **Check what is staged right now, the way the commit hook will**: **Command** ```bash vaultspec-core commit-gate ``` - **Check two documents explicitly and capture the result for a script**: **Command** ```bash vaultspec-core commit-gate .vault/adr/2026-02-04-auth-adr.md .vault/plan/2026-02-04-auth-plan.md --json ``` --- ### doctor **Usage synopsis** ```bash vaultspec-core doctor [OPTIONS] ``` Diagnose overall workspace and vault health. This is the single health command: it runs the workspace diagnosis of `vaultspec-core spec doctor` and the full vault sweep of `vaultspec-core vault check all`, then reports both under one exit code. Reach for it when you want a yes-or-no answer about the whole project; reach for the two narrower commands when you already know which half you are investigating. #### Options - `--target DIR` (`-t`, default discovered) - Diagnose a directory other than the current one. - `--json` (default off) - Output as JSON. Exit codes: `0` = all ok, `1` = warnings, `2` = errors. Not every line the diagnosis prints is weighed. The tool-server configuration line, the process registry, and stale package seeds are reported for your attention and do not raise the code, so a run can print `warn` and still exit `0`. Do not infer failure from the word `warn` in the output: read the exit code, or read `status` under `--json`. The conditions that do raise it are the framework layout, the provider directories, the builtins, `.gitignore` and `.gitattributes`, migrations, the pre-commit hooks, rename integrity, vault content, and an install-mode or version-floor mismatch on any declared package. #### Examples - **Check the health of the whole project, framework and vault together**: **Command** ```bash vaultspec-core doctor ``` - **Diagnose another checkout and capture the result for a script**: **Command** ```bash vaultspec-core doctor --target ../other-project --json ``` ## Vault commands Group command: `vaultspec-core vault [OPTIONS] COMMAND [ARGS]...` ### vaultspec-core vault add **Usage synopsis** ```bash vaultspec-core vault add [OPTIONS] DOC_TYPE ``` Create a new `.vault/` document from a template. #### Arguments - `DOC_TYPE` - `adr`, `audit`, `exec`, `plan`, `reference`, `research`. #### Options - `--feature TAG` (`-f`) - Feature tag (kebab-case, lowercase letters, digits, hyphens). Required. - `--date DATE` (default today) - Override date (ISO 8601, e.g., YYYY-MM-DD). - `--title TITLE` - Document title. - `--topic TOPIC` - Kebab-case filename infix that distinguishes a second document of the same type for one feature, producing `{date}-{feature}-{topic}-{type}.md`. Only valid for `adr`, `audit`, `reference`, and `research`. - `--related DOC` (`-r`) - Related document(s). Accepts path, filename, stem, or `[[wiki-link]]`. Repeatable. - `--tags TAG` - Accepts only the document’s required directory and feature tags. Repeatable; duplicates are ignored. Other tags are rejected before writing, including with `--force` or `--dry-run`. Omit this option for ordinary creation. - `--force` (default off) - Overwrite an existing document at the resolved path. - `--dry-run` (default off) - Preview without writing files. - `--json` (default off) - Emit machine-readable JSON output in standard envelope. - `--tier TIER` (default L1) - Plan tier (`L1`, `L2`, `L3`, `L4`). Ignored for non-plan types. - `--no-hints` (default off) - Suppress next-step advisory hints. `exec` is not a scaffold type. `vaultspec-core vault add exec` exits 1 with the message “execution is logged with vault exec log”; the ledger is the only execution artifact and `vaultspec-core vault exec log` its only writer. --- ### vaultspec-core vault edit **Usage synopsis** ```bash vaultspec-core vault edit [OPTIONS] REF ``` Set body and/or frontmatter in one atomic write. This is the primary editing surface for a scaffolded document: the body channel (`--body-file` or `--body-stdin`) and the frontmatter flags are applied together in a single write with a single validation pass, so a document never lands on disk with new prose and stale metadata. At least one edit - a body channel or a frontmatter flag - must be supplied. `--expected-blob-hash` requires the full 40-character hash of the document version you reviewed. Compute it with `git hash-object --no-filters `. The write is refused if the file’s raw bytes have changed. After a conflict, reread the document before computing a new hash. #### Arguments - `REF` - Document to edit. Accepts stem, filename, path, or `[[wiki-link]]`. Required. #### Options - `--body-file FILE` - Read the new body text from this file. - `--body-stdin` (default off) - Read the new body text from stdin. - `--date DATE` - Set the date field (`YYYY-MM-DD`). - `--tags TAG` - Set the tags list. Repeatable; replaces the whole list. - `--related DOC` (`-r`) - Set the related list. Repeatable; replaces the whole list. Each input is resolved to `[[wiki-link]]` form. - `--expected-blob-hash HASH` - Refuse the write unless the on-disk blob OID matches. - `--check` / `--no-check` (default `--check`) - Run conformance checks before writing. - `--dry-run` (default off) - Preview without writing. - `--json` (default off) - Output as JSON. - `--target DIR` (`-t`, default discovered) - Target directory. #### Examples - **Replace a document’s prose and relink it in one write**: **Command** ```bash vaultspec-core vault edit 2026-05-17-test-feature-research --body-file draft.md --related 2026-05-17-test-feature-adr ``` - **Pipe generated prose in and preview the result before committing to it**: **Command** ```bash cat draft.md | vaultspec-core vault edit 2026-05-17-test-feature-research --body-stdin --dry-run ``` --- ### vaultspec-core vault set-body **Usage synopsis** ```bash vaultspec-core vault set-body [OPTIONS] REF ``` Replace a document’s body prose and update `modified` and `body_hash`. With `--check` (the default), the proposed content is validated first and the write is refused if any diagnostic is an error. Use this when the metadata is already right and you only want to swap the prose; use `vaultspec-core vault edit` when the same change also touches frontmatter. #### Arguments - `REF` - Document to edit. Accepts stem, filename, path, or `[[wiki-link]]`. Required. #### Options - `--body-file FILE` - Read the new body text from this file. - `--body-stdin` (default off) - Read the new body text from stdin. - `--expected-blob-hash HASH` - Refuse the write unless the on-disk blob OID matches. - `--check` / `--no-check` (default `--check`) - Run conformance checks before writing. - `--dry-run` (default off) - Preview without writing. - `--json` (default off) - Output as JSON. - `--target DIR` (`-t`, default discovered) - Target directory. #### Examples - **Swap in a rewritten body from a file**: **Command** ```bash vaultspec-core vault set-body 2026-05-17-test-feature-research --body-file rewrite.md ``` To reject stale writes, use [`--expected-blob-hash`](). --- ### vaultspec-core vault set-frontmatter **Usage synopsis** ```bash vaultspec-core vault set-frontmatter [OPTIONS] REF ``` Edit selected frontmatter fields, keeping the body byte for byte. Only the fields you pass are changed and every other key is preserved. The proposed metadata is validated before writing and the write is refused on any violation, so a malformed tag set or date never reaches disk. The `modified:` stamp is refreshed automatically. There is no `--title` flag: a document’s title is its body heading, not a frontmatter field. Both `--tags` and `--related` replace the whole list rather than appending, so pass every value you want to keep. To add or drop a single edge instead, use `vaultspec-core vault link add` and `vaultspec-core vault link remove`. #### Arguments - `REF` - Document to edit. Accepts stem, filename, path, or `[[wiki-link]]`. Required. #### Options - `--date DATE` - Set the date field (`YYYY-MM-DD`). - `--tags TAG` - Set the tags list. Repeatable; replaces the whole list. - `--related DOC` (`-r`) - Set the related list. Repeatable; replaces the whole list. Each input is resolved to `[[wiki-link]]` form. - `--expected-blob-hash HASH` - Refuse the write unless the on-disk blob OID matches. - `--dry-run` (default off) - Preview without writing. - `--json` (default off) - Output as JSON. - `--target DIR` (`-t`, default discovered) - Target directory. #### Examples - **Repoint a document’s related list at its governing decision record**: **Command** ```bash vaultspec-core vault set-frontmatter 2026-05-17-test-feature-plan --related 2026-05-17-test-feature-adr ``` - **Correct a document’s date without touching a word of its prose**: **Command** ```bash vaultspec-core vault set-frontmatter 2026-05-17-test-feature-plan --date 2026-05-18 ``` --- ### vaultspec-core vault rename **Usage synopsis** ```bash vaultspec-core vault rename [OPTIONS] REF ``` Rename a document’s file and re-point incoming references. The document is renamed to `<--to>.md` in the same directory, every other document’s `related: [[old-stem]]` entry is rewritten to the new stem, and the `modified:` stamp is refreshed. Pre-checks for blob hash, stem grammar, and filename collision run before anything is written, and the renamed document’s conformance diagnostics come back with the result. This renames one document. To rename a whole feature - its documents, its exec folder, its tags, and its index - use `vaultspec-core vault feature rename`. #### Arguments - `REF` - Document to rename. Accepts stem, filename, path, or `[[wiki-link]]`. Required. #### Options - `--to STEM` - New identity-bearing stem (filename without `.md`). Required. - `--expected-blob-hash HASH` - Refuse the rename unless the on-disk blob OID matches. - `--check` / `--no-check` (default `--check`) - Report conformance checks on the renamed document. - `--dry-run` (default off) - Preview without writing. - `--json` (default off) - Output as JSON. - `--target DIR` (`-t`, default discovered) - Target directory. #### Examples - **Give a document a clearer stem and fix every link that pointed at it**: **Command** ```bash vaultspec-core vault rename 2026-05-17-test-feature-research --to 2026-05-17-test-feature-intake-research ``` - **See which documents a rename would rewrite before running it**: **Command** ```bash vaultspec-core vault rename 2026-05-17-test-feature-research --to 2026-05-17-test-feature-intake-research --dry-run ``` --- ### vaultspec-core status **Usage synopsis** ```bash vaultspec-core status [OPTIONS] [TARGET] ``` Orient in a vaultspec vault: rollup or a grounding trace for a target. This is the top-level zeroth move. Read-only - it never writes and produces no artifact. **Rollup mode** (no `TARGET`): reports plans in flight, each with a one-line overview (tier, completed waves and phases, step completion, and the next open step); plans recently completed; recent changes grouped by type with ledgers collapsed per feature; active features; and vault totals. Outcome semantics: always `unchanged` (read-only verb). Advisory hints point at the targeted form and at `vaultspec-core spec doctor` for framework health. The rollup’s Discovery section says which vault search to reach for. First it says whether hosted vault search (`vaultspec-core vault search`) is configured and whether the key came from the `environment`, provisioned `local_env`, or workspace `dotenv`. It then shows whether the `vaultspec-rag` companion is provisioned, which decides the next step a declined vault search names. Both lines report configuration, not liveness: a configured key can still be rejected when a search runs, and a provisioned companion can still be down. Under `--json` they are `data.hosted_search` (`configured`, `source`) and `data.companion` (`package`, `signal`, `mode`, `version`, `floor`, `health_authority`; the key is absent when the probe failed). **Targeted mode** (`TARGET` is a plan stem, plan path, or feature handle): renders the grounding trace - a plan-line header, then each step (display path, checkbox state, a cursor on the next open step) mapped to its evidence: `ledger N rows` plus the last `verify:` result for a step with ledger rows, `no rows` for an open step without any, or `unlinked` for a closed step without any. Exec documents that reference the plan but name no step are listed as unlinked records. Grounding documents are grouped by type beneath the step list. A feature handle traces every plan under that feature. `vaultspec-core status` is orientation, not auditing: it describes what exists without judging conformance. Use `vaultspec-core vault check` to audit and `vaultspec-core spec doctor` for framework health. #### Options - `--limit N` (default `10`) - Recently modified documents to show, per type. - `--since N` - Show documents modified within the last N days. - `--paths` (default off) - Show each referenced document’s path (targeted mode). - `--verbose-exec` (default off) - List ledgers instead of collapsing them per feature. - `--json` (default off) - Emit machine-readable output (`vaultspec.vault.status.v1`). - `--no-hints` (default off) - Suppress next-step advisory hints. `--limit` and `--since` apply only in rollup mode. `--since` switches from a last-N count to a day-window query. #### Examples - **Get a vault-wide orientation rollup (in-flight plans and recent changes)**: **Command** ```bash vaultspec-core status ``` - **Trace a specific plan to its ledger rows and grounding documents**: **Command** ```bash vaultspec-core status 2026-05-17-test-feature-plan ``` - **Show only documents modified in the last 7 days**: **Command** ```bash vaultspec-core status --since 7 ``` --- ### vaultspec-core vault list **Usage synopsis** ```bash vaultspec-core vault list [OPTIONS] [DOC_TYPE] ``` List vault documents. #### Arguments - `DOC_TYPE` - Filter by document type. #### Options - `--feature TAG` (`-f`) - Filter by feature tag. - `--date DATE` - Filter by date. - `--json` (default off) - Emit machine-readable output. - `--limit N` (default 50) - Maximum documents to return. - `--offset N` (default 0) - Documents to skip, for paging. #### Examples - **List all plans in the vault for a specific feature**: **Command** ```bash vaultspec-core vault list plan --feature test-feature ``` --- ### vaultspec-core vault stats **Usage synopsis** ```bash vaultspec-core vault stats [OPTIONS] ``` Show vault statistics and document counts. #### Options - `--feature TAG` (`-f`) - Filter by feature tag. - `--date DATE` - Filter by date. - `--type TYPE` - Filter by document type. - `--invalid` (default off) - Show only documents with invalid links. - `--orphaned` (default off) - Show only orphaned documents. - `--json` (default off) - Emit machine-readable output. #### Examples - **Display vault-wide statistics with details for orphaned and invalid-link documents**: **Command** ```bash vaultspec-core vault stats --invalid --orphaned ``` --- ### vaultspec-core vault search **Usage synopsis** ```bash vaultspec-core vault search [OPTIONS] QUERY ``` Ask the vault a question in plain language and read the passages that answer it. Hosted search ranks the vault’s records against the question and quotes, for each ranked record, the passage that answers it with its line range. It reads the vault from disk on every search, so there is no index to build or refresh. The same search backs the MCP `search` tool. Hosted search is enabled by a TypeSafe key in `VAULTSPEC_CORE_TYPESAFE_API_KEY` (see [environment variables]()). Every search sends the question and vault text to the TypeSafe API. Without a key the command sends nothing and reports `not configured`. When a configured search fails, it reports `unavailable` with the reason and returns no partial ranking. Either way it prints one sentence: why hosted search did not rank, then the search to run instead. That is a `vaultspec-rag` vault search over the requested record types when the workspace provisions `vaultspec-rag`, otherwise `vaultspec-core vault list` (MCP: `find`), with the type when one was requested, and grep of `.vault/`. Provisioning is read from the workspace configuration; core never calls `vaultspec-rag`. Hosted search covers the vault only; code search is `vaultspec-rag`’s. `vaultspec-core status` shows whether a key is configured and where it came from. The key itself never appears in any output. Output starts with a verdict: `answered`, or `nothing in the vault answers this`. When the provider would not read some records in full, the verdict reads `no record that was read answers this` instead, and the next line gives the number of those records. The ranked records follow, best first. Each record line gives its rank, record name, type, `path:first-last` line range, and the section the passage sits under. The passage follows: at most 700 bytes of whole lines, with `...` marking a passage that goes on past the line range shown. A second passage (`also ...`, 300 bytes) appears when the answer spans two. A `!` note flags a record that may contradict an assumption in the question. The page ends with the hit count and, when the ranking holds more records than were shown, the number withheld. #### Arguments - `QUERY` - The question to ask, in plain language. Must not be blank; at most 2,000 characters. #### Options - `--type TYPE` - Search only records of this type: `adr`, `audit`, `exec`, `plan`, `reference`, or `research`. Repeat the flag to search several types. Generated feature indexes are never searched. By default every type is searched. - `--feature TAG` (`-f`) - Search only this feature’s records. - `--date DATE` - Search only records with this exact date (`YYYY-MM-DD`). - `--limit N` (default `4`) - Maximum ranked records to return, from `1` to `11`. The most a search ranks is 11, so `--limit 11` returns the whole ranking. There is no `--offset`. - `--json` (default off) - Emit machine-readable output (`vaultspec.vault.search.v1`). The type, feature, and date filters are applied before anything is sent: a record they exclude never leaves the machine. Under `--json`, `data` carries the same fields as the MCP `search` result. `data.status` is `ok`, `not_configured`, or `unavailable`, and every reply carries `answered` and the `hits`. An `ok` reply adds `verdict` (`answered`, `nothing_answers`, or `none_read_answers`, the three verdicts above) and the window fields `returned`, `total`, and `truncated`. Each hit carries: `path`, `type`, `feature`, `date`, `title`, `score`, `answers` (the probability that the record states the answer), `premise_conflict`, each score to three decimal places, `blob_hash`, and an `excerpt` with `section`, `line_start`, `line_end`, `text`, and `truncated`. `line_end` is the last line `text` holds, and `truncated` marks a passage that goes on past it. A `supporting` excerpt is present only when the answer spans two passages. The `not_configured` and `unavailable` replies carry a `next_step` (`kind` `rag_search` or `listing`, the `types` it covers, and the `command` to run, where `` stands for your question and the `--feature` and `--date` filters are kept when the search had them) and a `remediation` sentence that words it, and `unavailable` also carries its `reason`: `credential_rejected`, `content_rejected`, `rate_limited`, `transport`, `deadline`, `invalid_response`, or `request_too_large`. `usage` reports the requests, tokens, and time a search spent, and `unscored`, the number of records the provider would not read in full. `answered` is `false` for the whole vault only when `unscored` is `0`. The JSON carries non-ASCII text as UTF-8 rather than `\u` escapes. Exit codes: - `0` - The search ran (envelope `status` `unchanged`), whether or not anything answers. Also `0` when hosted search is not configured (envelope `status` `skipped`). That is the default state without a key, and the reply is the search to run instead, not a failure. - `1` - Hosted search is configured but did not finish (envelope `status` `failed`), or the workspace cannot be read. - `2` - Invalid input: a blank or overlong `QUERY`, an unsearchable `--type`, or a `--limit` outside `1..11`. Nothing is read or sent. #### Examples - **Ask why a decision was taken**: **Command** ```bash vaultspec-core vault search "why does core never call vaultspec-rag" ``` - **Search only one feature’s decisions and read the whole ranking**: **Command** ```bash vaultspec-core vault search "which variable enrols hosted search" --type adr --feature hosted-search --limit 11 ``` - **Script against the verdict and the excerpts**: **Command** ```bash vaultspec-core vault search "what is the default page size" --json ``` --- ### vaultspec-core vault graph **Usage synopsis** ```bash vaultspec-core vault graph [OPTIONS] ``` Outputs a hierarchical tree grouped by feature and type. #### Options - `--feature TAG` (`-f`) - Scope to a single feature. - `--json` (default off) - Output as networkx node-link JSON. - `--metrics` (`-m`, default off) - Show aggregate graph metrics. - `--ascii` (default off) - Render ASCII topology. - `--body` (default off) - Include document body in JSON output. - `--node STEM` - Scope JSON to a node’s local (ego) neighbourhood. - `--depth N` (default 1) - Ego-graph radius in hops; only used with –node. - `--derived/--no-derived` (default off) - Include the derived relatedness edge set in JSON. - `--derived-limit N` (default none) - Maximum derived edges to return. The per-node fan-out cap bounds edges per node, not the total. - `--derived-offset N` (default 0) - Derived edges to skip, for paging. - `--ref REF` - Read the vault corpus from this git ref (branch, tag, or commit) through the object database, without checking it out into the working tree. The `--json` payload (schema `vaultspec.vault.graph.v2`) carries typed weighted explicit edges (`kind`, `multiplicity`, `weight`), node-size hints (`pagerank`, `in_degree`), and a separate `derived_edges` array of implicit relatedness edges kept out of the canonical `edges` array. A missing `--node` stem exits 1 with a `failed` envelope. #### Examples - **Visualize the vault hierarchy and structure as an ASCII tree scoped to a feature**: **Command** ```bash vaultspec-core vault graph --feature test-feature --ascii ``` --- ### vaultspec-core vault repair **Usage synopsis** ```bash vaultspec-core vault repair [OPTIONS] ``` Run the operator repair pipeline for `.vault/` content. This is the guided recovery surface for degraded vaults. It reports preflight and migration state, runs the health checks, applies supported mechanical fixes unless `--dry-run` is set, refreshes generated feature indexes unless `--no-index` is set, rebuilds graph state, and runs a postcheck pass. `vaultspec-core vault repair` is broader than `vaultspec-core vault check all --fix`. The check-level fixer remains available for compatibility, but it does not own generated index refresh, post-fix graph rebuild, root-cause grouping, or final delta reporting. It also strips standalone annotation comments during the fix phase. Inline HTML comments embedded in prose are preserved. #### Options - `--dry-run` (default off) - Preview repair actions without writing. - `--include-index/--no-index` (default on) - Refresh generated feature indexes during repair. - `--feature TAG` (`-f`) - Scope repair and index refresh to one feature. - `--verbose` (`-v`, default off) - Show INFO-level diagnostics and detailed paths. - `--json` (default off) - Emit machine-readable phase and summary payloads. #### Phases - `preflight` - Report migration status and platform path behavior, name every document the pending migrations are about to remove, then apply them. - `check` - Run the current vault health suite without mutation. - `fix` - Apply supported safe check-level fixes, or report planned fixes. - `index` - Refresh or preview generated `.vault/index/.index.md` files. - `postcheck` - Rebuild graph state and rerun checks after mutation. - `summary` - Report changed files, generated indexes, unresolved work, root causes. Dry-run mode never writes generated indexes or check fixes. If migrations are pending, dry-run reports that state rather than entering the index-refresh path, which converges the workspace before it writes. The `preflight` phase lists the documents pending migrations would remove *before* it runs them, and reports where their copies went afterwards. See [where deleted documents go](): a repair on a stale workspace is the run with the most pending destructive entries, and every document it removes is copied to `.vault/.trash/` first. #### Examples - **Scan and apply all safe automatic repairs to a degraded vault**: **Command** ```bash vaultspec-core vault repair ``` --- ### vaultspec-core vault sanitize annotations **Usage synopsis** ```bash vaultspec-core vault sanitize annotations [OPTIONS] ``` Strip generated template annotations from `.vault/` documents. Template hydration keeps agent-facing instructions in newly created documents; this command removes those instructions only when explicitly requested. Use `--dry-run` to see which files would be stripped without mutating the vault. The sanitizer removes YAML frontmatter comment directives, standalone HTML comment blocks, and malformed standalone `<-- ... -->` annotation blocks. It preserves fenced examples, inline HTML comments embedded in prose, and machine-owned comments such as retired plan markers. #### Options - `--feature TAG` (`-f`) - Sanitize documents for one feature. - `--dry-run` (default off) - Preview annotation removals. - `--verbose` (`-v`, default off) - Show stripped files. - `--json` (default off) - Emit machine-readable check payloads. - `--limit N` (default 50) - Maximum findings to return. - `--offset N` (default 0) - Findings to skip, for paging. #### Examples - **Strip all default template instructions and annotations from a feature’s documents**: **Command** ```bash vaultspec-core vault sanitize annotations --feature test-feature ``` --- ### vaultspec-core vault feature list **Usage synopsis** ```bash vaultspec-core vault feature list [OPTIONS] ``` List all feature tags in the vault. #### Options - `--date DATE` - Filter by date. - `--orphaned` (default off) - Show only features with no incoming links. - `--type TYPE` - Filter by document type. - `--stale-days N` - Show only features whose latest activity is older than N days. - `--json` (default off) - Emit machine-readable output. - `--limit N` (default 50) - Maximum features to return. - `--offset N` (default 0) - Features to skip, for paging. #### Examples - **List all active feature tags in the vault**: **Command** ```bash vaultspec-core vault feature list ``` --- ### vaultspec-core vault feature index **Usage synopsis** ```bash vaultspec-core vault feature index [OPTIONS] ``` Generate or update `.index.md` files in `.vault/index/`. Each index links to every document sharing that feature tag, making implicit feature clusters explicit in the graph. Indexes carry the `#index` directory tag plus the feature tag and are auto-managed. #### Options - `--feature TAG` (`-f`) - Generate index for a specific feature. - `--json` (default off) - Emit machine-readable output. #### Examples - **Rebuild or generate the index document for a specific feature**: **Command** ```bash vaultspec-core vault feature index --feature test-feature ``` --- ### vaultspec-core vault feature archive **Usage synopsis** ```bash vaultspec-core vault feature archive [OPTIONS] FEATURE_TAG ``` Move all documents for a feature tag to the archive. #### Options - `--dry-run` (default off) - Preview planned changes. - `--no-hints` (default off) - Suppress next-step advisory hints. - `--json` (default off) - Emit machine-readable output. - `--target` (`-t`) - Target directory (defaults to the discovered workspace root). #### Examples - **Archive all documents for a completed feature tag**: **Command** ```bash vaultspec-core vault feature archive test-feature ``` --- ### vaultspec-core vault feature unarchive **Usage synopsis** ```bash vaultspec-core vault feature unarchive [OPTIONS] FEATURE_TAG ``` Restore all archived documents for a feature tag. #### Options - `--dry-run` (default off) - Preview planned changes. - `--json` (default off) - Emit machine-readable output. - `--target` (`-t`) - Target directory (defaults to the discovered workspace root). #### Examples - **Restore and unarchive all documents for a previously archived feature**: **Command** ```bash vaultspec-core vault feature unarchive test-feature ``` --- ### vaultspec-core vault archive documents **Usage synopsis** ```bash vaultspec-core vault archive documents [OPTIONS] ``` Archive exactly the live vault documents listed in a UTF-8 manifest. Each line must be a repository-relative `.vault/*.md` path. The command validates every source and destination before it moves anything, so a bad line cannot produce a partial archive. #### Options - `--manifest PATH` - Required UTF-8 manifest of repository-relative vault Markdown paths, one per line. - `--dry-run` (default off) - Validate and show the archive destinations without writing. - `--json` (default off) - Emit the standard machine-readable result envelope. #### Examples - **Preview the archival of explicitly selected historical records**: **Command** ```bash vaultspec-core vault archive documents --manifest .vault/archive-manifest.txt --dry-run ``` --- ### vaultspec-core vault archive restore **Usage synopsis** ```bash vaultspec-core vault archive restore [OPTIONS] ``` Bring archived documents back into the live vault. Each manifest line must be a repository-relative `.vault/_archive/*.md` path. This is the inverse of `vaultspec-core vault archive documents`: every source and destination is validated before anything moves, so a bad line cannot produce a partial restore. #### Options - `--manifest PATH` - Required UTF-8 manifest of repository-relative archived Markdown paths, one per line. - `--dry-run` (default off) - Validate and show the restore destinations without writing. - `--deduplicate-identical` (default off) - When an archived document already has a live counterpart with byte-identical content, drop the archived copy instead of failing on the collision. Documents whose contents differ are still reported as conflicts. - `--json` (default off) - Emit the standard machine-readable result envelope. #### Examples - **Preview restoring a set of archived records**: **Command** ```bash vaultspec-core vault archive restore --manifest .vault/restore-manifest.txt --dry-run ``` - **Restore, clearing archived copies that already match the live document**: **Command** ```bash vaultspec-core vault archive restore --manifest .vault/restore-manifest.txt --deduplicate-identical ``` --- ### vaultspec-core vault exec relink **Usage synopsis** ```bash vaultspec-core vault exec relink [OPTIONS] ``` Relink one execution record to a live Step in its existing parent plan. The record body is preserved; only the validated Step mapping can change. #### Options - `--record PATH` - Required live execution-record path. - `--step STEP` - Required live Step identifier or display path in the parent plan. - `--dry-run` (default off) - Preview the recovery without writing. - `--json` (default off) - Emit the standard machine-readable result envelope. --- ### vaultspec-core vault exec retire **Usage synopsis** ```bash vaultspec-core vault exec retire [OPTIONS] ``` Archive one execution record only when its current Step is retired by its parent plan. #### Options - `--record PATH` - Required live execution-record path. - `--dry-run` (default off) - Preview the recovery without writing. - `--json` (default off) - Emit the standard machine-readable result envelope. --- ### vaultspec-core vault exec detach **Usage synopsis** ```bash vaultspec-core vault exec detach [OPTIONS] ``` Remove one record’s Step claim only when it resolves to neither a live nor a retired Step. #### Options - `--record PATH` - Required live execution-record path. - `--dry-run` (default off) - Preview the recovery without writing. - `--json` (default off) - Emit the standard machine-readable result envelope. --- ### vaultspec-core vault exec fold **Usage synopsis** ```bash vaultspec-core vault exec fold [OPTIONS] ``` Fold a feature’s per-Step execution records, from before 0.1.74, into its plan’s ledger. The folded records are removed once the ledger carrying their content is on disk; the upgrade migration runs the same fold on its own. A `body-v1` record’s `## Scope` paths become rows carrying the `T` (touched) operation, because that schema never recorded whether a path was added, modified, or deleted and none is invented; `T` stays distinguishable from a natively logged `A`/`M`/`D`/`R`. A `body-v2` record’s `## Changes` rows fold with their operations and `verify:` line intact, and its `## Notes` lines are carried under the Step id. A flat `--exec.md` record carrying a `step_id` folds too. Other prose is discarded; it is recoverable from the commit preceding the fold, since `.vault/` is tracked, but no forward command undoes it. A Phase Summary is removed once every Step of its Phase has rows in the ledger, and left intact otherwise. A record with no `step_id` cannot be attributed to a Step and is left intact. #### Options - `--feature FEATURE` - Required feature tag, with or without a leading `#`. - `--dry-run` (default off) - Report the fold plan without writing. - `--force` (default off) - Required to apply; the fold removes records. - `--json` (default off) - Emit the standard machine-readable result envelope. --- ### vaultspec-core vault exec log **Usage synopsis** ```bash vaultspec-core vault exec log [OPTIONS] ``` Append one Step’s rows to its plan’s ledger, creating the ledger on first use. The ledger is one document per plan and the only execution artifact; it is append-only: existing rows are never rewritten, and re-logging an identical row is idempotent rather than duplicating it. Concurrent appends to one ledger are serialised by an advisory lock, and the managed `.gitattributes` block declares `merge=union` on ledgers so two branches appending different Steps merge without a conflict. #### Options - `--feature FEATURE` - Required feature tag, with or without a leading `#`. - `--related PLAN_STEM` - Required stem of the parent plan this ledger records. - `--step STEP` - Required canonical Step identifier or display path being logged. - `--row SPEC` - Row to append, repeatable. `A:path` added, `M:path` modified, `D:path` deleted, `R:old->new` renamed. The verb never infers an operation from disk state. - `--verify SPEC` - A check that ran, as `=pass` or `=fail`, repeatable; each is written as its own `verify:` row. - `--by PERSONA` - The persona that closed the Step; written as a `by:` row. - `--note TEXT` - Exception note, repeatable; written as a `## Notes` line under the Step id, the section created on first use. - `--dry-run` (default off) - Resolve and report the target ledger without writing. - `--json` (default off) - Emit the standard machine-readable result envelope. --- ### vaultspec-core vault feature rename **Usage synopsis** ```bash vaultspec-core vault feature rename [OPTIONS] OLD_FEATURE NEW_FEATURE ``` Atomically rename a feature tag across every vault surface. The rename rewrites document filenames, the exec folder and the execution-record filenames inside it, the `#feature` frontmatter tag, `related:` wiki-links, and the regenerated feature index. Free-form body prose is never touched, so a sentence that happens to mention the old name stays as you wrote it. The apply phase keeps a reverse journal. If anything fails part way through, the changes made so far are rolled back to the pre-rename state, so the vault is never left half renamed. By default the command refuses when the target feature already exists; `--force` merges the source feature into it, and per-file path collisions still refuse. Preview first with `--dry-run` - this command touches many files at once. #### Arguments - `OLD_FEATURE` - Current feature tag to rename. Required. - `NEW_FEATURE` - New feature tag name. Required. #### Options - `--dry-run` (default off) - Preview planned changes without writing. - `--force` (default off) - Merge the source into an existing target feature. - `--json` (default off) - Output as JSON. - `--no-hints` (default off) - Suppress next-step advisory hints. - `--target DIR` (`-t`, default discovered) - Target directory. #### Examples - **Preview the full set of files a feature rename would rewrite**: **Command** ```bash vaultspec-core vault feature rename test-feature editor-demo --dry-run ``` - **Fold one feature’s documents into another existing feature**: **Command** ```bash vaultspec-core vault feature rename test-feature editor-demo --force ``` --- ### vaultspec-core vault adr supersede **Usage synopsis** ```bash vaultspec-core vault adr supersede [OPTIONS] OLD_ADR ``` Supersede an old ADR with a new ADR. #### Arguments - `OLD_ADR` - Old ADR stem to supersede. #### Options - `--by` - New ADR stem that supersedes the old one. - `--dry-run` (default off) - Preview without writing. - `--json` (default off) - Output as JSON. - `--target` (`-t`) - Target directory (defaults to the discovered workspace root). #### Examples - **Supersede an outdated ADR with a newly created one**: **Command** ```bash vaultspec-core vault adr supersede 2026-05-17-old-adr-stem --by 2026-05-26-new-adr-stem ``` --- ### vaultspec-core vault adr crossref **Usage synopsis** ```bash vaultspec-core vault adr crossref [OPTIONS] [REFS]... ``` Find the ADRs a decision should cross-reference. Every other ADR is ranked locally; hosted judgments evaluate a bounded shortlist. The reply lists suggested links and declared links judged weak. With `--apply`, the new links are written into the source’s `related:` field. The same backend serves the MCP `crossref` tool. The judgment runs in three stages, each with a fixed ceiling, so a run’s cost does not grow with the size of the vault: - Every other ADR is ranked by code alone: the code identifiers the two decisions share (module and file paths, CLI verbs, configuration variables) and the overlap between the source’s decision text and each candidate’s feature, title, and opening line. Nothing is sent. - The best 192 candidates are put to hosted search as Choice questions of at most 32 options each. - The best 32 of the combined ranking, plus up to 8 declared links outside them, are judged in pairs. A source costs at most 46 requests under a 15-second deadline. A sweep takes at most 50 sources, or 52 when it must settle a refusal, and 300 seconds, and the vault may hold at most 5,000 ADRs. Cross-referencing uses the hosted-search key in `VAULTSPEC_CORE_TYPESAFE_API_KEY` (see [environment variables]()) and sends ADR text to the TypeSafe API. Without a key it sends nothing, reports that it is not configured, and names the search to run instead: the `vaultspec-rag` search when rag is provisioned, the ADR listing otherwise. Output lists each source, then its verdicts. A `link` verdict means the source should link that ADR; it is marked `new`, `declared`, or `written`. A `weak` verdict is a link the source already declares, judged below the threshold. Weak links are listed for a reader to check and are never removed. Each verdict also carries an advisory relation: `supersedes`, `refines`, `depends_on`, `conflicts`, `shared_artifact`, `topic_only`, or `unrelated`. It tells an author which pairs to read in full; it does not decide anything. #### Arguments - `REFS` - ADRs to cross-reference: a stem, filename, path, or `[[wiki-link]]`. One ADR is judged on its own; several make a sweep. #### Options - `--feature TAG` (`-f`) - Sweep this feature’s ADRs. - `--all` (default off) - Sweep non-retired ADRs, including proposals. Superseded, rejected, and deprecated ADRs are skipped unless named. - `--isolated` (default off) - Sweep only ADRs that link no other ADR. Combines with `--feature` to narrow further; `--all` stands alone. - `--after STEM` - Resume a sweep after this ADR: the `next_after` a previous sweep reported, with the same selector. Sweeps run in stem order and store no state. An ADR the provider refuses to read is held open while the sweep judges on, past its source limit by up to two more ADRs if it must: a later ADR the provider reads shows the refusal was that ADR’s own, and the sweep moves past both. A refusal no read settles, three refusals in a row, or any other failure stops the sweep with `stopped` set and the cursor before the first refusal still open, so resuming retries from there. - `--max-sources N` (default `10`) - Most ADRs one sweep judges, from `1` to `50`. - `--body-file PATH` - Judge proposed body prose for one existing ADR without changing it. Use this for an amendment before replacing accepted text. Omit frontmatter; no sweep options or `--apply` may accompany it. The result marks the source as `draft`. - `--apply` (default off) - Write each new `link` verdict into the source’s `related:`, as each source finishes, without reading them first. Nothing is removed, and no candidate is written to. To add only the links you have read and confirmed, run without `--apply` and use `vaultspec-core vault link add`. - `--json` (default off) - Emit machine-readable output (`vaultspec.vault.adr.crossref.v1`). - `--target` (`-t`) - Target directory (defaults to the discovered workspace root). Under `--json`, `data.sources` holds one entry per source judged, with its `status` (`ok`, `not_configured`, or `unavailable`), its `verdicts` (`stem`, `kind`, `score`, `relation`, `status`, `declared`, and `applied` when written), and the counts `links`, `written`, and `verdicts_total`. A reply carries at most 80 verdict rows; a source whose rows were cut has `truncated` set. A source also carries `unjudged_declared` when some declared links were beyond the judged ceiling, `write_failed` for links `--apply` could not write, and, when it was not judged, its `reason`, `next_step`, and `remediation`. `data` also carries the totals `judged`, `links`, and `written`, the number of sources `remaining`, `next_after` when sources remain and one was processed (without it, a resume starts from the beginning), `stopped` when a sweep ended early, and `usage` when anything was sent. Each judged source includes `coverage`: corpus, pool, and judged candidate counts, `source_truncated`, and `candidates_truncated`. Each returned candidate whose input was clipped has `input_truncated`. Decision and constraint sections receive space before context can consume the 6,000-character budget; other sections are retained within that bound. Read relevant full records when input was clipped. An `ok` response means the bounded judgment completed, not that every conflict was excluded. Exit codes: - `0` - Every source taken was judged (envelope `status` `unchanged`, or `updated` when `--apply` wrote links), or hosted search is not configured (envelope `status` `skipped`). - `1` - A link `--apply` judged could not be written, or hosted search is configured but a source could not be judged (envelope `status` `failed`). The reply says where to resume. - `2` - Invalid input: no source or sweep option, a `REFS` entry or `--after` value that is not an ADR of this vault, `REFS` combined with `--feature`, `--isolated`, or `--all`, `--all` combined with `--feature` or `--isolated`, an empty `--feature`, a vault with more than 5,000 ADRs, or `--max-sources` outside `1..50`. #### Examples - **Check a newly drafted ADR before presenting it**: **Command** ```bash vaultspec-core vault adr crossref 2026-05-26-new-adr-stem ``` - **Review the ADRs that link nothing yet, ten at a time**: **Command** ```bash vaultspec-core vault adr crossref --isolated vaultspec-core vault adr crossref --isolated --after 2026-05-17-last-judged-adr-stem ``` --- ### vaultspec-core vault rule promote **Usage synopsis** ```bash vaultspec-core vault rule promote [OPTIONS] ``` Promote an audit finding to a project-level rule. #### Options - `--from` - Audit stem to promote from. Required. - `--as` - Kebab-case name of the promoted rule. Required. - `--force` (default off) - Overwrite existing rule source. - `--dry-run` (default off) - Preview without writing. - `--json` (default off) - Output as JSON. - `--target` (`-t`) - Target directory (defaults to the discovered workspace root). #### Examples - **Promote a specific finding from an audit file into a project-shared rule**: **Command** ```bash vaultspec-core vault rule promote --from 2026-05-17-feature-audit --as project-rule-name ``` --- ### vaultspec-core vault check **Usage synopsis** ```bash vaultspec-core vault check [OPTIONS] COMMAND [ARGS]... ``` Run health checks on `.vault/`. Exits with code `1` if errors are found. #### Shared options - `--fix` (default off) - Apply auto-fixes where supported. - `--feature TAG` (`-f`) - Limit to a specific feature. - `--verbose` (`-v`, default off) - Show INFO-level diagnostics. - `--json` (default off) - Emit machine-readable output. - `--limit N` (default 50) - Maximum findings to return per check. The per-check and aggregate counts are never windowed, so severity totals stay exact on any page. - `--offset N` (default 0) - Findings to skip, for paging. `vaultspec-core vault check all` additionally accepts `--no-hints` to suppress the next-step advisory hints it prints after a run. `rename-integrity` adds a second repair flag, because a name mismatch can be resolved from either side: `--fix` is filename-wins and rewrites the frontmatter name to match the file, while `--fix-frontmatter-wins` is the inverse and renames the file to match the frontmatter name. Pick the one whose side you trust. #### Subcommands - `all` (`--fix`: partial, `--feature`: yes) - Run every check in sequence. - `structure` (`--fix`: yes, `--feature`: no) - Check vault directory structure and filename conventions. - `frontmatter` (`--fix`: yes, `--feature`: yes) - Validate document frontmatter against vault schema. - `modified-stamp` (`--fix`: yes, `--feature`: yes) - Validate and reconcile the `modified:` recency stamp on every document. - `annotations` (`--fix`: yes, `--feature`: yes) - Find generated template annotations in vault documents. - `markdown` (`--fix`: yes, `--feature`: yes) - Check and optionally fix markdown hygiene (whitespace, blank runs, trailing newline). - `links` (`--fix`: yes, `--feature`: yes) - Check wiki-links follow Obsidian convention (no `.md` extension). - `dangling` (`--fix`: yes, `--feature`: yes) - Find `related:` frontmatter wiki-links that resolve to no document. - `body-links` (`--fix`: yes, `--feature`: yes) - Find wiki-links and markdown path links in document body text. - `placeholders` (`--fix`: no, `--feature`: yes) - Find unreplaced `{...}` template placeholders in document body prose. - `orphans` (`--fix`: no, `--feature`: yes) - Find documents with no incoming wiki-links. - `features` (`--fix`: no, `--feature`: yes) - Check feature tag completeness - missing doc types. - `exec-mapping` (`--fix`: no, `--feature`: yes) - Pair ledger rows with plan Steps: a per-Step record or a closed Step with no row in an existing ledger is an error; a closed Step with no row in a plan without a ledger, or a row for an unknown Step, is a warning; a row for a still-open Step is info (work in flight); a row for a retired Step is clean. - `body-sections` (`--fix`: no, `--feature`: yes) - Check document bodies carry the sections their template mandates. - `feature-rename-integrity` (`--fix`: no, `--feature`: yes) - Surface exec folders whose feature disagrees with their records’ tag. - `references` (`--fix`: compatibility-only, `--feature`: yes) - Report missing cross-references without selecting evidence or decision links. - `schema` (`--fix`: compatibility-only, `--feature`: yes) - Check ADR links to Research, Reference, or Audit evidence and the status of decisions linked by active approved plans. Decision-free plans may have no ADR links. - `adr-status` (`--fix`: yes, `--feature`: yes) - Validate ADR status against the canonical taxonomy. Warn about legacy declarations even alongside a canonical H1, and mismatches between superseded status and successor metadata. Repairs only quote a known token; missing or conflicting authority requires inspection. - `rename-integrity` (`--fix`: yes, `--feature`: no) - Check name/filename integrity for rules, skills, and agents. - `encoding` (`--fix`: no, `--feature`: yes) - Surface `.vault/` documents that are not valid UTF-8 (detection only). - `code-boundary` (`--fix`: no, `--feature`: yes) - Scan source files for references to the project’s own vault records (opt-in; findings are advisory). - `foreign` (`--fix`: no, `--feature`: no) - Warn about files the framework did not place inside the managed `.vaultspec/` or `.vault/` trees (detection only; findings are warnings, never errors). `compatibility-only` means the flag is accepted but performs no repairs: evidence and authority links need an explicit choice. `yes` = fully supported, `partial` = only the sub-checks that accept `--fix` apply fixes (`all` dispatches to every check it runs), `no` = flag rejected with error. `all` runs twenty of the twenty-one checks above: `code-boundary` is opt-in and runs only when named, so an exit-0 `all` makes no claim about it. `structure` does not support `--feature` filtering. Use `vaultspec-core vault repair` when the operator goal is end-to-end recovery with generated index refresh, post-fix validation, and a final delta report. #### Examples - **Run all vault health checks to verify link integrity and directory structure**: **Command** ```bash vaultspec-core vault check all ``` - **Audit and automatically repair dangling wiki-links**: **Command** ```bash vaultspec-core vault check dangling --fix ``` - **Check feature completeness for a specific feature tag**: **Command** ```bash vaultspec-core vault check features --feature test-feature ``` - **Scan for and report any generated template instructions or annotations**: **Command** ```bash vaultspec-core vault check annotations --feature test-feature ``` - **Verify Obsidian-style wiki links in body text resolved against the vault**: **Command** ```bash vaultspec-core vault check body-links ``` - **Audit rule, skill, and agent filenames for matching name tags**: **Command** ```bash vaultspec-core vault check rename-integrity ``` - **Find all unreferenced (orphaned) documents in the vault**: **Command** ```bash vaultspec-core vault check orphans ``` - **Validate document frontmatter fields against required templates**: **Command** ```bash vaultspec-core vault check frontmatter --fix ``` - **Check wiki-link formats (ensuring no .md file extensions are used)**: **Command** ```bash vaultspec-core vault check links ``` - **Enforce architectural schema dependency rules**: **Command** ```bash vaultspec-core vault check schema ``` - **Verify all external references are valid and up to date**: **Command** ```bash vaultspec-core vault check references ``` - **Check directory structure and naming conventions for rules, skills, and agents**: **Command** ```bash vaultspec-core vault check structure ``` ### vaultspec-core vault plan **Usage synopsis** ```bash vaultspec-core vault plan [OPTIONS] COMMAND [ARGS]... ``` Inspect and manipulate plan documents per the plan-hardening convention. Plans declare a complexity tier (`L1`, `L2`, `L3`, `L4`) in frontmatter and are structured as `Epic > Wave > Phase > Step`. Every mutating operation goes through this surface. Canonical identifiers (`S##`, `P##`, `W##`) remain append-only and gap-no-reuse. `vaultspec-core vault plan check` flags hand-edits to checkbox glyphs or display paths. #### Examples - **Query all open steps in a plan**: **Command** ```bash vaultspec-core vault plan query .vault/plan/2026-05-17-test-feature-plan.md --open ``` - **Append a Step to Phase P01 of an L2 plan**: **Command** ```bash vaultspec-core vault plan step add --phase P01 --action "Implement login authentication handler" --scope "src/auth.py" .vault/plan/2026-05-17-test-feature-plan.md ``` - **Toggle completion checkbox of a step**: **Command** ```bash vaultspec-core vault plan step toggle .vault/plan/2026-05-17-test-feature-plan.md S01 ``` - **Renumber a phase to resolve duplicate identifier conflicts**: **Command** ```bash vaultspec-core vault plan phase renumber --to P02 .vault/plan/2026-05-17-test-feature-plan.md P01 ``` - **Validate the formatting and structure of an existing plan file**: **Command** ```bash vaultspec-core vault plan check .vault/plan/2026-05-17-test-feature-plan.md ``` - **Mark a plan step completed (idempotent check)**: **Command** ```bash vaultspec-core vault plan step check .vault/plan/2026-05-17-test-feature-plan.md S01 ``` - **Mark a plan step incomplete (idempotent uncheck)**: **Command** ```bash vaultspec-core vault plan step uncheck .vault/plan/2026-05-17-test-feature-plan.md S01 ``` - **Insert a new step before an existing anchor step**: **Command** ```bash vaultspec-core vault plan step insert --action "Validate input arguments" --before S02 .vault/plan/2026-05-17-test-feature-plan.md ``` - **Edit an existing step’s action prose and code scope**: **Command** ```bash vaultspec-core vault plan step edit --action "New auth handler" --scope "src/auth.py" .vault/plan/2026-05-17-test-feature-plan.md S01 ``` - **Move a step to a different phase inside the plan**: **Command** ```bash vaultspec-core vault plan step move --to-phase P02 .vault/plan/2026-05-17-test-feature-plan.md S01 ``` - **Retire a plan step permanently**: **Command** ```bash vaultspec-core vault plan step remove .vault/plan/2026-05-17-test-feature-plan.md S01 ``` - **Append a new phase to the current wave of a plan**: **Command** ```bash vaultspec-core vault plan phase add --title "Authentication Layer" --intent "Set up secure login/signup" .vault/plan/2026-05-17-test-feature-plan.md ``` - **Insert a phase before an existing anchor phase**: **Command** ```bash vaultspec-core vault plan phase insert --title "Database Setup" --before P02 .vault/plan/2026-05-17-test-feature-plan.md ``` - **Edit a phase’s title or intent prose in place**: **Command** ```bash vaultspec-core vault plan phase edit --title "Updated Auth Setup" .vault/plan/2026-05-17-test-feature-plan.md P01 ``` - **Move a phase to a different wave in the plan**: **Command** ```bash vaultspec-core vault plan phase move --to-wave W02 .vault/plan/2026-05-17-test-feature-plan.md P01 ``` - **Retire a phase along with all of its descendant steps**: **Command** ```bash vaultspec-core vault plan phase remove .vault/plan/2026-05-17-test-feature-plan.md P01 ``` - **Append a new wave to a plan**: **Command** ```bash vaultspec-core vault plan wave add --title "Advanced Features" --intent "Add full-text search" .vault/plan/2026-05-17-test-feature-plan.md ``` - **Insert a wave after an existing anchor wave**: **Command** ```bash vaultspec-core vault plan wave insert --title "Optimization Wave" --after W01 .vault/plan/2026-05-17-test-feature-plan.md ``` - **Edit a wave’s title or intent prose in place**: **Command** ```bash vaultspec-core vault plan wave edit --title "Updated Core Wave" .vault/plan/2026-05-17-test-feature-plan.md W01 ``` - **Move a wave to reposition it within the plan**: **Command** ```bash vaultspec-core vault plan wave move --after W02 .vault/plan/2026-05-17-test-feature-plan.md W01 ``` - **Retire a wave along with all of its descendant phases and steps**: **Command** ```bash vaultspec-core vault plan wave remove .vault/plan/2026-05-17-test-feature-plan.md W01 ``` - **Display the plan’s high-level Epic intent paragraph**: **Command** ```bash vaultspec-core vault plan epic intent show .vault/plan/2026-05-17-test-feature-plan.md ``` - **Update the plan’s Epic intent paragraph**: **Command** ```bash vaultspec-core vault plan epic intent edit --text "Epic intent text associating PM issues" .vault/plan/2026-05-17-test-feature-plan.md ``` - **Display the plan’s current complexity tier**: **Command** ```bash vaultspec-core vault plan tier show .vault/plan/2026-05-17-test-feature-plan.md ``` - **Promote a plan’s complexity tier to L4**: **Command** ```bash vaultspec-core vault plan tier promote --target L4 --epic-intent "Epic goal" .vault/plan/2026-05-17-test-feature-plan.md ``` - **Demote a plan’s complexity tier to L1**: **Command** ```bash vaultspec-core vault plan tier demote --target L1 --force .vault/plan/2026-05-17-test-feature-plan.md ``` #### Shared mutation options Every mutating plan verb - the step, phase, wave, epic-intent, and tier commands - shares three flags: - `--dry-run` (default off) - Preview the rewritten plan without writing it. - `--json` (default off) - Output as JSON. - `--canonicalise` (default off) - Strip unrecognized prose blocks while re-serializing the plan. Without it, prose the parser does not recognize is carried through untouched; with it, the plan is rewritten to the canonical structure only. Preview with `--dry-run` before using it on a plan that carries hand-written notes. #### Read commands - `status` - Report plan health, structure, and completion. `--json` emits a machine-readable payload. - `check` - Validate convention compliance; with `--fix`, apply autofixable transformations. - `query` - Filter Step rows by `--phase`/`--wave` scope and `--open`/`--closed` predicate. `vaultspec-core vault plan check` exits `1` when at least one ERROR-severity finding is present. --- #### vaultspec-core vault plan status **Usage synopsis** ```bash vaultspec-core vault plan status [OPTIONS] PATH ``` Report plan health, structure, completion percentages, and identify missing execution records. ##### Arguments - `PATH` - Path to the `.vault/plan/...-plan.md` plan file. ##### Options - `--json` (default off) - Emit machine-readable status payload. ##### General Output When run without `--json`, the command renders a console summary displaying: - **Plan Path & Complexity Tier**: Declared level (`L1` to `L4`). - **Container Counts**: Total count of Epic, Waves, Phases, and Steps. - **Completion Status**: Checked vs. unchecked steps and total progress percentage. ##### Ledger Coverage (`exec-missing`) The status command pairs every checked step with the plan’s ledger: - If a step is checked (`[x]`) in the plan but the ledger has no row naming it, the CLI generates a yellow warning block: **Captured output** ```text ! exec-missing: checked steps lacking execution records: S01, S02 ``` - This warning does not block execution or raise exit codes; the command still exits with code `0`. ##### Machine-Readable Output (`--json`) When passed `--json`, the output utilizes the uniform `vaultspec.vault.plan.status.v1` schema envelope: **Captured output** ```json { "schema": "vaultspec.vault.plan.status.v1", "status": "unchanged", "data": { "path": ".vault/plan/2026-05-17-test-feature-plan.md", "tier": "L2", "waves": 0, "phases": 1, "steps": 5, "checked_steps": 2, "completion_pct": 40.0, "exec_missing_ids": ["S01", "S02"] } } ``` ##### Examples - **Check the progress and ledger coverage of a plan**: **Command** ```bash vaultspec-core vault plan status .vault/plan/2026-05-17-test-feature-plan.md ``` --- #### Step commands - `add` - Append a Step at the next-available `S##`. Requires `--action` and `--scope`. At L2 and above, also supply `--phase`; omit it at L1. - `insert` - Insert at a named position with `--before`/`--after`; parent inferred from anchor. - `edit` - Replace `--action`, `--scope`, or both without changing the canonical identifier. - `move` - Re-parent (`--to-phase`), re-position (`--before`/`--after`), or both. - `remove` - Retire the Step’s canonical id permanently; the next-available counter skips it. - `check` - Mark the Step closed (`[x]`); idempotent. - `uncheck` - Mark the Step open (`[ ]`); idempotent. - `toggle` - Flip the Step’s checkbox state. #### Phase commands - `add` - Append a Phase at the next-available `P##`. Requires `--title` and `--intent`. - `insert` - Insert at a named position with `--before`/`--after`. - `edit` - Replace `--title`, `--intent`, or both in place. - `move` - Re-parent (`--to-wave`), re-position (`--before`/`--after`), or both. - `renumber` - Remediate a duplicated id via `--to `; refuses live / retired collisions. - `remove` - Retire the Phase plus every descendant Step (cascading retirement). `phase renumber` is the audited remediation surface for collisions inherited from legacy plans. One example is a writer who treated `P##` as Wave-scoped rather than per-document. The verb retires the old id so it cannot be reused, then recomputes every descendant Step’s display path against the new parent canonical id. #### Wave commands Identical shape to Phase, but the parent is implicit (Epic frame). Only `--before`/`--after` re-position. No `--to-epic` flag exists. Wave operations require `L3` or `L4`. #### Epic intent (L4 only) - `intent show` - Print the Epic intent paragraph. - `intent edit` - Replace the Epic intent paragraph; `--text` must declare the project-management (PM) association. #### Tier commands - `show` - Print the plan’s declared tier. - `promote` - Advance the tier transitively, for example L1 -> L4 in one call. Synthesized containers use `--phase-title`/`--phase-intent`/`--wave-title`/`--wave-intent`/`--epic-intent` for placeholders. - `demote` - Step the tier down. Refuses with an error when the collapsing layer holds more than one container; pass `--force` to retire the dropped ids and proceed. #### Move-flag precedence `step move` and `phase move` accept the re-parent flag (`--to-phase` / `--to-wave`) and the position flags (`--before` / `--after`) independently or together: - Re-parent flag alone re-parents and appends to the destination tail. - Position flag alone re-positions within the current parent; the anchor must share that parent. - Both flags re-parent and position the item; the anchor must reside in the destination post-move. A self-referential move (`step move S01 --before S01`) is rejected with the relevant `Move{Step,Phase,Wave}Error`. #### Identifier retirement `remove`, multi-step demotion, and Wave / Phase removal all add the retired canonical id to a hidden `` ledger embedded in the plan body. `next_available_*` consults this ledger so retired identifiers are never reused, even across `parse / serialize` round-trips invoked by `--fix`. #### Trailer commands - `emit` - Print a well-formed `Vaultspec-Step` or `Vaultspec-Feature` commit-linkage trailer line. Takes exactly one of `--step` (a Step or Phase display path, e.g. `W01.P02.S06` or `P02`) or `--feature` (a kebab-case feature tag, leading `#` optional). - `validate` - Validate the commit-linkage trailers found in a commit-message file. Always exits `0`. The commit-linkage trailer is an opt-in, advisory convention (per the accepted `commit-linkage` ADR): a malformed or absent trailer never blocks a commit and never fails a core command. `validate` reports each malformed trailer to stderr and always exits `0`, which makes it safe to wire up as a `commit-msg`-stage pre-commit hook. Teams that want the check add a local hook entry to their `.pre-commit-config.yaml`; teams that do not are unaffected: **File contents** ```yaml - repo: local hooks: - id: vaultspec-plan-trailer name: Validate vaultspec commit-linkage trailers language: system stages: [commit-msg] entry: uv run vaultspec-core vault plan trailer validate ``` At the `commit-msg` stage, pre-commit passes the path to the commit-message file (for example `.git/COMMIT_EDITMSG`) as the hook’s positional argument, which lines up with `validate`’s `MESSAGE_FILE` argument - no extra flag is needed. Add uv’s `--no-sync` flag to the `uv run` wrapper when the environment is already resolved and the hook should skip the dependency check. ##### Examples - **Emit a Step trailer for a commit template**: **Command** ```bash vaultspec-core vault plan trailer emit --step P02.S06 ``` - **Emit a feature trailer**: **Command** ```bash vaultspec-core vault plan trailer emit --feature commit-linkage ``` - **Validate a commit message file directly**: **Command** ```bash vaultspec-core vault plan trailer validate .git/COMMIT_EDITMSG ``` --- ### vaultspec-core vault link list **Usage synopsis** ```bash vaultspec-core vault link list [OPTIONS] [SRC] ``` List `related:` edges in the vault document graph. Without `SRC` every edge in the graph is listed. Given a `SRC`, the listing is scoped to that document: its out-links, meaning the edges it declares, and its in-links, meaning the edges other documents point at it. That in-link view is the quick way to answer “what would break if I retired this document?”. Use `--feature` to restrict the listing to edges whose source carries a given feature tag. For a whole-graph picture rather than an edge list, use `vaultspec-core vault graph`. #### Arguments - `SRC` (optional) - Scope the listing to edges from or to this document. Accepts stem, filename, path, or `[[wiki-link]]`. #### Options - `--feature TAG` (`-f`) - Filter edges whose source has this feature tag. - `--json` (default off) - Output as JSON. - `--target DIR` (`-t`, default discovered) - Target directory. #### Examples - **See everything one document links to and everything that links back to it**: **Command** ```bash vaultspec-core vault link list 2026-05-17-test-feature-adr ``` - **List only the edges declared by one feature’s documents**: **Command** ```bash vaultspec-core vault link list --feature test-feature ``` --- ### vaultspec-core vault link add **Usage synopsis** ```bash vaultspec-core vault link add [OPTIONS] SRC DST ``` Add a `related:` edge from `SRC` to `DST`. Both arguments are resolved to document stems and the edge is written into the source document’s `related:` frontmatter as a `[[wiki-link]]`. Adding an edge that already exists is reported as unchanged, so the command is safe to re-run. By default a dangling edge - one whose target resolves to no real document - is refused; pass `--force` when you deliberately want to link ahead to a document you have not scaffolded yet. The command exits `0` when the edge was added or already existed, and `1` when either argument fails to resolve or a dangling edge is refused. #### Arguments - `SRC` - Source document to add the edge from. Accepts stem, filename, path, or `[[wiki-link]]`. Required. - `DST` - Target document to link to. Accepts stem, filename, path, or `[[wiki-link]]`. Required. #### Options - `--dry-run` (default off) - Preview the change without writing. - `--force` (default off) - Allow creating a dangling edge whose target is not a real document. - `--json` (default off) - Output as JSON. - `--target DIR` (`-t`, default discovered) - Target directory. #### Examples - **Link a plan to the decision record it carries out**: **Command** ```bash vaultspec-core vault link add 2026-05-17-test-feature-plan 2026-05-17-test-feature-adr ``` - **Check what a link would write before writing it**: **Command** ```bash vaultspec-core vault link add 2026-05-17-test-feature-plan 2026-05-17-test-feature-adr --dry-run ``` --- ### vaultspec-core vault link remove **Usage synopsis** ```bash vaultspec-core vault link remove [OPTIONS] SRC DST ``` Remove a `related:` edge from `SRC` to `DST`. Only the source document is rewritten; the target is left untouched. Removing an edge that does not exist is reported as unchanged rather than as an error, so the command is safe to re-run and safe to script. It exits `0` on success or on a no-op, and `1` when either argument fails to resolve or the write fails. #### Arguments - `SRC` - Source document to remove the edge from. Accepts stem, filename, path, or `[[wiki-link]]`. Required. - `DST` - Target document to unlink. Accepts stem, filename, path, or `[[wiki-link]]`. Required. #### Options - `--dry-run` (default off) - Preview the change without writing. - `--json` (default off) - Output as JSON. - `--target DIR` (`-t`, default discovered) - Target directory. #### Examples - **Drop a stale link between two documents**: **Command** ```bash vaultspec-core vault link remove 2026-05-17-test-feature-plan 2026-05-17-old-adr-stem ``` ## Spec commands Group command: `vaultspec-core spec [OPTIONS] COMMAND [ARGS]...` Spec subcommands that operate on a workspace accept `--target / -t DIR`. `--json` is command-specific and appears only on commands that support machine-readable output. ### vaultspec-core spec doctor **Usage synopsis** ```bash vaultspec-core spec doctor [OPTIONS] ``` Run diagnostic collectors across the framework, providers, builtins, `.gitignore`, vault content, and configuration files. Reports findings and exits with the highest severity observed. The vault content row is read-only; when generated template annotations are present, doctor reports a warning and points to `vaultspec-core vault sanitize annotations`. Unreadable vault markdown files are reported as warnings and are not modified. #### Options - `--target DIR` (`-t`, default discovered) - Diagnose a directory other than the current one. - `--json` (default off) - Emit the diagnosis as JSON. - `--gate-errors` (default off) - Exit `0` on warnings and fail (exit `2`) only on errors. Intended for the pre-commit gate, where warning-level provider-mirror lag is an expected steady state that must not block a commit. Exit codes: `0` = all ok, `1` = warnings, `2` = errors. Not every line the diagnosis prints is weighed. The tool-server configuration line, the process registry, and stale package seeds are reported for your attention and do not raise the code, so a run can print `warn` and still exit `0`. Do not infer failure from the word `warn` in the output: read the exit code, or read `status` under `--json`. The conditions that do raise it are the framework layout, the provider directories, the builtins, `.gitignore` and `.gitattributes`, migrations, the pre-commit hooks, rename integrity, vault content, and an install-mode or version-floor mismatch on any declared package. #### Examples - **Diagnose overall workspace health across configuration, git, and vault**: **Command** ```bash vaultspec-core spec doctor ``` --- ### vaultspec-core spec rules / vaultspec-core spec skills / vaultspec-core spec agents Create, read, update, and delete (CRUD) operations for framework resources. All three groups share the same subcommand structure. **Usage synopsis** ```bash vaultspec-core spec rules [OPTIONS] COMMAND [ARGS]... vaultspec-core spec skills [OPTIONS] COMMAND [ARGS]... vaultspec-core spec agents [OPTIONS] COMMAND [ARGS]... ``` #### Subcommands - `list` - List all resources. - `add NAME [--body BODY] [--from-file FILE] [--force] [--dry-run]` - Create a resource. `skills add` and `agents add` also accept `--description TEXT` for the resource’s frontmatter summary, and `skills add` additionally accepts `--template NAME` to scaffold from a named template instead of an empty body. - `show NAME` - Print resource content to stdout. - `edit NAME [--editor EDITOR]` - Open in configured editor. Resolution order: –editor flag, local config, VAULTSPEC\_EDITOR, VISUAL, EDITOR, vi. See which editors are accepted. - `remove NAME [--yes|--force]` (`-y`) - Delete a resource. Prompts unless confirmed. - `rename OLD_NAME NEW_NAME` - Rename a resource. - `sync` (`--dry-run`, `--force`) - Resource-scoped sync; use top-level `vaultspec-core sync` for a complete provider refresh. - `restore FILENAME` - Restore to snapshotted original. - `status` (`--json`) - Report dry-run sync with prune enabled, returning missing/drifted/stale status. `edit` accepts the `--editor` option to override the editor binary for this invocation. `add` accepts the unified `--body` flag for direct content or `--from-file` to read from a file. Rules carry no description, so `rules add` has no `--description`; only skills support `--template`. #### Which editors are accepted The editor setting names a command that is executed, so it is validated before anything is launched. Two rules apply to every source. The command must be a program name or path followed by plain arguments. Arguments are expected and supported - `code --wait` and `subl -n -w` are both fine, and a quoted path containing spaces is fine - but shell metacharacters (`;`, `&`, `|`, `` ` ``, `$`, `%`, `(`, `)`), quoting syntax and control characters are refused. The editor is launched directly rather than through a shell, so those characters have no meaning here. The program itself must be a known text editor when the value arrives through the `--editor` flag or through the project-local `editor` config key. Those two travel: a flag can be composed by automation, and `.vaultspec/config.toml` is committed with the workspace, so cloning a repository is enough to inherit its value. Roughly eighty editors are recognised, including `vi`, `vim`, `nvim`, `nano`, `micro`, `emacs`, `helix`, `code`, `codium`, `cursor`, `zed`, `subl`, `kate`, `gedit`, `notepad`, and the JetBrains launchers. A rejection message lists the full set. The `VAULTSPEC_EDITOR`, `VISUAL` and `EDITOR` environment variables are **not** limited to that set. Setting an environment variable for a process already requires the ability to run code as that user, so screening it would protect nothing while stranding anyone whose editor is not recognised. If your editor is refused by the flag or the config key, set it in the environment instead: **Command** ```bash export VAULTSPEC_EDITOR="/opt/my-editor --wait" ``` An editor named by a source that is simply not installed is skipped, and resolution continues down the ladder as before; only a value that resolves and is then refused stops the command, so the reason is never silently swallowed. Editing is interactive by definition. A command invoked through the MCP gateway’s `invoke` tool has no terminal attached, so no editor is opened for it from any source, and the gateway refuses `--editor` outright rather than passing it through. `vaultspec-core spec sync` commands are narrow maintenance surfaces. They do not guarantee that provider-facing config stubs such as `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or `.codex/config.toml` have been fully refreshed. Run `vaultspec-core sync` after source-side changes when the goal is a complete provider-facing workspace. #### Examples - **List all rules, skills, or agents configured in the current project**: **Command** ```bash vaultspec-core spec rules list ``` - **Create a new custom project-level rule**: **Command** ```bash vaultspec-core spec rules add enforce-newline --body "All workspace source files must end with a single trailing newline." ``` - **Create a new custom skill from a local template**: **Command** ```bash vaultspec-core spec skills add unit-test-runner --description "Run python pytest suite" --template "templates/skill_template.md" ``` - **Create a new custom agent persona**: **Command** ```bash vaultspec-core spec agents add database_expert --description "An expert database optimization agent" ``` - **Display the content of a project rule**: **Command** ```bash vaultspec-core spec rules show enforce-newline ``` - **Edit a project skill using a specified editor command**: **Command** ```bash vaultspec-core spec skills edit unit-test-runner --editor zed ``` - **Delete a project agent persona**: **Command** ```bash vaultspec-core spec agents remove database_expert --force ``` - **Rename a project-level rule atomically**: **Command** ```bash vaultspec-core spec rules rename old-rule-name new-rule-name ``` - **Synchronize local rules changes to enrolled provider output stubs**: **Command** ```bash vaultspec-core spec rules sync ``` - **Report parsing and synchronization status of project skills**: **Command** ```bash vaultspec-core spec skills status ``` - **Restore a default rule to its original snapshotted version**: **Command** ```bash vaultspec-core spec rules restore enforce-newline.builtin.md ``` --- ### vaultspec-core spec system **Usage synopsis** ```bash vaultspec-core spec system [OPTIONS] COMMAND [ARGS]... ``` #### Subcommands - `show` (`--json`) - Display system prompt parts and generation targets. - `sync` (`--dry-run`, `--force`, `--json`) - Resource-scoped system prompt sync. #### Examples - **Display assembled system prompt configuration and composition**: **Command** ```bash vaultspec-core spec system show ``` - **Synchronize system prompts and stubs to provider workspaces**: **Command** ```bash vaultspec-core spec system sync ``` --- ### vaultspec-core spec hooks **Usage synopsis** ```bash vaultspec-core spec hooks [OPTIONS] COMMAND [ARGS]... ``` Agent-runtime hooks: shell commands your coding agent runs when something happens in a session. Authored once in `.vaultspec/hooks/` and rendered into each installed provider’s native hook config. For the file format, the canonical events and each provider’s spelling, see [agent-runtime hooks](). This group does not manage vaultspec’s own lifecycle events. Those are [triggers](), and they are a separate directory, a separate command group, and a separate approval. #### Subcommands - `list` (`--json`) - List this workspace’s hooks and the providers they render into. - `show NAME` - Show one hook’s source file. - `status` (`--json`) - Report parse errors and events no installed provider can run. - `sync` (`--dry-run`, `--force`) - Render this workspace’s hooks into each provider’s native config. - `trust [NAME] [--revoke] [--json]` - Approve this workspace’s hooks to be rendered into your agents’ configs, or withdraw that approval. There is no hook `add`: a hook is a file you write in `.vaultspec/hooks/`, like a rule or a skill. - `add [NAME] [--event EVENT] [--command COMMAND] [--force] [--json]` - Deprecated. Creates a *trigger*, not a hook, and is kept only so a caller of the pre-split name reaches what it meant. Use `vaultspec-core spec triggers add`. - `run EVENT [--json]` - Deprecated. Fires a *trigger*, not a hook. Use `vaultspec-core spec triggers run`. Both print a deprecation line naming the replacement, and both are removed one release from now. They are listed rather than hidden because the operator reading `--help` to find where `add` went is exactly the person who needs to be told. #### Hook trust A hook file declares a shell command, and `.vaultspec/hooks/` is shared through git like the rest of your project policy, so a hook definition arrives with every clone and every pull. That makes the file itself the wrong place to record whether its command may run: anyone who can open a pull request could otherwise also grant themselves execution on every machine that clones the branch. A rendered hook raises the stakes over a trigger, because it runs inside your agent’s session on every matching tool call rather than once per sync. vaultspec-core therefore treats a workspace’s hooks as untrusted until an operator says otherwise, and records that decision **outside the workspace** - in the machine-global VaultSpec home, `~/.vaultspec/hook-trust.json`. Nothing a checkout, an archive, or a clone carries can put an entry there. That file keeps its name from before hooks and triggers were separated; its entries are keyed by resolved path, so the two systems’ approvals never collide. Approval is per file and pinned to that file’s exact contents. Editing a hook, or pulling a change to one, drops the approval until you grant it again, so a hook you approved last month cannot quietly become a different command this month. It also means a trusted hook stops running the moment its file changes, which is the intended trade: a second `vaultspec-core spec hooks trust` after an intentional edit is cheaper than an unnoticed one. - Anywhere without an operator - CI (`CI` is set), `--json` output, redirected input, `VAULTSPEC_NON_INTERACTIVE`, or an MCP tool call - the hooks are skipped and the reason is written to stderr. There is no flag that auto-approves, because a flag a script can pass is a flag a repository can talk a script into passing. - The refusal lives in the renderer, not in the prompt, so every route into it is gated and not only the ones that can ask. A hook with no source file on disk is refused for the same reason: nothing about it can be matched against the ledger. - You are asked before a sync that would render and before `vaultspec-core install --upgrade`. A fresh install renders nothing, so it does not ask. - Declining costs only the hooks. The sync itself still completes. - Revoking works end to end: the next sync omits the withdrawn hook and removes the entry it had written, rather than leaving it behind. - `vaultspec-core spec hooks list` shows a `trust` column, so an enabled hook that is not running never has to be a mystery. - The gateway’s `invoke` tool cannot reach `vaultspec-core spec hooks sync`, `vaultspec-core spec hooks trust`, `vaultspec-core sync`, or `vaultspec-core install` at all; they are denied at the MCP surface. `vaultspec-core spec hooks trust` approves provider hooks only. When the workspace also has unapproved triggers, it says so and names the verb that approves those, because the two grants are separate. #### Examples - **List this workspace’s hooks and where each one renders**: **Command** ```bash vaultspec-core spec hooks list ``` - **See which declared events no installed provider can run**: **Command** ```bash vaultspec-core spec hooks status ``` - **Approve this workspace’s hooks, then render them**: **Command** ```bash vaultspec-core spec hooks trust vaultspec-core spec hooks sync ``` - **Preview a render without writing**: **Command** ```bash vaultspec-core spec hooks sync --dry-run ``` - **Withdraw approval; the next sync removes what it rendered**: **Command** ```bash vaultspec-core spec hooks trust --revoke ``` --- ### vaultspec-core spec triggers **Usage synopsis** ```bash vaultspec-core spec triggers [OPTIONS] COMMAND [ARGS]... ``` Lifecycle triggers: shell commands bound to vaultspec’s own events, fired by the CLI rather than by your agent. Source files live in `.vaultspec/triggers/`. One event fires today, `config.synced`, after an all-provider `vaultspec-core sync` completes. Two earlier events were declared but never emitted and have been retired; a trigger bound to one is now reported rather than silently ignored. #### Subcommands - `list` (`--json`) - List this workspace’s lifecycle triggers. - `add [NAME] [--event EVENT] [--command CMD] [--body BODY] [--from-file FILE] [--force] [--dry-run]` - Add a new trigger. `--event` defaults to `config.synced`. - `show NAME` - Display a trigger’s source file. - `edit NAME [--editor EDITOR]` - Open a trigger in the configured editor. - `rename OLD_NAME NEW_NAME` - Rename an existing trigger atomically. - `remove NAME [--yes|--force]` - Delete a trigger. - `status` (`--json`) - Report trigger parse errors and unsupported events. - `run EVENT [--path PATH]` - Fire this workspace’s triggers for one lifecycle event. - `trust [NAME] [--revoke] [--json]` - Approve this workspace’s triggers to run their shell commands as you, or withdraw that approval. #### Trigger trust Triggers carry the same consent model as hooks, for the same reason and through the same machine-global ledger: a trigger file arrives with every clone, so approval is recorded outside the workspace and pinned to each file’s contents. `vaultspec-core sync` and `vaultspec-core spec triggers run` show you each untrusted trigger’s command and offer to remember your approval, but only at an interactive terminal. Approval is keyed by resolved path. Upgrading from a version that kept triggers in `.vaultspec/hooks/` relocates them, which drops their approval - run `vaultspec-core spec triggers trust` once to restore it. The migration says so when it moves them. The gateway’s `invoke` tool cannot reach `vaultspec-core spec triggers add`, `vaultspec-core spec triggers run`, or `vaultspec-core spec triggers trust`. #### Examples - **Add a trigger that checks the vault after every sync**: **Command** ```bash vaultspec-core spec triggers add post-sync-check --command "vaultspec-core vault check all" ``` - **List this workspace’s triggers and their trust state**: **Command** ```bash vaultspec-core spec triggers list ``` - **Fire the triggers bound to the sync event**: **Command** ```bash vaultspec-core spec triggers run config.synced ``` - **Report parse errors and events that no longer exist**: **Command** ```bash vaultspec-core spec triggers status ``` - **Rename a trigger, then withdraw its approval**: **Command** ```bash vaultspec-core spec triggers rename post-sync-check vault-gate vaultspec-core spec triggers trust vault-gate --revoke ``` --- ### vaultspec-core spec gitignore **Usage synopsis** ```bash vaultspec-core spec gitignore [OPTIONS] COMMAND [ARGS]... ``` #### Subcommands - `disable` (`--json`) - Decline the vaultspec-managed `.gitignore` block for the whole project. - `enable` (`--json`) - Allow management of the `.gitignore` block for the whole project. `disable` records `blocks.gitignore = false` in `.vaultspec/workspace.json`; commit this file to share the policy. `enable` clears that override. Neither command edits `.gitignore`; remove an existing managed block yourself if needed. Install and upgrade create or restore the managed block unless project policy disables it. Ordinary sync leaves a manually removed block absent on that machine. To restore it, enable management and run `vaultspec-core install`. Both commands exit zero when the requested policy already holds. #### Options - `--json` (default off) - Emit the result as JSON. - `--target DIR` (`-t`, default discovered) - Act on a directory other than the current one. #### Examples - **Decline the block for the whole project**: **Command** ```bash vaultspec-core spec gitignore disable ``` - **Resume managing it**: **Command** ```bash vaultspec-core spec gitignore enable ``` ### vaultspec-core spec gitattributes **Usage synopsis** ```bash vaultspec-core spec gitattributes [OPTIONS] COMMAND [ARGS]... ``` #### Subcommands - `disable` (`--json`) - Decline the vaultspec-managed `.gitattributes` block for the whole project. - `enable` (`--json`) - Allow management of the `.gitattributes` block for the whole project. These controls share the [availability and policy behavior of `vaultspec-core spec gitignore`](), using `blocks.gitattributes` in `.vaultspec/workspace.json`. The [default entries]() control line endings and union merging of execution ledgers. #### Options - `--json` (default off) - Emit the result as JSON. - `--target DIR` (`-t`, default discovered) - Act on a directory other than the current one. #### Examples - **Disable managed Git attributes for the project**: **Command** ```bash vaultspec-core spec gitattributes disable ``` - **Resume managing it**: **Command** ```bash vaultspec-core spec gitattributes enable ``` ### vaultspec-core spec precommit **Usage synopsis** ```bash vaultspec-core spec precommit [OPTIONS] COMMAND [ARGS]... ``` #### Subcommands - `disable` (`--json`) - Decline vaultspec-managed `.pre-commit-config.yaml` scaffolding. - `enable` (`--json`) - Restore vaultspec-managed `.pre-commit-config.yaml` scaffolding. - `migrate` (`--remove-yaml`, `--dry-run`, `--json`) - Transplant the canonical vaultspec hooks into `prek.toml`. `disable` records `hooks.pre_commit = false` in `.vaultspec/workspace.json` to stop YAML scaffolding. Commit this file to share the policy; `enable` clears the override. Neither command changes existing configuration or uninstalls an active Git hook. Install and upgrade can recreate missing YAML unless `--skip precommit`, project policy, or an owning `prek.toml` prevents scaffolding. Ordinary sync leaves manually deleted YAML absent. After enabling management, run `vaultspec-core install` to restore it. With this policy disabled, reconciled ignore entries include `/.pre-commit-config.yaml`. Ignoring a file does not untrack an existing committed copy. Both policy commands exit zero when the requested state already holds. When `prek.toml` owns the hook boundary, sync no longer scaffolds `.pre-commit-config.yaml` and prek silently ignores it. `migrate` renders the canonical hook set into a vaultspec-managed block inside `prek.toml`. It is idempotent - re-running with the hooks already present is a no-op - and the superseded YAML config is never deleted unless `--remove-yaml` is passed and the canonical hooks are verified present in `prek.toml`. #### Options - `--remove-yaml` (default off, `migrate` only) - Also delete the superseded `.pre-commit-config.yaml` once the canonical hooks are verifiably present in `prek.toml`. - `--dry-run` (default off, `migrate` only) - Preview without writing. - `--json` (default off) - Emit the result as JSON. #### Examples - **Stop vaultspec from ever writing the hook config again**: **Command** ```bash vaultspec-core spec precommit disable ``` - **Restore managed scaffolding**: **Command** ```bash vaultspec-core spec precommit enable ``` - **Preview the transplant without writing**: **Command** ```bash vaultspec-core spec precommit migrate --dry-run ``` - **Transplant hooks, then remove the superseded YAML**: **Command** ```bash vaultspec-core spec precommit migrate --remove-yaml ``` ### vaultspec-core spec mcps **Usage synopsis** ```bash vaultspec-core spec mcps [OPTIONS] COMMAND [ARGS]... ``` Manage canonical MCP server definitions in `.vaultspec/mcps/*.json` and reconcile them into provider-native enrollment files. Provider targets are `all`, `claude`, `antigravity`, and `codex`; scopes are `project`, `local`, and `user`. Unsupported provider/scope combinations fail instead of writing to a substitute location. Use top-level `vaultspec-core sync` for a complete refresh across all provider-facing outputs. #### Subcommands - `vaultspec-core spec mcps list` - List all registered MCP server definitions. - `vaultspec-core spec mcps trust [PROVIDER]` (`--scope SCOPE`, `--target PATH`, `--source-from-cwd`, `--revoke`) - Approve exact MCP commands after review and confirmation at an interactive terminal. `--source-from-cwd` approves definitions from the current working directory for a top-level `vaultspec-core sync` invocation with a `--target` destination. `--revoke` withdraws existing grants; uninstall removes deployed entries. - `vaultspec-core spec mcps status [PROVIDER]` (`--scope SCOPE`, `--json`, `--target PATH`) - Inspect enrollment and ownership state without starting or probing MCP servers. - `vaultspec-core spec mcps add --name NAME [--config JSON] [--force]` - Add a new custom MCP server definition. - `vaultspec-core spec mcps remove NAME [--force]` - Remove an MCP server definition (`--force` skips confirmation). - `vaultspec-core spec mcps sync [PROVIDER]` (`--scope SCOPE`, `--dry-run`, `--force`, `--prune`, `--json`, `--target PATH`) - Reconcile canonical definitions into provider-native enrollment. - `vaultspec-core spec mcps uninstall [PROVIDER]` (`--scope SCOPE`, `--dry-run`, `--force`, `--json`, `--target PATH`) - Remove only vaultspec-owned provider-native enrollment. `vaultspec-core spec mcps status` exits `0` only when MCP config status is `ok`, otherwise `1`. It checks config health only and does not start or probe MCP server processes. The default provider is `all` and the default scope is `project`. `--force` on `sync` explicitly adopts or replaces same-name external enrollment; `--prune` removes owned enrollment whose canonical source was deleted. `uninstall` preserves canonical definitions and externally owned host entries. #### Examples - **Verify the health and synchronization status of MCP server definitions**: **Command** ```bash vaultspec-core spec mcps status ``` - **List all registered MCP server definitions**: **Command** ```bash vaultspec-core spec mcps list ``` - **Sync registered MCP definitions to deployment files**: **Command** ```bash vaultspec-core spec mcps sync ``` - **Inspect Codex project enrollment**: **Command** ```bash vaultspec-core spec mcps status codex --scope project ``` - **Preview removal of vaultspec-owned Claude user enrollment**: **Command** ```bash vaultspec-core spec mcps uninstall claude --scope user --dry-run ``` - **Register a new custom MCP server definition**: **Command** ```bash vaultspec-core spec mcps add --name sqlite-mcp --config "{\"command\": \"npx\", \"args\": [\"@modelcontextprotocol/server-sqlite\"]}" ``` - **Remove a registered MCP server definition**: **Command** ```bash vaultspec-core spec mcps remove sqlite-mcp --force ``` ### vaultspec-core spec reference **Usage synopsis** ```bash vaultspec-core spec reference generate [OPTIONS] ``` Regenerate the generator-owned regions of the bundled machine-facing CLI reference (`src/vaultspec_core/builtins/reference/cli.md`) from the live Typer command surface. The reference is a hybrid of hand-written prose and generator-owned zones delimited by `vaultspec:generated` HTML-comment markers; this verb rewrites only the managed zones and leaves the prose untouched. - `--check` (default off) - Render in memory, diff against the committed file, exit non-zero on mismatch without writing. - `--json` (default off) - Emit machine-readable output. Default (write) mode rewrites the bundled reference in place when the managed regions have drifted. `--check` mode is the CI and pre-commit entry point: it renders into memory, prints a unified diff on mismatch, and exits non-zero, leaving the file untouched (exit 0 when already in sync). - **Refresh the bundled reference after a command or flag change**: **Command** ```bash vaultspec-core spec reference generate ``` - **Verify the bundled reference is up to date (CI gate)**: **Command** ```bash vaultspec-core spec reference generate --check ``` **Usage synopsis** ```bash vaultspec-core spec reference snapshot [OPTIONS] ``` Maintain `src/vaultspec_core/builtins/reference/published-surface.json`, the record of the command and MCP tool surface of the latest published release - not a draft, not a prerelease. The generated unreleased-surface regions of these documents are the difference between that record and the live surface, which is why no version caveat in them is hand-written. - `--emit` (default off) - Print this build’s own surface as a snapshot document to stdout and write nothing. - `--verify FILE` - Compare a surface document (from `--emit`) against the committed record; exit non-zero when they differ. - `--record FILE` - Write a surface document (from `--emit`, run inside the latest published release’s distribution) as the committed record; requires `--development`. - `--development` (default off) - Explicitly authorize recording from a trusted development invocation. MCP callers cannot authorize reference maintenance. - `--json` (default off) - Emit machine-readable output. The record is never captured from a source tree. After publication, the release’s own distribution is installed in isolation and read back with `--emit`, and `--record` writes that document; a malformed document is refused and the record left untouched. `--verify` proves the committed record is what that distribution exposes. Without a mode flag the verb only reports the recorded version and counts. The three modes are mutually exclusive. - **Report what the committed record holds**: **Command** ```bash vaultspec-core spec reference snapshot ``` - **Read a published distribution’s own surface back, in an isolated install**: **Command** ```bash uv run --isolated --no-project --with vaultspec-core \ vaultspec-core spec reference snapshot --emit > surface.json ``` - **Record that surface as the committed record**: **Command** ```bash vaultspec-core spec reference snapshot --record surface.json --development ``` - **Prove the committed record matches a published distribution**: **Command** ```bash vaultspec-core spec reference snapshot --verify surface.json ``` ## Migration commands Group command: `vaultspec-core migrations [OPTIONS] COMMAND [ARGS]...` Every migration subcommand also accepts the global `--target / -t DIR` and `--json` flags. The migration registry runs every entry whose target version exceeds the workspace manifest’s `vaultspec_version`, then bumps the manifest version on success. Migrations are idempotent, and because they relocate, rewrite, and delete tracked `.vault/` documents they only run for a caller that asked to change the workspace: - `vaultspec-core install --upgrade`, `vaultspec-core migrations run`, and `vaultspec-core vault repair` run the **whole registry** - converging is what you invoked them for. - `vaultspec-core vault add`, `vaultspec-core vault feature index` and the MCP `create` tool run **only the entries that decide where their own write lands**. Writing a document into a stale layout is what leaves one feature with two tracked indexes, so they fix that; they never rewrite or delete a document you did not name. That second rule is deliberately narrow. A verb that writes one document has no standing to rewrite forty-seven others, so returning to a long-untouched workspace and adding one ADR converges the layout and leaves everything else exactly where it was. The entries that fold and remove documents wait for one of the three commands above. Every other command, including every read (`vaultspec-core vault list`, `vaultspec-core vault graph`, `vaultspec-core vault check`, and the MCP query tools), leaves the workspace exactly as it finds it. Anything left pending is reported rather than silently deferred: any command that observes a stale workspace logs a warning naming the outstanding entries. Run `vaultspec-core migrations status` to see them, and `vaultspec-core migrations run` to apply them - it names every document it is about to remove and asks before it does. ### Where deleted documents go Some migrations remove `.vault/` documents - the execution-record folds replace a folder of per-Step records with one ledger, and that consolidation is not expressible as an additive rewrite. Before any of them unlinks a file, a byte-identical copy of it is written to: **Captured output** ```text .vault/.trash/-/ ``` Each snapshot directory also carries a `RESTORE.txt` naming every copy’s original location, so a file can be identified by the path it had rather than by its name alone. - **How long they stay: forever.** Nothing in vaultspec ever deletes a snapshot. A safety net that expires on a timer is not a safety net, and for a document authored since the last commit - or in a workspace whose `.vault/` is not in git at all - the snapshot is the only copy that exists. The directory is listed in the managed `.gitignore` block, so it never enters the repository. Delete it yourself when you have decided the documents are not coming back; `.vault/.trash/` is always safe to remove in whole or in part. - **How to get one back: copy it.** There is no restore command, because a snapshot is a plain directory of unmodified files and copying one back is the whole operation. Read `RESTORE.txt` for the destination, then: **Command** ```bash cp .vault/.trash/20260517-120000-exec_ledger_only/exec/2026-05-17-demo/2026-05-17-demo-P01-S01.md .vault/exec/2026-05-17-demo/ ``` - **If the copy cannot be written, nothing is deleted.** A full disk or an unwritable `.vault/` fails the migration before the first unlink and leaves the manifest version alone, so the next run re-attempts. Deleting because the backup failed is the one outcome worse than not deleting. Preview a deletion before it happens with `vaultspec-core migrations run --dry-run`, which enumerates every path the run would remove and changes nothing. The list comes from the same planner the real run applies, so it is the run rather than a description of one. ### vaultspec-core migrations status **Usage synopsis** ```bash vaultspec-core migrations status [OPTIONS] ``` List registered migrations and which entries are pending against the current workspace manifest. Read-only; never mutates. #### Options - `--target DIR` (`-t`, default discovered) - Inspect a workspace other than the current directory. - `--json` (default off) - Emit status, registered list, and pending list as JSON. Exit codes: `0` when up to date or workspace has no manifest, `1` when migrations are pending. #### Examples - **List all registered schema migrations and check for pending entries**: **Command** ```bash vaultspec-core migrations status ``` --- ### vaultspec-core migrations run **Usage synopsis** ```bash vaultspec-core migrations run [OPTIONS] ``` Apply every pending migration in version order and bump the manifest’s `vaultspec_version`. A migration that fails stops the run and leaves the manifest unchanged so the next invocation re-attempts it. #### Options - `--target DIR` (`-t`, default discovered) - Migrate a workspace other than the current directory. - `--dry-run` (default off) - List every document the pending migrations would delete and change nothing. - `--yes` (`-y`, default off) - Skip the confirmation prompt for deletions. - `--json` (default off) - Emit per-entry summaries and counts as JSON. When the pending migrations would delete documents, an interactive terminal is asked to confirm unless `--yes` is passed. Non-interactive callers - CI, `--json`, the MCP server, a piped or closed stdin - are warned and proceed rather than waiting for input: the registry also runs from `vaultspec-core install --upgrade`, `vaultspec-core vault repair`, and the authoring verbs that let the schema decide where they write (`vaultspec-core vault add`, `vaultspec-core vault feature index`, and the MCP `create` tool), so refusing here would only push a blocked script onto a trigger that asks nothing at all. Either way, every removed document is copied into `.vault/.trash/` first. Exit codes: `0` on success (including the no-pending no-op and every dry run), `1` if any migration failed or an operator declined the deletion. #### Examples - **Preview every document the pending migrations would delete**: **Command** ```bash vaultspec-core migrations run --dry-run ``` - **Execute all pending schema migrations and upgrade the workspace**: **Command** ```bash vaultspec-core migrations run --yes ``` --- ## Config commands Group command: `vaultspec-core config [OPTIONS] COMMAND [ARGS]...` Manage local project configuration settings stored in `.vaultspec/config.toml` at the workspace root. Every config subcommand also accepts the global `--target / -t DIR` and `--json` flags. ### vaultspec-core config get **Usage synopsis** ```bash vaultspec-core config get [OPTIONS] KEY ``` Read a local configuration value. #### Options - `--json` (default off) - Emit machine-readable output. #### Examples - **Retrieve the local project-level editor setting**: **Command** ```bash vaultspec-core config get editor ``` ### vaultspec-core config set **Usage synopsis** ```bash vaultspec-core config set [OPTIONS] KEY VALUE ``` Write a local configuration value. Supported keys: `editor`. The `editor` value is validated on write and again every time it is used, so a file written by an older version or edited by hand cannot slip past the check. See which editors are accepted. Reading and clearing keep working on a value the edit path refuses - `vaultspec-core config get editor`, `vaultspec-core config list`, and `vaultspec-core config unset editor` are all unaffected - so an inherited setting can always be inspected and removed. #### Options - `--json` (default off) - Emit machine-readable output. #### Examples - **Configure the local project-level editor command to Zed**: **Command** ```bash vaultspec-core config set editor zed ``` ### vaultspec-core config unset **Usage synopsis** ```bash vaultspec-core config unset [OPTIONS] KEY ``` Clear a local configuration entry. #### Options - `--json` (default off) - Emit machine-readable output. #### Examples - **Clear the local project-level editor configuration**: **Command** ```bash vaultspec-core config unset editor ``` ### vaultspec-core config list **Usage synopsis** ```bash vaultspec-core config list [OPTIONS] ``` Enumerate all known configuration entries and current values. #### Options - `--json` (default off) - Emit machine-readable output. #### Examples - **Enumerate all local project-level configuration settings and values**: **Command** ```bash vaultspec-core config list ``` --- ## Project coordination ### vaultspec-core project context **Usage synopsis** ```bash vaultspec-core project context [OPTIONS] OBJECTIVE ``` Collect recent Git activity, branches, worktrees, and optional GitHub issues and PRs to propose a bounded attention order for the developer’s objective. The command reads project state without changing repositories or trackers. Missing sources are reported as incomplete coverage. A configured TypeSafe key enables optional ranking; without a key, with `--no-hosted`, or after a service failure, deterministic ordering is used. #### Arguments - `OBJECTIVE` - The developer outcome to prioritize. #### Options - `--repo OWNER/REPO` - Read issues and PRs from this GitHub repository using `gh`. - `--previous FILE` - Reuse unchanged judgments from a previous JSON result for up to one hour. Input is limited to 64,000 bytes. - `--limit INTEGER` (default `5`, range `1..10`) - Maximum attention items returned. - `--no-hosted` - Disable hosted ranking even when a key is configured. - `--target DIR` (`-t`, default cwd) - Project directory to inspect. - `--json` - Emit structured observations, coverage, ordering, and available usage. #### Examples **Command** ```bash vaultspec-core project context "Finish the release and unblock active PRs" --no-hosted vaultspec-core project context "Prioritize today's work" --repo owner/project --json ``` ## Review context ### vaultspec-core review context **Command** ```bash vaultspec-core review context "Preserve caller contracts" --base main --candidate src/caller.py:20-70 --candidate tests/test_service.py:1-80 --json ``` Select supporting passages from an explicit Git review scope. This command reads repository state without running checks or producing a review verdict. A configured `VAULTSPEC_CORE_TYPESAFE_API_KEY` opts into sending the objective, bounded diff and candidate passages to TypeSafe. Missing credentials, rejected keys, timeouts and service failures preserve the supplied discovery order. #### Arguments and options - `OBJECTIVE` - Review behavior or constraint, 1..1,000 UTF-8 bytes. - `--base REF` - Required base commit reference. - `--candidate PATH[:START-END]` - Required tracked, repository-relative locator; repeat for 1..12 passages. A single line can use `PATH:LINE`. - `--head REF` - Read the target commit and its candidate content. Without this flag, read tracked working-tree changes, including staged changes. Untracked files are excluded and working-tree reads are not atomic. - `--limit INTEGER` - Return up to this many passages; default 3, range 1..6. - `--previous FILE` - Reuse identical-input judgments from a JSON result up to 128,000 bytes for at most one hour. A key must remain enrolled. Status `reused` does not claim current service connectivity. - `--no-hosted` - Disable hosted selection even with a configured key. - `--target DIR` (`-t`, default cwd) - Git repository root. - `--json` - Return the `vaultspec.review.context.v1` envelope. Each candidate is at most 120 lines and 4,000 UTF-8 bytes from a file up to 1 MB. Larger passages need narrower locators. Collection has a shared 10-second budget; hosted selection makes one batch with a 15-second budget. A diff exceeding 24,000 bytes or involving environment/private-key paths disables hosted selection. Candidate environment stores, conventional key files, symlinks and paths outside the repository are excluded. These path protections are not general secret scanning. The result carries verbatim selected passages and hashes, unselected locators, exclusions, diff scope, hosted status, usage and a reusable judgment. Source text is not rewritten by the model. Candidate exclusions and hosted failure exit 0 with reasons; invalid input or an unavailable Git scope exits 2. The existing MCP `discover`/`invoke` gateway exposes the same command; repeatable candidate flags accept a JSON array. Keep the full diff and governing decisions in the review. Expand omitted context when needed, share selections across reviewers, and reuse applicable verification results. Ranking is optional supporting evidence, not proof of correctness or complete coverage. ## Settings resolution One order holds for every setting, in every process kind (CLI, MCP server, and any package that imports vaultspec-core’s public resolvers). Earlier rungs win: 1. **Invocation** - a CLI flag or an explicit programmatic override for that call. 2. **Session environment** - the process’s own environment. For a setting the framework shares, a companion package’s scoped name is read first - `VAULTSPEC__ROOT`, `VAULTSPEC__LOG_LEVEL`, `VAULTSPEC__STDIO_WATCHDOG` - and falls back to the framework name behind it - `VAULTSPEC_TARGET_DIR`, `VAULTSPEC_LOG_LEVEL`, `VAULTSPEC_STDIO_WATCHDOG` - when it supplies nothing. A credential never chains. 3. **Project store** - `.vaultspec/.env`, for the persistable settings only, written only by an explicit import; see local environment provisioning. 4. **Workspace `.env`** - credentials only, under the gate below. 5. **Persisted configuration** - the single store that owns the key: `.vaultspec/config.toml` or `.vaultspec/workspace.json`. 6. **Derived and external defaults** - `pyproject.toml` mode detection, or a third-party convention with a product equivalent, such as `VISUAL` then `EDITOR`. 7. **The shipped default**, declared once in the table below. The workspace `.env` is `/.env`. It is never found by walking up from the working directory or from where the package is installed, and no variant (`.env.local` and the like) is read. It supplies a credential - today only `VAULTSPEC_CORE_TYPESAFE_API_KEY` - one name at a time, and only when both hold: the running interpreter lives inside the workspace (its project virtual environment), and the owning package’s own resolved install mode for that workspace is `dependency` or `dev`. A `uvx` invocation or a globally installed tool (such as a uv tool, a pipx install, or a release binary) pointed at a fresh clone never reads that repository’s `.env`. No `.env` file is ever committed, this one or any other: dotenv files hold secrets. The managed `.gitignore` block ignores every `.env` and `.env.*` file at any depth, leaving only `.env.example` templates committable; the commit gate refuses one that is force-added; and `vaultspec-core doctor` warns when the Git index already tracks one. An ignore rule cannot untrack a file, so a tracked `.env` needs `git rm --cached` and every secret it held rotated. Booleans read one vocabulary: `1`, `true`, `yes` or `on` against `0`, `false`, `no` or `off`, case-folded and stripped. A blank value is unset, not off, and falls through to the next rung. An invalid value for a product-owned variable refuses the process and names the variable, the value and the expected shape. The stdio watchdog is the one protective switch that instead warns and stays armed: refusing to start is not a safer outcome than running guarded. ## Environment variables vaultspec-core owns the `VAULTSPEC_` variables below and honours a few external conventions, listed after them. Environment variables override the default and are overridden by the invocation. - `VAULTSPEC_TARGET_DIR` (path, default discovered) - Root workspace directory (where `.vault/` and `.vaultspec/` live), for every process kind: the CLI, the MCP server, and any importing package. Equivalent to `--target` on the CLI. Ranked below an explicit `--target` and above discovery from the working directory; a directory that does not exist is refused rather than discovered past. - `VAULTSPEC_DOCS_DIR` (str, default `.vault`) - Vault directory name. - `VAULTSPEC_INDEX_DIR` (str, default `index`) - Name of the subdirectory inside the vault that holds the auto-generated feature indexes (`.index.md`). - `VAULTSPEC_FRAMEWORK_DIR` (str, default `.vaultspec`) - Framework directory name. - `VAULTSPEC_CLAUDE_DIR` (str, default `.claude`) - Claude tool directory name. - `VAULTSPEC_GEMINI_DIR` (str, default `.gemini`) - Gemini tool directory name. - `VAULTSPEC_ANTIGRAVITY_DIR` (str, default `.agents`) - Antigravity directory name. - `VAULTSPEC_IO_BUFFER_SIZE` (int, default `8192`) - I/O read buffer size in bytes. - `VAULTSPEC_TERMINAL_OUTPUT_LIMIT` (int, default `1000000`) - Subprocess stdout capture limit in bytes. - `VAULTSPEC_LOCK_TIMEOUT_SECONDS` (float, default `120.0`) - Total seconds a single advisory-lock acquisition may wait before failing with a diagnosable timeout instead of blocking indefinitely. Covers the in-process and cross-process layers combined. Raise it if a large corpus or a slow network volume makes legitimate contention exceed the budget. - `VAULTSPEC_EDITOR` (str, unset by default) - Editor command every surface that opens an editor consults - the edit verbs (`vaultspec-core spec {rules|skills|agents} edit`) and interactive creation of a rule, skill, agent, or trigger alike. Read after the `--editor` flag and before the project config key, `VISUAL` and `EDITOR`; `vi` is the last rung when none of them answers. Unlike the flag and the config key, an editor named in the environment is not restricted to the recognised set; see which editors are accepted. - `VAULTSPEC_CORE_TYPESAFE_API_KEY` (secret, unset by default) - TypeSafe API key for hosted vault search (`vaultspec-core vault search` and the MCP `search` tool), ADR wording checks, and optional project and review context ranking. Read from the process environment, then the provisioned `.vaultspec/.env` project store. A workspace-root `.env` supplies it only when both omit it, and then only under the credential gate above. Only this one variable is read from that file. Blank counts as unset at every source. The generic `TYPESAFE_API_KEY` does not enable it. The key never appears in output; `vaultspec-core status` reports only whether one is configured and from which source. - `VAULTSPEC_LOG_LEVEL` (str, default `WARNING` for the CLI, `INFO` for the MCP server) - Root log level when neither `--debug` nor `--verbose` is given, for example `DEBUG`, `INFO`, or `WARNING`. An unknown name is refused. - `VAULTSPEC_JSON_PRETTY` (bool, unset by default) - Indents `--json` output. A true word turns it on; unset, blank or a false word leaves the envelope one compact line. - `VAULTSPEC_NO_HINTS` (bool, unset by default) - Set to a true word to drop the `Next actions` block the commands print after their report. Equivalent to `--no-hints`. Unset, blank or a false word leaves the hints in place. - `VAULTSPEC_NON_INTERACTIVE` (bool, unset by default) - Set to a true word to declare that no operator is watching: repository triggers awaiting approval are skipped instead of prompted for. Outranks `CI` in both directions, so a wrapper script running under CI with somebody watching can say so with `VAULTSPEC_NON_INTERACTIVE=0`. - `VAULTSPEC_STDIO_WATCHDOG` (bool, unset by default; armed) - Lifetime watchdog for the MCP server, on by default. A false word disables it, which leaves the server to exit on stdin EOF alone. Unset, blank, or an unrecognised word leaves it armed: it is a protective switch, so a typo warns rather than turning the guard off. Read by `vaultspec-core-mcp` rather than by the CLI; see the [MCP reference](). - `VAULTSPEC_MCP_GATEWAY_INVOCATION` (str, unset by default) - Internal, set by vaultspec-core itself: the MCP invoke gateway sets it on every CLI process it spawns. Any non-empty value marks the process as having no terminal, so it refuses to open an editor. Not an operator setting. vaultspec-core also honours these external variables. It does not own them. - `CI` (presence) - Set by CI systems. Same effect as `VAULTSPEC_NON_INTERACTIVE`. - `NO_COLOR` (non-empty string) - Set to any non-empty value to disable colour in console output, as the no-color.org convention defines it. Set but empty is not a request for monochrome output. - `GIT_INDEX_FILE` (presence) - Set by git for every commit hook it runs. While it is set, commands print no `Next actions` block and no `--fix` suggestion for a finding, because hook output is often acted on without review. - `COLUMNS` (int) - Console width. When unset, the width is read from the terminal once at startup. - `VISUAL`, `EDITOR` (str) - Editor commands the edit verbs consult after `VAULTSPEC_EDITOR` and the project config key, in that order. - `CLAUDE_CONFIG_DIR` (path, default home directory) - Claude Code’s configuration home, whose `.claude.json` holds user-scope MCP servers. - `CODEX_HOME` (path, default `~/.codex`) - Codex’s home, whose `config.toml` holds user-scope MCP servers. ## See also - [Framework manual]() - Development workflow, skills, and customization. - [MCP reference]() - MCP server tools, setup, and configuration. For bug reports and feature requests, open an issue on the [vaultspec-core issue tracker]().