docs: tighten prose across documentation

[ian-flores]

Summary

• Removed AI-isms and inflated language across all 14 doc files (docs/, README, CONTRIBUTING)
• Replaced copula avoidance patterns ("serves as", "stands as") with plain "is"/"are"
• Cut filler transitions, hedging, and unnecessary adverbs ("comprehensive", "automatically", "ensure that")
• Tightened prose to direct, declarative statements
• Standardized verb usage ("verify" instead of mixed "ensure/check/confirm")

No technical content, code blocks, YAML, commands, or document structure changed. Net zero line count (406 insertions, 406 deletions).

Test plan

• Verify all docs render correctly on GitHub
• Spot-check a few files for accuracy (no meaning changes)

[claude]

Claude finished @ian-flores's task —— View job

---

Review Complete

• Read review guidelines
• Get PR diff and review changes
• Submit review

The prose cleanup is solid — filler is removed, language is tighter, and no code/YAML/commands were touched. I found a few issues to flag (couldn't post inline comments due to permissions, so including them here):

---

Meaning Changes

1. docs/architecture.md:94 — "You can attribute database connections to specific products" introduces second-person, inconsistent with the rest of the section. Original passive form ("Database connections can be attributed…") fits better.

2. docs/architecture.md:370 — "It mirrors public repositories and hosts private packages" states these always happen. Original "It can mirror…and host…" correctly describes optional capabilities.

3. docs/guides/connect-configuration.md:93 — "Re-enabling Connect after suspension requires…" conveys obligation. Original "is as simple as…" conveys ease. Consider: "To re-enable Connect after suspension, remove the field or set it back to true:"

4. docs/guides/connect-configuration.md:79 — "Customer lacks a Connect license yet" is grammatically awkward ("lacks" and "yet" conflict). Consider: "Customer does not have a Connect license. Deploy the site without Connect and enable it once licensed."

5. docs/guides/connect-configuration.md:100-102 — "When to use" items changed from gerund form ("Permanently decommissioning…") to imperative ("Permanently decommission…"). The original gerund form reads better as situation descriptions under a "when to use" heading.

Ensure vs. Verify

Throughout the troubleshooting and other guides, "ensure" was globally replaced with "verify." These words have different meanings:

• Verify = confirm/check that something is true
• Ensure = make it so / take action if needed

In troubleshooting solution steps (e.g., "Ensure the metadata URL is accessible from pods"), the intent is to fix the problem, not just check for it. "Verify" is appropriate in diagnostic steps. Consider restoring "ensure" where the intent is corrective action.

Structural Changes

In several files (troubleshooting.md, authentication-setup.md, workbench-configuration.md), numbered debugging/troubleshooting steps (e.g., 1. **Verify group claim is present:**) were flattened to unnumbered paragraphs with bold headings. The numbered-list format communicates sequential order and is standard for procedures. Consider preserving numbered lists in troubleshooting sections.

---

[claude]

Prose cleanup looks good overall — the changes remove filler and tighten language across the board. I found a few spots where the edits subtly shift meaning or introduce structural changes. Detailed feedback is in the PR comment.