# Customize Fleet Roles

Mosaic resolves persona contracts through two layers:

1. `fleet/roles/<canonical-class>.md` — seeded baseline contract.
2. `fleet/roles.local/<canonical-class>.md` — operator override or custom role; this layer wins.

The same shared resolver is used by profile validation, provisioning, roster-v2 semantic validation,
and launch-time persona injection.

## Override a baseline role

Create a readable Markdown contract under `roles.local` with the canonical filename and class marker:

```markdown
# Code — local role definition

The local code role (`class: code`) follows the operator's repository conventions.
```

Save it as `fleet/roles.local/code.md`. Do not edit generated or seeded baseline assets when the goal
is a durable local customization.

Legacy aliases canonicalize before lookup. Therefore `roles.local/implementer.md` does not override
`code`; use `roles.local/code.md`. See [Legacy Fleet Class Aliases](../migration/legacy-class-aliases.md).

## Add a custom class

A custom class remains supported when a readable contract exists for the exact identifier:

```markdown
# Release notes — local role definition

The release-notes role (`class: release-notes`) prepares operator-reviewed release copy.
```

Save it as `fleet/roles.local/release-notes.md`, then reference `class: release-notes` and a matching
`tool_policy: release-notes` in roster v2. Adding only a `LIBRARY.md` row is insufficient.

Names such as `worker`, `analyst`, and `canary` are not built-in aliases; they need genuine custom
contracts. `agents[].alias`, Tess, and Ultron are display names and cannot select a class.

## Validation and authority boundaries

Semantic validation reads the winning contract and rejects missing, unreadable, or empty files.
Protected authority is derived from canonical class metadata in code, never from role prose. A custom
contract cannot claim merge, validation-certificate, orchestration, lease, or interaction authority.

Roster v2 also fails closed when a protected class and tool policy do not match after canonicalization,
or when an unprotected class claims a protected tool policy. The legacy `operator-interaction` policy
canonicalizes to `interaction`.

Role customization does not issue leases, store validation certificates, mutate credentials, or
change lifecycle state.