Publish DevRunbook source

docs/52-usability-recovery-roadmap.md

@@ -0,0 +1,123 @@
+# 52 — Usability recovery roadmap
+
+## Why this roadmap exists
+
+The live visual audit on 2026-07-30 found that the technical release gates in
+roadmap 51 were satisfied, while the production interface was still too dense,
+too technical and inconsistent in Dutch. This roadmap therefore governs the
+next product release. Earlier security, integrity and deterministic rendering
+contracts remain mandatory.
+
+The release is outcome-gated. A phase is complete only after its checks run on
+the Unraid deployment candidate and its evidence is recorded in
+`CURRENT_STATE.md`.
+
+## Baseline findings
+
+- The interface mixes Dutch and English in navigation, headings and actions.
+- The mobile library and project list create pages over ten thousand pixels
+  tall and put filters before the primary content.
+- The Start action bar obscures content on a phone.
+- Several mobile header controls are smaller than 44 by 44 CSS pixels.
+- Task and project details expose implementation terminology before the user
+  understands the outcome.
+- Generic labels such as More and Management do not describe their destination.
+- Empty task history does not help the user take the next useful action.
+
+## Phase A — Readable foundation
+
+Outcome: every primary screen has one clear purpose, consistent language and a
+stable information hierarchy.
+
+- use task, project and result as the default user vocabulary;
+- localize the authenticated shell, commands, primary pages, status and errors;
+- assign a unique browser title to every primary route;
+- keep expert and governance terminology behind contextual disclosure;
+- use one primary action per page header and demote secondary actions;
+- establish a readable measure, spacing scale and minimum 44-pixel touch target.
+
+Gate: Start, Tasks, Projects and Task library are understandable in Dutch at
+390, 768 and 1440 pixels without mixed-language primary controls, overlap or
+horizontal scrolling.
+
+## Phase B — Two-step task creation and library
+
+Outcome: a first-time user can choose a project, describe the desired result
+and generate a governed task without understanding internal platform concepts.
+
+- keep the default flow to project plus task;
+- show a short, plain-language review of scope, protection and success;
+- make advanced settings optional and collapsed;
+- collapse library filters by default, especially on mobile;
+- render results progressively rather than as an unbounded page;
+- make task cards describe outcome first and technical evidence second;
+- provide actionable zero-result and validation recovery.
+
+Gate: representative beginner tasks complete with project plus task, no raw
+schema keys are visible, and the primary mobile action never covers content.
+
+## Phase C — Projects and task history
+
+Outcome: projects and generated tasks are easy to find, compare and resume.
+
+- add search, useful sort and compact project rows;
+- show connection freshness and action required in ordinary language;
+- make project overview the default, with technical profile as a secondary tab;
+- rename Run Pack and run terminology in the primary UI to task and result;
+- add useful empty states, filters and status summaries to task history;
+- preserve immutable historical output and exact profile/version evidence.
+
+Gate: a target project is findable in a 500-project fixture using keyboard or
+touch, stale/error states have a clear recovery action, and empty task history
+links directly to creating a first task.
+
+## Phase D — Accessibility, responsive behavior and release proof
+
+Outcome: the simplified product is independently usable and operationally safe.
+
+- verify keyboard order, focus visibility, dialogs, drawers and error focus;
+- verify 200% zoom, reflow, reduced motion and light/dark contrast;
+- run Axe on all critical authenticated flows with zero serious or critical
+  findings;
+- measure mobile target sizes and prevent nested page scrolling;
+- run end-to-end browser journeys against the Unraid release candidate;
+- run format, lint, typecheck, unit, integration, security and production build;
+- rehearse restart and persistence, then deploy exactly one healthy DockerMan
+  container reachable on the LAN with the configured icon.
+
+Gate: all required suites execute rather than skip, critical browser flows pass
+at 390, 768 and 1440 pixels with no console errors, and production health and
+persistence checks pass after restart.
+
+## Delivery order
+
+1. Phase A shell, language, metadata and mobile readability.
+2. Phase B Start and Task library.
+3. Phase C Projects, project detail and Tasks.
+4. Phase D accessibility, full qualification and production deployment.
+
+Each phase is committed separately when practical. No release tag is created
+without explicit operator approval.
+
+## Follow-up closure — 2026-08-01
+
+The cross-role follow-up audit closes the recovery release for primary user
+journeys. Shared shell controls, account/security, role labels, denials and
+recovery actions are consistently localized. Account routes inherit useful
+navigation commands, viewer-only sessions no longer advertise write-only
+composition, and empty viewer workspaces explain the required editor/owner
+action.
+
+Evidence was produced from the exact all-in-one candidate on Unraid: 36/36
+PostgreSQL integration tests, the full repository verify/security/audit gate,
+17/17 focused Chromium/Axe scenarios, owner/editor/viewer browser journeys,
+390-pixel mobile and 200%-equivalent reflow, with no horizontal overflow or
+console errors.
+
+The roadmap does not claim a multi-workspace switcher, localized public
+onboarding or a plain-language rewrite of canonical expert authoring contracts.
+The current application deliberately selects one deterministic authorized
+membership; first-run setup, login and invitation acceptance remain English;
+and repository-profile and integration authoring remain expert surfaces.
+Implementing these requires separate product, localization and authorization
+milestones rather than a cosmetic shell change.