feat(onboarding): add Getting Started journeys

[lfnandoo]

Outcome

Delivers Phase 1 — Getting Started foundation and first complete vertical slice of the onboarding roadmap. A first-time user can choose a private Parallax demo or connect production data, resume the journey from anywhere in the product, and continue into the initial Product Tour.

This branch starts from main at 88f11cf7 and contains one focused onboarding commit.

Full onboarding plan

The product roadmap remains the three-journey flow documented in plans/onboarding/OVERVIEW.md:

1. Entry and choice

   • Start after authentication with the user's current Team/workspace context.
   • Ask one question: explore SignalPilot with demo data or connect production data.
   • Keep the choice reversible and make incomplete work resumable.

2. Demo journey

   • Create a personal Demo Team.
   • Fork the allowlisted Parallax Xata parent into a private writable branch.
   • Import the matching public dbt repository and wait for compiled metadata.
   • Open a versioned saved Chat Agent replay without consuming a live request.
   • Offer suggested live questions, enforce the demo allowance on the server, and route the user to the Product Tour or production setup.
   • Remove the demo project, private Xata branch, and connection before deleting the Demo Team.

3. Production setup journey

   • Use the active non-demo Team, or create a production Team when leaving a Demo Team.
   • Import a GitHub/dbt project.
   • Create or choose a warehouse connection, test it, verify compatibility, and link it to the imported project only after a healthy test.
   • Store Team-scoped Anthropic access.
   • Invite one technical teammate or explicitly skip the optional step.
   • Recompute readiness from real project, connection, dbt, and key state; then open Chat Agent with the project selected.

4. Product Tour journey

   • Reuse the persistent Getting Started controller across product routes.
   • Guide the user through asking a question, inspecting governed work, exploring schema/lineage and knowledge, and inviting a teammate.
   • Keep setup progress attached to the Team and tour progress attached to the user.
   • Allow collapse, resume, restart, and session-only dismissal.

5. Acceptance and rollout

   • Exercise Demo, Setup, fallback/resume, cleanup, and Product Tour in a configured cloud environment.
   • Verify Clerk Team transitions, Xata branch isolation, GitHub/dbt compilation, warehouse test-and-link behavior, Anthropic BYOK, request-limit concurrency, narrow-screen behavior, and deletion cleanup.
   • Configure SP_DEMO_XATA_ORG and SP_DEMO_CATALOG; keep XATA_KEY in deployment secrets only.
   • Resolve the remaining product choices: demo retention, feature surface, exact tour pages, and technical-invite role.

Phase status

Phase	Status	Scope
Phase 0 — Product contract and clickable prototype	Complete on main	Three-journey UX, state ownership, warehouse auto-link contract, and shareable mockup.
Phase 1 — Foundation and vertical slice	Implemented in this PR	Persistent controller; Demo Team/bootstrap/replay/limit/cleanup; resumable setup; test-and-link; Team key/invite/readiness; initial tour; free-tier project entitlement split.
Phase 2 — Cloud acceptance and hardening	Not yet accepted	Live Clerk/Xata/GitHub/dbt/warehouse/BYOK flows, concurrency and cleanup failure drills, responsive/browser acceptance.
Phase 3 — Rollout and product completion	Planned	Deployment configuration, telemetry/operational monitoring, product-choice closure, staged release and production evidence.

This PR is therefore at Phase 1. It provides local automated evidence, but it does not claim staging or production acceptance.

What changed in this phase

• Added the global compact/drawer Getting Started controller with persisted Demo, Setup, and Tour state.
• Replaced the legacy cloud onboarding entry with the Demo vs Connect choice and added a Team-switcher re-entry point.
• Added an allowlisted, idempotent Parallax demo bootstrap that provisions private Xata data, imports the paired dbt project, and seeds an authorized Chat replay.
• Added an atomic server-side five-live-request Demo Team limit, remaining-usage UI, suggested questions, and upgrade/setup next actions.
• Preserved demo ownership tags and made project/branch/connection cleanup a prerequisite for Demo Team deletion.
• Reused production GitHub import, connection, Anthropic-key, invitation, and readiness surfaces inside the setup journey; the connection is linked only after a successful test.
• Added tour targets across Chat, connections, schema, lineage, knowledge, and Team screens.
• Made dbt projects/lineage available to Free Teams while retaining paid gating for user-managed notebook sessions; Free Teams allow the owner plus one teammate.

Validation

• uv run pytest tests/test_getting_started_policy.py tests/test_demo_connector_isolation.py -q — 34 passed.
• npm run test:unit -- --run lib/getting-started.test.ts lib/api/error-messages.test.ts components/chat/chat-message.test.tsx — 20 passed.
• npm run typecheck — passed.
• uv run ruff check <changed Python files> — passed.
• git diff --cached --check — passed before commit.

Deployment notes

• XATA_KEY is server-side only and must come from the deployment secret store.
• The checked-in catalog exposes only Parallax because it has the paired allowlisted dbt repository.
• Live cloud/browser acceptance remains the Phase 2 gate; local tests are not evidence that staging or production is ready.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
signal-pilot	Ready	Preview	Sep 5, 2026 4:03am UTC
signal-pilot-docs	Error		Sep 5, 2026 4:03am UTC