# Use the handbook

Keep one source for the team and its agents. A project vendors the book so
its agreed version remains available without a network connection.

From the product’s root, with Node 20 or later:

```sh
node /path/to/principles/bin/principles.mjs init
```

This creates `principles/HANDBOOK.md`, its examples, the local CLI and version metadata,
a pointer in `AGENTS.md`, and a short project note at `docs/principles.md`.
Use `--overlay <path>` to put the note elsewhere. Link existing documentation
instead of copying it into another template.

## Make it available

Check that the agents your team uses actually load the project instructions.
Some clients need an explicit import or configuration. File presence alone
does not establish that the instructions were read.

Keep the project note limited to facts that affect decisions: what the
product does, its authority boundaries, where its design system lives, and
how to verify changes. Record a deliberate departure from the handbook with
its reason. No pass table, new skill or new test framework is required.

The handbook explains [what counts as proof](HANDBOOK.md#prove-the-outcome).
The product supplies the checks.

## Update the copy

For a copy installed before the handbook, run the **new checkout’s CLI** once:

```sh
node /path/to/principles/bin/principles.mjs sync
```

This replaces the old layers and passes with the handbook. Later updates use
the installed CLI:

```sh
node principles/principles.mjs check
node principles/principles.mjs sync
```

`check` checks the installed copy, instruction pointer and project note. It
does not verify product behavior. `sync` updates the vendored files; review
that diff before adopting changed principles. It leaves the project note
alone. Change shared principles in this repository, not in a vendored copy.

Source resolution uses `--source`, then `PRINCIPLES_SOURCE`, then the local
source checkout when running its CLI, then the recorded source or
`git@github.com:mutativ/principles.git`. `check --upstream` compares the
installed commit with the source’s current head.