open-wadah 1.0.6 → 1.2.0

package/README.md

@@ -1,6 +1,6 @@
 # open-wadah
 
-Open Wadah CLI for managing tasks in a shared workspace.
+Open Wadah CLI — shared task board for humans and agents. Use it from the terminal or from Cursor, Claude Code, and Kimi.
 
 ## Install
 
@@ -8,22 +8,13 @@ Open Wadah CLI for managing tasks in a shared workspace.
 npm install -g open-wadah
 ```
 
-Commands are available as `wadah`, `tm`, and `ow`.
+Commands: `wadah`, `tm`, `ow` (same CLI).
 
-## Quick Start
+## Quick start
 
-1. Make sure the API is reachable (default: `https://api.openwadah.com`).
-2. Sign up or log in:
-
-```bash
-wadah signup
-wadah login
-```
-
-`wadah login` uses browser sign-in by default.  
-Use `wadah login --password` for terminal email/password.
-
-3. Use the CLI:
+1. API must be reachable (default: `https://api.openwadah.com`). Override: `TASK_MANAGER_API_URL` or `--api <url>`.
+2. Sign in: `wadah login` (browser) or `wadah login --password` (terminal).
+3. Use the board:
 
 ```bash
 wadah open
@@ -31,55 +22,69 @@ wadah add "Fix login issue"
 wadah complete <task-id>
 ```
 
-## Useful Commands
+## Commands
+
+| Command | Description |
+|--------|-------------|
+| **Auth** | `login`, `signup`, `logout`, `whoami` |
+| **Tasks** | `open`, `list`, `search`, `requested`, `add`, `complete`, `reopen`, `view`, `update`, `move`, `assign`, `comment`, `delete` |
+| **Relationships** | `add --blocks <id>`, `add --blocked-by <id>`, `update --blocks <id>` |
+| **Board** | `boards --json`, `buckets --json`, `assignees --json`; `board create/delete`, `bucket create/update/delete`, `assignee create/update/delete` |
+| **Files** | `folders`, `files`, `folder create` / `mkdir`, `upload` |
+| **Calendar** | `calendar` (list; `--assignee`, `--task`, `--from`, `--to`), `calendar add`, `calendar update <id>`, `calendar delete <id>` |
+| **Docs** | `docs` (list), `doc create [title]`, `doc show <id>`, `doc update <id>`, `doc delete <id>` |
+| **Agent tokens** | `agent-tokens` (list), `agent-token create [name]`, `agent-token delete <id>` |
+| **Workspace** | `state`, `members`, `invite`, `config` |
+| **Other** | `do "<sentence>"` (natural language, needs `OPENAI_API_KEY`), `doctor`, `completion [bash\|zsh]` |
 
-- `wadah --help`
-- `wadah whoami`
-- `wadah doctor`
-- `wadah list --open`
-- `wadah move <task-id> <bucket>`
-- `wadah update <task-id> --title "New title"`
-- `wadah state`
+Run `wadah --help` for full list and options.
 
-## Global Flags
+## Shell completion
 
-- `--profile <name>`: use a named profile (defaults to `default`)
-- `--token <token>`: use a token for this command only
-- `--json`: force machine-readable JSON output
-- `--quiet`: silence non-error output (also machine-friendly)
+**Bash:**
 
-## Stable Error Codes
+```bash
+wadah completion bash >> ~/.bashrc
+source ~/.bashrc
+```
 
-When `--json` is enabled (or output is non-interactive), errors return:
+**Zsh:**
 
-```json
-{"error":{"code":"auth_error","message":"Not authenticated"}}
+```bash
+wadah completion zsh >> ~/.zshrc
+source ~/.zshrc
 ```
 
-Common codes:
+## Agent / AI use
 
-- `auth_error`
-- `validation_error`
-- `network_error`
-- `api_error`
-- `server_error`
-- `authorization_pending`
-- `invalid_device_code`
-- `token_expired`
-- `login_timeout`
+- Set `TASK_MANAGER_TOKEN` (create a token: `wadah agent-token create "My Agent"`).
+- Use `--json` for machine-readable output: `wadah open --json`, `wadah list --json`, `wadah buckets --json`.
+- Natural language: `wadah do "add a task to fix the bug"` (requires `OPENAI_API_KEY`).
+- In Cursor/Claude/Kimi: see **WADAH_CLI.md** in the repo root for a short reference.
+- For autonomous 24/7 agents with GitHub Actions: see **AGENTS.md** in the repo root.
 
-## API URL Override
+## Global flags
 
-Use env var:
+- `--api <url>` — API base URL
+- `--profile <name>` — config profile
+- `--token <token>` — auth token for this run
+- `--json` — JSON output
+- `--quiet` — minimal output
 
-```bash
-TASK_MANAGER_API_URL=https://api.openwadah.com wadah open
-```
+## Develop & test
 
-Or pass per command:
+From the repo root:
 
 ```bash
-wadah --api https://api.openwadah.com open
+npm run install:all
+npm run tm -- --help
+cd task-manager-cli && npm test
 ```
 
-Use your own API URL if self-hosting (for example `https://api.yourcompany.com`).
+## Error codes (with `--json`)
+
+- `auth_error` — not authenticated
+- `validation_error` — bad input
+- `network_error` — request failed
+- `api_error` — API returned an error
+- `config` — missing config (e.g. OPENAI_API_KEY for `do`)

package/cli.js

@@ -6,8 +6,9 @@ import Conf from 'conf'
 import { input, password as promptPassword } from '@inquirer/prompts'
 import { webcrypto } from 'node:crypto'
 import { spawn } from 'node:child_process'
-import { readFileSync } from 'node:fs'
-import { dirname, resolve } from 'node:path'
+import { readFileSync, existsSync, createReadStream } from 'node:fs'
+import FormData from 'form-data'
+import { dirname, resolve, basename } from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 const randomUUID = () => webcrypto.randomUUID()
@@ -180,8 +181,8 @@ function printTaskList(tasks, state) {
 }
 
 function handleError(err) {
-  const msg = err.message ?? 'Unexpected error'
-  const code = err.code ?? 'unknown_error'
+  const msg  = err.message ?? 'Unexpected error'
+  const code = err.code    ?? 'unknown_error'
   const authLike =
     code === 'auth_error' ||
     msg.toLowerCase().includes('missing token') ||
@@ -194,6 +195,17 @@ function handleError(err) {
     console.error(chalk.red('\n✗ Not authenticated.'))
     console.error(chalk.gray('  Humans:  wadah login'))
     console.error(chalk.gray('  Agents:  TASK_MANAGER_TOKEN=<token> wadah open\n'))
+  } else if (code === 'network_error') {
+    console.error(chalk.red('\n✗ Network error — could not reach the API.'))
+    console.error(chalk.gray(`  Check your connection or API URL: ${getApiBase()}`))
+    console.error(chalk.gray('  Run: wadah doctor\n'))
+  } else if (code === 'server_error') {
+    console.error(chalk.red('\n✗ Server error — something went wrong on the API side.'))
+    console.error(chalk.gray('  Try again in a moment. If it persists, check api.openwadah.com status.\n'))
+  } else if (code === 'api_error' && msg.toLowerCase().includes('not found')) {
+    console.error(chalk.red('\n✗ Not found.'))
+    console.error(chalk.gray('  The resource may not exist, or this endpoint may not be available for agent tokens.'))
+    console.error(chalk.gray('  Run: wadah doctor\n'))
   } else {
     console.error(chalk.red(`\n✗ ${msg}\n`))
   }
@@ -203,12 +215,11 @@ function handleError(err) {
 async function resolveMyAssigneeId(state) {
   try {
     const me = await api('/api/auth/me')
+    if (me.assigneeId) return me.assigneeId
     const userId = me.user?.id
-    // Match by user_id field on assignee (if backend returns it)
     const byUserId = state.assignees.find((a) => a.user_id === userId)
     if (byUserId) return byUserId.id
   } catch {}
-  // Fallback: 'Me' assignee
   return state.assignees.find((a) => a.name === 'Me')?.id ?? null
 }
 
@@ -262,10 +273,117 @@ function isMachineOutput() {
   return runtimeJsonOutput || runtimeQuietOutput || !process.stdout.isTTY
 }
 
+// ── session state cache ───────────────────────────────────────────────────────
+let _cachedState = null
+async function getState() {
+  if (!_cachedState) _cachedState = await api('/api/state')
+  return _cachedState
+}
+
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms))
 }
 
+// ── natural language (do) ─────────────────────────────────────────────────────
+
+const DO_SYSTEM_PROMPT = `You are a parser for the "wadah" CLI (task board). Given the user's natural language request, output exactly one JSON object with no markdown or extra text:
+{"command": "<command>", "args": [<array of string arguments>]}
+
+Available commands and their args (use these exact command names):
+- add: args = [task title string]. Example: add a task "Fix login" -> {"command": "add", "args": ["Fix login"]}
+- folder create (or mkdir): args = [folder name]. Example: create a folder called Reports -> {"command": "folder create", "args": ["Reports"]}
+- upload: args = [file path]. Optional: include "--folder", "<folder-id>" in args if user says to put in a folder. Example: upload report.pdf -> {"command": "upload", "args": ["report.pdf"]}
+- open: args = []. List open tasks.
+- list: args = []. List all tasks.
+- complete: args = [task id]. Mark task done. Example: complete task abc123 -> {"command": "complete", "args": ["abc123"]}
+- requested: args = []. List tasks I requested.
+- view: args = [task id]. Show task details.
+- boards: args = []. List boards.
+- buckets: args = []. List columns.
+- assignees: args = []. List assignees.
+- state: args = []. Full state JSON.
+- move: args = [task id, bucket name or id]. Move task to another column.
+- assign: args = [task id, assignee name]. Assign a task.
+- whoami: args = []. Show current user/workspace.
+- folders: args = []. List folders.
+- files: args = []. List files; optionally include "--folder", "<id>" in args.
+- members: args = []. List workspace members.
+- calendar: args = []. List calendar events.
+- calendar add: args = []; include "--title", "<t>", "--start", "<iso>", "--end", "<iso>" for new event (start/end required).
+- docs: args = []. List workspace docs.
+- doc create: args = [title]. Create a doc. Optional: "--parent", "<id>", "--emoji", "<char>".
+- doc show: args = [doc id]. Show one doc.
+- doc update: args = [doc id]. Optional: "--title", "<t>", "--content", "<json>", "--emoji", "--parent", "<id>".
+- doc delete: args = [doc id]. Delete a doc.
+- agent-tokens: args = []. List agent tokens.
+- agent-token create: args = [name]. Create agent token; optional "--assignee-name", "<text>".
+- agent-token delete: args = [token id]. Revoke token.
+- board create: args = [board name]. Create board.
+- board delete: args = [board id]. Delete board.
+- bucket create: args = [column title]. Optional "--board", "<id>".
+- bucket update: args = [bucket id]. Optional "--title", "<t>", "--order", "<n>".
+- bucket delete: args = [bucket id]. Delete column.
+- assignee create: args = [name]. Optional "--type", "human" or "agent".
+- assignee update: args = [assignee id]. Optional "--name", "--type".
+- assignee delete: args = [assignee id]. Delete assignee.
+
+If the request is unclear or not a valid CLI action, return {"command": "", "args": []}. Output only the JSON object.`
+
+async function parseNaturalLanguage(message) {
+  const apiKey = process.env.OPENAI_API_KEY || process.env.WADAH_OPENAI_API_KEY
+  if (!apiKey || !apiKey.trim()) {
+    throw new CliError('config', 'Set OPENAI_API_KEY or WADAH_OPENAI_API_KEY to use natural language (wadah do "...")')
+  }
+  const res = await fetch('https://api.openai.com/v1/chat/completions', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      Authorization: `Bearer ${apiKey.trim()}`,
+    },
+    body: JSON.stringify({
+      model: 'gpt-4o-mini',
+      messages: [
+        { role: 'system', content: DO_SYSTEM_PROMPT },
+        { role: 'user', content: String(message).trim() },
+      ],
+      max_tokens: 200,
+      temperature: 0,
+    }),
+  })
+  const data = await res.json().catch(() => ({}))
+  if (!res.ok) {
+    const err = data.error?.message || data.message || res.statusText
+    throw new CliError('api_error', `LLM request failed: ${err}`)
+  }
+  const text = data.choices?.[0]?.message?.content?.trim() || ''
+  const jsonMatch = text.match(/\{[\s\S]*\}/)
+  const raw = jsonMatch ? jsonMatch[0] : text
+  let parsed
+  try {
+    parsed = JSON.parse(raw)
+  } catch (_) {
+    throw new CliError('api_error', 'Could not parse LLM response as JSON')
+  }
+  const cmd = parsed.command && String(parsed.command).trim()
+  const args = Array.isArray(parsed.args) ? parsed.args.map(String) : []
+  return { command: cmd, args }
+}
+
+function runResolvedCommand(command, args) {
+  const cliPath = resolve(__dirname, 'cli.js')
+  const childArgs = [cliPath]
+  if (runtimeApiBase) childArgs.push('--api', runtimeApiBase)
+  if (runtimeToken) childArgs.push('--token', runtimeToken)
+  if (runtimeProfile) childArgs.push('--profile', runtimeProfile)
+  const cmdParts = String(command).split(/\s+/).filter(Boolean)
+  childArgs.push(...cmdParts, ...args)
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, childArgs, { stdio: 'inherit', env: process.env, shell: false })
+    child.on('error', reject)
+    child.on('close', (code) => (code === 0 ? resolve() : reject(new Error(`Exit ${code}`))))
+  })
+}
+
 function openBrowser(url) {
   let cmd
   let args
@@ -308,6 +426,27 @@ program.hook('preAction', (_, actionCommand) => {
   runtimeQuietOutput = Boolean(opts.quiet)
 })
 
+// ── do (natural language) ──────────────────────────────────────────────────────
+
+program
+  .command('do <message>')
+  .description('Run a command from natural language (e.g. "add a task to fix the login bug")')
+  .action(async (message) => {
+    try {
+      const { command, args } = await parseNaturalLanguage(message)
+      if (!command) {
+        console.error(chalk.yellow('\nCould not understand. Try a direct command, e.g:\n  wadah add "Fix bug"\n  wadah folder create "Reports"\n  wadah open\n'))
+        process.exit(1)
+      }
+      if (!runtimeQuietOutput && process.stdout.isTTY) {
+        console.log(chalk.gray(`Running: wadah ${command} ${args.join(' ')}\n`))
+      }
+      await runResolvedCommand(command, args)
+    } catch (err) {
+      handleError(err)
+    }
+  })
+
 // ── tm login ──────────────────────────────────────────────────────────────────
 
 program
@@ -563,7 +702,7 @@ program
   .option('--completed',              'Show completed tasks instead')
   .action(async (opts) => {
     try {
-      const state = await api('/api/state')
+      const state = await getState()
       let tasks = state.tasks.filter((t) => !!t.completed === !!opts.completed)
 
       if (!opts.all && !opts.assignee) {
@@ -602,7 +741,7 @@ program
       if (opts.open && opts.completed) {
         return fail('Use either --open or --completed, not both.')
       }
-      const state = await api('/api/state')
+      const state = await getState()
       let tasks = state.tasks
       if (opts.open) tasks = tasks.filter((t) => !t.completed)
       if (opts.completed) tasks = tasks.filter((t) => !!t.completed)
@@ -627,6 +766,48 @@ program
     } catch (err) { handleError(err) }
   })
 
+// ── tm search ─────────────────────────────────────────────────────────────────
+
+program
+  .command('search <query>')
+  .description('Search tasks by title, notes or tags')
+  .option('--board <name>',    'Limit search to a specific board')
+  .option('--assignee <name>', 'Limit search to a specific assignee')
+  .option('--open',            'Only open tasks (default)')
+  .option('--all',             'Include completed tasks')
+  .action(async (query, opts) => {
+    try {
+      const state = await getState()
+      const q = query.toLowerCase()
+      let tasks = state.tasks
+
+      if (!opts.all) tasks = tasks.filter((t) => !t.completed)
+      if (opts.board) {
+        const b = findBoard(state.boards, opts.board)
+        if (!b) return fail(`Board not found: ${opts.board}`)
+        tasks = tasks.filter((t) => t.boardId === b.id)
+      }
+      if (opts.assignee) {
+        const a = findAssignee(state.assignees, opts.assignee)
+        if (!a) return fail(`Assignee not found: ${opts.assignee}`)
+        tasks = tasks.filter((t) => t.assigneeId === a.id)
+      }
+
+      tasks = tasks.filter((t) =>
+        t.title.toLowerCase().includes(q) ||
+        (t.notes  ?? '').toLowerCase().includes(q) ||
+        (t.description ?? '').toLowerCase().includes(q) ||
+        (t.tags ?? []).some((tag) => tag.toLowerCase().includes(q))
+      )
+
+      if (!isMachineOutput() && tasks.length === 0) {
+        console.log(chalk.gray(`\n  No tasks matching "${query}".\n`))
+        return
+      }
+      printTaskList(tasks, state)
+    } catch (err) { handleError(err) }
+  })
+
 // ── tm requested ──────────────────────────────────────────────────────────────
 
 program
@@ -634,7 +815,7 @@ program
   .description('List open tasks you requested (assigned to others / agents)')
   .action(async () => {
     try {
-      const state = await api('/api/state')
+      const state = await getState()
       const myId  = await resolveMyAssigneeId(state)
       const tasks = state.tasks.filter((t) => t.requestedById === myId && !t.completed)
       printTaskList(tasks, state)
@@ -653,9 +834,11 @@ program
   .option('--repo <owner/repo>','GitHub repo')
   .option('--url <url>',        'Issue / PR URL')
   .option('--notes <text>',     'Notes')
+  .option('--blocks <id>',      'This task blocks another task (provide task id)')
+  .option('--blocked-by <id>',  'This task is blocked by another task (provide task id)')
   .action(async (title, opts) => {
     try {
-      const state = await api('/api/state')
+      const state = await getState()
       const myId  = await resolveMyAssigneeId(state)
 
       let assigneeId    = myId
@@ -668,14 +851,19 @@ program
         requestedById = myId
       }
 
-      const bucket = opts.bucket
-        ? state.buckets.find((b) => b.title.toLowerCase().includes(opts.bucket.toLowerCase()))
-        : state.buckets[0]
-
       const board = opts.board
         ? state.boards.find((b) => b.name.toLowerCase().includes(opts.board.toLowerCase()))
         : state.boards.find((b) => b.id === state.currentBoardId) ?? state.boards[0]
 
+      if (!board && opts.board) return fail(`Board not found: ${opts.board}`)
+      if (!board) console.warn(chalk.yellow(`  ⚠ No board specified — defaulting to "${state.boards[0]?.name}". Set a default with: wadah config --default-board "<name>"`))
+
+      const boardBuckets = board ? state.buckets.filter((b) => b.boardId === board.id) : state.buckets
+      const bucket = opts.bucket
+        ? boardBuckets.find((b) => b.title.toLowerCase().includes(opts.bucket.toLowerCase()))
+          ?? state.buckets.find((b) => b.title.toLowerCase().includes(opts.bucket.toLowerCase()))
+        : boardBuckets[0] ?? state.buckets[0]
+
       const task = await api('/api/tasks', {
         method: 'POST',
         body:   JSON.stringify({
@@ -688,9 +876,27 @@ program
           repo:         opts.repo   ?? null,
           contextUrl:   opts.url    ?? null,
           notes:        opts.notes  ?? '',
+          tags: [
+            ...(opts.blocks    ? [`blocks:${opts.blocks.slice(0, 8)}`]    : []),
+            ...(opts.blockedBy ? [`blocked-by:${opts.blockedBy.slice(0, 8)}`] : []),
+          ],
         }),
       })
 
+      // If this task blocks another, tag the other task back
+      if (opts.blocks) {
+        try {
+          const other = await api(`/api/tasks/${opts.blocks}`)
+          const existingTags = other.tags ?? []
+          if (!existingTags.some((t) => t.startsWith('blocked-by:'))) {
+            await api(`/api/tasks/${opts.blocks}`, {
+              method: 'PATCH',
+              body: JSON.stringify({ tags: [...existingTags, `blocked-by:${task.id.slice(0, 8)}`] }),
+            })
+          }
+        } catch {}
+      }
+
       const assigneeName = state.assignees.find((a) => a.id === task.assigneeId)?.name ?? 'Unassigned'
       console.log(chalk.green('\n✓ Created') + `  ${chalk.bold(task.title)}`)
       console.log(chalk.gray(`  ID: ${task.id}  ·  Assigned to: ${assigneeName}\n`))
@@ -735,7 +941,7 @@ program
   .requiredOption('--to <name>', 'Assignee name')
   .action(async (id, opts) => {
     try {
-      const state = await api('/api/state')
+      const state = await getState()
       const a     = findAssignee(state.assignees, opts.to)
       if (!a) return fail(`Assignee not found: ${opts.to}`)
 
@@ -753,14 +959,18 @@ program
   .description('Move a task to another column')
   .action(async (id, bucketQuery) => {
     try {
-      const state = await api('/api/state')
+      const state = await getState()
       const bucket = findBucket(state.buckets, bucketQuery)
       if (!bucket) return fail(`Bucket not found: ${bucketQuery}`)
+      const patch = { bucketId: bucket.id }
+      if (bucket.boardId) patch.boardId = bucket.boardId
       const task = await api(`/api/tasks/${id}`, {
         method: 'PATCH',
-        body:   JSON.stringify({ bucketId: bucket.id }),
+        body:   JSON.stringify(patch),
       })
-      console.log(chalk.green('\n✓ Moved') + `  ${chalk.bold(task.title)} → ${bucket.title}\n`)
+      const boardName = state.boards.find((b) => b.id === bucket.boardId)?.name
+      const dest = boardName ? `${boardName} / ${bucket.title}` : bucket.title
+      console.log(chalk.green('\n✓ Moved') + `  ${chalk.bold(task.title)} → ${dest}\n`)
     } catch (err) { handleError(err) }
   })
 
@@ -778,6 +988,8 @@ program
   .option('--board <name>',           'Set board')
   .option('--bucket <name>',          'Set bucket')
   .option('--completed <true|false>', 'Set completion state')
+  .option('--blocks <id>',            'Mark this task as blocking another task')
+  .option('--blocked-by <id>',        'Mark this task as blocked by another task')
   .action(async (id, opts) => {
     try {
       const patch = {}
@@ -802,7 +1014,8 @@ program
       if (opts.clearDue) patch.dueDate = null
 
       const needsStateLookup = !!(opts.assignee || opts.board || opts.bucket)
-      const state = needsStateLookup ? await api('/api/state') : null
+      const state = needsStateLookup ? await getState() : null
+
 
       if (opts.assignee) {
         const a = findAssignee(state.assignees, opts.assignee)
@@ -815,12 +1028,32 @@ program
         patch.boardId = b.id
       }
       if (opts.bucket) {
-        const b = findBucket(state.buckets, opts.bucket)
+        const targetBoardId = patch.boardId ?? null
+        const scopedBuckets = targetBoardId
+          ? state.buckets.filter((b) => b.boardId === targetBoardId)
+          : state.buckets
+        const b = scopedBuckets.find((b) => b.id === opts.bucket || b.title.toLowerCase().includes(opts.bucket.toLowerCase()))
+          ?? state.buckets.find((b) => b.id === opts.bucket || b.title.toLowerCase().includes(opts.bucket.toLowerCase()))
         if (!b) return fail(`Bucket not found: ${opts.bucket}`)
         patch.bucketId = b.id
+        if (!patch.boardId && b.boardId) patch.boardId = b.boardId
       }
       if (opts.completed !== undefined) patch.completed = parsedCompleted
 
+      // Handle relationship tags (blocks / blocked-by)
+      if (opts.blocks || opts.blockedBy) {
+        const currentTask = await api(`/api/tasks/${id}`)
+        const currentTags = currentTask.tags ?? []
+        const newTags = [...currentTags]
+        if (opts.blocks && !newTags.some((t) => t.startsWith('blocks:'))) {
+          newTags.push(`blocks:${opts.blocks.slice(0, 8)}`)
+        }
+        if (opts.blockedBy && !newTags.some((t) => t.startsWith('blocked-by:'))) {
+          newTags.push(`blocked-by:${opts.blockedBy.slice(0, 8)}`)
+        }
+        patch.tags = newTags
+      }
+
       if (Object.keys(patch).length === 0) {
         return fail('Nothing to update. Run wadah update --help')
       }
@@ -868,7 +1101,17 @@ program
       if (task.dueDate) console.log(chalk.gray(`  Due:       ${formatDate(task.dueDate)}`))
       if (task.repo) console.log(chalk.gray(`  Repo:      ${task.repo}`))
       if (task.contextUrl) console.log(chalk.gray(`  Link:      ${task.contextUrl}`))
-      if (task.tags?.length) console.log(chalk.gray(`  Tags:      #${task.tags.join('  #')}`))
+      if (task.tags?.length) {
+        const relTags = task.tags.filter((t) => t.startsWith('blocks:') || t.startsWith('blocked-by:'))
+        const plainTags = task.tags.filter((t) => !t.startsWith('blocks:') && !t.startsWith('blocked-by:'))
+        if (plainTags.length) console.log(chalk.gray(`  Tags:      #${plainTags.join('  #')}`))
+        if (relTags.length) {
+          const blocking   = relTags.filter((t) => t.startsWith('blocks:')).map((t) => t.replace('blocks:', ''))
+          const blockedBy  = relTags.filter((t) => t.startsWith('blocked-by:')).map((t) => t.replace('blocked-by:', ''))
+          if (blocking.length)  console.log(chalk.red(`  Blocks:    ${blocking.join(', ')}`))
+          if (blockedBy.length) console.log(chalk.yellow(`  Blocked by: ${blockedBy.join(', ')}`))
+        }
+      }
       if (task.description) { console.log(); console.log(`  ${task.description}`) }
       if (task.notes) { console.log(chalk.gray('\n  Notes:')); console.log(`  ${task.notes}`) }
       if (task.subtasks?.length) {
@@ -911,7 +1154,17 @@ program
   .description('List all boards')
   .action(async () => {
     try {
-      const state = await api('/api/state')
+      const state = await getState()
+      if (isMachineOutput()) {
+        const result = state.boards.map((b) => ({
+          id:        b.id,
+          name:      b.name,
+          openCount: state.tasks.filter((t) => t.boardId === b.id && !t.completed).length,
+          doneCount: state.tasks.filter((t) => t.boardId === b.id &&  t.completed).length,
+        }))
+        console.log(JSON.stringify(result, null, runtimeJsonOutput ? 2 : 0))
+        return
+      }
       console.log()
       state.boards.forEach((b) => {
         const open = state.tasks.filter((t) => t.boardId === b.id && !t.completed).length
@@ -927,8 +1180,20 @@ program
   .description('List all columns (buckets)')
   .action(async () => {
     try {
-      const state = await api('/api/state')
+      const state = await getState()
       const boardMap = Object.fromEntries(state.boards.map((b) => [b.id, b.name]))
+      if (isMachineOutput()) {
+        const result = state.buckets.map((b) => ({
+          id:        b.id,
+          title:     b.title,
+          boardId:   b.boardId,
+          boardName: boardMap[b.boardId] ?? '—',
+          openCount: state.tasks.filter((t) => t.bucketId === b.id && !t.completed).length,
+          doneCount: state.tasks.filter((t) => t.bucketId === b.id &&  t.completed).length,
+        }))
+        console.log(JSON.stringify(result, null, runtimeJsonOutput ? 2 : 0))
+        return
+      }
       console.log()
       state.buckets.forEach((b) => {
         const open = state.tasks.filter((t) => t.bucketId === b.id && !t.completed).length
@@ -944,7 +1209,18 @@ program
   .description('List all assignees')
   .action(async () => {
     try {
-      const state = await api('/api/state')
+      const state = await getState()
+      if (isMachineOutput()) {
+        const result = state.assignees.map((a) => ({
+          id:        a.id,
+          name:      a.name,
+          type:      a.type ?? 'human',
+          openCount: state.tasks.filter((t) => t.assigneeId === a.id && !t.completed).length,
+          doneCount: state.tasks.filter((t) => t.assigneeId === a.id &&  t.completed).length,
+        }))
+        console.log(JSON.stringify(result, null, runtimeJsonOutput ? 2 : 0))
+        return
+      }
       console.log()
       state.assignees.forEach((a) => {
         const open = state.tasks.filter((t) => t.assigneeId === a.id && !t.completed).length
@@ -955,12 +1231,509 @@ program
     } catch (err) { handleError(err) }
   })
 
+// ── board CRUD ────────────────────────────────────────────────────────────────
+
+const boardCmd = program.command('board').description('Create or delete a board (list: wadah boards)')
+
+boardCmd
+  .command('create <name>')
+  .description('Create a new board')
+  .action(async (name) => {
+    try {
+      const board = await api('/api/boards', { method: 'POST', body: JSON.stringify({ name: String(name).trim() }) })
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(board, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Board created') + `  ${chalk.bold(board.name)}  ${chalk.gray(board.id?.slice(0, 8))}\n`)
+      }
+    } catch (err) { handleError(err) }
+  })
+
+boardCmd
+  .command('delete <id>')
+  .description('Delete a board (cannot delete the last one)')
+  .action(async (id) => {
+    try {
+      await api(`/api/boards/${id}`, { method: 'DELETE' })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Board deleted\n'))
+    } catch (err) { handleError(err) }
+  })
+
+// ── bucket CRUD ──────────────────────────────────────────────────────────────
+
+const bucketCmd = program.command('bucket').description('Create, update, or delete a column/bucket (list: wadah buckets)')
+
+bucketCmd
+  .command('create <title>')
+  .description('Create a new bucket (column)')
+  .option('--board <id>', 'Board id (optional)')
+  .action(async function (title) {
+    try {
+      const body = { title: String(title).trim() }
+      if (this.opts().board) body.boardId = this.opts().board
+      const bucket = await api('/api/buckets', { method: 'POST', body: JSON.stringify(body) })
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(bucket, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Bucket created') + `  ${chalk.bold(bucket.title)}  ${chalk.gray(bucket.id?.slice(0, 8))}\n`)
+      }
+    } catch (err) { handleError(err) }
+  })
+
+bucketCmd
+  .command('update <id>')
+  .description('Update a bucket')
+  .option('--title <text>', 'New title')
+  .option('--order <n>', 'Order (number)', parseInt)
+  .action(async function (id) {
+    const opts = this.opts()
+    try {
+      const patch = {}
+      if (opts.title !== undefined) patch.title = opts.title
+      if (opts.order !== undefined && !Number.isNaN(opts.order)) patch.order = opts.order
+      if (Object.keys(patch).length === 0) return fail('Provide --title or --order to update')
+      await api(`/api/buckets/${id}`, { method: 'PATCH', body: JSON.stringify(patch) })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Bucket updated\n'))
+    } catch (err) { handleError(err) }
+  })
+
+bucketCmd
+  .command('delete <id>')
+  .description('Delete a bucket (tasks move to another column)')
+  .action(async (id) => {
+    try {
+      await api(`/api/buckets/${id}`, { method: 'DELETE' })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Bucket deleted\n'))
+    } catch (err) { handleError(err) }
+  })
+
+// ── assignee CRUD ────────────────────────────────────────────────────────────
+
+const assigneeCmd = program.command('assignee').description('Create, update, or delete an assignee (list: wadah assignees)')
+
+assigneeCmd
+  .command('create <name>')
+  .description('Create a new assignee')
+  .option('--type <type>', 'Type: human or agent', 'human')
+  .action(async function (name) {
+    try {
+      const body = { name: String(name).trim(), type: this.opts().type || 'human' }
+      const assignee = await api('/api/assignees', { method: 'POST', body: JSON.stringify(body) })
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(assignee, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Assignee created') + `  ${chalk.bold(assignee.name)}  ${chalk.gray(assignee.id?.slice(0, 8))}\n`)
+      }
+    } catch (err) { handleError(err) }
+  })
+
+assigneeCmd
+  .command('update <id>')
+  .description('Update an assignee')
+  .option('--name <text>', 'New name')
+  .option('--type <type>', 'Type: human or agent')
+  .action(async function (id) {
+    const opts = this.opts()
+    try {
+      const patch = {}
+      if (opts.name !== undefined) patch.name = opts.name
+      if (opts.type !== undefined) patch.type = opts.type
+      if (Object.keys(patch).length === 0) return fail('Provide --name or --type to update')
+      await api(`/api/assignees/${id}`, { method: 'PATCH', body: JSON.stringify(patch) })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Assignee updated\n'))
+    } catch (err) { handleError(err) }
+  })
+
+assigneeCmd
+  .command('delete <id>')
+  .description('Delete an assignee (tasks unassigned)')
+  .action(async (id) => {
+    try {
+      await api(`/api/assignees/${id}`, { method: 'DELETE' })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Assignee deleted\n'))
+    } catch (err) { handleError(err) }
+  })
+
+program
+  .command('folders')
+  .description('List all folders (Files tab)')
+  .action(async () => {
+    try {
+      const folders = await api('/api/folders').catch(() => [])
+      const list = Array.isArray(folders) ? folders : []
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(list, null, runtimeJsonOutput ? 2 : 0))
+      } else if (list.length === 0) {
+        console.log(chalk.gray('\nNo folders. Create one: wadah folder create "Name"\n'))
+      } else {
+        console.log()
+        list.forEach((f) => console.log(`  ${chalk.bold(f.name)}  ${chalk.gray(`id: ${f.id}`)}`))
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+program
+  .command('files')
+  .description('List all files in the workspace')
+  .option('--folder <id>', 'Filter by folder id')
+  .action(async function () {
+    const opts = this.opts()
+    try {
+      const state = await getState()
+      let files = state.files ?? []
+      if (opts.folder) files = files.filter((f) => (f.folderId || f.folder_id) === opts.folder)
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(files, null, runtimeJsonOutput ? 2 : 0))
+      } else if (files.length === 0) {
+        console.log(chalk.gray('\nNo files. Upload one: wadah upload <path>\n'))
+      } else {
+        console.log()
+        files.forEach((f) => {
+          const name = f.name || f.id
+          const url = f.storageUrl || f.storage_url
+          console.log(`  ${chalk.bold(name)}  ${chalk.gray(url ? url.slice(0, 50) + '…' : f.id)}`)
+        })
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+program
+  .command('members')
+  .description('List workspace members')
+  .action(async () => {
+    try {
+      const members = await api('/api/workspace/members')
+      const list = Array.isArray(members) ? members : []
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(list, null, runtimeJsonOutput ? 2 : 0))
+      } else if (list.length === 0) {
+        console.log(chalk.gray('\nNo members.\n'))
+      } else {
+        console.log()
+        list.forEach((m) => console.log(`  ${chalk.bold(m.role)}  ${chalk.gray(m.user_id?.slice(0, 8) ?? '—')}`))
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+// ── agent tokens ──────────────────────────────────────────────────────────────
+
+program
+  .command('agent-tokens')
+  .description('List agent tokens for this workspace')
+  .action(async () => {
+    try {
+      const list = await api('/api/agent-tokens').catch(() => [])
+      const arr = Array.isArray(list) ? list : []
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(arr, null, runtimeJsonOutput ? 2 : 0))
+      } else if (arr.length === 0) {
+        console.log(chalk.gray('\nNo agent tokens. Create one: wadah agent-token create "Bot name"\n'))
+      } else {
+        console.log()
+        arr.forEach((t) => {
+          const as = t.assigneeName ? chalk.gray(` · acts as ${t.assigneeName}`) : ''
+          console.log(`  ${chalk.bold(t.name)}  ${chalk.gray(`id: ${t.id?.slice(0, 8)}${as}`)}`)
+        })
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+const agentTokenCmd = program.command('agent-token').description('Create or delete an agent token (for CLI/CI)')
+
+agentTokenCmd
+  .command('create [name]')
+  .description('Create an agent token; token is shown once — store it as TASK_MANAGER_TOKEN')
+  .option('--name <text>', 'Token name (if not passed as argument)')
+  .option('--assignee-name <text>', 'Display name for the agent (default: same as name)')
+  .action(async function (nameArg) {
+    const opts = this.opts()
+    const name = (nameArg || opts.name || 'CLI Agent').trim()
+    try {
+      const body = { name }
+      if (opts.assigneeName) body.assigneeName = opts.assigneeName
+      const result = await api('/api/agent-tokens', { method: 'POST', body: JSON.stringify(body) })
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(result, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Agent token created'))
+        console.log(chalk.gray(`  Name: ${result.name}  Id: ${result.id?.slice(0, 8)}  Acts as: ${result.assigneeName ?? result.name}`))
+        console.log(chalk.yellow('\n  Token (save it — shown once):'))
+        console.log(`  ${result.token}`)
+        console.log(chalk.gray('\n  Use: export TASK_MANAGER_TOKEN="<token>"\n'))
+      }
+    } catch (err) { handleError(err) }
+  })
+
+agentTokenCmd
+  .command('delete <id>')
+  .description('Revoke an agent token')
+  .action(async (id) => {
+    try {
+      await api(`/api/agent-tokens/${id}`, { method: 'DELETE' })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Agent token revoked\n'))
+    } catch (err) { handleError(err) }
+  })
+
+// ── calendar events ──────────────────────────────────────────────────────────
+
+const calendarCmd = program
+  .command('calendar')
+  .description('List calendar events (optional: --assignee, --task, --from, --to)')
+  .option('--assignee <id>', 'Filter by assignee id')
+  .option('--task <id>', 'Filter by task id')
+  .option('--from <iso>', 'From date (ISO)')
+  .option('--to <iso>', 'To date (ISO)')
+  .action(async function () {
+    const opts = this.opts()
+    try {
+      let path = '/api/calendar-events'
+      const q = []
+      if (opts.assignee) q.push(`assigneeId=${encodeURIComponent(opts.assignee)}`)
+      if (opts.task) q.push(`taskId=${encodeURIComponent(opts.task)}`)
+      if (opts.from) q.push(`from=${encodeURIComponent(opts.from)}`)
+      if (opts.to) q.push(`to=${encodeURIComponent(opts.to)}`)
+      if (q.length) path += '?' + q.join('&')
+      const list = await api(path).catch(() => [])
+      const arr = Array.isArray(list) ? list : []
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(arr, null, runtimeJsonOutput ? 2 : 0))
+      } else if (arr.length === 0) {
+        console.log(chalk.gray('\nNo calendar events.\n'))
+      } else {
+        console.log()
+        arr.forEach((e) => {
+          const start = e.startTime ? new Date(e.startTime).toLocaleString() : '—'
+          const end = e.endTime ? new Date(e.endTime).toLocaleString() : '—'
+          console.log(`  ${chalk.bold(e.title || 'Untitled')}  ${chalk.gray(`${start} → ${end}`)}  ${chalk.gray(`id: ${e.id?.slice(0, 8)}`)}`)
+        })
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+calendarCmd
+  .command('add')
+  .description('Create a calendar event (--start and --end required, ISO or YYYY-MM-DD)')
+  .option('--title <text>', 'Event title', 'Work block')
+  .option('--start <iso>', 'Start time (ISO or YYYY-MM-DD)')
+  .option('--end <iso>', 'End time (ISO or YYYY-MM-DD)')
+  .option('--task <id>', 'Task id')
+  .option('--assignee <id>', 'Assignee id')
+  .option('--color <hex>', 'Color')
+  .action(async function () {
+    const opts = this.opts()
+    try {
+      if (!opts.start || !opts.end) return fail('--start and --end are required')
+      const startTime = new Date(opts.start).toISOString()
+      const endTime = new Date(opts.end).toISOString()
+      const body = { title: opts.title, startTime, endTime }
+      if (opts.task) body.taskId = opts.task
+      if (opts.assignee) body.assigneeId = opts.assignee
+      if (opts.color) body.color = opts.color
+      const event = await api('/api/calendar-events', { method: 'POST', body: JSON.stringify(body) })
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(event, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Event created') + `  ${chalk.bold(event.title)}  ${chalk.gray(event.id?.slice(0, 8))}\n`)
+      }
+    } catch (err) { handleError(err) }
+  })
+
+calendarCmd
+  .command('update <id>')
+  .description('Update a calendar event')
+  .option('--title <text>', 'Event title')
+  .option('--start <iso>', 'Start time')
+  .option('--end <iso>', 'End time')
+  .option('--task <id>', 'Task id')
+  .option('--assignee <id>', 'Assignee id')
+  .option('--color <hex>', 'Color')
+  .action(async function (id) {
+    const opts = this.opts()
+    try {
+      const patch = {}
+      if (opts.title !== undefined) patch.title = opts.title
+      if (opts.start !== undefined) patch.startTime = new Date(opts.start).toISOString()
+      if (opts.end !== undefined) patch.endTime = new Date(opts.end).toISOString()
+      if (opts.task !== undefined) patch.taskId = opts.task
+      if (opts.assignee !== undefined) patch.assigneeId = opts.assignee
+      if (opts.color !== undefined) patch.color = opts.color
+      if (Object.keys(patch).length === 0) return fail('Provide at least one option to update')
+      await api(`/api/calendar-events/${id}`, { method: 'PATCH', body: JSON.stringify(patch) })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Event updated\n'))
+    } catch (err) { handleError(err) }
+  })
+
+calendarCmd
+  .command('delete <id>')
+  .description('Delete a calendar event')
+  .action(async (id) => {
+    try {
+      await api(`/api/calendar-events/${id}`, { method: 'DELETE' })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Event deleted\n'))
+    } catch (err) { handleError(err) }
+  })
+
+// ── workspace docs ─────────────────────────────────────────────────────────────
+
+program
+  .command('docs')
+  .description('List workspace docs')
+  .action(async () => {
+    try {
+      const list = await api('/api/docs').catch(() => [])
+      const arr = Array.isArray(list) ? list : []
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(arr, null, runtimeJsonOutput ? 2 : 0))
+      } else if (arr.length === 0) {
+        console.log(chalk.gray('\nNo docs.\n'))
+      } else {
+        console.log()
+        arr.forEach((d) => console.log(`  ${chalk.bold(d.title || 'Untitled')}  ${chalk.gray(`id: ${d.id?.slice(0, 8)}`)}`))
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+const docCmd = program.command('doc').description('Workspace doc (create, show, update, delete)')
+
+docCmd
+  .command('create [title]')
+  .description('Create a workspace doc')
+  .option('--title <text>', 'Doc title (if not passed as argument)')
+  .option('--parent <id>', 'Parent doc id')
+  .option('--emoji <char>', 'Emoji')
+  .action(async function (titleArg) {
+    const opts = this.opts()
+    const title = (titleArg || opts.title || 'Untitled').trim()
+    try {
+      const body = { title }
+      if (opts.parent) body.parentId = opts.parent
+      if (opts.emoji) body.emoji = opts.emoji
+      const doc = await api('/api/docs', { method: 'POST', body: JSON.stringify(body) })
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(doc, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Doc created') + `  ${chalk.bold(doc.title)}  ${chalk.gray(doc.id?.slice(0, 8))}\n`)
+      }
+    } catch (err) { handleError(err) }
+  })
+
+docCmd
+  .command('show <id>')
+  .description('Show a workspace doc')
+  .action(async (id) => {
+    try {
+      const doc = await api(`/api/docs/${id}`)
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(doc, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log()
+        console.log(chalk.bold(doc.title || 'Untitled'))
+        console.log(chalk.gray(`id: ${doc.id}`))
+        if (doc.content && typeof doc.content === 'object') {
+          const text = JSON.stringify(doc.content)
+          console.log(chalk.gray(text.slice(0, 200) + (text.length > 200 ? '…' : '')))
+        }
+        console.log()
+      }
+    } catch (err) { handleError(err) }
+  })
+
+docCmd
+  .command('update <id>')
+  .description('Update a workspace doc')
+  .option('--title <text>', 'Doc title')
+  .option('--content <json>', 'Content as JSON string')
+  .option('--emoji <char>', 'Emoji')
+  .option('--parent <id>', 'Parent doc id')
+  .action(async function (id) {
+    const opts = this.opts()
+    try {
+      const patch = {}
+      if (opts.title !== undefined) patch.title = opts.title
+      if (opts.content !== undefined) {
+        try {
+          patch.content = typeof opts.content === 'string' ? JSON.parse(opts.content) : opts.content
+        } catch (_) {
+          return fail('--content must be valid JSON')
+        }
+      }
+      if (opts.emoji !== undefined) patch.emoji = opts.emoji
+      if (opts.parent !== undefined) patch.parentId = opts.parent
+      if (Object.keys(patch).length === 0) return fail('Provide at least one option to update')
+      await api(`/api/docs/${id}`, { method: 'PATCH', body: JSON.stringify(patch) })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Doc updated\n'))
+    } catch (err) { handleError(err) }
+  })
+
+docCmd
+  .command('delete <id>')
+  .description('Delete a workspace doc')
+  .action(async (id) => {
+    try {
+      await api(`/api/docs/${id}`, { method: 'DELETE' })
+      if (!runtimeQuietOutput) console.log(chalk.green('\n✓ Doc deleted\n'))
+    } catch (err) { handleError(err) }
+  })
+
+program
+  .command('folder create <name>')
+  .alias('mkdir')
+  .description('Create a folder in the workspace (Files tab)')
+  .action(async (name) => {
+    try {
+      const folder = await api('/api/folders', {
+        method: 'POST',
+        body: JSON.stringify({ name: String(name).trim() }),
+      })
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(folder, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Folder created') + `  ${chalk.bold(folder.name)}  ${chalk.gray(`(id: ${folder.id})\n`)}`)
+      }
+    } catch (err) { handleError(err) }
+  })
+
+program
+  .command('upload <path>')
+  .description('Upload a file to the workspace (optional: --folder <id>)')
+  .option('--folder <id>', 'Put the file in this folder id')
+  .action(async (pathArg, opts) => {
+    try {
+      await ensureAuth()
+      const filePath = resolve(pathArg)
+      if (!existsSync(filePath)) return fail(`File not found: ${filePath}`)
+      const form = new FormData()
+      form.append('file', createReadStream(filePath), { filename: basename(filePath) })
+      if (opts.folder) form.append('folderId', String(opts.folder).trim())
+      const headers = { ...authHeaders() }
+      delete headers['Content-Type']
+      const res = await fetch(`${getApiBase()}/api/files/upload`, {
+        method: 'POST',
+        headers: { ...headers, ...form.getHeaders() },
+        body: form,
+      })
+      const data = await res.json().catch(() => ({}))
+      if (!res.ok) throw new CliError(data.error ?? 'Upload failed', data.error ?? res.statusText)
+      if (isMachineOutput()) {
+        console.log(JSON.stringify(data, null, runtimeJsonOutput ? 2 : 0))
+      } else {
+        console.log(chalk.green('\n✓ Uploaded') + `  ${chalk.bold(data.name)}  ${chalk.gray(`→ ${data.storageUrl ?? data.id}\n`)}`)
+      }
+    } catch (err) { handleError(err) }
+  })
+
 program
   .command('state')
   .description('Print full workspace state as JSON')
   .action(async () => {
     try {
-      const state = await api('/api/state')
+      const state = await getState()
       console.log(JSON.stringify(state, null, 2))
     } catch (err) { handleError(err) }
   })
@@ -1115,4 +1888,39 @@ program
     console.log()
   })
 
+// ── shell completion ──────────────────────────────────────────────────────────
+
+const CLI_COMMANDS = [
+  'add', 'agent-token', 'agent-tokens', 'assign', 'assignee', 'assignees', 'board', 'boards',
+  'bucket', 'buckets', 'calendar', 'comment', 'complete', 'config', 'delete', 'doc', 'docs',
+  'do', 'doctor', 'files', 'folder', 'folders', 'invite', 'list', 'login', 'members', 'mkdir',
+  'move', 'open', 'reopen', 'requested', 'search', 'signup', 'state', 'update', 'upload', 'view', 'whoami',
+]
+
+program
+  .command('completion [shell]')
+  .description('Print shell completion script (bash or zsh). Add to your profile: wadah completion bash >> ~/.bashrc')
+  .action((shell) => {
+    const sh = (shell || process.env.SHELL || 'bash').toLowerCase()
+    if (sh.includes('zsh')) {
+      console.log(`# zsh completion for wadah
+_wadah() {
+  local cur
+  cur=\${words[CURRENT]}
+  reply=(${CLI_COMMANDS.join(' ')})
+}
+compctl -K _wadah wadah tm ow
+`)
+    } else {
+      console.log(`# bash completion for wadah
+_wadah_completion() {
+  local cur=\${COMP_WORDS[COMP_CWORD]}
+  local cmds="${CLI_COMMANDS.join(' ')}"
+  COMPREPLY=( $(compgen -W "$cmds" -- "$cur") )
+}
+complete -F _wadah_completion wadah tm ow
+`)
+    }
+  })
+
 program.parse()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-wadah",
-  "version": "1.0.6",
+  "version": "1.2.0",
   "description": "Open Wadah CLI — shared task board for humans and agents",
   "type": "module",
   "bin": {
@@ -9,13 +9,15 @@
     "tm": "cli.js"
   },
   "scripts": {
-    "start": "node cli.js"
+    "start": "node cli.js",
+    "test": "node --test test/cli.test.js"
   },
   "dependencies": {
     "@inquirer/prompts": "^8.3.0",
     "chalk": "^5.4.1",
     "commander": "^13.1.0",
     "conf": "^13.1.0",
+    "form-data": "^4.0.0",
     "node-fetch": "^3.3.2"
   }
 }

package/test/cli.test.js

@@ -0,0 +1,67 @@
+import { spawn } from 'node:child_process'
+import { test } from 'node:test'
+import { strict as assert } from 'node:assert'
+import { resolve, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const cliPath = resolve(__dirname, '../cli.js')
+
+function runCli(args) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(process.execPath, [cliPath, ...args], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      env: { ...process.env, TASK_MANAGER_TOKEN: '' },
+    })
+    let stdout = ''
+    let stderr = ''
+    child.stdout?.on('data', (d) => { stdout += d })
+    child.stderr?.on('data', (d) => { stderr += d })
+    child.on('close', (code) => resolvePromise({ code, stdout, stderr }))
+    child.on('error', reject)
+  })
+}
+
+test('wadah --help exits 0 and prints usage', async () => {
+  const { code, stdout } = await runCli(['--help'])
+  assert.equal(code, 0)
+  assert.match(stdout, /Open Wadah|Usage|Commands/)
+})
+
+test('wadah --version exits 0 and prints version', async () => {
+  const { code, stdout } = await runCli(['--version'])
+  assert.equal(code, 0)
+  assert.match(stdout, /\d+\.\d+\.\d+/)
+})
+
+test('wadah (no args) prints help or exits', async () => {
+  const { code, stdout, stderr } = await runCli([])
+  assert(code === 0 || code === 1)
+  const out = stdout + stderr
+  assert.match(out, /Usage|Commands|Open Wadah/)
+})
+
+test('wadah open --help shows open command help', async () => {
+  const { code, stdout } = await runCli(['open', '--help'])
+  assert.equal(code, 0)
+  assert.match(stdout, /open|List/)
+})
+
+test('wadah doctor runs without crashing', async () => {
+  const { code } = await runCli(['doctor'])
+  // Doctor may exit 0 or 1 depending on API/token; we only assert it doesn't throw
+  assert(code === 0 || code === 1)
+})
+
+test('wadah completion bash prints script', async () => {
+  const { code, stdout } = await runCli(['completion', 'bash'])
+  assert.equal(code, 0)
+  assert.match(stdout, /complete -F _wadah_completion/)
+  assert.match(stdout, /wadah tm ow/)
+})
+
+test('wadah completion zsh prints script', async () => {
+  const { code, stdout } = await runCli(['completion', 'zsh'])
+  assert.equal(code, 0)
+  assert.match(stdout, /compctl|_wadah/)
+})