doc: Update plans around hover actions and bidirectional hook communication.

docs/DEVPLAN.md

@@ -114,22 +114,61 @@ with vim muscle memory.
 
 ## Phase 3: Structured I/O & Hooks
 
-The structured data pipeline.
+The structured data pipeline and the full hook system.
+
+**Implementation order:**
+
+1. Item model expansion (sublabel, meta, icon, group as
+   explicit optional fields on Item, alongside the raw
+   Value)
+2. Output struct with action context (separate from the
+   original item, no mutation)
+3. HookHandler trait in pikl-core, HookEvent enum,
+   HookResponse enum
+4. Exec hooks in CLI: `--on-<event>-exec` flags, subprocess
+   per event, stdout discarded
+5. Debounce system: none / debounce(ms) / cancel-stale,
+   configurable per hook via CLI flags
+6. Handler hooks in CLI: `--on-<event>` flags, persistent
+   process, stdin/stdout JSON line protocol
+7. Handler protocol commands: add_items, replace_items,
+   remove_items, set_filter, close
+8. `--filter-fields` scoping (which fields the filter
+   searches against)
+9. `--format` template strings for display
+   (`{label} - {sublabel}`)
+10. Field filters in query syntax (`meta.res:3840`),
+    integrated into the filter pipeline
 
 **Deliverables:**
-- JSON line input parsing (label, sublabel, meta, icon,
-  group)
-- JSON output with action context
-- Full hook lifecycle: on-open, on-close, on-hover,
+- Item model: sublabel, meta, icon, group as first-class
+  optional fields
+- Output: separate struct with action context (action,
+  index) wrapping the original item
+- Exec hooks (`--on-<event>-exec`): fire-and-forget,
+  subprocess per event, item JSON on stdin
+- Handler hooks (`--on-<event>`): persistent bidirectional
+  process, JSON lines on stdin/stdout
+- Handler protocol: add_items, replace_items, remove_items,
+  set_filter, close
+- Full lifecycle events: on-open, on-close, on-hover,
   on-select, on-cancel, on-filter
-- Hook debouncing
-- Bidirectional hooks (hook stdout modifies menu state)
-- `--format` template strings for display
-- Field filters (`meta.res:3840`)
-- Filter scoping (`--filter-fields`)
+- Debounce: three modes (none, debounce, cancel-stale),
+  per-hook CLI flags
+- Default debounce: on-hover 200ms + cancel-stale,
+  on-filter 200ms, others none
+- HookHandler trait in pikl-core (core emits events, does
+  not know what handlers do)
+- `--filter-fields label,sublabel,meta.tags`
+- `--format '{label} - {sublabel}'` template rendering
+- Field filters: `meta.res:3840` in query text
+- tracing for hook warnings (bad JSON, unknown actions,
+  process exit)
 
 **Done when:** The wallpaper picker use case works entirely
-through hooks and structured I/O.
+through hooks and structured I/O. A handler hook can
+receive hover events and emit commands to modify menu
+state.
 
 ## Phase 4: Multi-Select & Registers