restructure docs with value-focused README

- Move README to value props only
- Organize docs into cli/, features/, ui/, data/
- Create comprehensive keybindings doc
- Create storage format doc
- Move existing docs to appropriate subdirectories

Co-Authored-By: Warp <agent@warp.dev>

Author: ComputelessComputer

README.md

@@ -6,153 +6,74 @@
 
 A terminal-based AI-powered project manager built in Rust.
 
+## Why aipm?
+
+**Natural language task management** — Just type what you need. "Break down the auth feature into sub-tasks" or "mark all design tasks as done." The AI understands intent and executes through tool calls.
+
+**Email inbox → task list** — Integrates with Apple Mail via MCP to automatically surface actionable emails as task suggestions. Marketing and noise filtered out by AI.
+
+**File-per-task architecture** — Each task is a markdown file with YAML front matter. Grep your way through tasks. Perfect for AI coding agents.
+
+**Full keyboard control** — Vim-style bindings. Arrow keys. No mouse needed. Navigate between buckets, timeline, kanban, and settings instantly.
+
+**Context-aware AI** — Paste GitHub PR/issue URLs and the AI automatically fetches context. No manual copying.
+
 ## Features
 
-- **Buckets view** — organize tasks across Team, John-only, and Admin columns
-- **Timeline view** — chronological task overview
-- **Kanban view** — drag tasks through Backlog → Todo → In Progress → Done
-- **Settings** — configure AI model, API key, and other options from within the app
-- **AI triage & tools** — natural language input is routed through AI tool calls to create, update, delete, decompose, or bulk-update tasks
-- **URL context** — paste a link (GitHub PR/issue or any URL) and the AI automatically fetches and incorporates its content
-- **Delete confirmation** — modal prompt before deleting any task
-- **Keyboard-driven** — full navigation via keyboard with tab bar focus, arrow keys, and vim-style bindings
-
-## Keybindings
-
-| Context | Key | Action |
-|---------|-----|--------|
-| Global | `Ctrl-C` | Quit |
-| Global | `1/2/3/4` | Switch tabs |
-| Input | `/exit` | Quit |
-| Tab bar | `←/→` | Navigate tabs |
-| Tab bar | `Enter` | Enter selected tab |
-| Input | `Enter` | Create task |
-| Input | `Esc` | Switch to board |
-| Board | `↑/↓/←/→` | Navigate tasks and columns |
-| Board | `Enter/e` | Edit selected task |
-| Board | `d/x/Backspace/Delete` | Delete task (with confirmation) |
-| Board | `p/Space` | Advance progress |
-| Board | `P` | Retreat progress |
-| Board | `Esc` | Focus tab bar |
-| Edit | `↑/↓` | Navigate fields |
-| Edit | `Enter/e` | Edit field value |
-| Edit | `←/→` | Cycle enum fields |
-| Edit | `Esc` | Close overlay |
-
-## Setup
-
-### Requirements
-
-- Rust 1.70+
-- An OpenAI API key (for AI features)
-
-### Build & run
+- **Multiple views**: Buckets (columns), Timeline (chronological), Kanban (progress stages)
+- **AI triage**: Natural language → create/update/delete/decompose/bulk-update tasks via tool calls
+- **Email suggestions**: MCP integration with Apple Mail surfaces actionable inbox items
+- **URL context**: Auto-fetch GitHub PRs/issues or any URL content
+- **CLI mode**: Headless commands for scripting (`task list`, `suggestions sync`, etc.)
+- **Undo/history**: Snapshot before every operation, rollback anytime
+- **Sub-tasks & dependencies**: Hierarchical tasks with automatic parent progress sync
+- **Keyboard-driven**: Full vim-style navigation, no mouse required
+
+## Quick Start
 
 ```sh
 cargo build --release
 ./target/release/aipm
 ```
 
-### AI configuration
-
-Set your API key for your preferred provider:
+Set up AI (required for triage and email filtering):
 
 ```sh
 export ANTHROPIC_API_KEY="sk-ant-..."   # for Claude models
 export OPENAI_API_KEY="sk-..."           # for OpenAI models
 ```
 
-Or configure it in the Settings tab (`4`) within the app. The default model is `claude-sonnet-4-5`.
-
-## CLI commands
-
-All subcommands output JSON to stdout. Errors go to stderr with a non-zero exit code.
-Task IDs accept short prefixes (4+ hex chars), e.g. `36149d52` or `3614`.
-
-### Task commands
-
-- `aipm task list` — JSON array of all tasks.
-- `aipm task show <id>` — single task as JSON.
-- `aipm task add --title "X" --bucket "Y"` — create a task. Optional flags: `--priority low|medium|high|critical`, `--progress backlog|todo|in-progress|done`, `--due YYYY-MM-DD`, `--description "..."`, `--parent <id>` (for sub-tasks). Prints the created task as JSON.
-- `aipm task edit <id>` — update a task. Pass any combination of: `--title`, `--bucket`, `--description`, `--priority`, `--progress`, `--due` (use `none` to clear). Prints the updated task as JSON.
-- `aipm task delete <id>` — delete a task and all its sub-tasks. Prints confirmation JSON.
-
-### Bucket commands
+Or configure in Settings tab (`4`). Default model: `claude-sonnet-4-5`.
 
-- `aipm bucket list` — JSON array of all buckets.
-- `aipm bucket add <name>` — add a bucket. Optional: `--description "..."`.
-- `aipm bucket rename <old> <new>` — rename a bucket and update all tasks in it.
-- `aipm bucket delete <name>` — delete a bucket; tasks move to the first remaining bucket.
+## Usage
 
-### AI commands (headless)
+**TUI**: Just run `aipm` and start typing natural language instructions.
 
-- `aipm "<instruction>"` — send a natural-language instruction to AI for triage (create/update/delete tasks). Requires an API key.
-
-## AI tools
-
-The AI agent uses tool calling to decide how to handle each input. Available tools:
-
-| Tool | Description |
-|------|-------------|
-| `create_task` | Create a new task with title, bucket, description, priority, progress, due date, and optional subtasks |
-| `update_task` | Update fields on an existing task by ID prefix |
-| `delete_task` | Delete a task by ID prefix |
-| `decompose_task` | Break a task into smaller subtasks with dependency ordering |
-| `bulk_update_tasks` | Apply an instruction across multiple tasks at once |
-
-The AI also automatically fetches context from URLs included in the input:
-- **GitHub PRs/Issues** — fetches title, author, state, and body via the GitHub API
-- **Generic URLs** — fetches the page, extracts the title and a text snippet
-
-## Data storage
-
-Each task is stored as an individual markdown file with YAML front matter in a `tasks/` directory:
-
-```
-<data_dir>/
-  tasks/
-    550e8400-implement-user-auth.md
-    660e8400-setup-oauth-flow.md
-    ...
-  settings.yaml
-```
-
-Task file format:
-
-```yaml
----
-id: "550e8400-e29b-41d4-a716-446655440000"
-title: "Implement user authentication"
-bucket: Team
-progress: InProgress
-priority: High
-due_date: "2026-03-01"
-parent_id: "660e8400-e29b-41d4-a716-446655440001"
-dependencies:
-  - "770e8400-e29b-41d4-a716-446655440002"
-created_at: "2026-02-10T12:00:00Z"
-updated_at: "2026-02-15T14:30:00Z"
----
-Description goes here as the markdown body.
+**CLI**: Script-friendly JSON output:
+```sh
+aipm task list
+aipm "create three tasks for the auth feature"
+aipm suggestions sync --limit 5
 ```
 
-This file-per-task architecture makes tasks naturally navigable by AI coding agents:
+**Keybindings**: Press `1/2/3/4/0` to switch tabs. Full vim-style navigation (`hjkl`, arrows, etc.).
 
-```sh
-grep -r "priority: Critical" tasks/   # find all critical tasks
-grep -r "bucket: Team" tasks/          # find all team tasks
-ls tasks/                               # browse tasks by name
-cat tasks/550e8400-*.md                 # read a specific task
-```
+## Documentation
 
-Default data directory:
+### CLI
+- [Task Commands](docs/cli/tasks.md) - CRUD operations for tasks
+- [Bucket Commands](docs/cli/buckets.md) - Manage task columns/categories
+- [Undo/History](docs/cli/undo.md) - Rollback operations
 
-- **macOS**: `~/Library/Application Support/aipm/`
-- **Linux**: `$XDG_DATA_HOME/aipm/` or `~/.local/share/aipm/`
+### Features
+- [AI Triage](docs/features/ai.md) - Natural language task management
+- [Email Suggestions](docs/features/suggestions.md) - Apple Mail MCP integration
 
-Override with `AIPM_DATA_DIR` environment variable.
+### UI
+- [Keybindings](docs/ui/keybindings.md) - Complete keyboard reference
 
-Existing `tasks.json` data is automatically migrated to the new format on first run.
+### Data
+- [Storage Format](docs/data/storage.md) - File-per-task architecture details
 
 ## License
 

docs/buckets.md docs/cli/buckets.mddocs/buckets.md renamed to docs/cli/buckets.md

@@ -0,0 +1,122 @@
+# Data Storage
+
+aipm uses a file-per-task architecture where each task is stored as an individual markdown file with YAML front matter.
+
+## Directory Structure
+
+```
+<data_dir>/
+  tasks/
+    550e8400-implement-user-auth.md
+    660e8400-setup-oauth-flow.md
+    ...
+  settings.yaml
+  history/
+    snapshot-2026-02-17-120000.json
+    snapshot-2026-02-17-130000.json
+    ...
+```
+
+## Task File Format
+
+Each task is stored as a markdown file with YAML front matter:
+
+```yaml
+---
+id: "550e8400-e29b-41d4-a716-446655440000"
+title: "Implement user authentication"
+bucket: Team
+progress: InProgress
+priority: High
+due_date: "2026-03-01"
+parent_id: "660e8400-e29b-41d4-a716-446655440001"
+dependencies:
+  - "770e8400-e29b-41d4-a716-446655440002"
+created_at: "2026-02-10T12:00:00Z"
+updated_at: "2026-02-15T14:30:00Z"
+---
+Description goes here as the markdown body.
+Multi-line descriptions are supported.
+```
+
+## Fields
+
+- **id**: UUID v4 identifier
+- **title**: Task name
+- **bucket**: Column/category (e.g. "Team", "Personal")
+- **progress**: One of `Backlog`, `Todo`, `InProgress`, `Done`
+- **priority**: One of `Low`, `Medium`, `High`, `Critical`
+- **due_date**: Optional ISO date (YYYY-MM-DD)
+- **parent_id**: Optional UUID of parent task (for sub-tasks)
+- **dependencies**: Array of task UUIDs this task depends on
+- **created_at**: ISO 8601 timestamp
+- **updated_at**: ISO 8601 timestamp
+- **start_date**: Optional timestamp when task moved to InProgress
+
+## Data Directory Locations
+
+Default locations by platform:
+
+- **macOS**: `~/Library/Application Support/aipm/`
+- **Linux**: `$XDG_DATA_HOME/aipm/` or `~/.local/share/aipm/`
+
+Override with environment variable:
+
+```sh
+export AIPM_DATA_DIR=/path/to/custom/location
+```
+
+## File-per-Task Benefits
+
+This architecture makes tasks naturally accessible to AI agents and command-line tools:
+
+```sh
+# Find all critical tasks
+grep -r "priority: Critical" tasks/
+
+# Find all team tasks
+grep -r "bucket: Team" tasks/
+
+# Browse tasks by name
+ls tasks/
+
+# Read a specific task
+cat tasks/550e8400-*.md
+
+# Count tasks by progress
+grep -l "progress: InProgress" tasks/*.md | wc -l
+```
+
+## Migration
+
+Existing `tasks.json` data is automatically migrated to the file-per-task format on first run. The old file is preserved as a backup.
+
+## Settings File
+
+Settings are stored in `settings.yaml`:
+
+```yaml
+owner_name: "John"
+enabled: true
+openai_api_key: "sk-..."
+anthropic_api_key: "sk-ant-..."
+model: "claude-sonnet-4-5"
+api_url: ""
+timeout_secs: 30
+show_backlog: true
+show_todo: true
+show_in_progress: true
+show_done: true
+buckets:
+  - name: "Team"
+    description: "Team-wide tasks"
+  - name: "Personal"
+    description: "Individual tasks"
+mcp_enabled: false
+mcp_python_path: "/usr/bin/python3"
+mcp_script_path: ""
+```
+
+## History / Undo
+
+State snapshots are saved in `history/` before each CLI or AI operation. See [CLI Undo](../cli/undo.md) for details.