docs: LUA-180 surface the post-deploy debug loop

ai-guide.mdx

@@ -24,6 +24,8 @@ Authenticate → lua init → Write Code → lua test → iterate → lua chat s
                     (Optional) lua integrations connect → Agent gets third-party tools instantly
 ```
 
+After **`lua init`**, the CLI surfaces a suggested build loop: **compile → test → chat (sandbox) → push and deploy**. Treat that sequence as your default checklist before iterating on agent code.
+
 ---
 
 ## 1. Authentication (PREREQUISITE)
@@ -138,7 +140,103 @@ project/
 
 ---
 
-## 3. Agent Configuration (LuaAgent)
+## 3. Debugging with `lua logs` (read this BEFORE you write tools)
+
+<Note>
+**This section is promoted to the top because every AI builder needs the post-deploy loop in their head before they write a single tool.** All `console.log`, `console.error`, etc. output from your tool code shows up in `lua logs`. The CLI also prints a `✨ Tip:` line at the end of every push/deploy/chat/sync/compile/test pointing at the right `lua logs --type X --limit N` command for what you just ran. Follow it.
+</Note>
+
+The single canonical post-deploy loop is:
+
+```
+lua push --auto-deploy → lua chat -m "test" → lua logs --type X --limit 10
+```
+
+For the full canonical guide, see [Debugging your agent — the post-deploy loop](/cli/debugging).
+
+### The "post-test-always-check" pattern
+
+After every `lua chat -m "test"`, immediately run:
+
+```bash
+lua logs --type agent_error --limit 5
+```
+
+If the count is **zero**, the test passed cleanly. If **non-zero**, fix the error before running another test message — most pipeline errors (billing, validation, LLM provider failures) don't surface in the chat response itself.
+
+The CLI helps by running a quiet `agent_error` probe automatically after every `lua chat` turn — when new errors fire, you'll see:
+
+```
+⚠️  2 new agent error(s) during this turn — run `lua logs --type agent_error --limit 2` to inspect.
+```
+
+Set `LUA_NO_HINTS=1` to silence all post-action hints.
+
+### Post-deploy verification recipe
+
+After deploying, always run this 3-line check:
+
+```bash
+lua push all --force --auto-deploy
+lua chat -m "verify deploy" -e production -t prod-verify --clear
+lua logs --type agent_error --limit 5  # should be empty
+```
+
+If step 3 returns entries timestamped after your deploy, **don't walk away** — read them and decide whether to roll back.
+
+<Warning>
+**Important:** `lua logs` returns **zero** results right after deploy until something executes. Generate traffic first, for example:
+
+```bash
+lua chat -e production -m "test"
+```
+
+Then inspect:
+
+```bash
+lua logs --type skill --limit 10
+```
+</Warning>
+
+### `lua logs` quick reference
+
+```bash
+# View all logs
+lua logs --type all --limit 50
+
+# Filter by type (the CLI suggests the right --type after each command)
+lua logs --type skill --name mySkill --limit 10
+lua logs --type job --name healthCheck --json
+lua logs --type webhook --limit 20
+lua logs --type agent_error --limit 10  # post-chat canary
+lua logs --type mcp --limit 20
+lua logs --type rag --limit 10
+lua logs --type mastra --limit 20
+
+# Filter by user (for user-reported issues)
+lua logs --type all --user-id user_abc123 --limit 50
+```
+
+### Filter types
+
+| Type | Description |
+|------|-------------|
+| `all` | All logs |
+| `skill` | Skill/tool executions |
+| `job` | Job executions |
+| `webhook` | Webhook executions |
+| `preprocessor` | PreProcessor executions |
+| `postprocessor` | PostProcessor executions |
+| `mcp` | MCP tool executions |
+| `mastra` | Agent runtime / LLM SDK / framework-level logs |
+| `rag` | Knowledge-base / RAG retrieval logs |
+| `user_message` | User messages |
+| `agent_response` | Agent responses |
+| `agent_error` | Pipeline errors — the signal to watch after a `lua chat` test |
+
+---
+
+## 4. Agent Configuration (LuaAgent)
 
 The main configuration lives in `src/index.ts`:
 
@@ -184,7 +282,7 @@ Communication style:
 
 ---
 
-## 4. Building Components
+## 5. Building Components
 
 ### Skills & Tools
 
@@ -302,7 +400,7 @@ const addDisclaimer = new PostProcessor({
 
 ---
 
-## 5. Testing Strategy
+## 6. Testing Strategy
 
 <Note>
 This is one of the most important sections. Understanding when to use `lua test` vs `lua chat` is critical.
@@ -465,7 +563,7 @@ lua chat -e production -m "Test message" -t prod-verify --clear
 
 ---
 
-## 6. Push vs Deploy
+## 7. Push vs Deploy
 
 <Warning>
 Understanding this distinction is critical. Many users confuse these commands.
@@ -510,9 +608,17 @@ lua deploy skill --name mySkill --set-version latest --force
 | `lua push` | Upload version to server (staging) |
 | `lua deploy` | Make that version live for all users |
 
+After `lua push` **without** `--auto-deploy`, code is **staged, not live**. The CLI says so explicitly — for example:
+
+```
+✨ Staged but NOT live yet. To make it active: lua deploy skill
+```
+
+Use `lua push … --auto-deploy` or run `lua deploy` explicitly before validating in production.
+
 ---
 
-## 7. Environment Variables
+## 8. Environment Variables
 
 ### Sandbox vs Production
 
@@ -540,42 +646,6 @@ Set environment variables **as needed** when code requires them.
 
 ---
 
-## 8. Debugging with `lua logs`
-
-<Note>
-**This is the core debugging command.** All `console.log`, `console.error`, etc. output appears here.
-</Note>
-
-Works for ALL request types: `lua test`, `lua chat`, production requests.
-
-```bash
-# View all logs
-lua logs --type all --limit 50
-
-# Filter by type
-lua logs --type skill --name mySkill --limit 10
-lua logs --type job --name healthCheck --json
-lua logs --type webhook --limit 20
-
-# Pagination
-lua logs --type all --limit 20 --page 2
-```
-
-### Log Types
-
-| Type | Description |
-|------|-------------|
-| `all` | All logs |
-| `skill` | Skill/tool executions |
-| `job` | Job executions |
-| `webhook` | Webhook executions |
-| `preprocessor` | PreProcessor executions |
-| `postprocessor` | PostProcessor executions |
-| `user_message` | User messages |
-| `agent_response` | Agent responses |
-
----
-
 ## 9. Sandbox Overrides
 
 When using `lua chat -e sandbox`, the following can be overridden with local compiled code **without needing to push/deploy**:
@@ -1003,6 +1073,9 @@ lua logs --type skill --name order-service --limit 10 --json
 ## Related Documentation
 
 <CardGroup cols={2}>
+  <Card title="Debugging Loop" icon="bug" href="/cli/debugging">
+    Canonical post-deploy debug loop and the active `agent_error` probe
+  </Card>
   <Card title="CLI Commands Reference" icon="terminal" href="/cli/overview">
     Complete CLI command documentation
   </Card>

cli/chat-command.mdx

@@ -424,8 +424,43 @@ lua chat -m "review @report.pdf and @notes.txt" -e sandbox
   </Accordion>
 </AccordionGroup>
 
+## Active log probe (`agent_error` after every turn)
+
+After every `lua chat` turn — interactive or `-m` non-interactive — the CLI runs a quiet `lua logs --type agent_error` probe scoped to the current session. The probe checks for **server-side pipeline errors that don't always surface in the chat response itself** (billing failures, schema validation failures, LLM provider errors, post-processor errors).
+
+**When the probe is silent**, no agent errors fired during your turn — you're clean.
+
+**When new errors fire**, the CLI prints a one-line warning at the end of the turn:
+
+```
+⚠️  2 new agent error(s) during this turn — run `lua logs --type agent_error --limit 2` to inspect.
+```
+
+**Empty response:** If the agent returns **no text** (empty stream), the CLI warns: `⚠️  The agent returned an empty response` and points you at `agent_error` and `runtime` logs so you can see what failed on the server.
+
+Run the suggested command verbatim to inspect the errors.
+
+To opt out (for example in CI that captures only command output), set `LUA_NO_HINTS=1`:
+
+```bash
+LUA_NO_HINTS=1 lua chat -m "test" -e production
+```
+
+### Debugging recipe
+
+```bash
+# Send one isolated test, then check for pipeline errors
+lua chat -m "test" -t debug-1 --clear && lua logs --type agent_error --limit 5
+```
+
+See [Debugging your agent — the post-deploy loop](/cli/debugging) for the complete flow.
+
 ## Troubleshooting
 
+<Note>
+**Debugging after a failed chat:** If a chat turn returns a wrong, empty, or error response, the CLI now automatically surfaces a count of `agent_error` logs that fired during that turn. To inspect them, run the suggested `lua logs --type agent_error --limit N` command. See [Debugging your agent — the post-deploy loop](/cli/debugging) for the canonical loop.
+</Note>
+
 <AccordionGroup>
   <Accordion title="No API key found">
     **Error:**
@@ -500,18 +535,18 @@ lua chat -m "review @report.pdf and @notes.txt" -e sandbox
 ## Related Commands
 
 <CardGroup cols={2}>
+  <Card title="Debugging Loop" icon="bug" href="/cli/debugging">
+    Canonical push → test → check flow + the active log probe
+  </Card>
+  <Card title="lua logs" icon="terminal" href="/cli/logs-command">
+    Inspect agent_error and tool execution logs
+  </Card>
   <Card title="lua test" icon="flask">
     Test individual tools with specific inputs
   </Card>
   <Card title="lua push" icon="upload">
     Deploy skills to server
   </Card>
-  <Card title="lua deploy" icon="rocket">
-    Publish version to production
-  </Card>
-  <Card title="lua compile" icon="gears">
-    Compile TypeScript code
-  </Card>
 </CardGroup>
 
 ## Next Steps