feat: AI rewrite trigger (:rw / :rwq) — spec ready, handoff for implementation

[Data-Wise]

Handoff: AI Rewrite Trigger (:rw / :rwq)

Date: 2026-07-04
Worktree: ~/.git-worktrees/flow-cli/feature-ai-rewrite-trigger
Branch: feature/ai-rewrite-trigger (1 commit, not pushed)
Spec: docs/specs/SPEC-ai-rewrite-trigger.md
Feature request: docs/FEATURE-REQUEST-ai-rewrite-trigger.md

Where this stands

Spec + feature-request docs are written and committed locally in this worktree. No
implementation code exists yet — Espanso config, the rewrite shell script, and Keychain
wiring are all still to be built.

What to do next (pick up here)

1. Resolve the 3 open questions in spec §9 (model choice for :rw vs :rwq, trigger naming,
   whether the doctor health check ships in this PR or a fast-follow)
2. Build: Espanso YAML config with :rw/:rwq matches → shell script → Gemini API key in
   Keychain
3. Manual test in ≥2 apps per the feature request's acceptance criteria
4. Decide whether to push this branch / open a PR, or keep local until MVP is validated

Context for a fresh session or different model

• This solves: Apple Intelligence's Writing Tools right-click menu doesn't work inside
  Electron apps (Claude Desktop, Claude Code) because those apps use custom text fields, not
  native AppKit components.
• Architecture decision already made: lives in flow-cli, not craft/savant (rewrite tool
  is OS-layer, not a Claude Code orchestration or skill-content concern — full reasoning in
  spec §2).
• Backend decision already made: Gemini API direct for both live triggers — zero
  Anthropic/Claude token cost, cost is a non-issue given existing Google token allocation.
• Do not implement :rws, :rwp, or a model router in this pass — explicitly parked, see
  spec §4.
• Do not use Antigravity CLI (agy) as a backend — documented non-TTY stdout-drop bug
  breaks scripted/piped invocation, which is exactly how Espanso would call it.