feat(j5): library definitions are personas, not agents

[bryantderosier]

One word was doing two jobs. "Agent" meant both a running participant (a thread, a Crew seat, a subagent) and a saved definition in the library, and Jackson's review kept reaching for "persona" where the descriptions said "agent". A library entry is now a persona everywhere a person or a model reads the word, and "agent" is reserved for something running.

• UI. Settings → Personas at /settings/personas (the search entry still answers "agents"; the four current users re-find the page), the library panel, create and edit dialogs, the draft picker, the assignment control, the identity chip, the composer picker's badge and empty state, and the crew roster card. A seat with no persona is a custom seat. Mobile matches: settings row, screen title and deep link, library screen, create modal, composer popover.
• Mentions. @persona:id is what the picker inserts and the docs teach; @agent:id still parses so old drafts and habits keep working.
• MCP surface. list_agents is list_personas with a personas[] result. The agent parameter on spawn_agent, delegate_task, crew seats, and request_crew_member is persona, with agent accepted as a deprecated alias for one release. Crew results carry persona_id, gate notices and seat briefs write persona=, and the standing orchestration instructions, tool descriptions, allowlists, and server error messages say persona.
• Docs. The user guide is docs/user/personas.md; the persona contract, operations guide, crews definition, glossary (new persona row), tools reference, FORK.md rows, and the design record follow.

Left alone on purpose: code identifiers, file names, atoms, RPC names, agent-personas.json, and every place "agent" means a running participant, including the right panel's live Agents tab.

Stacked on #183. Design record: docs/j5/worklog/2026-09-16-crew-command-decoupling.md, "personas, not agents".

Evidence

Before, the same page and picker read "Agents" and "Agent"; the rename is one word, so no separate before shot. After:

Settings → Personas.

Composer picker badge.

🤖 Generated with Claude Code

Closes #210.

[Jacksondr5]

The rename itself is clean: every non-J5 edit is a label change inside an already-recorded FORK.md case, the allowlists and registration tests agree on list_personas, the writer, brief, and parser agree on persona= for new notices, and the mention picker inserts @persona: on web and mobile.

Requesting changes on the compatibility code. The agent parameter is accepted as a deprecated alias on four verbs (spawn_agent, delegate_task, crew seats, request_crew_member), decoded separately in each with persona silently winning on conflict, @agent:id still parses on web and mobile, and three notes say "accepted for one release". docs/j5/process/working-in-the-repo.md records the rule as written: "Pre-dogfood, no legacy-compatibility code, ever (Jackson, 2026-09-01). Accommodations for data or states that cannot exist yet (no users, no legacy drafts) are YAGNI and get deleted; invariants stay and fail closed, loudly." Jackson reaffirmed it today for this case. There is also no version-skew argument for it: the callers are models that read the tool schema from the same server process at session start, and a server restart ends every provider session, so nothing can keep sending the old name. Remove the alias, the per-verb decode, the LEGACY_AGENT_MENTION_PREFIX parse and its token exclusion, and the three deprecation notes (tools.ts, FORK.md, agent-tools.md). With one field left, give persona a schema description so the model sees what it is.

Also requesting (inline on crewNotices.logic.ts): the gate parser drops unrecognized roster lines silently.

Comments:

• No redirect for /settings/agents on web or the mobile deep link. Accepted in the body; a one-file J5 route that redirects would cost nothing.
• Leftover "agent" strings where a person reads them: the mobile library screen's "Use Settings → Agents in the web app", "Edit agent", "Replace existing agents?", and the shared "agent definition" copy in client-runtime and the server's library errors.
• FORK.md rows now stale: one cites docs/user/agents.md (renamed), two name the pre-rename identifiers as current, and the Stack.tsx / SettingsRouteScreen row was not updated for the personas link path.

Reviewed by Claude Fable 5.1 in Claude Code, with an independent pass by GPT-6-Astra in Codex.

[bryantderosier]

b2feffd42 removes the compatibility code: the agent alias and its per-verb decode, the @agent: parse and its token exclusion, and the deprecation notes in tools.ts, FORK.md, and agent-tools.md; persona carries a schema description in their place, and the worklog records the reversal under the pre-dogfood rule. The gate parser fails closed on any roster line it does not understand. The redirect, the leftover strings, and the stale FORK.md rows are tracked in #187.

[Jacksondr5]

The compatibility code is gone as ruled: no agent alias or per-verb decode, no old mention parse or token exclusion, no deprecation notes, persona carries a schema description, and the worklog records the reversal under the pre-dogfood rule. The gate parser fails closed on any roster line it does not understand, verified against the old-format fixture. Approving.

One sentence to fix in this PR since the file is already in the diff (inline on docs/user/personas.md): it still teaches the removed mention spelling.

Reviewed by Claude Fable 5.1 in Claude Code, with an independent pass by GPT-6-Astra in Codex.

[bryantderosier]

The stack is restacked and pushed through 37a6cc709. Remaining mobile/import/validation wording and FORK references now say persona. The custom-seat empty-value fixtures follow the persona wire vocabulary. Server, web, mobile, and client-runtime typechecks pass. The old settings redirect remains deliberately separate, alongside #182 and Fleet command-palette work; see #187.

[Jacksondr5]

Round five. The mobile, import, and validation strings say persona, the user guide teaches only @persona:, and the FORK.md rows for the user guide and the tool names are correct. Two residuals.

• inline on FORK.md: the mobile row now cites a file that does not exist.
• apps/server/src/j5/agents/agentPersonaLibrary.ts still says "Agent definition exceeds 64 KiB." in two validation messages a person can see.

Reviewed by Claude Fable 5.1 in Claude Code, with an independent pass by GPT-6-Astra in Codex.

[bryantderosier]

Both residuals from the round-five review are fixed: the mobile file reference is restored and both size-limit validation messages say “Persona definition.”

[Jacksondr5]

FORK.md names the mobile file that exists, and both size-limit messages say persona. With the alias removal, the fail-closed parser, and the persona copy verified across three rounds, approving.

Reviewed by Claude Fable 5.1 in Claude Code, with an independent pass by GPT-6-Astra in Codex.