> ## Documentation Index
> Fetch the complete documentation index at: https://docs.locality.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Development

> Build, run, test, and validate Locality from this repository.

Use the root `Makefile` for normal development.

## Setup

```bash theme={null}
make setup
```

This installs desktop and OAuth service npm dependencies.

## Desktop development

Fresh-build Rust sidecars and start the Tauri desktop app:

```bash theme={null}
make prepare-desktop-dev-sidecars
make dev-tauri
```

Run the frontend only:

```bash theme={null}
make dev-desktop
```

Build the packaged desktop app:

```bash theme={null}
make build-tauri
```

## Rust and frontend checks

```bash theme={null}
make check
make test
make lint
make fmt
```

GitHub Actions parity:

```bash theme={null}
make ci
```

## Run the CLI

```bash theme={null}
make run-cli ARGS='status --json'
make run-cli ARGS='doctor'
```

Or run the debug binary directly after build:

```bash theme={null}
./target/debug/loc status
```

## Daemon development

```bash theme={null}
make run-daemon
./target/debug/loc daemon status
./target/debug/loc daemon restart
```

The default state root is `~/.loc`. Use `LOCALITY_STATE_DIR` for isolated tests.

## macOS File Provider development

```bash theme={null}
make install-macos-file-provider
./target/debug/loc file-provider status notion-main
./target/debug/loc file-provider restart notion-main
```

For File Provider changes, verify the installed app, daemon, registered domain, and visible CloudStorage folder. A passing Rust build is not enough.

## Publish commands

Release commands are deliberate and should be run only for a release task:

```bash theme={null}
make publish
make publish-unnotarized
make publish-linux
make publish-windows
make render-homebrew-cask
make render-updater-manifest
make render-linux-repositories
```

Do not publish a build that failed relevant checks.

The dedicated `.github/workflows/release-notes.yml` workflow generates the
GitHub Release body with `scripts/render-release-notes.sh`. The script compares
`RELEASE_TAG` with the previous reachable `v*` tag, sends the commit range and
diff summary to `codex exec`, and writes `target/release/release-notes.md` for
`gh release create/edit --notes-file`. GitHub's PR-only generated notes are
intentionally not used because direct commits to `main` are common. Platform
release workflows only publish assets; if they create the release first, the
notes workflow later replaces the placeholder body.

GitHub Actions needs `CODEX_CONFIG_TOML` plus the provider credential named by
that config. The current Azure OpenAI setup uses `AZURE_OPENAI_API_KEY`. Those
secrets are passed only to the release-notes step.

Validate the plumbing locally with:

```bash theme={null}
make test-release-notes
```

## Docs development

The published docs use Mintlify from the repository's `docs-site/` directory. Internal engineering notes stay in `docs/`.

Preview from an isolated docs workspace:

```bash theme={null}
make docs-dev
```

Validate before committing:

```bash theme={null}
make docs-validate
```

CI runs the same validation for docs-related pull requests:

```bash theme={null}
make docs-validate
make docs-broken-links
```

The docs helper pins the Mintlify CLI version for deterministic local and CI behavior. Override it only when intentionally testing a CLI upgrade:

```bash theme={null}
MINTLIFY_PACKAGE=mintlify@latest make docs-validate
```

Check navigation paths directly when editing `docs-site/docs.json`:

```bash theme={null}
cd docs-site
jq empty docs.json
for p in $(jq -r '.. | .pages? // empty | .[]? | strings' docs.json); do test -f "$p.mdx" || echo "missing $p.mdx"; done
```

Keeping the Mintlify root in `docs-site/` avoids mixing public docs with internal design notes.