onboarding-routes

Invocation#

echo-cli onboarding-routes list --product <onboarding product id>
echo-cli onboarding-routes add --product <onboarding product id> --journey <journey id> [--source <source>] [--persona <persona>] --by <name>
echo-cli onboarding-routes remove --route <route-id>

Inputs and output#

list writes routes, oldest first (id, product_id, journey_id, source and persona in lower case or null where the route does not look, created_by, created_at), and decisions, newest first (product_id, subject_id, route_id, journey_id, the source and persona the subject carried, decided_at). add and remove write the route.

State effect#

Every verb calls Echo Web's authenticated /api/onboarding/routes with ECHO_INTERNAL_BEARER at ECHO_WEB_BASE_URL; the Journey routes section of the onboarding studio and the Onboarding journey routes section of Echo Desktop's GEO screen call the same operation, and echo-mcp reads routes and decisions as echo_onboarding_routes. A product backend asks GET /api/onboarding/bundle?product_id=<id>&subject=<id>&source=<s>&persona=<p> with its ONBOARDING_BUNDLE_TOKEN instead of naming a journey: the subject's first decision answers when one was stored, so a subject keeps the journey it started; otherwise the oldest route whose every stated value the subject carries (trimmed, case-blind) decides, and the decision is stored in onboarding_route_decisions. The bundle carries route, the decision; asked with journey_id, route is null. At most one route exists per product, source and persona; removing a route keeps its decisions without it.

Refusals#

• A wrong invocation is refused before anything is sent: "onboarding-routes takes <every verb's usage, separated by semicolons>; got <word>", "onboarding-routes <verb> does not take <flag>; it takes …", "<flag> needs a value" and "onboarding-routes <verb> needs <flag>".
• Echo Web answers a bad request with "product_id is required: …", "journey_id is required: …", "source is required: …" or "persona is required: …" for a blank one, or "a route needs source, persona or both: what a subject must carry to get the journey"; not found with "<product> has no journey <journey>" or "no onboarding route has id <id>; echo-cli onboarding-routes list --product <id> shows them"; and a conflict with "<product> already routes source <source> and persona <persona> to <journey> as <id>; remove it first". The command prints Echo Web's sentence and exits 1.
• The bundle answers a subject no route matches with 404: "no onboarding route of <product> matches source <source> and persona <persona>; echo-cli onboarding-routes add declares one", so the product shows its own default; and a request with neither journey_id nor subject with 400: "journey_id is missing: name the journey, or name the subject (with source and persona) to be routed".