Prerequisites
Read AGENTS.md in the repository before opening a pull request. It defines the development, validation, and pinned-runtime upgrade rules this page summarizes. Area-specific guides live in docs/guides/.
Two package managers, one rule
The repository uses two isolated workspaces:
- Repo root — npm workspace for the Fleet launcher (
packages/fleet-prime) and the pinned upstream runtime. npm install only.
web/ — pnpm workspace for the web product (web/app, web/design, web/protocol, web/server). pnpm install only, always with --dir web.
Never run npm install inside web/, and never run pnpm at the repository root.
Running pnpm at the repo root rewrites the root node_modules to a pnpm layout and drops stray pnpm-workspace.yaml and pnpm-lock.yaml files at the root. To recover: delete both files, re-run npm install at the root, and never commit them.
Setup and dev server
Validation
After code changes, run the full check from the repository root:
It runs, in order: the runtime pin check (check:runtime), Biome lint/format with warnings as errors, the source installer check, the rendering contract checks, and the web typechecks. npm run check does not run tests.
Tests
Run the web test suites with pnpm --dir web test, or run a focused file from the relevant package root:
Adapter tests use the web server’s deterministic test doubles; they need no real provider APIs or keys.
Boundary rules to respect
- Do not import
prime-agent outside web/server. Browser code talks HTTP only.
- Do not add or restore vendored Prime Agent source trees. Engine changes belong upstream.
- Dependency updates respect a 7-day minimum release age (
min-release-age=7 in .npmrc), which requires npm 11.10 or later to enforce.
Repository guides
docs/guides/web-interface.md — web stack boundaries and install recovery.docs/guides/upstream-runtime.md — runtime pin upgrades and daemon protocol changes.docs/guides/github-workflow.md — issue and PR etiquette.docs/guides/tmux-testing.md — driving the engine TUI in tmux for interactive testing.docs/guides/releasing.md — cutting a Fleet release.
