docs: agent-facing deploy-failure auto-debug guide + llms.txt reference (Task #69)

[mastermanas805]

What

Make the deploy-failure auto-debug path discoverable by AI agents from llms.txt. When an agent (Claude Code, curl, MCP) hits a failed deploy, it can now learn HOW to self-recover — read the classified cause, fix, redeploy — directly from the LLM index.

Why

A failed deploy already classifies its cause and serves it back over HTTP (GET /api/v1/deployments/:id/events → reason + last_lines + hint), but nothing in llms.txt told agents this surface exists. Agents were left guessing on a build failure. This closes that gap.

Changes

• New docs page docs/troubleshooting-deploys.md — served at https://instanode.dev/docs#troubleshooting-deploys (single-page docs anchor) and https://instanode.dev/docs/troubleshooting-deploys.md (markdown mirror). Agent-facing, imperative. Covers:
  • The auto-debug loop: GET /api/v1/deployments/:id (status + error_message) → GET /api/v1/deployments/:id/events (reason, exit_code, last_lines = build-pod log tail, hint) → fix Dockerfile/tarball/port/env → POST /deploy/:id/redeploy (or redeploy=true on /deploy/new with the same name) → re-poll. Live build: GET /deploy/:id/logs (SSE).
  • The thinner anonymous-stacks path: GET /api/v1/stacks/:slug (status + raw error) + GET /stacks/:slug/logs/:svc; explicitly notes there is no /events autopsy for anon stacks.
  • Honest caveats: failure email delivery blocked (use /events + dashboard autopsy panel, not email), "diagnostics pending" window, thinner runtime crash-loop diagnostics.
• llms.txt: new "Debugging a failed deploy (agent self-recovery)" section + md-mirror entry under the text-only routes list.
• Renumbered later docs order: frontmatter (claim 6, auth 7, limits 8, machine-readable 9) so the troubleshooting page slots after deploy/stacks.

Accuracy

Every endpoint path verified against the live api source (deploy.go / stack.go / router.go): /api/v1/deployments/:id, /api/v1/deployments/:id/events, /deploy/:id/logs, /deploy/:id/redeploy, /stacks/:slug, /stacks/:slug/logs/:svc. No invented fields. Source material: InstaNode-dev/docs ci/02-FAILURE-DIAGNOSIS-AND-AUTODEBUG.md.

Out of scope (separate agent)

The instanode-web/public/llms.txt fallback mirror + any new llms-contract CI marker (fetch-content.mjs requireMarkers / llmsContract.test.ts) are handled separately. Note: this content-repo llms.txt already carries all four current requireMarkers, so the build's lock-step sync is not blocked — this reference will flow to the live llms.txt on the next instanode-web build.

🤖 Generated with Claude Code