docs(roadmap): inscribe V4 UX/DX research-informed backlog (§2.4) + scope corrections

[Davincc77]

Summary

Docs-only PR that integrates a UX/DX comparative review (Mem0, Letta .af, Zep, LangGraph, AGENTS.md, Cursor, Obsidian, Logseq, 1Password, Bitwarden, KeePassXC, ComfyUI workflow JSON, dated 2026-05-24) into the Road to .klickd v4 GA backlog.

The full research report is not copied into the repo — only the actionable decisions (new §2.4) and the opposable anti-patterns (A1–A6) are inscribed.

This PR follows the merge of #35 (RFC-001 / RFC-002 v1 core / RFC-004 → Accepted, merged at SHA 891e7581d74daff1ab743f4d4ab32f8052c9e9f4 on 2026-05-24).

Changes

• docs/roadmap/ROAD-TO-V4-GA.md §0 — V4 scope corrections (maintainer validation 2026-05-24):
  • generic continuity (media / project) = V4 via RFC-001 (already Accepted);
  • baseline gaming.klickd = V4 conditional on optional + registry-based;
  • 3D / spatial / CAD / printing = V5 track, does not block v4.0.0.
• docs/roadmap/ROAD-TO-V4-GA.md §2.4 — UX/DX-driven backlog (R4- IDs):
  • P0 — user.klickd 7-step wizard with reload verification (R4-P0-1); KLICKD_E_* i18n actionable error messages (R4-P0-2); 5 downloadable persona example profiles (R4-P0-3); formal deprecation policy (R4-P0-4).
  • P1 — minimal media.klickd aligned with RFC-001 (R4-P1-1); minimal project.klickd with AGENTS.md export (R4-P1-2); published JSON Schema v4 + offline validator (R4-P1-3); optional registry-based gaming.klickd baseline (R4-P1-4); QR / deeplink onboarding subject to zero-server architecture review (R4-P1-5 → P2 if blocking).
  • P2 — progressive compression preview (R4-P2-2); preferred_model routing hint (R4-P2-3); shared_context family UI (R4-P2-4); IANA MIME (R4-P2-5, cross-ref to existing P2-1).
• docs/roadmap/ROAD-TO-V4-GA.md §2.4 — R4-Anti-Patterns A1–A6 (opposable list): JSON wall, silent migration, hidden cloud coupling, schema inflation, spec-first without examples, non-actionable errors. Every v4+ PR must justify it does not introduce these.
• docs/roadmap/ROAD-TO-V4-GA.md §5 — status updated post-merge of rfc(v4): promote RFC-001 / RFC-002 (v1 core) / RFC-004 from Proposed to Accepted #35; next recommended PR is SPEC normative v4 (P0-1).
• docs/roadmap/V4-UX-DX-RESEARCH-NOTES.md (new) — intake summary documenting sources, decisions, anti-patterns, and scope corrections. Non-normative.

Strict governance respected

• No SPEC / schema / SDK / vector change.
• No publish (npm / PyPI / Zenodo / IANA).
• No tag / release.
• No package version bump.
• No locked_* field touched.
• No destructive change.
• Acceptance Checklist V4 not modified.

Test plan

• Local docs heading structure verified.
• Python vectors: python verify_vectors.py → 59/59 passed (0 failed).
• JS vectors: npm test → 29/29 passed (13 skipped, hash-wasm not installed locally — CI workflow test-vectors covers this).
• CI test-vectors green on this branch.
• CI verify-npm-preview (if it runs on docs branches) green.
• Reviewer confirms: no breaking changes, no normative wording moved, all backlog items respect zero-server / no-publish / locked_* constraints.

🤖 Generated with Claude Code