feat(tui): add automation apply and rules editing

README.md

@@ -5,7 +5,8 @@
 ## Current posture
 
 - Primary stack: Rust + `clap`
-- Operator surfaces: CLI first, TUI inspection plus confirmed selected-thread workflow, draft, and cleanup actions second
+- Operator surfaces: CLI first, TUI inspection plus confirmed selected-thread
+  workflow, draft, cleanup, and persisted automation actions second
 - Local operational store: SQLite with migration-owned schema and FTS5-backed mailbox search
 - Native Gmail foundation: OAuth login, active account persistence, live profile/label reads, one-shot mailbox sync, local search, thread-scoped workflow state, remote draft sync, reviewed cleanup actions, attachment catalog/export foundation, review-first automation rules, and a terminal operator shell
 - Hardening surface: read-only label audits, readiness verification, and operator runbooks for safe real-mailbox rollout
@@ -171,9 +172,10 @@ with the durable design captured in
 The terminal operator shell lives in
 [`docs/operations/tui-operator-shell.md`](docs/operations/tui-operator-shell.md),
 with the durable design captured in
-[`docs/decisions/0008-read-only-tui-foundation.md`](docs/decisions/0008-read-only-tui-foundation.md)
+[`docs/decisions/0008-read-only-tui-foundation.md`](docs/decisions/0008-read-only-tui-foundation.md),
 [`docs/decisions/0009-tui-workflow-actions.md`](docs/decisions/0009-tui-workflow-actions.md),
-and [`docs/decisions/0010-tui-draft-cleanup-flows.md`](docs/decisions/0010-tui-draft-cleanup-flows.md).
+[`docs/decisions/0010-tui-draft-cleanup-flows.md`](docs/decisions/0010-tui-draft-cleanup-flows.md),
+and [`docs/decisions/0011-tui-automation-apply-rules.md`](docs/decisions/0011-tui-automation-apply-rules.md).
 
 Config precedence is:
 
@@ -218,6 +220,8 @@ Advanced manual overrides still work:
 - [`docs/decisions/0007-verification-audit-hardening.md`](docs/decisions/0007-verification-audit-hardening.md): read-only audit ownership and real-mailbox rollout posture
 - [`docs/decisions/0008-read-only-tui-foundation.md`](docs/decisions/0008-read-only-tui-foundation.md): read-only terminal shell ownership
 - [`docs/decisions/0009-tui-workflow-actions.md`](docs/decisions/0009-tui-workflow-actions.md): confirmed local workflow actions in the TUI
+- [`docs/decisions/0010-tui-draft-cleanup-flows.md`](docs/decisions/0010-tui-draft-cleanup-flows.md): selected-thread draft and cleanup flows in the TUI
+- [`docs/decisions/0011-tui-automation-apply-rules.md`](docs/decisions/0011-tui-automation-apply-rules.md): persisted automation run apply and editor-backed rules editing in the TUI
 - [`docs/operations/local-config-and-store.md`](docs/operations/local-config-and-store.md): config precedence, store bootstrapping, and hardening
 - [`docs/operations/gmail-auth-and-account.md`](docs/operations/gmail-auth-and-account.md): Gmail OAuth flow, credential storage, and account verification
 - [`docs/operations/mailbox-sync-and-search.md`](docs/operations/mailbox-sync-and-search.md): sync commands, search filters, and cursor behavior
@@ -232,6 +236,10 @@ Advanced manual overrides still work:
 ## Near-term build plan
 
 1. Use the verification and hardening runbook to canonicalize labels, deepen the local audit corpus, and generate disabled starter rules with `automation rules suggest`.
-2. Add automation action flows to the TUI with confirmation screens that preserve the persisted review-snapshot safety model.
-3. Improve automation ergonomics only after a few low-surprise micro-batch archive/label runs land cleanly.
-4. Add unsubscribe assistance only after the deeper sync proves out list-header coverage in the local cache.
+2. Use the TUI automation pane for validation, disabled suggestion review,
+   persisted preview runs, saved-run candidate inspection, and high-friction
+   saved-run apply.
+3. Improve automation ergonomics only after a few low-surprise micro-batch
+   archive/label runs land cleanly.
+4. Add unsubscribe assistance only after the deeper sync proves out list-header
+   coverage in the local cache.

docs/README.md

@@ -20,14 +20,15 @@ Start here:
 8. [`decisions/0008-read-only-tui-foundation.md`](decisions/0008-read-only-tui-foundation.md)
 9. [`decisions/0009-tui-workflow-actions.md`](decisions/0009-tui-workflow-actions.md)
 10. [`decisions/0010-tui-draft-cleanup-flows.md`](decisions/0010-tui-draft-cleanup-flows.md)
-11. [`architecture/system-overview.md`](architecture/system-overview.md)
-12. [`operations/local-config-and-store.md`](operations/local-config-and-store.md)
-13. [`operations/gmail-auth-and-account.md`](operations/gmail-auth-and-account.md)
-14. [`operations/mailbox-sync-and-search.md`](operations/mailbox-sync-and-search.md)
-15. [`operations/attachment-catalog-and-export.md`](operations/attachment-catalog-and-export.md)
-16. [`operations/thread-workflow-and-cleanup.md`](operations/thread-workflow-and-cleanup.md)
-17. [`operations/automation-rules-and-bulk-actions.md`](operations/automation-rules-and-bulk-actions.md)
-18. [`operations/verification-and-hardening.md`](operations/verification-and-hardening.md)
-19. [`operations/tui-operator-shell.md`](operations/tui-operator-shell.md)
-20. [`operations/plugin-assisted-workflows.md`](operations/plugin-assisted-workflows.md)
-21. [`roadmap/v1-search-triage-draft-queue.md`](roadmap/v1-search-triage-draft-queue.md)
+11. [`decisions/0011-tui-automation-apply-rules.md`](decisions/0011-tui-automation-apply-rules.md)
+12. [`architecture/system-overview.md`](architecture/system-overview.md)
+13. [`operations/local-config-and-store.md`](operations/local-config-and-store.md)
+14. [`operations/gmail-auth-and-account.md`](operations/gmail-auth-and-account.md)
+15. [`operations/mailbox-sync-and-search.md`](operations/mailbox-sync-and-search.md)
+16. [`operations/attachment-catalog-and-export.md`](operations/attachment-catalog-and-export.md)
+17. [`operations/thread-workflow-and-cleanup.md`](operations/thread-workflow-and-cleanup.md)
+18. [`operations/automation-rules-and-bulk-actions.md`](operations/automation-rules-and-bulk-actions.md)
+19. [`operations/verification-and-hardening.md`](operations/verification-and-hardening.md)
+20. [`operations/tui-operator-shell.md`](operations/tui-operator-shell.md)
+21. [`operations/plugin-assisted-workflows.md`](operations/plugin-assisted-workflows.md)
+22. [`roadmap/v1-search-triage-draft-queue.md`](roadmap/v1-search-triage-draft-queue.md)

docs/decisions/0008-read-only-tui-foundation.md

@@ -28,8 +28,10 @@ Mailroom adds `mailroom tui` as a Ratatui-based, read-only operator shell.
   a read-only automation rollout report from the existing Rust core.
 - The Search pane runs local SQLite FTS queries through the mailbox read model
   without store initialization or migration side effects.
-- No TUI view exposes Gmail mutations, draft send, cleanup execution,
-  attachment export, automation snapshot creation, or automation apply.
+- No first-slice TUI view exposed Gmail mutations, draft send, cleanup
+  execution, attachment export, automation snapshot creation, or automation
+  apply. Later ADRs add confirmed actions while preserving service ownership and
+  high-friction mutation gates.
 - `ratatui` is compiled with default features disabled and only the Crossterm
   backend enabled to avoid pulling extra widget/backend surface.
 

docs/decisions/0011-tui-automation-apply-rules.md

@@ -0,0 +1,72 @@
+# 0011: TUI Automation Apply and Rules Editing
+
+## Status
+
+Accepted.
+
+## Context
+
+Mailroom already has a review-first automation model:
+
+- `.mailroom/automation.toml` is the local typed rules file.
+- `automation rollout` is read-only readiness and candidate preview.
+- `automation run` persists a frozen review snapshot in SQLite.
+- `automation apply <run-id> --execute` mutates Gmail from that saved snapshot.
+
+The TUI previously showed only rollout readiness. Issue #26 adds operator flows
+for rules review, persisted run creation, saved candidate inspection, and
+guarded apply without creating a second rules engine or bypassing the CLI safety
+model.
+
+## Decision
+
+The TUI automation pane remains a thin operator surface over existing automation
+services.
+
+- Rules validation calls the same rules validation service as
+  `automation rules validate`.
+- Starter suggestions call the same suggestion service as
+  `automation rules suggest` and remain disabled snippets for operator review.
+- Persisted preview creation calls `automation run` semantics and writes a local
+  review snapshot only.
+- Candidate inspection loads a saved run by ID and renders saved candidate
+  details from SQLite.
+- Apply is only available for a loaded persisted run and requires typing
+  `APPLY` exactly.
+- The TUI never applies live `automation rollout` output.
+
+Rules editing uses `$VISUAL` or `$EDITOR` against `.mailroom/automation.toml`
+instead of a constrained in-TUI TOML form. If the active rules file is missing,
+the TUI seeds it from `config/automation.example.toml` before opening the
+editor. After the editor exits, the TUI validates the file and refreshes the
+automation rollout report.
+
+## Consequences
+
+- Operators can complete the automation review loop without leaving the TUI for
+  routine validation, suggestion review, snapshot creation, run inspection, and
+  guarded apply.
+- Operators still use their normal editor for TOML, preserving comments,
+  formatting, and multi-line edits without adding a second TOML writer.
+- Terminal lifecycle must temporarily restore the terminal before launching the
+  editor, then re-enter Ratatui after the editor exits.
+- Gmail mutation risk stays bounded because apply targets only a persisted run
+  snapshot and requires exact high-friction confirmation.
+
+## Rejected Options
+
+### In-TUI Structured Rules Form
+
+Rejected for this slice. A constrained form would need to represent the full
+rules schema, ordering, comments, labels, and future predicates. That duplicates
+rules ownership and increases the chance of silently rewriting operator TOML.
+
+### Apply Rollout Directly
+
+Rejected. Rollout output is a live preview, not a reviewed snapshot. Applying it
+would violate the persisted review boundary from ADR 0006.
+
+### TUI-Specific Automation Store
+
+Rejected. Saved runs, candidates, and events already live in the canonical
+SQLite automation tables. A TUI-specific store would create drift.

docs/operations/automation-rules-and-bulk-actions.md

@@ -169,6 +169,26 @@ cargo run -- automation apply 42 --execute --json
 Without `--execute`, `automation apply` returns a validation-style error and
 does not mutate Gmail.
 
+## TUI Automation Operator Flow
+
+`cargo run -- tui` exposes the same review-first automation loop in the
+Automation pane:
+
+- `v` validates `.mailroom/automation.toml`.
+- `g` reviews disabled starter suggestions from local mailbox evidence.
+- `e` opens `.mailroom/automation.toml` in `$VISUAL`, `$EDITOR`, or `vi`; if the
+  file is missing, the TUI seeds it from `config/automation.example.toml` before
+  launching the editor and validates it after the editor exits.
+- `n` creates a persisted preview run snapshot with a positive candidate limit.
+- `o` loads a persisted run by ID for candidate inspection.
+- `j` / `k` moves through loaded run candidates.
+- `a` applies only the loaded persisted run after typing `APPLY` exactly.
+
+The TUI never applies live `automation rollout` output. It must have a saved run
+loaded before apply can open, and the apply confirmation shows the run ID,
+candidate count, action mix, any currently blocked rollout rules, and a Gmail
+mutation warning.
+
 Prune stale local review snapshots after inspecting the dry-run counts:
 
 ```bash

docs/operations/tui-operator-shell.md

@@ -2,10 +2,10 @@
 
 `mailroom tui` opens the native terminal operator shell.
 
-It is designed for fast inspection and deliberate workflow, draft, and cleanup
-actions after `workspace init`, auth setup, and a local sync. It does not
-replace the CLI JSON contract; it renders the same underlying reports for human
-operation and uses existing service owners for every action.
+It is designed for fast inspection and deliberate workflow, draft, cleanup, and
+automation actions after `workspace init`, auth setup, and a local sync. It does
+not replace the CLI JSON contract; it renders the same underlying reports for
+human operation and uses existing service owners for every action.
 
 ## Run
 
@@ -27,7 +27,9 @@ cargo run -- tui --search "project alpha"
 - Workflows: `workflow list` queue overview, selected-row detail, current draft
   inspection, confirmed local workflow actions, Gmail draft actions, and cleanup
   preview/execute flows.
-- Automation: read-only `automation rollout` readiness and candidate preview.
+- Automation: `automation rollout` readiness, rule validation, disabled starter
+  suggestion review, persisted run creation, saved-run candidate inspection, and
+  guarded saved-run apply.
 - Help: key bindings and safety posture.
 
 ## Keys
@@ -59,6 +61,17 @@ Workflow view keys:
 - `l`: preview or execute label cleanup
 - `x`: preview or execute trash cleanup
 
+Automation view keys:
+
+- `j` / `Down`: select next saved-run candidate after a run is loaded
+- `k` / `Up`: select previous saved-run candidate after a run is loaded
+- `v`: validate `.mailroom/automation.toml`
+- `g`: review disabled starter suggestions from local mailbox evidence
+- `n`: create a persisted automation preview run snapshot
+- `o`: load a persisted automation run by ID
+- `a`: apply the loaded persisted run after high-friction confirmation
+- `e`: open `.mailroom/automation.toml` in `$VISUAL`, `$EDITOR`, or `vi`
+
 Workflow confirmation keys:
 
 - `Enter`: confirm the displayed action
@@ -79,6 +92,15 @@ Workflow confirmation keys:
 - label cleanup input: labels are comma-separated; `Tab` / `Shift+Tab` switches
   between add, remove, and confirmation fields
 
+Automation confirmation keys:
+
+- `Enter`: confirm the displayed automation action
+- `Esc` / `q`: cancel the automation confirmation
+- run creation input: type a positive candidate limit; this creates only a
+  local persisted review snapshot
+- saved-run input: type a positive run ID to inspect candidates
+- apply input: type `APPLY` exactly, then `Enter`
+
 ## Safety Contract
 
 The TUI shell is still review-first. It exposes workflow, draft, and cleanup
@@ -107,21 +129,42 @@ Draft send and cleanup execute are high-friction Gmail mutations:
 - after successful actions, the TUI refreshes the workflow list, selected draft
   detail, and any active local search report through existing services
 
+Automation actions use the existing automation service layer:
+
+- rules validation uses `automation rules validate`
+- starter suggestions use `automation rules suggest` and stay disabled snippets
+  for operator review
+- run creation uses `automation run` and writes a local persisted snapshot
+- saved-run inspection uses `automation show`
+- apply uses `automation apply <run-id> --execute` only for the loaded persisted
+  run
+
+Automation apply is a high-friction Gmail mutation:
+
+- the TUI never applies live `automation rollout` output
+- a run must be loaded before apply can open
+- the confirmation summarizes the run ID, candidate count, action mix, blocked
+  rollout rules when present, and a Gmail mutation warning
+- apply requires typing `APPLY` exactly before `Enter`
+- after successful automation actions, the TUI refreshes rollout readiness
+
+Rules editing uses the operator's editor instead of an in-TUI TOML form. Press
+`e` to open `.mailroom/automation.toml` in `$VISUAL`, `$EDITOR`, or `vi`. If the
+rules file is missing, the TUI seeds it from `config/automation.example.toml`.
+When the editor exits, the TUI validates the file and refreshes automation
+readiness.
+
 It still does not:
 
 - promote workflows to `closed`
-- apply automation snapshots
-- create automation run snapshots
 - fetch or export attachments
-- edit `.mailroom/automation.toml`
+- apply rollout previews directly
 
 Use the existing CLI commands for flows that remain intentionally outside this
 TUI slice:
 
 ```bash
 cargo run -- workflow promote <thread-id> --to closed --json
-cargo run -- automation run --limit 10 --json
-cargo run -- automation apply <run-id> --execute --json
 ```
 
 ## Troubleshooting

docs/roadmap/v1-search-triage-draft-queue.md

@@ -88,12 +88,16 @@ draft/cleanup slice are now in place too:
   through existing workflow services
 - cleanup archive, label, and trash preview by default, with high-friction
   execute confirmations through existing workflow services
-- no attachment export, automation apply, rules editing, or direct Gmail adapter
-  calls from TUI code
-
-The next implementation slices should focus on automation action flows and the
-real personal ruleset rollout on top of the shipped audit surface, not re-open
-auth, account, config, store, sync, workflow, draft, cleanup, attachment, or
+- automation rules validation, disabled starter suggestion review, editor-backed
+  rules editing, persisted run creation, saved-run candidate inspection, and
+  high-friction saved-run apply through existing automation services
+- no attachment export, live rollout apply, or direct Gmail adapter calls from
+  TUI code
+
+The next implementation slice should focus on production TUI polish,
+accessibility, narrow-terminal resilience, render-path performance, and the real
+personal ruleset rollout on top of the shipped audit surface, not re-open auth,
+account, config, store, sync, workflow, draft, cleanup, attachment, or
 automation ownership.
 
 ## Deferred

src/automation/mod.rs

@@ -5,7 +5,10 @@ mod rules;
 mod service;
 mod suggestions;
 
-pub(crate) use model::AutomationRolloutReport;
+pub(crate) use model::{
+    AutomationApplyReport, AutomationRolloutReport, AutomationRulesSuggestReport,
+    AutomationRulesValidateReport, AutomationRunPreviewReport, AutomationShowReport,
+};
 pub use model::{
     AutomationPruneRequest, AutomationPruneStatus, AutomationRolloutRequest,
     AutomationRulesSuggestRequest, AutomationRunRequest, DEFAULT_AUTOMATION_ROLLOUT_LIMIT,