chore(docs): clean docs

Author: bgagent

docs/abca-plugin/README.md

@@ -25,8 +25,8 @@ Or add to your project's `.claude/settings.json`:
 | `/setup` | First-time setup, prerequisites | Walk through prerequisites, toolchain, and first deployment |
 | `/deploy` | Deploy, diff, destroy | Deploy, diff, or destroy the CDK stack |
 | `/onboard-repo` | Add a repository | Onboard a GitHub repo via Blueprint CDK construct |
-| `/submit-task` | Submit a coding task | Submit tasks with prompt quality guidance and cost controls (supports quick mode) |
-| `/troubleshoot` | Debug, errors, failures | Diagnose build, deployment, auth, and task execution issues |
+| `/submit-task` | Submit a coding task | Submit tasks with prompt quality guidance and cost controls (supports quick mode, `--trace`) |
+| `/troubleshoot` | Debug, errors, failures | Diagnose build, deployment, auth, and task execution issues (supports `--verbose`) |
 | `/status` | Status, health check | Check stack health, running tasks, and recent history |
 
 ### Agents
@@ -38,7 +38,7 @@ Or add to your project's `.claude/settings.json`:
 
 ### Hook
 
-- **SessionStart** — Advertises available skills and agents so Claude can proactively suggest them when your request matches.
+- **SessionStart** — Advertises available skills, agents, and interactive task commands (`watch`, `nudge`, `trace`, `webhook`) so Claude can proactively suggest them when your request matches.
 
 ## Plugin Structure
 

docs/abca-plugin/hooks/hooks.json

@@ -3,7 +3,7 @@
     "SessionStart": [
       {
         "type": "prompt",
-        "prompt": "The ABCA plugin is active. Available skills:\n- /setup — first-time setup walkthrough\n- /deploy — deploy, diff, or destroy the CDK stack\n- /onboard-repo — add a GitHub repository\n- /submit-task — submit a coding task (guided or quick mode)\n- /troubleshoot — diagnose deployment, auth, or task issues\n- /status — platform health check (stack, tasks, build)\n\nAvailable agents: cdk-expert (CDK infrastructure), agent-debugger (task failure investigation).\n\nSuggest relevant skills when the user's request matches."
+        "prompt": "The ABCA plugin is active. Available skills:\n- /setup — first-time setup walkthrough\n- /deploy — deploy, diff, or destroy the CDK stack\n- /onboard-repo — add a GitHub repository\n- /submit-task — submit a coding task (guided or quick mode)\n- /troubleshoot — diagnose deployment, auth, or task issues\n- /status — platform health check (stack, tasks, build)\n\nAvailable agents: cdk-expert (CDK infrastructure), agent-debugger (task failure investigation).\n\nInteractive task commands (suggest when user is monitoring or steering a running task):\n- bgagent watch <task-id> — stream progress events in real time\n- bgagent nudge <task-id> \"<message>\" — steer the agent mid-run\n- bgagent trace download <task-id> — download full execution trace\n- bgagent webhook create/list/revoke — manage webhook integrations\n- --trace flag on submit — enable detailed tracing for a task\n- --verbose flag — HTTP debug output on any command\n\nSuggest relevant skills when the user's request matches."
       }
     ]
   }

docs/abca-plugin/skills/status/SKILL.md

@@ -50,3 +50,5 @@ Build:    [PASS | FAIL with error summary]
 ```
 
 If the CLI isn't configured, note this and suggest running the `setup` skill.
+
+**Tip:** For real-time streaming of a specific task's progress, suggest `bgagent watch <TASK_ID>` instead of polling status.

docs/abca-plugin/skills/submit-task/SKILL.md

@@ -103,6 +103,7 @@ node cli/lib/bin/bgagent.js submit \
 - `--max-turns N` — Turn limit (1-500)
 - `--max-budget N` — USD cost limit ($0.01-$100)
 - `--idempotency-key KEY` — Deduplication key for safe retries
+- `--trace` — Enable detailed tracing (4 KB preview cap + full NDJSON trajectory upload to S3)
 - `--wait` — Poll until terminal status
 - `--output json|text` — Output format
 
@@ -122,12 +123,26 @@ curl -X POST "$API_URL/tasks" \
   }'
 ```
 
-## Step 6: Monitor
+## Step 6: Monitor and Interact
 
-After submission, show how to check status:
+After submission, show how to monitor and steer the task:
 ```bash
+# Watch progress in real time (adaptive polling, auto-exits on terminal state)
+node cli/lib/bin/bgagent.js watch <TASK_ID>
+
+# Check status snapshot
 node cli/lib/bin/bgagent.js status <TASK_ID>
+
+# Steer the agent mid-run (combined-turn acknowledgement)
+node cli/lib/bin/bgagent.js nudge <TASK_ID> "Focus on the auth module first"
+
+# View event log
 node cli/lib/bin/bgagent.js events <TASK_ID>
+
+# Download execution trace (requires --trace on submit)
+node cli/lib/bin/bgagent.js trace download <TASK_ID>
+
+# List running tasks
 node cli/lib/bin/bgagent.js list --status RUNNING
 ```
 

docs/abca-plugin/skills/troubleshoot/SKILL.md

@@ -176,13 +176,21 @@ aws cloudformation describe-stacks --stack-name backgroundagent-dev --query 'Sta
 # Stack outputs
 aws cloudformation describe-stacks --stack-name backgroundagent-dev --query 'Stacks[0].Outputs' --output table
 
-# Task status
-node cli/lib/bin/bgagent.js status <TASK_ID>
+# Task status (use --verbose for HTTP-level debug output)
+node cli/lib/bin/bgagent.js --verbose status <TASK_ID>
 node cli/lib/bin/bgagent.js events <TASK_ID> --output json
 
+# Watch task progress in real time
+node cli/lib/bin/bgagent.js watch <TASK_ID>
+
+# Download full execution trace (task must have been submitted with --trace)
+node cli/lib/bin/bgagent.js trace download <TASK_ID>
+
 # List running tasks
 node cli/lib/bin/bgagent.js list --status RUNNING
 
 # Build health
 mise run build
 ```
+
+**Tip:** Add `--verbose` to any `bgagent` command to see the full HTTP request/response cycle on stderr. This is the fastest way to diagnose auth, network, or API contract issues.