docs: LUA-180 surface the post-deploy debug loop#14
Open
Conversation
Wave 1 Agent E for LUA-180 ("Make post-deploy diagnosis easier with
lua logs"). Pairs with the CLI changes that add centralized
writeTip()/writeNextStep() hints, the active agent_error probe in
lua chat, and contextual lua logs --type X --name Y suggestions in
push/deploy error paths.
Surface the canonical debug loop wherever AI builders and human
users land:
- cli/debugging.mdx: rewritten as the canonical "post-deploy loop"
page. Adds the 5-step push -> test -> check loop, the
lua test vs lua chat vs lua logs decision matrix, the full 11-type
--type filter table (skill, webhook, job, preprocessor,
postprocessor, mcp, mastra, rag, user_message, agent_response,
agent_error), the auto agent_error probe callout, signal-vs-noise
guidance for log icons, and the post-deploy verification recipe.
Preserves console.log debugging patterns and common-bug entries.
- cli/logs-command.mdx: adds "When to run lua logs" (after chat,
after push, when investigating a user issue), inline
agent_error vs mastra/runtime distinction, the post-deploy
verification recipe, --user-id flag, and a cross-link to the
debugging loop.
- cli/chat-command.mdx: adds an "Active log probe" subsection
documenting the quiet agent_error probe, a debugging callout in
Troubleshooting, the chat -m && lua logs recipe, and the
LUA_NO_HINTS=1 escape hatch.
- ai-guide.mdx: promotes the Debugging section from #8 to #3
(immediately after lua init) so AI builders see it before they
write their first tool. Adds the post-test-always-check pattern,
the post-deploy verification recipe, --user-id usage, the full
filter-type table, and renumbers sections 4-8 accordingly.
- getting-started/quick-start.mdx: adds a final "Test and verify"
step (lua chat -m + lua logs) so first-time builders learn the
verify habit immediately.
- cli/non-interactive-mode.mdx: adds a CI-friendly post-deploy
verification recipe using --ci push, --ci chat, and a jq-based
agent_error count check, plus LUA_NO_HINTS=1 guidance for CI.
- mcp-for-builders.mdx: fixes the production MCP tool reference -
the public docs MCP exposes search_lua_cli and
query_docs_filesystem_lua_cli (verified against the live
docs.heylua.ai/mcp endpoint), not the previously documented
get_page_lua_cli which never existed.
- docs.json: adds cli/debugging to the CLI Commands sidebar
immediately after cli/logs-command.
Refs LUA-180.
Made-with: Cursor
…fic-first, active probe docs Made-with: Cursor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Companion docs PR for LUA-180. Sibling CLI PR: lua-ai-global/lua-core-services#288.
Goal: make sure users (especially LLM builders running `lua chat -m`) and AI agents reading the docs MCP can find the optimal post-deploy debug flow. The single canonical loop is `lua push --auto-deploy → lua chat -m "test" → lua logs --type X --limit 10`.
Files touched
Coordination with PR #286 (logs schema rename)
`mastra` is kept in the filter-type table here because PR #286 (`chore/consolidate-log-source-types`) is the canonical rename of `mastra` → `runtime`. Updating it here would create false drift. After #286 merges, a small follow-up will rename `mastra` → `runtime` across these doc surfaces in one mechanical commit.
Test plan
Related
Made with Cursor
Note
Low Risk
Docs-only changes that reorganize and expand guidance around post-deploy verification and log inspection; low implementation risk beyond potential broken links or confusing command examples.
Overview
Elevates a single canonical post-deploy workflow (
lua push --auto-deploy → lua chat -m "test" → lua logs) across the docs, emphasizing the "always checkagent_error" pattern, staged-vs-live semantics afterlua push, and the new per-turnagent_errorprobe + opt-out viaLUA_NO_HINTS=1.Rewrites
cli/debugging.mdxinto the primary "post-deploy loop" guide and threads it throughai-guide.mdx,cli/chat-command.mdx,cli/logs-command.mdx,getting-started/quick-start.mdx, andcli/non-interactive-mode.mdx(including a CI-friendly verification recipe that fails builds on non-zeroagent_error).Updates navigation (
docs.json) to includecli/debugging, and corrects MCP docs (mcp-for-builders.mdx) to reference the live toolquery_docs_filesystem_lua_cliinstead ofget_page_lua_cli.Reviewed by Cursor Bugbot for commit 0328d8e. Bugbot is set up for automated code reviews on this repo. Configure here.