docs: fill journeydoc tutorial prose

docs/tutorials/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Tutorials",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Tutorials",
+    "description": "Step-by-step walkthroughs for everyday tasks. The user track covers individual workflows; the admin track covers org-wide configuration."
+  }
+}

docs/tutorials/admin/01-configure-default-columns.md

@@ -0,0 +1,64 @@
+---
+sidebar_position: 1
+title: Configure default project columns
+description: Set the columns every new Planix project starts with — what the team's lane structure looks like, with optional WIP limits.
+---
+
+# Configure default project columns
+
+Every new Planix project is seeded with a default column set on creation. Out of the box that's *To Do*, *In Progress*, *Review*, *Done* — four columns, no WIP limits. If your team uses a different flow (you have a *Blocked* lane, or a *Ready to deploy* lane, or you want WIP limits on the active columns), set the default here once and every new project picks it up.
+
+## Goal
+
+By the end the instance will have a default-column set tailored to your team's flow, and a freshly-created test project will use that set.
+
+## Prerequisites
+
+- Admin on the Nextcloud instance.
+- The **Planix** app installed and enabled with the Planix register initialised (see [Manage Planix settings](03-admin-settings.md)).
+- A view on what the team's actual lane structure looks like — read the columns off your current real project board if you have one, or talk it through with the team.
+
+## Steps
+
+1. Open **Settings → Administration → Planix** and scroll to the **Default Project Configuration** section.
+
+   ![Default Project Configuration section](/screenshots/tutorials/admin/01-configure-default-columns-01.png)
+
+2. Review the current default columns. Each row shows **order**, **title**, **colour**, and **WIP limit** (empty if unset). The default Planix install ships *To Do*, *In Progress*, *Review*, *Done*.
+
+   ![Current default columns](/screenshots/tutorials/admin/01-configure-default-columns-02.png)
+
+3. Edit the columns. **Add column** appends a new row; the **drag handle** reorders; the **trash** removes a column; the **WIP limit** field accepts an integer or stays blank (no limit). Use distinct colours so the kanban board reads at a glance.
+
+   ![Edited default columns — Blocked + WIP limits](/screenshots/tutorials/admin/01-configure-default-columns-03.png)
+
+4. **Save**. The change applies to **projects created after the save**; existing projects keep the column set they were created with. To migrate an existing project, edit its columns by hand on the board.
+
+   ![Settings saved confirmation](/screenshots/tutorials/admin/01-configure-default-columns-04.png)
+
+5. Verify. Create a test project (see [Create your first project](../user/02-create-project.md)). Its board should open with exactly the column set you configured, in the right order, with the right colours and WIP limits.
+
+   ![New project picks up the new defaults](/screenshots/tutorials/admin/01-configure-default-columns-05.png)
+
+## Verification
+
+The **Default Project Configuration** section shows the column set you saved. A new project created after the save uses that set verbatim; an old project still uses its original set. The WIP limits, if you set any, appear in the new project's column headers.
+
+## Common issues
+
+| Symptom | Fix |
+|---|---|
+| Save action does nothing | The save endpoint returned a 4xx — check the Nextcloud log; usually the user-rights check (only admins can save). |
+| New project still uses the old defaults | The save didn't land — reload **Settings → Administration → Planix** and check the column rows match what you intended. |
+| Existing project doesn't pick up the new defaults | By design — default columns only apply on project creation. Edit existing projects' columns manually on the board. |
+| Column count limit | No fixed cap, but kanban best practice is 4–7 columns; more than that and the board scrolls horizontally on a 1280px viewport. |
+| Colour picker is empty | Brand-token CSS variables didn't load — graceful-restart Apache or hard-reload the settings page. |
+| Screenshots may be missing | App not yet installed in the test environment; rerun `npm run test:e2e:docs` once it is. |
+
+## Reference
+
+- [Create your first project](../user/02-create-project.md) — what users see after these defaults take effect.
+- [Work with the kanban board](../user/03-work-with-boards.md) — where the columns live.
+- [Manage labels](02-manage-labels.md) — the other big admin task.
+- [Kanban board reference](../../features/kanban-board.md) — column model.
+- [Admin settings reference](../../features/admin-settings.md) — the full admin surface.

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

@@ -0,0 +1,63 @@
+---
+sidebar_position: 2
+title: Manage labels
+description: Maintain the instance-wide label catalogue — colour-coded tags that any project's tasks can be tagged with.
+---
+
+# Manage labels
+
+Labels in Planix are **app-wide**, not per-project. Every label lives in the same catalogue, available across every project. The intent: cross-project categorisation — *bug*, *feature*, *security*, *tech-debt*, *blocked-by-vendor* — uses the same vocabulary everywhere so dashboards and reports compose cleanly.
+
+## Goal
+
+By the end the instance will have a label catalogue tailored to how the team categorises work, with consistent colours so the kanban cards read at a glance.
+
+## Prerequisites
+
+- Admin on the Nextcloud instance.
+- The **Planix** app installed and enabled with the Planix register initialised (see [Manage Planix settings](03-admin-settings.md)).
+- A view on the team's category vocabulary — what kinds of work do you actually want to tag?
+
+## Steps
+
+1. Open **Settings → Administration → Planix** and scroll to the **Label Management** section.
+
+   ![Label Management section](/screenshots/tutorials/admin/02-manage-labels-01.png)
+
+2. Review the current labels. Each row shows **title**, **colour swatch**, and an **edit** / **delete** action. On a fresh install the catalogue is empty; on an upgraded install you'll see whatever labels someone has been adding ad hoc.
+
+   ![Current labels list](/screenshots/tutorials/admin/02-manage-labels-02.png)
+
+3. Add labels for the team's categories. Click **Add label**, type a **title** (e.g. *bug*), pick a **hex colour** (use the same colour family as the other labels in its category — red shades for blockers, green for completed-flavour, blue for normal flow). Save. Repeat for each category.
+
+   ![Adding a new label](/screenshots/tutorials/admin/02-manage-labels-03.png)
+
+4. Edit an existing label. Click the **edit** action on a row, change the title or the colour, save. The change propagates to every task already tagged with it — the colour update is visible the next time those task cards render.
+
+   ![Editing a label](/screenshots/tutorials/admin/02-manage-labels-04.png)
+
+5. Delete a label. The **delete** action prompts a confirmation showing how many tasks currently carry the label. Deleting removes the label from every task; the tasks themselves stay. Use this to retire categories that no longer apply.
+
+   ![Delete confirmation with task count](/screenshots/tutorials/admin/02-manage-labels-05.png)
+
+## Verification
+
+The **Label Management** section lists the labels you added. Creating a task (see [Add and manage tasks](../user/04-manage-tasks.md)) shows your labels in the label picker. Editing a label's colour updates every card already tagged with it. Deleting a label removes it from every task that carried it.
+
+## Common issues
+
+| Symptom | Fix |
+|---|---|
+| Label picker on a task is still empty after adding labels here | Browser cache; reload the Planix app. Labels are read on app load through the labels store. |
+| Colour picker doesn't apply | Brand-token CSS isn't loaded — graceful-restart Apache or hard-reload. |
+| Delete shows `0 tasks affected` but the label is still on cards | Wait a tick — the task count is computed server-side; the next render reflects the actual state. |
+| Want per-project labels | Not supported — labels are intentionally app-wide so dashboards across projects compose. Use a label prefix (*proj-A-frontend*, *proj-B-frontend*) if you need project-scoping. |
+| Duplicate labels (same title, different colours) | Allowed but discouraged; users see a duplicate in the picker. Delete the one with fewer tasks; the other survives. |
+| Screenshots may be missing | App not yet installed in the test environment; rerun `npm run test:e2e:docs` once it is. |
+
+## Reference
+
+- [Add and manage tasks](../user/04-manage-tasks.md) — where users pick from this catalogue.
+- [Work with the kanban board](../user/03-work-with-boards.md) — label-based board filtering.
+- [Configure default project columns](01-configure-default-columns.md) — the parallel admin task.
+- [Admin settings reference](../../features/admin-settings.md) — the full admin surface.

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

@@ -0,0 +1,64 @@
+---
+sidebar_position: 3
+title: Manage Planix settings
+description: Open Planix's admin settings, confirm the version, initialise the OpenRegister register and schemas, and toggle the Procest bridge.
+---
+
+# Manage Planix settings
+
+Planix's admin settings page in the Nextcloud administration panel does three jobs: it reports the installed version with an *Update available* indicator, it shows whether the OpenRegister-backed register and schemas are initialised (and offers an **Initialize register** action when not), and it carries the per-instance feature toggles (default columns, labels, Procest bridge). This tutorial covers the version + register-initialisation parts; the column and label management each have their own page.
+
+## Goal
+
+By the end you will have confirmed the Planix version, run (or re-run) the register initialisation so all schemas land in OpenRegister, and reviewed the feature toggles so the rest of the admin surface (default columns, labels) and the Procest bridge are set as you want them.
+
+## Prerequisites
+
+- Admin on the Nextcloud instance.
+- The **OpenRegister** app installed and enabled, with at least one register available — Planix's initialiser creates its own register if one isn't there yet.
+
+## Steps
+
+1. Open **Settings → Administration → Planix**. The page opens with the **App version info** card at the top.
+
+   ![Planix admin settings — version section](/screenshots/tutorials/admin/03-admin-settings-01.png)
+
+2. Confirm the **Version**. The `CnVersionInfoCard` shows the installed Planix version and the connection status to OpenRegister. If a newer version is available on the Nextcloud App Store, an *Update available* indicator with a link is rendered. Use this to confirm Nextcloud loaded the version you expect after an install or upgrade.
+
+   ![Version info card](/screenshots/tutorials/admin/03-admin-settings-02.png)
+
+3. Scroll to the **OpenRegister Setup** card. It shows whether the Planix register and its eight schemas (project, column, task, task-comment, time-entry, label, member, settings) are initialised. On a fresh install the card displays **Initialize register**; click it to import the OpenAPI 3.0 register definition from `lib/Settings/planix_register.json` into OpenRegister.
+
+   ![OpenRegister Setup card](/screenshots/tutorials/admin/03-admin-settings-03.png)
+
+4. After the import succeeds, the card switches to *Register initialised* and lists each schema with a green tick. If the *Initialize register* action fails, the Nextcloud log will carry the underlying error — usually an OpenRegister version skew on the import API. Once both apps are on compatible versions, re-run.
+
+   ![Register initialised — schemas listed](/screenshots/tutorials/admin/03-admin-settings-04.png)
+
+5. Confirm the **Procest bridge** toggle (under the OpenRegister card) is set to your preference. Default is **on**: Planix tasks and projects accept Procest case UUIDs (`zaakUuid`, `caseReference`) and render deep-links into the Procest app when set (see [Link a task to a Procest case](../user/08-link-procest.md)). Switching it **off** disables the deep-linking; the metadata fields still exist as read-only.
+
+   ![Procest bridge toggle](/screenshots/tutorials/admin/03-admin-settings-05.png)
+
+## Verification
+
+The **App version info** card shows the installed version and (if applicable) the available update. The **OpenRegister Setup** card shows *Register initialised* with all schemas listed. The **Procest bridge** toggle reflects your choice. Opening the Planix app loads without error banners, project lists render, and **Create project** opens a populated form.
+
+## Common issues
+
+| Symptom | Fix |
+|---|---|
+| **OpenRegister Setup** card stuck on *Initialize register* even after clicking | The import is failing server-side — check the Nextcloud log for the Planix repair-step error. Stale OpenRegister / Planix version pair is the usual cause; align versions and re-run. |
+| Schemas listed but **Create project** fails with a schema error | The schema definitions don't match what the Planix Vue code expects — usually an upgrade where the register definition moved on but the JS bundle is stale. Hard-reload Planix; if that doesn't help, re-run the initialise. |
+| Procest bridge toggle missing | The toggle only renders when both Planix and Procest are detected — install Procest, reload settings, and the toggle appears. |
+| *Initialize register* succeeds but lists fewer schemas than expected | OpenRegister rejected some schemas (usually a duplicate-name conflict with another app); check the OpenRegister side — the conflict is logged. |
+| Version says "Up to date" but the dashboard layout is wrong | The webpack bundle is stale — graceful-restart Apache (or rebuild and reload). |
+| Screenshots may be missing | App not yet installed in the test environment; rerun `npm run test:e2e:docs` once it is. |
+
+## Reference
+
+- [Open Planix for the first time](../user/01-first-launch.md) — the user-facing check that the initialisation worked.
+- [Configure default project columns](01-configure-default-columns.md) — first big admin task after initialisation.
+- [Manage labels](02-manage-labels.md) — second one.
+- [Link a task to a Procest case](../user/08-link-procest.md) — what the Procest bridge unlocks.
+- [Admin settings reference](../../features/admin-settings.md) — the full admin surface and the underlying services.
+- [Register schemas reference](../../features/register-schemas.md) — what the initialise creates in OpenRegister.

docs/tutorials/admin/_category_.json

@@ -0,0 +1,11 @@
+{
+  "label": "Admin guide",
+  "position": 2,
+  "collapsible": true,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "title": "Admin guide",
+    "description": "Org-wide administration — default columns, labels, and the OpenRegister mapping that backs every project."
+  }
+}

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

@@ -0,0 +1,57 @@
+---
+sidebar_position: 1
+title: Open Planix for the first time
+description: Open Planix, find your way around the dashboard and navigation, and confirm the OpenRegister back end is connected.
+---
+
+# Open Planix for the first time
+
+A first look at Planix — the dashboard, the navigation, and how to confirm Planix is wired up to OpenRegister so projects, tasks, boards, and time entries can load.
+
+## Goal
+
+By the end you will have opened the Planix app, recognised the dashboard KPIs and the navigation, and confirmed that the OpenRegister back end is connected.
+
+## Prerequisites
+
+- A Nextcloud account on an instance where the **Planix** app is installed and enabled.
+- The **OpenRegister** app installed and enabled — Planix stores everything (projects, columns, tasks, time entries, labels) in OpenRegister, so it is a hard dependency.
+- The Planix register and its schemas initialised. An admin runs this once from **Settings → Administration → Planix** (see [Manage Planix settings](../admin/03-admin-settings.md)).
+
+## Steps
+
+1. Open the Nextcloud app menu in the top bar and pick **Planix**. You land on the **Dashboard**.
+
+   ![Planix dashboard](/screenshots/tutorials/user/01-first-launch-01.png)
+
+2. Read the four KPI cards — **Open tasks** (open or in_progress assigned to you), **Overdue tasks** (past their due date), **In Progress**, **Completed today**. On a fresh install they read `0`; they fill in as tasks are assigned and worked on. Click any card to jump straight to **My Work** with that filter applied.
+
+   ![Dashboard KPI cards](/screenshots/tutorials/user/01-first-launch-02.png)
+
+3. Below the KPIs you see **Recent projects** (the five most recently active projects you are a member of) and **Due this week** (tasks assigned to you with a due date in the next seven days, sorted by due date). New users with no projects see a *No projects yet* empty state with a **Create project** button.
+
+   ![Recent projects and Due this week](/screenshots/tutorials/user/01-first-launch-03.png)
+
+4. Open the left navigation. Top-level entries: **Dashboard**, **My Work**, **Projects**, **Timesheet**. Below the divider you have **Settings** (the per-user dialog, via the gear icon). The **Projects** entry takes you to the project list — empty on a fresh install.
+
+   ![Planix navigation](/screenshots/tutorials/user/01-first-launch-04.png)
+
+## Verification
+
+You are set up correctly when: the Planix dashboard renders without an error banner, the KPI cards display (zero counts are fine), the left navigation lists the entries above, and clicking **Projects** loads the project list — either with rows or a clean *No projects yet* empty state, not a load error.
+
+## Common issues
+
+| Symptom | Fix |
+|---|---|
+| "OpenRegister is not installed or enabled" banner | Install and enable the OpenRegister app, then reload Planix. |
+| KPI cards show `—` instead of `0` | The Planix register isn't initialised yet — an admin runs **Initialize register** from **Settings → Administration → Planix** (see [Manage Planix settings](../admin/03-admin-settings.md)). |
+| Planix 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). |
+| Screenshots may be missing | App not yet installed in the test environment; rerun `npm run test:e2e:docs` once it is. |
+
+## Reference
+
+- [Create a project](02-create-project.md) — the natural next step once the app loads.
+- [Your dashboard and My Work](07-my-work-and-dashboard.md) — what the KPI cards point at.
+- [Manage Planix settings](../admin/03-admin-settings.md) — register initialisation, version info.
+- [Dashboard & My Work reference](../../features/dashboard.md) — the underlying feature spec.