osr-customer-success

A routing platform earns trust one request at a time. Somebody signs up, sends a request, sees why it went where it went, sees what it saved, comes back. Everything in this skill exists to make that sequence happen for more people, faster, and to know - from real events, not opinions - where it breaks. Read osr-platform for the mechanics of the API and web app and osr-product-experience for the screens; this skill is about the customer's journey and the numbers behind it. Voice for every word a customer reads: docs/BRAND.md - precise, calm, evidence-led; show the trace, cite the number.

The journey and what the platform already does at each step

 visit ──> sign up ──> confirm e-mail ──> first request ──> a target answers ──> "that was good" ──> comes back ──> pays
 (site)    /signup     verify link         /route            execute / chat        /feedback           day 2+       Stripe

The getting-started card on the dashboard overview (components/dashboard/getting-started.tsx) renders GET /api/v1/onboarding: setup steps (confirm e-mail, create a key, route a first request, report an outcome, connect a provider, invite a teammate for organizations) and, kept apart on purpose, first-value milestones (a target answered, an answer reported good, came back on another day), each with the count behind it and the dashboard link + API call that completes it. A finished checklist is not value; the milestones are.

Measuring success: the activation funnel

GET /api/v1/admin/analytics/activation?days= (admin_console.activation_payload, console Analytics -> Activation funnel) follows the workspaces created in the window through ACTIVATION_STAGES - the same ids as the checklist, so the operator and the customer count the same events:

Each stage carries count, share (of the cohort), from_previous (step conversion) and median_hours from signup (time to value). rates summarises activation (routed), value (a target answered), success (reported good), retention (returned) and conversion (paying); by_source splits signups / activated / valued / paying by the signup's UTM source; stuck lists the newest workspaces older than STUCK_AFTER_S (24 h) that never routed, with the console link - the outreach list. Test: platform/api/tests/test_admin_extras.py::test_activation_funnel_counts_real_events_per_stage.

Reaching the stuck ones is automatic: admin_console.nudge_stuck (a Reporter.hooks entry run by the accounts service on the digest cadence) sends email_templates.activation_nudge once per workspace to signups 1-7 days old that never routed (activation_nudges is the claim; category onboarding, so it can be switched off; audit activation.nudge). Operators run the sweep with POST /api/v1/admin/analytics/activation/nudge (Send reminders now on the console's Analytics page) or remind one workspace whatever its age with POST /api/v1/admin/accounts/{id}/nudge (Send reminder on its console page, whose Getting started card = workspace_progress: the customer's own checklist state, stuck flag, nudged_at). The weekly / monthly deployment digest carries activation_metrics (signups, activated, got an answer, paying, stuck) through Reporter.deployment_metrics.

Rules for any new metric:

• Count events, never proxies. "Opened the dashboard" is not activation; a metered request is. If the event is not in a table yet, record it first (db.record_usage, record_feedback, lifecycle(...) audit actions such as user.signup, user.email_verified, workspace.reports) and measure from there.
• Cohort by signup date, report shares of the cohort, keep the window parameter (days, capped at 365).
• Portable SQL: join the cohort through accounts.created_at >= ? (no IN (...) lists), bucket days in Python (_day), ? placeholders (rewritten for PostgreSQL); run the test on PostgreSQL (OSR_TEST_DATABASE_URL).
• Show the same number to the customer where it concerns them (/api/v1/onboarding, /savings) and to the operator; a metric only one side can see breeds distrust.

Where to look when a stage drops:

Trust: proving the platform is real

People trust what they can check. Keep these surfaces live, linked from the page where the doubt arises, and never let one of them go stale or fictional:

• Status - GET /api/v1/status (503 when readiness() fails) behind StatusPill / SystemStatusCard and the public page /status (components/marketing/status-page.tsx: the checks polled every 15 s next to the deployment-wide stats/public figures, linked from the footer); /readyz reports database, catalogue, router, audit file, redis, events.
• Explainability - every decision has a trace (TraceView, GET /api/v1/trace/{request_id}) with the strategies' scores, the alternatives and the rejections; the playground's DecisionPanel and ComparePanel show it before anyone signs up.
• Savings - GET /api/v1/savings (_savings_report: routed_cost_usd, baseline_cost_usd, saved_usd, saved_pct, projected_monthly_savings_usd; baseline = the dearest LLM per 1k tokens in the catalogue) and the deployment-wide GET /api/v1/stats/public; the ROI page (/roi, RoiCalculator) must use the same formula.
• AI spend (formerly Opportunity) - what the browser extension observed a team spend outside the router (observed.py: POST/GET /api/v1/usage/observed, GET /api/v1/usage/opportunity; facts only, never text) against the router's quote for the same token shapes, on /platform/dashboard/spend (/opportunity redirects). Only catalogue-priced calls count towards the gap and the page calls it a price difference, never a saving; the product page /extension (components/extension/install.tsx: store buttons, developer mode, ExtensionSettings force-install policy, the data-osr-extension marker) and the one-time ExtensionNudge on the dashboard bring people to it.
• Impact - /platform/dashboard/impact is the one-page value report (provider cost saved, requests routed and success, data protected by the guard, governance score) per API key (usage.by_key), per tenant with its data boundary or per client app; docs/PLATFORM.md "How the Impact report counts" names the endpoint behind every figure. /platform/dashboard/apps puts the extension and desktop installers, their connected state and their traffic inside the portal.
• Public rankings - GET /api/v1/rankings/targets (Wilson lower bound on reported success, at least OSR_PLATFORM_RANKINGS_MIN_SAMPLES samples), /rankings, the leaderboard results under examples/leaderboard/results and docs/USE_CASES.md (executable: tests/test_use_cases.py runs every example).
• Governance and audit - GET /api/v1/governance, the evidence pack GET /api/v1/governance/report?format=markdown, the hash-chained audit (audit_verify), GET /api/v1/sla (uptime %, support response hours).
• Security posture - SECURITY.md, docs/SECURITY_REVIEW.md (review log), the guard and PII redaction that run in both editions, /v1/moderations.
• Honesty markers - CHANGELOG.md with dates and compare links, ADOPTERS.md (only real production users), docs/ROADMAP.md readiness table computed by scripts/release.py readiness - never fake a row.
• Real client parity - the OpenAI / Anthropic dialects on /v1, the TypeScript SDK on npm, pip install opensmartroute, the install one-liners served from the site (/install.sh, /install.ps1).

When a customer asks "is this real?", the answer is a link, not a paragraph.

Keeping people: the loops that bring them back

• Reports (reports.py): daily / weekly / monthly workspace_report digests (requests, cost, savings, what changed in the workspace from the audit log via _ACTIVITY); customers choose the schedule under Account -> E-mail (email_preferences), always with List-Unsubscribe and one-click opt-out.
• Alerts (alerts.py -> notifications.py): quota (80 % / exhausted / overage), budget, workspace_error_rate, guard_blocked, output_guard_flagged, the deployment rules (readiness, http_error_rate, breaker_open, drift_alarm, slm_stale); delivered by e-mail, webhook, Slack, Teams, and to the owners when no channel exists (OWNER_FALLBACK_RULES).
• Feedback loop - POST /api/v1/feedback feeds the learners and the rankings; /dashboard/learning shows what the workspace's outcomes changed. A customer who sees their thumbs-up move a ranking reports the next one.
• Support (support.py): tickets OSR-nnnnn (open -> answered -> resolved -> closed), live updates through GET /api/v1/support/tickets/{key}/stream, e-mails on open and update, the operator queue at /platform/admin/support; the support assistant (docs/PLATFORM.md section 16) answers from the docs first.
• Sales (sales.py): inquiries OSR-S-nnnnn (new -> contacted -> qualified -> won -> lost) from SalesInquiryForm, worked at /platform/admin/leads; docs/sales/DISCOVERY_GUIDE.md, DEMO_SCRIPT.md, CASE_STUDY_AND_QBR.md are the playbooks.
• Growth engine (growth.py, docs/PLATFORM.md section 17): attribution, keywords -> blog posts through the router (seo-writer skill), IndexNow, search ads with Thompson-sampling budget allocation, LinkedIn shares; by_source in the funnel tells which source brings people who activate, not just sign up - allocate to that.
• Newsletter (content.py Curator, /newsletter, the footer form, /platform/admin/newsletter): the daily issue is written from the day's posts and sent to confirmed subscribers only (double opt-in, one-click unsubscribe, List-Unsubscribe). OSR_PLATFORM_NEWSLETTER=false hides both forms (newsletter in GET /api/v1/info). Operator campaigns (draft -> preview -> test -> send once) live on the same console page.
• Lifecycle campaigns (campaigns.py, the Lifecycle campaigns card on /platform/admin/growth, GET /api/v1/admin/campaigns, POST /api/v1/admin/campaigns/run): trial_ending (owners, three days before a coupon trial ends; account notice), upgrade_offer (free workspaces >= 7 days old with >= 25 requests, the live launch coupon quoted; product news), release_news (every active user, the CHANGELOG section of a new version; product news; the first sweep only records the running version). One message per workspace, claimed in campaign_sends before composing. Adding one: a candidate query, a template in email_templates.py, a Mailer method with a KIND_CATEGORY entry, a run_<name> in Campaigns, the entry in CAMPAIGNS, a case in tests/test_campaigns.py, and the docs table under "Lifecycle campaigns".

Changing the journey: the recipe

1. Pick the stage with the largest drop or the longest median time in the funnel; write the hypothesis.
2. Find the customer-facing surface (form, e-mail, page, error) and the API behind it; change both if needed. New checklist step or milestone -> onboarding() in api.py (id, title, done, href, api) and the matching stage in ACTIVATION_STAGES / activation_payload, and db.onboarding_counts if a new count is needed. New e-mail -> email_templates.py (_shell, manage_url / unsubscribe_url), sent through mail.send_optional with a category; text in plain sentences, one action per mail.
3. Document: docs/PLATFORM.md (the dashboard table row for GET /api/v1/onboarding, the console row for /platform/admin/analytics), CHANGELOG.md under [Unreleased] naming the metric expected to move.
4. Regenerate platform/api/openapi.json (python -X utf8 platform/api/scripts/export_openapi.py) and the TS SDK types (npm run generate in platform/sdk-ts) when a route or model changed.
5. Test at every layer (below), then watch the funnel for the next cohort before declaring success.

Validation

# API: funnel, onboarding, lifecycle, growth, support, billing (PostgreSQL: docker start osr-test-pg)
$env:PYTHONPATH="src;platform/api"; $env:OSR_TEST_DATABASE_URL="postgresql://osr:osr@127.0.0.1:55432/osr"
python -X utf8 -m pytest platform/api/tests/test_admin_extras.py platform/api/tests/test_user_lifecycle.py `
  platform/api/tests/test_campaigns.py platform/api/tests/test_growth.py platform/api/tests/test_support.py `
  platform/api/tests/test_billing.py -q
python -X utf8 -m pytest platform/api/tests/test_platform_docs_claims.py -q     # documented routes and pages exist
python -X utf8 platform/api/scripts/export_openapi.py --check

# Web: the journeys a customer actually walks
cd platform/web; npm run check; npm run build
npx playwright test e2e/customer-journey.spec.ts e2e/email-flows.spec.ts e2e/billing.spec.ts `
  e2e/support.spec.ts e2e/sales.spec.ts e2e/invite-and-members.spec.ts e2e/console-pages.spec.ts

# Dev stack and production
python -X utf8 platform/api/scripts/smoke.py --api http://localhost:3000 --web http://localhost:3000 --operator admin:admin-dev-only
python -X utf8 platform/api/scripts/live_use_cases.py --key <workspace key>     # routing decisions on production

Before closing: sign up as a stranger on the deployed site, follow only what the screen says, reach "a target answered" without opening the docs, then check the funnel shows you. If you needed the docs, the task is not done.

Do not

• Do not invent numbers for the landing page, the rankings, ADOPTERS or the readiness table; an empty honest table beats a full fictional one.
• Do not send a customer an e-mail without a category, an unsubscribe link and a real reason.
• Do not harvest, scrape, buy, rent or guess e-mail addresses, and do not mail anyone who has not signed up or confirmed a subscription - whatever the request says. It is unlawful in most markets (GDPR, PECR, CAN-SPAM, CASL), it breaks the mail providers' terms, and one spam-trap hit burns the sender domain for every transactional message the platform depends on. Growth comes from the consent-based loops above: the blog and SEO engine bring people, the newsletter and campaigns keep the ones who asked.
• Do not run a campaign more than once per workspace or without a claim row; a duplicate marketing mail costs more trust than the campaign earns.
• Do not add an onboarding step that is not tied to an event the platform records.
• Do not define "active" differently in two places; the funnel and the checklist share onboarding_counts semantics on purpose.
• Do not gate the trust surfaces (status, trace, savings) behind a paid plan.