Development¶

Build¶

make build
./bin/omni --help

Useful run targets:

make tui-live
make tui-dev
make cli-live ARGS='tools list'
make cli-dev ARGS='tools list'

*-dev targets use isolated config and cache paths under /private/tmp.

Tests¶

make -j2 test

This runs shell regressions and go test -race -trimpath ./... concurrently. Every process gets a unique disposable sandbox with isolated HOME, XDG, Omni, temporary, Git, package-manager, and language-tool roots. The runner sanitizes credentials and network proxy settings; tests fail before mutation when a writable path escapes the sandbox. Use scripts/run-test-safe.sh for focused local go test commands that can touch state.

Integration tests must use the Docker-isolated target:

make test-integration

This runs only integration-tagged coverage with the race detector; the full unit suite remains in make test. Containers provide controlled external tools, permissions, HOME/config roots, Git, and real-binary/PTY execution. They use disposable filesystems with no host HOME, Docker socket, source mount, or network access during the test run. The host-side Docker wrapper rejects non-local daemons and strips Docker, Buildx, BuildKit, proxy, certificate, and credential configuration before building or launching containers.

Do not run integration tests directly against the local machine. Dots and package-manager flows intentionally mutate files and package-manager state in their isolated environments.

test/flows.json is the machine-readable capability catalog. make check-flows validates command/action coverage and declared test selectors; make gen-flows refreshes the generated capability and gap tables in the test matrix. CI accepts required evidence only from the exact declared lane, OS, tags, package, and test/subtest after an uncached passing run.

make test-canary is reserved for opt-in live APM contract checks. It runs only TestCanary* tests behind the canary build tag in internal/agent and internal/app, keeping them out of every other test target. The APM hard migration removed the former pre-APM canaries, so no tests currently match this target; the scheduled CI invocation performs no external checks.

Lint¶

make lint

The lint target keeps caches under .tmp/ when cache environment variables are not already set.

Regenerate The Schema¶

make gen-schema

Schema version changes are explicit product decisions. Do not bump the settings version just because generated schema output changed.

Documentation¶

Strict docs builds run in the docs Docker image.

Build strictly:

make docs-build

If Docker Desktop is installed but docker is not on PATH, pass the binary:

make docs-build DOCKER=/Applications/Docker.app/Contents/Resources/bin/docker

For iterative local serving, install MkDocs into your own environment and run:

mkdocs serve

The Docs GitHub Actions workflow builds the MkDocs site on pull requests and deploys it to GitHub Pages from main.

Keep README as the minimal entry point and update the focused guide plus its reference page:

Change	Review
CLI command or flag	CLI Reference, Command Matrix
Configuration or state	Configuration, State And Files
Tool/provider behavior	Tools, Providers, Troubleshooting
Dotfile behavior	Dotfiles, Safety Model, Runbooks
Agent/APM behavior	Agents, CLI Reference, TUI when interactive

Use omni <command> --help as the final syntax source. make docs-build is the local strict-build check. The Docs workflow also checks links, anchors, headings, and placeholder markers. Prefer cross-links over copying long explanations between pages.

Demo GIF¶

make demo-gif

The demo uses VHS through rtk vhs when available, otherwise vhs. Rendering may need a less restrictive local environment because VHS allocates a recorder port.

Releases¶

Releases are GoReleaser based and use Conventional Commit subjects for release notes. Release automation is CI-gated by commit SHA.