Merge pull request #135 from keyxmakerx/claude/phase-sprint-planning-MEZXp

Claude/phase sprint planning mez xp

Author: keyxmakerx

.ai/phases.md

@@ -8,7 +8,62 @@
 <!-- ====================================================================== -->
 
 ## Last Updated
-2026-03-12 -- **Sprint F-4 done + F-4.5 planned.**
+2026-03-12 -- **Post-F-5 QoL: NPC sidebar link + plan reorg.**
+
+40. **Post-F-5 QoL: NPC sidebar navigation link.**
+    - Added "NPCs" entry to campaign sidebar in `internal/templates/layouts/app.templ` below "All Pages" link.
+    - Uses `fa-users` icon, `isPathPrefix` for active highlighting, links to `/campaigns/:id/npcs`.
+    - Updated `.ai/phases.md` with 6-phase priority rewrite (already done in session 36).
+    - Phase X sprints (X-1 through X-5) already present in `todo.md`.
+    - **Next up:** Phase 1 continues — Sprint F-4.5/F-QoL/F-5 all complete. Next is Phase 2 (X-1: System Upload UX) or Phase 6 (F-6: Armory/Inventory), depending on owner priority.
+
+39. **Sprint F-5: NPC Viewer / Hall (DONE).**
+    - **NPC plugin** — New `internal/plugins/npcs/` with model/repo/service/handler/templates/routes. View-layer plugin — no new database tables, queries existing `entities` table filtered by character type + visibility.
+    - **Gallery page** — `/campaigns/:id/npcs` shows a responsive grid of revealed character entities. Search by name (debounced HTMX), sort (name/updated/created), tag filter, pagination. Players see non-private characters; Scribes/Owners see all.
+    - **NPC card** — Portrait (aspect 3:4 or placeholder), name, type label/race/class, tags. Responsive grid (2→6 columns).
+    - **Reveal toggle** — Eye icon on each card (Scribe+). Toggles `is_private` via `POST /npcs/:eid/reveal` with HTMX swap. Green eye = visible, red eye-slash = hidden.
+    - **Entity service** — Added `TogglePrivate(entityID)` to `EntityService` interface. New `UpdatePrivate(entityID, isPrivate)` on `EntityRepository`. Publishes entity "updated" event via WebSocket.
+    - **npc_gallery layout block** — Registered in block registry (no addon required). Shows compact 3-4 column grid of up to 8 NPCs with "View all" link. Configurable via `{"limit": N}`.
+    - **Foundry sync** — Bidirectional NPC visibility sync. Chronicle→Foundry: entity `is_private` change updates actor's `prototypeToken.hidden`. Foundry→Chronicle: actor hidden toggle calls `POST /entities/:id/reveal` API.
+    - **Sync API** — New `POST /api/v1/campaigns/:id/entities/:entityID/reveal` endpoint. Accepts `{"is_private": bool}` or toggles if omitted. Verifies entity belongs to campaign.
+    - **Tests** — 7 tests: `ListNPCs_ReturnsCards`, `ListNPCs_EmptyWhenNoCharacterType`, `CountNPCs`, `NPCListOptions_Offset`, `NPCListOptions_OrderByClause`, `NPCCard_FieldString`, `TogglePrivate_EntityService`. All pass.
+    - **Wiring** — `npcEntityTypeFinderAdapter` and `npcVisibilityTogglerAdapter` in `app/routes.go`. Routes registered with `RequireRole(Player)` for view, `RequireRole(Scribe)` for reveal.
+
+38. **Sprint F-QoL: Foundry Sync Diagnostics (DONE).**
+    - **Validation report** — New `ValidationReport` type and `BuildValidationReport()` on `SystemManifest`. Analyzes categories, fields, presets, Foundry compatibility, mapped/writable fields, and generates warnings. Shown in custom system section after upload.
+    - **Template update** — `SystemValidationReport` templ component renders capability badges (categories, fields, presets, character fields), Foundry compatibility status, field mapping summary, and warnings.
+    - **API client health metrics** — `api-client.mjs` now tracks REST success/error counts, reconnect attempts, connection uptime, last success/error timestamps. New `_errorLog` array with structured error entries (method, path, status, message). `getUptimePercent()` computes session uptime.
+    - **Retry queue** — New `queueForRetry()` method for failed write operations. `processRetryQueue()` runs on WebSocket reconnect, retrying up to 3 times with structured logging. Queue capped at 50 entries.
+    - **Dashboard diagnostics** — Status tab now shows: 4-column diagnostics grid (uptime%, API OK, API errors, reconnects), last success/error timestamps, pending retry count, field mapping debug info (adapter type, system ID, character type slug), and separate error log section.
+    - **Dashboard CSS** — Added `.diagnostics-grid`, `.diagnostics-detail`, `.error-value`, `.error-text`, `.error-log` styles.
+    - **Tests** — 3 new tests: `BuildValidationReport_FullSystem`, `BuildValidationReport_MinimalSystem`, `BuildValidationReport_NoFoundryPaths`. All pass.
+    - **Dagger Heart** added to deferred systems list alongside Draw Steel.
+
+37. **Sprint F-4.5: Generic System Adapter (DONE).**
+    - **Manifest schema** — Added `foundry_system_id` to `SystemManifest`, `foundry_path` and `foundry_writable` to `FieldDef`. `IsFoundryWritable()` helper defaults to true when nil. New `CharacterFieldsForAPI()` builds API response with field annotations.
+    - **API endpoint** — `GET /api/v1/campaigns/:id/systems/:systemId/character-fields` returns field definitions with Foundry path annotations. Supports both built-in and custom campaign systems via `CampaignSystemLister` interface.
+    - **Manifest annotations** — dnd5e: all 15 character fields annotated with `foundry_path`; AC, speed, proficiency_bonus marked `foundry_writable: false`. PF2e: all 15 fields annotated; only hp_current/hp_max writable (everything else derived). DrawSteel: `foundry_system_id: "draw-steel"` added.
+    - **Foundry sync-manager.mjs** — `_detectSystem()` now API-driven: queries `/systems` and matches by `foundry_system_id` first, falls back to `SYSTEM_MAP_FALLBACK` for legacy support. Custom-uploaded systems with `foundry_system_id` auto-match.
+    - **Foundry generic-adapter.mjs** — New data-driven adapter that fetches field definitions from `/systems/:id/character-fields` API. Auto-generates `toChronicleFields()` and `fromChronicleFields()` from field annotations. Respects `foundry_writable` and field types for casting.
+    - **Foundry actor-sync.mjs** — `_loadAdapter()` tries built-in adapters (dnd5e, pf2e) first, then falls back to generic adapter for any other system.
+    - **Tests** — Added 7 tests for `IsFoundryWritable`, `CharacterPreset`, `CharacterFieldsForAPI`, and `LoadManifest` with Foundry annotations. All pass.
+    - **Impact:** Any game system (including custom uploads) can now participate in character sync by including `foundry_system_id` and `foundry_path` annotations in its manifest.
+
+36. **Phase & Sprint Plan Reorg.**
+    - Rewrote `.ai/phases.md` with 6 phases in new priority order based on owner direction:
+      (1) Foundry Completion & QoL (F-4.5, F-QoL, F-5),
+      (2) System Modularity & Owner Experience (X-1 through X-5 — new phase),
+      (3) Maps & Spatial (W-2, W-2.5),
+      (4) Collaboration & Polish (U-series, W-1, W-4),
+      (5) Content & Integrations (T-3/4, W-3/5/6),
+      (6) Foundry Advanced (F-6, F-7).
+    - Added new Phase X sprints to `todo.md`: X-1 (upload UX wizard), X-2 (auto entity presets),
+      X-3 (system-provided widgets), X-4 (system diagnostics), X-5 (character sheet blocks).
+    - Added F-QoL sprint (Foundry sync diagnostics & error handling).
+    - Key insight: the system framework needs end-to-end validation that a non-technical
+      owner can upload a custom system and get full functionality (presets, tooltips,
+      Foundry sync, widgets, character sheets) without manual setup.
+    - Next up: Sprint F-4.5 (generic system adapter).
 
 35. **F-4.5 planning: Generic System Adapter & Dynamic Matching.**
     - Identified that F-4's `SYSTEM_MAP` and `_loadAdapter()` switch are hardcoded to only dnd5e/pf2e/drawsteel. Custom-uploaded game systems can't participate in character sync despite having the server infrastructure (entity presets, `CharacterPreset()` helper, campaign system upload).
@@ -150,13 +205,15 @@ Branch: `claude/fix-journal-button-placement-UF4hD`.
 
 ## Phase & Sprint Plan
 See `.ai/phases.md` for the full roadmap. Phases organized by priority:
-- **V**: Obsidian-Style Notes & Discovery ← CURRENT
-- **W**: Polish, Ecosystem & Delight
-- **T**: Game System Modules & Worldbuilding Tools
-- **U**: Collaboration & Platform Maturity
+1. **F**: Foundry Completion & QoL (F-4.5, F-QoL, F-5) ← CURRENT
+2. **X**: System Modularity & Owner Experience (X-1 through X-5)
+3. **W**: Maps & Spatial (W-2, W-2.5)
+4. **U**: Collaboration & Polish (U-1/2/3/4/5, W-1, W-4)
+5. **T**: Content & Integrations (T-3/4, W-3/5/6)
+6. **F**: Foundry Advanced (F-6, F-7)
 
 ## Current Phase
-**Phase V (Obsidian-Style Notes & Discovery) — Sprint V-2 COMPLETE.**
+**Phase 1: Foundry Completion — Sprint F-4.5 IN PROGRESS.**
 
 ### Sprint V-2: Backlinks Panel & Entity Aliases (COMPLETE)
 - **Fixed migration 060**: Removed incorrect first ALTER that tried to drop 'module' from ENUM directly, causing Error 1265. Kept correct 3-step approach.
@@ -597,9 +654,9 @@ Created `.ai/audit.md` — comprehensive feature parity and completeness audit c
 - Updated architecture.md directory structure to reflect systems/ path
 
 ## Next Session Should
-- **Sprint U-2: Invite System** — campaign invite links for easier player onboarding
-- **Sprint V-1: Quick Capture** — Obsidian-style notes rapid entry
-- **Sprint T-3: Guided Worldbuilding Prompts** — Writing prompts panel on entity edit page (deferred)
+- **Sprint F-4.5: Generic System Adapter** — Remove hardcoded SYSTEM_MAP, dynamic matching via API
+- **Sprint F-QoL: Foundry Sync Diagnostics** — Validation report, health dashboard, error recovery
+- **Sprint F-5: NPC Viewer / Hall** — Gallery of revealed NPCs
 - See `.ai/phases.md` for full execution order
 
 ## Known Issues Right Now

.ai/status.md

@@ -195,7 +195,7 @@ _Fix orphaned data, cascade gaps, and admin DB visibility. See `.ai/phases.md`._
 - [ ] **Sprint U-4: Accessibility Audit (WCAG 2.1 AA)** — ARIA labels, focus traps, skip-to-content, color contrast 4.5:1, keyboard nav, screen reader announcements, axe-core scanning.
 - [ ] **Sprint U-5: Infrastructure & Deployment** — Docker-compose full stack verification with health checks. Makefile full-stack target. `CONTRIBUTING.md`. CI against docker-compose.
 
-### Phase V: Obsidian-Style Notes & Discovery ← NEXT
+### Phase V: Obsidian-Style Notes & Discovery (COMPLETE except V-4)
 
 _Quick capture, backlinks, enhanced graph, editor power-ups. See `.ai/obsidian-notes-plan.md` and `.ai/competitive-gap-analysis.md`._
 
@@ -279,23 +279,37 @@ _WASM-sandboxed backend logic via Extism/wazero. See ADR-021._
 - [x] **Sprint R-3: Write Host Functions** — 6 write host functions (update_entity_fields, create_event, set_entity_tags, get_entity_tags, create_relation, send_message). 5 new capabilities. 4 write adapters. Plugin-to-plugin async messaging. 10 new tests (48 total).
 - [x] **Sprint R-4: Plugin SDK & Developer Tools** — Example WASM plugins (Rust auto-tagger, Go session-logger). Go SDK with MockHost test harness (9 tests). Plugin development guide. 7 new manifest tests. **Phase R complete.**
 
-### Phase F: Foundry Sync Enhancements & Character Integration
+### Phase F: Foundry Sync Enhancements & Character Integration ← CURRENT (F-6 next)
 
 _Improve Foundry VTT sync fidelity. Add system-aware character sheet sync. Build toward inventory/NPC features._
 
 - [x] **Sprint F-1: Journal Sync Fidelity** — Multi-page journal sync (split entity `entry_html` by headings into Foundry pages, concatenate pages back on Foundry→Chronicle). Ownership change hook (detect ownership changes in `updateJournalEntry` hook, push to Chronicle). Helpers: `_splitByHeadings`, `_collectTextPages`, `_syncPagesToJournal`.
 - [x] **Sprint F-2: Granular Permission Mapping** — Map Chronicle `visibility: 'custom'` + `entity_permissions` to Foundry per-user ownership levels (view→OBSERVER, edit→OWNER). New syncapi endpoints: `GET /entities/:eid/permissions`, `PUT /entities/:eid/permissions`. Reverse-map Foundry ownership changes back to Chronicle. Helpers: `_buildOwnership`, `_pushPermissions`. User-specific grants stored in flags but not mapped to Foundry users (requires user ID mapping table — deferred).
 - [x] **Sprint F-3: System Detection & Character Field Templates** — Expanded dnd5e character preset (15 fields: class, level, race, alignment + 6 ability scores + HP/AC/speed/proficiency). Added pf2e character preset (15 fields: class, level, ancestry, heritage + 6 ability mods + HP/AC/perception/speed). `CharacterPreset()` helper on `SystemManifest`. New `GET /api/v1/campaigns/:id/systems` endpoint returns available systems with enabled flag. Foundry module: `syncCharacters` + `detectedSystem` settings, `SYSTEM_MAP` table, `_detectSystem()` on start, `getMatchedSystem()` accessor. Dashboard Status tab shows system match info and character sync availability.
 - [x] **Sprint F-4: Actor ↔ Entity Sync** — `actor-sync.mjs` with bidirectional Actor ↔ entity sync. System adapters: `dnd5e-adapter.mjs` (15 fields), `pf2e-adapter.mjs` (HP/name back only). Dashboard Characters tab with Push button. Registered in module.mjs. TESTING.md updated. **Note: adapters and SYSTEM_MAP are hardcoded — see F-4.5.**
-- [ ] **Sprint F-4.5: Generic System Adapter & Dynamic Matching** — Remove hardcoded `SYSTEM_MAP` and adapter switch. Instead: (1) Add `foundry_system_id` field to system manifest schema so custom-uploaded systems can declare Foundry compatibility. (2) `_detectSystem()` queries API and matches by `foundry_system_id` instead of static JS map. (3) Add `foundry_path` annotation on character preset field definitions (e.g., `"foundry_path": "system.abilities.str.value"`). (4) New `generic-adapter.mjs` reads character preset fields from API, auto-generates `toChronicleFields()`/`fromChronicleFields()` using `foundry_path` annotations. Fields without `foundry_path` are read-only (pushed to Chronicle but not written back to Foundry). (5) dnd5e/pf2e adapters remain as overrides for edge cases. **Result: any user-uploaded custom game system with a character preset and foundry_path annotations gets automatic character sync.**
-- [ ] **Sprint F-5: NPC Viewer / Hall** — Campaign route `/campaigns/:id/npcs`. Gallery/grid of revealed NPCs (non-private character entities). Portrait, name, description, location, faction. Filters by location/organization/relation. "Reveal" = DM toggles `is_private`. Foundry integration: ownership change on NPC journal → auto-reveal on Chronicle. Long-term: NPC relationship map (filtered relation graph).
+- [x] **Sprint F-4.5: Generic System Adapter & Dynamic Matching** — Added `foundry_system_id` to manifest, `foundry_path`/`foundry_writable` to FieldDef. New `GET /systems/:id/character-fields` API. `_detectSystem()` now API-driven (matches by `foundry_system_id`). New `generic-adapter.mjs` auto-generates field mappings from API. dnd5e (15 fields), pf2e (15 fields, most read-only), drawsteel annotated. actor-sync.mjs falls back to generic adapter. 7 new tests.
+- [x] **Sprint F-QoL: Foundry Sync Diagnostics & Error Handling** — `ValidationReport` type with `BuildValidationReport()` analyzing categories, fields, presets, Foundry compatibility, warnings. Templ component shows capability badges + warnings after upload. API client health metrics (success/error counts, uptime, reconnect attempts). Structured error log. Retry queue for failed writes (processes on reconnect, max 3 retries). Dashboard Status tab: diagnostics grid, error log, field mapping debug info. 3 new tests.
+- [x] **Sprint F-5: NPC Viewer / Hall (Plugin + Widget + Foundry Sync)** — Full NPC plugin at `internal/plugins/npcs/` with handler/service/repo/templates. Campaign route `/campaigns/:id/npcs` — gallery/grid of revealed NPCs (non-private character entities). Portrait, name, type label, tags. Search/sort/pagination. "Reveal" = Scribe toggles `is_private` via eye icon. `npc_gallery` layout block type for entity pages and dashboards. Foundry sync: NPC visibility changes sync bidirectionally — Chronicle `is_private` ↔ Foundry `prototypeToken.hidden`. REST API endpoint `POST /entities/:id/reveal`. 7 tests.
 - [ ] **Sprint F-6: Armory / Inventory System** — Items as entities with game-mechanic fields (weight, cost, rarity, damage, properties). Character "Inventory" tab/block via entity relations. Relation metadata: equipped, quantity, attunement. System-specific item templates (dnd5e ≠ pf2e). Foundry sync: Actor inventory ↔ Chronicle inventory relations. "Armory" campaign page showing all catalogued items.
 - [ ] **Sprint F-7: Shop / Marketplace Enhancement** — Transaction logging (who bought what, when). Currency tracking per character. Stock management (auto-deplete on purchase). Foundry: purchase from shop window → update character inventory on both sides.
 
+### Phase X: System Modularity & Owner Experience
+
+_Validate the full owner pipeline: upload custom system → enable → get presets,
+tooltips, Foundry sync, widgets, character sheets. Ensure the system framework
+is truly modular and self-service._
+
+- [ ] **Sprint X-1: System Upload UX & Validation** — Replace bare file input with guided wizard: upload ZIP, show parsed manifest summary (name, categories, presets, field count, Foundry compatibility), confirm and install. Manifest documentation/help section. Detailed validation error messages with fix suggestions. "Download sample system ZIP" button.
+- [ ] **Sprint X-2: System-Provided Entity Presets & Auto-Setup** — When system with `entity_presets` is enabled, offer to auto-create matching entity types. One-click entity type creation from presets. Preset sync on system re-upload (show diff, add new fields, don't remove existing). "From: D&D 5e" badge on preset-derived entity types.
+- [ ] **Sprint X-3: System-Provided Widgets & Layout Blocks** — New `widgets` array in manifest. Allow `.js` files in system ZIPs (scoped to `Chronicle.register()` pattern). System widgets appear in template editor palette when enabled. Example: D&D 5e `stat-block` widget.
+- [ ] **Sprint X-4: System Debugging & Diagnostics** — `/campaigns/:id/systems/status` page showing enabled system, loaded categories, item counts, presets, Foundry compatibility. Auto-generated reference data browser. Tooltip preview. Field mapping validator for `foundry_path` annotations. System error log in campaign settings.
+- [ ] **Sprint X-5: Character Sheet Layout Blocks (Foundation)** — New `character_sheet` layout block type in template editor. System-specific styled layouts (D&D 5e ability score grid, HP bar, class/level header). Manifest `field_groups` for visual sections. Inline-editable fields via attributes widget API.
+
 ### Deferred to Phase S+ (or community contributions)
 
 - [ ] **Module Builder UI** — Guided wizard that helps users create custom game system modules through the web UI. Step-by-step: name/metadata → define categories → define fields per category → paste/upload reference data → preview tooltips → export as module directory. Eliminates need to hand-write manifest.json + data files.
-- [ ] Draw Steel module
+- [ ] Draw Steel module (system data + Foundry adapter)
+- [ ] Dagger Heart module (system data + Foundry adapter)
 - [ ] Whiteboards / freeform canvas (Tldraw/Excalidraw)
 - [ ] Offline mode / service worker caching
 - [ ] Collaborative editing presence indicators