docs: use a supported agent role in role examples (#16449)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Every agent has a role, and the API only accepts the values in
`AGENT_ROLES` (`z.enum(AGENT_ROLES)` in
`packages/shared/src/validators/agent.ts`)
> - The board-operator guide, the API docs and the agent-facing API
reference are where operators and agents learn which role values to send
> - They name `manager` as a role, but `manager` is not in
`AGENT_ROLES`, so creating an agent with it is rejected with
`invalid_value`
> - This pull request replaces the unsupported value with supported ones
in the guide and in the two places that show the same invalid value in
an example
> - The benefit is that the documented role values match what the API
accepts

## Linked Issues or Issue Description

- Fixes: #15687

## What Changed

- `docs/guides/board-operator/managing-agents.md`: the Role list now
reads `ceo`, `cto`, `pm`, `engineer`, `researcher`, etc. (`pm` replaces
the unsupported `manager`). The next bullet already says Reports to is
the agent's manager in the org tree, so the hierarchy is still described
and no extra wording was added.
- `docs/api/agents.md` and
`skills/paperclip/references/api-reference.md` (two examples): the same
invalid value appeared as `"role": "manager"` in response examples for
an "EngineeringLead" / "VP Engineering" agent. Changed to `cto`, which
is a supported role and fits those examples. These are single-word
changes made so the documented examples do not contradict the guide.
- Left alone on purpose: ordinary uses of the word "manager" in prose
(reports-to wording, AWS Secrets Manager), the "Worked Example: Manager
Heartbeat" heading, the planning docs under `doc/plans/`, and a code
test fixture (`ui/src/components/RoutineOverview.test.tsx`).
- No code, validation or enum change; no new role.

## Verification

- Before: the guide lists `manager`, and `AGENT_ROLES`
(`packages/shared/src/constants.ts`) is `ceo, cto, cmo, cfo, security,
engineer, designer, pm, qa, devops, researcher, general`, with no
`manager`; the create validator uses `z.enum(AGENT_ROLES)`.
- After: every role value named in the changed lines (`ceo`, `cto`,
`pm`, `engineer`, `researcher`) is in `AGENT_ROLES`. `git diff --check`
is clean. `pnpm-lock.yaml` is unchanged.
- This is a docs-only change (3 files, 4 lines), so I did not run the
test suite and did not add a test; there is no docs lint script that
runs without installing dependencies.
- To check by hand: send `POST /api/companies/{companyId}/agents` with
`"role": "manager"` (rejected with `invalid_value`) and with `"role":
"pm"` (passes role validation).

## Risks

- Low. Documentation only, no runtime behavior change.
- `cto` in the two example responses is a judgment call for the
"EngineeringLead" / "VP Engineering" sample; any supported role would
also be valid there. The two extra files are example-only and can be
dropped if a maintainer prefers this PR to touch only the guide.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Implementation: Anthropic Claude Sonnet 5.5 (`claude-sonnet-5-5`),
medium reasoning effort, with tool use and code execution through Claude
Code. Context window not reported by the runtime.
- Coordination and this description: Anthropic Claude Sonnet 5.5
(`claude-sonnet-5-5`).
- Independent review of the exact head: OpenAI Codex `gpt-5.6-sol`,
medium reasoning effort, read-only, no findings.
- The issue was picked by an automated screening agent; a human
contributor directed the work and owns the change.

## Checklist

- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-authored-by: Claude Sonnet 5.5 <noreply@anthropic.com>

docs/api/agents.md

@@ -46,7 +46,7 @@ Returns the agent record for the currently authenticated agent.
   "budgetMonthlyCents": 5000,
   "spentMonthlyCents": 1200,
   "chainOfCommand": [
-    { "id": "mgr-1", "name": "EngineeringLead", "role": "manager" },
+    { "id": "mgr-1", "name": "EngineeringLead", "role": "cto" },
     { "id": "ceo-1", "name": "CEO", "role": "ceo" }
   ]
 }

docs/guides/board-operator/managing-agents.md

@@ -21,7 +21,7 @@ Agents are the employees of your autonomous company. As the board operator, you
 Create agents from the Agents page. Each agent requires:
 
 - **Name** — unique identifier (used for @-mentions)
-- **Role** — `ceo`, `cto`, `manager`, `engineer`, `researcher`, etc.
+- **Role** — `ceo`, `cto`, `pm`, `engineer`, `researcher`, etc.
 - **Reports to** — the agent's manager in the org tree
 - **Adapter type** — how the agent runs
 - **Adapter config** — runtime-specific settings (working directory, model, prompt, etc.)

skills/paperclip/references/api-reference.md

@@ -26,7 +26,7 @@ Detailed reference for the Paperclip control plane API. For the core heartbeat p
     {
       "id": "mgr-1",
       "name": "EngineeringLead",
-      "role": "manager",
+      "role": "cto",
       "title": "VP Engineering"
     },
     {
@@ -594,7 +594,7 @@ Paperclip converts that into a `changes_requested` decision, reassigns the issue
 ```
 # 1. Identity (skip if already in context)
 GET /api/agents/me
--> { id: "mgr-1", role: "manager", companyId: "company-1", ... }
+-> { id: "mgr-1", role: "cto", companyId: "company-1", ... }
 
 # 2. Check team status
 GET /api/companies/company-1/agents