Goal: Tenant Onboarding Milestones (NUX)

State

Lifecycle: Completed — merged to arda-frontend-app main 15–16 October 2026.

Give a new tenant a reason to reach real value in its first session instead of landing on an empty grid: an in-app onboarding guide with a single goal — 25 items — and a free starter kit earned at the goal. Record the tenant’s progress as milestones (observed facts such as “added first item via scan”, each stamped with when and by whom) so that customer success can see where a trial stalled without asking, and so the guide can decide what to show from durable state rather than from the browser.

User Stories

As a new tenant, I want a guided path to my first 25 items with a free starter kit as the reward, so that I reach real value in my first session instead of an empty grid.
As a customer-success operator, I want the tenant’s onboarding progress recorded as durable milestones, so that I can see where a trial stalled without asking them.

Linear Tickets

PDEV-1830 — Tenant NUX: onboarding milestones on Tenant.settings — Done. Re-scoped from its original creationChannel-on-Item plan to the milestones model; carries the as-shipped scope and the follow-up list.
PDEV-2150 — Mint per-tenant starter-kit discount codes on the BFF or backend — Backlog. Replaces the shared free-shipping code with single-use, per-tenant codes.

Repositories

Repository	Role	Changes
`arda-frontend-app`	Guide UI, onboarding provider, and the BFF package that owns milestone writes	New `@arda-cards/bff/onboarding` package (`/bff/onboarding/*`); every item create routed through the BFF; onboarding provider and hooks; guide, header meter, kit fulfilment; mock handlers and scenario picker
`accounts-component`	Stores the milestones	No change — V1 uses the existing free-form `Tenant.settings` blob. The dedicated module is the graduation path (see the specification)
`documentation`	This project directory	Goal, as-built specification, atlas

Success Criteria

A tenant short of 25 items sees a header meter and can open a guide that offers every add method; a tenant first seen at ≥25 items with no milestones sees nothing.
Each in-app item-creation method’s first successful use is recorded once, server-side, over an item that was actually created — never over one that failed, never twice per key. item-added-email is the V1 exception: it records the inbox-wizard click-out, not a confirmed creation.
At 25 items the starter kit is created, remembered on the tenant, and queued in the order queue, in one idempotent call; a retry never mints a second kit.
The kit’s order URL is correct the moment the kit exists: free shipping applied, tenant and account email carried as order attributes (verified on Shopify test order #G2GCNFIVJ).
Placing the kit order records nux-completed, after which the meter and guide are hidden permanently and nothing further is written.
No milestone is ever written by the browser directly; the BFF stamps actor and time from the verified JWT.

Context

The product’s earlier onboarding work (Userflow tour, “Web to product” flow, the IMTS new-user journey design) left the first session without a persistent, server-known notion of progress. PDEV-1830 originally proposed tagging each Item with a creationChannel; the product owner redirected it to a per-tenant milestones model so progress is a small, key-based record rather than something derived from the item set.

The frontend BFF (API proxy) already held the session and talked to ARDA on the browser’s behalf, which made it the natural single writer for milestones without a backend change.

Scope

In Scope

Milestone vocabulary, allowlisted and enforced at the BFF.
BFF endpoints: read milestones, record a non-item milestone, create an item with its method, claim the starter kit; completion recorded on the kanban card walk.
Onboarding provider composed from single-purpose hooks (tenant record, engagement latch, auto-open once per sign-in, kit fulfilment policy).
Guide modal, header meter, celebration and kit sheet; the inbox click-out recorded as item-added-email.
Free shipping via a standing Shopify code on the kit’s cart permalink, decoupled from the SupportToolKit reward ladder.
Mock-mode parity so the whole NUX can be driven end to end without a backend.

Out of Scope

creationChannel item provenance — orthogonal analytics value; separate backlog item (DQ-M7).
A dedicated bitemporal onboardingMilestone module in accounts — the graduation path; design retained in the specification.
Backend- or toolkit-recorded item-added-email and server-side idempotency for a simultaneous kit claim.
Per-tenant minted discount codes — PDEV-2150.
The SupportToolKit 48h welcome-kit producer’s overlap with this offer — product call, outside this project.

Constraints

No backend change: milestones live on Tenant.settings, read-merge-PUT by the BFF in one round trip.
Existing tenants must see nothing on deploy — eligibility is judged from the item count and the absence of milestones, and only an enrolled tenant’s adds are recorded.
Nothing may be granted on the strength of a cart attribute; they are attribution only.
The server decides and records completion; the client reads it. No client-side watch on the kit’s card.
One route for every item add, so the method travels with the create and the milestone is written over the created row.

Deliverables

#	Deliverable	Location
1	BFF onboarding package	`arda-frontend-app/packages/bff/src/onboarding/` (#1438)
2	Item create via BFF	`src/hooks/collections/items/useAddItem.ts`, `useAddItems.ts` (#1441)
3	Onboarding provider and hooks	`src/components/onboarding/` (#1443)
4	Guide UI, meter, kit fulfilment, completion	`src/components/onboarding/` (#1422)
5	As-built specification	specification.md
6	Ticket and PR map	atlas.md

Reference Documents

Specification — decisions, product rules, write path, provider, UI, trade-offs, graduation path.
Atlas — the PR stack, increment traceability, follow-ups.
API proxy (frontend BFF) — the platform the endpoints are built on.