Run: concierge-wizard-ui

• branch: claude/concierge-wizard-ui-pipeline-aqnww8
• pr: #609

Stub: Concierge wizard UI (/onboarding in apps/web)

• feature-slug: concierge-wizard-ui
• epic: tenant-onboarding-wizard
• personas: Admin, Vendor
• initiative: Build the Bridge / objective: Q2-2026 O1 — Establish PMF with Vendor Partners
• depends-on: blueprint-commit-service, onboarding-concierge-agent
• sequence: 6 of 7

Problem

Everything below this stub is headless. The first user needs the actual setup-assistant surface in the main platform: the two-pane concierge from the demo — chat on the left, live blueprint filling in on the right — plus what the demo skipped: reviewing and verifying items, and a launch that really commits.

Proposed change

An /onboarding route in apps/web porting the demo concierge experience (apps/demo/app/onboarding/concierge/ + components/onboarding/) onto real parts: chat wired to the stub-5 streaming route via useChat; blueprint panel rendering the persisted blueprint live (sections reveal as drafted, confidence badges shown); per-item review controls (approve / edit / reject) that update review state via server actions; a verify step that advances the blueprint to verified once every section is reviewed; and a launch action calling the stub-3 commit service, with success ("workspace ready") and failure states. Resumable: reloading mid-setup restores conversation context and blueprint progress.

Acceptance criteria (rough)

• A first user on a fresh tenant can complete the whole journey at /onboarding: converse, watch the blueprint fill in, review every item, verify, launch — and land in a workspace where the committed records exist in the normal CRUD surfaces.
• Items can be approved, edited inline or rejected before launch; launch is blocked until the blueprint is verified.
• Leaving and returning mid-setup restores progress (persisted blueprint + conversation state).
• Commit failure surfaces a clear retryable error — the user is never dropped into a half-configured workspace silently.

Out of scope (this feature)

• Forcing users to this route (stub 7 does the redirect gating; here the route merely exists and works).
• Onboarding models B/C UI patterns (import wizard, review board).
• Mobile-first polish beyond the responsive baseline (demo hides the panel below lg — acceptable v1).

Notes for Define

Port, don't import: apps/demo components are local shadcn (dashboard-page skill warns about this) — rebuild on @sustentus/ui per web conventions. Route policy + nav wiring per web-route skill (deny-by-default: an unlisted route silently redirects). Server actions follow the three-step pipeline (server-action skill). touches: apps/web/app/(app)/onboarding/, apps/web/lib/route-policies.ts, packages/ui if any primitive is missing.

Spec: Concierge wizard UI (/onboarding)

• slug: concierge-wizard-ui
• personas: Admin, Vendor
• touches: apps/web/app/(app)/onboarding, apps/web/lib/route-policies.ts, apps/web/components/onboarding, packages/ui (only if a primitive is missing)
• complexity: complex

Problem

Everything beneath this feature in the tenant-onboarding-wizard epic is now built but headless: the blueprint document (stub 1), the reusable agent core (stub 2), the atomic commit service (stub 3), the source-analysis pipeline (stub 4) and the streaming concierge agent + /api/onboarding/chat route (stub 5) all exist server-side, but a fresh tenant's first user has no surface to actually run setup. This feature is the surface: the two-pane concierge from apps/demo — chat on the left, the live blueprint filling in on the right — brought into apps/web on real AI and real data, plus the parts the demo skipped (per-item review, a verify gate, and a launch that really commits). It directly advances Build the Bridge / Q2-2026 O1 — Establish PMF with Vendor Partners (KR: onboard 8+ vendors onto paid tiers): without a working setup surface a fresh vendor tenant cannot self-serve into a configured workspace.

Proposed change

An /onboarding route in apps/web that ports the demo concierge experience (apps/demo/app/onboarding/concierge/ + apps/demo/components/onboarding/) onto the real backend. Two panes:

• Chat (left) — wired to the stub-5 streaming route POST /api/onboarding/chat via useChat. Sending a message streams the concierge's reply; the conversation drives the persisted blueprint.
• Blueprint panel (right) — renders the tenant's persisted blueprint live (onboardingBlueprintService.getBlueprint/getOrCreateBlueprint): sections reveal as they are drafted, each item shows a confidence badge, and the panel reflects server state (not local mock), so a reload restores it.

On top of the demo:

• Per-item review controls — approve / edit / reject on each blueprint item, persisted through server actions (the three-step Zod → resolveActionContext → runActionBody pipeline) calling setItemReviewState. Edit opens an inline editor over the item's human label and the structured data fields that actually commit (e.g. product name/description, SLA target/warning days, setting value); saving stamps the item reviewState: edited, provenance: human_edited. Approve → approved, reject → rejected.
• Verify step — advances the blueprint in_review → verified via advanceStatus(tenantId, "verified"), enabled only when every item across all sections is decided (approved / edited / rejected — no pending remains). Rejected items count as reviewed; they simply won't commit. When items are still pending, Verify is blocked and the panel shows what's outstanding.
• Launch — disabled until the blueprint is verified; calls commitBlueprint(tenantId) (stub 3) through a server action. On success it renders a "workspace ready" success screen summarising the records created, with an explicit CTA into the app (the user chooses when to leave — no auto-redirect; forced routing is stub 7). On failure it surfaces a clear, retryable error and keeps the user on /onboarding (the blueprint stays verified).

Route reachability is added to apps/web/lib/route-policies.ts (deny-by-default; the /onboarding page must be listed for admin/vendor or it silently redirects), with nav wiring per the web-route skill. Demo components are ported, not imported — they are local shadcn, so they are rebuilt on @sustentus/ui per web conventions.

Acceptance criteria

• /onboarding exists in apps/web, is reachable by an admin/vendor user (route-policy entry present), and renders a two-pane layout — chat left, live blueprint right (the panel may collapse below the lg breakpoint, matching the demo's responsive baseline).
• The chat pane is wired to POST /api/onboarding/chat via useChat; sending a message streams the concierge's reply, and the conversation progressively fills the blueprint panel.
• The blueprint panel renders the persisted blueprint (server state): sections reveal as they are drafted and each item shows a confidence badge — not the demo mock spine.
• Each blueprint item can be approved, edited inline (label + the committing data fields; stamps edited / human_edited), or rejected before launch, each persisted via a server action; the panel reflects the new review state.
• Verify advances the blueprint to verified only when no item is pending (every item approved / edited / rejected); while any item is pending, Verify is blocked and the outstanding items are indicated.
• Launch is disabled until the blueprint is verified; on click it commits via commitBlueprint, and on success shows a "workspace ready" screen (summary of committed records) with an explicit CTA into the app — and the committed records are then present in the normal CRUD surfaces.
• A commit failure surfaces a clear, retryable error and leaves the user on /onboarding with the blueprint still verified — the user is never silently dropped into a half-configured workspace.
• The flow is resumable: leaving and returning to /onboarding mid-setup restores blueprint progress (persisted document) and conversation context (prior messages replayed), continuing rather than restarting.

Out of scope

• Forcing the first user to /onboarding / redirect gating — that is stub 7 (first-run-gating); here the route merely exists and works.
• Onboarding interaction models B/C UI (import wizard, autopilot review board) — concierge only.
• Auto-redirecting the user into the app after launch — decided against (success screen + explicit CTA instead).
• Mobile-first polish beyond the responsive baseline (the demo hides the panel below lg — acceptable for v1).
• Post-launch editing of committed blueprint areas — already covered by the existing per-entity CRUD surfaces.
• Any change to the stub-5 chat route, the stub-3 commit service, or the blueprint model/service — this feature consumes them as-is.

Open questions

none — the three UX decisions (post-launch landing = success screen + CTA; inline edit scope = label + committing fields; verify gate = every item decided) are settled above.

Build notes: concierge-wizard-ui

• commits: feat: concierge-wizard-ui — /onboarding concierge wizard on real backend

What changed

• apps/web/lib/route-policies.ts: added a /onboarding policy (admin, vendor) so the deny-by-default proxy lets the page through. /api/onboarding/ was already policy-locked (stub 5).
• apps/web/lib/nav.ts + apps/web/components/sidebar/app-sidebar.tsx
• apps/web/app/(app)/onboarding/page.tsx: server component — resolves tenant + role, getOrCreateBlueprint, serialises it, and renders the two-pane workspace. Passes the role-home CTA for the success screen.
• apps/web/app/(app)/onboarding/actions.ts: five server actions on the explicit Zod → resolveActionContext({ allowedRoles: ["admin","vendor"] }) → runActionBody pipeline: getBlueprintStateAction, reviewBlueprintItemAction (approve/reject), editBlueprintItemAction, verifyBlueprintAction, launchBlueprintAction.
• apps/web/lib/onboarding/serialize.ts: server-only projection of the Mongoose blueprint into a JSON-safe shape for the client.
• apps/web/components/onboarding/: ported the demo concierge onto real AI + data — types.ts (client mirror types + per-section metadata / editable fields), onboarding-workspace.tsx (state + action orchestration), concierge-chat.tsx (useChat → /api/onboarding/chat, localStorage resume), blueprint-panel.tsx (persisted sections, progress, verify/launch), blueprint-item.tsx (per-item approve/edit/reject + inline editor), confidence-badge.tsx, launch-complete.tsx (committed-records summary + CTA).

Design decisions

• No service change (spec Out-of-scope respected). The blueprint service exposes no single-item edit, so editBlueprintItemAction reads the section and rewrites it via upsertSection, preserving every other item's review state/provenance and stamping the edited item edited / human_edited.
• Inline-edit scope = committing fields. The editor exposes the human label plus the data fields the commit service actually reads (name/description, SLA target/warning/breach days, setting value). Structural cross-references (productKeys, serviceKey, stage) are preserved untouched via a merge, so an edit can't break the atomic commit.
• Verify gate. verifyBlueprintAction advances → verified only when ≥1 item exists and none are pending; it is idempotent once verified/committed. advanceStatus is forward-only, so a blueprint handed over at in_review (by the concierge's mark_blueprint_complete) advances cleanly.
• Launch failure is retryable. A failed commit throws its reason back through runActionBody as a normal ActionError; the blueprint stays verified (the commit service's abort path), so the user is never dropped into a half-configured workspace.
• Resumability. Blueprint progress is the persisted document (loaded server-side). Conversation context is replayed from per-tenant localStorage — the concierge itself resumes from the persisted blueprint server-side (stub 5), so the interview continues rather than restarts even with no local history. Chosen because neither stub 5 nor the BRD flow persists chat transcripts, and touching the stub-5 route is out of scope.
• Responsive baseline. The blueprint panel is hidden below lg (matching the demo); mobile polish is explicitly out of scope for v1.

Branch note

Build was committed to the run's existing branch claude/concierge-wizard-ui-pipeline-aqnww8 (PR #609) — the pipeline's one-PR-per-run invariant requires continuing on the run branch rather than the session's auto-named branch.

Acceptance criteria status

• /onboarding exists in apps/web, reachable by admin/vendor (route-policy entry), two-pane layout (chat left, live blueprint right; panel hidden below lg).
• Chat pane wired to POST /api/onboarding/chat via useChat; messages stream and progressively fill the blueprint panel (background refresh after each assistant turn).
• Blueprint panel renders the persisted (server) blueprint: sections reveal when they have items, each item shows a confidence badge — no demo mock spine.
• Each item can be approved, edited inline (label + committing data fields; stamps edited / human_edited), or rejected — each persisted via a server action; the panel reflects the new state.
• Verify advances → verified only when no item is pending; while any is pending, Verify is disabled and the outstanding count is shown.
• Launch is disabled until verified; commits via commitBlueprint; on success shows a "workspace ready" screen (records summary) with an explicit CTA. Committed records land in the real collections (commit service), i.e. the normal CRUD surfaces.
• Commit failure surfaces a clear, retryable error and keeps the user on /onboarding with the blueprint still verified.
• Resumable: returning to /onboarding restores blueprint progress (persisted document) and conversation context (localStorage replay); the concierge continues from persisted state.

Verify result

• mechanical checks (format · lint · typecheck · build) run in CI + the Vercel preview, not here.

Notes for review

• The inline editor deliberately does not expose structural reference fields — confirm that matches the intended review scope.
• Conversation resume is client-side (localStorage) by necessity (no server-side transcript store, and the stub-5 route is out of scope); the agent's own resume is server-side from the blueprint.
• New Sparkles icon added to the sidebar icon map for the nav entry.

Changelog: concierge-wizard-ui

Published as apps/help/app/changelog/2026-07-08-concierge-wizard-ui/page.mdx.

• personas: admin, vendor
• title: Set up your workspace by chatting with an AI concierge

You can now set up your whole workspace from one place. Open setup and chat with an AI assistant — as you answer, it drafts your company profile, product and service catalogue, skills, SLAs and settings into a live blueprint beside the conversation. Review each item before anything goes live (approve, edit inline, or drop it), then verify and launch to create it all in one step. Progress and conversation are saved, so you can leave and come back.

Fresh vendors can now self-serve their entire workspace setup

Who it's for: Vendors and admins setting up a new tenant What shipped: An AI concierge at /onboarding that interviews the first user, drafts their whole workspace — profile, catalogue, skills, SLAs, settings — and commits it live once every item is reviewed and verified. Why it matters: Removes the manual-setup barrier to getting vendors onto paid tiers — Build the Bridge, Objective 1: Establish Product-Market Fit with Vendor Partners.

Dig deeper: <merged-PR-URL> · <changelog-entry-URL>