🤖 docs: rewrite tutorials and the controller and MCP guides in plain English

[ThomasK33]

Summary

Rewrite the tutorials and two how-to guides in plain English: docs/tutorials/getting-started.md, docs/tutorials/deploy-coderprovisioner.md, docs/tutorials/deploy-with-argocd.md, docs/how-to/deploy-controller.md, and the setup part of docs/how-to/mcp-server.md. The text follows ASD-STE100 (Simplified Technical English) about 80% of the time: short sentences, active voice, conditions before commands, numbered steps, and warnings before the action. Kubernetes and Coder terms, field names, commands, and code stay as they were.

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

Background

The guides are accurate but dense. Several sentences join a rule, a reason, and an exception with semicolons or colons. Plain English is easier to follow during a procedure and easier to translate.

Implementation

• Rewrote the prose only. No code block, command, YAML, flag, field name, or URL changed. Headings that other pages link to are unchanged (#5-clean-up-optional, #connect-an-external-postgresql-database). One heading without links changed: "Want everything instead?" is now "Run all components instead".
• The cleanup step of "Deploy a Coder Control Plane" now shows the CRD and namespace deletion risks as a warning before the commands, not as a note after them.
• The "Request rules" section of mcp-server.md is byte-identical, so this PR does not conflict with 🤖 deps: bump Coder SDK to v2.37.3 #163, which edits that section.
• Split long rules into lists, for example the spec.database rules and the state while the database Secret is missing.

Factual fixes

1. docs/how-to/mcp-server.md said that the mcp container exits if --mcp-token-file is missing, unreadable, empty, or too short. It also exits if the token contains whitespace (internal/app/mcpapp/http.go:105-106). The list now includes that case.

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 no meaning changes. I applied its optional wording fixes ("reachable", "appears as", "running in namespace argocd") and the whitespace gap above.
• Built the site locally with mkdocs and took screenshots.

"Deploy a Coder Control Plane", before:

"Deploy a Coder Control Plane", after:

"Deploy the controller", 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:20:00.623980Z	bb8dc22	PR opened
🔒 Security Review	✅ Completed 2026-10-02T12:47:33.542946Z	bb8dc22	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: bb8dc22ef5

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.