ConductionNL · rubenvdlinde · May 17, 2026 · May 17, 2026 · May 17, 2026 · May 17, 2026
diff --git a/docs/integrator-guide.md b/docs/integrator-guide.md
@@ -24,7 +24,42 @@ A virtual app is one record in OpenBuilt's `Application` OR schema. The shape is
 
 The `manifest` object validates against [`@conduction/nextcloud-vue/src/schemas/app-manifest.schema.json`](https://github.com/ConductionNL/nextcloud-vue/blob/main/src/schemas/app-manifest.schema.json). The closed `type` enum for pages is `index | detail | dashboard | logs | settings | chat | files | form | custom`.
 
-## Step-by-step
+## Creating a virtual app with the wizard
+
+For most operators the visual wizard at **Virtual apps → New application** is the
+quicker path. It walks you through three steps in one round-trip:
+
+1. **Identity** — pick a slug + human-readable name + description.
+2. **Versions** — accept the default chain (`development → staging → production`)
+   or adjust it. Each version maps to its own per-version register
+   (`openbuilt-{slug}-{versionSlug}`) so production data is physically isolated
+   from staging and development. The wizard's chain editor enforces ADR-002's
+   linear-chain rule (no fan-out, no cycles, exactly one terminal `production`
+   tier).
+3. **Permissions** — pick the owners / editors / viewers. The caller is
+   pre-filled into `owners`. Group `group:*` becomes the "all signed-in users"
+   wildcard per REQ-OBRBAC-004.
+
+On submit the wizard atomically creates the `Application` record, the N
+`ApplicationVersion` rows, and N per-version registers — and seeds each
+register with the default schema set (`hello-message` by default) under the
+namespaced slug `{appSlug}-{versionSlug}-{originalSchemaSlug}`. The manifest's
+`config.register` and `config.schema` pointers are rewritten to match
+(`openbuilt-{slug}-{tier}` and `{appSlug}-{tier}-hello-message` respectively)
+so the insights service and the runtime each address the right per-tier slice.
+
+**Empty-state landing** — fresh installs no longer auto-seed a `hello-world`
+Application (the legacy `SeedHelloWorld` repair step was retired by
+`openbuilt-versioning-model`). New deploys land the admin on an empty Virtual
+apps index with a CTA pointing at the wizard. Pre-existing installs are not
+affected; the migration step `MigrateToVersionedModel` only fires when
+pre-spec-C Application rows are present and is idempotent on re-runs.
+
+For further reading on what each step writes through to OR, see
+[`openbuilt-runtime.md`](./openbuilt-runtime.md) and the wizard chain spec
+[`openspec/changes/openbuilt-app-creation-wizard/`](../openspec/changes/openbuilt-app-creation-wizard/).
+
+## Step-by-step (manual / integrator path)
 
 1. **Pick a slug.** Must be kebab-case, 2–48 chars, unique within your organisation. The synthetic appId in CnAppRoot becomes `openbuilt-${slug}`.
 2. **Design your schemas** in OpenRegister directly (the OpenBuilt schema editor lands in chain spec `openbuilt-schema-editor`). At minimum: one schema per primary entity your app shows.

diff --git a/docs/openbuilt-runtime.md b/docs/openbuilt-runtime.md
@@ -87,15 +87,45 @@ OpenBuilt does **not** ship an `ApplicationLifecycleService.php` / `ApplicationS
 
 > If OR's current lifecycle engine doesn't yet support the `on_transition.upsert_relation` / `delete_relation` actions for sibling-object upkeep, the fallback is a single PHP listener `lib/Listener/BuiltAppRouteSyncListener.php` subscribed to `ObjectLifecycleTransitionedEvent` (per design.md OQ-1). The listener is the ADR-031 §Exceptions(1) path; behaviour from the user's perspective is identical either way.
 
-## Seed: `hello-world`
-
-`lib/Repair/SeedHelloWorld.php` runs idempotently on every install + post-migration:
-
-1. Guard on `openbuilt/application` slug `hello-world` — if present, no-op.
-2. Save one `Application` (`slug: hello-world`, `status: published`, version `0.1.0`) with a manifest exercising `index`, `detail`, and `form` page types against the seeded `hello-message` schema.
-3. Save three sample `hello-message` objects.
-
-The seed gives integrators a working virtual app on minute one of an OpenBuilt install — browse to `/index.php/apps/openbuilt/builder/hello-world` post-install.
+## Creating a virtual app (wizard flow)
+
+Most operators reach the virtual app via the visual wizard at **Virtual apps →
+New application**. The flow is owned by `ApplicationCreationController` +
+`ApplicationCreationService` and lands in a single transactional round-trip:
+
+1. **Submit** the wizard's three-step payload (`identity`, `versions[]`,
+   `permissions`) to `POST /api/applications/wizard`.
+2. The service creates the parent `Application` row, then per version:
+    - one `ApplicationVersion` row carrying the manifest, register pointer, and
+      semver,
+    - one per-version OR register `openbuilt-{appSlug}-{versionSlug}`,
+    - the default schema set (currently just `hello-message`) seeded into the
+      per-version register under namespaced slugs
+      (`{appSlug}-{versionSlug}-{originalSlug}`).
+3. The first version in the chain's `productionVersion` pointer is set on the
+   parent Application.
+4. The wizard rewrites the manifest's `pages[].config.register` and
+   `pages[].config.schema` to the namespaced per-version values before save —
+   so the runtime + insights service address the right per-tier slice (see
+   `ApplicationCreationService::substituteVersionContext()`).
+
+Rollback is best-effort: if any step fails the service tears down the registers
++ application + version rows it managed to create so the org-wide unique slug
+isn't squatted.
+
+### Empty-state landing (no auto-seed)
+
+The legacy `lib/Repair/SeedHelloWorld.php` repair step was retired by
+[`openbuilt-versioning-model`](../openspec/changes/openbuilt-versioning-model/).
+Fresh installs land the admin on an empty Virtual apps index with a CTA
+pointing at the wizard; pre-existing installs that still carry pre-spec-C
+Application rows are migrated by `MigrateToVersionedModel` (destructive but
+idempotent — see ADR-002).
+
+The `hello-world` slug now ships only as part of the wizard's
+`default-manifest.json`/`default-schemas.json` blueprint, so every freshly
+provisioned app gets the same one-index-one-detail-one-form starter and the
+`/builder/{slug}` route resolves the moment publish fires.
 
 ## File map
 

diff --git a/docs/static/screenshots/tutorials/admin/01-rbac-01.png b/docs/static/screenshots/tutorials/admin/01-rbac-01.png
diff --git a/docs/static/screenshots/tutorials/admin/01-rbac-02.png b/docs/static/screenshots/tutorials/admin/01-rbac-02.png
diff --git a/docs/static/screenshots/tutorials/admin/01-rbac-03.png b/docs/static/screenshots/tutorials/admin/01-rbac-03.png
diff --git a/docs/static/screenshots/tutorials/admin/01-rbac-04.png b/docs/static/screenshots/tutorials/admin/01-rbac-04.png
diff --git a/docs/static/screenshots/tutorials/admin/01-rbac-05.png b/docs/static/screenshots/tutorials/admin/01-rbac-05.png
diff --git a/docs/static/screenshots/tutorials/admin/02-template-catalogue-01.png b/docs/static/screenshots/tutorials/admin/02-template-catalogue-01.png
diff --git a/docs/static/screenshots/tutorials/admin/02-template-catalogue-02.png b/docs/static/screenshots/tutorials/admin/02-template-catalogue-02.png
diff --git a/docs/static/screenshots/tutorials/admin/02-template-catalogue-03.png b/docs/static/screenshots/tutorials/admin/02-template-catalogue-03.png
diff --git a/docs/static/screenshots/tutorials/admin/02-template-catalogue-04.png b/docs/static/screenshots/tutorials/admin/02-template-catalogue-04.png
diff --git a/docs/static/screenshots/tutorials/admin/02-template-catalogue-05.png b/docs/static/screenshots/tutorials/admin/02-template-catalogue-05.png
diff --git a/docs/static/screenshots/tutorials/admin/03-admin-settings-01.png b/docs/static/screenshots/tutorials/admin/03-admin-settings-01.png
diff --git a/docs/static/screenshots/tutorials/admin/03-admin-settings-02.png b/docs/static/screenshots/tutorials/admin/03-admin-settings-02.png
diff --git a/docs/static/screenshots/tutorials/admin/03-admin-settings-03.png b/docs/static/screenshots/tutorials/admin/03-admin-settings-03.png
diff --git a/docs/static/screenshots/tutorials/admin/03-admin-settings-04.png b/docs/static/screenshots/tutorials/admin/03-admin-settings-04.png
diff --git a/docs/static/screenshots/tutorials/admin/03-admin-settings-05.png b/docs/static/screenshots/tutorials/admin/03-admin-settings-05.png
diff --git a/docs/static/screenshots/tutorials/user/01-first-launch-01.png b/docs/static/screenshots/tutorials/user/01-first-launch-01.png
diff --git a/docs/static/screenshots/tutorials/user/01-first-launch-02.png b/docs/static/screenshots/tutorials/user/01-first-launch-02.png
diff --git a/docs/static/screenshots/tutorials/user/01-first-launch-03.png b/docs/static/screenshots/tutorials/user/01-first-launch-03.png
diff --git a/docs/static/screenshots/tutorials/user/01-first-launch-04.png b/docs/static/screenshots/tutorials/user/01-first-launch-04.png
diff --git a/docs/static/screenshots/tutorials/user/02-create-from-template-01.png b/docs/static/screenshots/tutorials/user/02-create-from-template-01.png
diff --git a/docs/static/screenshots/tutorials/user/02-create-from-template-02.png b/docs/static/screenshots/tutorials/user/02-create-from-template-02.png
diff --git a/docs/static/screenshots/tutorials/user/02-create-from-template-03.png b/docs/static/screenshots/tutorials/user/02-create-from-template-03.png
diff --git a/docs/static/screenshots/tutorials/user/02-create-from-template-04.png b/docs/static/screenshots/tutorials/user/02-create-from-template-04.png
diff --git a/docs/static/screenshots/tutorials/user/02-create-from-template-05.png b/docs/static/screenshots/tutorials/user/02-create-from-template-05.png
diff --git a/docs/static/screenshots/tutorials/user/03-design-schema-01.png b/docs/static/screenshots/tutorials/user/03-design-schema-01.png
diff --git a/docs/static/screenshots/tutorials/user/03-design-schema-02.png b/docs/static/screenshots/tutorials/user/03-design-schema-02.png
diff --git a/docs/static/screenshots/tutorials/user/03-design-schema-03.png b/docs/static/screenshots/tutorials/user/03-design-schema-03.png
diff --git a/docs/static/screenshots/tutorials/user/03-design-schema-04.png b/docs/static/screenshots/tutorials/user/03-design-schema-04.png
diff --git a/docs/static/screenshots/tutorials/user/03-design-schema-05.png b/docs/static/screenshots/tutorials/user/03-design-schema-05.png
diff --git a/docs/static/screenshots/tutorials/user/04-design-page-01.png b/docs/static/screenshots/tutorials/user/04-design-page-01.png
diff --git a/docs/static/screenshots/tutorials/user/04-design-page-02.png b/docs/static/screenshots/tutorials/user/04-design-page-02.png
diff --git a/docs/static/screenshots/tutorials/user/04-design-page-03.png b/docs/static/screenshots/tutorials/user/04-design-page-03.png
diff --git a/docs/static/screenshots/tutorials/user/04-design-page-04.png b/docs/static/screenshots/tutorials/user/04-design-page-04.png
diff --git a/docs/static/screenshots/tutorials/user/04-design-page-05.png b/docs/static/screenshots/tutorials/user/04-design-page-05.png
diff --git a/docs/static/screenshots/tutorials/user/05-connect-data-01.png b/docs/static/screenshots/tutorials/user/05-connect-data-01.png
diff --git a/docs/static/screenshots/tutorials/user/05-connect-data-02.png b/docs/static/screenshots/tutorials/user/05-connect-data-02.png
diff --git a/docs/static/screenshots/tutorials/user/05-connect-data-03.png b/docs/static/screenshots/tutorials/user/05-connect-data-03.png
diff --git a/docs/static/screenshots/tutorials/user/05-connect-data-04.png b/docs/static/screenshots/tutorials/user/05-connect-data-04.png
diff --git a/docs/static/screenshots/tutorials/user/05-connect-data-05.png b/docs/static/screenshots/tutorials/user/05-connect-data-05.png
diff --git a/docs/static/screenshots/tutorials/user/06-preview-app-01.png b/docs/static/screenshots/tutorials/user/06-preview-app-01.png
diff --git a/docs/static/screenshots/tutorials/user/06-preview-app-02.png b/docs/static/screenshots/tutorials/user/06-preview-app-02.png
diff --git a/docs/static/screenshots/tutorials/user/06-preview-app-03.png b/docs/static/screenshots/tutorials/user/06-preview-app-03.png
diff --git a/docs/static/screenshots/tutorials/user/06-preview-app-04.png b/docs/static/screenshots/tutorials/user/06-preview-app-04.png
diff --git a/docs/static/screenshots/tutorials/user/06-preview-app-05.png b/docs/static/screenshots/tutorials/user/06-preview-app-05.png
diff --git a/docs/static/screenshots/tutorials/user/07-version-snapshots-01.png b/docs/static/screenshots/tutorials/user/07-version-snapshots-01.png
diff --git a/docs/static/screenshots/tutorials/user/07-version-snapshots-02.png b/docs/static/screenshots/tutorials/user/07-version-snapshots-02.png
diff --git a/docs/static/screenshots/tutorials/user/07-version-snapshots-03.png b/docs/static/screenshots/tutorials/user/07-version-snapshots-03.png
diff --git a/docs/static/screenshots/tutorials/user/07-version-snapshots-04.png b/docs/static/screenshots/tutorials/user/07-version-snapshots-04.png
diff --git a/docs/static/screenshots/tutorials/user/07-version-snapshots-05.png b/docs/static/screenshots/tutorials/user/07-version-snapshots-05.png