# operator-setup-checklist Specification

## Purpose

Give a fresh deployment's first operator a visible, truthful path from nothing to a deliverable plan: a persistent checklist derived entirely from live system state, never from stored progress, so it can never disagree with the surfaces it links.

## Requirements

### Requirement: Operator surface provides a state-derived setup checklist

The operator panel SHALL provide a setup checklist that walks a fresh deployment through the minimum path from nothing to a deliverable plan. The checklist SHALL cover, as discrete steps: create an entitlement set; create a product that uses it (the product step is keyed on a published product, and its copy states that the operator panel publishes a product at creation — the panel's create path has no draft state and no separate publish control, so a standalone "publish" step could never be independently acted on); add an active price and sync it to Stripe; create a plan ladder and attach the product as a tier; choose an org-type default plan. Each step SHALL link directly to the surface where the operator completes it, and each incomplete step SHALL name what completing it unlocks (the downstream step it feeds).

Steps SHALL be classed **required** (entitlement set, published product, ladder with a rank-0 tier) or **conditional** (price plus Stripe sync, needed only when products are sold for money; org-type default, needed only when signup should confer a plan). A conditional step SHALL state its condition inline, because the system cannot judge from data whether the deployment's model needs it — a free-tier-less paid deployment legitimately never sets a default, and a free-only deployment legitimately never configures Stripe.

Every step's completion state SHALL be derived from live system state (existence queries against the same tables the linked surfaces manage). The checklist SHALL NOT store its own progress flags, so its claims cannot disagree with reality: deleting the last entitlement set un-completes that step.

#### Scenario: Fresh instance shows every step incomplete

- **WHEN** an operator views the setup checklist on a deployment with no
entitlement sets, products, prices, ladders, or org-type defaults
- **THEN** every step renders as incomplete
- **AND** each step links to the surface that completes it

#### Scenario: Completion is derived, not recorded

- **WHEN** an operator creates an entitlement set through the normal
Entitlement Sets surface and returns to the checklist
- **THEN** the entitlement-set step renders complete without the operator
having interacted with the checklist itself

#### Scenario: Completion reverses when the underlying state disappears

- **WHEN** the only entitlement set is deleted after its step showed complete
- **THEN** the step renders incomplete again

### Requirement: The checklist is persistent and revisitable, not a wizard

The checklist SHALL remain reachable for the lifetime of the deployment. It SHALL NOT gate or sequence access to any other operator surface, SHALL NOT force steps to be completed in order, and SHALL NOT require the operator to pass through it on any navigation path. It is a map, not a corridor.

#### Scenario: Steps can be completed out of order

- **WHEN** an operator creates a plan ladder before any product exists
- **THEN** the ladder step derives complete while earlier-listed steps remain
incomplete
- **AND** no checklist mechanism prevented or warned against the ordering

#### Scenario: Checklist survives setup

- **WHEN** every step is complete and an operator navigates to the checklist
surface directly
- **THEN** the checklist renders with all steps complete rather than being
removed or redirecting away

### Requirement: The checklist recedes when required setup is complete

While any **required** step derives incomplete, the checklist SHALL be foregrounded on the operator landing surface (per the `operator-panel-navigation` landing-region requirement). Once every required step derives complete, the landing surface SHALL stop foregrounding it, even when conditional steps remain incomplete; the checklist surface itself remains addressable and continues to show conditional steps with their conditions.

#### Scenario: Completed required setup no longer occupies the landing page

- **WHEN** every required checklist step derives complete and an operator
visits `/operator`
- **THEN** the landing surface does not render the setup-progress region
- **AND** this holds even when a conditional step (Stripe pricing, org-type
default) remains incomplete

#### Scenario: Conditional steps stay visible on the checklist surface

- **WHEN** an operator visits the checklist surface after all required steps
are complete
- **THEN** incomplete conditional steps still render, each stating the
condition under which it matters