# The fleet registry — `fleet.toml`

`fleet.toml` is the project-orchestrator's **authoritative, PO-only** record of every project in the
fleet. It is the *single* place where project ↔ harness ↔ ref ↔ location is recorded. Projects
themselves carry none of this: knowledge is one-directional (**PO → projects, never the reverse**), so
a project repo never contains a `fleet.toml`, a project id, or any mention of the PO.

Validate / inspect it with the helper:

```bash
python3 scripts/fleet.py validate     # parse + schema-check; exit 1 on any error
python3 scripts/fleet.py list         # one line per project
python3 scripts/fleet.py status       # list + a summary count
python3 scripts/fleet.py get <name>   # dump one project's full entry
```

## Schema

### `[fleet]` — registry metadata (optional)

| key | type | meaning |
|---|---|---|
| `version` | integer | registry schema version; bump on a breaking change to this format |

### `[[project]]` — one block per project

| key | required | type | meaning |
|---|---|---|---|
| `name` | **yes** | string | unique fleet id, kebab-case. Used by the helper scripts to address the project. |
| `location` | **yes** | string | where the project lives: a git URL (remote) **or** a local filesystem path (a working clone the PO can drive directly). |
| `harness` | **yes** | string | which harness runs the project (e.g. `agent-orchestrator`). The PO reads that harness's docs to know how to drive it. |
| `ref` | **yes** | string | the harness ref the project pins (its `engine/` submodule pin — a tag/branch/SHA). The in-repo submodule pin is the source of truth; this mirrors it for at-a-glance fleet inventory. |
| `enabled` | **yes** | bool | whether this project is part of the active fleet (a bare fleet "start everything" would skip `enabled = false`). |
| `secrets` | **yes** | string | where the project's creds live (a path like `.env`, or a secrets-manager ref). Never the secret values themselves; secrets are never in git. |
| `config` | no | string | the project's harness config file, relative to its root (default `agents.toml`). |
| `notes` | no | string | free-form operator notes. |

Unknown fields are rejected by `fleet.py validate` (typo guard). Duplicate `name`s are rejected.

## Why the registry, and only the registry, holds this

If a project repo recorded its own harness/ref/fleet-membership, that knowledge would be
bidirectional and a project would "know" it belongs to a fleet — breaking isolation and making a
project un-runnable standalone. Instead:

- **what harness + what ref** a project uses is captured *in the project* only as the `engine/`
  submodule pin (a plain git fact, no fleet semantics), and *in the PO* as this registry's
  `harness`/`ref`. The project never names a PO.
- **which projects exist, where, enabled** lives *only* here. Remove a project from the fleet by
  deleting its `[[project]]` block; the project repo is unaffected and still runnable by hand.

## Adding an entry

Either let `scripts/create-project.sh --register` append one when it scaffolds a project, or add a
block by hand and run `python3 scripts/fleet.py validate`. See `docs/manage-projects.md`.