docs: update foundry module docs, fix migration numbering conflict

- foundry-module/.ai.md: Mark F-4.5/F-QoL/F-5 as DONE, add missing files
  (generic-adapter, sync-dashboard), update known limitations to reflect
  API-driven system matching and generic adapter
- foundry-module/TESTING.md: Add generic adapter and sync dashboard test
  sections, update character sync prerequisites
- .ai/status.md: Mark Phase 1 (Foundry Completion) as COMPLETE, update
  current phase and next session priorities
- Renumber NPC addon migration from 000007 to 000009 to resolve conflict
  with campaign_invites (000007) after merge from main

https://claude.ai/code/session_01WJEjfBqjZaGatHiXXXDupo

Author: claude

.ai/status.md

@@ -237,15 +237,15 @@ Branch: `claude/fix-journal-button-placement-UF4hD`.
 
 ## Phase & Sprint Plan
 See `.ai/phases.md` for the full roadmap. Phases organized by priority:
-1. **F**: Foundry Completion & QoL (F-4.5, F-QoL, F-5) ← CURRENT
+1. **F**: Foundry Completion & QoL (F-4.5, F-QoL, F-5) ← COMPLETE
 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 1: Foundry Completion — Sprint F-4.5 IN PROGRESS.**
+**Sprint 42: U-1 + W-1 + T-3.** Phase 1 (Foundry Completion: F-4.5, F-QoL, F-5) done. Next: Phase 2 (X-1: System Upload UX) or Phase 6 (F-6: Armory/Inventory).
 
 ### 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.
@@ -686,9 +686,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 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
+- **W-1 Saved Filters** — Persist command palette search filters per campaign
+- **Phase 2: X-1 System Upload UX** — Guided wizard for system install
+- **Phase 6: F-6 Armory / Inventory System** — Items as entities, character inventory, Foundry sync
 - See `.ai/phases.md` for full execution order
 
 ## Known Issues Right Now

…igrations/000007_add_npcs_addon.down.sql …igrations/000009_add_npcs_addon.down.sqldb/migrations/000007_add_npcs_addon.down.sql renamed to db/migrations/000009_add_npcs_addon.down.sql db/migrations/000007_add_npcs_addon.down.sql renamed to db/migrations/000009_add_npcs_addon.down.sql

@@ -11,14 +11,16 @@ v12/v13 module, connecting via REST API + WebSocket to the Chronicle backend.
 ```
 module.mjs (entry point)
   └─ SyncManager (sync-manager.mjs)
-       ├─ ChronicleAPI (api-client.mjs)   ← REST + WebSocket client
-       ├─ JournalSync (journal-sync.mjs)  ← Entity ↔ JournalEntry
-       ├─ MapSync (map-sync.mjs)          ← Map drawings/tokens ↔ Scene
-       ├─ CalendarSync (calendar-sync.mjs)← Calendar events/date ↔ Calendaria/SimpleCalendar
-       ├─ ShopWidget (shop-widget.mjs)    ← Shop entity inventory in Foundry UI
-       └─ ActorSync (actor-sync.mjs)      ← Character entity ↔ Actor
-            ├─ dnd5e-adapter.mjs           ← D&D 5e field mapping
-            └─ pf2e-adapter.mjs            ← Pathfinder 2e field mapping
+       ├─ ChronicleAPI (api-client.mjs)    ← REST + WebSocket client
+       ├─ JournalSync (journal-sync.mjs)   ← Entity ↔ JournalEntry
+       ├─ MapSync (map-sync.mjs)           ← Map drawings/tokens ↔ Scene
+       ├─ CalendarSync (calendar-sync.mjs) ← Calendar events/date ↔ Calendaria/SimpleCalendar
+       ├─ ShopWidget (shop-widget.mjs)     ← Shop entity inventory in Foundry UI
+       ├─ SyncDashboard (sync-dashboard.mjs) ← 6-tab ApplicationV2 status/management UI
+       └─ ActorSync (actor-sync.mjs)       ← Character entity ↔ Actor
+            ├─ dnd5e-adapter.mjs            ← D&D 5e field mapping
+            ├─ pf2e-adapter.mjs             ← Pathfinder 2e field mapping
+            └─ generic-adapter.mjs          ← Data-driven adapter (any system)
 ```
 
 ### Data Flow
@@ -52,6 +54,9 @@ All sync modules use a `_syncing` boolean flag to prevent infinite loops:
 | `scripts/actor-sync.mjs` | Actor ↔ character entity bidirectional sync. System adapter loading, hook registration |
 | `scripts/adapters/dnd5e-adapter.mjs` | D&D 5e field mapping: 15 fields (ability scores, HP, AC, speed, level, class, race, alignment, proficiency_bonus) |
 | `scripts/adapters/pf2e-adapter.mjs` | PF2e field mapping: ability mods, HP, AC, perception, speed, level, class, ancestry, heritage. Only HP/name sync back |
+| `scripts/adapters/generic-adapter.mjs` | Data-driven adapter: fetches field defs from `/systems/:id/character-fields` API, auto-generates mappings from `foundry_path` annotations. Fallback for systems without a hand-written adapter |
+| `scripts/sync-dashboard.mjs` | 6-tab ApplicationV2 dashboard (Entities, Shops, Maps, Characters, Calendar, Status). Pull/push actions, health metrics, error log, search/filter |
+| `templates/sync-dashboard.hbs` | Handlebars template for the sync dashboard tabs and content |
 | `templates/shop-window.hbs` | Handlebars template for shop inventory display |
 | `styles/chronicle-sync.css` | Status indicator + shop window styles |
 | `lang/en.json` | English localization for all UI strings |
@@ -99,10 +104,10 @@ All sync modules use a `_syncing` boolean flag to prevent infinite loops:
 - **Single scene**: Only the active Foundry scene syncs (no multi-scene)
 - **GM only**: Full sync runs only for GM users; players get passive updates via Foundry
 - **Character sync: limited fields back from PF2e**: Only HP and name sync from Chronicle to PF2e actors (most values are derived from items/rules)
-- **Character sync: hardcoded adapters**: `_loadAdapter()` in actor-sync.mjs uses a switch statement that only loads dnd5e and pf2e adapters. Custom/uploaded game systems won't get character sync until F-4.5 (generic adapter) is implemented. The server infrastructure already supports it — custom systems can define `entity_presets` with a `-character` slug and field definitions. F-4.5 will replace the hardcoded switch with a generic adapter that reads field mappings from the Chronicle API.
-- **System ID mapping hardcoded**: `SYSTEM_MAP` in sync-manager.mjs only maps 3 Foundry system IDs. F-4.5 will query available systems from the API and match dynamically.
+- **Character sync: custom system requirements**: Custom game systems must include `foundry_path` annotations on their character preset fields for bidirectional sync. Systems without annotations get no character sync (the generic adapter returns null). dnd5e and pf2e have hand-written adapters that handle edge cases.
+- **System matching fallback**: `SYSTEM_MAP_FALLBACK` (3 entries: dnd5e, pf2e, drawsteel) in sync-manager.mjs is used only when the `/systems` API call fails or the system lacks a `foundry_system_id` in its manifest. Normal operation queries the API and matches dynamically.
 
-## Planned Features (Phase F)
+## Features (Phase F)
 
 See `.ai/todo.md` Phase F for full sprint breakdown.
 
@@ -135,20 +140,31 @@ See `.ai/todo.md` Phase F for full sprint breakdown.
 - WS: `entity.created/updated/deleted` filtered by character type (via type_slug, type_name, or type_id)
 - Dashboard "Characters" tab: synced/unlinked actors, Push button, empty states
 - Delete from Chronicle unlinks Actor (preserves data); delete from Foundry deletes Chronicle entity
-- **Limitation**: Adapters are hardcoded per system. See F-4.5 for generic/dynamic adapter plan.
-
-### F-4.5: Generic System Adapter & Dynamic System Matching (PLANNED)
-- **Goal**: Any game system (built-in or user-uploaded custom) works with character sync out of the box, with no Foundry module code changes required.
-- **Remove `SYSTEM_MAP` hardcoding**: Instead of mapping Foundry `game.system.id` → Chronicle system ID via a static JS object, query `GET /systems` and match by `foundry_system_id` field on the system manifest. Systems API already returns all registered systems. Add `foundry_system_id` to system manifest schema so custom uploads can declare their Foundry compatibility.
-- **Generic adapter**: New `adapters/generic-adapter.mjs` that reads character field definitions from the Chronicle API (`GET /systems/:id/character-fields` or from the character preset in the entity types response). For each field in the preset, it generates `toChronicleFields()` mappings (Foundry `system.*` → Chronicle `fields_data.*`) and `fromChronicleFields()` reverse mappings.
-- **Field mapping convention**: The generic adapter uses a convention-based approach: Chronicle field keys map to Foundry `system.<path>` using a `foundry_path` property on each field definition. Systems that declare `foundry_path` on their character preset fields get automatic bidirectional sync. Fields without `foundry_path` are pushed to Chronicle (read from Foundry's flat actor data) but not written back.
-- **Fallback to specific adapters**: dnd5e and pf2e adapters remain as overrides for known systems (they handle edge cases like PF2e's derived values). Generic adapter is the fallback for any system not in the override list.
-- **Server changes**: Add optional `foundry_system_id` and `foundry_path` fields to system manifest `entity_presets[].fields[]`. Expose character preset fields via API so the Foundry module can read them. Custom system upload already validates manifests, so these fields would be available on upload.
-- **Custom system workflow**: User uploads a custom game system ZIP to Chronicle with a manifest that includes `foundry_system_id: "my-system"` and character preset fields with `foundry_path` annotations. Foundry module auto-detects the system, reads field definitions from API, and syncs characters without any adapter code.
-
-### F-5: NPC Viewer / Hall (website feature)
-- Campaign route `/campaigns/:id/npcs` — gallery of revealed NPCs
-- Foundry integration: ownership change on NPC journal → auto-reveal on Chronicle
+- dnd5e/pf2e adapters remain as overrides; generic adapter handles all other systems (see F-4.5).
+
+### F-QoL: Foundry Sync Diagnostics & Error Handling (DONE)
+- `ValidationReport` type with `BuildValidationReport()` analyzing categories, fields, presets, Foundry compatibility
+- API client health metrics: success/error counts, uptime percentage, reconnect attempts, last timestamps
+- Structured error log (last 50 entries with timestamp, method, path, status, message)
+- Retry queue for failed write operations (processes on reconnect, max 3 retries, cap 50 items)
+- Dashboard Status tab: diagnostics grid, error log, field mapping debug info, activity log
+- Templ component shows capability badges + warnings after system upload
+
+### F-4.5: Generic System Adapter & Dynamic System Matching (DONE)
+- `generic-adapter.mjs`: Fetches field definitions from `/systems/:id/character-fields` API. Auto-generates `toChronicleFields()`/`fromChronicleFields()` mappings from `foundry_path` annotations. Respects `foundry_writable` flag. Type casting for numbers.
+- `_detectSystem()` in sync-manager.mjs now API-driven: queries `/systems`, matches by `foundry_system_id`. Falls back to `SYSTEM_MAP_FALLBACK` for legacy support.
+- `_loadAdapter()` in actor-sync.mjs tries built-in adapters (dnd5e, pf2e) first, then falls back to generic adapter via `createGenericAdapter()`.
+- Server: `foundry_system_id` on `SystemManifest`, `foundry_path`/`foundry_writable` on `FieldDef`. `IsFoundryWritable()` helper. New `GET /systems/:id/character-fields` API. dnd5e (15 fields), pf2e (15 fields, most read-only), drawsteel annotated.
+- Custom system workflow: Upload ZIP with manifest including `foundry_system_id` and `foundry_path` annotations → Foundry module auto-detects, reads field defs from API, syncs characters without adapter code.
+- **Limitation**: Systems without `foundry_path` on their fields get no character sync.
+
+### F-5: NPC Viewer / Hall (DONE)
+- NPC plugin at `internal/plugins/npcs/` with model/repo/service/handler/templates/routes
+- Campaign route `/campaigns/:id/npcs` — gallery/grid of revealed NPCs (non-private character entities)
+- Portrait, name, type label, tags. Search/sort/pagination. Reveal toggle 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: `POST /entities/:id/reveal`. Sidebar navigation link. 7 tests
 
 ### F-6: Armory / Inventory System
 - Items with game-mechanic fields, character "Inventory" tab via relations

…/migrations/000007_add_npcs_addon.up.sql …/migrations/000009_add_npcs_addon.up.sqldb/migrations/000007_add_npcs_addon.up.sql renamed to db/migrations/000009_add_npcs_addon.up.sql db/migrations/000007_add_npcs_addon.up.sql renamed to db/migrations/000009_add_npcs_addon.up.sql

@@ -151,7 +151,7 @@ Requires a running Chronicle instance and Foundry VTT with the chronicle-sync mo
 ## Character Sync (Actor ↔ Entity)
 
 ### Prerequisites
-- [ ] Game system matches a Chronicle system (dnd5e or pf2e)
+- [ ] Game system matches a Chronicle system (built-in or custom with foundry_path annotations)
 - [ ] "Sync Characters" enabled in module settings
 - [ ] Character entity type exists in Chronicle campaign
 
@@ -187,6 +187,16 @@ Requires a running Chronicle instance and Foundry VTT with the chronicle-sync mo
 - [ ] PF2e: Only HP and name sync back from Chronicle (derived values protected)
 - [ ] PF2e: ancestry, heritage, class, level, perception, speed push to Chronicle
 
+### Generic Adapter (Custom Systems)
+- [ ] Custom system with foundry_path annotations → generic adapter loaded
+- [ ] Generic adapter maps annotated fields bidirectionally (Chronicle ↔ Foundry)
+- [ ] Fields with foundry_writable: false only push to Chronicle, not written back
+- [ ] System without foundry_path on any field → generic adapter returns null, character sync disabled
+- [ ] Type casting: number fields cast via Number(), string fields pass through
+- [ ] _detectSystem() matches by foundry_system_id from API (not SYSTEM_MAP)
+- [ ] _detectSystem() falls back to SYSTEM_MAP_FALLBACK when API fails
+- [ ] _loadAdapter() tries dnd5e/pf2e first, then generic adapter
+
 ### Edge Cases
 - [ ] Actor sync disabled when no system adapter available
 - [ ] Sync guard prevents infinite loops (change in A doesn't re-trigger back to A)
@@ -200,3 +210,26 @@ Requires a running Chronicle instance and Foundry VTT with the chronicle-sync mo
 - [ ] Network timeout during sync doesn't corrupt state
 - [ ] Partial sync failure (one entity fails) doesn't block others
 - [ ] Module gracefully handles Chronicle server restart
+
+## Sync Dashboard
+
+### Access
+- [ ] Click status indicator → dashboard opens (GM only)
+- [ ] Dashboard shows "Not configured" state when settings missing
+- [ ] Dashboard opens to last-active tab
+
+### Tabs
+- [ ] Entities tab: entity list with sync status dots, pull/push actions, visibility toggle, search filter
+- [ ] Shops tab: shop entities with "Open Shop" button linking to ShopWidget
+- [ ] Maps tab: scene-to-map linking via dropdown, drawing/token counts
+- [ ] Characters tab: synced/unlinked actors, push button, system badge
+- [ ] Calendar tab: date comparison (Chronicle vs Foundry), pull/push buttons, module detection
+- [ ] Status tab: connection health, activity log, error log, diagnostics grid, system match info
+
+### Diagnostics (F-QoL)
+- [ ] Health metrics: REST success/error counts, uptime percentage, reconnect attempts
+- [ ] Error log: last 50 errors with timestamp, method, path, status
+- [ ] Retry queue: failed writes queued and processed on reconnect (max 3 retries)
+- [ ] Activity log: last 100 sync actions with color-coded type icons
+- [ ] Clear log button resets activity log
+- [ ] Reconnect button triggers manual WebSocket reconnection