old sprints work, new sprints for exposing functionality via cli, improve code_of_conduct and other agents instructions

docs/modules/platform/platform-service.md

@@ -84,3 +84,75 @@ Provide a single, deterministic aggregation layer for cross-service UX workflows
 
 ## Gateway exposure
 The Platform Service is exposed via Gateway and registered through Router discovery. It does not expose direct ingress outside Gateway in production.
+
+## Setup Wizard
+
+The Platform Service exposes setup wizard endpoints to support first-run configuration and reconfiguration workflows. These endpoints replace UI-mock implementations with real backend state management.
+
+### API surface (v1)
+
+#### Sessions
+- `GET /api/v1/setup/sessions` - Get current setup session for tenant
+- `POST /api/v1/setup/sessions` - Create new setup session
+- `POST /api/v1/setup/sessions/resume` - Resume existing or create new session
+- `POST /api/v1/setup/sessions/finalize` - Finalize setup session
+
+#### Steps
+- `POST /api/v1/setup/steps/execute` - Execute a setup step (runs Doctor checks)
+- `POST /api/v1/setup/steps/skip` - Skip an optional setup step
+
+#### Definitions
+- `GET /api/v1/setup/definitions/steps` - List all step definitions
+
+### Setup step identifiers
+
+| Step ID | Title | Required | Depends On |
+|---------|-------|----------|------------|
+| `Database` | Database Setup | Yes | - |
+| `Valkey` | Valkey/Redis Setup | Yes | - |
+| `Migrations` | Database Migrations | Yes | Database |
+| `Admin` | Admin Bootstrap | Yes | Migrations |
+| `Crypto` | Crypto Profile | Yes | Admin |
+| `Vault` | Vault Integration | No | - |
+| `Scm` | SCM Integration | No | - |
+| `Notifications` | Notification Channels | No | - |
+| `Environments` | Environment Definition | No | Admin |
+| `Agents` | Agent Registration | No | Environments |
+
+### Setup session states
+
+| Status | Description |
+|--------|-------------|
+| `NotStarted` | Setup not begun |
+| `InProgress` | Setup in progress |
+| `Completed` | All steps completed |
+| `CompletedPartial` | Required steps completed, optional skipped |
+| `Failed` | Required step failed |
+| `Abandoned` | Setup abandoned by user |
+
+### Setup step states
+
+| Status | Description |
+|--------|-------------|
+| `Pending` | Not yet started |
+| `Current` | Currently active step |
+| `Passed` | Completed successfully |
+| `Failed` | Validation failed |
+| `Skipped` | Explicitly skipped |
+| `Blocked` | Blocked by dependency |
+
+### Security and scopes
+- Read: `platform.setup.read`
+- Write: `platform.setup.write`
+- Admin: `platform.setup.admin`
+
+### Offline posture
+- Sessions include `DataAsOfUtc` for offline rendering with stale indicators
+- Step results cached with Doctor check pass/fail status
+- Suggested fixes generated for failed checks
+
+### Related documentation
+- UX flow specification: `docs/setup/setup-wizard-ux.md`
+- Repository inventory: `docs/setup/setup-wizard-inventory.md`
+- Doctor checks: `docs/setup/setup-wizard-doctor-contract.md`
+