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

# Developing from source

> Package manager boundaries, dev server, checks, and tests for working on the Fleet Prime Agent codebase.

## 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.

<Warning>
  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.
</Warning>

## Setup and dev server

```bash theme={null}
npm ci
pnpm install --dir web
pnpm --dir web --filter @prime-agent/web dev   # or: npm run dev:web
```

## Validation

After code changes, run the full check from the repository root:

```bash theme={null}
npm run check
```

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:

```bash theme={null}
cd web/server
pnpm exec vitest run src/__tests__/specific.test.ts
```

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.