PBI-58: Developer manual + in-app /manual page (#148)

* docs(PBI-58): add developer manual chapters under docs/manual/ Adds a 7-file English-language manual targeted at new human contributors: index, overview, statuses & transitions (with mermaid state diagrams), git workflow, MCP integration, docker, and troubleshooting. The manual is the *map* — it cross-references existing runbooks/ADRs/architecture docs rather than duplicating their content. Regenerates docs/INDEX.md and validates with check-doc-links.mjs. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(PBI-58): add markdown rendering deps + manual:build script Adds mermaid, rehype-slug, rehype-autolink-headings for the in-app /manual page. Wires manual:build into prebuild so production builds always regenerate the chapter TOC. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(PBI-58): codegen script for in-app manual TOC scripts/build-manual.mjs walks docs/manual/, parses YAML front-matter, strips it from the body, and emits lib/manual.generated.ts with a typed ManualEntry[] containing slug, title, description, filePath, and the embedded markdown body. Pure Node 20, mirrors generate-docs-index.mjs. Inlining the markdown at build time keeps runtime serverless functions free of filesystem reads, which avoids whole-project NFT tracing. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(PBI-58): /manual route renders developer manual chapters in-app Catch-all route at app/(app)/manual/[[...slug]]/page.tsx with generateStaticParams covering every TOC entry. Server-side MarkdownView uses react-markdown with remark-gfm, rehype-slug, and rehype-autolink-headings; mermaid code blocks are routed to a client-only MermaidBlock that dynamic-imports mermaid on mount. ManualSidebar (client) reads the typed TOC and highlights the active chapter via usePathname. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(PBI-58): add Manual link to main nav bar Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-07 18:00:10 +02:00 · 2026-05-07 18:00:10 +02:00 · bd7478861b
commit bd7478861b
parent d750676f5e
19 changed files with 2239 additions and 105 deletions
--- a/docs/manual/01-overview.md
+++ b/docs/manual/01-overview.md
@ -0,0 +1,99 @@
+---
+title: "Overview"
+status: active
+audience: [contributor]
+language: en
+last_updated: 2026-05-07
+when_to_read: "First chapter — start here for the elevator pitch and project structure."
+---
+
+# 01 — Overview
+
+## What is Scrum4Me?
+
+Scrum4Me is a **desktop-first fullstack web app for solo developers and small Scrum teams** who manage multiple software projects in parallel. It models the Scrum hierarchy explicitly (Product → PBI → Story → Task), supports Sprints with split-screen drag-and-drop planning, and integrates Claude Code as an automated implementation worker — every result the agent produces is logged back into the originating story.
+
+The app is deployable to **Vercel + Neon** (default) and can run **fully local** via the worker container. A built-in demo user has read-only access; Product Owners add Developers by username, and those Developers gain write access to that product's stories, tasks, and sprints.
+
+## Entity hierarchy
+
+```mermaid
+flowchart TB
+  Product["Product<br/>(per repo)"]
+  Idea["Idea<br/>(pre-PBI staging)"]
+  PBI["PBI<br/>(Product Backlog Item)"]
+  Story["Story"]
+  Task["Task"]
+  Sprint["Sprint<br/>(cross-cutting)"]
+
+  Product --> Idea
+  Idea -.->|"AI-grilled & planned"| PBI
+  Product --> PBI
+  PBI --> Story
+  Story --> Task
+  Sprint -.->|"contains stories<br/>denormalised on tasks"| Story
+  Sprint -.-> Task
+```
+
+- **Product** — one row per repo. `repo_url`, `definition_of_done`, members.
+- **Idea** — pre-PBI staging entity introduced in M12. Goes through `IDEA_GRILL` (AI Q&A loop) and `IDEA_MAKE_PLAN` jobs to produce a structured plan that can be turned into a PBI tree.
+- **PBI** — a Product Backlog Item. Has `priority` (1–4) and `sort_order` (float, see [`docs/patterns/sort-order.md`](../patterns/sort-order.md)).
+- **Story** — a unit of value under a PBI; has acceptance criteria. Lives in the backlog (`OPEN`) until added to a sprint.
+- **Task** — the smallest unit; has an `implementation_plan` consumed by the Claude worker. `sprint_id` is denormalised from the parent story for query efficiency.
+- **Sprint** — cross-cutting time-box. Stories are added to a sprint; tasks inherit `sprint_id`. Sprint execution has two modes: `PER_TASK` and `SPRINT_BATCH` — see [`docs/architecture/sprint-execution-modes.md`](../architecture/sprint-execution-modes.md).
+
+For status lifecycles of each entity, see [02 — Statuses & Transitions](./02-statuses-and-transitions.md).
+
+## Stack
+
+| Layer | Technology |
+|---|---|
+| Framework | Next.js 16 (App Router) + React 19 |
+| Language | TypeScript (strict) |
+| Styling | Tailwind CSS + shadcn/ui + Material Design 3 tokens via [`app/styles/theme.css`](../../app/styles/theme.css) |
+| Client state | Zustand + dnd-kit |
+| Database | Prisma v7 + PostgreSQL (Neon) |
+| Auth | iron-session + bcryptjs |
+| Utilities | Zod, Sonner, Sharp, Vercel Analytics |
+| Hosting | Vercel (app), Neon (DB), Mac/NAS Docker (worker) |
+
+For the rationale behind each choice and the technologies we explicitly **don't** use, see [`docs/architecture/overview.md`](../architecture/overview.md).
+
+## Repository layout
+
+```
+Scrum4Me/
+├── app/                    # Next.js App Router routes
+│   ├── (app)/              # authenticated desktop UI
+│   ├── (auth)/             # login, register, demo
+│   ├── (mobile)/           # /m/* mobile shell (3 screens)
+│   ├── api/                # REST route handlers (Claude integration)
+│   └── styles/             # MD3 token CSS
+├── components/             # shared UI components
+├── lib/                    # server/client utilities
+│   └── task-status.ts      # the ONLY place DB↔API enum mapping happens
+├── prisma/                 # schema + migrations
+├── docs/                   # this manual + ADRs, runbooks, patterns, specs
+└── scripts/                # codegen, seeders, link checkers
+```
+
+The `*-server.ts` filename suffix marks server-only modules (DB, Node APIs). They must never be imported into a client component — see the hardstop in [`CLAUDE.md`](../../CLAUDE.md#hardstop-regels).
+
+For a deeper structural breakdown including stores, realtime channels, and the job queue, see [`docs/architecture/project-structure.md`](../architecture/project-structure.md).
+
+## Glossary refresh
+
+A few terms used throughout this manual that often differ from "generic Scrum" usage:
+
+- **PBI** — Product Backlog Item. Not "Feature" or "Epic".
+- **Story** — A unit of work under a PBI. Not "Ticket" or "Issue".
+- **Sprint Goal** — The narrative for a sprint. Not "Objective".
+- **Worker** — A Claude Code agent claiming jobs from the Scrum4Me queue (M13).
+- **Demo user** — A read-only built-in user; writes return `403`. See [`docs/adr/0006-demo-user-three-layer-policy.md`](../adr/0006-demo-user-three-layer-policy.md).
+- **Idea** — Pre-PBI staging artefact (M12). Has its own state machine; see [02](./02-statuses-and-transitions.md#idea).
+
+The complete glossary lives at [`docs/glossary.md`](../glossary.md).
+
+## What's next
+
+→ [02 — Statuses & Transitions](./02-statuses-and-transitions.md) covers how each entity moves through its lifecycle, with state-machine diagrams.