diff --git a/lib/llm/index.js b/lib/llm/index.js
index 1252dc6..af2f125 100644
--- a/lib/llm/index.js
+++ b/lib/llm/index.js
@@ -63,6 +63,14 @@ sqlcmd -i ./scripts/query.sql
 1. Check current context: \`sqlcmd config current-context\`
 2. Show the context name and query to the user
 3. Ask for explicit confirmation before executing
+
+### Gotchas
+
+- When passing multi-line SQL starting with \`--\` comments as a positional argument, the CLI parses \`--\` as flag prefixes. Use the \`--query\` flag instead:
+  \`\`\`bash
+  sqlcmd query --query "-- this comment won't break
+  SELECT 1"
+  \`\`\`
 `,
   },
   gh: {