ConductionNL · rubenvdlinde · May 13, 2026 · May 13, 2026
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
diff --git a/docs/static/screenshots/tutorials/user/08-export-app-01.png b/docs/static/screenshots/tutorials/user/08-export-app-01.png
diff --git a/docs/static/screenshots/tutorials/user/08-export-app-02.png b/docs/static/screenshots/tutorials/user/08-export-app-02.png
diff --git a/docs/static/screenshots/tutorials/user/08-export-app-03.png b/docs/static/screenshots/tutorials/user/08-export-app-03.png
diff --git a/docs/static/screenshots/tutorials/user/08-export-app-04.png b/docs/static/screenshots/tutorials/user/08-export-app-04.png
diff --git a/docs/static/screenshots/tutorials/user/08-export-app-05.png b/docs/static/screenshots/tutorials/user/08-export-app-05.png
diff --git a/docs/tutorials/admin/01-rbac.md b/docs/tutorials/admin/01-rbac.md
@@ -1,35 +1,58 @@
 ---
 sidebar_position: 1
 title: Manage who can build (RBAC)
-description: Step-by-step guide to Manage who can build (RBAC)
+description: Decide which Nextcloud groups can open the builder, edit virtual apps, publish, and export.
 ---
 
 # Manage who can build (RBAC)
 
-Step-by-step guide to Manage who can build (RBAC)
+OpenBuilt scopes builder access through Nextcloud groups. Anyone in the *admin* group has the full ride; everyone else needs explicit membership in an OpenBuilt builder group. This is what stops an end user from opening the schema designer for an app they only meant to *use*.
 
 ## Goal
 
-<!-- {{TODO: write the goal — what the reader will have accomplished by the end}} -->
+By the end you will have nominated a Nextcloud group as the *OpenBuilt builders* group, added a user to it, and confirmed they can open the page designer.
 
 ## Prerequisites
 
-<!-- {{TODO: list the prerequisites — what must be installed, enabled, or configured first}} -->
+- You are in the Nextcloud *admin* group.
+- The user (or users) you want to give builder access exist on the Nextcloud and are in at least one group.
+- A sense of the access matrix you want — for most teams *one builder group per virtual app* is overkill; a single *OpenBuilt builders* group is the right starting point.
 
 ## Steps
 
-<!-- {{TODO: write the numbered steps. Each step that needs a screenshot gets one shoot() call in tests/e2e/docs-screenshots.spec.ts and a corresponding image ref here, e.g. ![alt](/screenshots/tutorials/admin/1-<slug>-<step>.png)}} -->
+1. Open **Settings → Administration → OpenBuilt** in Nextcloud. The OpenBuilt admin settings page opens with three sections: *Version Information*, *Support* and *Configuration*.
+
+   ![OpenBuilt admin settings](/screenshots/tutorials/admin/01-rbac-01.png)
+
+2. Scroll to **Configuration**. Find the **Builder groups** dropdown — it is a multi-select picker of Nextcloud groups; on a fresh install it is empty, which is why only *admin* can open the builder today.
+
+   ![Builder groups picker](/screenshots/tutorials/admin/01-rbac-02.png)
+
+3. Pick the group you want to nominate (for example *openbuilt-builders*). If the group does not exist yet, create it first under **Settings → Users → Groups**.
+
+   ![Group picked](/screenshots/tutorials/admin/01-rbac-03.png)
+
+4. Click **Save**. The setting persists to `IAppConfig`; the next call to the OpenBuilt API checks the new group membership.
+
+   ![Configuration saved](/screenshots/tutorials/admin/01-rbac-04.png)
+
+5. Add the user you want to give builder access to that group (under **Settings → Users**). Ask them to reload OpenBuilt — they should now see the **Open builder** / **Edit pages** controls on every virtual app.
+
+   ![User can open builder](/screenshots/tutorials/admin/01-rbac-05.png)
 
 ## Verification
 
-<!-- {{TODO: how the reader confirms it worked}} -->
+The RBAC change is good when: a user in the nominated group can open `/apps/openbuilt/builder/\<slug\>/pages` without a 403, and a user *not* in the group gets the 403 they should.
 
 ## Common issues
 
 | Symptom | Fix |
 |---|---|
-| <!-- {{TODO: a likely failure}} --> | <!-- {{TODO: the fix}} --> |
+| Save button does nothing | The configuration field is read-only on locked instances — check `config.php` for `'config_is_read_only' => true` and remove it. |
+| User still sees a 403 after group add | Nextcloud caches group memberships per session — ask the user to log out and back in. |
+| Multiple builder groups conflict | Membership is OR-ed across groups: being in *any* of the listed groups gives builder access. Trim the list if that is broader than you intended. |
 
 ## Reference
 
-<!-- {{TODO: link the relevant feature/spec reference pages}} -->
+- [Manage the template catalogue](./02-template-catalogue.md) — same picker controls who can publish templates.
+- [Admin settings](./03-admin-settings.md) — version info, register, support contact.
diff --git a/docs/tutorials/admin/02-template-catalogue.md b/docs/tutorials/admin/02-template-catalogue.md
@@ -1,35 +1,58 @@
 ---
 sidebar_position: 2
 title: Curate the template catalogue
-description: Step-by-step guide to Curate the template catalogue
+description: Promote an exported virtual app into the template gallery so other builders can clone from it.
 ---
 
 # Curate the template catalogue
 
-Step-by-step guide to Curate the template catalogue
+The template gallery is where new virtual apps start. The four templates that ship with OpenBuilt (*Permit Tracker*, *Stakeholder Consultation*, *Employee Onboarding*, *Incident Reporter*) are a baseline; in a real deployment you will add your own and retire the ones that do not fit.
 
 ## Goal
 
-<!-- {{TODO: write the goal — what the reader will have accomplished by the end}} -->
+By the end you will have promoted a finished virtual app into the template gallery, picked its category and description, and confirmed it shows up under **Templates** for everyone with builder access.
 
 ## Prerequisites
 
-<!-- {{TODO: list the prerequisites — what must be installed, enabled, or configured first}} -->
+- You are an OpenBuilt admin (in the *admin* group, or in a group nominated under [Manage who can build (RBAC)](./01-rbac.md)).
+- A virtual app that is *finished enough* to be a template — schemas stable, pages saved, a small set of well-chosen sample records.
+- A clear category to slot it under (*GOVERNMENT SERVICES*, *CITIZEN ENGAGEMENT*, *INTERNAL OPERATIONS*, *FIELD WORK*, or a custom category).
 
 ## Steps
 
-<!-- {{TODO: write the numbered steps. Each step that needs a screenshot gets one shoot() call in tests/e2e/docs-screenshots.spec.ts and a corresponding image ref here, e.g. ![alt](/screenshots/tutorials/admin/2-<slug>-<step>.png)}} -->
+1. Open **Templates** in the OpenBuilt left navigation. The gallery shows the current set, with category badges and **Use this template** buttons.
+
+   ![Template gallery](/screenshots/tutorials/admin/02-template-catalogue-01.png)
+
+2. To add a new template, open the source virtual app and click **Actions → Promote to template** (or open **Virtual apps**, tick the row, and pick **Promote to template** from the bulk-action menu).
+
+   ![Promote-to-template action](/screenshots/tutorials/admin/02-template-catalogue-02.png)
+
+3. The dialog asks for the template's **Name** (defaults to the app's name), **Slug**, **Category**, **Description** (one-liner shown on the card) and a longer **Body** (markdown, shown on hover and on the template-detail page).
+
+   ![Promote dialog](/screenshots/tutorials/admin/02-template-catalogue-03.png)
+
+4. Click **Promote**. OpenBuilt freezes the current manifest, copies it under a new `application-template` record, and the new card lands in the gallery at the top of its category.
+
+   ![New card in the gallery](/screenshots/tutorials/admin/02-template-catalogue-04.png)
+
+5. To retire a template, click the card to open its detail page, then **Actions → Retire**. The template stops appearing in the gallery, existing apps that were cloned from it stay untouched.
+
+   ![Retire template](/screenshots/tutorials/admin/02-template-catalogue-05.png)
 
 ## Verification
 
-<!-- {{TODO: how the reader confirms it worked}} -->
+The promotion worked when: the new card shows up under the right category on the **Templates** gallery, builders can click **Use this template** and land in [Create an application from a template](../user/02-create-from-template.md), and the resulting clone matches the source app.
 
 ## Common issues
 
 | Symptom | Fix |
 |---|---|
-| <!-- {{TODO: a likely failure}} --> | <!-- {{TODO: the fix}} --> |
+| **Promote to template** is missing from the Actions menu | You are not in a builder/admin group — see [Manage who can build (RBAC)](./01-rbac.md). |
+| Category dropdown does not list yours | Custom categories are stored on `application-template` records — add the category to the first record manually via OpenRegister, future promotions pick it up. |
+| Template appears in the gallery but **Use this template** errors | The frozen manifest references a register that does not exist on the target instance — re-promote with the *Include registers* tick. |
 
 ## Reference
 
-<!-- {{TODO: link the relevant feature/spec reference pages}} -->
+- [Create an application from a template](../user/02-create-from-template.md) — the user flow your template feeds.
+- [Export the app](../user/08-export-app.md) — alternative to promoting (downloadable ZIP).
diff --git a/docs/tutorials/admin/03-admin-settings.md b/docs/tutorials/admin/03-admin-settings.md
@@ -1,35 +1,57 @@
 ---
 sidebar_position: 3
 title: Manage OpenBuilt settings
-description: Step-by-step guide to Manage OpenBuilt settings
+description: The three things every OpenBuilt admin touches — version info, OpenRegister wiring and the support contact.
 ---
 
 # Manage OpenBuilt settings
 
-Step-by-step guide to Manage OpenBuilt settings
+OpenBuilt's admin settings page (in Nextcloud at **Settings → Administration → OpenBuilt**) is short on purpose. It surfaces only the configuration an admin needs to know about: the running version, the OpenRegister register OpenBuilt writes to, and the support contact end users will see.
 
 ## Goal
 
-<!-- {{TODO: write the goal — what the reader will have accomplished by the end}} -->
+By the end you will have confirmed the running OpenBuilt version is up to date, set the OpenRegister register, and confirmed the support contact details users see.
 
 ## Prerequisites
 
-<!-- {{TODO: list the prerequisites — what must be installed, enabled, or configured first}} -->
+- Your account is in the *admin* group.
+- The OpenRegister app is installed and enabled.
 
 ## Steps
 
-<!-- {{TODO: write the numbered steps. Each step that needs a screenshot gets one shoot() call in tests/e2e/docs-screenshots.spec.ts and a corresponding image ref here, e.g. ![alt](/screenshots/tutorials/admin/3-<slug>-<step>.png)}} -->
+1. Open **Settings → Administration → OpenBuilt** in Nextcloud. The page is split into three sections: *Version Information*, *Support* and *Configuration*.
+
+   ![OpenBuilt admin settings page](/screenshots/tutorials/admin/03-admin-settings-01.png)
+
+2. Confirm **Version Information**. The section shows the running app version (for example `0.2.0`) and an *Up to date* badge if the running version matches the latest release on the Nextcloud app store.
+
+   ![Version information section](/screenshots/tutorials/admin/03-admin-settings-02.png)
+
+3. Confirm **Support**. The block shows the support email (`support@conduction.nl` by default). This is what users see if they hit the *Contact support* link from inside OpenBuilt.
+
+   ![Support section](/screenshots/tutorials/admin/03-admin-settings-03.png)
+
+4. Scroll to **Configuration**. The **Register** dropdown maps OpenBuilt to the OpenRegister register that holds application, schema, template, version and export records. On a fresh install it is pre-set to the `openbuilt` register imported by the app's repair step.
+
+   ![Configuration section](/screenshots/tutorials/admin/03-admin-settings-04.png)
+
+5. To rotate to a different register (only relevant when you are running multiple OpenBuilt instances against the same Nextcloud), pick the new register and click **Save**. The change takes effect on the next API call.
+
+   ![Configuration saved](/screenshots/tutorials/admin/03-admin-settings-05.png)
 
 ## Verification
 
-<!-- {{TODO: how the reader confirms it worked}} -->
+The settings page is healthy when: the *Up to date* badge is green, the Support block shows your team's contact details, the Register dropdown points at a register that exists on this Nextcloud, and the save toast confirms the change persisted.
 
 ## Common issues
 
 | Symptom | Fix |
 |---|---|
-| <!-- {{TODO: a likely failure}} --> | <!-- {{TODO: the fix}} --> |
+| Register dropdown is empty | OpenRegister has no `openbuilt` register imported yet — run `php occ openbuilt:repair` on the host. |
+| Version Information shows *Outdated* | Update OpenBuilt via the Nextcloud app store. |
+| Save button does nothing | The configuration field is read-only on locked instances — check `config.php` for `'config_is_read_only' => true`. |
 
 ## Reference
 
-<!-- {{TODO: link the relevant feature/spec reference pages}} -->
+- [Manage who can build (RBAC)](./01-rbac.md) — same settings page, builder-groups picker.
+- [Manage the template catalogue](./02-template-catalogue.md) — what builders see in the gallery.
diff --git a/docs/tutorials/user/01-first-launch.md b/docs/tutorials/user/01-first-launch.md
@@ -1,35 +1,54 @@
 ---
 sidebar_position: 1
 title: Open OpenBuilt for the first time
-description: Step-by-step guide to Open OpenBuilt for the first time
+description: Open OpenBuilt, walk the navigation, and confirm the seed Hello World virtual app loaded.
 ---
 
 # Open OpenBuilt for the first time
 
-Step-by-step guide to Open OpenBuilt for the first time
+A first look at OpenBuilt — what the app is for, what the navigation gives you, and how to tell the seed *Hello World* virtual app is ready to play with.
 
 ## Goal
 
-<!-- {{TODO: write the goal — what the reader will have accomplished by the end}} -->
+By the end you will have opened OpenBuilt, recognised the dashboard tiles and the left-hand navigation, and seen the seed *Hello World* virtual app in the Virtual apps list.
 
 ## Prerequisites
 
-<!-- {{TODO: list the prerequisites — what must be installed, enabled, or configured first}} -->
+- A Nextcloud account on an instance where the **OpenBuilt** app is installed and enabled.
+- The **OpenRegister** app installed and enabled — OpenBuilt stores virtual apps, schemas, templates and version snapshots in OpenRegister.
+- The OpenBuilt repair step has run, so the *Hello World* seed virtual app is present (the repair runs once on first enable; an admin can re-trigger it from **Nextcloud admin → Overview**).
 
 ## Steps
 
-<!-- {{TODO: write the numbered steps. Each step that needs a screenshot gets one shoot() call in tests/e2e/docs-screenshots.spec.ts and a corresponding image ref here, e.g. ![alt](/screenshots/tutorials/user/1-<slug>-<step>.png)}} -->
+1. Open the Nextcloud app menu in the top bar and pick **OpenBuilt**. You land on the dashboard.
+
+   ![OpenBuilt dashboard](/screenshots/tutorials/user/01-first-launch-01.png)
+
+2. Read the dashboard tiles — *Virtual apps*, *Published*, *Templates*, *Published versions*. They show counts pulled from OpenRegister; on a fresh install the *Virtual apps* and *Published* tiles read `1` (the seed Hello World app), *Templates* reads however many the template gallery ships and *Published versions* sits on the snapshot count.
+
+   ![Dashboard stat tiles](/screenshots/tutorials/user/01-first-launch-02.png)
+
+3. Open the left-hand navigation. The entries map one-to-one onto what OpenBuilt manages: **Virtual apps** (your draft and published apps), **Schemas** (the OpenRegister schemas you can re-use across apps), **Templates** (the gallery you can clone from), **Exports** (zipped manifest exports). Below the divider sit **Documentation** and **Features & roadmap**.
+
+   ![OpenBuilt navigation](/screenshots/tutorials/user/01-first-launch-03.png)
+
+4. Click **Virtual apps**. The list view opens with a *Cards / Table* toggle, an **Add Application** button, and the OpenRegister side filters. The seed *Hello World* row is the one to start poking at.
+
+   ![Virtual apps list, Hello World seeded](/screenshots/tutorials/user/01-first-launch-04.png)
 
 ## Verification
 
-<!-- {{TODO: how the reader confirms it worked}} -->
+You are set up correctly when: the OpenBuilt dashboard renders without an error banner, the left navigation lists the entries above, and **Virtual apps** shows at least the *Hello World* row.
 
 ## Common issues
 
 | Symptom | Fix |
 |---|---|
-| <!-- {{TODO: a likely failure}} --> | <!-- {{TODO: the fix}} --> |
+| "OpenRegister is not installed or enabled" banner | Install and enable the OpenRegister app, then reload OpenBuilt. |
+| Virtual apps list is empty | The repair step did not run — an admin re-enables OpenBuilt, or runs `php occ openbuilt:repair` on the host. |
+| OpenBuilt is missing from the app menu | The app is not enabled for your account — ask an administrator to enable it (and check it is not restricted to a group you are not in). |
 
 ## Reference
 
-<!-- {{TODO: link the relevant feature/spec reference pages}} -->
+- [Clone from a template](./02-create-from-template.md) — the natural next step.
+- [Admin settings](../admin/03-admin-settings.md) — register, version, support contact.