vaultspec-dashboard

The human-facing visual workspace for a Vaultspec project.

What it does · Project layout · Getting started · Capabilities · Vaultspec family · Documentation · Status

Complete Vaultspec workspace showing the project and worktree selector, Vault and Files navigation, populated graph, timeline, and activity

The complete workspace keeps repository context, vault content, relationships, history, and current activity in one view.

What it does

Project knowledge often spans source files, Git history, worktrees, current activity, and .vault/. This Git-tracked directory stores research, decisions, plans, execution records, and audits. File browsers show each item but hide the relationships between them.

vaultspec-dashboard brings this work into one visual workspace. Choose a project and worktree, then browse documents or source files beside focused, switchable vault and code graphs. Inspect changes, open work, and history without turning the entire project into an unreadable graph. Search by file or title, with optional semantic search for meaning-based discovery. Author and review Markdown without leaving the workspace.

Visual tour

Markdown decision document open within its vault and repository context beside the populated graph

Open a document from Documents > Decisions without losing its workspace and graph context.

Search documents and code with a real query, scoped result controls, and populated results.

Activity and status view showing open plans and the running search service

Review current open plans and search-service state from the running workspace.

Project layout

Project responsibilities

Project	Responsibility
vaultspec-core	Governs the workflow and `.vault/` record. Owns validation, command-line and Model Context Protocol (MCP) surfaces, and authoritative document materialization.
vaultspec-rag	Provides optional retrieval-augmented generation (RAG). Indexes vault documents and source code, then retrieves both by meaning.
vaultspec-dashboard	Owns the `vaultspec` binary, visual workspace, application programming interface (API), session state, and governed review experience.

The dashboard delegates governed writes to core and semantic retrieval to RAG. It uses the core command-line interface, RAG's local service API for reads, and bounded RAG commands for explicit lifecycle actions.

Installed runtime

The dashboard installs as a complete product tree, not a single file. Every supported channel places the same set:

Part	What it is
`vaultspec`	The dashboard executable: engine, API, live event stream, and web interface in one native Rust binary. Run `vaultspec serve` from a managed worktree. The command prints a local URL.
`vaultspec-updater`	A separate executable that installs a new release while the dashboard is stopped, so an update never rewrites files the running application holds open.
Manifest, licenses, and bill of materials	The digest of every installed file, third-party license texts, and the software bill of materials (SBOM).

That list is the whole tree. No agent-to-agent runtime is bundled, and its absence is a decision rather than an omission: the dashboard resolves that runtime from ~/.vaultspec/a2a/generations/ in your home directory, never from its own install directory, and no shipped operation populates that location yet — adoption is declared but not implemented. Bundling one would therefore have added roughly 269 MB, the overwhelming majority of the download, for a directory the dashboard never reads. It returns to the release when adoption is implemented; until then the agent-to-agent capabilities are unavailable rather than half-present. Nothing downloads on first run either way, so the network is needed only to fetch the release.

After placing the tree, every installer checks it against the release manifest with the shipped verifier, vaultspec verify-release. A tree that fails that check is a failed install. A partial or binary-only install isn't supported.

The dashboard uses two independently installed companions:

vaultspec-core supplies governed vault operations. Without core, the dashboard warns and continues with those capabilities unavailable. Full authoring requires core 0.1.34 or later.
vaultspec-rag supplies optional semantic search. The dashboard discovers the machine-wide service and can broker explicit lifecycle actions. Stopping it also affects its other clients.

A source checkout uses a separate Vite and Rust development loop; it isn't the installed product model.

Current-main vaultspec status output showing the active worktree, graph index, core invocation, RAG availability, seat, and watcher

This current-main status capture is generated from real vaultspec --json status output against this worktree. Its lifecycle fields may be newer than the latest release.

Getting started

Prerequisites and installation

vaultspec-dashboard supports four platforms:

macOS on Apple silicon
Linux on arm64, glibc 2.28 or newer
Linux on x64, glibc 2.28 or newer
Windows on x64

Intel macOS isn't supported.

Both Linux binaries are built inside a digest-pinned manylinux_2_28 image, so that floor is enforced by the build environment rather than inherited from whichever machine happened to run the build. It covers the current enterprise LTS releases — RHEL 8 and 9 and their rebuilds, Debian 12 and 13, Ubuntu 22.04 and newer, Amazon Linux 2023 — and a repository guard fails the build if this sentence and the pinned image ever disagree.

The routes below target the latest published GitHub Release. Development on main may contain lifecycle changes that haven't been released yet.

Every channel installs the same complete tree described under Installed runtime, and verifies it before the install counts as done.

Channel	Platforms	Who installs and updates it	Status
Shell script	macOS, Linux	This project's installer and updater	Awaiting release
PowerShell script	Windows	This project's installer and updater	Awaiting release
MSI	Windows	Windows Installer, with this project's updater	Not built
Scoop	Windows	Scoop	Pending proof
WinGet	Windows	WinGet	Pending proof
`cargo install`, `cargo binstall`	—	—	Not supported

Awaiting release means the artifact is produced and attached by the release pipeline, but no release has yet completed to carry it. Not built means the release does not currently carry that artifact at all. dist-workspace.toml sets installers = [], disabling dist's generated shell and PowerShell installers in favour of the product-owned packaging/install.sh and packaging/install.ps1, which install the complete tree rather than a bare binary. Those two are now published as release assets by the same job that attaches the product archives, so an installer can never appear on a release whose archives are missing — but that job has not yet completed successfully for any release, so no published release carries either script today. No MSI has ever been built.

A channel marked pending proof must still prove install, upgrade, downgrade, repair, and uninstall on a clean machine before it counts as supported. Until it does, prefer a supported channel.

Shell script and PowerShell script are awaiting their first release. Once a release carries them, these are the commands — with no argument, each installs the newest published release:

curl -fsSL https://github.com/nevenincs/vaultspec-dashboard/releases/latest/download/install.sh | bash

&amp; ([scriptblock]::Create((irm https://github.com/nevenincs/vaultspec-dashboard/releases/latest/download/install.ps1)))

bash, not sh: the script uses set -o pipefail, which dash — /bin/sh on Debian and Ubuntu — does not accept. Pass --version (-Version in PowerShell) to pin a release instead of taking the newest. Both verify the downloaded archive against its published .sha256 before placing anything, and run vaultspec verify-release over the installed tree afterwards; a tree that fails either check is a failed install.

Until that first release lands, download the platform archive from Releases and run the binary directly.

Scoop (Windows):

scoop bucket add nevenincs https://github.com/nevenincs/homebrew-tap
scoop install nevenincs/vaultspec-dashboard

The bucket is the ORGANISATION tap nevenincs/homebrew-tap, which serves bucket/ for Scoop and Formula/ for Homebrew across every nevenincs product - a package manager resolves one bucket per organisation, not one per repository. The bucket/ directory that used to live in this repository is no longer the published source. This channel stays pending proof until a release actually publishes a manifest there; vaultspec-core and vaultspec-rag are present today and this product is not.

WinGet (Windows): winget install vaultspec.vaultspec installs the same MSI.

Homebrew (macOS on Apple Silicon; Linux on x86-64 and arm64):

brew tap nevenincs/tap
brew install nevenincs/tap/vaultspec

brew tap nevenincs/tap resolves to the same organisation tap by convention, so unlike Scoop it needs no explicit URL. The product ships as a formula, not a cask: cask-on-Linux is restricted to portable artifact types, and brew's quarantine opt-out has been removed, so a cask would hand macOS users a quarantined un-notarized binary. The formula places the whole release tree under the Cellar's libexec and puts only the vaultspec command on PATH, so the updater, licences, release.json and the SBOM stay beside the binary where vaultspec verify-release can find them. Intel Mac is not served - there is no x86_64-apple-darwin build. Like Scoop, this channel stays pending proof until a release actually publishes a formula to the tap.

Updating

How you update depends on how you installed.

Shell or PowerShell: run vaultspec update. The dashboard stops, hands the replacement to vaultspec-updater, and starts again. No file is swapped underneath the running application, and the previous release stays on disk to return to.
MSI: run vaultspec update. The updater applies the new package through Windows Installer rather than editing installed files. To return to an earlier release, install its package.
Scoop or WinGet: update through the manager — scoop update vaultspec or winget upgrade vaultspec.vaultspec. vaultspec update refuses on a manager-installed copy and names the command to run instead.
Homebrew: brew upgrade vaultspec, and brew uninstall vaultspec to remove it. Do not run vaultspec update on a Homebrew copy: it does not refuse there — the only thing it checks is whether vaultspec-updater sits beside the dashboard, and the formula installs them as siblings — so it would hand a release transaction to a helper that rewrites files Homebrew owns.

Removing it, and what stays

Uninstalling removes the installed tree and the records the product keeps about its own releases. It leaves your work alone.

Shell: install.sh --uninstall
PowerShell: install.ps1 -Uninstall
MSI: uninstall vaultspec from Apps & features
Scoop: scoop uninstall vaultspec
WinGet: winget uninstall vaultspec.vaultspec

Your data survives because it never lives in the install directory. Vault documents stay in your project's Git repository, and per-user application state stays in .vaultspec in your home directory.

> Not supported: cargo install and cargo binstall. Either would place only the > vaultspec binary, without the updater, the release manifest, or the > verification, update, and removal guarantees that depend on them. vaultspec-cli stays > off crates.io until a Cargo channel can carry the complete product. Use a channel from > the table instead. > > Note on code signing: the installers, MSI, and binary archives are currently > unsigned. macOS Gatekeeper will quarantine the binary on first run - right-click the > binary, choose Open, and confirm the override prompt. Windows SmartScreen may show > an "Unknown publisher" warning - click More info then Run anyway to proceed.

Confirm the installation:

vaultspec --version

Your project must use Git. Governed capabilities also require vaultspec-core 0.1.34 or later. Install it separately with uv:

uv tool install 'vaultspec-core&gt;=0.1.34'

From the project directory, verify that the project is ready:

git rev-parse --is-inside-work-tree
vaultspec-core --version
vaultspec-core status --json -t .

The Git command must print true. The core version must be 0.1.34 or later. The status command must exit successfully, proving that core can read the managed vault.

If the project isn't managed yet, create only the core scaffolding:

vaultspec-core install core -t .

This command modifies the project by installing the core vault structure and configuration. Review the vaultspec-core getting-started guide before applying it to an existing project.

The walkthrough that follows uses an existing managed project with at least one decision record. A freshly scaffolded project contains no records yet. Follow the Vaultspec framework to create meaningful project records before continuing.

Start the dashboard

From the managed Git worktree, run:

vaultspec serve

Keep the terminal open. When the service is ready, it prints:

vaultspec serve: listening on http://127.0.0.1:8767 (bearer token in service.json)

Open http://127.0.0.1:8767 in your browser. A successful dashboard shows the current worktree selector, Vault/Files browser, populated graph, timeline, and activity rail. The complete workspace capture shows this result.

Optional semantic search

vaultspec-rag adds optional semantic search. Name matching remains available without it.

The current vaultspec-rag service runtime requires:

CPython 3.13.x
An NVIDIA CUDA-capable graphics processor (GPU) with about 3 GB of free video memory
Linux or Windows

macOS, AMD GPUs, and Apple silicon aren't supported. The service has no central processing unit (CPU) fallback. The dashboard requires vaultspec-rag 0.2.28 or later, but it doesn't verify the resident version.

Install vaultspec-rag in the project's Python environment. A global uv tool installation isn't suitable for launching its GPU service.

uv add vaultspec-rag
uv run vaultspec-rag install
uv sync
uv run vaultspec-rag server start
uv run vaultspec-rag index
uv run vaultspec-rag server jobs

Wait for the vault and code jobs to finish before using semantic search. Follow the installation guide and getting-started guide for the complete setup.

When the service is offline, Search service reports that it isn't running. Search falls back to literal document and code-name matching and may report:

> Full search is unavailable — showing name matches only.

Follow one record from vault to search

Check the current location: project / worktree selector.

Expected result: The selector names the project and worktree whose vault you're viewing. When it names the intended workspace, leave it unchanged.
In Vault mode, expand Documents, then expand Decisions.

Expected result: Decision records appear beneath Decisions.
Select a decision record with a single click.

Expected result: The record becomes the current selection. The graph uses the same selection.
Double-click the record, or press Enter, to open it in the docked reader.

Expected result: The reader shows a breadcrumb, type, title, date, and body. It also shows View and Edit when editing is available.
Move focus to the graph canvas, then use the arrow keys to walk through connected nodes.

Expected result: The shared selection moves through the graph. Press Enter to open the selected record, E to expand it, or Escape to clear the selection.
Press Command+P on macOS or Ctrl+P on Windows and Linux.

Expected result: Search documents and code opens with All, Docs, and Code scopes.
Choose Docs, enter part of the decision title, and press Enter on the selected result.

Expected result: The matching decision opens in the docked reader.

Capabilities

See Visual tour for the corresponding workspace, document, search, and status views.

User goal	Mounted view	Boundary
Browse project content	Project and worktree selector; Vault and Files browser	Shows registered projects and worktrees, the vault tree, and the code tree.
Explore relationships and history	Desktop graph with timeline, filters, and minimap	Switches between vault and code corpora. It doesn't mix them. The graph isn't available in compact or mobile layouts.
Inspect a document or source file	Docked Markdown viewer or read-only code viewer	Code inspection includes syntax highlighting, line numbers, and copy. Code editing isn't supported.
Edit vault content	Markdown authoring view with View/Edit, toolbar, properties, rename, and save controls	Supports approved vault Markdown writes when authoring is available. Core materializes approved changes.
Search documents and code	`Mod+P` command palette with All, Docs, and Code scopes	Combines semantic and literal search, returns a bounded result set, and opens selections in the viewer.
Monitor and review work	Activity and status rail	Covers changes, open plans, pull requests, issues, commits, search service status, approvals, and reviews. Sections can degrade independently.

When a capability is unavailable

The dashboard keeps unaffected features available when a data source or browser capability fails. Each affected view reports its own limitation.

Unavailable capability	What the interface says	What remains usable
vaultspec-core	The server warns and continues. The graph may say `Links unavailable — the rest of the graph is live`.	Structural graph nodes, independent data, and supported reads remain. Declared links and authoring are unavailable.
Semantic search	Search may say `Full search is unavailable — showing name matches only.` Search service says `Search service not running`.	Document-metadata and code-name matches, graph, browsing, timeline, reading, and GitHub data remain.
GitHub data	Pull-request and issue sections report that the `gh` command-line interface (CLI) isn't available or that GitHub is unavailable.	Local Git history, vault content, graph, plans, and search remain.
Browser graphics	The canvas says `Graphics unavailable`. After context loss, it says `Restoring graphics…`.	Non-canvas views remain while the canvas recovers or graphics stay unavailable.
Some graph relationships	The graph reports `Links unavailable — the rest of the graph is live`, `Mentions unavailable — the rest of the graph is live`, or `Timeline unavailable — the rest of the graph is live`.	The available graph stays visible without the missing relationship type.
The entire graph	The view says `Graph is not available`.	Non-graph views and any other available capabilities remain.

Glossary

Term	Meaning
Vaultspec	A four-project family: vaultspec-core, vaultspec-rag, vaultspec-dashboard, and vaultspec-a2a.
vault or `.vault/`	A project directory containing structured Markdown research, decisions, plans, execution records, and audits.
vault document	One structured Markdown artifact stored in a vault.
Vaultspec pipeline	An approval-gated flow through Research, Decide, Plan, Execute, and Verify. See the Vaultspec framework.
Architecture Decision Record (ADR)	A record of a binding project decision and its reasoning.
semantic search	Search that ranks indexed text by meaning, not only by exact words. See the search and indexing guide.
vaultspec-core	The governed workflow, command-line interface, validators, and vault-document tooling.
vaultspec-rag	The optional retrieval service that indexes vault documents and code.
workspace	A registered Git project root.
worktree	One checked-out working copy used for the current operation.

Vaultspec family

Project	Role	Status
vaultspec-core	The agent harness: the pipeline, the vault, and the CLI that drives them.	Beta
vaultspec-rag	The semantic search component for vault and code.	Beta
vaultspec-dashboard	The application that runs it all as a UI.	Beta
vaultspec-a2a	Headless agent-to-agent orchestration.	Beta

Documentation

Task	Documentation
Install the dashboard	Download the latest release
Learn the core workflow	Read the Vaultspec framework guide
Use vaultspec-core	Core command-line interface (CLI) reference · Core MCP reference
Diagnose a core project	Run the core health doctor
Install vaultspec-rag	RAG installation guide
Search and index content	RAG search and indexing guide
Use vaultspec-rag	RAG CLI reference · RAG MCP reference
Troubleshoot the RAG service	Service-mode troubleshooting
Review dashboard changes	Dashboard engine release notes
Report an application problem	Open a dashboard issue

Status and license

Status: Beta. vaultspec-dashboard is public, unarchived, and actively developed. See GitHub Releases for current releases and the changelog for release details.

Report bugs and request features through GitHub Issues. Include:

Output from vaultspec --version
Operating system, platform, and installation method
Exact command and working directory
When applicable, selected worktree or --scope
Steps to reproduce the problem
Output from vaultspec --json status
A relevant error excerpt or screenshot
vaultspec-rag health details for semantic-search issues only

Keep diagnostics focused. Redact credentials, tokens, private paths, and private content before submitting a report.

License: MIT.

Contributing

These instructions apply to a source checkout. They don't install a published release.

Install the toolchain, synchronize development dependencies, and start the Vite and Rust development servers:

mise install
just deps sync
just serve

Run the relevant quality checks before submitting changes:

just lint all
just test all
just test e2e
just ci

just test all runs the Rust and Vitest suites. End-to-end tests run separately with just test e2e.

Build the embedded, single-binary product with:

just build package

Use mise.toml and the justfile as the authoritative task definitions. For design work, use:

Read the current-main application lifecycle when working on unreleased launch, update, or single-instance behavior.

Release automation lives in the Release Please workflow and distribution workflow. Use conventional commits and let Release Please update the engine changelog.

Regenerate terminal README assets with:

just docs readme-assets

To regenerate application captures, keep just serve running in one terminal. Run the capture task in another:

npm --prefix frontend run readme:capture

The capture task generates the README figures and their manifest.

vaultspec-dashboard

The human-facing visual workspace for a Vaultspec project.

What it does · Project layout · Getting started · Capabilities · Vaultspec family · Documentation · Status

Complete Vaultspec workspace showing the project and worktree selector, Vault and Files navigation, populated graph, timeline, and activity

The complete workspace keeps repository context, vault content, relationships, history, and current activity in one view.

What it does

Visual tour

Markdown decision document open within its vault and repository context beside the populated graph

Open a document from Documents > Decisions without losing its workspace and graph context.

Search documents and code with a real query, scoped result controls, and populated results.

Activity and status view showing open plans and the running search service

Review current open plans and search-service state from the running workspace.

Project layout

Project responsibilities

Project	Responsibility
vaultspec-core	Governs the workflow and `.vault/` record. Owns validation, command-line and Model Context Protocol (MCP) surfaces, and authoritative document materialization.
vaultspec-rag	Provides optional retrieval-augmented generation (RAG). Indexes vault documents and source code, then retrieves both by meaning.
vaultspec-dashboard	Owns the `vaultspec` binary, visual workspace, application programming interface (API), session state, and governed review experience.

Installed runtime

The dashboard installs as a complete product tree, not a single file. Every supported channel places the same set:

Part	What it is
`vaultspec`	The dashboard executable: engine, API, live event stream, and web interface in one native Rust binary. Run `vaultspec serve` from a managed worktree. The command prints a local URL.
`vaultspec-updater`	A separate executable that installs a new release while the dashboard is stopped, so an update never rewrites files the running application holds open.
Manifest, licenses, and bill of materials	The digest of every installed file, third-party license texts, and the software bill of materials (SBOM).

The dashboard uses two independently installed companions:

vaultspec-core supplies governed vault operations. Without core, the dashboard warns and continues with those capabilities unavailable. Full authoring requires core 0.1.34 or later.
vaultspec-rag supplies optional semantic search. The dashboard discovers the machine-wide service and can broker explicit lifecycle actions. Stopping it also affects its other clients.

A source checkout uses a separate Vite and Rust development loop; it isn't the installed product model.

Current-main vaultspec status output showing the active worktree, graph index, core invocation, RAG availability, seat, and watcher

This current-main status capture is generated from real vaultspec --json status output against this worktree. Its lifecycle fields may be newer than the latest release.

Getting started

Prerequisites and installation

vaultspec-dashboard supports four platforms:

macOS on Apple silicon
Linux on arm64, glibc 2.28 or newer
Linux on x64, glibc 2.28 or newer
Windows on x64

Intel macOS isn't supported.

The routes below target the latest published GitHub Release. Development on main may contain lifecycle changes that haven't been released yet.

Every channel installs the same complete tree described under Installed runtime, and verifies it before the install counts as done.

Channel	Platforms	Who installs and updates it	Status
Shell script	macOS, Linux	This project's installer and updater	Awaiting release
PowerShell script	Windows	This project's installer and updater	Awaiting release
MSI	Windows	Windows Installer, with this project's updater	Not built
Scoop	Windows	Scoop	Pending proof
WinGet	Windows	WinGet	Pending proof
`cargo install`, `cargo binstall`	—	—	Not supported

A channel marked pending proof must still prove install, upgrade, downgrade, repair, and uninstall on a clean machine before it counts as supported. Until it does, prefer a supported channel.

Shell script and PowerShell script are awaiting their first release. Once a release carries them, these are the commands — with no argument, each installs the newest published release:

curl -fsSL https://github.com/nevenincs/vaultspec-dashboard/releases/latest/download/install.sh | bash

&amp; ([scriptblock]::Create((irm https://github.com/nevenincs/vaultspec-dashboard/releases/latest/download/install.ps1)))

Until that first release lands, download the platform archive from Releases and run the binary directly.

Scoop (Windows):

scoop bucket add nevenincs https://github.com/nevenincs/homebrew-tap
scoop install nevenincs/vaultspec-dashboard

WinGet (Windows): winget install vaultspec.vaultspec installs the same MSI.

Homebrew (macOS on Apple Silicon; Linux on x86-64 and arm64):

brew tap nevenincs/tap
brew install nevenincs/tap/vaultspec

Updating

How you update depends on how you installed.

Shell or PowerShell: run vaultspec update. The dashboard stops, hands the replacement to vaultspec-updater, and starts again. No file is swapped underneath the running application, and the previous release stays on disk to return to.
MSI: run vaultspec update. The updater applies the new package through Windows Installer rather than editing installed files. To return to an earlier release, install its package.
Scoop or WinGet: update through the manager — scoop update vaultspec or winget upgrade vaultspec.vaultspec. vaultspec update refuses on a manager-installed copy and names the command to run instead.
Homebrew: brew upgrade vaultspec, and brew uninstall vaultspec to remove it. Do not run vaultspec update on a Homebrew copy: it does not refuse there — the only thing it checks is whether vaultspec-updater sits beside the dashboard, and the formula installs them as siblings — so it would hand a release transaction to a helper that rewrites files Homebrew owns.

Removing it, and what stays

Uninstalling removes the installed tree and the records the product keeps about its own releases. It leaves your work alone.

Shell: install.sh --uninstall
PowerShell: install.ps1 -Uninstall
MSI: uninstall vaultspec from Apps & features
Scoop: scoop uninstall vaultspec
WinGet: winget uninstall vaultspec.vaultspec

Your data survives because it never lives in the install directory. Vault documents stay in your project's Git repository, and per-user application state stays in .vaultspec in your home directory.

Confirm the installation:

vaultspec --version

Your project must use Git. Governed capabilities also require vaultspec-core 0.1.34 or later. Install it separately with uv:

uv tool install 'vaultspec-core&gt;=0.1.34'

From the project directory, verify that the project is ready:

git rev-parse --is-inside-work-tree
vaultspec-core --version
vaultspec-core status --json -t .

The Git command must print true. The core version must be 0.1.34 or later. The status command must exit successfully, proving that core can read the managed vault.

If the project isn't managed yet, create only the core scaffolding:

vaultspec-core install core -t .

This command modifies the project by installing the core vault structure and configuration. Review the vaultspec-core getting-started guide before applying it to an existing project.

Start the dashboard

From the managed Git worktree, run:

vaultspec serve

Keep the terminal open. When the service is ready, it prints:

vaultspec serve: listening on http://127.0.0.1:8767 (bearer token in service.json)

Optional semantic search

vaultspec-rag adds optional semantic search. Name matching remains available without it.

The current vaultspec-rag service runtime requires:

CPython 3.13.x
An NVIDIA CUDA-capable graphics processor (GPU) with about 3 GB of free video memory
Linux or Windows

Install vaultspec-rag in the project's Python environment. A global uv tool installation isn't suitable for launching its GPU service.

uv add vaultspec-rag
uv run vaultspec-rag install
uv sync
uv run vaultspec-rag server start
uv run vaultspec-rag index
uv run vaultspec-rag server jobs

Wait for the vault and code jobs to finish before using semantic search. Follow the installation guide and getting-started guide for the complete setup.

When the service is offline, Search service reports that it isn't running. Search falls back to literal document and code-name matching and may report:

> Full search is unavailable — showing name matches only.

Follow one record from vault to search

Check the current location: project / worktree selector.

Expected result: The selector names the project and worktree whose vault you're viewing. When it names the intended workspace, leave it unchanged.
In Vault mode, expand Documents, then expand Decisions.

Expected result: Decision records appear beneath Decisions.
Select a decision record with a single click.

Expected result: The record becomes the current selection. The graph uses the same selection.
Double-click the record, or press Enter, to open it in the docked reader.

Expected result: The reader shows a breadcrumb, type, title, date, and body. It also shows View and Edit when editing is available.
Move focus to the graph canvas, then use the arrow keys to walk through connected nodes.

Expected result: The shared selection moves through the graph. Press Enter to open the selected record, E to expand it, or Escape to clear the selection.
Press Command+P on macOS or Ctrl+P on Windows and Linux.

Expected result: Search documents and code opens with All, Docs, and Code scopes.
Choose Docs, enter part of the decision title, and press Enter on the selected result.

Expected result: The matching decision opens in the docked reader.

Capabilities

See Visual tour for the corresponding workspace, document, search, and status views.

User goal	Mounted view	Boundary
Browse project content	Project and worktree selector; Vault and Files browser	Shows registered projects and worktrees, the vault tree, and the code tree.
Explore relationships and history	Desktop graph with timeline, filters, and minimap	Switches between vault and code corpora. It doesn't mix them. The graph isn't available in compact or mobile layouts.
Inspect a document or source file	Docked Markdown viewer or read-only code viewer	Code inspection includes syntax highlighting, line numbers, and copy. Code editing isn't supported.
Edit vault content	Markdown authoring view with View/Edit, toolbar, properties, rename, and save controls	Supports approved vault Markdown writes when authoring is available. Core materializes approved changes.
Search documents and code	`Mod+P` command palette with All, Docs, and Code scopes	Combines semantic and literal search, returns a bounded result set, and opens selections in the viewer.
Monitor and review work	Activity and status rail	Covers changes, open plans, pull requests, issues, commits, search service status, approvals, and reviews. Sections can degrade independently.

When a capability is unavailable

The dashboard keeps unaffected features available when a data source or browser capability fails. Each affected view reports its own limitation.

Unavailable capability	What the interface says	What remains usable
vaultspec-core	The server warns and continues. The graph may say `Links unavailable — the rest of the graph is live`.	Structural graph nodes, independent data, and supported reads remain. Declared links and authoring are unavailable.
Semantic search	Search may say `Full search is unavailable — showing name matches only.` Search service says `Search service not running`.	Document-metadata and code-name matches, graph, browsing, timeline, reading, and GitHub data remain.
GitHub data	Pull-request and issue sections report that the `gh` command-line interface (CLI) isn't available or that GitHub is unavailable.	Local Git history, vault content, graph, plans, and search remain.
Browser graphics	The canvas says `Graphics unavailable`. After context loss, it says `Restoring graphics…`.	Non-canvas views remain while the canvas recovers or graphics stay unavailable.
Some graph relationships	The graph reports `Links unavailable — the rest of the graph is live`, `Mentions unavailable — the rest of the graph is live`, or `Timeline unavailable — the rest of the graph is live`.	The available graph stays visible without the missing relationship type.
The entire graph	The view says `Graph is not available`.	Non-graph views and any other available capabilities remain.

Glossary

Term	Meaning
Vaultspec	A four-project family: vaultspec-core, vaultspec-rag, vaultspec-dashboard, and vaultspec-a2a.
vault or `.vault/`	A project directory containing structured Markdown research, decisions, plans, execution records, and audits.
vault document	One structured Markdown artifact stored in a vault.
Vaultspec pipeline	An approval-gated flow through Research, Decide, Plan, Execute, and Verify. See the Vaultspec framework.
Architecture Decision Record (ADR)	A record of a binding project decision and its reasoning.
semantic search	Search that ranks indexed text by meaning, not only by exact words. See the search and indexing guide.
vaultspec-core	The governed workflow, command-line interface, validators, and vault-document tooling.
vaultspec-rag	The optional retrieval service that indexes vault documents and code.
workspace	A registered Git project root.
worktree	One checked-out working copy used for the current operation.

Vaultspec family

Project	Role	Status
vaultspec-core	The agent harness: the pipeline, the vault, and the CLI that drives them.	Beta
vaultspec-rag	The semantic search component for vault and code.	Beta
vaultspec-dashboard	The application that runs it all as a UI.	Beta
vaultspec-a2a	Headless agent-to-agent orchestration.	Beta

Documentation

Task	Documentation
Install the dashboard	Download the latest release
Learn the core workflow	Read the Vaultspec framework guide
Use vaultspec-core	Core command-line interface (CLI) reference · Core MCP reference
Diagnose a core project	Run the core health doctor
Install vaultspec-rag	RAG installation guide
Search and index content	RAG search and indexing guide
Use vaultspec-rag	RAG CLI reference · RAG MCP reference
Troubleshoot the RAG service	Service-mode troubleshooting
Review dashboard changes	Dashboard engine release notes
Report an application problem	Open a dashboard issue

Status and license

Status: Beta. vaultspec-dashboard is public, unarchived, and actively developed. See GitHub Releases for current releases and the changelog for release details.

Report bugs and request features through GitHub Issues. Include:

Output from vaultspec --version
Operating system, platform, and installation method
Exact command and working directory
When applicable, selected worktree or --scope
Steps to reproduce the problem
Output from vaultspec --json status
A relevant error excerpt or screenshot
vaultspec-rag health details for semantic-search issues only

Keep diagnostics focused. Redact credentials, tokens, private paths, and private content before submitting a report.

License: MIT.

Contributing

These instructions apply to a source checkout. They don't install a published release.

Install the toolchain, synchronize development dependencies, and start the Vite and Rust development servers:

mise install
just deps sync
just serve

Run the relevant quality checks before submitting changes:

just lint all
just test all
just test e2e
just ci

just test all runs the Rust and Vitest suites. End-to-end tests run separately with just test e2e.

Build the embedded, single-binary product with:

just build package

Use mise.toml and the justfile as the authoritative task definitions. For design work, use:

Read the current-main application lifecycle when working on unreleased launch, update, or single-instance behavior.

Release automation lives in the Release Please workflow and distribution workflow. Use conventional commits and let Release Please update the engine changelog.

Regenerate terminal README assets with:

just docs readme-assets

To regenerate application captures, keep just serve running in one terminal. Run the capture task in another:

npm --prefix frontend run readme:capture

The capture task generates the README figures and their manifest.

vaultspec nevenincs

README

vaultspec-dashboard

What it does

Visual tour

Project layout

Project responsibilities

Installed runtime

Getting started

Prerequisites and installation

Updating

Removing it, and what stays

Start the dashboard

Optional semantic search

Follow one record from vault to search

Capabilities

When a capability is unavailable

Glossary

Vaultspec family

Documentation

Status and license

Contributing

vaultspec nevenincs

README

vaultspec-dashboard

What it does

Visual tour

Project layout

Project responsibilities

Installed runtime

Getting started

Prerequisites and installation

Updating

Removing it, and what stays

Start the dashboard

Optional semantic search

Follow one record from vault to search

Capabilities

When a capability is unavailable

Glossary

Vaultspec family

Documentation

Status and license

Contributing