# Vaultspec > Vaultspec implements a structured coding workflow focused on #features, decision records, and the documents grounding them. Its rules, skills, and agents guide your coding agent through each step, and its CLI and MCP server scaffold, validate, and link the documents. 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) ## Docs - [Documentation home](https://vaultspec.neve.md/docs/) - [Product page as Markdown](https://vaultspec.neve.md/index.md) - [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) - [Core documentation](https://vaultspec.neve.md/docs/core/index.html) - [RAG documentation](https://vaultspec.neve.md/docs/rag/index.html) - [Site-authored guides as one file](https://vaultspec.neve.md/llms-full.txt): the guides written for this site, assembled into a single text file. Imported manuals stay on the documentation site, each naming its source. ## Optional - [vaultspec-dashboard](https://github.com/nevenincs/vaultspec-dashboard): a separate project building a dedicated frontend on the vault's own files, in early development, in the open. - [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 11 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 - are available at https://vaultspec.neve.md/docs/. Each names, in its footer, the upstream file and commit it was taken from. Find the complete Markdown page index at https://vaultspec.neve.md/docs/llms.txt and the structured catalog at https://vaultspec.neve.md/content-index.json. ## Documentation Home vaultspec keeps research, decisions, and plans with your project instead of losing them in agent conversations. [How vaultspec works](concepts.md) explains the records. This page takes about five minutes to read. You'll download Core, install it in a project, create a record, and check it with your coding agent. Downloads may take longer. ## Before you start Install [uv](https://docs.astral.sh/uv/getting-started/installation/), then open a terminal in your project's root folder. Run the commands here from that folder. Core works without vaultspec-rag, a graphics processor (GPU), or a TypeSafe API key. vaultspec-rag is optional, but the workflow is designed around it: agents look for evidence by meaning first, and fall back to listing and `grep` when it isn't there. ## Download and install ```sh uvx vaultspec-core --version uvx vaultspec-core install uvx vaultspec-core doctor ``` The first command downloads Core if needed and prints its version. Installation creates `.vault/` for records, `.vaultspec/` for workflow instructions, and your coding agents' configuration. Look for `framework ok` and clean vault checks in the doctor's output. Already installed? Follow the [update instructions](core/installation.md#upgrade). For other options, see [installation details](core/installation.md). ## Create your first record ```sh uvx vaultspec-core vault add research --feature notes-search --title "Search project notes" uvx vaultspec-core vault list --feature notes-search uvx vaultspec-core status ``` The first command prints `Created:` followed by a dated Markdown path. Open that file in your editor: it's a research template, ready for findings. Creating a template does **not** perform research or start a plan. The list shows the record. Status shows `notes-search` with one document and, in a fresh project, no plans in flight. Existing project work also appears. ## Check it with your agent For the agent step, open the project in an agent with the Core [Model Context Protocol (MCP) server](guides/mcp.md) enabled. Send this prompt: ```{code-block} none :class: vs-block-prompt Use the vaultspec-core MCP status tool to show the status of this project. Tell me which features exist and whether any plan is in flight. Do not change any files. ``` The agent should report the same feature and plan state as the terminal. This prompt was tested with Codex. If the tool isn't available, follow the [connection checks](guides/mcp.md#check-that-it-connected). ## Continue when you need more - [Run a feature](guides/workflow.md): evidence, decisions, implementation, and review. - [Use the command line](guides/cli.md): create records, find work, and check it. - [Add project search](rag/installation.md): set up vaultspec-rag, the semantic search the workflow leads with. - [TypeSafe API integration and environment loading](guides/typesafe-env.md): separate keys, one settings order, and where `.env` is read. - [Core CLI](core/cli.md) and [vaultspec-rag CLI](rag/cli.md) references: all commands and options. (when-something-goes-wrong)= If a check fails, use [workspace verification](core/verification.md); if search results look wrong, see [search troubleshooting](rag/verification.md). For help, report the command, version, and error in the [Core issue tracker](https://github.com/nevenincs/vaultspec-core/issues). ```{toctree} :hidden: requirements core/installation rag/installation rag/getting-started concepts guides/workflow guides/cli guides/mcp guides/rag-service guides/typesafe-env core/index rag/index core/cli rag/cli ``` --- ## Requirements Start with Core. It installs the workflow and manages records without vaultspec-rag, a GPU, or an API key. The [quickstart](index.md) follows that path. vaultspec-rag is optional, but the workflow is designed around its semantic search, and it has the hard requirement: a supported GPU. It depends on Core, so installing it installs Core too. (requirements-setup)= ## Before installing Core You need [uv](https://docs.astral.sh/uv/getting-started/installation/), a terminal, and a project folder. Core and vaultspec-rag both run on CPython 3.13 or 3.14, and uv downloads a supported interpreter if needed. The quickstart's agent step also needs a coding agent with Core's [MCP connection](guides/mcp.md) enabled; the command-line steps work without it. (requirements-gpu)= (vaultspec-rag-needs-a-supported-gpu)= (requirements-models)= (the-service-needs-a-hugging-face-token)= ## Before installing vaultspec-rag Each machine runs one search service from a host installation, which needs: - An NVIDIA GPU with a driver that supports CUDA 13 on Linux or Windows, or Apple silicon on macOS. There is no CPU path, and AMD GPUs and Intel Macs are unsupported. `--local-only` changes where the index is stored, not this requirement. - Enough memory and disk for its resource profile, and several gigabytes for the models. - Network access for the public model files and the managed index server's first download. The default models need no Hugging Face account or token. A client installation needs no GPU, PyTorch, or model download, but it only works beside a host installation on the same machine, under the same user account, at the same release. [Set up vaultspec-rag](rag/installation.md#what-you-need-before-you-start) states each requirement in full, and [how vaultspec-rag runs](guides/rag-service.md) explains the service and its client. TypeSafe is an optional integration. Core and vaultspec-rag each take their own [API key, resolved through one shared settings order](guides/typesafe-env.md). (requirements-routes)= ## Platforms and install routes - [Core installation](core/installation.md): uvx, a shell tool, or a project dependency. - [Core distribution channels](core/channels.md): platform coverage and release archives. - [vaultspec-rag installation](rag/installation.md#choose-what-this-environment-runs): a host as a standalone tool, a project dependency, or a release binary for Windows x86-64, Linux x86-64 and ARM64, or Apple silicon; a client in a Python project. (requirements-versions)= ## Which version these pages describe Imported component references follow their published releases. The versions an install command resolves can differ between distribution channels. See the published page for this section: https://vaultspec.neve.md/docs/requirements.html --- ## Installing vaultspec-core For the full setup path and a working example, start at the [documentation home](../index.md). This page covers installation choices and updates. ## Before you begin Install [uv](https://docs.astral.sh/uv/getting-started/installation/). Open a terminal in the project you want to configure. Core does not need a GPU or an API key. See [requirements](../requirements.md) for supported Python versions and [distribution channels](channels.md) for other platforms and binary downloads. ## Install Acquiring the package and provisioning a project are separate operations. `uvx` acquires and runs Core in an isolated environment; Core's `install` command writes the workflow into the current project. Neither operation starts your agent. ```sh uvx vaultspec-core --version uvx vaultspec-core install uvx vaultspec-core doctor ``` Keep the `uvx` prefix for subsequent commands. This route does not put `vaultspec-core` on your shell's PATH. ## What it writes | Location | Purpose | | --- | --- | | `.vault/` | Research, decisions, plans, and other records | | `.vaultspec/` | Workflow rules, skills, templates, and agent definitions | | `.claude/`, `.codex/`, `.gemini/`, `.agents/` | Generated agent configuration | | `CLAUDE.md`, `AGENTS.md`, `GEMINI.md` | Instructions for supported agents | | `.mcp.json` | Core's MCP server entry | | `.pre-commit-config.yaml` | Configuration for commit checks | | `.gitignore`, `.gitattributes` | Managed ignore and line-ending rules | Installing writes configuration; it does not open an agent session. Use [Connect your agent](../guides/mcp.md) to check the connection. ## How you run it afterwards | Installation | Run commands as | | --- | --- | | Run on demand with uvx | `uvx vaultspec-core status` | | Install a shell tool | `vaultspec-core status` | | Add a project dependency | `uv run vaultspec-core status` | To install a shell tool: ```sh uv tool install vaultspec-core ``` Follow uv's PATH instructions if your shell cannot find the installed command. Installing the tool and configuring a project are separate operations: run `vaultspec-core install` in each project that needs the workflow. ## Joining a project that already has it Use the command prefix selected by the project. In a checkout already provisioned on this machine, `uv sync` installs locked project dependencies and `uv run vaultspec-core status` checks its records. For a fresh clone, follow the project's setup instructions; the joining check here covered an existing checkout. ### Choose a provisioning mode Package installation makes the command available. Provisioning writes the project's vault and agent configuration. Choose placement independently: | Mode | Intended package setup | Generated launch prefix | | --- | --- | --- | | `tool` | Package acquired outside the project | `uvx --from vaultspec-core` | | `dev` | Project's default development dependency group | `uv run --no-sync` | | `dependency` | Project runtime dependencies | `uv run --no-sync` | Core chooses the mode from an explicit `--mode`, then a saved workspace choice, then the package's placement in `pyproject.toml`, then `tool`. Invoking Core through `uvx` does not force `tool` mode in a project that declares it as a dependency. The interpreter must also belong to the workspace before Core can read its TypeSafe key from the workspace-root `.env`. For development tooling in a uv-managed Python project: ```sh uv add --dev vaultspec-core uv run vaultspec-core install --mode dev uv run vaultspec-core status ``` The `--mode dev` and `--mode dependency` flags configure how agent commands launch Core. `uv add --dev` installs the development dependency; neither mode flag adds a package to your project. This mode also affects eligibility to read the project's `.env`; see [environment loading](../guides/typesafe-env.md#which-source-wins). ## Preview before writing ```sh uvx vaultspec-core install --dry-run ``` Review the reported paths before installing into a project with existing agent configuration. For provider selection and skip options, use the [CLI reference](cli.md). ## Verify the install ```sh uvx vaultspec-core doctor uvx vaultspec-core status ``` On a fresh installation, `doctor` exits `0` with `framework ok` and clean vault checks; it exits `1` for warnings and `2` for errors. Status reports no features or plans until a record is created. `semantic search none` means vaultspec-rag is not provisioned yet; Core still creates and lists records. [Install vaultspec-rag](../rag/installation.md) next. See [workspace verification](verification.md) for other findings. (activate-the-commit-checks)= Commit-hook configuration does not demonstrate that Git is running those hooks. Follow your project's hook setup and the [verification guide](verification.md). ## Upgrade Save or commit your project changes before refreshing bundled files. First update the package using the route that acquired it: | Package route | Update command | | --- | --- | | Run on demand with uvx | `uvx --upgrade vaultspec-core --version` | | Standalone uv tool | `uv tool upgrade vaultspec-core` | | uv project dependency | `uv sync --upgrade-package vaultspec-core` | | Scoop | `scoop update vaultspec-core` | | Homebrew | `brew upgrade vaultspec-core` | Then refresh each project's provisioned files. For the uvx route, run: ```sh uvx vaultspec-core install --upgrade ``` `install --upgrade` refreshes the project from the package you are running; it does not upgrade that package. Use the matching command prefix for other routes. Review the changed files and run `doctor` again. ### Environment settings during install and upgrade Set environment variables in the process running `install` or `install --upgrade`. The workspace-root `.env` is not a general settings file: Core reads only its TypeSafe key there, and only from an eligible project environment. To save supported settings for later Core commands, explicitly import them with `--env NAME` or `--env-file PATH`. On an existing installation, include `--upgrade`: ```sh uvx vaultspec-core install --upgrade --env VAULTSPEC_CORE_TYPESAFE_API_KEY ``` This imports a key already set in the process environment into `.vaultspec/.env`; it does not require a key for installation. See [when settings take effect](../guides/typesafe-env.md#during-install-and-upgrade) for import timing and precedence. Plain `install` on an existing installation is rejected as already installed. Invalid Vaultspec settings normally refuse the run and name the variable; fix or unset it. The watchdog switch is the exception: an unrecognised `VAULTSPEC_STDIO_WATCHDOG` value leaves it armed. The [environment variables](cli.md#environment-variables) list each accepted value. For other package managers, migrations, or removal, consult the [CLI reference](cli.md) and [distribution channels](channels.md). ## Where to go next - [Create your first record](../index.md#create-your-first-record). - [Install vaultspec-rag](../rag/installation.md). - [Connect your agent](../guides/mcp.md). - [Run a feature](../guides/workflow.md). - [Configure TypeSafe and environment loading](../guides/typesafe-env.md). --- ## Installing vaultspec-rag vaultspec-rag adds search by meaning over project records and code. It is optional for [Core](../index.md), but the workflow is designed around it: agents look for evidence by meaning first. vaultspec-rag depends on Core, so every installation below installs Core with it; it also searches repositories that don't use the workflow. The search service needs a supported graphics processor (GPU): an NVIDIA GPU with CUDA on Linux or Windows, or Apple silicon on macOS. It doesn't run on the CPU or on AMD GPUs, and no route supports Intel Macs. [Why it needs a GPU](architecture.md#why-vaultspec-rag-needs-a-gpu) explains the choice. ## Choose what this environment runs Each machine runs one background search service, started under your user account. Two kinds of installation work with it: - A **host installation** carries the `gpu` extra. It runs the models and is the only kind that can start the service. - A **client installation** leaves `gpu` out. It loads no models, needs no GPU, and sends every request to the service a host installation on the same machine started. It must be exactly the service's release; a client refuses any other. The `mcp` extra adds the server your coding agent launches. Extras are not `--mode` flags. ### Choose an installation | Package | Installation | Starts the service | Runs the agent's MCP server | | --- | --- | --- | --- | | `vaultspec-rag` | Client | No | No | | `vaultspec-rag[mcp]` | Client | No | Yes | | `vaultspec-rag[gpu]` | Host | Yes | No | | `vaultspec-rag[gpu,mcp]` | Host | Yes | Yes | Every machine needs one host installation. If `vaultspec-rag server status` already reports the service running, [set up each repository](#set-up-each-repository) from that host installation, or [add a client](#add-a-client-to-a-python-project) to a Python project. If it reports the service stopped, start it with `vaultspec-rag server start` rather than reinstalling. ## What you need before you start For a host installation: - On Linux or Windows, an NVIDIA driver that supports CUDA 13: the `CUDA Version` that `nvidia-smi` prints must be 13.0 or later. On macOS, the system provides the driver. - For the default resource profile, 16 GiB of system RAM, 8 GiB of free index-store space, and 12 GiB of free CUDA memory at startup. The `embedded-local` profile lowers these for smaller corpora; select it with `VAULTSPEC_RAG_INDEX_SUPPORT_PROFILE` in the environment that starts the service ([resource bounds](configuration.md#index-resource-bounds-and-memory-ceilings)). - Several gigabytes of free disk for the models, which every repository shares. - [uv](https://docs.astral.sh/uv/getting-started/installation/) and CPython 3.13 or 3.14 for the Python routes. A prebuilt binary needs neither. - Network access to PyPI, `download.pytorch.org` on Linux and Windows, the Hugging Face model server, and GitHub release downloads. On Apple silicon the service uses Metal Performance Shaders (MPS) and refuses to start while `PYTORCH_ENABLE_MPS_FALLBACK` lets operations fall back to the CPU, so unset it where the service starts. (model-access)= ### The model cache and its first download The default dense, sparse, and reranking models are public. They need no Hugging Face account, login, or token. The sparse model is `Linkup-Platform/linkup-sparseup-embed-v1` (SPARSEUP). Set `HF_HOME` in the process environment before provisioning if you want a different model-cache location. Repository setup and host service startup can fetch missing files; clients never download them. See [model and index-server provisioning](provisioning.md) for the pinned downloads, cache verification, and offline setup. ## Set up a host installation ### Install as a standalone tool This is the default route. One installation serves every repository on the machine. On Windows x86-64 and Linux x86-64 or aarch64: ```sh uv tool install --python 3.13 "vaultspec-rag[gpu,mcp]" --index https://download.pytorch.org/whl/cu130 --index-strategy unsafe-first-match ``` On Apple silicon: ```sh uv tool install --python 3.13 "vaultspec-rag[gpu,mcp]" ``` The two index options fetch CUDA PyTorch, and uv records them so later upgrades keep the GPU build. A tool installed without them gets CPU-only PyTorch; repair it with [pin the GPU build](#pin-the-gpu-build). If uv says its executables directory isn't on your `PATH`, run `uv tool update-shell` and open a new terminal. ### Install as a project dependency Choose this when one Python project's environment should run the service and collaborators share its pinned release. Configure the CUDA build of PyTorch before you add the package. Otherwise the first `uv add` installs PyPI's `torch`, which is CPU-only on Windows. Add this block to the project's `pyproject.toml`; it's the same block the repository setup writes: ```toml [[tool.uv.index]] name = "pytorch-cu130" url = "https://download.pytorch.org/whl/cu130" explicit = true [tool.uv.sources] torch = [ {index = "pytorch-cu130", marker = "sys_platform == 'linux' or sys_platform == 'win32'"}, ] ``` Then, from the project root, add vaultspec-rag together with `torch` as a direct dependency, because uv applies a package source only to direct dependencies: ```sh uv add "vaultspec-rag[gpu,mcp]" "torch>=2.4" ``` Linux and Windows get the CUDA build, and Apple silicon gets the standard build, which uses Metal. Run later commands as `uv run vaultspec-rag` from the project root. To keep both out of the published dependencies, add them with `uv add --dev` and pass `--torch-group dev` to the repository setup ([install options](cli.md#install)). (prebuilt-binaries-and-temporary-runs)= ### Prebuilt binaries Release archives for Windows x86-64, Linux x86-64 and ARM64, and Apple silicon carry both commands and need no Python toolchain. Install them with Scoop (`scoop bucket add nevenincs https://github.com/nevenincs/homebrew-tap`, then `scoop install vaultspec-rag`) or Homebrew (`brew tap nevenincs/tap https://github.com/nevenincs/homebrew-tap`, then `brew install vaultspec-rag`), or download one with its `SHA256SUMS` from the [releases page](https://github.com/nevenincs/vaultspec-rag/releases) and compare the digest before extracting. On first launch a binary installs PyTorch, so it needs network access. The Linux archives need glibc 2.39 (Ubuntu 24.04, Debian 13, Fedora 40 or later); on older distributions use the standalone tool, which needs glibc 2.28. ### Set up each repository Run the repository setup once in the root of every repository you want to search. The command is named `install`, but it configures the repository; it doesn't install the package. For a standalone tool or a binary: ```sh vaultspec-rag install --no-torch-config ``` For a project dependency, run the setup through the project. With the CUDA source from [install as a project dependency](#install-as-a-project-dependency) already in `pyproject.toml`, its PyTorch step has nothing to change. If the source is missing, the setup asks to add it: answer `y`, or pass `--yes` when nobody is there to answer; on Windows, declining leaves CPU-only PyTorch. Then sync, so anything it added takes effect: ```sh uv run vaultspec-rag install uv sync ``` The setup adds the agent integration (a rule, a skill, and the MCP entry) and creates `.vault/` if missing. In a host environment with a usable accelerator, it also provisions the models and Qdrant server. If the accelerator is not ready, those downloads are skipped with a reason; host `server start` provisions missing files before starting the service. Later repositories reuse the cache. Clients skip all dependency provisioning. - `--no-mcp` sets up terminal use without an agent. - `--local-only` keeps the index on disk instead of in the managed Qdrant server and skips its download. It changes storage only; the models still run on the GPU. The choice covers the whole service. A host setup saves this choice for later `server start` calls; a client cannot change the host's saved backend. Run the service under the `embedded-local` profile, because the default profile refuses this backend. A startup flag overrides the environment, which overrides the saved choice. See [storage backends](backends.md). - `--mode` corrects how the setup detected the installation; see [what your agent launches](#what-your-agent-launches). ### Machine-readable output `install --json` and `uninstall --json` print one line in the shared envelope `{"schema", "status", "data"}`. `status` is one of `created`, `updated`, `unchanged`, `removed`, `skipped`, or `failed`. The exit code is `0` on success, `1` on failure, and `2` when the run completed but skipped a step that needed consent, such as the PyTorch patch nobody approved. A tool environment that needs the CUDA repair, run without authority to apply it, is a failure. The [command reference](cli.md#install) lists every flag and exit code. ### Start and verify From the host installation: ```sh vaultspec-rag server start vaultspec-rag --version vaultspec-rag server doctor ``` `server start` loads the models and waits until the service is ready. A healthy `server doctor` report shows PyTorch ready on a `cuda` or `mps` backend, every configured model cached, and the Qdrant binary present. The service doesn't restart after a reboot; [running it automatically](service-mode.md#running-it-automatically) covers that. Then [index and run a first search](getting-started.md#step-2-start-the-service-and-index-your-project). ## Add a client to a Python project A client lets a uv-managed project list vaultspec-rag without GPU packages. It still needs a host installation on the same machine, running the service under your user account. Read the service's release from the host installation: ```sh vaultspec-rag server status --verbose ``` From the project root, pin the client to the `Service release:` it prints, then set up the project so the agent launches the MCP server from the project environment: ```sh uv add --dev "vaultspec-rag[mcp]==" uv run vaultspec-rag install --mode dev ``` For terminal use only, add plain `vaultspec-rag==` and pass `--no-mcp`. A client skips PyTorch and every download on its own. Checked on Windows: the setup printed `PyTorch configuration: not needed (this installation is a client)`, reported PyTorch, models, and Qdrant as skipped, and the project environment held no PyTorch. `uv run vaultspec-rag server doctor` then reports the service's release as matching this client. Index and search with the usual commands prefixed with `uv run`; start, stop, and upgrade the service from the host installation. ## What your agent launches The setup writes the agent's MCP entry for the installation it detected: | `--mode` | When | The agent runs | | --- | --- | --- | | `tool` | Standalone tool, binary, or no project dependency | `uvx --from vaultspec-rag[mcp] python -m vaultspec_rag.server` | | `dependency` | Runtime project dependency | `uv run --no-sync python -m vaultspec_rag.server` | | `dev` | Development-group dependency | `uv run --no-sync python -m vaultspec_rag.server` | Either form loads no models and forwards every call to the service. The `tool` entry names no release, and a server whose release differs from the service's has its tool calls refused with `service_version_mismatch`. The project forms run without syncing, so run `uv sync` after changing the project's dependencies. [MCP integration](mcp.md) covers client configuration and the tools. ## Upgrade A client refuses a service from any other release, so upgrade the host installation and every client together. Package upgrades acquire new code; `install --upgrade` refreshes repository artifacts from the code you are running. 1. Close connected agent sessions and run `vaultspec-rag server stop`. 2. Upgrade the host: `uv tool upgrade vaultspec-rag` for a standalone tool, `uv sync --upgrade-package vaultspec-rag` for a project dependency, `scoop update vaultspec-rag` or `brew upgrade vaultspec-rag` for a binary. 3. Check the upgraded host's `vaultspec-rag --version`, then pin each client project to that release with `uv add --dev "vaultspec-rag[mcp]=="`. 4. In each repository, run `vaultspec-rag install --upgrade` (with `uv run` for a project installation), repeating any `--local-only`, `--no-mcp`, or `--no-torch-config` you used. 5. Start the service once from the updated host installation with `vaultspec-rag server start`, supplying its environment settings, then run `vaultspec-rag server doctor`. A running service keeps the code and settings it started with until it restarts. Indexes created with the former SPLADE sparse model are incompatible with SPARSEUP. Rebuild every repository indexed with that model after starting the updated service: ```sh vaultspec-rag --target index --rebuild --type all ``` Wait for each rebuild to complete and [verify the index](verification.md) before searching. Neither `install --upgrade` nor automatic file watching migrates these vectors; a `full_reindex_required` result needs this explicit rebuild. A standalone tool installed without the two index options upgrades to CPU-only PyTorch; `server doctor` says so and names the repair below. ### Environment settings during setup and startup Set download, cache, model, and backend variables in the process environment before running `install` or `install --upgrade`, and supply matching settings to the host process that runs `server start`. A client shell's settings do not change a service that is already running. RAG does not import settings with Core's `--env` or `--env-file` flags, and it does not read Core's `.vaultspec/.env` store. The workspace-root `.env` can supply only RAG's TypeSafe key, from an eligible project environment. See [environment loading](../guides/typesafe-env.md#rag-set-the-key-where-the-service-starts) for that eligibility and when to restart the service. ## When something goes wrong - `vaultspec-rag` isn't found: for a standalone tool, run `uv tool update-shell` and open a new terminal; for a project dependency, use `uv run vaultspec-rag`. - A default model download fails: check network access and the cache findings in [the provisioning reference](provisioning.md). Default models require no login. - `server start` says the installation is a client: start the service from the host installation. - Commands report that no service is running: start it from the host installation. - Commands refuse to run against the service and name two releases: move the older side to the newer release, as in [upgrade](#upgrade). - `install` refuses to edit `pyproject.toml`: rerun with `--yes`, or with `--no-torch-config` to manage PyTorch yourself. The [service troubleshooting](service-mode.md#troubleshooting) and [index verification](verification.md) pages cover the rest. To remove a repository's setup, see [uninstall](cli.md#uninstall). ### Pin the GPU build A standalone tool on Linux or Windows with missing or CPU-only PyTorch, or whose upgrade record lacks the CUDA source, is repaired in place. Apple silicon never needs this. ```sh vaultspec-rag server doctor vaultspec-rag install --yes --no-torch-config vaultspec-rag server stop vaultspec-rag server start ``` `server doctor` names the build and prints the two repair commands; `install --yes --no-torch-config` applies them and verifies the result. Nothing has to be stopped during the repair, but the service and any agent session running the MCP server keep their old PyTorch until they restart. Don't force a reinstall with `uv tool install --force` while either still runs: it can leave the tool missing packages. ### Server start cannot find the Qdrant binary The managed service uses a pinned, verified Qdrant binary. It does not look for `qdrant` on `PATH` or in the current directory. Host setup and service startup provision the managed binary when needed; a client never does. ### A Qdrant on PATH is no longer used To supply your own binary, set both `VAULTSPEC_RAG_QDRANT_BINARY` (an absolute path to a regular file, not a link) and `VAULTSPEC_RAG_QDRANT_BINARY_SHA256` (its SHA-256 digest) in the process environment before setup or startup. Supplying only one, or an invalid path or digest, fails instead of falling back to another binary. See [provisioning](provisioning.md) for supported binaries, cache verification, and download troubleshooting. --- ## 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/` | One append-only ledger per plan: files changed and checks run, per step | Follow the approved plan | | Review | `.vault/audit/` | Findings and their resolutions | 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 Review the architecture decision before planning and the plan before implementation. The installed skills use your existing authorization when it covers the work. They do not promise a fixed number of approval prompts. Reject an ADR that leaves a requirement 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 uvx vaultspec-core status ``` ## Where to go next - [Run a feature from research to review](guides/workflow.md) - what to review at each stage. - [Core CLI reference](core/cli.md) - exact commands and advanced plan management. - [Document syntax](core/syntax.md) - the structure of records created by Core. --- ## One Feature, End to End Start from the [documentation home](../index.md) to install Core and create a record. Then [connect your agent](mcp.md) so it can read and update project records. ## Check the starting point Use this prompt to check the connection and find existing work: ```{code-block} none :class: vs-block-prompt Use the vaultspec-core MCP status tool to show the status of this project. Tell me which features exist and whether any plan is in flight. Do not change any files. ``` In the tested quickstart project, Codex called the Core status tool and reported one `notes-search` research record and no plan. If the tool is unavailable, use the [connection checks](mcp.md#check-that-it-connected). ## Start a feature record If you completed the quickstart, keep its `notes-search` record. In a project that does not have that record yet, this prompt starts it through the agent: ```{code-block} none :class: vs-block-prompt Use the vaultspec-core MCP create tool to create a research record with feature notes-search and title Search project notes. Report the created path. Do not implement code. ``` The tested Codex session created the dated Markdown file and returned its path. Open it to see the research template. It still needs the question, findings, and sources; creating it does not perform the investigation. (research-the-problem)= ## Move from a question to reviewed work The installed skills describe the workflow. Each stage has a different result: | Stage | What you review | Installed skill | | --- | --- | --- | | Investigate | Evidence, existing behavior, and alternatives | `vaultspec-research` or `vaultspec-code-research` | | Decide | A proposed architecture decision record (ADR), when a decision needs one | `vaultspec-adr` | | Plan | Scoped steps and how each will be checked | `vaultspec-write` | | Implement | Code changes and recorded verification for the approved steps | `vaultspec-execute` | | Review | Findings against the implementation | `vaultspec-code-review` | Review the proposed decision and plan before authorizing implementation. Existing decisions and sufficient evidence can be reused; a small task need not create every kind of record. [How vaultspec works](../concepts.md) explains these terms. These are skill responsibilities, not a fixed sequence of chat messages. The agent's tools, project instructions, and your authorization affect what happens next. The two tested prompts check status and create a record. They do not run the complete feature workflow. ## Check progress and the result ```sh uvx vaultspec-core status uvx vaultspec-core vault list --feature notes-search ``` Keep the feature tag consistent so its records stay grouped. If you used another tag, substitute it for `notes-search`. Read the code diff and actual test results alongside the records. A checked step or a clean record check does not establish that the implementation works. See [review and correctness](../core/correctness.md). (make-the-check-a-gate)= ## Where to go next Use the [command-line guide](cli.md) to create and find records yourself. The [CLI reference](../core/cli.md) covers plan editing and execution logging; [workspace verification](../core/verification.md) covers record checks. --- ## Use the command line Run these commands from your project root after [installing Core](../core/installation.md). The examples use `uvx`; change the prefix if you chose a [tool or project installation](../core/installation.md#how-you-run-it-afterwards). (orient-before-you-do-anything)= (if-your-agent-has-no-skills)= ## Find your work ```sh uvx vaultspec-core status uvx vaultspec-core vault feature list ``` Status shows plans in flight and recent records. The feature list also finds work that has records but no plan. To list records for the quickstart's feature: ```sh uvx vaultspec-core vault list --feature notes-search ``` Feature-specific `status` needs a plan to trace. Before a plan exists, `status notes-search` exits `1` with an unresolved target, so use the record list until then. (create-documents-never-hand-write-them)= ## Create a record If you haven't created the quickstart record yet, run: ```sh uvx vaultspec-core vault add research --feature notes-search --title "Search project notes" ``` Open the path printed after `Created:`. The command supplies the filename and metadata; you or your agent must fill in the research. It does not investigate the subject or implement code. Use one feature tag, such as `notes-search`, for related work. See the [creation reference](../core/cli.md#vaultspec-core-vault-add) for other document types. (what-the-exit-code-gates-on)= (gate-a-pipeline-on-it)= ## Check records ```sh uvx vaultspec-core vault check all ``` Read the findings as well as the exit code. The untouched research template in this walkthrough produces five warnings and exit code `0`; only errors fail the check. A successful check does not mean the research is finished or the code is correct. Fill in the record, then check again. The [verification guide](../core/verification.md) explains checks, repairs, and automation. ## Get JSON output ```sh uvx vaultspec-core status --json uvx vaultspec-core vault list --feature notes-search --json ``` These return the same project state and record listing in machine-readable form. Every `--json` command emits one [output envelope](../core/cli.md#json-output-envelope). (work-a-plan)= ## Where to go next [Run a feature](workflow.md) explains what to review at each stage. For editing steps, recording completed work, renaming a feature, or archiving records, use the [plan and feature commands](../core/cli.md#command-index). --- ## Reaching Vaultspec From Your Agent Core exposes project operations through the Model Context Protocol (MCP). Your coding agent calls these tools to find records and report progress. ## Point your agent at it Complete the [Core installation](../core/installation.md) in your project, then open that project in your agent. The default installation writes Core's server entry to these locations: | Agent | Generated MCP configuration | | --- | --- | | Claude Code | `.mcp.json` | | Codex | `.codex/config.toml` | | Antigravity | `.agents/mcp_config.json` | Gemini receives workflow guidance, but this installation does not generate a native Gemini MCP entry. Use the [command-line guide](cli.md) when your agent has no Core MCP tool. The prompt walkthrough here was tested with Codex. For example, the generated `.mcp.json` entry is: ```json { "mcpServers": { "vaultspec-core": { "command": "uvx", "args": ["--from", "vaultspec-core", "python", "-m", "vaultspec_core.mcp_server.app"] } } } ``` This is generated configuration, not another setup step to copy. A `dev` or `dependency` [installation](../core/installation.md#choose-a-provisioning-mode) launches the server with `uv run --no-sync` from the project environment instead. Your agent must enable and trust the server according to its own controls. The installer does not grant that trust. ## Check that it connected After the [quickstart](../index.md), send: ```{code-block} none :class: vs-block-prompt Use the vaultspec-core MCP status tool to show the status of this project. Tell me which features exist and whether any plan is in flight. Do not change any files. ``` The tested Codex session called Core's `status` tool and reported `notes-search` with one research record and no plan. Inspect the tool call as well as the reply: the reply should be based on the project's current state. If the agent cannot find the tool, check that it opened the right project and enabled the configured server. Compare the result with: ```sh uvx vaultspec-core status ``` If terminal commands are blocked, check the agent's permissions separately from its MCP connection. ## Two products, one file Core manages records; vaultspec-rag searches them and your code. In a project with Core installed, vaultspec-rag's setup writes a `vaultspec-rag` entry beside Core's. Keep both. That entry launches a small server that forwards each search to the machine's vaultspec-rag service. Searches need that service running and the project indexed; follow [vaultspec-rag setup](../rag/installation.md) and [how vaultspec-rag runs](rag-service.md). (withholding-the-destructive-tools)= (the-hot-path)= ## Where to go next For the complete tool set and read-only server options, see the [Core MCP reference](../core/mcp.md). For key resolution and environment sources, see [TypeSafe and environment loading](typesafe-env.md). Continue with [Run a feature](workflow.md) once the status check works. --- ## How vaultspec-rag Runs vaultspec-rag is two programs you set up separately. You install a search service and start it yourself. Your agent launches a small MCP server that reaches that service. Both run on your machine, and neither listens beyond loopback. ```{raw} html
The four parts of a vaultspec-rag setup and who starts each Four boxes in a row. Your agent reads its MCP configuration and starts the MCP server. The MCP server, vaultspec-search-mcp, talks to the agent over stdio, loads no models, and forwards every call to the search service. You start the search service; it listens on 127.0.0.1:8766 and runs the models on the GPU. It keeps its index in a store that is either a managed server on 127.0.0.1:8765 or, with --local-only, a directory on disk. The agent starts the first two; you start the last two. vaultspec-core's own MCP server is a separate entry in the same configuration and never calls this service. your agent MCP server search service index store reads .mcp.json and starts the MCP server stdio, loads no models, forwards calls 127.0.0.1:8766, models on the GPU managed on :8765, or on disk: --local-only started by your agent started by you: server start vaultspec-core's MCP server is a separate entry in the same .mcp.json and never calls this service
  1. your agentreads its MCP configuration and starts the MCP server
  2. MCP servervaultspec-search-mcp over stdio; it loads no models and forwards every call
  3. search serviceyou start it; it listens on 127.0.0.1:8766 and runs the models on the GPU
  4. index storea managed server on 127.0.0.1:8765, or a directory on disk with --local-only

vaultspec-core's MCP server is a separate entry in the same .mcp.json and never calls this service.

Your agent starts its MCP server. You start the search service, once, and it serves every project on the machine.
``` ## What you install One package holds the command, the service and the MCP server. The service needs the `[gpu]` extra and the MCP server needs the `[mcp]` extra, so a machine that runs all of it takes `vaultspec-rag[gpu,mcp]`. The release binaries carry both. An environment that only talks to a running service can leave `[gpu]` out; [choose what each environment runs](../rag/installation.md#choose-what-this-environment-runs) has the combinations. `vaultspec-rag install` sets up the project and writes the MCP entry your agent reads. A host with a usable accelerator also provisions the models and the store's server binary; a client skips every download. Host `server start` provisions any missing files before startup. Check the [requirements](../requirements.md) first. The service runs only on a supported GPU. Its default models are public and need no Hugging Face token; [provisioning](../rag/provisioning.md) explains the downloads. ## You start the service ```bash uv run vaultspec-rag server start ``` That starts the managed store on `127.0.0.1:8765`, loads the models once, and serves on `127.0.0.1:8766` until you stop it. Later searches reuse the loaded models, which is why it stays running. Drop the `uv run` prefix if you installed a standalone tool or a binary. The service runs in the Python environment that launched it, and that environment's PyTorch build decides the GPU. Start it from an installation with the `[gpu]` extra; one without it cannot start the service. [Which Python environment runs the service](../rag/service-mode.md#which-python-environment-runs-the-service) explains why. To keep the index in a directory instead of a managed server, add `--local-only`. That changes storage only; the models still run on the GPU. See [storage backends](../rag/backends.md). Nothing starts the service for you at login. vaultspec-rag ships no system service, so wrap `server start` yourself if you want that; see [running it automatically](../rag/service-mode.md#running-it-automatically). ## Your agent starts the MCP server The agent reads the entry `install` wrote and launches the MCP server as a child process over stdio. The entry runs it through `uvx` or through the project's environment, depending on how vaultspec-rag is installed; [what your agent launches](../rag/installation.md#what-your-agent-launches) shows each form. That process loads no models. It resolves the project, forwards each search to the running service, and tags the call with the project so one service can answer for many. The service does not speak MCP, and no client connects to it directly. [How the connection works](../rag/mcp.md#how-the-connection-works) has the detail, and [Use vaultspec-rag with MCP clients](../rag/mcp.md) covers client setup and the tools it exposes. ## vaultspec-core's MCP server is separate vaultspec-core has its own MCP server for records, plans and checks. It sits beside vaultspec-rag's entry in the same `.mcp.json` and never calls the search service. [Connect your agent](mcp.md#two-products-one-file) shows the two entries together and what happens when they are installed in different modes. ## One service for every project Only one service runs per machine, because it owns the GPU and the managed store. It keeps a slot for each project it has served and drops idle ones on its own. A new git worktree of a project it has already indexed reuses the vectors it can, rather than encoding everything again. - [Manage projects](../rag/service-mode.md#manage-projects) - [Reusing vectors across worktrees](../rag/indexing.md#reusing-vectors-across-worktrees) ## Day to day | To | Run | | --- | --- | | Start it | `uv run vaultspec-rag server start` | | See whether it is up | `uv run vaultspec-rag server status` | | Find out why it is not healthy | `uv run vaultspec-rag server doctor` | | Read its log | `uv run vaultspec-rag server logs` | | Stop it | `uv run vaultspec-rag server stop` | On Windows, `server stop` cannot signal the detached service, so it ends it with a bounded force-stop and cleans up after it. [Stop and restart the service](../rag/service-mode.md#stop-and-restart-the-service) has the details. ## When the service is not running A search does not quietly load the models into the calling process. It fails, names the problem and suggests the fix, so a stopped service is never mistaken for an empty result. The same happens when the command-line tool and the running service are different releases. [Troubleshooting](../rag/service-mode.md#troubleshooting) covers ports in use, a service that will not stop, and a store that will not start. ## Where to go next - [Install vaultspec-rag](../rag/installation.md) - [Your first search](../rag/getting-started.md) - [The background service in full](../rag/service-mode.md) --- ## vaultspec-core Core installs the workflow, configures supported coding agents, and manages the feature records under `.vault/`. It runs without [vaultspec-rag](../rag/index.md), but the workflow is designed around its semantic search: agents look for evidence by meaning first, and fall back to listing and `grep` without it. ## Start - [Install Core](installation.md) - [Understand the workflow](../concepts.md) - [Run a feature](../guides/workflow.md) - [The workflow in depth](framework.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: installation framework syntax correctness verification channels mcp cli ``` --- ## vaultspec-rag vaultspec-rag indexes vaultspec records, source code, and routed documents for search by meaning. It is the search engine the vaultspec workflow is designed around: optional for Core, which falls back to listing and `grep` without it. It depends on Core, so installing it installs Core too, and it also searches repositories that don't use the workflow. Its search service needs a supported GPU: NVIDIA with CUDA on Linux or Windows, or Apple silicon on macOS. ## Start - [Install vaultspec-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) - [Model and index-server provisioning](provisioning.md) - [Storage backends](backends.md) - [Storage maintenance](storage-maintenance.md) - [Automation](automation.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 the failing command, its error, and the output of `vaultspec-rag server doctor --json`, `vaultspec-rag server status --json`, and `vaultspec-rag server logs`. Redact credentials and private content before posting. Released under the [MIT License](https://github.com/nevenincs/vaultspec-rag/blob/main/LICENSE). ```{toctree} :hidden: installation getting-started query-craft verification configuration mcp service-mode provisioning automatic-convergence backends storage-maintenance automation preprocessing-hooks service-discovery indexing search-and-index architecture cli ``` --- ## Complete published content - [All page Markdown](https://vaultspec.neve.md/docs/llms.txt) - [Structured page catalog](https://vaultspec.neve.md/content-index.json)