# Vaultspec

> Vaultspec is a coding harness: it implements a structured coding workflow focused on #features, decision records and the documents grounding them. It bundles rules, agents, skills, and tools to author the documents that describe and track a feature's development.

Actively developed. MIT licensed.

## The harness

- [vaultspec-core](https://github.com/nevenincs/vaultspec-core):
  Decision-driven harness for coding agents, and humans.
- [vaultspec-rag](https://github.com/nevenincs/vaultspec-rag):
  The semantic search component for vault and code. Indexing and search require an
  NVIDIA GPU with CUDA on Linux or Windows, or Apple silicon with MPS. CPU-only and
  AMD inference are not supported.

## Get started

- [Install vaultspec-core](https://vaultspec.neve.md/docs/core/installation.html)
- [Install vaultspec-rag](https://vaultspec.neve.md/docs/rag/installation.html)
- [Start RAG, index the project, and run a search](https://vaultspec.neve.md/docs/rag/getting-started.html)
- [Run a feature with your coding agent](https://vaultspec.neve.md/docs/guides/workflow.html)

## Interfaces

Records are Markdown files in your repository; open them in an editor or Obsidian.

[vaultspec-dashboard](https://github.com/nevenincs/vaultspec-dashboard) is a separate
project building a dedicated frontend on the same files. It is in early development, in
the open.

## Docs

[Download the site-authored guides](https://vaultspec.neve.md/llms-full.txt) as one text file.
Imported manuals remain on the documentation site with source and compatibility notices.

- [Documentation home](https://vaultspec.neve.md/docs/)
- [Concepts](https://vaultspec.neve.md/docs/concepts.html)
- [CLI guide](https://vaultspec.neve.md/docs/guides/cli.html)
- [MCP guide](https://vaultspec.neve.md/docs/guides/mcp.html)
- [Semantic search quickstart](https://vaultspec.neve.md/docs/rag/getting-started.html)
- [Core documentation](https://vaultspec.neve.md/docs/core/index.html)
- [RAG documentation](https://vaultspec.neve.md/docs/rag/index.html)
- [vaultspec-core on PyPI](https://pypi.org/project/vaultspec-core/)
- [vaultspec-rag on PyPI](https://pypi.org/project/vaultspec-rag/)

---

# The Pages Written for This Site

This section carries the full text of the 8 pages written for
this documentation site. It is not the whole site. The other
24 pages are vendored copies of the vaultspec-core and
vaultspec-rag manuals - the two CLI references, the search product's
configuration, indexing, service-mode and query pages, and the framework and
syntax manuals - and they are readable only at https://vaultspec.neve.md/docs/. Each
is served under a notice naming the file and upstream commit it was taken
from, and where the copied text disagrees with the shipped tool that notice
says what the tool actually does. Reproducing the pages here would drop the
corrections, so this file links to them instead: https://vaultspec.neve.md/docs/core/
and https://vaultspec.neve.md/docs/rag/.

## Documentation Home

```{raw} html
<div class="vs-docs-band"></div>
```

Vaultspec adds a decision-led development workflow and semantic codebase search to your coding agent.

## Install

Install both required components:

1. [Install vaultspec-core](core/installation.md).
2. [Install vaultspec-rag](rag/installation.md).
3. [Start RAG, index the project, and run a search](rag/getting-started.md).

## Use the workflow

Open your configured coding agent and use one of these prompts:

> Use vaultspec-research to investigate adding full-text search to the API. Use the feature tag search-api.

> Execute the approved plan for search-api.

> Use vaultspec-code-review to review the completed search-api implementation.

The agent pauses for approval before it records the decision and before it executes the plan. [Read the operating model](concepts.md) for the records and approval points.

## Command references

- [vaultspec-core CLI reference](core/cli.md): every Core command, option, outcome, and exit code.
- [vaultspec-rag CLI reference](rag/cli.md): every RAG command, option, outcome, and exit code.

## Advanced

- [Core document syntax](core/syntax.md)
- [Core MCP tools](core/mcp.md)
- [Review and correctness](core/correctness.md)
- [RAG query craft](rag/query-craft.md)
- [RAG configuration](rag/configuration.md)
- [RAG service operation](rag/service-mode.md)
- [RAG automation](rag/automation.md)
- [RAG storage maintenance](rag/storage-maintenance.md)
- [RAG preprocessing hooks](rag/preprocessing-hooks.md)

(when-something-goes-wrong)=
## Troubleshooting

- Core installation or validation: [check the workspace and records](core/verification.md).
- Missing or stale results: [verify the RAG service and index](rag/verification.md).
- Installation or GPU failures: [RAG installation troubleshooting](rag/installation.md#when-something-goes-wrong).

```{toctree}
:maxdepth: 2
:hidden:
:caption: Start

core/installation
rag/installation
rag/getting-started
concepts
guides/workflow
guides/cli
guides/mcp
```

```{toctree}
:maxdepth: 2
:hidden:
:caption: Reference

core/cli
rag/cli
core/index
rag/index
```

---

## The Pipeline and Its Vocabulary

(the-words-in-one-place)=
Vaultspec stores the reasoning and verification for a feature beside its code. One feature tag connects the records.

| Stage | Record | Purpose | Approval |
| --- | --- | --- | --- |
| Research | `.vault/research/` or `.vault/reference/` | Evidence, existing behavior, and options | Confirm the evidence before a decision |
| Decision | `.vault/adr/` | Chosen approach, rejected alternatives, and consequences | Approve before planning |
| Plan | `.vault/plan/` | Ordered implementation steps and verification | Approve before execution |
| Execute | `.vault/exec/` | Files changed and verification evidence | Follow the approved plan |
| Review | `.vault/audit/` | Scope, findings, and recommendations | Resolve blocking findings |

Feature indexes under `.vault/index/` are generated. Runtime state under `.vault/data/` is local and must not be committed.

## What you approve

Two decisions are yours, and the agent stops for both: the architecture decision before anything is planned, and the plan before anything is built. Approve a decision when it matches the requirement, and reject an ADR that leaves one unresolved.

The review at the end is a separate gate. Record validation checks structure and links, so it can pass over an implementation nobody has proved.

## Find the current state

```bash
vaultspec-core status search-api
```

## Where to go next

- [Run a feature from research to review](guides/workflow.md) - the three prompts and the two approvals, stage by stage.
- [Core CLI reference](core/cli.md) - exact commands and advanced plan management.
- [Document syntax](core/syntax.md) - for authoring records by hand.

---

## One Feature, End to End

The ordinary workflow is three prompts and two approval decisions. Replace `search-api` with one feature tag throughout.

(research-the-problem)=
## Research and decide

> Use vaultspec-research to investigate adding full-text search to the API. Use the feature tag search-api.

Read the evidence and alternatives. Ask for corrections or approve the research and architecture decision. Do not approve an ADR that leaves a requirement unresolved.

## Approve and execute the plan

Read the proposed plan. Check its scope, ordering, and verification. Approve it, then ask:

> Execute the approved plan for search-api.

Check progress without changing the vault:

```bash
vaultspec-core status search-api
```

## Review

> Use vaultspec-code-review to review the completed search-api implementation.

Read the audit with the final code diff. Resolve blocking findings before accepting the feature. Record checks validate structure and links; they do not prove correctness or require an audit.

## Manual and advanced operation

Use the [vaultspec-core CLI reference](../core/cli.md) to create records, edit plan structure, resolve branch collisions, rename or archive features, and automate checks. Use [review guidance](../core/correctness.md) for the correctness gate.

(make-the-check-a-gate)=
For commit and continuous-integration gates, use the [Core check command reference](../core/cli.md#vaultspec-core-vault-check).

## Where to go next

- [How Vaultspec works](../concepts.md) - the records each stage writes and who approves them.
- [Driving the vault from the command line](cli.md) - the same operations without an agent.
- [Reaching Vaultspec from your agent](mcp.md) - the same operations over MCP.

---

## Use the command line

Run commands from your repository root. Use the [command prefix for your installation](../core/installation.md#how-you-run-it-afterwards) with the commands shown here.

<p id="if-your-agent-has-no-skills"></p>

This page covers the operations you run yourself. To run a complete feature through your coding agent, follow the [feature workflow](workflow.md).

<p id="orient-before-you-do-anything"></p>

## Check progress

Run `status` for a read-only overview of in-flight plans, completion, next open steps, and recent changes:

```bash
vaultspec-core status
```

If a feature has a plan, narrow the report to its tag. Replace `notes-search` with your feature's tag:

```bash
vaultspec-core status notes-search
```

The report links execution evidence; it does not prove the implementation is correct. See the [status reference](../core/cli.md#vaultspec-core-status) for output details and [workspace verification](../core/verification.md) for checks.

<p id="create-documents-never-hand-write-them"></p>

## Create documents

Create a research document. Replace `payment-retries` with your feature tag and
`"Payment retry options"` with your title:

```bash
vaultspec-core vault add research --feature payment-retries --title "Payment retry options"
```

```text
Next action:
  Define an Architecture Decision Record (ADR) for your research
    vaultspec-core vault add adr --feature payment-retries --related 2026-09-05-payment-retries-research
Created: .vault/research/2026-09-05-payment-retries-research.md
```

Captured on `0.1.73`. The `Created` path is absolute in the real output and
shortened here. Supplying `--title` is what keeps the run quiet: without it the
scaffolder reports `WARNING  Potential unhydrated placeholder found in
template: {topic}` as it writes.

The command assigns the filename, frontmatter, and tags. Open the file named in
`Created` and write its body using the [research guidance](workflow.md#research-and-decide).

Complete the research before running the command under `Next action`. That command
creates an architecture decision record (ADR) linked to your research file.

To create another research document for the same feature, add `--topic backoff`.
See the [creation reference](../core/cli.md#vaultspec-core-vault-add) for other
document types and options, and [document syntax](../core/syntax.md) for fields
maintained by the CLI.

<p id="work-a-plan"></p>

## Edit a plan

Start with an existing plan in `.vault/plan/` with `tier: L2`. For other tiers,
restructuring, or removal, see the [plan command reference](../core/cli.md#vaultspec-core-vault-plan).
That reference writes the plan argument the other way round, as a full
`.vault/plan/...md` path after the flags rather than a stem before them. Both
resolve, and so does a stem after the flags: measured on one plan on `0.1.73`,
all three added a Step. It is house style between a page written here and a page
copied from the harness, not two different commands.

Replace `PLAN` in each command with your plan's filename without `.md`. Adapt the
example titles and actions to your work.

1. Add a phase:

   ```bash
   vaultspec-core vault plan phase add PLAN --title "Retry the capture" --intent "Retry failed captures with exponential backoff."
   ```

2. Use the returned phase ID in place of `P01`. Replace `src/billing/retry.py` with
   the file path the step affects, then add the step:

   ```bash
   vaultspec-core vault plan step add PLAN --phase P01 --action "Retry a failed capture with exponential backoff" --scope "src/billing/retry.py"
   ```

3. After completing the work and verification, mark the step complete. Replace
   `P01.S01` with the returned step ID:

   ```bash
   vaultspec-core vault plan step check PLAN P01.S01
   ```

   This command marks the checkbox; it doesn't run tests.

## Reach a tier above L2

`L1` is Steps. `L2` adds Phases, `L3` adds Waves above them, and `L4` adds an
Epic frame above those. The tier is a frontmatter field, `tier: L4`, and the
containers it requires have to be present or the plan fails its own check.

There is one route to a plan above `L2`, and it is not the obvious one.
Scaffolding straight at the tier you want leaves a plan you cannot edit. `L1` is
the only tier whose scaffold passes its own check on the day it is written; at
`L2` the fresh document is already short a Phase, and the walkthrough above only
hides it by adding one in the next command:

```
vaultspec-core vault add plan --feature search-api --tier L4 --related 2026-09-05-search-api-adr
vaultspec-core vault plan check 2026-09-05-search-api-plan
```

```text
[error] PLAN010 line 0: L4 plan must contain an Epic intent block
  fix (manual): Reconcile the 'tier:' frontmatter field with the document's heading structure per the convention ADR's tier-driven structure rules.
[error] PLAN010 line 0: L4 plan must contain at least one Wave heading
  fix (manual): Reconcile the 'tier:' frontmatter field with the document's heading structure per the convention ADR's tier-driven structure rules.
```

The scaffold succeeds and the plan it wrote is invalid, at the moment it is
written: the tier in the frontmatter promises containers the document does not
have. Both missing containers are named on that first run, so the requirements
are not withheld from you. What the check will not do is create them, and adding
them by hand clears that list one entry at a time. The Wave is allowed - `Added
Wave W01` - and the Epic intent the same run already named is still outstanding:

```
vaultspec-core vault plan wave add --title "Index the corpus" --intent "Get documents into a searchable store." 2026-09-05-search-api-plan
vaultspec-core vault plan check 2026-09-05-search-api-plan
```

```text
[error] PLAN010 line 0: L4 plan must contain an Epic intent block
  fix (manual): Reconcile the 'tier:' frontmatter field with the document's heading structure per the convention ADR's tier-driven structure rules.
```

Filling a tier's containers by hand is not a route, it is doing one container at
a time what a single verb does in one call.

Build at `L2` and promote. Promotion is the verb that creates the containers, so
it asks for their titles rather than writing placeholders: run it without them
and it names exactly which are missing - `Cannot promote L2 -> L4 without the
following flag(s): --wave-title, --wave-intent`, and it adds that "the CLI does
not write TODO placeholders into plan documents".

It asks only for the containers it has to create, which is worth knowing before
you read the reference. Its promotion example passes `--epic-intent` and nothing
else, and that is correct for the plan it is written against: promoting an `L3`
to `L4` adds the Epic frame over a Wave that already exists, so there is no Wave
to name. The same command from `L2` has to create the Wave as well, and refuses
until you name it. Read the flags as a function of the distance you are moving
rather than of the tier you are moving to.

```
vaultspec-core vault plan tier promote --target L4 --epic-intent "Ship full-text search across the API, tracked as EPIC-412." --wave-title "Index the corpus" --wave-intent "Get documents into a searchable store." 2026-09-05-search-api-plan
```

```text
Tier promoted to L4. (Preserved 3 unknown blocks)
```

That plan passes `vault plan check` with exit `0`, and what it wrote is:

```markdown
## Epic intent

Ship full-text search across the API, tracked as EPIC-412.

## Wave `W01` - Index the corpus

Get documents into a searchable store.

### Phase `W01.P01` - Tokenizer

Choose and wire the tokenizer.

- [ ] `W01.P01.S01` - Wire the tokenizer into the index writer; `src/search/index.py`.
```

The Epic intent is a section, not a frontmatter field, and it is where an
external tracker reference belongs. Each container carries its intent as the
paragraph under its heading. And the identifiers lengthen as the tiers nest:
the Step that was `S01` at `L1` is `W01.P01.S01` here, because a Step is
addressed by its whole path once there is more than one container above it.

Demotion is the same verb backwards, and it is worth running once before you
need it. It removes the containers above the target tier and reports what it
kept:

```
vaultspec-core vault plan tier demote --target L2 2026-09-05-search-api-plan
vaultspec-core vault plan check 2026-09-05-search-api-plan
```

```text
Tier demoted to L2. (Preserved 3 unknown blocks)
[error] PLAN010 line 0: L2 plan must contain at least one Phase heading
  fix (manual): Reconcile the 'tier:' frontmatter field with the document's heading structure per the convention ADR's tier-driven structure rules.
```

The demote succeeds with exit `0` and leaves the plan failing its own check with
exit `1`. That is the same asymmetry as the scaffold: these verbs move the tier
and strip what sits above it, and neither one writes the containers the tier you
land on requires. Promotion is the exception, and only because it refuses to run
until you have named them. After a demotion, add the Phase yourself.

<p id="what-the-exit-code-gates-on"></p>

## Keep it healthy

Check the records after editing them:

```sh
vaultspec-core vault check all
```

Follow the [verification guide](../core/verification.md) to interpret exit codes,
apply supported repairs, and review the changes before committing.
Use the [CI examples](#gate-a-pipeline-on-it) to check records automatically.

One thing about the summary line is worth knowing before you try to reconcile
it: the three numbers do not subtract. Here is one vault, checked, repaired, and
checked again, showing only the last line of each report:

```text
  Total: 6 errors, 36 warnings
  Total: 6 errors, 27 warnings, 19 fixed
  Total: 6 errors, 27 warnings
```

Thirty-six warnings, nineteen fixed, twenty-seven left. `fixed` counts the
repairs applied; the warning count beside it is a fresh count taken afterwards,
against a corpus those repairs have already changed. Repairing one thing can
settle a check that was never counted and unsettle one that was, so the middle
line is a new reading rather than the first line minus the repairs. The third
line confirms it by agreeing with the second. Compare runs, not arithmetic.

## Rename a feature without breaking its trail

A feature tag is in the filename of every document that carries it, in the
frontmatter of each one, and in the `related:` links between them. Renaming it
by hand means editing all three in step, and the check that would catch a miss
runs after the damage. One verb does the whole set.

Preview it first. This is the one place the preview earns its keep, because it
tells you the size of what you are about to do:

```
vaultspec-core vault feature rename payment-retries capture-retries --dry-run
```

```text
Dry-run: Previewing feature rename 'payment-retries' -> 'capture-retries'
Planned renames (3 documents):
  .vault/adr/2026-09-04-payment-retries-adr.md  ->  .vault/adr/2026-09-04-capture-retries-adr.md
  .vault/plan/2026-09-04-payment-retries-plan.md  ->  .vault/plan/2026-09-04-capture-retries-plan.md
  .vault/research/2026-09-04-payment-retries-research.md  ->  .vault/research/2026-09-04-capture-retries-research.md
Predicted: 3 tag rewrite(s), 2 related-link rewrite(s)
No incoming cross-feature links found.
```

The last two lines are the ones to read. `tag rewrite(s)` and
`related-link rewrite(s)` are the edits inside the files, which are the part a
by-hand rename forgets, and the cross-feature line says whether any other
feature points at this one. Drop the flag to apply:

```
vaultspec-core vault feature rename payment-retries capture-retries
```

```text
Next action:
  Verify your vault is completely clean after renaming the feature
    vaultspec-core vault check all
Renamed 3 documents 'payment-retries' -> 'capture-retries'.
  .vault/adr/2026-09-04-payment-retries-adr.md  ->  .vault/adr/2026-09-04-capture-retries-adr.md
  .vault/plan/2026-09-04-payment-retries-plan.md  ->  .vault/plan/2026-09-04-capture-retries-plan.md
  .vault/research/2026-09-04-payment-retries-research.md  ->  .vault/research/2026-09-04-capture-retries-research.md
3 tag rewrite(s), 2 related-link rewrite(s)
```

It exits `0` and the counts match the preview, which is what you are checking.

Body prose is not rewritten, and that reaches further than the reference's
wording suggests, because a document's title is body prose. The research file
above still carries `payment-retries` in its own heading afterwards. The trail is
intact and every heading is stale, which is the half of this operation you
finish by hand. Nothing finds those mentions for you.

Paths above are written with `/`. That run was made on Windows, where the tool
prints `\`.

## Retire a feature without deleting it

A vault accumulates. Every feature you finish stays in `feature list` beside the
ones you are working on, and the list is the inventory a later reader - or a
later you - reads to find out what this project has decided. A finished feature
that never leaves it makes that list worse the longer the project runs.

Archiving is the way out, and it is the only one that keeps the records. Start
from what the list holds:

```
vaultspec-core vault feature list
```

```text
  billing  1 docs  (research)  2026-09-05
  shipping  1 docs  (research)  2026-09-05
```

```
vaultspec-core vault feature archive billing
```

```text

Next action:
  Verify your vault remains completely clean after archiving
    vaultspec-core vault check all
Archived 1 documents.
  .vault\_archive\research\2026-09-05-billing-research.md
```

The hint prints above the result rather than below it, which reads oddly and is
what the tool does. The documents move to `.vault/_archive/` rather than being
removed, and the feature drops out of the list:

```
vaultspec-core vault feature list
```

```text
  shipping  1 docs  (research)  2026-09-05
```

To undo it, unarchive the same tag. It reverses exactly, and this half prints
no hint at all:

```
vaultspec-core vault feature unarchive billing
```

```text
Unarchived 1 documents.
  .vault\research\2026-09-05-billing-research.md
```

Archiving is reversible and deleting is not, so reach for this first. It is
also the only undo here: nothing restores a document the filesystem no longer
has, and `vault archive restore` recovers only what was archived rather than
removed. Captured
on `0.1.73`; that run was made on Windows, where the tool prints `\`.


## Gate a pipeline on it

Check out the repository and
[install `vaultspec-core` on `PATH`](../core/installation.md#how-you-run-it-afterwards)
before running these steps. For the optional gates, install Bash and `jq`.

Run the vault checks as a pipeline step. Errors fail the step; warnings pass.

```yaml
- name: Check the vault
  run: vaultspec-core vault check all
```

To reject `code-boundary` and `modified-stamp` findings, add this gate:

```yaml
- name: Check source boundaries and record stamps
  shell: bash
  run: |
    set -euo pipefail
    for check in code-boundary modified-stamp; do
      vaultspec-core vault check "$check" --json |
        jq -e --arg check "$check" '
          .schema == ("vaultspec.vault.check." + $check + ".v2")
          and .status == "unchanged"
          and .data.diagnostics.total == 0'
    done
```

The gate checks the response schema and total findings, not one page of results.
It deliberately rejects warnings. `code-boundary` is excluded from `all`;
`modified-stamp` runs in `all` but reports advisory findings. A stamp mismatch
flags a record for inspection; it doesn't prove whether the record was approved.
See the [check reference](../core/cli.md#vaultspec-core-vault-check) for details.

To validate every plan, add:

```yaml
- name: Check plan conventions
  shell: bash
  run: |
    set -euo pipefail
    shopt -s nullglob
    for plan in .vault/plan/*.md; do
      vaultspec-core vault plan check "$plan"
    done
```

When `.vault/plan/` contains no Markdown files, this step skips cleanly.

Apply corrections locally,
[review the diff, and recheck](../core/verification.md#check-records-before-committing).
Keep `--fix` out of the pipeline so it checks the committed files.

<p id="ask-for-machine-readable-output"></p>

## Get JSON output

Request status as JSON:

```bash
vaultspec-core status --json
```

See the [JSON output reference](../core/cli.md#json-output-envelope) for response fields.

The `--json` flag is command-specific. Check a command's `--help` output to see
whether it supports JSON.

## When a command refuses

Five refusals cover most of what stops you, and each names its own way out.

`vaultspec is already installed at ...` comes from a second `install` in a
project that has one. It names three ways forward - `--upgrade` to re-seed the
bundled rules and skills, `--force` to overwrite, `uninstall` to start over -
and exits `1`.

`error: L1 plans do not support Phase headings; promote first` means the plan
has no container above its Steps. Scaffold with `--tier L2`, or run
`vaultspec-core vault plan tier promote`, which wants the new container's title
and intent as flags.

`'vaultspec-core vault check orphans' has no auto-fix capabilities` means the
check rejects `--fix`. Run it without that flag and resolve the findings manually.
See the [check reference](../core/cli.md#vaultspec-core-vault-check) for supported fixes.

`Step canonical identifier 'S02' appears 2 times in document order` comes from
`vaultspec-core vault plan check`, and it is the one thing a hand-edited plan
can break that nothing repairs. Its fix is marked manual because the tool
cannot know which row the execution records naming `S02` were written against.
`vault check all` does not run the plan conventions, so a duplicate survives a
clean run of it.

For an unresolved related document, run `vaultspec-core vault list` and use the
existing document's filename or stem in `--related`.

## Where to go next

If you'd rather your agent called these operations directly than shelled out,
read [reaching Vaultspec from your agent](mcp.md).

---

## Reaching Vaultspec From Your Agent

Connect your agent through Model Context Protocol (MCP) to call vault operations
as tools. The MCP server uses the same validation and identifier rules as the
command-line interface (CLI). See the [MCP reference](../core/mcp.md) for tools
and parameters.

## Point your agent at it

Run `vaultspec-core install` to configure supported agents. The installer writes
the server entry in each provider's format. A default `.mcp.json` entry is:

```json
{
  "mcpServers": {
    "vaultspec-core": {
      "command": "uvx",
      "args": [
        "--from",
        "vaultspec-core",
        "python",
        "-m",
        "vaultspec_core.mcp_server.app"
      ]
    }
  }
}
```

The launch command depends on the installation mode. With both core and vaultspec-rag
installed as project dependencies, the entries use the project environment:

```json
{
  "mcpServers": {
    "vaultspec-core": {
      "command": "uv",
      "args": [
        "run",
        "--no-sync",
        "python",
        "-m",
        "vaultspec_core.mcp_server.app"
      ]
    },
    "vaultspec-rag": {
      "command": "uv",
      "args": [
        "run",
        "--no-sync",
        "python",
        "-m",
        "vaultspec_rag.server"
      ]
    }
  }
}
```

Check `install mode` in `vaultspec-core doctor` before comparing your generated
configuration with an example. See [installation modes](../core/installation.md)
for setup details and [combined server entries](#two-products-one-file) for
core and vaultspec-rag in the default mode.

In `.codex/config.toml`, find the installer-managed `mcps` region:

```toml
# <vaultspec type="mcps">
[mcp_servers."vaultspec-core"]
args = ["--from", "vaultspec-core", "python", "-m", "vaultspec_core.mcp_server.app"]
command = "uvx"
# </vaultspec>
```

Your agent launches the core MCP server over standard input and output; no
separate core service or network port is needed for this configuration.

For vaultspec-rag, start its background service before using its search tools.
Follow [vaultspec-rag MCP setup](../rag/mcp.md) for the startup sequence.

If your agent requests approval for the configured server, review and approve it
in the agent's interface before using its tools.

## Two products, one file

The search component answers to two names here, and only one of them belongs in
a project file. The package and the `.mcp.json` key are both `vaultspec-rag`,
which is what the entries below use. `vaultspec-search-mcp` is a console script
the base install registers, and it is one of two ways to launch the same server
rather than a second server.

vaultspec-rag declares its own server in the same `.mcp.json`, and its installer writes
that entry the same way core writes its own. Running `vaultspec-rag install` in a
project that already has the harness leaves you this, which is the file a reader
who installed both as tools ends up holding:

```json
{
  "mcpServers": {
    "vaultspec-core": {
      "command": "uvx",
      "args": [
        "--from",
        "vaultspec-core",
        "python",
        "-m",
        "vaultspec_core.mcp_server.app"
      ]
    },
    "vaultspec-rag": {
      "command": "uvx",
      "args": [
        "--from",
        "vaultspec-rag[gpu,mcp]",
        "python",
        "-m",
        "vaultspec_rag.server"
      ]
    }
  }
}
```

core and vaultspec-rag use separate keys in the same configuration. The vaultspec-rag entry requests
the `gpu,mcp` extras at launch. To skip MCP enrollment during vaultspec-rag installation,
use `vaultspec-rag install --no-mcp`.

Keep installer-managed entries in their generated form. Use the manual
`vaultspec-search-mcp` configuration only for clients the installer does not
manage; see [vaultspec-rag MCP setup](../rag/mcp.md).

## When the two components are in different modes

The file above is the tool route: both components installed as tools, both
launched with `uvx`. The quickstarts on this site do not take it. The front page
installs core with `uv tool install vaultspec-core`, and vaultspec-rag's tutorial
installs it with `uv add "vaultspec-rag[gpu]"`, which is one of each. A
workspace records the mode per package rather than for itself, so that
combination is a supported state and not a mistake.

It does not arrive tidy. Because vaultspec-rag depends on core, adding vaultspec-rag to a
project also brings core into the project environment, and the entries written
at that point launch both out of the project - which is no longer the tool mode
core is declared in. The mode check reports the mismatch rather than the mode
(showing only the two install-mode lines of a longer report):

```bash
vaultspec-core doctor
```

```text
  install mode (vaultspec-core) warn declared tool; hook entries or MCP command do not match; run vaultspec-core install --upgrade, or install --mode to re-provision
  install mode (vaultspec-rag) ok declared dependency; artifacts match
```

Of the two remedies that message offers, `--mode` is not the one to reach for on
a project that is already installed: it stops on `Error: vaultspec is already
installed at <path>`. Reconcile with the other:

```bash
vaultspec-core install --upgrade
```

Running the check again reports the declared modes instead of the mismatch, and
core stays a tool:

```bash
vaultspec-core doctor
```

```text
  install mode (vaultspec-core) ok declared tool; artifacts match
  install mode (vaultspec-rag) ok declared dependency; artifacts match
```

The reconciled file is the one this combination ends up holding. Core launches
as a tool and vaultspec-rag out of the project, in the same `.mcp.json`:

```json
{
  "mcpServers": {
    "vaultspec-core": {
      "command": "uvx",
      "args": [
        "--from",
        "vaultspec-core",
        "python",
        "-m",
        "vaultspec_core.mcp_server.app"
      ]
    },
    "vaultspec-rag": {
      "command": "uv",
      "args": [
        "run",
        "--no-sync",
        "python",
        "-m",
        "vaultspec_rag.server"
      ]
    }
  }
}
```

Compare the `command` of each entry against the mode the check reports for that
package, not against the file a single-mode route would leave. `uvx --from` is a
tool; `uv run --no-sync` is a project dependency. An entry in the other package's
form is the mismatch above, and `vaultspec-core install --upgrade` is what
settles it.

A hand-edited managed entry can cause sync to skip it:

```bash
vaultspec-core spec mcps sync
```

```text
Scoped sync: native MCP targets only. Run vaultspec-core sync for the full provider refresh.
MCPs sync
  claude
    s vaultspec-rag
  = antigravity  up to date
  = codex  up to date
  5 unchanged  1 skipped
  - MCP server 'vaultspec-rag' in .mcp.json differs from its definition
    (use --force to overwrite).
```

The counts refer to server entries, not files. Do not treat a skipped entry as
a durable override; see [managed-entry ownership](#hand-editing-the-file).
To replace it with the managed definition, use `--force`:

```bash
vaultspec-core spec mcps sync --force
```

```text
Scoped sync: native MCP targets only. Run vaultspec-core sync for the full provider refresh.
MCPs sync
  claude
    ~ vaultspec-rag
  = antigravity  up to date
  = codex  up to date
  1 updated  5 unchanged
```

Check the generated entries:

```bash
vaultspec-core spec mcps status
```

```text
mcps status
  claude project ok .mcp.json vaultspec-core, vaultspec-rag none none none
  antigravity project ok .agents\mcp_config.json vaultspec-core, vaultspec-rag none none none
  codex project ok .codex\config.toml vaultspec-core, vaultspec-rag none none none
  ok: 3 provider target(s)
```

This reports native MCP configuration targets, not every enabled agent, and the
two counts differ on an ordinary install. Setup enables four providers -
`.vaultspec/providers.json` lists `antigravity`, `claude`, `codex` and `gemini` -
while the report above names three. Gemini is the one missing, because on
`0.1.73` it has no MCP configuration file for the installer to own: it receives
the harness through `.gemini/SYSTEM.md` and `.gemini/agents/` instead, and a
search of `.gemini/` turns up no MCP config at all. So three targets on a
four-provider install is the expected reading rather than a row that fell out,
and the same asymmetry is why the provider table in the
[MCP reference](../core/mcp.md) has three rows. These Windows captures have both
components installed; absolute paths are shortened to their final file.

For an unmanaged client, such as a desktop application with its own configuration,
install the `vaultspec-rag` `mcp` extra in the environment that provides `vaultspec-search-mcp`.
Set an explicit project root:

```json
{
  "mcpServers": {
    "vaultspec-rag": {
      "command": "vaultspec-search-mcp",
      "args": ["--read-only"],
      "env": {
        "VAULTSPEC_RAG_ROOT": "/absolute/path/to/your/project"
      }
    }
  }
}
```

Use an absolute path for `VAULTSPEC_RAG_ROOT`. In JSON, write Windows paths with
forward slashes, such as `C:/Users/me/project`, or escape each backslash.
Do not replace an installer-managed `.mcp.json` entry with this manual configuration.

## Hand-editing the file

vaultspec-core records a fingerprint of every entry it wrote. An entry whose
bytes no longer match its fingerprint is treated as yours for one run: that sync
skips it with a warning rather than repairing it, and records what you wrote as
the bytes it now tracks. The run after that finds a fingerprint that matches,
reads the entry as its own, and refreshes the launch shape to the current
standard. `vaultspec-core spec mcps sync --force` reaches the same end in one
run rather than two. An entry core never wrote at all is never adopted or
modified without that flag.

```{raw} html
<figure class="vs-pipe">
<svg viewBox="0 0 960 270" role="img" aria-labelledby="vs-fp-t vs-fp-d" class="vs-pipe-svg">
  <title id="vs-fp-t">What a hand-edited entry goes through on the next two syncs</title>
  <desc id="vs-fp-d">Four states in order. First the entry core wrote, whose bytes
  match the fingerprint it recorded. Then your edit, after which the bytes no
  longer match. The next sync skips that entry with a warning and adopts what you
  wrote as the bytes it now tracks. The sync after that finds a fingerprint that
  matches, reads the entry as its own, and refreshes it to the current launch
  shape, at which point your edit is gone. Passing --force reaches the same end in
  one run instead of two. An entry core never wrote is never adopted or modified
  without that flag.</desc>

  <g class="vs-pipe-flow">
    <path d="M222 57 h20" /><path d="M462 57 h20" /><path d="M702 57 h20" />
    <path d="M242 57 l-7 -4 v8 z" /><path d="M482 57 l-7 -4 v8 z" />
    <path d="M722 57 l-7 -4 v8 z" />
  </g>

  <g class="vs-pipe-stage">
    <rect x="0"   y="30" width="222" height="54" rx="6" />
    <rect x="240" y="30" width="222" height="54" rx="6" />
    <rect x="480" y="30" width="222" height="54" rx="6" />
    <rect x="720" y="30" width="240" height="54" rx="6" />
  </g>

  <g class="vs-pipe-name" font-size="19" text-anchor="middle">
    <text x="111" y="63">core wrote it</text>
    <text x="351" y="63">you edit it</text>
    <text x="591" y="63">first sync</text>
    <text x="840" y="63">second sync</text>
  </g>

  <g class="vs-pipe-note" font-size="18" text-anchor="middle">
    <text x="111" y="116">the bytes match the</text>
    <text x="111" y="139">fingerprint it recorded</text>
    <text x="351" y="116">the bytes no longer</text>
    <text x="351" y="139">match</text>
    <text x="591" y="116">skips it with a warning,</text>
    <text x="591" y="139">and adopts what</text>
    <text x="591" y="162">you wrote</text>
    <text x="840" y="116">the fingerprint matches</text>
    <text x="840" y="139">now, so it refreshes</text>
    <text x="840" y="162">the entry</text>
  </g>

  <g class="vs-pipe-dir" font-size="18" text-anchor="middle">
    <text x="591" y="192">your edit survives</text>
    <text x="840" y="192">your edit is gone</text>
  </g>

  <g class="vs-pipe-band">
    <rect x="0" y="216" width="960" height="42" rx="6" />
    <text x="480" y="242" font-size="18" text-anchor="middle">sync --force reaches the last box in one run; an entry core never wrote is never adopted or modified without it</text>
  </g>
</svg>
<ol class="vs-pipe-steps">
  <li><b>core wrote it</b><span>the bytes match the fingerprint it recorded</span></li>
  <li><b>you edit it</b><span>the bytes no longer match</span></li>
  <li><b>first sync</b><span>skips it with a warning, and adopts what you wrote - your edit survives</span></li>
  <li><b>second sync</b><span>the fingerprint matches now, so it refreshes the entry - your edit is gone</span></li>
</ol>
<p class="vs-pipe-steps-band"><code>sync --force</code> reaches the last box in one run; an entry core never wrote is never adopted or modified without it.</p>
<figcaption>An edit does not survive. It buys one sync, and the run that takes
it away is an ordinary one with no flags.</figcaption>
</figure>
```


If you would rather core never touched the file at all, pass `--skip mcp` to the
*first* install. `vaultspec-core install --skip mcp` leaves a workspace with no
recorded enrolment, and a workspace with no enrolment is one sync leaves alone
entirely - there is no fingerprint to compare against, so nothing to adopt or
refresh. On a project that is already installed the same command refuses, and
the section on withholding the destructive tools has the route that works
there.

The [Model Context Protocol (MCP) reference](../core/mcp.md) sets out the
ownership rules in full.

## Withholding the destructive tools

```{warning}
Do not rely on a hand-added `--read-only` flag in an installer-managed entry.
Two ordinary `vaultspec-core spec mcps sync` runs can remove it: the first skips
the edited entry; the second refreshes it and drops the flag. This restores
mutating tools, including index deletion for vaultspec-rag. Recheck the launch arguments
after sync, even if its message says hand-edited entries are never refreshed.
```

Launch vaultspec-rag with `--read-only` to expose only search and read tools over MCP.

The server advertises twelve tools and the flag halves them. Six stay:
`search_codebase`, `search_vault`, `search_documents`, `search_combined`,
`get_code_file` and `get_index_status`. Six go: `reindex_all`,
`reindex_codebase`, `reindex_vault`, `reindex_documents`, `clean_documents` and
`clean_all`. Check your client's available-tool list after reconnecting.

Append the flag to the existing launch arguments:

```json
{
  "mcpServers": {
    "vaultspec-rag": {
      "command": "uvx",
      "args": [
        "--from",
        "vaultspec-rag[gpu,mcp]",
        "python",
        "-m",
        "vaultspec_rag.server",
        "--read-only"
      ]
    }
  }
}
```

Core's server takes the same flag, and its surface is smaller than the rag one.
Probed over stdio with `tools/list` on 0.1.73, the default launch advertises nine
tools - `find`, `create`, `edit`, `status`, `check`, `plan_progress`,
`plan_edit`, `discover` and `invoke` - of which six carry `readOnlyHint: false`.
With `--read-only` four are advertised: `find`, `status`, `check` and
`discover`. The five that go are `create`, `edit`, `plan_progress`, `plan_edit`
and `invoke`, and they go from the listing rather than being refused when
called, so a client is never handed the schema of something it cannot use.
`check` stays but narrows: its `fix` parameter is gone and its description
changes from "Run the vault health-check suite, optionally repairing." to "Run
the vault health-check suite without repair." That is why six of the nine count
as mutating while only five are withdrawn.

Whichever server you run, the mutating tools write straight into the working
tree and never commit: calling `create` on a clean checkout leaves the new
records as untracked changes and adds no commit. Run them on a clean tree if you
want the diff reviewable.

This Core example demonstrates the overwrite risk after appending `--read-only`
to a managed entry. The first sync skips it:

```
vaultspec-core spec mcps sync
```

```text
Scoped sync: native MCP targets only. Run vaultspec-core sync for the full provider refresh.
MCPs sync
  claude
    s vaultspec-core
  = antigravity  up to date
  = codex  up to date
  2 unchanged  1 skipped
  - MCP server 'vaultspec-core' in <project>/.mcp.json differs from its definition (use --force to overwrite).
```

The second run, identical, takes it back:

```
vaultspec-core spec mcps sync
```

```text
MCPs sync
  claude
    ~ vaultspec-core
  = antigravity  up to date
  = codex  up to date
  1 updated  2 unchanged
  - MCP server 'vaultspec-core' launch refreshed to the current standard: 'uvx --from vaultspec-core python -m vaultspec_core.mcp_server.app --read-only' -> 'uvx --from vaultspec-core python -m vaultspec_core.mcp_server.app' (managed entry was unchanged since vaultspec wrote it; hand-edited entries are never refreshed automatically).
```

The refreshed launch no longer contains `--read-only`, despite the message's
claim that hand-edited entries are never refreshed automatically.

This behavior was also reproduced on Core `0.1.73` with a second managed server
added through `spec mcps add`: the first sync reported `2 skipped`; the second
reported `2 updated` and removed both flags. The captures use a Core-only
Windows project, with its path shortened to `<project>`.

To preserve custom launch arguments across ordinary syncs, remove managed
enrollment before creating your own entries. `install --skip mcp` applies to
the first install; it refuses an already-installed project. Preview removal:

```
vaultspec-core spec mcps uninstall --dry-run
```

```text
  claude
    - vaultspec-core
    - vaultspec-rag
  antigravity
    - vaultspec-core
    - vaultspec-rag
  codex
    - vaultspec-core
    - vaultspec-rag
  6 removed
```

Re-run it with `--force` to apply:

```
vaultspec-core spec mcps uninstall --force
```

```text
MCPs uninstall sync
  claude
    - vaultspec-core
  antigravity
    - vaultspec-core
  codex
    - vaultspec-core
  3 removed
```

These captures use different projects: the preview includes core and vaultspec-rag;
the applied run includes Core only. Removal deletes managed entries and can
delete their configuration file if nothing else remains.

Recreate each entry you need with `--read-only`, then check ownership with sync.
This excerpt shows an externally managed Core entry in a project with both components:

```
vaultspec-core spec mcps sync
```

```text
  5 created  1 skipped
  - MCP server 'vaultspec-core' in <project>/.mcp.json is externally managed; use --force to adopt it explicitly.
```

Confirm that each custom entry is reported as externally managed and still
contains `--read-only`. Ordinary syncs leave external entries alone;
`sync --force` adopts and overwrites them. The captured path is shortened.

Core also accepts `--read-only`, through both its module launch and the
`vaultspec-core-mcp` command. Releases before 0.2.4 named that command
`vaultspec-mcp`:

```
vaultspec-core-mcp --help
```

```text
Usage: vaultspec-core-mcp [OPTIONS] COMMAND [ARGS]...

  Run the Vaultspec MCP server.

Options:
  --parent-pid <int>  Explicit client PID for the stdio lifetime watchdog
                      (watched in addition to the discovered client)
  --read-only         Expose only non-mutating MCP tools.
  --help              Show this message and exit.
```

Append the flag to Core's launch arguments. The same
[managed-entry overwrite warning](#hand-editing-the-file) applies.
Confirm your client's available tools against
[Core's read-only tool list](../core/mcp.md#serving-a-read-only-surface).
`check` remains available without repairs; `invoke` is withheld.

For vaultspec-rag, start the resident service before using its tools; follow
[vaultspec-rag MCP setup](../rag/mcp.md).

## Check that it connected

Open your client's available-tool list and check for Core's `status` and `find`.
Read-only mode exposes fewer tools, and vaultspec-rag adds a separate set.

If Core's tools are missing, restart the client and check whether it requires
approval to launch the server. Check the installed configuration:

```
vaultspec-core doctor
```

For a Claude configuration, look for:

```text
  mcp ok .mcp.json present
```

This confirms the configuration file exists, not that the client connected.

To prove the server itself answers, speak to it directly. It is a stdio server,
so a client is three lines of JSON on its standard input: the handshake, the
notification that the handshake is done, and one call. Run this from a project
that has a vault:

```
vaultspec-core-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"status","arguments":{}}}
EOF
```

That is a POSIX heredoc. PowerShell has no such operator and reserves `<`, so
the block above is a parse error there rather than a failed run. Its equivalent
is a single-quoted here-string piped in, and the closing `'@` has to sit at the
start of its line:

```powershell
@'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"status","arguments":{}}}
'@ | vaultspec-core-mcp
```

Both were run against `0.2.4`, and the refusal further down translates the
same way. It answers one line of JSON per request. The second is the `status` call, and
its `result` is the shape every tool on this page returns - abridged here to the
summary line and the first feature, because the rollup also carries totals and
the plans in flight:

```text
{"jsonrpc":"2.0","id":2,"result":{"content":[{"text":"1 active features, 0 plans in flight","type":"text"}],"isError":false,"structuredContent":{"tool_schema_version":"0.2.4","kind":"rollup","features":[{"name":"search-api","doc_count":2,"latest_activity":"2026-09-21","has_plan":true,"status":"Planned","plan_tier":"L2","plan_completion_percent":0.0}],...}}}
```

Two things in that answer are worth knowing before you read the tool reference.
`content` carries a sentence for a person, and `structuredContent` carries the
same answer as data - your agent reads the second, which is why its summaries
can be more specific than the one line the server wrote. And `isError` is a
field inside `result` rather than a JSON-RPC `error`, so a refusal arrives on
the success path. Ask `status` for a feature that is not there - the same three
lines, with one argument changed:

```
vaultspec-core-mcp <<'EOF'
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"1"}}}
{"jsonrpc":"2.0","method":"notifications/initialized"}
{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"status","arguments":{"target":"no-such-feature"}}}
EOF
```

```text
{"jsonrpc":"2.0","id":2,"result":{"content":[{"text":"Error executing tool status: Could not resolve orientation target 'no-such-feature'. Run `vaultspec-core vault feature list` to enumerate available targets.","type":"text"}],"isError":true}}
```

That is `result`, not `error`. A client that only checks whether the call
completed reads it as a success, which is why the refusals on this page are
worth reading rather than assuming a silent tool worked.

(the-hot-path)=
## Start a feature

Follow [Run a feature from research to review](workflow.md) to research,
approve, and implement a change. Use the [tool reference](../core/mcp.md#tools)
to look up parameters and write behavior.

## When to use the command line instead

Use the CLI for resource syncs and plan changes above step level, including
phases, waves, and tiers. These operations use the destructive `invoke` gateway
over MCP, which can require host confirmation.

Rebuilding a feature index, managing MCP entries, and uninstalling require the
CLI. See [command-line guidance](cli.md) and the
[MCP reference](../core/mcp.md).

## Two writers, one vault

Supply `expected_blob_hash` when calling `edit` to reject a write if the document
has changed since you read it. See the [edit parameters](../core/mcp.md#edit).

The CLI equivalent is `--expected-blob-hash`. This example supplies a mismatched
hash to demonstrate a refused write. Replace the document stem and body-file
path with existing files in your project:

```
vaultspec-core vault set-body 2026-09-04-payment-retries-research --body-file new-body.md --expected-blob-hash deadbeefdeadbeefdeadbeefdeadbeef
```

```text
Blob-hash conflict: document changed on disk since it was read
expected deadbeefdeadbeefdeadbeefdeadbeef, on disk 63ce7068181d11f30e097ef43d04e5dc150f5d27
```

The command exits `1` without changing the document. The captured on-disk hash
will differ in your project. After a conflict, reread the document and reconcile
your changes before retrying with its current hash.

## Where to go next

- [Model Context Protocol reference](../core/mcp.md) - setup, install modes,
  environment, and every tool's parameters.
- [Driving the vault from the command line](cli.md) - the same operations from a
  prompt.

---

## vaultspec-core

Core installs the workflow, configures supported coding agents, and manages the feature records under `.vault/`.

## Start

- [Install Core](installation.md)
- [Understand the workflow](../concepts.md)
- [Run a feature](../guides/workflow.md)

## Reference

- [CLI reference](cli.md)
- [Document syntax](syntax.md)
- [MCP tools](mcp.md)
- [Workspace and record checks](verification.md)
- [Review and correctness](correctness.md)
- [Distribution channels](channels.md)

Records are Markdown files under `.vault/`. Open that directory in [Obsidian](https://obsidian.md) to browse the linked documents.

## Support and license

vaultspec-core is in beta. Report bugs, ask questions, or propose changes on the [issue tracker](https://github.com/nevenincs/vaultspec-core/issues). Released under the [MIT License](https://github.com/nevenincs/vaultspec-core/blob/main/LICENSE).

```{toctree}
:hidden:
:caption: Core

installation
framework
syntax
correctness
verification
channels
mcp
cli
```

---

## Installing vaultspec-core

## Before you begin

Install [uv](https://docs.astral.sh/uv/getting-started/installation/) and your
coding agent. Core supports CPython 3.13 and 3.14; uv downloads a supported
interpreter if needed.

Run the project setup from your repository root. Git is not required to
install, but committing the records and policy lets teammates share them.

Core 0.1.73 has an [installer bug](https://github.com/nevenincs/vaultspec-core/issues/399)
that skips ignore rules when `.gitignore` is missing. Create the file before you
install:

```bash
touch .gitignore
```

PowerShell has no `touch`; use `New-Item -ItemType File .gitignore` there.

Skipping this costs nothing visible. The install still succeeds, still exits
`0`, and still reports no problem - it simply writes no ignore rules at all,
and the managed block below is absent rather than incomplete. With the empty
file in place first, the same install writes it:

```text
# >>> vaultspec-managed (do not edit this block) >>>
.vault/.obsidian/
.vault/.trash/
.vault/data/
.vault/logs/
.vaultspec/*.lock
.vaultspec/_snapshots/
.vaultspec/mcp-ownership.json
.vaultspec/providers.json
/.agents/mcp_config.json.lock
/.codex/config.toml.lock
/.gitignore.lock
/.mcp.json.lock
/.pre-commit-config.yaml.lock
# <<< vaultspec-managed <<<
```

`0.1.73` is the version the command below resolves to: `0.1.73` is what
PyPI serves as current, and what a fresh install reports back under
[verify the install](#verify-the-install). The fix is on main, so this applies
until the next release rather than to some older one you might already have.

Core does not require a GPU. The [search package](../rag/installation.md) has
separate hardware requirements.

## Install

1. From your repository root, install the command-line tool:

   ```bash
   uv tool install vaultspec-core
   ```

2. Configure the current project for all supported coding agents:

   ```bash
   vaultspec-core install
   ```

3. [Verify the installation](#verify-the-install).

For other installation options, see [distribution channels](channels.md) and
[command prefixes](#how-you-run-it-afterwards).

```{vs-cast} vaultspec-core-install
:caption: Recorded project setup with `uvx vaultspec-core install`. This route does not add Core to PATH.
```

## How you run it afterwards

After a [tool installation](#install) or [standalone download](channels.md#direct-release-downloads),
use the command on your PATH:

```
vaultspec-core status
```

When running Core through `uvx`, keep that prefix on every command:

```
uvx vaultspec-core status
```

For a project dependency, add Core to the project and use `uv run`:

```
uv add vaultspec-core
uv run vaultspec-core status
```

For development-only dependencies, see [provisioning modes](#choose-a-provisioning-mode).

If your shell cannot find `vaultspec-core`, check the prefix: `uvx` does not add
the command to PATH. For a tool installation, follow uv's PATH instructions if
it reports that the executable directory is missing from PATH.

## What it writes

The installer creates records directories, project policy, and coding-agent
configuration:

```none
.vault/          the records: research, adr, plan, exec, audit, reference, index
.vaultspec/      the harness: rules, skills, agents, system, hooks, mcps,
                 templates, reference
.claude/ .gemini/ .codex/ .agents/    generated per-provider configuration
CLAUDE.md AGENTS.md GEMINI.md         the file each agent reads on startup
.mcp.json        the MCP server declaration
.pre-commit-config.yaml               vault checks, for pre-commit to wire
.gitattributes   a managed block pinning line endings
.gitignore       a managed block for runtime-state ignore rules
```

`.vault/` starts empty apart from its subdirectories. It fills as you work.

Commit `.vaultspec/workspace.json` with the project policy so teammates share
the provisioning mode. Keep machine-local ownership records, locks, and
snapshots untracked; see [ignored runtime files](#ignored-runtime-files).

<p id="what-each-provider-receives"></p>

## Agent configuration

| Coding agent | Skill instructions | Agent definitions | System guidance |
| --- | --- | --- | --- |
| Claude Code | `.claude/skills/` | `.claude/agents/` | `.claude/rules/vaultspec-system.builtin.md` |
| Codex | Folded into `.codex/config.toml` | `.codex/config.toml` | `.codex/rules/vaultspec-system.builtin.md` |
| Gemini CLI | Folded into `.gemini/SYSTEM.md` | `.gemini/agents/` | `.gemini/SYSTEM.md` |
| Antigravity | `.agents/skills/` | Not generated | No dedicated output |

The first column is the one that decides whether you have anything to type.
Measured on a fresh install of `0.1.73`: ten skill directories under
`.claude/skills/` and ten under `.agents/skills/`, and no skills directory for
either of the other two. `.agents/` is Antigravity's, and nothing the install
writes points Codex or Gemini at it - searched for `.agents` across
`.codex/`, `.gemini/`, `AGENTS.md` and `GEMINI.md`, and it does not appear.
What those two get instead is the same instruction set folded into files they
already read, so their stages are driven from
[the command line](../guides/cli.md) rather than invoked by name.

To edit `.vaultspec/` sources and sync your changes, see
[customize project policy](framework.md#customize-the-policy).

## Choose a provisioning mode

The mode controls how generated project commands launch core. Leave `--mode`
unset to reuse the saved mode, or detect it from `pyproject.toml` on a new installation.

- `tool` is the default. Commands launch through `uvx`; core is not a project dependency.
- `dev` uses core from the default development dependency group. Contributors get
  it through `uv sync`, and generated commands use the project environment.
- `dependency` uses core as a runtime dependency. Choose this only when your
  package calls core at runtime; it becomes a dependency of your published package.

The mode does not add the package to `pyproject.toml`. For a development
dependency, run `uv add --dev vaultspec-core`, then configure the harness:

```
vaultspec-core install --mode dev
```

The `tool` mode is separate from `uv tool install`, which installs the command
for your shell. See [command prefixes](#how-you-run-it-afterwards).

## Install for one agent only

The installer configures every provider it supports. To configure one, name it:

```
vaultspec-core install claude
```

Valid providers are `all`, `core`, `claude`, `gemini`, `antigravity`, and
`codex`. `core` writes the framework without configuring any agent, which is
what you want if you drive the pipeline entirely from the command line.

To keep everything except one piece, skip it instead. `--skip` is repeatable and
takes a provider name, `core`, `mcp`, or `precommit`:

```
vaultspec-core install --skip precommit
```

## Preview before writing

Preview the affected paths without changing the project:

```bash
vaultspec-core install --dry-run
```

Review the paths before installing into a project with existing agent
configuration. The preview's `unchanged` marker does not guarantee that a
modified bundled file will retain its contents.

For an existing installation, follow the [upgrade steps](#upgrade).
`install --force` restores bundled files and can replace your edits to them;
commit your changes first. User-added rules survive.

(the-other-force)=
### Force a sync

Force sync prunes stale generated files and can overwrite provider configuration,
including custom MCP launch settings. Review your changes before running it:

```bash
vaultspec-core sync --force
```

This removes generated copies of deleted source rules. Unmanaged files in
provider directories are not pruned. See the [sync reference](cli.md#sync)
for options.

Do not rely on ordinary syncs to preserve a hand-edited MCP entry indefinitely.
See [MCP ownership and read-only settings](../guides/mcp.md#withholding-the-destructive-tools)
before changing its launch arguments.

(installing-into-a-repository-with-no-gitignore)=
## Ignored runtime files

The managed block in `.gitignore` excludes runtime state such as `.vault/data/`,
caches, and lock files. Keep your feature
records and project policy in Git.

Ignore rules do not untrack files that were already committed. Check whether
runtime data is tracked:

```bash
git ls-files -- .vault/data
```

If that command lists files, remove them from Git's index while leaving them on disk:

```bash
git rm -r --cached -- .vault/data
```

Review and commit the staged removals. If the listing is empty, no cleanup is needed.

## Verify the install

Check the installed CLI version, workspace configuration, and vault validation:

```bash
vaultspec-core --version
vaultspec-core doctor
```

```text
0.1.73
workspace diagnosis
  framework ok .vaultspec/ present
  claude ok dir: complete
  gemini ok dir: complete
  antigravity ok dir: complete
  codex ok dir: complete
  builtins ok current
  gitignore ok complete
  gitattributes ok complete
  mcp ok .mcp.json present
  migration ok all registered migrations applied
  vault content ok no generated template annotations
  precommit ok all hooks present
  rename integrity ok all rules, skills, and agents names are consistent
  install mode (vaultspec-core) ok declared tool; artifacts match
  semantic search none vaultspec-rag not provisioned; core discovery and find cover document lookup without it

Vault Check - All
  ok structure: clean
  ok frontmatter: clean
  ok annotations: clean
  ok encoding: clean
```

Captured on a fresh install of `0.1.73` into an empty repository, exit `0`. Read
it down the verdict column - `ok`, `warn` or `none` - rather than reading every
row.

Two abridgements. The `process registry` row is omitted, because it reports
machine-global records left by other projects and says nothing about this
workspace. The vault check runs nineteen entries where four are shown, and all
nineteen read `clean` on a vault with no documents in it yet.

Compare your version with [published releases](https://pypi.org/project/vaultspec-core/).
Address reported problems and rerun `vaultspec-core doctor`. See
[workspace and vault verification](verification.md) for check details and exit
codes.

`semantic search none` means RAG is not provisioned for this workspace;
Core works without it.
To add search, follow the [RAG installation guide](../rag/installation.md).

To run vault checks when you commit, [activate the Git hooks](../guides/workflow.md#manual-and-advanced-operation).
Installing hook configuration alone does not enable Git to run it.

## Upgrade

Commit your project changes first. Refreshing bundled content replaces edits to
bundled files while preserving user-added rules.

If you installed Core with `uv tool install`, upgrade the CLI:

```bash
uv tool upgrade vaultspec-core
```

uv respects any [version constraints set at installation](https://docs.astral.sh/uv/guides/tools/#upgrading-tools).
After updating Core, refresh the project's bundled content from its root:

```bash
vaultspec-core install --upgrade
```

Inspect migration status without changing the project:

```bash
vaultspec-core migrations status
```

If migrations are pending, apply them:

```bash
vaultspec-core migrations run
```

Review the changed files before committing. See the [migration reference](cli.md#vaultspec-core-migrations-status)
for options and exit codes.

## Uninstall

Uninstall removes `.vaultspec/`, provider directories, and generated configuration.
It preserves `.vault/` unless you add `--remove-vault`; back up your feature
records before using that option.

Preview the affected paths without removing anything:

```bash
vaultspec-core uninstall --dry-run
```

Review the list and save any configuration you need. Then confirm removal:

```bash
vaultspec-core uninstall --force
```

For permanent removal, review the remaining vaultspec blocks in `.gitignore`
and `.gitattributes`. Remove them if you no longer need their rules. After all
vaultspec processes have stopped, remove leftover `.gitignore.lock`,
`.mcp.json.lock`, and `.pre-commit-config.yaml.lock` files. Leave these files
and blocks in place if you plan to reinstall.

## Joining a project that already has it

Clone the repository and install the CLI using the project's
[installation route](#how-you-run-it-afterwards). From the clone's root,
create your local provider configuration from the shared `.vaultspec/` policy:

```bash
vaultspec-core install
```

Use plain `install` for a fresh clone, not `--upgrade` or `--force`. The installer
establishes local manifest state from the existing policy. A second install
reports `already installed`; see [upgrading](#upgrade) when updating an existing
installation.

Git hooks do not travel with a clone. [Activate the commit checks](../guides/workflow.md#manual-and-advanced-operation)
locally. If the project uses search, [set up your own index](../rag/getting-started.md).
Then run `vaultspec-core status` to find the team's in-flight work:

```bash
vaultspec-core status
```

```text
Vault Status

Plans in flight  (at least one open step)
  2026-09-06-payment-retries-plan   L2   -   P0/1   0/1 steps   0%   next P01.S01      2026-09-06

Recent changes
  adr
    2026-09-06-payment-retries-adr  2026-09-06
  plan
    2026-09-06-payment-retries-plan  2026-09-06
  research
    2026-09-06-payment-retries-research  2026-09-06

Active features
  payment-retries  3 docs plan  L2 0/1 0%  2026-09-06

Discovery
  vaultspec-rag not provisioned - use find and grep for discovery

Totals
  Total documents: 3
  Total features:  1
```

`Plans in flight` is the answer to what anyone is working on: one row per plan
that still has an open Step, carrying its tier, how far through its Phases and
Steps it is, and the identifier of the next Step to pick up. A clone with
nothing started prints `none` there and the rest of the report unchanged, so an
empty first section means the vault is idle rather than unreadable.

`Discovery` reports whether the search component is available in this project;
the line above is what it prints when only Core is installed.

## Where to go next

- [Run a feature with your coding agent](../guides/workflow.md).
- [Drive the vault from the command line](../guides/cli.md).
- [Look up document types and workflow concepts](../concepts.md).

---

## vaultspec-rag

RAG indexes Vaultspec records, source code, and routed documents for semantic search. It is required in the standard Vaultspec setup.

## Start

- [Install RAG](installation.md)
- [Start the service and run a search](getting-started.md)
- [Write a precise query](query-craft.md)

## Reference

- [CLI reference](cli.md)
- [Configuration](configuration.md)
- [MCP tools](mcp.md)
- [Index verification](verification.md)

## Advanced

- [Service operation](service-mode.md)
- [Storage backends](backends.md)
- [Storage maintenance](storage-maintenance.md)
- [Automation](automation.md)
- [Automatic convergence](automatic-convergence.md)
- [Preprocessing hooks](preprocessing-hooks.md)
- [Service discovery](service-discovery.md)
- [Indexing internals](indexing.md)

## Support and license

vaultspec-rag is in beta. [Report issues](https://github.com/nevenincs/vaultspec-rag/issues) with your version, operating system, GPU, command, and error output, and redact credentials and private content before posting. Released under the [MIT License](https://github.com/nevenincs/vaultspec-rag/blob/main/LICENSE).

```{toctree}
:hidden:
:caption: RAG

installation
getting-started
query-craft
verification
configuration
mcp
service-mode
backends
storage-maintenance
automation
automatic-convergence
preprocessing-hooks
service-discovery
indexing
search-and-index
architecture
cli
```

---