docs: AI-optimized docs restructure (Phases 1–8) (#61)

* docs(dialog-pattern): add generic entity-dialog spec

Introduceert docs/patterns/dialog.md als bron-of-truth voor elke
create/edit/detail-dialog in Scrum4Me, ongeacht het achterliggende
dataobject. Bevat 14 secties: uitgangspunten, stack, component-
architectuur, layout, validatie, drielaagse demo-policy, submission,
dialog-gedrag, theming, footer, triggers/URL-state, per-entiteit
profile-template, out-of-scope, en een verificatie-checklist.

Registreert het patroon in CLAUDE.md "Implementatiepatronen"-tabel
zodat Claude (en mensen) de spec verplicht raadplegen voor elke
nieuwe dialog.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(dialog-pattern): convert task spec + add pbi/story entity-profiles

Reduceert docs/scrum4me-task-dialog.md van 507 naar ~140 regels: alle
gedeelde regels verhuisd naar docs/patterns/dialog.md, dit document
bevat nu alleen Task-specifieke velden, URL-pattern, status-veld,
server actions, triggers en bewuste out-of-scope-keuzes.

Voegt twee nieuwe entity-profielen toe voor bestaande dialogen:
- docs/scrum4me-pbi-dialog.md (PbiDialog: state-based, code+title-rij,
  PbiStatusSelect, geen delete in v1)
- docs/scrum4me-story-dialog.md (StoryDialog: state-based, header met
  status/priority badges, inline activity-log, demo-readonly-fallback,
  inline-delete-confirm i.p.v. AlertDialog)

Beide profielen documenteren expliciet de "Bekende gaps t.o.v.
generieke spec" zodat opvolgende PR's de afwijkingen kunnen
rechtzetten of bewust kunnen accorderen.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* Added pdevelopment docs

* docs(plans): add docs-restructure plan for AI-optimized lookup

Audit of existing 39 doc files (~10.700 lines) and a phased restructure
proposal aimed at minimising the tokens an AI agent has to read to find
the right reference. Captures resolved decisions on language (English),
ADR template (Nygard default with MADR escape-hatch), index generator
(node script), and folder taxonomy. Proposal status — fase 1 to follow.

* docs(adr): add ADR scaffolding (templates, README, meta-ADR)

Set up docs/adr/ as the canonical home for architecture decisions:

- templates/nygard.md — default four-section format (Status, Context,
  Decision, Consequences) for one-way-door decisions.
- templates/madr.md — MADR v4 with YAML front-matter and explicit
  Considered Options for decisions where rejected alternatives matter.
- README.md — naming convention (NNNN-kebab-case), template-selection
  guidance (Nygard default; MADR for auth, queue mechanics, agent
  integration), status lifecycle, and ADR roster.
- 0000-record-architecture-decisions.md — meta-ADR establishing the
  practice itself, in Nygard format.

Backfilling existing implicit decisions (base-ui-over-radix, float
sort_order, demo-user three-layer policy, etc.) is fase 6 of the
docs-restructure plan.

* feat(docs): add docs index generator + initial INDEX.md

scripts/generate-docs-index.mjs walks docs/**/*.md, parses YAML
front-matter (or first H1 fallback) and a Nygard-style ## Status
section, then writes docs/INDEX.md with grouped tables for ADRs,
Specs, Plans (with archive subsection), Patterns, and Other.

Pure Node 20 (no external deps); idempotent — running it twice
produces byte-identical output. Excludes adr/templates/, the ADR
README, INDEX.md itself, and any *_*.md sidecar file.

Wire-up:
- package.json: docs:index → node scripts/generate-docs-index.mjs

Initial run indexed 35 docs across the existing structure; the
generated INDEX.md is committed so the table is reviewable in the
PR before hooking generation into a pre-commit step.

* chore: ignore Obsidian vault and personal sidecar files

Add .obsidian/ (Obsidian vault config) and _*.md (personal sidecar
notes) to .gitignore so the docs/ tree can serve as canonical source
of truth while still being usable as an Obsidian vault for personal
authoring. The docs index generator already excludes the same _*.md
pattern from INDEX.md.

* docs(plans): add PBI bulk-create spec for docs-restructure

Machine-parseable spec for an executor that calls the scrum4me MCP
(create_pbi → create_story → create_task) to seed the docs-restructure
work into the DB.

- Section 1 (Context) is the PBI description; serves as task-context
  via mcp__scrum4me__get_claude_context.
- Section 2 lists the 6 resolved decisions (English, MD3+styling
  merged, solo-paneel merged, .Plans archived, Nygard ADR default,
  node index script).
- Section 3 records what already shipped on this branch so the
  executor doesn't duplicate the ADR scaffolding or index generator.
- Section 4 carries the structured YAML graph: 1 PBI, 8 stories
  (one per phase), 39 tasks. product_id is REPLACE_ME — fill before
  running.
- YAML validated with PyYAML; field schema sanity-checked.

* docs(junk-cleanup): remove stub patterns/test.md

* docs(junk-cleanup): archive .Plans/ to docs/plans/archive/

* docs(front-matter): add YAML front-matter to docs/ root

* docs(front-matter): add YAML front-matter to patterns/

* docs(front-matter): add YAML front-matter to plans + agent files

* docs(index): regenerate INDEX.md after front-matter pass

* docs(naming): drop scrum4me- prefix from doc filenames

* docs(naming): lowercase API.md and MD3 filenames

* docs(naming): rename plan file to kebab-case ASCII

* docs(naming): rename middleware.md to proxy.md (next 16)

* docs(naming): polish CLAUDE.md doc-index after renames

* docs(taxonomy): scaffold topical folders under docs/

* docs(taxonomy): move spec files into docs/specs/

* docs(taxonomy): move design/api/qa/backlog/assets into folders

* docs(taxonomy): move agent-instruction-audit into decisions/

* docs(split): break architecture.md into 6 topical files

* docs(split): merge solo-paneel-spec into specs/functional.md

* docs(split): merge md3-color-scheme into design/styling

* docs(trim): extract branch/commit rules into runbook

* docs(trim): extract MCP integration into runbook

* docs(adr): add 0001-base-ui-over-radix

* docs(adr): add 0002-float-sort-order

* docs(adr): add 0003-one-branch-per-milestone

* docs(adr): add 0004-status-enum-mapping

* docs(adr): add 0005-iron-session-over-nextauth

* docs(adr): add 0006-demo-user-three-layer-policy

* docs(adr): add 0007-claude-question-channel-design

* docs(adr): add 0008-agent-instructions-in-claude-md + update README index

* docs(index): regenerate after ADR 0001-0008

* docs(glossary): add docs/glossary.md

* chore(docs): regenerate INDEX.md in pre-commit hook

* docs(readme): link INDEX + glossary + agent instructions

* feat(docs): add doc-link checker script

* chore(docs): wire docs:check-links and docs npm scripts

* ci(docs): block merge on broken doc links

* docs(links): fix broken cross-references after restructure

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/obsidian-authoring.md

@@ -0,0 +1,202 @@
+---
+title: Obsidian as Personal Authoring Layer
+status: active
+audience: maintainer, contributor
+language: en
+last_updated: 2026-05-02
+related:
+  - docs/adr/README.md
+  - scripts/generate-docs-index.mjs
+  - .gitignore
+---
+
+# Obsidian as Personal Authoring Layer
+
+Scrum4Me's documentation lives as plain Markdown under `docs/`. The canonical
+source of truth is the committed `.md` file — rendered on GitHub, read by
+agents (Claude Code, Codex) directly from the file system, and indexed by
+`scripts/generate-docs-index.mjs`.
+
+Note: the `mcp` server does **not** expose `docs/` content. Its
+20 tools serve database state (products, sprints, stories, tasks, jobs,
+questions) via Prisma. Documentation reaches the agent only through the
+file-system tools, so the canonical Markdown is the one and only channel.
+
+Obsidian is **not** a second source of truth. It is a personal authoring
+layer that you can opt into without changing what the repo or the agent
+sees. This document records the conventions that keep both views consistent.
+
+## Why an authoring layer at all
+
+A canonical `0003-job-claim-strategy.md` is short, declarative, and final.
+The thinking that produced it — alternatives weighed, links followed, half-
+ideas — is messy and personal. Forcing that into the committed file inflates
+ADRs and dilutes the signal future readers (human or agent) need.
+
+Obsidian gives you a place to keep the thinking next to the artefact without
+polluting it: graph view, backlinks, properties, scratch notes. The
+`.gitignore` rules below ensure none of that crosses the repo boundary.
+
+## Vault setup
+
+Open the repo root as the vault, not just `docs/`.
+
+Reasons:
+
+- ADRs and patterns frequently reference code (`prisma/schema.prisma`,
+  `lib/task-status.ts`). Markdown links from a `docs/`-only vault cannot
+  resolve those targets; from a root vault they can.
+- The same vault then surfaces `README.md`, `CLAUDE.md`, and `AGENTS.md`
+  as nodes in the graph — useful when reasoning about agent instructions.
+- Per-developer Obsidian config lives in `.obsidian/` at the vault root,
+  which is already gitignored.
+
+### Two repos, two vaults
+
+The MCP server lives in a separate repo (`mcp`) with its own
+`CLAUDE.md`, tools, and tests. Open it as a **separate** Obsidian vault
+when you work there. Each `.obsidian/` directory is per-folder and stays
+gitignored on both sides; cross-repo notes belong in whichever vault you
+opened first, not in some shared third location.
+
+Schema-related ADRs are an exception: the MCP server consumes the
+Scrum4Me Prisma schema via the `vendor/scrum4me/` git submodule, so the
+*decision* about the schema belongs in this repo's `docs/adr/`. The
+mirror in `mcp` only needs an `npm run sync-schema` after the
+ADR lands here, not its own ADR.
+
+## Link style
+
+In Settings → Files & Links:
+
+- **Use [[Wikilinks]]** → off
+- **New link format** → Relative path to file
+- **Default location for new notes** → "Same folder as current file"
+
+Wikilinks would render as plain text on GitHub and are not parsed by the
+docs index generator. Stick to standard Markdown links (`./adr/0001-foo.md`)
+so the same file works in Obsidian, GitHub, and any agent reader.
+
+Obsidian still resolves Markdown links for backlinks and graph view, so you
+do not lose Obsidian's navigation features.
+
+## Front-matter is Obsidian Properties
+
+`scripts/generate-docs-index.mjs` reads a small set of YAML front-matter
+keys: `title`, `status`, `date` (or `last_updated`). Obsidian renders the
+exact same YAML block as its Properties panel.
+
+Practical consequence: flipping a plan from `proposal` to `accepted` in
+the Obsidian Properties UI and then running `npm run docs:index` is a
+complete workflow — no separate metadata store, no plugin needed.
+
+The repo's front-matter is intentionally flat (no nested objects, no lists
+beyond simple arrays) to stay parseable by the dependency-free generator.
+When adding fields, keep them flat.
+
+## Templates
+
+Two ADR templates ship in `docs/adr/templates/`:
+
+- `nygard.md` — default, for one-way-door decisions
+- `madr.md` — for decisions where rejected alternatives must be recorded
+
+Both use `{{curly braces}}` placeholders so they read naturally in any
+editor and so Codex and Claude Code can fill them mechanically.
+
+Two ways to use them from Obsidian:
+
+1. **Core Templates plugin** (recommended starting point). Settings →
+   Templates → Template folder location: `docs/adr/templates`. Then
+   `Cmd-P → Insert template → nygard` inserts the body verbatim. Fill
+   placeholders by hand.
+2. **Templater** (community plugin). If filling the next ADR number and
+   today's date by hand becomes a bottleneck, write a Templater wrapper
+   in a vault-only `_templates/` folder that reads `nygard.md` and
+   substitutes `<% tp.date.now("YYYY-MM-DD") %>` plus a computed next
+   number. Keep this wrapper out of git — it is personal tooling, not
+   part of the canonical convention.
+
+Do not modify the canonical templates to use Templater syntax. The
+placeholders must remain agent-readable.
+
+## Sidecar files for personal notes
+
+`.gitignore` already excludes `_*.md` and the docs index generator
+mirrors that exclusion (`/\/_[^/]+\.md$/`). Use this for any file that
+should stay personal:
+
+- `docs/adr/_draft-0003-job-claim-strategy.md` — alternatives, doubts,
+  links you considered before settling on the canonical ADR
+- `docs/plans/_questions-for-jp.md` — open questions you want to think
+  about but not raise yet
+- `_scratch.md` anywhere in the tree
+
+Workflow for an ADR:
+
+1. Brainstorm in `docs/adr/_draft-NNNN-…md` — free-form, link-heavy.
+2. When the decision is clear, copy the relevant prose into the canonical
+   `docs/adr/NNNN-…md`, applying the Nygard or MADR template.
+3. Run `npm run docs:index`.
+4. Commit only the canonical ADR (the sidecar is invisible to git).
+
+The sidecar can stay as a personal trail or be deleted — both are local-
+only choices.
+
+## Plugin recommendations
+
+Useful and low-risk:
+
+- **Outline** (core) — table of contents per file
+- **Backlinks**, **Outgoing Links** (core) — see what links to and from
+  the current document
+- **Linter** (community) — can enforce that ADRs have a `status` field
+  in front-matter
+
+Use with care:
+
+- **Dataview** — tempting to replace `INDEX.md` with a Dataview query.
+  Don't. The query renders blank on GitHub and is invisible to Claude
+  Code. Use Dataview only in a sidecar (`_dashboard.md`) for personal
+  views.
+
+Avoid as canonical source:
+
+- **Canvas**, **Excalidraw** — not diff-able, not agent-readable. Keep
+  diagrams as committed SVG (`docs/assets/erd.svg`) or as Mermaid blocks inside
+  Markdown.
+
+## Index generator interaction
+
+`generate-docs-index.mjs` is the system of record for `docs/INDEX.md`.
+Two reliability concerns when authoring through Obsidian:
+
+- **Forgetting to regenerate the index.** If you create or rename a doc
+  in Obsidian and commit without running the generator, INDEX.md goes
+  stale. Mitigations: a `pre-commit` hook that runs `npm run docs:index`
+  whenever staged changes touch `docs/**/*.md`, or a habit of running
+  `npm run docs:index` before every `git add docs/`.
+- **Renaming and "update links" prompts.** Obsidian's "automatically
+  update internal links" applies to wikilinks. Since this vault uses
+  Markdown links, Obsidian will still try to update them — verify the
+  diff before committing, especially for cross-folder renames.
+
+## What Obsidian must not do
+
+- Introduce wikilinks into committed files
+- Add Obsidian-only blocks (callouts, embeds with `![[...]]`) into
+  canonical docs
+- Replace `INDEX.md` with a Dataview view in the committed tree
+- Modify front-matter keys outside the documented set without also
+  updating `generate-docs-index.mjs`
+
+If a workflow benefits the personal vault but breaks one of those rules,
+keep it in a `_*.md` sidecar.
+
+## Summary
+
+Treat Obsidian like a notebook bound to the same desk as the repo:
+useful for thinking, never confused with what's published. The
+gitignore rules and the index generator already enforce most of this
+mechanically — these conventions cover the parts that still depend on
+the author's judgement.