diff --git a/docs/requirements/onboarding-wizard.md b/docs/requirements/onboarding-wizard.md
new file mode 100644
index 00000000..615cc8f5
--- /dev/null
+++ b/docs/requirements/onboarding-wizard.md
@@ -0,0 +1,189 @@
+# Onboarding Wizard Contract (D4)
+
+Status: DRAFT — awaiting ratification (webui-audit S2, contract 3 of 9).
+Authority: PRD D4 (Part I §6), D11 v1 slice (Part I §9), D8 architecture
+gate (Part I §8), the identity account-lifecycle contract
+(`docs/requirements/identity-lifecycle.md`, §§2–4), and the RBAC grant
+model contract (`docs/requirements/rbac-grant-model.md`, §4.3). This
+document turns D4 into a concrete contract: what the wizard is
+architecturally, its v1 step model, mode branching, re-run/idempotency
+semantics, and what it seeds under whose authority.
+
+Scope: the Gateway-backed product onboarding wizard. Out of scope: the
+host-local install wizard (`mosaic wizard`, which drives host install and
+gateway bootstrap and is not this artifact — audit REPORT.md layer 3);
+Enterprise mode conversion (contract 6); custody enforcement semantics
+(contract 7); the deferred-beyond-v1 steps themselves (connectors, comms
+integrations, voice-matching, M365 — D11 defers them; they bind here only
+through the extensibility rule §2.4).
+
+## 1. Placement and architecture
+
+1. The wizard is a **product surface over the Gateway command API** — a
+   web UI flow (and equivalently scriptable command sequence) that
+   composes existing audited Gateway commands. It is subject to the D8
+   hard rule like every other webUI surface: no wizard operation reaches
+   the database or filesystem directly, and no wizard-only privileged
+   write path exists.
+2. **The wizard introduces no new mutation surface.** Every state change
+   it performs is an existing command with its own contract: user and
+   epoch writes under the identity contract §3, hierarchy writes under
+   contract 1 §5, grant writes under contract 2 §4, settings writes under
+   their owning command family. The one exception is the bootstrap epoch
+   transition, where the wizard drives the bootstrap writer defined by
+   identity §3 — that writer's constraints (§3.1–§3.6) bind unchanged;
+   this contract adds nothing to them.
+3. **Wizard state derives from canonical state.** Each step renders the
+   system's current configuration (read through the same commands) and
+   applies deltas; the wizard does not keep an answer file whose contents
+   can drift from reality. The wizard MAY persist run bookkeeping
+   (started/completed timestamps, mode) and MUST persist the
+   explicit-choice records other contracts mandate (registration mode,
+   identity §2.2; per-provider JIT enablement, identity §4.1) — those are
+   settings writes, not private wizard state.
+4. If a wizard-completion marker is stored, it is presentational only
+   (which entry screen to show). No authorization or gating decision may
+   read it: gating state lives where its owning contract puts it
+   (bootstrap epoch in `bootstrap_state`, registration mode in settings).
+
+## 2. Modes and extensibility
+
+1. The wizard **differs by mode** (D4): Standalone and Enterprise share
+   one skeleton; Enterprise makes personal data optional and moves focus
+   to business structure, RBAC, and external systems.
+2. **v1 ships the Standalone flow only** (D11). The mode branch point and
+   skeleton MUST still exist in v1 — mode is a property of the flow, not
+   a fork of it — but no Enterprise-only step ships, and mode conversion
+   is contract 6.
+3. Mode is chosen at bootstrap and recorded as an explicit operator
+   choice. Changing it later is conversion (contract 6), not a wizard
+   re-run.
+4. **Extensibility:** new wizards attach as tabs (D4). Attaching a wizard
+   tab is a registration of additional steps against the same skeleton,
+   inheriting this contract's rules (§1 architecture, §3 step contract,
+   §4 re-runnability). A tab cannot opt out of them.
+
+## 3. v1 step model (Standalone)
+
+The v1 wizard consists of exactly these steps, in order, each backed by
+the named authority:
+
+1. **System and company name.** System name is a settings write. Company
+   name feeds step 4's company creation.
+2. **Component choices.** Mosaic Comms/Matrix vs external; Mosaic
+   SSO/Authentik vs external; Mosaic DB/PostgreSQL vs external; vector
+   DB (D4). v1 records the choices as settings and configures what is
+   installable in-product; component provisioning beyond that is host
+   tooling, out of scope here.
+3. **Initial user.** Email/password or SSO, per identity §3: the
+   first-admin transition is atomic, one per bootstrap epoch, and the SSO
+   variant runs inside the bootstrap transaction (identity §3.6). The
+   wizard also presents registration mode (identity §2.2) and, when SSO
+   is configured, per-provider JIT with its allowlist warning (identity
+   §4.1, §4.3) — each recorded as an explicit choice, none silently
+   defaulted.
+4. **Initial hierarchy and seeding.** Creates the first company (naming
+   the initial `owner` grant in the same audited operation, contract 2
+   §4.3), an initial estate, an initial project, and an initial workspace
+   with seeded example data (D4, D11). All through hierarchy commands
+   (contract 1 §5.1); seeded examples are ordinary workspace content
+   created by ordinary commands, attributable in audit to the wizard run
+   actor.
+5. **Minimal agent enrollment.** One harness, API-key login, agent name
+   and persona (D11). Enrollment specifics belong to the agent-enrollment
+   command family; this contract binds only that the step exists, is
+   skippable, and uses that family.
+
+Steps deferred beyond v1 (user onboarding profile, connectors, comms,
+voice-matching) appear in `docs/ROADMAP.md` per D11. Note for the profile
+step when it lands: sensitive profile categories are custody-bound to the
+user's own brain (D14, contract 7); the v1 wizard collects none of them,
+so v1 ships no custody surface.
+
+## 4. Re-runnability and idempotency (D4 "no lock-in")
+
+1. **Re-run is a first-class operation.** After completion, running the
+   wizard again re-opens every step against current state (§1.3) for
+   reconfiguration. Nothing about completion locks the wizard.
+2. **The bootstrap epoch does not re-open** (identity §3.4). On re-run,
+   step 3 shows the existing admin/registration/JIT configuration and
+   allows changing the mutable parts through their normal commands;
+   "setup already completed" is a stable state, and factory reset — a
+   future, explicitly destructive operation — is the only path to a new
+   epoch.
+3. **Idempotent seeding.** Step 4 on re-run MUST NOT duplicate: the
+   initial company/estate/project/workspace are created at most once per
+   bootstrap epoch, keyed by recorded seed identity (the created node
+   ids), not by name matching. A re-run offers to create _additional_
+   hierarchy nodes (PRD: users can create N companies, N estates, N
+   projects) but never re-creates or resets the originals, and never
+   touches user content added since. Example-data seeding is likewise
+   at-most-once per epoch and is skippable.
+4. **Interrupted runs strand nothing.** The wizard is resumable at step
+   granularity: each step's apply either commits through its command (and
+   is then visible as current state to the resumed run) or leaves nothing
+   (identity §3.5 for the bootstrap step). There is no wizard-level
+   transaction spanning steps and no compensating rollback of completed
+   steps.
+
+## 5. Seeding authority (resolves contract 2 review NEW-1)
+
+1. During the bootstrap epoch, the wizard's authority to create the first
+   company is the bootstrap writer's (identity §3): there is no earlier
+   user to authorize it. The first company creation names the first admin
+   (or the operator-designated initial user) as initial `owner` (contract
+   2 §4.3).
+2. **Post-bootstrap top-level company creation** — the "N companies" flow
+   — is decided by the ruling below: any ACTIVE platform user MAY create
+   a top-level company and MUST name an initial `owner` grant in the same
+   audited operation (contract 2 §4.3); the creator naming themselves is
+   the default. Until that ruling, deny-by-default holds (contract 2
+   §3.1): no implicit creation authority exists.
+3. Child-node creation inside the wizard (estate, project, workspace
+   under the seeded company) follows contract 2 §4.3 unchanged: parent
+   `owner` authority, no automatic grant needed.
+
+## 6. Verification requirements
+
+Binding on the implementing PRs:
+
+1. **No-new-writers witness:** the wizard modules appear in no
+   class-table writer allowlist (contract 1 §6.3b) and hold no direct DB
+   access; a static assertion that wizard code reaches state only through
+   Gateway command clients.
+2. **Re-run witnesses:** complete the wizard, then re-run it to
+   completion making no changes — assert zero new hierarchy nodes, zero
+   new users, zero duplicated example content, and the bootstrap epoch
+   still completed (identity §8's epoch witnesses cover the transition
+   itself). Then a re-run that adds a second company succeeds and leaves
+   the first company and its content untouched (row-count and content
+   assertions).
+3. **Seed-audit witness:** every node, grant, and example item created by
+   a wizard run has its command audit event (contract 1 §5.2, contract 2
+   §4.4) attributing the wizard-run actor; the first-company event names
+   the initial owner grant in the same audited operation.
+4. **Explicit-choice witnesses:** after a completed run, registration
+   mode, per-provider JIT flags, mode (Standalone/Enterprise), and
+   component choices each read back as recorded values; the identity
+   contract's defaults (registration `closed`, JIT off) hold for any
+   choice the run did not explicitly make.
+5. **Gating-independence witness:** with any wizard-completion marker
+   deleted (§1.4), authorization and registration gating behave
+   identically — proving no gate reads wizard state.
+6. **Interrupted-run witness:** kill a run between steps; assert no
+   stranded partial outcome (identity §8 covers the bootstrap step; for
+   step 4, either the node set committed with its audit events or is
+   absent) and that a resumed run completes against the committed state.
+
+## Ruling request
+
+Ratify sections 1–6 as written, with one decision embedded:
+
+- Decision (§5.2): post-bootstrap, any ACTIVE platform user may create a
+  top-level company, naming an initial `owner` grant (default: self) in
+  the same audited operation. Basis: PRD Part I §4 "Users can create N
+  companies, N estates, N projects" read as end-user capability, not
+  admin-only. Alternative if rejected: top-level creation stays
+  deny-by-default and becomes a platform-admin-granted capability in a
+  later contract — nothing in this contract or contract 2 breaks either
+  way, because deny-by-default is the resting state (contract 2 §3.1).