🤖 docs: rewrite the troubleshooting guide in plain English

[ThomasK33]

Summary

Rewrite docs/how-to/troubleshooting.md in plain English. The text follows ASD-STE100 (Simplified Technical English) about 80% of the time: short sentences, active voice, conditions before commands, and numbered steps. Quoted error messages, commands, flags, and file paths stay as they were.

This is the third PR of a plain-English docs series (#164, #165). It stands alone and is based on main.

Background

The troubleshooting page packs symptom, cause, and fix into long sentences with semicolons. A reader who is fixing a problem needs one fact per sentence.

Implementation

• Rewrote the prose only. No code block, command, flag, URL, or quoted error string changed. The heading Proxied requests fail with 503 and an x509 error, which other pages link to, is unchanged. One heading without links lost its contraction ("A component I didn't expect is running" is now "A component that you did not expect is running").
• Each symptom section now names the symptom, the cause, and the fix in separate sentences or list items.
• "may not" (in the sense "is not permitted to") is now "does not have permission to" or "cannot".

Factual fixes

1. The all mode ServiceUnavailable bullet said only that no eligible CoderControlPlane exists or its operator access is not ready. It now lists all eligibility rules from findEligibleControlPlanes: operator access enabled and ready, an operator token reference and a URL in the status, and no . in the name (internal/aggregated/coder/controlplane_provider.go:280-299).
2. The multiple eligible CoderControlPlane ... section suggested querying one namespace. That does not help when one namespace has more than one eligible control plane, because the server returns the same error for that namespace (internal/aggregated/coder/controlplane_provider.go:315-323). The section now says so, and says that a dedicated server in standalone mode needs all three flags.

Validation

• make docs-check (strict mkdocs build), markdownlint-cli2 0.18.1, cspell 8.19.4, and lychee pass on the pushed commit.
• A separate read-only auditor compared every changed claim with the original text and the code. It found one widened claim in my first draft of fix 2 (it said a dedicated server does not help either, which is wrong because standalone mode does not list control planes). That is fixed, together with its optional findings (standalone files are used "instead", "can reach only").
• Built the site locally with mkdocs and took screenshots.

Troubleshooting page, before:

Troubleshooting page, after:

Refs: no issue. Part of a plain-English docs pass.

---

Generated with xum • Model: anthropic:claude-opus-5-5 • Thinking: high

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-02T12:24:19.708079Z	0900d16	PR opened
🔒 Security Review	✅ Completed 2026-10-02T12:46:39.132669Z	0900d16	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[ThomasK33]

@codex security review

[chatgpt-codex-connector]

🛡️ Codex Security Review

Security review completed. No security issues were found in this pull request.

Reviewed commit: 0900d16cfc

View security finding report

Only the user who started this review can view the report in Codex.

ℹ️ About Codex security reviews in GitHub

This is an experimental Codex feature. Security reviews are triggered when:

• You comment "@codex security review"
• A regular code review gets triggered (for example, "@codex review" or when a PR is opened), and you’re opted in so security review runs alongside code review

Once complete, Codex will leave suggestions, or a comment if no findings are found.