Davincc77 · Davincc77 · May 24, 2026 · May 24, 2026
diff --git a/SPEC.md b/SPEC.md
@@ -1973,6 +1973,36 @@ This section restates, in one place, the privacy and stability invariants that a
 
 These invariants apply equally to the production v3.x line and the v4 preview track. The preview adds new *fields*; it does not relax existing privacy or stability rules.
 
+### §33.11 Normative onboarding contract — R4-P0-1 (`user.klickd` wizard)
+
+While the field surface of §33 remains preview / non-normative, the
+**user-visible onboarding flow** for any future v4 `user.klickd`
+writer is now constrained by a normative companion document:
+
+- [`docs/spec/R4-P0-1-onboarding-wizard.md`](./docs/spec/R4-P0-1-onboarding-wizard.md) — Normative (V4 P0).
+
+That document binds, in RFC 2119 language, the seven-step
+`user.klickd` onboarding wizard with mandatory reload verification
+(step 6). It is **docs-only** and does **not** introduce any new
+on-the-wire field, schema, SDK API, vector, package version, Git
+tag, or release. It does **not** relax or modify the §33.7
+forward-compatibility contract or the §33.10 privacy invariants.
+
+R4-P0-1 lands ahead of the wider P0-1 SPEC §33 field-surface
+promotion because the empirical UX research
+([`docs/roadmap/V4-UX-DX-RESEARCH-NOTES.md`](./docs/roadmap/V4-UX-DX-RESEARCH-NOTES.md))
+shows the onboarding contract is the load-bearing piece that
+determines whether `.klickd` v4 can reach non-developer users at
+all. Strict schema (P0-2), SDK alignment (P0-3 / P0-4), and
+vectors (P0-6) remain on their own tracks. The QR / deeplink
+onboarding trigger remains out of scope for R4-P0-1 and is
+governed by [`docs/ux/V4-ONBOARDING-QR-DEEPLINK.md`](./docs/ux/V4-ONBOARDING-QR-DEEPLINK.md).
+
+When the §33 field surface is itself promoted to the normative SPEC
+body in a future PR, the cross-reference inside
+[`docs/spec/R4-P0-1-onboarding-wizard.md`](./docs/spec/R4-P0-1-onboarding-wizard.md) §3.2 MUST be updated to
+point at the new normative SPEC section.
+
 ---
 
 ## License

diff --git a/docs/roadmap/ROAD-TO-V4-GA.md b/docs/roadmap/ROAD-TO-V4-GA.md
@@ -259,10 +259,10 @@ Chaque entrée précise : *Objet → Livrables → Critères de sortie (Definiti
 
 - **Objet :** interface guidée (web component / page dédiée) qui génère un `user.klickd` valide **sans exposer le JSON brut**. Étape 6 = recharger le fichier dans le wizard avant de quitter — non-négociable.
 - **Pourquoi :** 1Password, Obsidian, Bitwarden convergent ; sans wizard avec rechargement, `.klickd` reste réservé aux développeurs et l'onboarding crée des fichiers non-réouvrables.
-- **Livrables :** spec UX dans [`docs/ux/V4-UX-SPEC.md`](../ux/V4-UX-SPEC.md), maquette des 7 écrans, contrat des erreurs aux étapes 4 (passphrase) et 6 (rechargement).
-- **DoD :** chaque étape a un seul choix dominant ; étape 6 produit un succès ou un message d'erreur orienté utilisateur (cf. R4-P0-2) ; aucun écran n'expose un payload JSON brut.
+- **Livrables :** contrat normatif RFC 2119 dans [`docs/spec/R4-P0-1-onboarding-wizard.md`](../spec/R4-P0-1-onboarding-wizard.md), spec UX dans [`docs/ux/V4-UX-SPEC.md`](../ux/V4-UX-SPEC.md), maquette des 7 écrans, contrat des erreurs aux étapes 4 (passphrase) et 6 (rechargement).
+- **DoD :** chaque étape a un seul choix dominant ; étape 6 produit un succès ou un message d'erreur orienté utilisateur (cf. R4-P0-2) ; aucun écran n'expose un payload JSON brut. **Statut :** contrat normatif R4-P0-1 inscrit (docs/spec) — implémentation `klickd.app` séparée.
 - **Garde-fou anti-pattern :** A1 (mur JSON), A5 (spec-first sans exemples), A6 (erreurs non actionnables).
-- **Périmètre :** docs-only pour la spec UX. L'implémentation du wizard est tracée séparément côté `klickd.app` (hors-repo) et ne bloque pas le tag `v4.0.0` côté format — mais bloque l'adoption non-développeur.
+- **Périmètre :** docs-only pour la spec UX et le contrat normatif. L'implémentation du wizard est tracée séparément côté `klickd.app` (hors-repo) et ne bloque pas le tag `v4.0.0` côté format — mais bloque l'adoption non-développeur.
 - **Dépendances :** P0-1 (SPEC normative v4), R4-P0-2 (messages d'erreur), R4-P0-3 (profils d'exemple).
 
 #### R4-P0-2 — Messages d'erreur `KLICKD_E_*` i18n orientés utilisateur

diff --git a/docs/spec/R4-P0-1-onboarding-wizard.md b/docs/spec/R4-P0-1-onboarding-wizard.md
@@ -0,0 +1,299 @@
+# R4-P0-1 — `user.klickd` Onboarding Wizard (Normative, v4 P0)
+
+> **Status:** NORMATIVE (V4 P0). Docs-only promotion of [SPEC §33](../../SPEC.md)
+> R4-P0-1 preview wording toward the normative `.klickd` v4 surface. This
+> document uses **RFC 2119 / RFC 8174** key words (MUST, MUST NOT, SHALL,
+> SHOULD, SHOULD NOT, MAY) as defined therein.
+>
+> **Scope:** this document binds the user-visible onboarding flow that any
+> conforming v4 `user.klickd` writer (web, desktop, CLI, mobile, IDE
+> plugin) MUST expose to a first-time non-developer user. It does **not**
+> bind SDK internals, schema strictness, wire-format, vectors, or
+> packaging. No SDK, schema, vector, npm / PyPI / Zenodo / DOI / Git tag
+> release is implied or required by this document.
+>
+> **Out of scope (kept for clarity, tracked elsewhere):** error message
+> i18n table ([R4-P0-2](../roadmap/ROAD-TO-V4-GA.md#r4-p0-2--messages-derreur-klickd_e_-i18n-orientés-utilisateur)),
+> downloadable example profiles ([R4-P0-3](../roadmap/ROAD-TO-V4-GA.md#r4-p0-3--profils-dexemple-téléchargeables-5-personas)),
+> deprecation policy ([R4-P0-4](../roadmap/ROAD-TO-V4-GA.md#r4-p0-4--politique-de-dépréciation-v4-formelle)),
+> QR / deeplink onboarding trigger ([R4-P1-5 / R4-P2-1](../roadmap/ROAD-TO-V4-GA.md#r4-p1-5--r4-p2-1--qr--deeplink-onboarding-trigger-conditionnel)
+> and [`V4-ONBOARDING-QR-DEEPLINK.md`](../ux/V4-ONBOARDING-QR-DEEPLINK.md)),
+> `media.klickd` continuity ([RFC-001](../rfcs/RFC-001-media-profile-v1.md)),
+> `project.klickd` AGENTS.md export ([R4-P1-2](../roadmap/ROAD-TO-V4-GA.md#r4-p1-2--projectklickd-minimal--export-agentsmd)),
+> `gaming.klickd` baseline ([R4-P1-4](../roadmap/ROAD-TO-V4-GA.md#r4-p1-4--gamingklickd-baseline-optionnelle-registry-based)).
+
+---
+
+## 1. Why this is normative now
+
+Empirical UX convergence (1Password, Bitwarden, Obsidian, KeePassXC,
+Letta `.af` first-run flows — see
+[`V4-UX-DX-RESEARCH-NOTES.md`](../roadmap/V4-UX-DX-RESEARCH-NOTES.md))
+shows that a `.klickd` v4 file generated **without** a guided wizard and
+**without** a mandatory reload verification ends up unreadable by its
+own author. Anti-pattern A1 (raw JSON wall) and anti-pattern A6
+(non-actionable errors) are then locked in at onboarding time and
+cannot be recovered downstream.
+
+Promoting only the **onboarding wizard contract** to normative — not the
+underlying schema, not the SDK, not the wire-format — is the minimum
+intervention that prevents the format from regressing to a
+developer-only artefact at V4 GA. Schema strictness (P0-2), SDK
+alignment (P0-3 / P0-4), and vectors (P0-6) remain on their own
+tracks. This document only constrains what a conforming `user.klickd`
+writer **shows the user**.
+
+---
+
+## 2. Terminology
+
+- **`user.klickd` writer**: any client (web component, desktop app,
+  mobile app, CLI, IDE plugin) that produces a `user.klickd` v4 file
+  intended for an end-user, non-developer audience.
+- **Wizard**: the guided first-run flow described in §3.
+- **Reload verification** (step 6 — see §3.6): mandatory re-open of the
+  just-written file inside the same wizard, before the user is allowed
+  to exit the flow with a "success" terminal state.
+- **`user.klickd` vs `<x>.klickd`**: `user.klickd` is the personal
+  identity / state profile for a single human end-user. Other
+  `<x>.klickd` profiles (`project.klickd`, `agent.klickd`,
+  `media.klickd`, `gaming.klickd`, `core.klickd`) are advanced /
+  domain-specific and **MUST NOT** be reachable from the `user.klickd`
+  wizard's main path. They MAY be reachable via a separate, advanced,
+  progressive-disclosure entry (out of scope for this document).
+- **Dominant choice**: at each wizard step, exactly one action is
+  visually primary; the rest are secondary or hidden under
+  progressive-disclosure controls.
+- **Raw payload**: the JSON / CBOR / binary bytes of the produced
+  `.klickd` file or any in-memory payload tree representation.
+
+---
+
+## 3. Normative wizard contract (R4-P0-1)
+
+A conforming `user.klickd` writer **MUST** implement the seven steps
+described in §3.1–§3.7, in order, with the constraints listed for each
+step. The writer **MAY** present additional informational screens
+before, between, or after these steps (e.g., a welcome screen, a
+language selector, a final share / export prompt), but it **MUST NOT**
+remove, merge, reorder, or skip any of the seven normative steps in the
+`user.klickd` main path.
+
+The writer **MUST NOT** expose the raw payload at any wizard step
+described below. Inspection of the raw payload is out of scope for the
+`user.klickd` main path; it **MAY** be reachable through a separate
+"advanced" view that is not part of the wizard.
+
+### 3.1 Step 1 — Welcome & explicit intent
+
+- The writer **MUST** present a single explanatory screen stating, in
+  the detected UI language: (a) what a `user.klickd` file is in one
+  sentence, (b) that the file will live locally on the user's device
+  by default, (c) that no account, server, or upload is involved.
+- The dominant choice **MUST** be a single primary action ("Create my
+  `user.klickd`" or equivalent). A secondary action **MAY** be
+  provided ("I already have a `user.klickd` file → import").
+- The writer **MUST NOT** require the user to read more than three
+  short paragraphs before reaching the primary action.
+
+### 3.2 Step 2 — Identity (minimum viable profile)
+
+- The writer **MUST** collect, at minimum, the inputs that map to the
+  `user.klickd` mandatory payload fields as defined by the current
+  normative v4 schema track (P0-2; until P0-2 is GA, the writer
+  **MUST** target the `user.klickd` minimum surface described in
+  [SPEC §33](../../SPEC.md#33--klickd-v4-preview-non-normative)).
+- The writer **MUST NOT** require any field that is not strictly
+  required by the schema. Optional fields **MAY** be offered behind
+  progressive disclosure.
+- The writer **MUST NOT** collect personal data that is not used by
+  the produced payload. In particular, the writer **MUST NOT** ask
+  for an email, phone number, or legal name unless the schema or a
+  user-selected optional facet explicitly requires it.
+
+### 3.3 Step 3 — Preferences (one screen, dominant defaults)
+
+- The writer **MUST** present preference choices (UI language, tone,
+  verification-gate friction profile if relevant, `human_veto_policy`
+  default if relevant) on a single screen with sensible defaults
+  pre-selected.
+- The dominant choice **MUST** be "Continue with defaults". Each
+  preference **MUST** have a default value that is safe for a
+  non-developer end-user.
+- The writer **MUST NOT** require the user to understand
+  `verification_gates`, `human_veto_policy`, `claim_sources`, or any
+  other v4 internal field name to complete this step.
+
+### 3.4 Step 4 — Passphrase
+
+- The writer **MUST** require the user to enter a passphrase used by
+  the file's Argon2id KDF (per the v3.x envelope contract that remains
+  in force under §33.7).
+- The writer **MUST** display an entropy indicator (visual hint
+  acceptable; numeric score acceptable; the precise estimator is
+  unspecified).
+- The writer **MUST** require confirmation of the passphrase by a
+  second entry, or by a "reveal once" interaction with explicit
+  user-typed confirmation. The writer **MUST NOT** silently accept a
+  single-entry passphrase without confirmation.
+- The writer **MUST NOT** transmit the passphrase off-device by any
+  channel (network, cross-tab, clipboard auto-copy, telemetry, error
+  reporter). The passphrase **MUST** be cleared from memory after key
+  derivation, except for the explicit re-derivation needed at step 6
+  (reload verification).
+- On failure to confirm, the writer **MUST** produce a user-oriented
+  error message (i18n table defined by [R4-P0-2](../roadmap/ROAD-TO-V4-GA.md#r4-p0-2--messages-derreur-klickd_e_-i18n-orientés-utilisateur);
+  if R4-P0-2 has not landed at the time of implementation, the writer
+  **SHOULD** ship a minimal English fallback for each failure code).
+
+### 3.5 Step 5 — Generate & save locally
+
+- The writer **MUST** produce the `user.klickd` file entirely on the
+  user's device. No network call **MAY** be required to complete this
+  step.
+- The writer **MUST** offer the user a clear, local destination for
+  the file (download, save-as dialog, local app storage, OS keychain
+  if applicable). The chosen destination **MUST NOT** be a third-party
+  cloud upload by default. A future PR **MAY** add an opt-in
+  cloud-backup facet; that opt-in is **NOT** part of the V4 P0
+  normative onboarding path.
+- The writer **MUST** display the resulting file's local path or
+  storage location to the user before moving to step 6.
+- The writer **MUST NOT** treat step 5 success as the end of the
+  wizard. Reaching step 6 is mandatory (see §3.6).
+
+### 3.6 Step 6 — Mandatory reload verification (non-negotiable)
+
+- The writer **MUST** re-open the file produced at step 5 inside the
+  same wizard process, and **MUST** require the user to re-enter the
+  passphrase chosen at step 4 to decrypt it.
+- The writer **MUST NOT** skip, hide, defer, or make optional the
+  reload verification. The "Skip verification" path **MUST NOT**
+  exist in a conforming `user.klickd` main path.
+- If reload succeeds (file decrypts, payload parses, mandatory fields
+  present): the writer **MUST** show an explicit success state ("Your
+  `user.klickd` file is valid and re-openable.") and **MUST** advance
+  to step 7.
+- If reload fails (wrong passphrase, decryption error, missing
+  mandatory field, payload parse error): the writer **MUST** show a
+  user-oriented error message identifying the failure class (per
+  R4-P0-2 when available; minimal English fallback otherwise) and
+  **MUST** offer at least one user-actionable next step that does
+  **NOT** require contacting support (e.g., "re-enter passphrase",
+  "regenerate from step 4", "open the local file picker manually").
+- The writer **MUST NOT** mark the produced file as "valid" or
+  "ready to use" until step 6 has completed successfully.
+
+### 3.7 Step 7 — Next steps (closing the loop)
+
+- The writer **MUST** present a final screen telling the user, in the
+  detected UI language: (a) where the file is now stored locally, (b)
+  what the file is for in one sentence ("paste it into a `.klickd`-
+  aware agent to resume your context"), (c) at least one explicit
+  next action (open agent, copy local path, export a non-secret
+  fingerprint, etc.).
+- The writer **MUST NOT** auto-upload, auto-share, or auto-publish
+  the file to any third party at step 7.
+- The writer **MAY** offer optional onward actions (configure an
+  agent integration, create a project profile, generate a backup
+  reminder). These onward actions are out of scope for R4-P0-1 and
+  **MUST NOT** block exit from the wizard.
+
+---
+
+## 4. Conformance requirements (cross-cutting)
+
+A conforming `user.klickd` writer:
+
+1. **MUST** keep the seven steps in the main `user.klickd` path
+   linear and step-by-step. Free-form / power-user dashboards
+   **MUST NOT** replace the wizard for first-time `user.klickd`
+   creation.
+2. **MUST NOT** expose raw payload bytes, raw JSON, raw CBOR, raw
+   binary buffers, schema field names, or internal envelope fields
+   (`kdf`, `cipher`, AAD, salt, nonce, ciphertext, MAC) inside the
+   wizard UI. These **MAY** be reachable via a separate, opt-in
+   "advanced view" reached from outside the wizard.
+3. **MUST NOT** require any network call to complete steps 1–7. A
+   future opt-in facet (cloud backup, sync, telemetry, crash
+   reporting) **MUST** be off by default and **MUST NOT** be
+   pre-checked at any wizard step.
+4. **MUST** preserve unknown fields verbatim on any subsequent edit
+   or re-save, per the §33.7 forward-compatibility contract.
+5. **MUST** keep step 6 (reload verification) reachable on every
+   first-time creation. Subsequent edits of an existing file
+   **SHOULD** also offer a reload verification gesture, but this is
+   **NOT** required by R4-P0-1.
+6. **MUST NOT** introduce a separate `<x>.klickd` advanced flow
+   (e.g., `project.klickd`, `agent.klickd`) into the `user.klickd`
+   main path. Advanced profiles **MAY** be reached from a separate
+   progressive-disclosure entry point.
+7. **MUST NOT** add a QR-code or deeplink import path into steps 1–7
+   of the `user.klickd` main flow as part of V4 P0. Any QR /
+   deeplink trigger is governed by
+   [`V4-ONBOARDING-QR-DEEPLINK.md`](../ux/V4-ONBOARDING-QR-DEEPLINK.md)
+   and remains P1 conditional / P2.
+
+---
+
+## 5. Non-goals (explicit out-of-scope for R4-P0-1)
+
+To avoid scope creep at V4 P0, R4-P0-1 explicitly does **NOT**:
+
+- Define the underlying strict schema for `user.klickd`. That is
+  P0-2.
+- Define SDK APIs for writer / reader of `user.klickd`. That is P0-3
+  (Python) and P0-4 (TypeScript).
+- Define the cross-implementation vector set for `user.klickd`. That
+  is P0-6.
+- Bump any package version, mint any Git tag, cut any GitHub release,
+  publish to npm / PyPI / Zenodo, or update any DOI.
+- Replace, supersede, or weaken the §33.7 forward-compatibility
+  contract or the §33.10 privacy invariants.
+- Define `media.klickd`, `project.klickd`, `agent.klickd`,
+  `gaming.klickd`, `core.klickd`, or any other domain profile.
+  Those remain on their own RFC tracks (RFC-001, RFC-006, RFC-007,
+  RFC-008) and **MUST NOT** be inserted into the `user.klickd`
+  wizard's main path by R4-P0-1.
+- Define the QR / deeplink onboarding trigger. That decision lives in
+  [`V4-ONBOARDING-QR-DEEPLINK.md`](../ux/V4-ONBOARDING-QR-DEEPLINK.md)
+  and remains P1 conditional → P2.
+- Define the `KLICKD_E_*` error code i18n table. That is
+  [R4-P0-2](../roadmap/ROAD-TO-V4-GA.md#r4-p0-2--messages-derreur-klickd_e_-i18n-orientés-utilisateur),
+  which this document references but does not redefine.
+
+---
+
+## 6. Relationship to SPEC §33
+
+This document is the **normative** counterpart to the R4-P0-1 item
+tracked under [§2.4 of the V4 GA roadmap](../roadmap/ROAD-TO-V4-GA.md#r4-p0-1--wizard-userklickd-7-étapes-avec-rechargement-de-vérification).
+The roadmap entry remains the planning artefact; this document is the
+binding contract for any future v4 `user.klickd` writer.
+
+[`SPEC.md` §33](../../SPEC.md#33--klickd-v4-preview-non-normative)
+remains **preview / non-normative** for the on-the-wire field surface.
+A future PR (P0-1 SPEC promotion proper) will lift the §33 field
+surface into the normative SPEC body. R4-P0-1 (this document) is the
+**UX onboarding contract** part of that wider P0-1 effort; it lands
+first because it is independent of schema strictness (P0-2) and
+SDK alignment (P0-3 / P0-4), and because the empirical UX research
+([`V4-UX-DX-RESEARCH-NOTES.md`](../roadmap/V4-UX-DX-RESEARCH-NOTES.md))
+shows it is the load-bearing piece that determines whether
+non-developer adoption is possible at all.
+
+When the §33 field surface is promoted into the normative SPEC body,
+the cross-reference in §3.2 of this document **MUST** be updated to
+point at the new normative SPEC section instead of §33.
+
+---
+
+## 7. Next recommended branch after R4-P0-1
+
+Per the roadmap §2.4 and ["Suggested next branches" §3](../roadmap/ROAD-TO-V4-GA.md#3-suggested-next-branches),
+the recommended next docs/spec branch after R4-P0-1 lands is
+**R4-P0-2** — the `KLICKD_E_*` i18n error table — because R4-P0-1
+already depends on it for step 4 (passphrase confirmation failure)
+and step 6 (reload verification failure) error messaging. R4-P0-2 is
+docs-only and unblocks the wizard's error contract without touching
+SDK, schema, or vectors.