Skip to content

Add troubleshooting guide, fix sidebar consistency, retire support page#612

Merged
phinze merged 2 commits intomainfrom
phinze/add-troubleshooting-guide
Feb 17, 2026
Merged

Add troubleshooting guide, fix sidebar consistency, retire support page#612
phinze merged 2 commits intomainfrom
phinze/add-troubleshooting-guide

Conversation

@phinze
Copy link
Contributor

@phinze phinze commented Feb 16, 2026

Summary

We were about to recommend miren debug bundle to 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.

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.
@phinze phinze requested a review from a team as a code owner February 16, 2026 19:34
@coderabbitai
Copy link

coderabbitai bot commented Feb 16, 2026

📝 Walkthrough

Walkthrough

This 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 sudo for the debug bundle and to review/redact sensitive data, and updates labs.md to reference Discord for contact. It also adds JSON redaction of Docker inspect output in the debug bundle command.


Comment @coderabbitai help to get the list of available commands and usage tips.

Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link

@coderabbitai coderabbitai bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 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 sudo may not realize they can still run miren debug bundle without 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.

@phinze phinze merged commit e301828 into main Feb 17, 2026
12 checks passed
@phinze phinze deleted the phinze/add-troubleshooting-guide branch February 17, 2026 15:17
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants