# Setup and installation

How to build, install, and first-run Flavite from source. Every command and path here reflects the current codebase.

# Prerequisites

Headless use (flavite-cli) needs none of the display/GPU requirements.

# Install

git clone https://github.com/lexbity/flavite
cd flavite
cargo build -p flavite-app -p flavite-cli -p flavite-text-search-worker

This produces three binaries in target/debug/:

• flavite — the desktop app (crate flavite-app).
• flavite-cli — the headless CLI (crate flavite-cli).
• flavite-text-search-worker — the isolated regex helper. Keep this binary in the same directory as the desktop and CLI binaries; the applications resolve that exact sibling and never search PATH or accept a configured executable path. If it is absent or has a mismatched protocol version, regex Find/Replace reports that state and literal matching remains usable.

For a faster daily-driver build use cargo build --release -p flavite-app -p flavite-cli -p flavite-text-search-worker. When installing the executables manually, install the helper into the same bin directory as both Flavite binaries.

# Developer setup (one command after clone)

If you plan to work on Flavite itself, run:

just setup

This runs cargo xtask setup, which is idempotent and installs:

1. The pinned Rust components (rustfmt, clippy, llvm-tools-preview).
2. The nightly toolchain (minimal profile) — used by cargo-fuzz.
3. Cargo tools, if missing: cargo-fuzz, cargo-deny, cargo-audit, cargo-llvm-cov, and cargo-shear (nightly) — prebuilt via a pinned cargo-binstall where available.

No git hooks are installed: gating lives in CI (just gate / just ci-gate), not in a local pre-push hook.

Individual steps tolerate failure with a warning and continue; setup ends by suggesting just gate to verify the workspace.

# First run

The desktop app never creates note content for you. A folder of Markdown files is adopted as a vault on first open:

• With no --vault argument and no FLAVITE_VAULT set, flavite opens the start screen: type a vault folder path and press Open, use the Choose folder… native dialog, or use Open last vault if one is remembered on this device.
• With --vault PATH (or the FLAVITE_VAULT env var), the app opens that vault directly. A non-existent path cannot be adopted; the folder must exist.

To create a vault explicitly, use the CLI:

flavite-cli init --path /path/to/vault    # creates the directory if needed, writes vault.toml

First open of a vault writes <vault>/.flavite/vault.toml (its identity) and registers it in the OS data dir.

# Verify the installation

# Vault health check (exit code 0 = healthy, nonzero only on ERROR-level findings)
flavite-cli doctor --path /path/to/vault
flavite-cli doctor --path /path/to/vault --json   # machine-readable report

# Workspace-level verification (developer installs)
just gate      # fmt + clippy + tests + arch check, ~5 min

doctor checks SQLite integrity, tantivy index generation, broken/ambiguous links, duplicate IDs, attachments, and more. Warnings are reported but do not fail the command.

# Platform notes

# Linux

• Wayland and X11 are both supported for the app (winit decides).
• Development-only visual harnesses need extra packages: just ui-visual-setup installs xvfb, xdotool, imagemagick, python3-pil, tesseract-ocr via apt (Debian-style systems; elsewhere install them manually).
• CI uses just gpu-setup (mesa-vulkan-drivers / lavapipe) on machines without a GPU.

# macOS / Windows

Covered by CI (just setup, just gate, docs, deny/audit, MSRV). No extra packages are required. The visual/fuzz/coverage harnesses are Linux-only.

# Graph backend

The graph view has two interchangeable renderers publishing identical geometry:

A failed GPU initialization never disables the network or note editing — switching to canvas is a workaround for driver problems, not a necessity.

# Environment variables (user-relevant)

Additional variables exist for test harnesses and crash-simulation (FLAVITE_HARNESS_*, FLAVITE_RENAME_KILL_ROOT, FLAVITE_W12_CRASH_ROOT, FLAVITE_TANTIVY_KILL_CHILD_ROOT, FLAVITE_RECOVERY_KILL_CHILD_ROOT, …). Do not set these outside test scenarios: several are destructive hooks that kill processes or inject UI faults.

# Where state lives

Everything under <vault>/.flavite/ is vault-rooted: it travels with the vault and is never machine-pinned. Everything under <data> is device-local. <data> is the OS data directory for the app (ProjectDirs for com.flavite/Flavite — e.g. ~/.local/share/Flavite on Linux), with FLAVITE_DATA_DIR overriding it entirely when set to an absolute path.

# Troubleshooting

# See also

• APP-FEATURES.md — desktop app guide and shortcuts.
• CLI-FEATURES.md — full CLI reference.
• QueryLanguage.md — query expression syntax.

# Source-search platform boundary

The regex helper currently enforces process-group and address-space limits on Unix. Other platforms explicitly refuse regex execution until their required resource isolation is implemented; literal Find/Replace remains available. A bare child process without resource limits is not a supported fallback.

Shortcut names use canonical named keys such as Enter, Escape, Delete and ArrowUp/ArrowDown/ArrowLeft/ArrowRight. Removed spellings Return/Esc/Del/Up/Down/Left/Right must be changed explicitly in overrides.