diff --git a/.agents/references/terminology.md b/.agents/references/terminology.md
index 17bf101a..8c3dd203 100644
--- a/.agents/references/terminology.md
+++ b/.agents/references/terminology.md
@@ -186,6 +186,7 @@ For the summary of the most critical terms (core features, Oz terms, terms to av
 - ❌ "Oz is running" → Use "An agent is running" or "A run is in progress"
 - ❌ "AI agents" → Use "agents" (the "AI" prefix is redundant)
 - ❌ "Ambient Agents" / "ambient agents" → Use "Cloud Agents" / "cloud agents" ("ambient" is no longer a product term; acceptable only in code identifiers like `AmbientAgentConfig`)
+- ❌ "agent identity" / "agent identities" → Use "agent," "agents," or "cloud agent(s)" in user-facing copy. Use legacy API names such as `agent_identity_uid` or `/agent/identities` only when documenting the exact field, path, or compatibility behavior.
 
 ## Platform terms
 
diff --git a/.agents/skills/style_lint/SKILL.md b/.agents/skills/style_lint/SKILL.md
index 188c2a84..010e55ef 100644
--- a/.agents/skills/style_lint/SKILL.md
+++ b/.agents/skills/style_lint/SKILL.md
@@ -12,12 +12,12 @@ Scan Warp Astro Starlight documentation for formatting and terminology issues de
 From the docs repo root:
 
 ```bash
-python3 .warp/skills/style_lint/style_lint.py
+python3 .agents/skills/style_lint/style_lint.py
 ```
 
 ### Options
 
-- `--all`: Scan all markdown files in `docs/` (default)
+- `--all`: Scan all markdown files in `src/content/docs/` (default)
 - `--changed`: Scan only files changed in the current branch (fast, for PR workflows)
 - `--fix`: Auto-fix high-confidence issues (optional, off by default)
 - `--create-pr`: Create a branch and PR with auto-fixes (requires `gh` CLI, implies `--fix`)
@@ -28,13 +28,13 @@ python3 .warp/skills/style_lint/style_lint.py
 ### Quick check on changed files:
 
 ```bash
-python3 .warp/skills/style_lint/style_lint.py --changed
+python3 .agents/skills/style_lint/style_lint.py --changed
 ```
 
 ### Full audit with auto-fix and PR:
 
 ```bash
-python3 .warp/skills/style_lint/style_lint.py --all --fix --create-pr
+python3 .agents/skills/style_lint/style_lint.py --all --fix --create-pr
 ```
 
 ## What it checks
@@ -52,7 +52,7 @@ python3 .warp/skills/style_lint/style_lint.py --all --fix --create-pr
 ### Terminology checks
 
 - **Product name casing**: "Warp Terminal" (→ "Warp"), "agent mode" (→ "Agent Mode"), "warp drive" (→ "Warp Drive"), "codebase context" (→ "Codebase Context"), "agent management panel" (→ "Agent Management Panel")
-- **Oz terms to avoid**: "Oz agent", "Oz cloud agent", "Oz subagent", "Oz conversation", "Ozzies", "Deploying an Oz", "The Oz Agent", "Oz is running", "AI agents"
+- **Oz terms to avoid**: "agent identity", "agent identities", "Oz agent", "Oz cloud agent", "Oz subagent", "Oz conversation", "Ozzies", "Deploying an Oz", "The Oz Agent", "Oz is running", "AI agents"
 - **Deprecated terminology**: "whitelist" (→ "allowlist"), "blacklist"/"blocklist" (→ "denylist")
 - **External product names**: "Github" (→ "GitHub"), "github actions" (→ "GitHub Actions"), "MacOS" (→ "macOS"), "A.I." (→ "AI")
 - **Unrecognized terms** (warning): Bolded terms that look like product names but aren't in `terminology.md`. Flags candidates for glossary addition — not errors, just suggestions.
@@ -76,4 +76,4 @@ Requires Python 3.7+. Optional: `requests` (for Slack notifications), `gh` CLI (
 For scheduled cloud agent runs:
 1. Configure the environment with the docs repo
 2. Set the `SLACK_BOT_TOKEN` secret in the environment (for `--slack-notify`)
-3. Run: `python3 .warp/skills/style_lint/style_lint.py --all --fix --create-pr --slack-notify`
+3. Run: `python3 .agents/skills/style_lint/style_lint.py --all --fix --create-pr --slack-notify`
diff --git a/.agents/skills/style_lint/style_lint.py b/.agents/skills/style_lint/style_lint.py
index 644ef86b..671654f4 100644
--- a/.agents/skills/style_lint/style_lint.py
+++ b/.agents/skills/style_lint/style_lint.py
@@ -73,6 +73,8 @@
 
 # Oz terms to avoid (case-insensitive patterns)
 OZ_TERMS_TO_AVOID = [
+    (r"\bagent identities\b", "Use 'agents' or 'cloud agents' unless referring to legacy API names in code"),
+    (r"\bagent identity\b", "Use 'agent' or 'cloud agent' unless referring to legacy API names in code"),
     (r"\bOzzies\b", "Use 'agents', 'instances', or 'subagents'"),
     (r"\bDeploying an Oz\b", "Use 'Deploying an agent'"),
     (r"\bThe Oz Agent\b", "Use 'the agent' or 'the Warp Agent'"),
diff --git a/AGENTS.md b/AGENTS.md
index be218c56..bd352a9c 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -634,6 +634,7 @@ Product feature names retain their standard capitalization. Match the exact casi
 - ❌ "AI agents" → Use "agents" (the "AI" prefix is redundant)
 - ❌ "Ambient Agents" / "ambient agents" → Use "Cloud Agents" / "cloud agents" ("ambient" is no longer a product term)
 - ❌ "Agent Modality" or "agent modality" → Use "Terminal and Agent modes" (this was an internal name, not user-facing)
+- ❌ "agent identity" / "agent identities" → Use "agent," "agents," or "cloud agent(s)" in user-facing copy. Use legacy API names such as `agent_identity_uid` or `/agent/identities` only when documenting the exact field, path, or compatibility behavior.
 
 ### Technical terms
 - **AI** (not "A.I.")
diff --git a/developers/agent-api-openapi.yaml b/developers/agent-api-openapi.yaml
index d032b3f5..40de5497 100644
--- a/developers/agent-api-openapi.yaml
+++ b/developers/agent-api-openapi.yaml
@@ -1779,7 +1779,9 @@ components:
           x-go-type-skip-optional-pointer: false
         agent_identity_uid:
           type: string
-          description: "Optional agent identity UID to use as the execution principal for the run.\nThis is only valid for runs that are team owned. \n"
+          description: |
+            Optional cloud agent UID to use as the execution principal for the run.
+            This legacy field name is only valid for team-owned runs.
         conversation_id:
           type: string
           description: |