task-pigeon/docs/plans/2026-08-16-monitor-ux-polish-plan.md

Small SQLite task queue CLI for people and coding agents.

---
artifact_contract: ce-unified-plan/v1
artifact_readiness: implementation-ready
execution: code
created: 2026-08-16
product_contract_source: ce-plan-bootstrap
---

# Pigeon Monitor UX Polish Plan

## Problem Frame

Pigeon's Ink monitor is already the right shape for the product, but the operator experience is still too easy to miss: detail mode does not obviously advertise how to get back out, section controls are subtle, and the help surface is not yet strong enough to make the dashboard feel self-explanatory. The core product stays the same:

CLI -> command functions -> Drizzle/SQL -> SQLite

This plan focuses on making the monitor feel like a production-ready control surface without changing the underlying architecture.

## Product Contract

### Requirements

- R1: Keep the monitor on Ink. Do not replace it with a heavier or different TUI framework.
- R2: Make detail mode obviously recoverable. Esc, Backspace, and left arrow should back out of detail consistently, and the UI should tell the operator that plainly.
- R3: Make section and pane state obvious. The footer, section headers, and selected-item labels should show what is active and what actions are available.
- R4: Keep the composer and detail copy concise, context-aware, and readable in narrow terminals.
- R5: Preserve existing task and message actions, refresh behavior, and non-interactive command output.
- R6: Improve README/operator guidance so the keyboard model matches the runtime behavior.
- R7: Keep the codebase schema-first and test-driven. Use zod-defined state and update tests alongside behavior changes.

### Scope Boundaries

- In scope: monitor navigation clarity, help text, footer hints, detail exit behavior, composer copy, README updates, and regression tests.
- Out of scope: backend sync, remote replication redesign, a new auth model, changing the publish pipeline, or swapping away from SQLite.

## Key Technical Decisions

- KTD1: Ink remains the monitor rendering layer.
- KTD2: Navigation state stays small and explicit, with no new application layer.
- KTD3: Detail mode exits on Esc, Backspace, and left arrow.
- KTD4: Help text should be context-sensitive rather than a static wall of shortcuts.
- KTD5: Keep one-off command output plain and readable; the monitor is the interactive surface.
- KTD6: Use zod-first types for monitor state and transitions, then infer the TypeScript shapes from those schemas.

## Implementation Units

### U1: Navigation and Help Model

Files:
- `src/monitor-tui.tsx`
- `src/monitor-tui.test.tsx`

Work:
- Tighten detail-mode exit behavior.
- Make the footer and monitor hints reflect current mode.
- Ensure the operator can always tell how to go back from detail/composer states.

Tests:
- keyboard-path tests for enter/detail/back/cancel flows
- regression coverage for the monitor footer/help text behavior

### U2: Panel and Copy Polish

Files:
- `src/monitor-tui.tsx`

Work:
- Refine composer and detail-panel copy so it reads clearly in narrow terminals.
- Keep active state visible without crowding the dashboard.
- Preserve the current task/message actions while making them easier to discover.

Tests:
- exercised indirectly through monitor render tests

### U3: Docs and Operator Guidance

Files:
- `README.md`
- `skills/pigeon/SKILL.md`

Work:
- Update monitor shortcut documentation to match the runtime model.
- Make the operator guidance shorter and more direct.
- Keep the published docs aligned with the actual monitor behavior.

Tests:
- `bun run ci`
- package verification via `npm pack --dry-run`

## Verification

- `bun test src/monitor-tui.test.tsx src/cli.test.ts`
- `bun run ci`
- `npm pack --dry-run`