coder · nickvigilante · Aug 3, 2026 · Jul 10, 2026 · Jul 10, 2026 · Jul 10, 2026
diff --git a/.claude/skills/doc-check/SKILL.md b/.claude/skills/doc-check/SKILL.md
@@ -58,6 +58,10 @@ writing them.
   below.
 - **Renames or moves**: See [Renames and moves require redirects](#renames-and-moves-require-redirects)
   below.
+- **Terminology and the glossary**: Does the change introduce, rename, or
+  deprecate a Coder product or feature name? If so,
+  `docs/reference/glossary.md` needs a matching entry. See
+  [Glossary and terminology](#glossary-and-terminology) below.
 
 ## What not to comment on
 
@@ -126,6 +130,24 @@ a separate repo, not in this one. When a doc page is renamed or moved:
 Do not create a `docs/_redirects` file in this repo; that format isn't
 processed by coder.com.
 
+### Glossary and terminology
+
+The [glossary](../../../docs/reference/glossary.md) defines Coder-specific
+product and feature names, including collisions like the several senses of
+"agent". It drifts when the product's vocabulary changes and the page
+doesn't. Flag a glossary update when a change:
+
+- Adds a Coder product or feature name that isn't in the glossary yet.
+- Renames one. The entry should keep the former name (for example,
+  "previously named ...").
+- Deprecates one. The entry should say so and name the replacement.
+
+This is the canonical rule in
+[Structural rules](../../../docs/.style/content-guidelines.md#structural-rules);
+the content guidelines govern. Don't flag generic lowercase concepts or
+internal-only identifiers with no user-facing surface; they don't earn a
+glossary entry.
+
 ## Coder-specific patterns
 
 ### Callouts

diff --git a/.claude/skills/write-docs/SKILL.md b/.claude/skills/write-docs/SKILL.md
@@ -66,7 +66,10 @@ style.
    the Diátaxis framework in the [content guidelines](../../../docs/.style/content-guidelines.md#follow-the-diátaxis-framework).
    One outcome per page. New pages MUST be added to `docs/manifest.json` under
    the right section, and the documentation lands in the same change as the
-   feature.
+   feature. If the change introduces, renames, or deprecates a Coder product
+   or feature name, update the [glossary](../../../docs/reference/glossary.md)
+   in the same change (add, edit, or mark the entry) per the
+   [Structural rules](../../../docs/.style/content-guidelines.md#structural-rules).
 4. **Draft with deliberate pedagogy** (see patterns below).
 5. **Self-review and validate.** Apply the prose style guide with it open.
    Run `make lint/emdash`, markdownlint, and Vale. Run the commands and code
@@ -122,9 +125,9 @@ drift from the source.
 The canonical
 [Structural rules](../../../docs/.style/content-guidelines.md#structural-rules)
 cover the manifest entry, auto-generated content, Premium marking, renames
-and redirects, and the emdash ban. Read them for the exact wording; the
-pre-handoff checklist below turns them into pass/fail items. Two application
-notes the canonical rules do not spell out:
+and redirects, the emdash ban, and the glossary. Read them for the exact
+wording; the pre-handoff checklist below turns them into pass/fail items. Two
+application notes the canonical rules do not spell out:
 
 - On a rename, pick the new link target by the specific page each sentence
   promises, not just the section hub, and confirm moved anchors still resolve.
@@ -166,6 +169,9 @@ the whole series as a single review.
 - [ ] The content belongs in `docs/`; anything that does not was routed.
 - [ ] One outcome per page, correct Diátaxis mode, added to
       `docs/manifest.json`.
+- [ ] New, renamed, or deprecated product or feature names have a matching
+      `docs/reference/glossary.md` entry (a rename keeps the former name; a
+      deprecation names the replacement).
 - [ ] Prose style guide applied with it open; `make lint/emdash`,
       markdownlint, and Vale pass.
 - [ ] Inbound links resolve; renames have redirects in `coder/coder.com`.

diff --git a/docs/.style/content-guidelines.md b/docs/.style/content-guidelines.md
@@ -285,6 +285,23 @@ doc-check agent.
   semicolons, or periods, or restructure the sentence. For numeric
   ranges, use a plain hyphen (e.g., `0-100`). The rule is enforced by
   `make lint/emdash`.
+- **Terminology changes update the glossary.** When a change introduces,
+  renames, or deprecates a Coder product or feature name, update the
+  [glossary](../reference/glossary.md) in the same change, the way a
+  user-facing feature lands with its docs:
+  1. New name: add an entry with a short definition and a link to the
+     page that covers the term.
+  2. Rename: update the entry and record the former name (for example,
+     "previously named ...") so a reader who searches the old term still
+     lands in the right place.
+  3. Deprecation: mark the term deprecated and name its replacement.
+
+  A term earns an entry when it is a Coder-specific product or feature
+  proper noun, or a word that collides with another Coder meaning (for
+  example, the several senses of "agent"). Generic lowercase concepts and
+  internal-only identifiers with no user-facing surface do not. This is
+  what keeps the glossary from drifting as the product's vocabulary
+  changes.
 
 ## What does not belong in the docs
 

diff --git a/docs/.style/style-guide/word-choice.md b/docs/.style/style-guide/word-choice.md
@@ -40,6 +40,10 @@ It reads as a misspelling of the product name.
 
 *Enforced by `Coder.ProductTerms` (planned).*
 
+The [glossary](../../reference/glossary.md) is the fuller registry of these names and disambiguates collisions like the several senses of "agent".
+When you add, rename, or deprecate a product or feature name, update the glossary in the same change.
+The planned `Coder.ProductTerms` rule and the glossary should draw on one shared term list.
+
 ## Brand names
 
 Use the canonical casing for third-party brand and product names.

diff --git a/docs/manifest.json b/docs/manifest.json
@@ -1553,6 +1553,11 @@
 			"path": "./reference/index.md",
 			"icon_path": "./images/icons/notes.svg",
 			"children": [
+				{
+					"title": "Glossary",
+					"description": "Definitions of Coder terms and product names",
+					"path": "./reference/glossary.md"
+				},
 				{
 					"title": "REST API",
 					"description": "Learn how to use Coderd API",