Quickstart¶

This guide gets the repository ready for day-to-day use.

Prerequisites¶

Nix with flakes enabled
direnv
Docker (for the MCP gateway stack)

just and all other tooling are provided by the Nix dev shell.

First-time setup¶

Clone the repository and enter the directory.
Allow direnv to load the Nix dev shell:

direnv allow

Synchronize compatibility symlinks and generate derived configs:

just sync-ai

Hydrate local secrets from Bitwarden vault:

just bw-env-hydrate

Run the standard checks to confirm everything is wired correctly:

just format
just lint
just test
just build

Start the MCP gateway:

just mcp-up

VS Code starts the MCP gateway automatically on workspace open via the mcp: gateway up task in .vscode/tasks.json. When prompted for automatic tasks, choose Allow.

OpenCode¶

Run OpenCode with the repo-first instructions and config:

just opencode

Documentation workflow¶

Build the docs site:

just docs

Serve docs locally for preview:

just docs-serve

The local docs server is available at http://127.0.0.1:8000.

Writing quality¶

Spelling checks are required quality gates for docs and config text. Add project-specific terms to .vscode/cspell-project-words.txt and keep cspell.json as the canonical spell configuration.