Wizard Is the Universal Product Entrypoint

Status: Accepted · 2026-06-09 Scope: repo:main (platform + app.askthew.com) and the Wizard iOS app Related: architecture.md (W ecosystem), Mobile Auth And Workspace Resolution

Context

Two observations forced this decision:

1. The web (app.askthew.com) onboards a new product or project context via voice or W Card. The Wizard iOS app onboards via a W Card built from typed / spoken / photographed input. Both flows do the same job: capture the crux of the project and seed it.
2. A Google sign-in redirect bug on mobile sent the user to app.askthew.com — a different product surface (the post-onboarding console) — instead of back into Wizard. This exposed that "product", "form factor", and "URL" were tangled, and that the onboarding flow was implemented twice without a shared contract.

We were treating Wizard as "the mobile app" and the web onboarding as a separate, unnamed flow. They are the same product.

Decision

Wizard is the platform's universal entrypoint — capture → W Card → seed project context — rendered on whatever surface the user is on. It is not a mobile app, and it is not separate from the web.

• The W Card is the canonical entrypoint artifact and the contract. Every onboarding surface produces the same W Card and calls the same seed/promote API.
• Capture engines are per-surface and intentionally different; their output is identical:
  • Wizard-mobile → on-device Apple Intelligence (Foundation Models for six-W extraction; dictation; Vision OCR).
  • Wizard-web → server voice / LLM + the W-Card form.
• The web's existing voice/W-Card onboarding is Wizard-web — it already exists; it must be factored out and named, not rebuilt.

Architecture

ONE onboarding capability (platform):  capture → W Card → seed project context
   │  shared: W Card schema · seed/promote API · flow shape · design language
   ├─ Wizard-mobile : capture engine = on-device Apple Intelligence (text · dictation · photo-OCR)
   └─ Wizard-web    : capture engine = server voice / LLM + W-Card form
                       ↓
               canonical W Card  →  /seed  →  project context

Consolidate: the W Card schema, the onboarding flow shape (capture → review → seed), the seed/promote endpoint, the design language. Keep surface-specific: the capture engine and the modalities offered (mobile on-device vs web server). We unify the output, not the engines.

What converges, what diverges

• Converge — at the entrypoint. Before project context exists, both surfaces run the same Wizard intake against the same W Card contract. "Fewer functionality on mobile" does not apply here: the entrypoint is identical.
• Diverge — after project context exists. Mobile Wizard stays capture-focused (keep capturing / quick edits); web graduates the user into the console (Why / operate). The console is the surface you graduate into, not what onboarding shows.

Routing & auth implication (and the bug fix)

Route by onboarding state, not by surface.

• Native Wizard auth → askthew://auth-callback (stays in the app). Add it to the Supabase Redirect URLs allowlist so Supabase stops falling back to the Site URL. Never bounce native auth to a web product.
• After mobile auth:
  • no project context yet → stay in mobile Wizard intake.
  • project context exists → show the mobile project view (scoped).
• Web mirrors this: onboarding state decides Wizard-intake vs console.

The redirect bug and the architectural error were the same mistake — sending the entrypoint to the destination.

Consequences

• Onboarding becomes a single platform capability with a stable contract; web and mobile can no longer drift into two different onboardings.
• Wizard-web ships as a factoring-out of existing flow, not a new build.
• Mobile's smaller surface is now correctly framed as scope-by-mode (capture vs operate), not feature-parity debt.
• Auth/landing is deterministic per surface and onboarding state.

Sequence

1. Now: fix native auth to land in-app (Supabase redirect allowlist). Stops Wizard from ever showing the console.
2. Now: define the onboarding contract — W Card schema + seed/promote flow + a "modality adapter" interface that both Wizard-web and Wizard-mobile implement.
3. Soon: refactor web onboarding and mobile intake to both target that contract (two adapters, one flow).
4. Later, only if needed: formalize a dedicated Wizard-web surface (route or subdomain) reusing the contract — a capture surface, not a console clone.

Open item

Author the onboarding contract spec (W Card schema · seed/promote API · modality-adapter interface) as the single artifact both surfaces implement. This is what makes "build it once, render per surface" real.