docs: fill journeydoc tutorials (content + screenshots)

.gitignore

@@ -86,6 +86,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/

docs/tutorials/admin/01-configure-workflow.md

@@ -1,35 +1,60 @@
 ---
 sidebar_position: 1
 title: Configure a governance workflow
-description: Step-by-step guide to configure a governance workflow
+description: Create a governance body and set the rules — quorum, majority, co-signature threshold, who may do what — that drive its meetings.
 ---
 
 # Configure a governance workflow
 
-Step-by-step guide to configure a governance workflow
+A *governance body* in Decidesk is the thing that meets and decides — a board, a council, a general assembly, a working group. Its workflow is the set of rules Decidesk enforces for its meetings: quorum, majority, co-signature threshold, and which roles may schedule meetings, submit motions, and operate votes.
 
 ## Goal
 
-`{{TODO: write the goal — what the reader will have accomplished by the end}}`
+By the end you will have a governance body in Decidesk with a type, a domain, term dates, and the workflow rules that its meetings, motions, and votes will follow.
 
 ## Prerequisites
 
-`{{TODO: list prerequisites — Decidesk installed, a configured workspace/register, the right role, etc.}}`
+- The **Decidesk** and **OpenRegister** apps installed and enabled, with the Decidesk register imported (see [Manage Decidesk settings](03-admin-settings.md)).
+- Admin (or whoever your organisation appoints) — creating governance bodies and setting workflow rules is an administrative act.
+- A clear picture of the body's actual rules of order (quorum, majority threshold, co-signature requirement, term length).
 
 ## Steps
 
-`{{TODO: 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. Go to **Governance bodies** (under the Decidesk navigation) and click **Add Item**. The *Create Item* dialog opens.
+
+   ![Create governance body dialog](/screenshots/tutorials/admin/01-configure-workflow-01.png)
+
+2. Fill in the body — **name**, **body type** (board, council, ALV/general assembly, committee, …), **domain** (the area it governs), and **term start / term end**. Click **Create**.
+
+   ![Governance body fields filled in](/screenshots/tutorials/admin/01-configure-workflow-02.png)
+
+3. Open the body. Its sidebar has an **Overview**, a **Members** tab, and an **Audit trail**. The Overview is where the workflow rules live — **quorum**, **majority rule** (simple, absolute, two-thirds, …), and the **co-signature threshold** for motions.
+
+   ![Governance body detail with workflow rules](/screenshots/tutorials/admin/01-configure-workflow-03.png)
+
+4. Set the rules to match the body's rules of order. These feed straight into the app: the quorum is checked when a voting round opens, the majority rule decides whether a motion carries, and the co-signature threshold gates a motion's admissibility.
+
+   ![Workflow rules set on the body](/screenshots/tutorials/admin/01-configure-workflow-04.png)
+
+5. Add members on the **Members** tab and give each a role (see [Manage members and roles](02-manage-members.md)) — roles are what let someone schedule a meeting, submit a motion, or operate a vote for this body.
+
+   ![Members tab on the governance body](/screenshots/tutorials/admin/01-configure-workflow-05.png)
 
 ## Verification
 
-`{{TODO: how the reader confirms it worked}}`
+The body shows under **Governance bodies** with its type and domain, its Overview shows the quorum / majority / co-signature settings you entered, and a test meeting created against the body enforces them (e.g. opening a voting round flags quorum, a motion needs the threshold of co-signatures). The **Audit trail** records the body's creation and any rule changes.
 
 ## Common issues
 
 | Symptom | Fix |
 |---|---|
-| `{{TODO}}` | `{{TODO}}` |
+| **Add Item** opens an empty dialog | The `governance-body` schema isn't imported — re-run **Settings → Registers → Re-import configuration** (see [Manage Decidesk settings](03-admin-settings.md)). |
+| Motions on this body never need co-signatures | The co-signature threshold is 0 — set it to the number the body's rules require. |
+| Quorum warning never appears | Quorum is unset or 0 — set the body's quorum so the check has something to compare against. |
+| A member can't schedule a meeting for the body | They don't have a role that grants meeting-scheduling rights — adjust their role on the **Members** tab. |
 
 ## Reference
 
-`{{TODO: link related docs — feature pages, OpenRegister schema, ADRs}}`
+- [Manage members and roles](02-manage-members.md) — assign chair / voting rights / secretary on this body.
+- [Manage Decidesk settings](03-admin-settings.md) — the register import these schemas depend on.
+- [Schedule a meeting and build the agenda](../user/02-schedule-meeting.md) — what a member does once the body exists.

docs/tutorials/admin/02-manage-members.md

@@ -1,35 +1,60 @@
 ---
 sidebar_position: 2
 title: Manage members and roles
-description: Step-by-step guide to manage members and roles
+description: Add participants to a governance body, assign roles (chair, secretary, voting member), and handle proxies and party affiliations.
 ---
 
 # Manage members and roles
 
-Step-by-step guide to manage members and roles
+Members are the people in a governance body; their **role** is what Decidesk checks before letting them act. This page covers adding participants, assigning roles, and the details that affect votes — voting rights, party affiliation, proxies.
 
 ## Goal
 
-`{{TODO: write the goal — what the reader will have accomplished by the end}}`
+By the end you will have a governance body whose members are set up with the right roles, so meeting scheduling, motion submission, vote operation, and minutes signing all land on the right people.
 
 ## Prerequisites
 
-`{{TODO: list prerequisites — Decidesk installed, a configured workspace/register, the right role, etc.}}`
+- A governance body to add members to (see [Configure a governance workflow](01-configure-workflow.md)).
+- Admin, or the chair of the body — both can manage that body's membership.
+- The list of people, their roles, and (if relevant) their party affiliations and voting rights.
 
 ## Steps
 
-`{{TODO: 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 governance body and go to its **Members** tab. It lists the current members with their role; click **Add member**.
+
+   ![Members tab on a governance body](/screenshots/tutorials/admin/02-manage-members-01.png)
+
+2. Add a participant — link a Nextcloud account (or record an external participant with a **display name** and **email**), set the **role** (chair, vice-chair, secretary, voting member, observer, …), and the **party** affiliation if the body tracks one. Save.
+
+   ![Add member dialog](/screenshots/tutorials/admin/02-manage-members-02.png)
+
+3. Repeat for the rest of the body. The role each person holds is what the app enforces — only a chair opens and closes voting rounds, only a secretary drives the minutes lifecycle, observers see but don't vote.
+
+   ![Members list with assigned roles](/screenshots/tutorials/admin/02-manage-members-03.png)
+
+4. Manage participants more broadly under **Participants** in the navigation — a person can sit on more than one body, each with its own role. The participant detail page shows their roles and an **Audit trail** of membership changes.
+
+   ![Participants list](/screenshots/tutorials/admin/02-manage-members-04.png)
+
+5. For a meeting, the chair (or whoever has the right) confirms who is **present**; an absent voting member can have a **proxy** assigned for that meeting's votes, if the body allows proxies. Proxy limits and whether proxies are allowed at all come from the body's workflow.
+
+   ![Meeting participants with a proxy assigned](/screenshots/tutorials/admin/02-manage-members-05.png)
 
 ## Verification
 
-`{{TODO: how the reader confirms it worked}}`
+The body's **Members** tab lists everyone with the role you set, a chair can open a voting round (and a non-chair can't), a secretary can submit minutes for approval, and proxy assignments only stick where the body's workflow permits them. Membership changes show in the **Audit trail**.
 
 ## Common issues
 
 | Symptom | Fix |
 |---|---|
-| `{{TODO}}` | `{{TODO}}` |
+| A member can't do something you expected | Check their **role** on this body — rights are role-based and per-body, so a chair on one body is just a member on another. |
+| Can't assign a proxy | The body must allow proxies, the proxy must be a present member of the meeting, and one member can hold only a limited number of proxies. |
+| The same person appears twice | They're a member of two bodies — that's expected; each membership is separate, with its own role. |
+| External participant has no account link | That's fine — Decidesk records external participants by display name and email; they just can't log in to act themselves. |
 
 ## Reference
 
-`{{TODO: link related docs — feature pages, OpenRegister schema, ADRs}}`
+- [Configure a governance workflow](01-configure-workflow.md) — quorum, majority, proxy rules that interact with roles.
+- [Run a vote](../user/05-run-vote.md) — where presence, voting rights, and proxies come into play.
+- [Take and publish the minutes](../user/06-take-minutes.md) — who must be a signer.

docs/tutorials/admin/03-admin-settings.md

@@ -1,35 +1,61 @@
 ---
 sidebar_position: 3
 title: Manage Decidesk settings
-description: Step-by-step guide to manage Decidesk settings
+description: Open the Decidesk settings, import the register and schemas, check the version, and configure the ORI endpoint and email voting.
 ---
 
 # Manage Decidesk settings
 
-Step-by-step guide to manage Decidesk settings
+Decidesk's settings page does three jobs: it tells you the installed version, it maps the app's object types onto an OpenRegister register and schemas (this is the import that makes everything else work), and it holds the advanced options — the ORI endpoint for publishing voting results, and the email-reply voting toggle.
 
 ## Goal
 
-`{{TODO: write the goal — what the reader will have accomplished by the end}}`
+By the end you will have confirmed the Decidesk version, run (or re-run) the register import so all 24 object types are configured, and set the ORI endpoint and email-voting option to match your deployment.
 
 ## Prerequisites
 
-`{{TODO: list prerequisites — Decidesk installed, a configured workspace/register, the right role, etc.}}`
+- Admin on the Nextcloud instance (or a Decidesk admin), since this changes how the whole app is wired.
+- The **OpenRegister** app installed and enabled — the register import has nothing to import into otherwise.
+- For ORI publication: the URL of your ORI (Open Raadsinformatie / decision-publication) endpoint.
 
 ## Steps
 
-`{{TODO: 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 **Settings** from the Decidesk navigation. The page has three sections — **Version**, **Registers**, **Advanced**.
+
+   ![Decidesk settings page](/screenshots/tutorials/admin/03-admin-settings-01.png)
+
+2. **Version** — confirms the installed Decidesk version and shows an "Up to date" indicator. Nothing to change here; it's the at-a-glance check that the app installed cleanly.
+
+   ![Version section of settings](/screenshots/tutorials/admin/03-admin-settings-02.png)
+
+3. **Registers** — the *Register Configuration* widget shows how many of Decidesk's 24 object types are mapped (e.g. *0/24 configured* on a broken or fresh install, *24/24* once imported). Pick the target register, then click **Re-import configuration** to (re)create the register, all schemas, and the mappings.
+
+   ![Register configuration widget](/screenshots/tutorials/admin/03-admin-settings-03.png)
+
+4. After the import, the count should read *24/24 configured* and the Decidesk lists (Meetings, Motions, …) and their **Add Item** forms work. The same import also runs automatically on app install/upgrade — the button is for fixing a partial import.
+
+   ![Register configuration after import](/screenshots/tutorials/admin/03-admin-settings-04.png)
+
+5. **Advanced** — set the **ORI endpoint** (the URL Decidesk pushes published voting results to) and toggle **email voting** on if you want absent members to be able to vote by replying to a ballot email. Save.
+
+   ![Advanced settings — ORI endpoint and email voting](/screenshots/tutorials/admin/03-admin-settings-05.png)
 
 ## Verification
 
-`{{TODO: how the reader confirms it worked}}`
+The **Version** section shows the installed version with "Up to date", the **Registers** widget reads *24/24 configured*, a list view's **Add Item** opens a dialog with real form fields (not an empty modal), and the **Advanced** values you saved persist on reload.
 
 ## Common issues
 
 | Symptom | Fix |
 |---|---|
-| `{{TODO}}` | `{{TODO}}` |
+| Register widget stuck at *0/24 configured* even after clicking Re-import | The import is failing server-side — check the Nextcloud log for the Decidesk configuration error; a stale OpenRegister / Decidesk version pair can mismatch the import API. Re-run after both apps are on compatible versions. |
+| **Add Item** dialogs are empty across the app | Same root cause — the schemas aren't mapped; fix the register import first, everything else follows. |
+| ORI publication does nothing | The **ORI endpoint** field is empty or wrong — publishing a voting result only pushes to ORI when a valid endpoint is set. |
+| Email votes never count | **Email voting** must be enabled here *and* the member must reply from their registered address within the voting round's window. |
+| Settings page itself shows an OpenRegister error | OpenRegister isn't installed/enabled — install it, then reload Decidesk. |
 
 ## Reference
 
-`{{TODO: link related docs — feature pages, OpenRegister schema, ADRs}}`
+- [Open Decidesk for the first time](../user/01-first-launch.md) — the user-facing check that the import worked.
+- [Configure a governance workflow](01-configure-workflow.md) — the first thing to set up once the register is imported.
+- [Run a vote](../user/05-run-vote.md) — where the ORI endpoint and email-voting settings are used.

docs/tutorials/user/01-first-launch.md

@@ -1,35 +1,54 @@
 ---
 sidebar_position: 1
 title: Open Decidesk for the first time
-description: Step-by-step guide to open Decidesk for the first time
+description: Open Decidesk, find your way around the navigation, and confirm the OpenRegister back end is connected.
 ---
 
 # Open Decidesk for the first time
 
-Step-by-step guide to open Decidesk for the first time
+A first look at Decidesk — where the app lives, what the navigation gives you, and how to tell it is wired up to OpenRegister.
 
 ## Goal
 
-`{{TODO: write the goal — what the reader will have accomplished by the end}}`
+By the end you will have opened the Decidesk app, recognised the dashboard and the left-hand navigation, and confirmed that the OpenRegister-backed lists (Meetings, Motions, Decisions, …) load.
 
 ## Prerequisites
 
-`{{TODO: list prerequisites — Decidesk installed, a configured workspace/register, the right role, etc.}}`
+- A Nextcloud account on an instance where the **Decidesk** app is installed and enabled.
+- The **OpenRegister** app installed and enabled — Decidesk stores everything (meetings, motions, votes, minutes) in OpenRegister, so it is a hard dependency.
+- The Decidesk register and its schemas imported. An admin runs this once from **Settings → Registers → Re-import configuration** (see [Manage Decidesk settings](../admin/03-admin-settings.md)).
 
 ## Steps
 
-`{{TODO: 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 **Decidesk**. You land on the dashboard.
+
+   ![Decidesk dashboard](/screenshots/tutorials/user/01-first-launch-01.png)
+
+2. Read the dashboard tiles — *Minutes awaiting approval*, *Published decisions*, *Open action items*. On a fresh install they read `0`; they fill in as work moves through the app.
+
+   ![Dashboard stat tiles](/screenshots/tutorials/user/01-first-launch-02.png)
+
+3. Open the left-hand navigation. The entries map one-to-one onto the things Decidesk tracks: **Meetings**, **Motions**, **Decisions**, **Action items**, **Minutes**, **Tasks**, **Workspaces**, **Comments**, **Email links**, **Engagement**. Below the divider sit **Settings** and **Features & roadmap**.
+
+   ![Decidesk navigation](/screenshots/tutorials/user/01-first-launch-03.png)
+
+4. Click **Meetings**. The list view opens with a *Cards / Table* toggle, an **Add Item** button, and a search sidebar. An empty install shows *No items found* — expected until someone schedules the first meeting.
+
+   ![Meetings list, empty state](/screenshots/tutorials/user/01-first-launch-04.png)
 
 ## Verification
 
-`{{TODO: how the reader confirms it worked}}`
+You are set up correctly when: the Decidesk dashboard renders without an error banner, the left navigation lists the entries above, and clicking through to **Meetings** (or any other list) shows either rows or a clean *No items found* state — not a load error.
 
 ## Common issues
 
 | Symptom | Fix |
 |---|---|
-| `{{TODO}}` | `{{TODO}}` |
+| "OpenRegister is not installed or enabled" banner | Install and enable the OpenRegister app, then reload Decidesk. |
+| Lists load but **Add Item** opens a modal with no form fields | The Decidesk register import is incomplete — an admin re-runs **Settings → Registers → Re-import configuration**. |
+| Decidesk 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 related docs — feature pages, OpenRegister schema, ADRs}}`
+- [MCP Tools (AI Chat Companion integration)](../../features/mcp-tools.md) — how the AI companion reaches Decidesk's data.
+- [Manage Decidesk settings](../admin/03-admin-settings.md) — register import, ORI endpoint, email voting.