ConductionNL · rubenvdlinde · May 13, 2026 · May 13, 2026
diff --git a/.gitignore b/.gitignore
@@ -81,6 +81,7 @@ docker/dolphin/models/
 /docs/i18n/nl/
 
 # Playwright (journeydoc capture + future e2e)
+/tests/e2e/.auth/
 /tests/e2e/test-results/
 /tests/e2e/playwright-report/
 /playwright-report/

diff --git a/docs/static/screenshots/tutorials/admin/01-floors-zones-01.png b/docs/static/screenshots/tutorials/admin/01-floors-zones-01.png
diff --git a/docs/static/screenshots/tutorials/admin/01-floors-zones-02.png b/docs/static/screenshots/tutorials/admin/01-floors-zones-02.png
diff --git a/docs/static/screenshots/tutorials/admin/01-floors-zones-03.png b/docs/static/screenshots/tutorials/admin/01-floors-zones-03.png
diff --git a/docs/static/screenshots/tutorials/admin/01-floors-zones-04.png b/docs/static/screenshots/tutorials/admin/01-floors-zones-04.png
diff --git a/docs/static/screenshots/tutorials/admin/02-knowledge-source-01.png b/docs/static/screenshots/tutorials/admin/02-knowledge-source-01.png
diff --git a/docs/static/screenshots/tutorials/admin/02-knowledge-source-02.png b/docs/static/screenshots/tutorials/admin/02-knowledge-source-02.png
diff --git a/docs/static/screenshots/tutorials/admin/02-knowledge-source-03.png b/docs/static/screenshots/tutorials/admin/02-knowledge-source-03.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/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-browse-desks-01.png b/docs/static/screenshots/tutorials/user/02-browse-desks-01.png
diff --git a/docs/static/screenshots/tutorials/user/02-browse-desks-02.png b/docs/static/screenshots/tutorials/user/02-browse-desks-02.png
diff --git a/docs/static/screenshots/tutorials/user/02-browse-desks-03.png b/docs/static/screenshots/tutorials/user/02-browse-desks-03.png
diff --git a/docs/static/screenshots/tutorials/user/02-browse-desks-04.png b/docs/static/screenshots/tutorials/user/02-browse-desks-04.png
diff --git a/docs/static/screenshots/tutorials/user/02-browse-desks-05.png b/docs/static/screenshots/tutorials/user/02-browse-desks-05.png
diff --git a/docs/static/screenshots/tutorials/user/03-book-a-slot-01.png b/docs/static/screenshots/tutorials/user/03-book-a-slot-01.png
diff --git a/docs/static/screenshots/tutorials/user/03-book-a-slot-02.png b/docs/static/screenshots/tutorials/user/03-book-a-slot-02.png
diff --git a/docs/static/screenshots/tutorials/user/03-book-a-slot-03.png b/docs/static/screenshots/tutorials/user/03-book-a-slot-03.png
diff --git a/docs/static/screenshots/tutorials/user/03-book-a-slot-04.png b/docs/static/screenshots/tutorials/user/03-book-a-slot-04.png
diff --git a/docs/static/screenshots/tutorials/user/03-book-a-slot-05.png b/docs/static/screenshots/tutorials/user/03-book-a-slot-05.png
diff --git a/docs/static/screenshots/tutorials/user/04-recurring-booking-01.png b/docs/static/screenshots/tutorials/user/04-recurring-booking-01.png
diff --git a/docs/static/screenshots/tutorials/user/04-recurring-booking-02.png b/docs/static/screenshots/tutorials/user/04-recurring-booking-02.png
diff --git a/docs/static/screenshots/tutorials/user/04-recurring-booking-03.png b/docs/static/screenshots/tutorials/user/04-recurring-booking-03.png
diff --git a/docs/static/screenshots/tutorials/user/04-recurring-booking-04.png b/docs/static/screenshots/tutorials/user/04-recurring-booking-04.png
diff --git a/docs/static/screenshots/tutorials/user/05-calendar-sync-01.png b/docs/static/screenshots/tutorials/user/05-calendar-sync-01.png
diff --git a/docs/static/screenshots/tutorials/user/05-calendar-sync-02.png b/docs/static/screenshots/tutorials/user/05-calendar-sync-02.png
diff --git a/docs/static/screenshots/tutorials/user/05-calendar-sync-03.png b/docs/static/screenshots/tutorials/user/05-calendar-sync-03.png
diff --git a/docs/static/screenshots/tutorials/user/05-calendar-sync-04.png b/docs/static/screenshots/tutorials/user/05-calendar-sync-04.png
diff --git a/docs/static/screenshots/tutorials/user/06-desk-knowledge-01.png b/docs/static/screenshots/tutorials/user/06-desk-knowledge-01.png
diff --git a/docs/static/screenshots/tutorials/user/06-desk-knowledge-02.png b/docs/static/screenshots/tutorials/user/06-desk-knowledge-02.png
diff --git a/docs/static/screenshots/tutorials/user/06-desk-knowledge-03.png b/docs/static/screenshots/tutorials/user/06-desk-knowledge-03.png
diff --git a/docs/static/screenshots/tutorials/user/06-desk-knowledge-04.png b/docs/static/screenshots/tutorials/user/06-desk-knowledge-04.png
diff --git a/docs/tutorials/admin/01-floors-zones.md b/docs/tutorials/admin/01-floors-zones.md
@@ -1,35 +1,54 @@
 ---
 sidebar_position: 1
 title: Set up floors, zones and desks
-description: Step-by-step guide to set up floors, zones and desks
+description: Model the building once — define floors, group desks into zones, set per-desk metadata (equipment, accessibility).
 ---
 
 # Set up floors, zones and desks
 
-Step-by-step guide to set up floors, zones and desks.
+Before anyone can book a desk, the building has to exist in DeskDesk. The model is straightforward: a *floor* belongs to a building and has *zones*; each zone holds *desks*; each desk carries equipment metadata (monitor count, sit/stand, accessibility flag, locker code).
 
 ## Goal
 
-<!-- {{GOAL}} — write the goal: the admin has modelled the building — floors, the zones on each floor, and the desks in each zone — so users can browse and book. -->
+By the end the building is modelled — at least one floor, divided into zones (open-office / quiet / phone-booth / accessible), and each zone populated with desks that carry the metadata users want to filter by.
 
 ## Prerequisites
 
-<!-- {{PREREQS}} — admin access to the DeskDesk settings page; DeskDesk installed and its OpenRegister registers/schemas in place. -->
+- Admin on the Nextcloud instance.
+- OpenRegister installed and the DeskDesk register imported (the configuration import runs on app install).
+- A rough floor plan or desk list to work from — the metadata model is flexible enough to capture an existing CSV, but you need to know the desk count per zone.
 
 ## Steps
 
-<!-- {{STEPS}} — numbered steps: open admin settings, add a floor, add zones to it, add desks to each zone (name, attributes). Screenshot-worthy steps get a shoot() call in tests/e2e/docs-screenshots.spec.ts. -->
+1. Open **Floors** from the in-app navigation. On a fresh install the list is empty.
+
+   ![Floors list view, empty](/screenshots/tutorials/admin/01-floors-zones-01.png)
+
+2. Click **Add Item**. The dialog asks for *Name* (e.g. "Floor 3"), *Building*, *Capacity*, and the *Zones* relation. Each zone has a *Name*, *Kind* (open-office / quiet / phone-booth / accessible), and a *Desk count* preview.
+
+   ![New floor dialog](/screenshots/tutorials/admin/01-floors-zones-02.png)
+
+3. Save the floor. It appears in the Floors list with the zones count visible. Click the floor row to open its detail page, then add desks to each zone — *Display name*, *Equipment* (multi-select: monitor, dual-monitor, sit-stand, dock), *Accessibility flag*, *Locker code* (optional).
+
+   ![Floors list after adding](/screenshots/tutorials/admin/01-floors-zones-03.png)
+
+4. Repeat for every floor in the building. The Floors list summarises building / floor count / total desks — handy for a quick sanity check before opening DeskDesk up to the org.
+
+   ![Floors list — multiple floors](/screenshots/tutorials/admin/01-floors-zones-04.png)
 
 ## Verification
 
-<!-- {{VERIFICATION}} — the floor plan renders for users with the floors, zones and desks you added. -->
+The Floors list shows each floor with the right zone count and total desk count. Opening DeskDesk as a regular user surfaces the floor picker populated with these floors; the desks index renders the cards with the equipment metadata.
 
 ## Common issues
 
 | Symptom | Fix |
 |---|---|
-<!-- {{COMMON_ISSUES}} — e.g. "floor plan empty for users" / "check the desks were saved to the configured register". -->
+| **Add Item** dialog has no zone fields | The zone schema is not mapped — re-run the configuration import from the [admin settings page](./03-admin-settings.md). |
+| Saved a floor but it does not appear in the user's floor picker | Browser cache — hard-reload (Ctrl-Shift-R). Vue Router caches the floor list for ~1 minute. |
+| Cannot delete a floor with bookings against its desks | DeskDesk refuses cascading deletes that would orphan bookings. Cancel the bookings first, or move them to a different desk, then delete the floor. |
 
 ## Reference
 
-<!-- {{REFERENCE}} — link related docs: OpenRegister schema for floors/zones/desks, ADRs. -->
+- [Configure the knowledge source](./02-knowledge-source.md) — next admin step.
+- [Browse desks](../user/02-browse-desks.md) — the user-facing view of what you just set up.
diff --git a/docs/tutorials/admin/02-knowledge-source.md b/docs/tutorials/admin/02-knowledge-source.md
@@ -1,35 +1,54 @@
 ---
 sidebar_position: 2
 title: Connect the wiki knowledge source
-description: Step-by-step guide to connect the wiki knowledge source
+description: Wire up an OpenConnector source pointing at xWiki (or any compatible wiki) so each desk surfaces its how-to articles.
 ---
 
 # Connect the wiki knowledge source
 
-Step-by-step guide to connect the wiki knowledge source.
+DeskDesk's *knowledge sidebar* — the per-desk how-to panel — is fed by an OpenConnector *source* pointing at xWiki (or any compatible wiki). The source returns a list of articles plus a render URL; DeskDesk surfaces them under the *Knowledge* tab on the floor detail page.
 
 ## Goal
 
-<!-- {{GOAL}} — write the goal: the admin has wired DeskDesk to the company wiki (xWiki) over OpenConnector so desk how-to articles surface in the app. -->
+By the end the knowledge sidebar on a desk's detail page shows articles from your wiki, opening one launches the rendered article in a modal or in a new tab, and the same source is reusable across other DeskDesk instances or other Conduction apps.
 
 ## Prerequisites
 
-<!-- {{PREREQS}} — OpenConnector installed and configured; an xWiki instance with desk how-to pages; admin access to DeskDesk settings. -->
+- The **OpenConnector** app installed and enabled.
+- An xWiki (or compatible) endpoint reachable from the Nextcloud host — URL, an API user, and authentication credentials (Basic auth, OAuth2, or a personal access token).
+- Floors and desks already configured — see [Floors, zones and desks](./01-floors-zones.md).
 
 ## Steps
 
-<!-- {{STEPS}} — numbered steps: open admin settings, choose the knowledge source, point it at the OpenConnector source / xWiki space, map articles to desks, test the connection. Screenshot-worthy steps get a shoot() call in tests/e2e/docs-screenshots.spec.ts. -->
+1. Open **Settings → Administration → DeskDesk** from the Nextcloud admin section. Scroll to the *Knowledge* card.
+
+   ![Admin settings - Knowledge card](/screenshots/tutorials/admin/02-knowledge-source-01.png)
+
+2. The card shows the configured *knowledge source* (an OpenConnector source ID + a human label) and a *Test* button. On a fresh install the field is empty.
+
+   ![Admin settings - Knowledge mid](/screenshots/tutorials/admin/02-knowledge-source-02.png)
+
+3. Click **Connect a source**. The dialog opens with two paths: pick an existing OpenConnector source from the dropdown, or create one inline (the create form is the standard OpenConnector source form — endpoint, auth, mapping).
+
+   ![Admin settings - Knowledge bottom](/screenshots/tutorials/admin/02-knowledge-source-03.png)
+
+   For xWiki, the endpoint is usually `https://wiki.example.com/rest/wikis/xwiki/spaces/...`; the mapping flattens xWiki's REST response into the shape DeskDesk expects (`title`, `url`, `summary`, `desk_match`). Use the default mapping the source template ships with — it covers stock xWiki.
+
+4. Save. Click **Test** to confirm DeskDesk can list articles. A successful test returns a sample of articles; a failure surfaces the OpenConnector error inline (most often: auth token wrong, or the endpoint is unreachable from the NC host).
 
 ## Verification
 
-<!-- {{VERIFICATION}} — opening a desk in the app shows its linked articles, with content pulled from the wiki. -->
+The *Test* button returns a list of sample articles. Opening DeskDesk as a regular user, browsing to a desk that has a wiki article tagged with its identifier, and opening the *Knowledge* sidebar shows that article. See [Read the how-to articles for a desk](../user/06-desk-knowledge.md) for the user-facing flow.
 
 ## Common issues
 
 | Symptom | Fix |
 |---|---|
-<!-- {{COMMON_ISSUES}} — e.g. "connection test fails" / "check the OpenConnector source credentials and base URL". -->
+| Test returns "401 Unauthorized" | The OpenConnector auth credentials are wrong or expired — refresh the token / fix the basic-auth password on the source. |
+| Test returns articles but the sidebar stays empty | The article's `desk_match` field does not match the desk's identifier. Either tag the article with the desk ID in xWiki, or adjust the OpenConnector mapping. |
+| **Connect a source** dialog is missing | OpenConnector is not installed or enabled — install it from the app store first. |
 
 ## Reference
 
-<!-- {{REFERENCE}} — link related docs: OpenConnector docs, the "Read the how-to articles for a desk" user tutorial, ADR-019. -->
+- [Read the how-to articles for a desk](../user/06-desk-knowledge.md) — the user-facing view of this configuration.
+- [Admin settings](./03-admin-settings.md) — the wider DeskDesk settings page.
diff --git a/docs/tutorials/admin/03-admin-settings.md b/docs/tutorials/admin/03-admin-settings.md
@@ -1,35 +1,55 @@
 ---
 sidebar_position: 3
 title: Manage DeskDesk settings
-description: Step-by-step guide to manage DeskDesk settings
+description: Walk through the DeskDesk admin settings — register import, calendar sync toggle, recurring bookings, slot definitions, knowledge source.
 ---
 
 # Manage DeskDesk settings
 
-Step-by-step guide to manage DeskDesk settings.
+DeskDesk's settings page does five jobs: it confirms the OpenRegister mapping, holds the calendar-sync toggle, holds the recurring-bookings toggle, defines the slot windows (AM / PM / full day), and points at the [knowledge source](./02-knowledge-source.md). All of it lives under **Settings → Administration → DeskDesk** in Nextcloud.
 
 ## Goal
 
-<!-- {{GOAL}} — write the goal: the admin knows where every DeskDesk setting lives and what it does — registers, calendar sync, recurring bookings, slot definitions, knowledge source. -->
+By the end every DeskDesk admin setting is set to a sensible value for the deployment, the page reports no errors, and a test booking + a test recurring booking confirm the engine is wired up.
 
 ## Prerequisites
 
-<!-- {{PREREQS}} — admin access to the DeskDesk settings page. -->
+- Admin on the Nextcloud instance.
+- OpenRegister installed and the DeskDesk register imported (the configuration import runs on app install).
 
 ## Steps
 
-<!-- {{STEPS}} — numbered steps: open admin settings, walk through each section (data source / registers, calendar sync toggle, recurring bookings toggle, slot definitions, knowledge source), save. Screenshot-worthy steps get a shoot() call in tests/e2e/docs-screenshots.spec.ts. -->
+1. Open **Settings → Administration → DeskDesk**. The page has five sections — *Registers*, *Calendar sync*, *Recurring bookings*, *Slot definitions*, *Knowledge*. Scroll through to see the layout.
+
+   ![Admin settings - top](/screenshots/tutorials/admin/03-admin-settings-01.png)
+
+2. **Registers** — confirms the OpenRegister mapping for each DeskDesk object type (floor, zone, desk, booking, recurrence, knowledge-source). Each row shows the target register + schema; on a healthy install every row is populated. Click **Re-import configuration** to (re)run the import — useful after a DeskDesk upgrade.
+
+   ![Admin settings - Registers + Calendar](/screenshots/tutorials/admin/03-admin-settings-02.png)
+
+3. **Calendar sync** — toggle controlling whether DeskDesk publishes each booking into Nextcloud Calendar via the OpenRegister calendar provider. Default = on. **Recurring bookings** — toggle to allow or disallow recurring bookings org-wide (some deployments forbid them to keep desk allocation fair). Default = on.
+
+   ![Admin settings - Recurring + Slots](/screenshots/tutorials/admin/03-admin-settings-03.png)
+
+4. **Slot definitions** — defines the time windows for *AM*, *PM*, *Full day*, and any *Custom* slots. Edit the defaults to match your office hours (the shipped defaults are AM 09:00–12:30, PM 13:00–17:30, Full day 09:00–17:30). **Knowledge** — the source for the per-desk how-to sidebar, set up in the [knowledge-source tutorial](./02-knowledge-source.md).
+
+   ![Admin settings - Knowledge + bottom](/screenshots/tutorials/admin/03-admin-settings-04.png)
 
 ## Verification
 
-<!-- {{VERIFICATION}} — settings persist after reload and the app behaves accordingly. -->
+The Registers section shows every row populated. Toggling Calendar sync off and re-saving prevents new bookings from appearing in Calendar (existing entries stay). Adjusting a slot window and creating a fresh booking puts the new times on the booking. The page itself reports no error banner.
 
 ## Common issues
 
 | Symptom | Fix |
 |---|---|
-<!-- {{COMMON_ISSUES}} — e.g. "settings don't persist" / "check the app has write access to its app config". -->
+| Registers row stuck unmapped after re-import | The import is failing server-side — check `nextcloud.log` for the *deskdesk* configuration error. Bring DeskDesk + OpenRegister to compatible versions and retry. |
+| Calendar sync toggle does nothing visible | The OpenRegister calendar provider is missing or disabled. Check OpenRegister's settings and re-enable. |
+| Slot definitions don't show on a new booking | Browser cache — hard-reload (Ctrl-Shift-R). The slot list is cached in Vue's pinia store. |
+| **Knowledge** card has no *Connect a source* button | OpenConnector is not installed — install it before continuing. |
 
 ## Reference
 
-<!-- {{REFERENCE}} — link related docs: the floors/zones and knowledge-source tutorials, ADRs. -->
+- [Set up floors, zones and desks](./01-floors-zones.md) — the first admin step.
+- [Connect the wiki knowledge source](./02-knowledge-source.md) — the *Knowledge* section's deep-dive.
+- [Open DeskDesk for the first time](../user/01-first-launch.md) — the user-facing check after this is done.
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 DeskDesk for the first time
-description: Step-by-step guide to open DeskDesk for the first time
+description: Open DeskDesk, find your way around the navigation, and confirm the OpenRegister back end is connected.
 ---
 
 # Open DeskDesk for the first time
 
-Step-by-step guide to open DeskDesk for the first time.
+A first look at DeskDesk — where the app lives, what the navigation gives you, and how to tell it is wired up to OpenRegister.
 
 ## Goal
 
-<!-- {{GOAL}} — write the goal: what the reader will have accomplished by the end (e.g. "DeskDesk open, the floor plan loaded, oriented on where the booking controls live"). -->
+By the end you will have opened DeskDesk, recognised the dashboard, the floor plan and the booking list, and confirmed that the OpenRegister-backed lists (Desks, Bookings, Floors) load.
 
 ## Prerequisites
 
-<!-- {{PREREQS}} — list prerequisites: DeskDesk installed and enabled, at least one floor/zone/desk configured by an admin, a Nextcloud account. -->
+- A Nextcloud account on an instance where the **DeskDesk** app is installed and enabled.
+- The **OpenRegister** app installed and enabled — DeskDesk stores everything (desks, floors, zones, bookings, knowledge sources) in OpenRegister, so it is a hard dependency.
+- At least one floor with desks configured by an admin — see [Set up floors, zones and desks](../admin/01-floors-zones.md). Without that, the floor picker is empty and the booking dialog has nothing to book.
 
 ## Steps
 
-<!-- {{STEPS}} — write the numbered steps. Each step that warrants a screenshot gets a matching shoot() call in tests/e2e/docs-screenshots.spec.ts — see /journeydoc-add-story. -->
+1. Open the Nextcloud app menu in the top bar and pick **DeskDesk**. You land on the dashboard / desks index.
+
+   ![DeskDesk dashboard](/screenshots/tutorials/user/01-first-launch-01.png)
+
+2. Read the dashboard tiles — occupancy, *My bookings*, *Popular zones*. On a fresh install they read `0`; they fill in as people book.
+
+   ![Dashboard tiles](/screenshots/tutorials/user/01-first-launch-02.png)
+
+3. The in-app navigation has three top-level entries — **Desks** (the home / floor plan), **Bookings** (your booking history), **Floors** (admin view of the building). Below the divider sit **Settings** and the link to the Nextcloud admin settings page.
+
+   ![DeskDesk navigation](/screenshots/tutorials/user/01-first-launch-03.png)
+
+4. Click **Bookings**. The list view shows every booking on the instance (filtered by *My bookings* by default). An empty install reads *No items found* — expected until someone books.
+
+   ![Bookings list, empty state](/screenshots/tutorials/user/01-first-launch-04.png)
 
 ## Verification
 
-<!-- {{VERIFICATION}} — how the reader confirms it worked. -->
+You are set up correctly when: the DeskDesk dashboard renders without an error banner, the navigation lists *Desks*, *Bookings*, *Floors*, and clicking **Bookings** shows either rows or a clean *No items found* state — not a load error.
 
 ## Common issues
 
 | Symptom | Fix |
 |---|---|
-<!-- {{COMMON_ISSUES}} — one row per known symptom/fix pair. -->
+| "OpenRegister is not installed or enabled" banner | Install and enable the OpenRegister app, then reload DeskDesk. |
+| Floor picker is empty | No floors configured — an admin sets up at least one (see [Floors, zones and desks](../admin/01-floors-zones.md)). |
+| DeskDesk 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
 
-<!-- {{REFERENCE}} — link related docs: feature pages, OpenRegister schema, ADRs. -->
+- [Browse desks by floor and zone](./02-browse-desks.md) — the next user step.
+- [Set up floors, zones and desks](../admin/01-floors-zones.md) — the admin counterpart that creates the data this view reads.