🤖 docs: rewrite the aggregated API behavior reference in plain English

[ThomasK33]

Summary

Rewrite docs/reference/aggregated-api-behavior.md in plain English. The text follows ASD-STE100 (Simplified Technical English) about 80% of the time: short sentences, active voice, simple tenses, and one fact per sentence. Status codes, field names, commands, and code stay as they were.

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

Background

This reference page lists where coderworkspaces and codertemplates behave differently from usual Kubernetes resources: names, delete preconditions, the workspace resourceVersion, watch, server-side apply, and template builds. Most rules are in passive sentences that do not say which component acts. The rewrite names the actor (the server, Coder, or Kubernetes).

Implementation

• Rewrote the prose of the sections from the top through "Server-side apply". All code blocks and headings are byte-identical to main (checked with a script), so the anchors that other pages use still work.
• The "Template builds" section has only three small edits (a semicolon and two possessives). Draft 🤖 feat: reuse the earlier import when a CoderTemplate Update is retried #132 changes that section, so I kept the diff there small.
• Removed bold lead-ins ("Why:", "Equality only.") and wrote them as plain sentences or list items.
• No facts were added or removed. I found no stale claims on this page.

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 (workspace.go, watch.go, identity.go). It found one must-fix item in my first draft: the reason for rejecting aliases read as a statement about current behavior. That is fixed, together with its optional wording fixes ("served from", "even when", an unclear "it").
• Built the site locally with mkdocs and took screenshots.

Before:

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:39:07.349148Z	587af78	PR opened
🔒 Security Review	✅ Completed 2026-10-02T12:45:49.977978Z	587af78	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: 587af78f03

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.