Add troubleshooting guide, fix sidebar consistency, retire support page#612
Add troubleshooting guide, fix sidebar consistency, retire support page#612
Conversation
The CLI Reference page was secretly a clickable page in the sidebar while
Features and Resources were just expandable headers — but they all looked
the same, so nobody realized CLI Reference was its own page. Demoted it
to a regular child item ("Overview") so all three categories behave
consistently.
While we were in there, we noticed `miren debug bundle` had no real docs
beyond a one-liner, and recommending it without mentioning sudo meant
people would get partial bundles. Rather than a standalone debug-bundle
page, we wrote a troubleshooting guide that walks through the whole
diagnostic funnel: doctor → logs → sandbox list → deploy history →
build logs → server logs → debug bundle → getting help. The debug bundle
docs live naturally at the end of that escalation path.
The support page was made redundant by the troubleshooting guide's
"Getting help" section, so we folded its links (Discord, GitHub Issues,
Roadmap) into the new page and removed it.
📝 WalkthroughWalkthroughThis pull request replaces docs/support.md with a new docs/troubleshooting.md and updates internal links from /support to /troubleshooting. It adds troubleshooting content and CLI reference link updates, adjusts sidebar items to remove support and add troubleshooting, updates the CLI reference front matter and link to the troubleshooting section, changes the bug report template to recommend using Comment |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Fix all issues with AI agents
In @.github/ISSUE_TEMPLATE/bug_report.yml:
- Around line 43-47: The bug report template's description currently instructs
users to run `sudo miren debug bundle` without warning that the resulting bundle
may contain secrets/PII; update the YAML under the description field to add a
brief redaction guidance paragraph telling users to review and remove sensitive
files/credentials before uploading, to prefer the non‑sudo fallback `miren debug
bundle` when possible, and to point to any internal docs or a short checklist
for common items to redact; ensure the new text is concise and appears
immediately before the existing "Tip: Run `sudo miren debug bundle`..." line so
reviewers see it when collecting logs.
In `@docs/docs/troubleshooting.md`:
- Around line 105-144: Add a short, prominent warning near the "## Gathering a
debug bundle" section (and optionally under "## Getting help") instructing users
to review and redact sensitive information before sharing bundles; reference the
command example `sudo miren debug bundle` so readers know it applies to those
artifacts, and give a brief checklist of what to redact (e.g., secrets, private
keys, API tokens, and personally identifiable information) and a pointer to
instructions for redaction or contacting support if unsure.
Strip environment variable values from docker inspect output in debug bundles — they commonly contain credentials and API keys. The Env key names are preserved but values are replaced with [REDACTED]. Add warnings to the troubleshooting guide and bug report template so users know to review bundle contents before sharing publicly.
There was a problem hiding this comment.
🤖 Fix all issues with AI agents
Before applying any fix, first verify the finding against the current code and
decide whether a code change is actually needed. If the finding is not valid or
no change is required, do not modify code for that item and briefly explain why
it was skipped.
In @.github/ISSUE_TEMPLATE/bug_report.yml:
- Around line 43-47: Update the description field to mention the non-sudo
fallback: add a brief sentence after the `sudo miren debug bundle` tip stating
that if users lack sudo permissions they can run `miren debug bundle` without
sudo (or with appropriate user-level permissions) and still collect logs, and
remind them to review and redact sensitive data; reference the existing
`description` block and the `sudo miren debug bundle` tip so reviewers can find
and edit that text.
🧹 Nitpick comments (1)
🤖 Fix all nitpicks with AI agents
Before applying any fix, first verify the finding against the current code and decide whether a code change is actually needed. If the finding is not valid or no change is required, do not modify code for that item and briefly explain why it was skipped. In @.github/ISSUE_TEMPLATE/bug_report.yml: - Around line 43-47: Update the description field to mention the non-sudo fallback: add a brief sentence after the `sudo miren debug bundle` tip stating that if users lack sudo permissions they can run `miren debug bundle` without sudo (or with appropriate user-level permissions) and still collect logs, and remind them to review and redact sensitive data; reference the existing `description` block and the `sudo miren debug bundle` tip so reviewers can find and edit that text..github/ISSUE_TEMPLATE/bug_report.yml (1)
43-47: Consider mentioning the non-sudo fallback.The redaction guidance is a good addition. However, users who cannot use
sudomay not realize they can still runmiren debug bundlewithout elevated privileges. Consider adding a brief note about this fallback option.- Tip: Run `sudo miren debug bundle` to collect system info, logs, and container state into a single archive for troubleshooting. Please review the bundle and redact any sensitive data (tokens, credentials, customer data) before attaching. + Tip: Run `sudo miren debug bundle` (or `miren debug bundle` without sudo) to collect system info, logs, and container state into a single archive for troubleshooting. Please review the bundle and redact any sensitive data (tokens, credentials, customer data) before attaching.🤖 Prompt for AI Agents
Before applying any fix, first verify the finding against the current code and decide whether a code change is actually needed. If the finding is not valid or no change is required, do not modify code for that item and briefly explain why it was skipped. In @.github/ISSUE_TEMPLATE/bug_report.yml around lines 43 - 47, Update the description field to mention the non-sudo fallback: add a brief sentence after the `sudo miren debug bundle` tip stating that if users lack sudo permissions they can run `miren debug bundle` without sudo (or with appropriate user-level permissions) and still collect logs, and remind them to review and redact sensitive data; reference the existing `description` block and the `sudo miren debug bundle` tip so reviewers can find and edit that text.
Summary
We were about to recommend
miren debug bundleto someone and realized: does this need sudo? (Yes.) Is that documented anywhere? (No.) And while looking at the docs to find where to put it, we discovered that the CLI Reference sidebar entry looks identical to Features and Resources but secretly links to a full page — the other two just expand. No visual cue, so you'd never know to click it.Fixed the sidebar so all three categories behave the same way — they expand, and the CLI Reference content lives as an "Overview" child page. Then instead of writing a standalone debug-bundle page, we built a proper troubleshooting guide that walks users through the whole diagnostic flow: start with
miren doctor, check logs and sandbox state, look at deploy history and build output, dig into server-level logs, and finally gather a debug bundle (with sudo!) when you need to escalate.The old support page was just three links to Discord, GitHub Issues, and the roadmap — all now covered by the troubleshooting page's "Getting help" section, so we retired it and updated the references in getting-started and labs.