Renaming Jo, Sam, Alex and Riley

The rename is two different jobs wearing one name. The job clients need is a display rename: every label, heading, sentence, email and PDF that says Jo, Sam, Alex or Riley says Onboarding, Discovery, Opportunity or Strategy instead. It is one agentic pass over about 80 files, needs no database migration, and breaks nothing outside the platform. The job that looks like the same thing is an identifier rename: URLs, API paths, database values, event types, test ids, file and folder names. That is a chain of data migrations across six tables and a telemetry cut-over, and clients never see any of it.

What clients see today

Logged in to platform-test as the Space X client user, the agent names appear in four places: the welcome screen ("Meet Jo, your onboarding guide"), the intake chat and its NDA and review tabs, the dashboard ("Continue your intake with Jo", "Sam → Alex → Riley"), and the pipeline page shown below. Deliverable packs and the Activate surfaces are already named after outputs, not agents. Emails follow the same pattern: "Your workshop pack is ready", "Your Opportunity Mapping Pack is ready", "Your Business Alignment Pack is ready".

Two client-facing artefacts also carry the names in a way that cannot be recalled: single-page PDF downloads from the board pack are named sam-…pdf, alex-…pdf, riley-…pdf, and some generated deliverable text refers to agents by name ("These deliverables translate Alex's prioritised partner shortlist…" on a Business Alignment Pack overview). Files clients have already downloaded and packs already published keep the old wording until regenerated.

Where the names live

Decisions needed before build

These are product calls, not engineering ones. Each one changes copy in dozens of places, so settle them first.

1. Agent names versus stage names. The pipeline today reads "Workshop with Sam", "Opportunity Mapping with Alex", "Alignment with Riley", and the stage vocabulary Intake, Workshop, Mapping, Alignment is used across admin and portal. If the agents become Onboarding, Discovery, Opportunity, Strategy, do the stages follow? "Discovery with Discovery" does not work. The natural resolution is that the agent name becomes the stage name and the "with X" construction goes.
2. Pack titles. Current titles are Workshop Pack (Align Phase Workshop Pack in the portal), Opportunity Mapping Pack, Business Alignment Pack, Partnership Growth Roadmap. Opportunity already fits. "Strategy" for Riley sits next to the Activate side's Strategy Anchor and the "Partnership Strategy Playbook" PDF, which is coherent but means Business Alignment Pack probably becomes Strategy Pack. Discovery has no pack title today.
3. Avatars. Initials become O, D, O, S. Onboarding and Opportunity collide. Either switch to the existing icon set (message, sparkles, target, users), give each stage a numeral, or pick distinct glyphs.
4. Whether agents keep any persona at all. Copy like "Jo will walk you through a guided conversation" and "Riley produces your 90-day activation playbook" is written in the third person about a character. Onboarding and Discovery are nouns, so those sentences need rewriting as things the platform does, not things a person does. Roughly 60 sentences.
5. Generated content already published. Packs on client portals contain the old names inside deliverable text. Decide whether to regenerate current packs after the release or let them roll over on the next run.

Front end

Display rename

• Introduce one display registry (name, stage label, pack label, short description, icon) in frontend/src/shared/types/domain.ts and delete the ten shadow copies: clientDetailActivityRail.ts, AdminPackPublishControl.tsx, RileyWorkspace.tsx, dashboard AGENT_TILES, ClientDetailHeader STAGE_STEPS, usePortalDeliverables ALIGN_AGENT_ORDER, the three page-title constants, the two workspace adapters, StageProgressSlider.
• Rewrite client-facing copy in about 30 files: welcome page, intake chat greeting and tabs, dashboard, pipeline stage names and descriptions, data intake, branding, provenance tooltips and banners in the worksheets, print cover and board-pack print strings.
• Rewrite consultant-facing copy in about 40 admin files: workspace banners, launch modals, run-state copy, status strings, toasts, readiness panel, client detail header and tabs, Activate onboarding wizard, worksheet data tab bands.
• Pack config packLabel and stageLabel in packs/sam.ts, alex.ts, riley.ts, and the mode and loading labels in brand.ts.
• Avatar and icon components per the design decision above.

Left alone under the recommendation

• Component, hook, file and directory names (155 non-test files, 37 directories), CSS classes, the --agent-* colour tokens, React Query keys, and the 363 agent-prefixed test ids that the e2e suite depends on.
• Route definitions keep their path segments. Add redirects if the URL segments are renamed later.

Back end

Display rename

• The backend label map in db/queries/engagement-events.ts, portal deliverables metadata (agentName, agentRole, pack titles), admin client lane metadata, lock-reason copy in agents-shared.ts, the source-drift message in the Alex worker, the two "with Jo" notification strings, Prometheus help text, six Grafana descriptions.
• PDF single-page filename builder: replace the agent slug with the new stage slug.
• Email deep links: no change needed if the old portal pack URLs stay valid.
• The stored alex-a2 prompt and any prompt-version text that names agents inside generated prose, shipped as a forward migration, then regenerate affected pages.
• RAG corpus document 09 mentions "Sam agent" and "Jo intake" in prose. Edit and re-ingest.

Identifier rename, if ever pursued

Listed so the size is clear. None of it is needed for the client outcome.

• Agent directories under backend/src/agents/ (134 files), 14 agent-named route and handler files, five shared-contract files, and hundreds of type-safe symbol renames.
• Persisted string values: agent_id rows in agent_runs, agent_run_events, page_versions, pack_versions, pack_publishes, quality_judge_runs; the column defaults; the two *_sam_page_key_required_check constraints; publish namespaces such as riley:business-alignment-pack which are also hardcoded inside a live migration predicate; event types sam:run:* and alex:source-readiness:checked that dedupe queries read back; templateName values; JSONB keys such as alex.launch_context, riley-overview.*, sam:d_compete.
• Source enums with CHECK constraints: activate_strategy_anchors.source, activate_partners.source, activate_anchor_partner_registry.source, baseline_source = 'jo_onboarding', finance 'jo_seed', readiness 'riley_typed_outputs'. Each needs drop, update, re-add under lock, in lockstep with ANCHOR_SOURCES and PARTNER_SOURCES in shared contracts.
• Hash-identity prefixes riley-anchor-source:v1, jo-onboarding-source:v1, riley-pack-source:v1 feed every stored source_revision. Changing them marks every Strategy Anchor stale. Freeze these regardless.
• BullMQ job kinds and dedupe ids in Redis break for in-flight jobs across a deploy.
• Env vars need a dual-read window; the RILEY_LLM_* set is set somewhere outside the repo and would need to be found first.

API and routes

• Public surfaces are clean. The v1 API and its OpenAPI document, the MCP server (tool names, descriptions, scopes), the Slack manifests and every Block Kit string, and the public webhook and OAuth routes contain no agent names. No external consumer, connected Claude client, Slack install or third-party dashboard changes.
• Internal API paths are consumed only by the first-party front end. Under the recommendation they stay. If renamed later, mount the old paths as permanent aliases and update the Caddyfile handle for /api/portal/jo/message in the same deploy.
• Bookmarkable browser URLs that carry an agent name and reach clients: /portal/engagements/:id/packs/alex/current and …/riley/current (embedded in published-pack emails), and consultant bookmarks on /admin/{sam,alex,riley}/:id. Keep them working. If new paths are wanted for cosmetic reasons, add them alongside and redirect.

Integrations and things outside the repo

Sequenced plan

The display rename is four PRs that can run as parallel agent passes off the same glossary, with two human gates: the naming decisions before, and a read of the rewritten copy after. The identifier rename, if the team wants it as tech-debt work later, is a separate run with different risk: directory and symbol renames, about 45 route aliases, a chain of data migrations across the tables and constraints listed above, e2e catalog rewrite, a telemetry cut-over, and env var rotation. Agents can do the mechanical work, but the migrations touch every historical row and the hash prefixes cannot move at all, so it needs staged rollout and rollback plans a copy change does not. It should never be bundled with the client-facing release.

Risks in the display rename

• Copy that reads wrong after a find-and-replace. Persona sentences and "with X" constructions need rewriting by hand. Budget review time, do not script it.
• Two words for one thing during transition. Clients hold PDFs named sam-… and emails saying Workshop Pack. A single line in the next pack-ready email ("previously the Workshop Pack") covers it.
• Docs drift. 316 docs files use the old names. Update the canonical README, field matrix and handoff index; leave historical decision records as they are.
• Naming collision with Opportunity Mapping Pack and Strategy Anchor. Resolved by decision 2, not by engineering.

Method: three code sweeps over frontend, backend/API/DB/shared contracts, and integrations/docs/e2e on main at 43d4704b; Playwright crawl of 20 admin pages as a consultant and 40 portal pages as the Space X client on platform-test; Gmail check of platform notification emails since May 2026. No code was changed.