feat: add product name variable system (Phase 1 — infrastructure)

.agents/references/terminology.md

@@ -4,6 +4,8 @@ Use this glossary everywhere you write about Warp. Keep definitions short, concr
 
 For the summary of the most critical terms (core features, Oz terms, terms to avoid), see the [Terminology standards](../../AGENTS.md#terminology-standards) section of AGENTS.md. This file is the full canonical reference.
 
+> **Product name variables**: Product names are defined in `src/data/vars.ts`. When writing new content, use `{VARS.WARP_AGENT_CLI}` (body prose) or `{{WARP_AGENT_CLI}}` (frontmatter) rather than hardcoding product names. See the ["Content variables" section of AGENTS.md](../../AGENTS.md#content-variables) for full usage instructions.
+
 ## Core product terms
 
 - **Agent** / **Agents** — Warp's AI feature for turning natural language into actions (answers, commands, code changes, and workflows).

.agents/skills/draft_docs/SKILL.md

@@ -85,6 +85,8 @@ Use source code to verify technical behavior, understand feature implementation,
 
 These rules are frequently violated by agents. Apply them carefully during drafting:
 
+- **Product name variables** — For any product name in `src/data/vars.ts`, use the variable instead of the hardcoded string. Add `import { VARS } from '@data/vars';` immediately after the frontmatter closing `---`. Use `{VARS.KEY}` in MDX prose (e.g. `{VARS.WARP_AGENT_CLI}` not "Oz CLI"). Use `{{TOKEN}}` directly in frontmatter YAML values (e.g. `title: "{{WARP_AGENT_CLI}} reference"`). Key vars: `WARP_AGENT_CLI`, `WARP_AUTOMATION_PLATFORM`, `WEB_APP`, `WEB_APP_URL`, `DASHBOARD`, `AGENT_MODE`, `WARP_DRIVE`. See `src/data/vars.ts` for the full list.
+
 - **Sentence case for all headings (H1–H4)** — Capitalize only the first word and proper feature names. ✅ `## How it works` ❌ `## How It Works`
 - **Descriptive, specific headings** — Beyond correct case, a heading should name the specific topic so readers and agents can scan the page and extract a self-contained answer. ✅ `## How key type affects billing and GitHub access` ❌ `## More details`
 - **Bold + dash format for list items** — `* **Term** - Description`, not `* Term: Description`
@@ -122,6 +124,7 @@ Before presenting the draft, verify against the quality checklist in `AGENTS.md`
 - [ ] Instructions include expected outcomes
 - [ ] Procedures are scannable: dense sections are split into numbered steps, short bullets, or concise subsections
 - [ ] UI surfaces and product terms use canonical names from `.agents/references/terminology.md`
+- [ ] Product names with a corresponding entry in `src/data/vars.ts` use the variable syntax (`{VARS.KEY}` in prose, `{{TOKEN}}` in frontmatter) — not hardcoded strings
 - [ ] If AEO-driven, the draft follows the AEO brief, uses source vocabulary naturally, and avoids duplicative or junk-drawer coverage
 - [ ] Images have descriptive alt text
 

.agents/skills/draft_feature_doc/SKILL.md

@@ -9,7 +9,7 @@ Draft a feature documentation page that combines conceptual and procedural conte
 
 ## Workflow
 
-Follow the workflow in `.warp/skills/draft_docs/SKILL.md`, using the **feature-doc template** at `.warp/templates/feature-doc.md`.
+Follow the workflow in `.agents/skills/draft_docs/SKILL.md`, using the **feature-doc template** at `.agents/templates/feature-doc.md`.
 
 ## Content type rules
 
@@ -31,6 +31,12 @@ All headings (H1–H4) must use **sentence case**: capitalize only the first wor
 - ❌ `## Configuring Your Environment`
 - ❌ `## Agent Mode Settings`
 
+## Product name variables
+
+For any product name in `src/data/vars.ts`, use the variable — never hardcode the string. The template already includes the `[VARS]` instruction block that shows exactly where to add the import. Key reminder:
+- Prose: `{VARS.WARP_AGENT_CLI}` (not "Oz CLI")
+- Frontmatter title/description: `{{WARP_AGENT_CLI}}`
+
 ## Existing examples
 
 Read 2-3 of these strong examples to match the existing pattern:

.agents/skills/review-docs-pr/SKILL.md

@@ -26,7 +26,8 @@ Focus on:
 3. **Content quality**: Check for clarity, accuracy, proper frontmatter, and appropriate use of headers/lists.
 4. **Code snippets**: Verify that any code examples, commands, or configuration snippets are correct and will work as documented. If you're unsure about technical details, use the `answer_question` skill to verify against the docs or search the source code.
 5. **Astro Starlight structure**: Verify `src/sidebar.ts` updates if files were added, moved, or renamed, and that redirects are added to vercel.json (redirects) when needed.
-6. **AEO/source-data fit**: For docs changes that target AEO, SEO, Peec recommendations, AI search prompts, or content gaps, check whether the PR has a clear source-data rationale, uses query vocabulary naturally, avoids junk-drawer coverage, and updates or links existing docs instead of creating duplicative content.
+6. **Product name variables**: Check whether any product names with a corresponding entry in `src/data/vars.ts` are hardcoded as literal strings instead of using `{VARS.KEY}` (prose) or `{{TOKEN}}` (frontmatter). Key strings to watch for: "Oz CLI", "Oz web app", "oz.warp.dev", "Oz dashboard", "Oz run". Flag as `⚠️ [IMPORTANT]` if a new file adds these without using the variable system. For existing files, flag as `💡 [SUGGESTION]`.
+7. **AEO/source-data fit**:
 
 Provide actionable, constructive feedback. Focus on documentation quality issues, not code bugs.
 

.agents/skills/style_lint/SKILL.md

@@ -60,6 +60,7 @@ python3 .agents/skills/style_lint/style_lint.py --all --fix --create-pr
 - **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.
+- **Hardcoded product name strings**: Product name strings that have a corresponding key in `src/data/vars.ts` but appear as literal text rather than variable syntax. Reports instances of known strings like "Oz CLI", "Oz web app", "oz.warp.dev", "Oz dashboard", "Oz run" (any value currently in `src/data/vars.ts`) in body prose and frontmatter. These are flagged as `⚠️ [IMPORTANT]` in PR context and reported (not auto-fixed) — they should use `{VARS.KEY}` in prose and `{{TOKEN}}` in frontmatter.
 
 ## Auto-fix behavior
 

.agents/skills/style_lint/style_lint.py

@@ -71,6 +71,20 @@
     (r"\bblocklist\b", "Use 'denylist'"),
 ]
 
+# Rename-sensitive product name strings that should use src/data/vars.ts variables
+# instead of being hardcoded. Keep this list in sync with vars.ts: only include
+# entries whose values are expected to change at a product rename. Stable feature
+# names (AGENT_MODE, WARP_DRIVE, etc.) are intentionally excluded.
+#
+# Each entry: (literal_string, var_key, suggestion)
+RENAME_SENSITIVE_VAR_STRINGS: List[Tuple[str, str, str]] = [
+    ("Oz CLI",       "WARP_AGENT_CLI",           "{VARS.WARP_AGENT_CLI} in prose or {{WARP_AGENT_CLI}} in frontmatter"),
+    ("Oz web app",   "WEB_APP",                  "{VARS.WEB_APP} in prose or {{WEB_APP}} in frontmatter"),
+    ("oz.warp.dev",  "WEB_APP_URL",              "{VARS.WEB_APP_URL} in prose or {{WEB_APP_URL}} in frontmatter"),
+    ("Oz dashboard", "DASHBOARD",                "{VARS.DASHBOARD} in prose or {{DASHBOARD}} in frontmatter"),
+    ("Oz run",       "PLATFORM_RUN",             "{VARS.PLATFORM_RUN} in prose or {{PLATFORM_RUN}} in frontmatter"),
+]
+
 # 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"),
@@ -92,7 +106,7 @@
 
 DEFAULT_SLACK_CHANNEL = os.environ.get("GROWTH_DOCS_SLACK_CHANNEL_ID", "")
 
-TERMINOLOGY_FILE = Path(".warp/references/terminology.md")
+TERMINOLOGY_FILE = Path(".agents/references/terminology.md")
 
 STANDARD_SCREENSHOT_WIDTHS = {"300px", "350px", "375px", "563px"}
 
@@ -852,6 +866,36 @@ def check_unrecognized_terms(lines: List[str], filepath: str, glossary: set) ->
     return issues
 
 
+def check_hardcoded_vars(lines: List[str], filepath: str) -> List[Issue]:
+    """Flag hardcoded product name strings that should use the vars system.
+
+    Strings listed in RENAME_SENSITIVE_VAR_STRINGS are expected to change at
+    product rename time. Using them as literals (instead of {VARS.KEY} in prose
+    or {{TOKEN}} in frontmatter) means they won't update when vars.ts changes.
+
+    Skips fenced code blocks and inline code spans so that CLI examples like
+    `oz.warp.dev` in a code fence are not flagged.
+    """
+    issues = []
+    in_code_block = False
+    for i, line in enumerate(lines, 1):
+        if line.strip().startswith("```"):
+            in_code_block = not in_code_block
+            continue
+        if in_code_block:
+            continue
+        # Strip inline code spans so backtick-wrapped references are not flagged
+        prose_line = re.sub(r"`[^`]+`", "", line)
+        for literal, var_key, suggestion in RENAME_SENSITIVE_VAR_STRINGS:
+            if literal in prose_line:
+                issues.append(Issue(
+                    filepath, i, "hardcoded-var",
+                    f'Hardcoded "{literal}" should use {suggestion} (see src/data/vars.ts)',
+                    "warning",
+                ))
+    return issues
+
+
 # Cache glossary terms once at module level
 _glossary_cache: Optional[set] = None
 
@@ -880,6 +924,7 @@ def run_all_checks(filepath: Path) -> List[Issue]:
     issues.extend(check_product_casing(lines, str(filepath)))
     issues.extend(check_oz_terms(lines, str(filepath)))
     issues.extend(check_deprecated_terms(lines, str(filepath)))
+    issues.extend(check_hardcoded_vars(lines, str(filepath)))
     issues.extend(check_unrecognized_terms(lines, str(filepath), _get_glossary()))
     return issues
 

.agents/templates/conceptual.md

@@ -1,9 +1,14 @@
 ---
-title: [Feature or concept name — sentence case. Title convention: noun or "About [subject]". The title field renders as the page H1; do not add a separate H1 in the body.]
+title: [Feature or concept name — sentence case. Title convention: noun or "About [subject]". The title field renders as the page H1; do not add a separate H1 in the body.
+  Use {{TOKEN}} syntax for any product names in src/data/vars.ts.]
 description: >-
   [1-2 sentences: what the concept/feature is + why it matters.
-  Write as a standalone summary for search results. Lead with user benefit.]
+  Write as a standalone summary for search results. Lead with user benefit.
+  Use {{TOKEN}} syntax for any product names in src/data/vars.ts.]
 ---
+[VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below.
+`import { VARS } from '@data/vars';`
+See AGENTS.md → Content variables for the full variable list and usage rules.]
 
 [Opening paragraph: What this feature/concept is and its primary benefit.
 1-3 sentences. Lead with what the user gains from understanding this.]

.agents/templates/faq.md

@@ -1,8 +1,12 @@
 ---
 description: >-
   [1-2 sentences: what topic area these FAQs cover.
-  Example: "Answers to common questions about cloud agents, billing, and environments."]
+  Example: "Answers to common questions about cloud agents, billing, and environments."
+  Use {{TOKEN}} syntax for any product names in src/data/vars.ts.]
 ---
+[VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below.
+`import { VARS } from '@data/vars';`
+See AGENTS.md → Content variables for the full variable list and usage rules.]
 
 # [Title — sentence case. Title convention: "[Feature] FAQs" or "Frequently asked questions"]
 

.agents/templates/feature-doc.md

@@ -1,8 +1,13 @@
 ---
 description: >-
   [1-2 sentences: what the feature does + primary user benefit.
-  Lead with the benefit, include key terms for SEO.]
+  Lead with the benefit, include key terms for SEO.
+  Use {{TOKEN}} syntax here for any product names that have a var in src/data/vars.ts.
+  Example: "Use the {{WARP_AGENT_CLI}} to run agents."]
 ---
+[VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below.
+`import { VARS } from '@data/vars';`
+See AGENTS.md → Content variables for the full variable list and usage rules.]
 
 # [Feature name — sentence case, capitalize only the first word and proper feature names]
 

.agents/templates/guide-page.md

@@ -10,6 +10,8 @@ description: >-
 [AEO GUIDANCE: If this guide is based on Peec, answer-engine prompts, search-query data, or AEO goals, create an AEO brief first using `.agents/skills/aeo_brief/SKILL.md`. Use the brief to preserve high-intent vocabulary naturally, translate awkward source-data phrasing into developer-friendly docs language, and decide whether this should be a new guide or an update to an existing page.]
 
 import VideoEmbed from '@components/VideoEmbed.astro';
+{/* VARS: Also add the line below if this guide references product names from src/data/vars.ts. Then use {VARS.KEY} in prose. Use {{TOKEN}} in frontmatter YAML values above. See AGENTS.md → Content variables. */}
+{/* import { VARS } from '@data/vars'; */}
 
 <VideoEmbed url="[YouTube or Loom URL — remove this block if no video]" />
 

.agents/templates/procedural.md

@@ -1,8 +1,12 @@
 ---
 description: >-
   [1-2 sentences: what the reader will accomplish.
-  Task-oriented: "Create and manage X" or "Configure Y for Z."]
+  Task-oriented: "Create and manage X" or "Configure Y for Z."
+  Use {{TOKEN}} syntax here for any product names that have a var in src/data/vars.ts.]
 ---
+[VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below.
+`import { VARS } from '@data/vars';`
+See AGENTS.md → Content variables for the full variable list and usage rules.]
 
 # [Task-oriented title — sentence case. Title convention: gerund, e.g., "Configuring X" or "Managing X"]
 

.agents/templates/quickstart.md

@@ -1,8 +1,12 @@
 ---
 description: >-
   [1-2 sentences: what the reader will accomplish + time estimate.
-  Example: "Learn how to run your first cloud agent in ~10 minutes."]
+  Example: "Learn how to run your first cloud agent in ~10 minutes."
+  Use {{TOKEN}} syntax here for any product names that have a var in src/data/vars.ts.]
 ---
+[VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below.
+`import { VARS } from '@data/vars';`
+See AGENTS.md → Content variables for the full variable list and usage rules.]
 
 # [Descriptive title — sentence case. Title convention: "[Feature] quickstart" or "Quickstart for [product]". Do NOT use a bare "Quickstart" — include the feature name.]
 

.agents/templates/reference.md

@@ -1,8 +1,12 @@
 ---
 description: >-
   [1-2 sentences: what is documented and how to use this reference.
-  Example: "Use the Oz CLI to run, configure, and manage agents from the terminal."]
+  Example: "Use the {{WARP_AGENT_CLI}} to run, configure, and manage agents from the terminal."
+  Use {{TOKEN}} syntax for any product names in src/data/vars.ts.]
 ---
+[VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below.
+`import { VARS } from '@data/vars';`
+See AGENTS.md → Content variables for the full variable list and usage rules.]
 
 # [Title — sentence case. Title convention: noun describing contents, e.g., "CLI commands", "Keyboard shortcuts"]
 

.agents/templates/troubleshooting.md

@@ -1,8 +1,12 @@
 ---
 description: >-
   [1-2 sentences describing common issues covered on this page.
-  Example: "Solutions for common issues with cloud agents, environments, and integrations."]
+  Example: "Solutions for common issues with cloud agents, environments, and integrations."
+  Use {{TOKEN}} syntax for any product names in src/data/vars.ts.]
 ---
+[VARS: Add this line immediately after the closing --- above if this page references any product names from src/data/vars.ts. Then use {VARS.KEY} for those names in the prose below.
+`import { VARS } from '@data/vars';`
+See AGENTS.md → Content variables for the full variable list and usage rules.]
 
 # [Title — sentence case. Title convention: "Troubleshooting [feature]" or "Known issues with [feature]"]