diff --git a/AGENTS.md b/AGENTS.md
index 2b6c6f1b..b3f9ec03 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -20,6 +20,19 @@ This file exists for compatibility with tools that look for AGENTS.md.
 
 See CLAUDE.md "Visual Design System" section for full guidance.
 
+## Agent Warning: Interactive Commands
+
+**DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use.
+
+Use `bd update` with flags instead:
+```bash
+bd update <id> --description "new description"
+bd update <id> --title "new title"
+bd update <id> --design "design notes"
+bd update <id> --notes "additional notes"
+bd update <id> --acceptance "acceptance criteria"
+```
+
 ## Landing the Plane (Session Completion)
 
 **When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
diff --git a/AGENT_INSTRUCTIONS.md b/AGENT_INSTRUCTIONS.md
index 7d899913..0f501551 100644
--- a/AGENT_INSTRUCTIONS.md
+++ b/AGENT_INSTRUCTIONS.md
@@ -191,6 +191,15 @@ bd show bd-44 --json
 
 ## Agent Session Workflow
 
+**WARNING: DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use. Use `bd update` with flags instead:
+```bash
+bd update <id> --description "new description"
+bd update <id> --title "new title"
+bd update <id> --design "design notes"
+bd update <id> --notes "additional notes"
+bd update <id> --acceptance "acceptance criteria"
+```
+
 **IMPORTANT for AI agents:** When you finish making issue changes, always run:
 
 ```bash
diff --git a/cmd/bd/AGENTS.md b/cmd/bd/AGENTS.md
index df7a4af9..61e75b69 100644
--- a/cmd/bd/AGENTS.md
+++ b/cmd/bd/AGENTS.md
@@ -12,6 +12,19 @@ bd close <id>         # Complete work
 bd sync               # Sync with git
 ```
 
+## Agent Warning: Interactive Commands
+
+**DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use.
+
+Use `bd update` with flags instead:
+```bash
+bd update <id> --description "new description"
+bd update <id> --title "new title"
+bd update <id> --design "design notes"
+bd update <id> --notes "additional notes"
+bd update <id> --acceptance "acceptance criteria"
+```
+
 ## Landing the Plane (Session Completion)
 
 **When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.