mirror of
https://github.com/coder/coder.git
synced 2026-09-21 20:51:01 +08:00
Nick Vigilante
ee7e7ecb74
Adds a reference glossary at `docs/reference/glossary.md` that defines
the Coder-specific terms and product names readers encounter across the
docs, and registers it in `docs/manifest.json` under **Reference**.
The page prioritizes the term collisions around "agent": it
disambiguates Coder Agents (the AI product), the workspace agent (the
in-workspace daemon), and the `coder_agent` Terraform resource with an
`[!IMPORTANT]` callout and cross-referenced entries. Every definition
was checked against the current docs, and every internal link is a
relative path that resolves in-repo.
Decision log and verification notes
**Scope of this PR**
- Creates the glossary page (`docs/reference/glossary.md`) and its
manifest entry.
- Adds glossary drift-prevention guidance in response to review feedback
(see **Follow-up from review** below).
- Out of scope (tracked separately): `Glossary: ` cross-link callouts
across the docs IA, the search-ranking boost, the workspace-daemon
rename decision, and the automated glossary lint guard
([DOCS-604](https://linear.app/codercom/issue/DOCS-604)).
**Follow-up from review (@bpmct)**
Ben flagged the risk that terms get introduced, renamed, or deprecated
without the glossary keeping up. Addressed in commit c12dea4 by pointing
both humans and tooling at the glossary:
- `docs/.style/content-guidelines.md`: a canonical Structural rule to
update the glossary in the same change that introduces, renames, or
deprecates a product or feature name.
- `.claude/skills/doc-check/SKILL.md`: doc-check flags terminology
changes that need a glossary update.
- `.claude/skills/write-docs/SKILL.md`: authoring updates the glossary
in the same change, plus a pre-handoff checklist item.
- `docs/.style/style-guide/word-choice.md`: cross-links the glossary as
the fuller product-name registry.
The single source of truth is the content-guidelines rule; the skills
reference it rather than restate it. The automated lint guard is
deliberately split into
[DOCS-604](https://linear.app/codercom/issue/DOCS-604): it touches
CI/build config and depends on the planned `Coder.ProductTerms` Vale
rule, so keeping it out holds this PR to a doc-only footprint. The four
files above are Markdown-only additions, validated in CI (markdownlint,
emdash, Vale advisory) rather than re-run locally.
**Source**
- Migrated and expanded from a generated glossary draft, then reconciled
against the live docs.
**Corrections made vs. the draft**
- AI Gateway and Agent Firewall are gated by the **AI Governance
Add-On** (Coder v2.32+), not plain Premium. Confirmed in
`docs/ai-coder/ai-governance.md`.
- Coder Tasks is framed as deprecated (12-month ESR, removed from new
releases starting v2.37; Coder Agents is the long-term replacement), per
`docs/ai-coder/tasks.md`.
- "Formerly AI Bridge" and "formerly Agent Boundaries" confirmed via the
rebranding-migration and agent-firewall pages; Agent Firewall backends
are `nsjail` (default) and `landjail`.
- OpenTofu is described as a custom Terraform binary that works but is
not officially supported, per `docs/admin/integrations/opentofu.md`.
- Premium markers were taken from `docs/manifest.json` (`"state":
["premium"]`).
**Local validation** (glossary page)
- `markdownlint-cli2`: 0 errors.
- `scripts/check_emdash.sh`: clean.
- Vale (`Coder` package): 0 errors, 0 warnings, 0 suggestions.
- All 120 links checked; every relative link resolves in-repo.
- 103 terms; no duplicate sibling headings (MD024 `siblings_only`).
**Reviewer note**
- This is a first-pass migration. Per the docs authoring skill, each
entry deserves a final accuracy pass before the page leaves draft. Flag
any term you want reworded, split, merged, or dropped.
> This PR was created with AI assistance (Coder Agents).