diff --git a/.gitignore b/.gitignore index 4b91c7bb2..2e5d70634 100644 --- a/.gitignore +++ b/.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/ diff --git a/docs/static/screenshots/tutorials/admin/01-configure-workflow-01.png b/docs/static/screenshots/tutorials/admin/01-configure-workflow-01.png new file mode 100644 index 000000000..17f16e5c3 Binary files /dev/null and b/docs/static/screenshots/tutorials/admin/01-configure-workflow-01.png differ diff --git a/docs/static/screenshots/tutorials/admin/01-configure-workflow-02.png b/docs/static/screenshots/tutorials/admin/01-configure-workflow-02.png new file mode 100644 index 000000000..f40046fa8 Binary files /dev/null and b/docs/static/screenshots/tutorials/admin/01-configure-workflow-02.png differ diff --git a/docs/static/screenshots/tutorials/admin/01-configure-workflow-03.png b/docs/static/screenshots/tutorials/admin/01-configure-workflow-03.png new file mode 100644 index 000000000..17f16e5c3 Binary files /dev/null and b/docs/static/screenshots/tutorials/admin/01-configure-workflow-03.png differ diff --git a/docs/static/screenshots/tutorials/admin/01-configure-workflow-04.png b/docs/static/screenshots/tutorials/admin/01-configure-workflow-04.png new file mode 100644 index 000000000..17f16e5c3 Binary files /dev/null and b/docs/static/screenshots/tutorials/admin/01-configure-workflow-04.png differ diff --git a/docs/static/screenshots/tutorials/admin/01-configure-workflow-05.png b/docs/static/screenshots/tutorials/admin/01-configure-workflow-05.png new file mode 100644 index 000000000..17f16e5c3 Binary files /dev/null and b/docs/static/screenshots/tutorials/admin/01-configure-workflow-05.png differ diff --git a/docs/static/screenshots/tutorials/admin/02-manage-members-01.png b/docs/static/screenshots/tutorials/admin/02-manage-members-01.png new file mode 100644 index 000000000..17f16e5c3 Binary files /dev/null and b/docs/static/screenshots/tutorials/admin/02-manage-members-01.png differ diff --git a/docs/static/screenshots/tutorials/admin/02-manage-members-02.png b/docs/static/screenshots/tutorials/admin/02-manage-members-02.png new file mode 100644 index 000000000..f40046fa8 Binary files /dev/null and b/docs/static/screenshots/tutorials/admin/02-manage-members-02.png differ diff --git a/docs/static/screenshots/tutorials/admin/02-manage-members-03.png b/docs/static/screenshots/tutorials/admin/02-manage-members-03.png new file mode 100644 index 000000000..17f16e5c3 Binary files /dev/null and b/docs/static/screenshots/tutorials/admin/02-manage-members-03.png differ diff --git a/docs/static/screenshots/tutorials/admin/02-manage-members-04.png b/docs/static/screenshots/tutorials/admin/02-manage-members-04.png new file mode 100644 index 000000000..17f16e5c3 Binary files /dev/null and b/docs/static/screenshots/tutorials/admin/02-manage-members-04.png differ diff --git a/docs/static/screenshots/tutorials/admin/02-manage-members-05.png b/docs/static/screenshots/tutorials/admin/02-manage-members-05.png new file mode 100644 index 000000000..f0317bff1 Binary files /dev/null and b/docs/static/screenshots/tutorials/admin/02-manage-members-05.png differ diff --git a/docs/static/screenshots/tutorials/admin/03-admin-settings-01.png b/docs/static/screenshots/tutorials/admin/03-admin-settings-01.png new file mode 100644 index 000000000..47f1f65b9 Binary files /dev/null and b/docs/static/screenshots/tutorials/admin/03-admin-settings-01.png differ diff --git a/docs/static/screenshots/tutorials/admin/03-admin-settings-02.png b/docs/static/screenshots/tutorials/admin/03-admin-settings-02.png new file mode 100644 index 000000000..47f1f65b9 Binary files /dev/null and b/docs/static/screenshots/tutorials/admin/03-admin-settings-02.png differ diff --git a/docs/static/screenshots/tutorials/admin/03-admin-settings-03.png b/docs/static/screenshots/tutorials/admin/03-admin-settings-03.png new file mode 100644 index 000000000..47f1f65b9 Binary files /dev/null and b/docs/static/screenshots/tutorials/admin/03-admin-settings-03.png differ diff --git a/docs/static/screenshots/tutorials/admin/03-admin-settings-04.png b/docs/static/screenshots/tutorials/admin/03-admin-settings-04.png new file mode 100644 index 000000000..47f1f65b9 Binary files /dev/null and b/docs/static/screenshots/tutorials/admin/03-admin-settings-04.png differ diff --git a/docs/static/screenshots/tutorials/admin/03-admin-settings-05.png b/docs/static/screenshots/tutorials/admin/03-admin-settings-05.png new file mode 100644 index 000000000..28f810911 Binary files /dev/null and b/docs/static/screenshots/tutorials/admin/03-admin-settings-05.png differ diff --git a/docs/static/screenshots/tutorials/user/01-first-launch-01.png b/docs/static/screenshots/tutorials/user/01-first-launch-01.png new file mode 100644 index 000000000..0f85954bb Binary files /dev/null and b/docs/static/screenshots/tutorials/user/01-first-launch-01.png differ diff --git a/docs/static/screenshots/tutorials/user/01-first-launch-02.png b/docs/static/screenshots/tutorials/user/01-first-launch-02.png new file mode 100644 index 000000000..0f85954bb Binary files /dev/null and b/docs/static/screenshots/tutorials/user/01-first-launch-02.png differ diff --git a/docs/static/screenshots/tutorials/user/01-first-launch-03.png b/docs/static/screenshots/tutorials/user/01-first-launch-03.png new file mode 100644 index 000000000..0f85954bb Binary files /dev/null and b/docs/static/screenshots/tutorials/user/01-first-launch-03.png differ diff --git a/docs/static/screenshots/tutorials/user/01-first-launch-04.png b/docs/static/screenshots/tutorials/user/01-first-launch-04.png new file mode 100644 index 000000000..d60cf848e Binary files /dev/null and b/docs/static/screenshots/tutorials/user/01-first-launch-04.png differ diff --git a/docs/static/screenshots/tutorials/user/02-schedule-meeting-01.png b/docs/static/screenshots/tutorials/user/02-schedule-meeting-01.png new file mode 100644 index 000000000..175e59608 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/02-schedule-meeting-01.png differ diff --git a/docs/static/screenshots/tutorials/user/02-schedule-meeting-02.png b/docs/static/screenshots/tutorials/user/02-schedule-meeting-02.png new file mode 100644 index 000000000..175e59608 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/02-schedule-meeting-02.png differ diff --git a/docs/static/screenshots/tutorials/user/02-schedule-meeting-03.png b/docs/static/screenshots/tutorials/user/02-schedule-meeting-03.png new file mode 100644 index 000000000..d60cf848e Binary files /dev/null and b/docs/static/screenshots/tutorials/user/02-schedule-meeting-03.png differ diff --git a/docs/static/screenshots/tutorials/user/02-schedule-meeting-04.png b/docs/static/screenshots/tutorials/user/02-schedule-meeting-04.png new file mode 100644 index 000000000..4db611353 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/02-schedule-meeting-04.png differ diff --git a/docs/static/screenshots/tutorials/user/02-schedule-meeting-05.png b/docs/static/screenshots/tutorials/user/02-schedule-meeting-05.png new file mode 100644 index 000000000..4db611353 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/02-schedule-meeting-05.png differ diff --git a/docs/static/screenshots/tutorials/user/03-add-motion-01.png b/docs/static/screenshots/tutorials/user/03-add-motion-01.png new file mode 100644 index 000000000..f8353b88d Binary files /dev/null and b/docs/static/screenshots/tutorials/user/03-add-motion-01.png differ diff --git a/docs/static/screenshots/tutorials/user/03-add-motion-02.png b/docs/static/screenshots/tutorials/user/03-add-motion-02.png new file mode 100644 index 000000000..f8353b88d Binary files /dev/null and b/docs/static/screenshots/tutorials/user/03-add-motion-02.png differ diff --git a/docs/static/screenshots/tutorials/user/03-add-motion-03.png b/docs/static/screenshots/tutorials/user/03-add-motion-03.png new file mode 100644 index 000000000..b0c820658 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/03-add-motion-03.png differ diff --git a/docs/static/screenshots/tutorials/user/03-add-motion-04.png b/docs/static/screenshots/tutorials/user/03-add-motion-04.png new file mode 100644 index 000000000..b0c820658 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/03-add-motion-04.png differ diff --git a/docs/static/screenshots/tutorials/user/03-add-motion-05.png b/docs/static/screenshots/tutorials/user/03-add-motion-05.png new file mode 100644 index 000000000..b0c820658 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/03-add-motion-05.png differ diff --git a/docs/static/screenshots/tutorials/user/04-propose-amendment-01.png b/docs/static/screenshots/tutorials/user/04-propose-amendment-01.png new file mode 100644 index 000000000..b0c820658 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/04-propose-amendment-01.png differ diff --git a/docs/static/screenshots/tutorials/user/04-propose-amendment-02.png b/docs/static/screenshots/tutorials/user/04-propose-amendment-02.png new file mode 100644 index 000000000..f8353b88d Binary files /dev/null and b/docs/static/screenshots/tutorials/user/04-propose-amendment-02.png differ diff --git a/docs/static/screenshots/tutorials/user/04-propose-amendment-03.png b/docs/static/screenshots/tutorials/user/04-propose-amendment-03.png new file mode 100644 index 000000000..b0c820658 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/04-propose-amendment-03.png differ diff --git a/docs/static/screenshots/tutorials/user/04-propose-amendment-04.png b/docs/static/screenshots/tutorials/user/04-propose-amendment-04.png new file mode 100644 index 000000000..b0c820658 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/04-propose-amendment-04.png differ diff --git a/docs/static/screenshots/tutorials/user/05-run-vote-01.png b/docs/static/screenshots/tutorials/user/05-run-vote-01.png new file mode 100644 index 000000000..d60cf848e Binary files /dev/null and b/docs/static/screenshots/tutorials/user/05-run-vote-01.png differ diff --git a/docs/static/screenshots/tutorials/user/05-run-vote-02.png b/docs/static/screenshots/tutorials/user/05-run-vote-02.png new file mode 100644 index 000000000..d60cf848e Binary files /dev/null and b/docs/static/screenshots/tutorials/user/05-run-vote-02.png differ diff --git a/docs/static/screenshots/tutorials/user/05-run-vote-03.png b/docs/static/screenshots/tutorials/user/05-run-vote-03.png new file mode 100644 index 000000000..d60cf848e Binary files /dev/null and b/docs/static/screenshots/tutorials/user/05-run-vote-03.png differ diff --git a/docs/static/screenshots/tutorials/user/05-run-vote-04.png b/docs/static/screenshots/tutorials/user/05-run-vote-04.png new file mode 100644 index 000000000..cdb43caaa Binary files /dev/null and b/docs/static/screenshots/tutorials/user/05-run-vote-04.png differ diff --git a/docs/static/screenshots/tutorials/user/05-run-vote-05.png b/docs/static/screenshots/tutorials/user/05-run-vote-05.png new file mode 100644 index 000000000..cdb43caaa Binary files /dev/null and b/docs/static/screenshots/tutorials/user/05-run-vote-05.png differ diff --git a/docs/static/screenshots/tutorials/user/06-take-minutes-01.png b/docs/static/screenshots/tutorials/user/06-take-minutes-01.png new file mode 100644 index 000000000..56061a950 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/06-take-minutes-01.png differ diff --git a/docs/static/screenshots/tutorials/user/06-take-minutes-02.png b/docs/static/screenshots/tutorials/user/06-take-minutes-02.png new file mode 100644 index 000000000..56061a950 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/06-take-minutes-02.png differ diff --git a/docs/static/screenshots/tutorials/user/06-take-minutes-03.png b/docs/static/screenshots/tutorials/user/06-take-minutes-03.png new file mode 100644 index 000000000..56061a950 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/06-take-minutes-03.png differ diff --git a/docs/static/screenshots/tutorials/user/06-take-minutes-04.png b/docs/static/screenshots/tutorials/user/06-take-minutes-04.png new file mode 100644 index 000000000..56061a950 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/06-take-minutes-04.png differ diff --git a/docs/static/screenshots/tutorials/user/06-take-minutes-05.png b/docs/static/screenshots/tutorials/user/06-take-minutes-05.png new file mode 100644 index 000000000..be8163fca Binary files /dev/null and b/docs/static/screenshots/tutorials/user/06-take-minutes-05.png differ diff --git a/docs/static/screenshots/tutorials/user/07-track-decisions-01.png b/docs/static/screenshots/tutorials/user/07-track-decisions-01.png new file mode 100644 index 000000000..cdb43caaa Binary files /dev/null and b/docs/static/screenshots/tutorials/user/07-track-decisions-01.png differ diff --git a/docs/static/screenshots/tutorials/user/07-track-decisions-02.png b/docs/static/screenshots/tutorials/user/07-track-decisions-02.png new file mode 100644 index 000000000..cdb43caaa Binary files /dev/null and b/docs/static/screenshots/tutorials/user/07-track-decisions-02.png differ diff --git a/docs/static/screenshots/tutorials/user/07-track-decisions-03.png b/docs/static/screenshots/tutorials/user/07-track-decisions-03.png new file mode 100644 index 000000000..a708a5774 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/07-track-decisions-03.png differ diff --git a/docs/static/screenshots/tutorials/user/07-track-decisions-04.png b/docs/static/screenshots/tutorials/user/07-track-decisions-04.png new file mode 100644 index 000000000..95a4e74dd Binary files /dev/null and b/docs/static/screenshots/tutorials/user/07-track-decisions-04.png differ diff --git a/docs/static/screenshots/tutorials/user/07-track-decisions-05.png b/docs/static/screenshots/tutorials/user/07-track-decisions-05.png new file mode 100644 index 000000000..fb4d63e6e Binary files /dev/null and b/docs/static/screenshots/tutorials/user/07-track-decisions-05.png differ diff --git a/docs/static/screenshots/tutorials/user/08-ai-companion-01.png b/docs/static/screenshots/tutorials/user/08-ai-companion-01.png new file mode 100644 index 000000000..f4c734d79 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/08-ai-companion-01.png differ diff --git a/docs/static/screenshots/tutorials/user/08-ai-companion-02.png b/docs/static/screenshots/tutorials/user/08-ai-companion-02.png new file mode 100644 index 000000000..f4c734d79 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/08-ai-companion-02.png differ diff --git a/docs/static/screenshots/tutorials/user/08-ai-companion-03.png b/docs/static/screenshots/tutorials/user/08-ai-companion-03.png new file mode 100644 index 000000000..f4c734d79 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/08-ai-companion-03.png differ diff --git a/docs/static/screenshots/tutorials/user/08-ai-companion-04.png b/docs/static/screenshots/tutorials/user/08-ai-companion-04.png new file mode 100644 index 000000000..f4c734d79 Binary files /dev/null and b/docs/static/screenshots/tutorials/user/08-ai-companion-04.png differ diff --git a/docs/tutorials/admin/01-configure-workflow.md b/docs/tutorials/admin/01-configure-workflow.md index a16b37893..761c85720 100644 --- a/docs/tutorials/admin/01-configure-workflow.md +++ b/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. diff --git a/docs/tutorials/admin/02-manage-members.md b/docs/tutorials/admin/02-manage-members.md index 1acea7349..04e10b0c4 100644 --- a/docs/tutorials/admin/02-manage-members.md +++ b/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. diff --git a/docs/tutorials/admin/03-admin-settings.md b/docs/tutorials/admin/03-admin-settings.md index 795956977..1f00cc35b 100644 --- a/docs/tutorials/admin/03-admin-settings.md +++ b/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. diff --git a/docs/tutorials/user/01-first-launch.md b/docs/tutorials/user/01-first-launch.md index c86638197..8e6ccd4a0 100644 --- 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 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. diff --git a/docs/tutorials/user/02-schedule-meeting.md b/docs/tutorials/user/02-schedule-meeting.md index 786c56e19..c18783886 100644 --- a/docs/tutorials/user/02-schedule-meeting.md +++ b/docs/tutorials/user/02-schedule-meeting.md @@ -1,35 +1,60 @@ --- sidebar_position: 2 title: Schedule a meeting and build the agenda -description: Step-by-step guide to schedule a meeting and build the agenda +description: Create a meeting, set its type and date, then build and publish its agenda. --- # Schedule a meeting and build the agenda -Step-by-step guide to schedule a meeting and build the agenda +Create a meeting record, give it a type and a date, then add agenda items and publish the agenda so participants can see it. ## Goal -`{{TODO: write the goal — what the reader will have accomplished by the end}}` +By the end you will have a meeting in Decidesk with a date, a meeting mode, an ordered list of agenda items, and a published agenda. ## Prerequisites -`{{TODO: list prerequisites — Decidesk installed, a configured workspace/register, the right role, etc.}}` +- Decidesk open and the OpenRegister back end connected (see [Open Decidesk for the first time](01-first-launch.md)). +- The right to create meetings — chair or secretary of the relevant governance body. Read-only members can view a meeting but not schedule one. +- The governance body that owns the meeting already exists (an admin creates these — see [Configure a governance workflow](../admin/01-configure-workflow.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 **Meetings** in the navigation and click **Add Item**. The *Create Item* dialog opens. + + ![Create meeting dialog](/screenshots/tutorials/user/02-schedule-meeting-01.png) + +2. Fill in the meeting fields — **title**, **meeting type** (board, council, ALV/general assembly, …), **scheduled date** and time, **end date**, **location**, and **meeting mode** (in person, online, hybrid). Set **quorum required** if the body has a quorum rule. Click **Create**. + + ![Meeting fields filled in](/screenshots/tutorials/user/02-schedule-meeting-02.png) + +3. The meeting appears in the list. Open it to reach the meeting detail page; the sidebar carries an **Overview**, **Agenda**, **Participants** and **Audit trail** tab. + + ![Meeting detail page](/screenshots/tutorials/user/02-schedule-meeting-03.png) + +4. Switch to the **Agenda** tab. Add agenda items one by one — each gets an **order number**, a **title**, an **item type** (information, discussion, decision), and an optional **estimated duration**. Drag rows to reorder. Mark routine items as *hamerstukken* (consent agenda) so they can be adopted in one block during the meeting. + + ![Agenda builder with items](/screenshots/tutorials/user/02-schedule-meeting-04.png) + +5. When the agenda is final, **publish** it. Participants now see the fixed agenda; later edits create a new revision rather than silently changing the published version. + + ![Published agenda](/screenshots/tutorials/user/02-schedule-meeting-05.png) ## Verification -`{{TODO: how the reader confirms it worked}}` +The meeting shows in the **Meetings** list with its scheduled date and `lifecycle` set (e.g. *planned*), the **Agenda** tab lists the items in order, and the agenda's status reads *published*. The **Audit trail** tab records who created the meeting and published the agenda. ## Common issues | Symptom | Fix | |---|---| -| `{{TODO}}` | `{{TODO}}` | +| **Add Item** opens an empty dialog | The `meeting` schema is not imported — ask an admin to re-run the register import (**Settings → Registers → Re-import configuration**). | +| Can't reorder agenda rows | Drag-reorder needs edit rights on the meeting; a read-only participant sees the list but can't move rows. | +| Published agenda still shows old items | A revision was created but not published — open the agenda and publish the latest revision. | +| Hamerstukken don't appear as a consent block in the live meeting | Each item must be flagged as a hamerstuk on the agenda before the meeting opens. | ## Reference -`{{TODO: link related docs — feature pages, OpenRegister schema, ADRs}}` +- [Add a motion to the agenda](03-add-motion.md) — attach a motion to one of these agenda items. +- [Take and publish the minutes](06-take-minutes.md) — what happens to the agenda after the meeting. +- [Configure a governance workflow](../admin/01-configure-workflow.md) — who is allowed to schedule meetings for a body. diff --git a/docs/tutorials/user/03-add-motion.md b/docs/tutorials/user/03-add-motion.md index 40aabd19a..ff7c0ce30 100644 --- a/docs/tutorials/user/03-add-motion.md +++ b/docs/tutorials/user/03-add-motion.md @@ -1,35 +1,59 @@ --- sidebar_position: 3 title: Add a motion to the agenda -description: Step-by-step guide to add a motion to the agenda +description: Submit a motion, attach it to an agenda item, and gather co-signatures. --- # Add a motion to the agenda -Step-by-step guide to add a motion to the agenda +Create a motion, link it to a decision-type agenda item, and — where the body requires it — collect co-signatures before it is admissible. ## Goal -`{{TODO: write the goal — what the reader will have accomplished by the end}}` +By the end you will have a motion in Decidesk attached to an agenda item, with its proposer set and (if needed) the required co-signatures gathered, ready for debate and a vote. ## Prerequisites -`{{TODO: list prerequisites — Decidesk installed, a configured workspace/register, the right role, etc.}}` +- A meeting with a published agenda that has at least one *decision*-type agenda item (see [Schedule a meeting and build the agenda](02-schedule-meeting.md)). +- Membership of the governance body, or whatever role the body's workflow grants motion-submission rights. +- If the body sets a co-signature threshold, the names of the members who will co-sign. ## 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 **Motions** in the navigation and click **Add Item**, or open the meeting's agenda item and add a motion from there. + + ![Create motion dialog](/screenshots/tutorials/user/03-add-motion-01.png) + +2. Fill in the motion — **title**, **motion type** (substantive, procedural, budget-related, …), the **proposer**, and the motion text. Link it to the **agenda item** it belongs to. Click **Create**. + + ![Motion fields filled in](/screenshots/tutorials/user/03-add-motion-02.png) + +3. Open the motion. Its sidebar has an **Overview**, **Amendments**, **Votes** and **Audit trail** tab. The motion starts in a *draft* / *submitted* lifecycle state. + + ![Motion detail page](/screenshots/tutorials/user/03-add-motion-03.png) + +4. If the body requires co-signatures, request them — Decidesk sends a co-sign request to each named member, and the motion stays *pending* until enough confirmations come in. The **Audit trail** records each confirmation. + + ![Co-signature requests on a motion](/screenshots/tutorials/user/03-add-motion-04.png) + +5. Once the co-signature threshold is met (or if none is required), transition the motion to *admissible*. It is now on the agenda for debate. + + ![Motion marked admissible](/screenshots/tutorials/user/03-add-motion-05.png) ## Verification -`{{TODO: how the reader confirms it worked}}` +The motion shows in the **Motions** list with its proposer and lifecycle, it is linked from the agenda item it belongs to, and — where applicable — the **Audit trail** shows the co-signature confirmations and the transition to *admissible*. ## Common issues | Symptom | Fix | |---|---| -| `{{TODO}}` | `{{TODO}}` | +| Can't transition the motion to admissible | The co-signature threshold isn't met yet — chase the outstanding confirmations, or check the body's threshold in its workflow. | +| Motion has no agenda item shown | It was created without linking an agenda item — edit the motion and set the agenda item. | +| Budget-related motion warns about budget impact | A budget-type motion can capture a monetary amount and budget-impact note; fill that in before the vote so the impact is on record. | ## Reference -`{{TODO: link related docs — feature pages, OpenRegister schema, ADRs}}` +- [Propose an amendment](04-propose-amendment.md) — change the text of this motion before the vote. +- [Run a vote](05-run-vote.md) — open a voting round on this motion. +- [Configure a governance workflow](../admin/01-configure-workflow.md) — co-signature thresholds and who may submit motions. diff --git a/docs/tutorials/user/04-propose-amendment.md b/docs/tutorials/user/04-propose-amendment.md index 058c549b1..e4c19f95f 100644 --- a/docs/tutorials/user/04-propose-amendment.md +++ b/docs/tutorials/user/04-propose-amendment.md @@ -1,35 +1,53 @@ --- sidebar_position: 4 title: Propose an amendment -description: Step-by-step guide to propose an amendment +description: Attach an amendment to a motion, describe the change, and move it through to a vote. --- # Propose an amendment -Step-by-step guide to propose an amendment +Create an amendment against an open motion — what changes, why — so it can be debated and voted on before the motion itself. ## Goal -`{{TODO: write the goal — what the reader will have accomplished by the end}}` +By the end you will have an amendment in Decidesk linked to its parent motion, with the proposed change described, ready for the chair to put it to a vote ahead of the motion. ## Prerequisites -`{{TODO: list prerequisites — Decidesk installed, a configured workspace/register, the right role, etc.}}` +- An admissible motion that is still open for amendments (see [Add a motion to the agenda](03-add-motion.md)). +- The right to submit amendments — usually the same membership/role that lets you submit motions for that body. ## 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 motion you want to amend and switch to its **Amendments** tab. Click **Add amendment** (or open **Motions**, find the parent motion, and add the amendment from there). + + ![Amendments tab on a motion](/screenshots/tutorials/user/04-propose-amendment-01.png) + +2. Describe the amendment — a **title**, the **proposer**, and the change itself (the wording to add, strike, or replace, and the rationale). The amendment is linked to its **parent motion** automatically. Click **Create**. + + ![Amendment fields filled in](/screenshots/tutorials/user/04-propose-amendment-02.png) + +3. Open the amendment. Its sidebar has an **Overview**, a **Parent motion** tab (a shortcut back to the motion it modifies), and an **Audit trail**. The amendment starts in a *submitted* state. + + ![Amendment detail page](/screenshots/tutorials/user/04-propose-amendment-03.png) + +4. The chair reviews the amendment for admissibility, then transitions it to *admissible*. Multiple admissible amendments on one motion are ordered — typically the most far-reaching is voted first. + + ![Amendment marked admissible](/screenshots/tutorials/user/04-propose-amendment-04.png) ## Verification -`{{TODO: how the reader confirms it worked}}` +The amendment shows on the parent motion's **Amendments** tab, the amendment's **Parent motion** tab links back to the right motion, and the **Audit trail** records the submission and the transition to *admissible*. ## Common issues | Symptom | Fix | |---|---| -| `{{TODO}}` | `{{TODO}}` | +| Can't add an amendment | The motion is past the amendment stage — once a vote is open on the motion, new amendments are no longer accepted. | +| Amendment isn't on the motion's Amendments tab | It was created without a parent motion — edit it and set the parent motion. | +| Two amendments conflict | That's normal — the chair sequences admissible amendments; voting one through can make a later one moot, in which case it is withdrawn. | ## Reference -`{{TODO: link related docs — feature pages, OpenRegister schema, ADRs}}` +- [Run a vote](05-run-vote.md) — vote the amendment through (or down) before the motion. +- [Add a motion to the agenda](03-add-motion.md) — the motion this amendment modifies. diff --git a/docs/tutorials/user/05-run-vote.md b/docs/tutorials/user/05-run-vote.md index 1112617f3..3b84e8824 100644 --- a/docs/tutorials/user/05-run-vote.md +++ b/docs/tutorials/user/05-run-vote.md @@ -1,35 +1,61 @@ --- sidebar_position: 5 title: Run a vote -description: Step-by-step guide to run a vote +description: Open a voting round on a motion or amendment, cast votes (including proxies), close it, and publish the result. --- # Run a vote -Step-by-step guide to run a vote +Open a voting round on a motion (or amendment), let members cast their vote — in the room, by proxy, or by email reply — then close the round and publish the tally as a decision. ## Goal -`{{TODO: write the goal — what the reader will have accomplished by the end}}` +By the end you will have run a voting round to completion: votes cast, quorum checked, the round closed, the tally computed, and the result published so it becomes a tracked decision. ## Prerequisites -`{{TODO: list prerequisites — Decidesk installed, a configured workspace/register, the right role, etc.}}` +- An admissible motion or amendment (see [Add a motion to the agenda](03-add-motion.md) and [Propose an amendment](04-propose-amendment.md)). +- Chair (or whoever the body's workflow names as the vote operator) — only that role can open and close a round. +- A participant list for the meeting so quorum and proxy assignments resolve correctly. +- For email voting: the **email voting** setting enabled (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. From the meeting's live view (or the motion's **Votes** tab), open a **voting round** on the motion or amendment. Decidesk records who is present and checks the quorum before the round opens. + + ![Open a voting round](/screenshots/tutorials/user/05-run-vote-01.png) + +2. Members **cast** their votes — *for*, *against*, *abstain*. A member who is absent can have a **proxy** cast on their behalf if the body allows proxies; the proxy assignment is recorded against the round. + + ![Casting votes in a round](/screenshots/tutorials/user/05-run-vote-02.png) + +3. If email voting is enabled, absent members can reply to a ballot email and their reply is matched into the round. The round stays open until the chair closes it. + + ![Voting round with email and proxy votes](/screenshots/tutorials/user/05-run-vote-03.png) + +4. The chair **closes** the round. Decidesk computes the **tally** — counts per option, whether the motion carries given the body's majority rule, and whether quorum was met. + + ![Closed round with the tally](/screenshots/tutorials/user/05-run-vote-04.png) + +5. **Publish** the result. The tally becomes a **decision** in Decidesk (and, if an ORI endpoint is configured, can be pushed there); the motion's lifecycle moves to *carried* or *rejected*. + + ![Published voting result](/screenshots/tutorials/user/05-run-vote-05.png) ## Verification -`{{TODO: how the reader confirms it worked}}` +The voting round shows as *closed* with a tally, the motion's lifecycle reads *carried* or *rejected*, and a matching **decision** appears under **Decisions** with the outcome. The **Audit trail** on the motion records who opened, cast, closed, and published. ## Common issues | Symptom | Fix | |---|---| -| `{{TODO}}` | `{{TODO}}` | +| Can't open a round | Only the chair / vote operator can; check your role for this body. | +| Round opens but warns about quorum | Quorum isn't met — the chair decides whether to proceed (some rules allow it, some don't); the warning is recorded either way. | +| Email replies aren't counted | Email voting must be enabled in **Settings**, and the reply must come from the member's registered address within the round's window. | +| Proxy vote rejected | The body must allow proxies, the proxy must be a present participant, and one member can usually hold only a limited number of proxies. | ## Reference -`{{TODO: link related docs — feature pages, OpenRegister schema, ADRs}}` +- [Track decisions and action items](07-track-decisions.md) — what happens to the decision this vote produced. +- [Take and publish the minutes](06-take-minutes.md) — the vote result lands in the minutes. +- [Manage Decidesk settings](../admin/03-admin-settings.md) — email voting and the ORI endpoint. diff --git a/docs/tutorials/user/06-take-minutes.md b/docs/tutorials/user/06-take-minutes.md index c10c449de..4a93f1be9 100644 --- a/docs/tutorials/user/06-take-minutes.md +++ b/docs/tutorials/user/06-take-minutes.md @@ -1,35 +1,60 @@ --- sidebar_position: 6 title: Take and publish the minutes -description: Step-by-step guide to take and publish the minutes +description: Generate a minutes draft from the meeting record, get it signed, and publish it. --- # Take and publish the minutes -Step-by-step guide to take and publish the minutes +Turn the meeting record — agenda, motions, votes, decisions — into a minutes document, take it through review and signing, then publish (and, for a general assembly, distribute) it. ## Goal -`{{TODO: write the goal — what the reader will have accomplished by the end}}` +By the end you will have a minutes document for the meeting that has moved from *draft* through *review* to *approved/published*, with the agreed signers recorded, and the action items it contains extracted. ## Prerequisites -`{{TODO: list prerequisites — Decidesk installed, a configured workspace/register, the right role, etc.}}` +- A meeting that has happened — agenda items handled, any votes closed, decisions published (see [Run a vote](05-run-vote.md)). +- Secretary (or whoever the body's workflow names) — that role drives the minutes lifecycle. +- The list of people who must sign the minutes (chair, secretary, …) per the body's rules. ## 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 meeting and go to **Minutes** in the navigation, then create a minutes record for the meeting — or use **Generate draft** to have Decidesk assemble a first draft from the meeting record (agenda items, motions, voting results, decisions). + + ![Generate a minutes draft](/screenshots/tutorials/user/06-take-minutes-01.png) + +2. Edit the draft — tidy the wording, add discussion notes, confirm the recorded decisions are right. The minutes detail page has a **Signers** tab and an **Audit trail**. + + ![Minutes detail with the draft](/screenshots/tutorials/user/06-take-minutes-02.png) + +3. On the **Signers** tab, set who must sign — typically the chair and the secretary. Then **submit for approval**: the minutes move to *review* and the dashboard's *Minutes awaiting approval* tile picks them up. + + ![Signers tab on the minutes](/screenshots/tutorials/user/06-take-minutes-03.png) + +4. The signers approve. When the last required signature is in, the minutes transition to *approved*. **Publish** them — the minutes become the official record of the meeting. + + ![Approved and published minutes](/screenshots/tutorials/user/06-take-minutes-04.png) + +5. **Extract action items** from the minutes — Decidesk pulls out the "X to do Y by Z" lines so they become tracked action items (see [Track decisions and action items](07-track-decisions.md)). For a general assembly (ALV), generate the ALV-format minutes and **distribute** them to members. + + ![Action items extracted from the minutes](/screenshots/tutorials/user/06-take-minutes-05.png) ## Verification -`{{TODO: how the reader confirms it worked}}` +The minutes show in the **Minutes** list with `lifecycle` *approved* (or *published*) and a version number, the **Signers** tab lists everyone who signed, the **Audit trail** records the submit/approve/publish steps, and the extracted action items appear under **Action items**. ## Common issues | Symptom | Fix | |---|---| -| `{{TODO}}` | `{{TODO}}` | +| **Generate draft** produces a thin draft | It only includes what's recorded — make sure agenda items, votes, and decisions were captured in the meeting before generating. | +| Minutes stuck in *review* | A required signer hasn't approved yet — check the **Signers** tab for the outstanding signature. | +| Action item extraction misses items | The extractor looks for clear assignment phrasing; rephrase vague lines, or add the action items by hand from **Action items → Add Item**. | +| No "distribute" option | Distribute is for ALV (general assembly) minutes — generate the ALV-format minutes first. | ## Reference -`{{TODO: link related docs — feature pages, OpenRegister schema, ADRs}}` +- [Track decisions and action items](07-track-decisions.md) — follow up the action items these minutes produced. +- [Schedule a meeting and build the agenda](02-schedule-meeting.md) — the agenda the minutes are built from. +- [Ask the AI companion about a meeting](08-ai-companion.md) — ask the companion to summarise what the minutes recorded. diff --git a/docs/tutorials/user/07-track-decisions.md b/docs/tutorials/user/07-track-decisions.md index 87f4eed5a..c2462c798 100644 --- a/docs/tutorials/user/07-track-decisions.md +++ b/docs/tutorials/user/07-track-decisions.md @@ -1,35 +1,59 @@ --- sidebar_position: 7 title: Track decisions and action items -description: Step-by-step guide to track decisions and action items +description: Find a published decision, follow its action items to completion, and read the engagement and completion-rate figures. --- # Track decisions and action items -Step-by-step guide to track decisions and action items +Once a vote closes and minutes publish, Decidesk keeps the trail open — the decision, the action items it spawned, who owns them, and whether they got done. ## Goal -`{{TODO: write the goal — what the reader will have accomplished by the end}}` +By the end you will know how to find a decision, see and update the action items linked to it, and read the completion-rate and engagement figures Decidesk derives from them. ## Prerequisites -`{{TODO: list prerequisites — Decidesk installed, a configured workspace/register, the right role, etc.}}` +- At least one published decision (see [Run a vote](05-run-vote.md)) and ideally minutes with extracted action items (see [Take and publish the minutes](06-take-minutes.md)). +- For updating an action item's status: being its assignee, or having edit rights on the body's work. ## 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 **Decisions** in the navigation. Each row shows the decision title, **outcome** (carried / rejected), **decision date**, and **publication** status; a *Publish* action handles any decision still pending publication. + + ![Decisions list](/screenshots/tutorials/user/07-track-decisions-01.png) + +2. Open a decision. Its sidebar has an **Overview** (the motion text, the tally, the legal basis), an **Action items** tab, and an **Audit trail**. + + ![Decision detail page](/screenshots/tutorials/user/07-track-decisions-02.png) + +3. On the **Action items** tab — or under **Action items** in the navigation — see what the decision committed someone to: a **title**, an **assignee**, a **due date**, and a **status** (open, in progress, done). The assignee updates the status as the work moves. + + ![Action items linked to a decision](/screenshots/tutorials/user/07-track-decisions-03.png) + +4. Back on the dashboard, the **Open action items** tile counts everything still open or in progress; the action-item analytics give completion rates per body and a *my items* view of what's assigned to you. + + ![Dashboard with the open-action-items tile](/screenshots/tutorials/user/07-track-decisions-04.png) + +5. Check **Engagement** for the meeting-level figures Decidesk derives — speaking time and an engagement score per participant — and **Tasks** for delegated follow-ups that aren't formal action items. + + ![Engagement and tasks views](/screenshots/tutorials/user/07-track-decisions-05.png) ## Verification -`{{TODO: how the reader confirms it worked}}` +A published decision shows in **Decisions** with its outcome, its **Action items** tab lists the linked items with assignees and statuses, and the dashboard's *Open action items* tile and the completion-rate figures move when you mark an item *done*. ## Common issues | Symptom | Fix | |---|---| -| `{{TODO}}` | `{{TODO}}` | +| A decision shows as not published | Use the *Publish* action on the **Decisions** list — publishing enforces the body's access rules server-side. | +| An action item has no assignee | Edit it and set an assignee, otherwise it won't show in anyone's *my items* and the completion rate can't account for it. | +| Completion rate looks wrong | It only counts action items with a status set — items left in the default state skew it; make sure assignees keep statuses current. | +| Engagement figures are empty | Engagement records are written from the live meeting (speaking turns); a meeting run without the live view won't have them. | ## Reference -`{{TODO: link related docs — feature pages, OpenRegister schema, ADRs}}` +- [Run a vote](05-run-vote.md) — where decisions come from. +- [Take and publish the minutes](06-take-minutes.md) — where most action items are extracted. +- [Ask the AI companion about a meeting](08-ai-companion.md) — ask "what action items are due this week?" instead of clicking through. diff --git a/docs/tutorials/user/08-ai-companion.md b/docs/tutorials/user/08-ai-companion.md index 53d0408a2..e0fda80fc 100644 --- a/docs/tutorials/user/08-ai-companion.md +++ b/docs/tutorials/user/08-ai-companion.md @@ -1,35 +1,55 @@ --- sidebar_position: 8 title: Ask the AI companion about a meeting -description: Step-by-step guide to ask the AI companion about a meeting +description: Use the Nextcloud AI Chat Companion to query Decidesk — meetings, action items, decisions — in plain language. --- # Ask the AI companion about a meeting -Step-by-step guide to ask the AI companion about a meeting +Decidesk exposes its governance data to the Nextcloud AI Chat Companion, so you can ask "what action items are due this week?" or "summarise the last council meeting" instead of clicking through lists. ## Goal -`{{TODO: write the goal — what the reader will have accomplished by the end}}` +By the end you will know how to open the AI companion, ask it a Decidesk question, and read the answer — including the source objects it cites. ## Prerequisites -`{{TODO: list prerequisites — Decidesk installed, a configured workspace/register, the right role, etc.}}` +- The Nextcloud **AI Chat Companion** available on your instance (hydra ADR-034), with a model configured. +- The **OpenRegister** app at a version that publishes the `IMcpToolProvider` interface — Decidesk registers its tools automatically against it, no admin step. +- Some Decidesk data to ask about (meetings, decisions, action items). ## 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 AI Chat Companion (the chat panel in the Nextcloud sidebar, or the companion app). It greets you with a chat box. + + ![AI companion chat panel](/screenshots/tutorials/user/08-ai-companion-01.png) + +2. Ask a Decidesk question in plain language — for example *"What action items are open and due this week?"* The companion calls Decidesk's `action-items` tool behind the scenes. + + ![Asking the companion about action items](/screenshots/tutorials/user/08-ai-companion-02.png) + +3. Read the answer. It lists the items with assignees and due dates, and — because every Decidesk tool returns a `sources[]` array — it cites which objects it used, so you can open them directly. + + ![Companion answer with cited sources](/screenshots/tutorials/user/08-ai-companion-03.png) + +4. Follow up — *"summarise the last council meeting"*, *"which motions are still admissible but not voted?"*, *"start the next board meeting"*. Each call is argument-validated and authorisation-checked against the objects before it runs, so the companion only ever shows you what you're allowed to see. + + ![Follow-up question to the companion](/screenshots/tutorials/user/08-ai-companion-04.png) ## Verification -`{{TODO: how the reader confirms it worked}}` +The companion returns a relevant answer (not "I don't have access to that"), the answer cites Decidesk objects you can click through to, and an action that changes state (e.g. "start the meeting") only succeeds if you have the right role. ## Common issues | Symptom | Fix | |---|---| -| `{{TODO}}` | `{{TODO}}` | +| Companion says it can't reach Decidesk | OpenRegister must be at the release that publishes `IMcpToolProvider`; if it isn't, the tools are simply unavailable and the rest of Decidesk still works. | +| Companion answer omits sources | Re-ask — every Decidesk tool returns sources; an answer without them usually means the model didn't actually call the tool. Be specific ("list the open action items"). | +| "Not authorised" on an action | The authorisation check runs before any business logic — you don't have the role that action requires for that body. | +| `/api/chat/health` 404 in the browser console | Harmless — that's the companion probing whether the chat back end is wired up; Decidesk's own pages don't depend on it. | ## Reference -`{{TODO: link related docs — feature pages, OpenRegister schema, ADRs}}` +- [MCP Tools (AI Chat Companion integration)](../../features/mcp-tools.md) — the five tools Decidesk exposes and how each call is validated and authorised. +- [Track decisions and action items](07-track-decisions.md) — the data the companion answers from. diff --git a/package.json b/package.json index b510a8e30..5cf5cd826 100644 --- a/package.json +++ b/package.json @@ -13,7 +13,9 @@ "lint": "eslint src", "lint-fix": "npm run lint -- --fix", "stylelint": "stylelint src/**/*.vue src/**/*.scss src/**/*.css", - "stylelint-fix": "stylelint src/**/*.vue src/**/*.scss src/**/*.css --fix" + "stylelint-fix": "stylelint src/**/*.vue src/**/*.scss src/**/*.css --fix", + "test:e2e": "playwright test", + "test:e2e:docs": "playwright test --project docs-capture" }, "browserslist": [ "extends @nextcloud/browserslist-config" @@ -51,6 +53,7 @@ "@nextcloud/eslint-plugin": "^2.2.1", "@nextcloud/stylelint-config": "^2.4.0", "@nextcloud/webpack-vue-config": "^6.0.1", + "@playwright/test": "^1.59.1", "@typescript-eslint/eslint-plugin": "^7.18.0", "@typescript-eslint/parser": "^7.18.0", "@vue/eslint-config-typescript": "^13.0.0", diff --git a/playwright.config.ts b/playwright.config.ts index 36a47f10b..4f42a294c 100644 --- a/playwright.config.ts +++ b/playwright.config.ts @@ -18,14 +18,18 @@ * `docs/static/screenshots/tutorials/{user,admin}/`. * * Point at a running Nextcloud with NEXTCLOUD_URL (default - * http://localhost:8080). Authentication / storage-state wiring is - * left for the team to add when the first real e2e spec lands. + * http://localhost:8080). `globalSetup` logs in once (admin/admin by + * default; override with NC_ADMIN_USER / NC_ADMIN_PASS) and persists + * the session to `tests/e2e/.auth/admin.json`; every spec reuses it via + * `use.storageState`. */ import { defineConfig, devices } from '@playwright/test' +import * as path from 'path' export default defineConfig({ testDir: './tests/e2e', + globalSetup: path.resolve(__dirname, 'tests/e2e/global-setup.ts'), timeout: 30_000, expect: { timeout: 10_000 }, fullyParallel: false, @@ -39,6 +43,7 @@ export default defineConfig({ use: { baseURL: process.env.NEXTCLOUD_URL || 'http://localhost:8080', + storageState: path.resolve(__dirname, 'tests/e2e/.auth/admin.json'), trace: 'on-first-retry', screenshot: 'only-on-failure', }, diff --git a/src/App.vue b/src/App.vue index 223aa3077..82265ae8a 100644 --- a/src/App.vue +++ b/src/App.vue @@ -15,6 +15,7 @@ :custom-components="customComponents" :page-types="pageTypes" app-id="decidesk" + data-testid="app-root" :translate="translateForApp" :permissions="permissions">