docs(cli): improve documentation with clearer audit trail examples

- Clarify difference between audit IDs and task IDs
- Add "Understanding Audit IDs vs Task IDs" section
- Document two types of notes (description vs progress notes)
- Add demo --no-cleanup to command reference
- Include interactive mode shortcuts (taskflow i)
- Add due dates commands reference
- Better examples showing audit list --task workflow
- Add Running the Demo section

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: mjunaidca

packages/cli/docs/README.md

@@ -14,11 +14,14 @@ taskflow add "Review authentication module"
 # Start working on it
 taskflow start 1
 
-# Update progress
+# Update progress with a note
 taskflow progress 1 --percent 50 --note "Checking OAuth flow"
 
 # Complete the task
 taskflow complete 1
+
+# View the audit trail for this task
+taskflow audit list --task 1
 ```
 
 ## Core Concepts
@@ -40,19 +43,21 @@ taskflow worker add @claude-code --type agent --name "Claude Code" --agent-type
 
 ### Audit Trail
 
-Every action creates an audit log entry:
+Every action creates an audit log entry. The audit system tracks WHO did WHAT, WHEN, and WHY.
 
 ```bash
 # View all audit logs
 taskflow audit list
 
-# View logs for a specific task
+# View audit entries for a specific TASK (most common use case)
 taskflow audit list --task 1
 
-# View a specific audit entry
-taskflow audit show 1
+# View a specific audit entry by its ID (to see full details including notes)
+taskflow audit show 12
 ```
 
+**Important:** `audit show <id>` shows an audit entry by **audit log ID**, not task ID. To find audit entries for a task, first run `audit list --task <id>` to see the audit IDs, then use `audit show <audit-id>` to see details.
+
 ### Projects
 
 Tasks belong to projects for organization:
@@ -78,6 +83,7 @@ taskflow add "New feature" --project myproject
 | `taskflow init --user @myname` | Initialize with custom default user |
 | `taskflow init --path /custom/path` | Initialize in specific directory |
 | `taskflow demo` | Run interactive demo showcasing human-agent parity |
+| `taskflow demo --no-cleanup` | Run demo and keep the data for exploration |
 | `taskflow status` | Show current TaskFlow status |
 
 ### Task Management
@@ -89,6 +95,7 @@ taskflow add "New feature" --project myproject
 | `taskflow show <id>` | Show task details |
 | `taskflow edit <id>` | Edit task properties |
 | `taskflow delete <id>` | Delete a task |
+| `taskflow search <keyword>` | Search tasks by keyword |
 
 #### Task Options
 
@@ -115,19 +122,29 @@ taskflow edit 1 \
 |---------|-------------|
 | `taskflow start <id>` | Start working on a task (pending → in_progress) |
 | `taskflow progress <id> --percent N` | Update task progress (0-100) |
+| `taskflow progress <id> --percent N --note "..."` | Update progress with a note |
 | `taskflow review <id>` | Submit task for review |
 | `taskflow complete <id>` | Mark task as completed |
 | `taskflow block <id>` | Mark task as blocked |
 | `taskflow unblock <id>` | Unblock a task |
+| `taskflow delegate <id> --to @worker` | Reassign task to another worker |
 
 #### Progress Notes
 
+Progress notes are stored in the audit trail, creating a work journal:
+
 ```bash
 # Update progress with a note
-taskflow progress 1 --percent 75 --note "Auth flow working, testing edge cases"
-```
+taskflow progress 1 --percent 25 --note "Started code review"
+taskflow progress 1 --percent 50 --note "Found issue in auth logic"
+taskflow progress 1 --percent 75 --note "Fixed issue, running tests"
+
+# View all progress notes for a task
+taskflow audit list --task 1
 
-Progress notes are stored in the audit trail, creating a work journal.
+# View full details of a specific audit entry (including the note)
+taskflow audit show 12
+```
 
 ### Worker Management
 
@@ -163,27 +180,64 @@ taskflow worker add @claude-code \
 
 ### Audit Trail
 
+The audit trail records every action taken in TaskFlow.
+
 | Command | Description |
 |---------|-------------|
 | `taskflow audit list` | List all audit entries |
-| `taskflow audit list --task <id>` | Filter by task |
-| `taskflow audit list --actor @id` | Filter by actor |
+| `taskflow audit list --task <id>` | Show audit entries for a specific task |
+| `taskflow audit list --actor @id` | Filter by who performed the action |
 | `taskflow audit list --project <slug>` | Filter by project |
-| `taskflow audit show <id>` | Show audit entry details |
+| `taskflow audit show <audit-id>` | Show full details of an audit entry |
+
+#### Understanding Audit IDs vs Task IDs
+
+```bash
+# Step 1: Find audit entries for task #3
+taskflow audit list --task 3
+# Output shows audit IDs: 9, 10, 11, 12
+
+# Step 2: View details of a specific audit entry
+taskflow audit show 12
+# Shows full context including notes, status changes, etc.
+```
 
 ### Interactive Mode
 
+Interactive mode provides a REPL for faster command entry:
+
 ```bash
-# Enter interactive REPL
+# Enter interactive mode
 taskflow interactive
+# Or use the shorthand
+taskflow i
 
 # In interactive mode, commands work without 'taskflow' prefix:
 taskflow> list
 taskflow> add "New task"
 taskflow> start 1
+taskflow> progress 1 --percent 50 --note "Working on it"
+taskflow> audit list --task 1
 taskflow> exit
 ```
 
+Special interactive commands:
+- `use <project>` - Set current project context
+- `whoami` - Show current worker
+- `whoami @worker` - Set current worker context
+- `help` - Show available commands
+- `exit` / `quit` / `q` - Exit interactive mode
+
+### Due Dates
+
+| Command | Description |
+|---------|-------------|
+| `taskflow add "title" --due 2025-12-31` | Create task with due date |
+| `taskflow due <id> --date 2025-12-31` | Set due date on existing task |
+| `taskflow due <id> --clear` | Remove due date |
+| `taskflow upcoming` | Show tasks with upcoming due dates |
+| `taskflow overdue` | Show overdue tasks |
+
 ## Task Status Flow
 
 ```
@@ -201,25 +255,44 @@ Valid transitions:
 
 ## Adding Notes to Tasks
 
-### Task Description (persistent)
+TaskFlow supports two types of notes:
+
+### 1. Task Description (persistent, editable)
+
+The description is attached to the task itself:
 
 ```bash
-# On creation
+# Set description on creation
 taskflow add "Implement auth" --description "Need OAuth2 with refresh tokens"
 
-# On edit
-taskflow edit 1 --description "Updated requirements"
+# Update description later
+taskflow edit 1 --description "Updated: Also need PKCE support"
+
+# View description
+taskflow show 1
 ```
 
-View with `taskflow show <id>`.
+### 2. Progress Notes (audit trail, timestamped history)
 
-### Progress Notes (audit trail)
+Progress notes create a work journal in the audit trail:
 
 ```bash
-taskflow progress 1 --percent 50 --note "Completed initial review"
+# Add notes as you work
+taskflow progress 1 --percent 25 --note "Started implementation"
+taskflow progress 1 --percent 50 --note "OAuth flow working"
+taskflow progress 1 --percent 75 --note "Adding PKCE, found edge case"
+taskflow progress 1 --percent 100 --note "All tests passing"
+
+# View the work journal
+taskflow audit list --task 1
+
+# See full details of any entry
+taskflow audit show 15
 ```
 
-View with `taskflow audit list --task 1`.
+**When to use which:**
+- **Description**: Requirements, acceptance criteria, context that may change
+- **Progress notes**: Work log, decisions made, issues found, timestamps
 
 ## Subtasks (Recursive Tasks)
 
@@ -229,10 +302,19 @@ Tasks can have subtasks for hierarchical decomposition:
 # Create parent task
 taskflow add "Build authentication system"
 
-# Create subtasks
+# Create subtasks using --parent flag
 taskflow add "Implement login form" --parent 1
 taskflow add "Add OAuth provider" --parent 1
 taskflow add "Write auth tests" --parent 1
+
+# Or use the subtask command
+taskflow subtask 1 "Implement logout"
+
+# View task with its subtasks
+taskflow show 1
+
+# View as a tree
+taskflow show 1 --tree
 ```
 
 ## Environment Variables
@@ -248,7 +330,8 @@ TaskFlow stores data in `.taskflow/` directory:
 ```
 .taskflow/
 ├── config.json    # Configuration (current user, default project)
-└── data.json      # All data (projects, workers, tasks, audit logs)
+├── data.json      # All data (projects, workers, tasks, audit logs)
+└── history.txt    # Interactive mode command history
 ```
 
 ## Examples
@@ -263,15 +346,15 @@ taskflow list
 # Start a task
 taskflow start 1
 
-# Work and update progress
+# Work and update progress with notes
 taskflow progress 1 --percent 25 --note "Started code review"
 taskflow progress 1 --percent 50 --note "Found issue in auth logic"
 taskflow progress 1 --percent 75 --note "Fixed issue, running tests"
 
 # Complete
 taskflow complete 1
 
-# Review what was done
+# Review what was done (view the work journal)
 taskflow audit list --task 1
 ```
 
@@ -290,6 +373,9 @@ taskflow add "Update docs" --assign @alex
 
 # Check who's doing what
 taskflow list
+
+# See what a specific person has done
+taskflow audit list --actor @sarah
 ```
 
 ### Project Organization
@@ -305,4 +391,24 @@ taskflow add "Add rate limiting" --project api
 
 # List tasks by project
 taskflow list --project auth
+
+# See all activity in a project
+taskflow audit list --project auth
+```
+
+### Running the Demo
+
+The demo showcases human-agent parity:
+
+```bash
+# Run demo (cleans up after)
+taskflow demo
+
+# Run demo and keep data for exploration
+taskflow demo --no-cleanup
+
+# After demo, explore the data
+taskflow list
+taskflow audit list
+taskflow show 1
 ```

packages/cli/quickstart.md

@@ -13,12 +13,13 @@ Demo first
 ```>> start 3```
 ```>> progress 3 --percent 50```
 ```>> complete 3```
+```>> audit list --task 3```
 
   ```>>add "Review PR #42" --description "Check authentication logic and error handling"```
   ```>>edit 3 --description "Updated requirements based on feedback" ```
   ```>>start 4```
   ```>>progress 4 --percent 50 --note "Completed initial review, waiting for tests"```
-  
+
 
   taskflow> # View a task
   taskflow> show 3