Local development

Start the frontend

Start the backend first. Then run the frontend in live mode:

npm install
VITE_ORION_MODE=live \
VITE_ORION_API_BASE_URL=http://127.0.0.1:8000 \
npm run dev -- --host 127.0.0.1

Open the live local app:

http://127.0.0.1:5173/app?mode=live

If the backend is unavailable, use replay for a fixed read-only scenario:

http://127.0.0.1:5173/app?mode=replay&scenario=baseline

Start the backend

From backend/:

uv sync --extra test --extra live
uv run uvicorn orion_backend.main:app --reload --port 8000

The backend needs server-side environment values for live dependencies. Use an untracked .env file or your shell environment. Never commit those values.

Run checks

From the repository root:

npm run typecheck
npm test
npm run lint
npm run build
node src/adapters/speech/clientWhisper/whisper.worker.bundle-check.mjs
git diff --check

From backend/:

uv run pytest
uv run ruff check .

Build docs

python3 -m pip install -r requirements-docs.txt
npm run docs:build

The output is dist/docs/. The build uses --strict. A missing navigation page or documentation warning fails the build.

Worktree rule

Use the Orion repository for Orion changes:

the repository root

Do not copy credentials, .env files, .aws-build/, or local snapshots into a commit.