pulumi
diff --git a/‎.claude/commands/brand-vale-sync/SKILL.md‎
Lines changed: 67 additions & 0 deletions b/‎.claude/commands/brand-vale-sync/SKILL.md‎
Lines changed: 67 additions & 0 deletions
diff --git a/‎.claude/commands/glow-up.md‎
Lines changed: 3 additions & 3 deletions b/‎.claude/commands/glow-up.md‎
Lines changed: 3 additions & 3 deletions
diff --git a/‎.github/workflows/brand-style-sync.yml‎
Lines changed: 79 additions & 0 deletions b/‎.github/workflows/brand-style-sync.yml‎
Lines changed: 79 additions & 0 deletions
diff --git a/‎AGENTS.md‎
Lines changed: 2 additions & 2 deletions b/‎AGENTS.md‎
Lines changed: 2 additions & 2 deletions
@@ -0,0 +1,67 @@
+---
+name: brand-vale-sync
+description: Weekly drift check of the offline Vale mirror (styles/Pulumi/) against the Pulumi brand guide served by the brand MCP server, with deprecated/retired terms as the priority. Opens a draft PR when the mirror has fallen behind; updates only the sync manifest when it hasn't. Invoked by the brand-style-sync workflow; also user-invocable for an on-demand check.
+---
+
+# Brand → Vale sync review
+
+The Vale rules under `styles/Pulumi/` are an **offline mirror** of the
+mechanically enforceable subset of the Pulumi brand guide. The brand guide —
+served by the **`pulumi-brand` MCP server** (`https://brand.pulumi.com/mcp`) —
+is the source of truth; the mirror only follows. Your job: detect where the
+mirror has drifted behind the guide, and open a PR that catches it up.
+
+**If the brand MCP server is unreachable, stop and fail loudly.** Do not
+guess at the guide's contents from memory or from cached prose in this repo —
+a sync against a hallucinated source is worse than no sync.
+
+## Scope
+
+`styles/Pulumi/BRAND-SYNC.yaml` is the manifest: it maps each mirrored Vale
+rule to the brand section and subsection it tracks, and records `last_synced`.
+Rules **not** listed there (AI-drafting tells, Hugo mechanics, repo
+conventions) are repo-owned — never "sync" them against the guide, and never
+edit the brand guide side of anything (that's `pulumi/marketing-web`).
+
+## Process
+
+1. **Load the manifest** (`styles/Pulumi/BRAND-SYNC.yaml`).
+1. **Pull each brand section it references** via the MCP server:
+   `get_guidelines({section: "terminology"})`, `writing-style`, and `voice`.
+1. **Compare, rule by rule.** For each manifest entry, read the Vale rule file
+   and check the guide content it mirrors. You are looking for:
+   - **Retired terms the mirror doesn't know** — a row in the terminology
+     section's "Retired and disallowed names" table with no corresponding
+     entry in `Substitutions.yml` (single fixed replacement) or
+     `DeprecatedProductNames.yml` (context-dependent replacement). This is the
+     highest-value check: renamed products rot fastest.
+   - **Renamed or re-cased canonical names** — a "Product names" row that
+     `Nomenclature.yml` mis-canonicalizes or misses.
+   - **Mirror entries the guide no longer supports** — a swap or token whose
+     brand rule was changed or dropped. Flag these for removal.
+   - **Stale rule `message:`/`link:` text** that misquotes the guide.
+1. **Judge before you write.** The mirror is deliberately narrower than the
+   guide: only near-zero-false-positive, mechanically checkable rules belong
+   in it (see the admission criteria in
+   `.claude/commands/docs-review/scripts/vale-deterministic-fixes.yaml`).
+   A guide rule with no safe regex (e.g. "runtime code" → "function
+   serialization", where *runtime* has too many live meanings) is **correctly
+   absent** — note it in the PR body as intentionally unmirrored rather than
+   forcing a noisy rule. When adding a retired name, decide the tier:
+   - single fixed replacement → `Substitutions.yml` (auto-fixable, blocker)
+   - context-dependent replacement → `DeprecatedProductNames.yml` (flag-only)
+1. **Validate.** Run Vale (`make lint-prose ARGS=<a couple of touched content
+   files>` or `vale` on a scratch fixture exercising each new/changed token,
+   positive and negative cases) to prove the rules compile and match as
+   intended. Run `make lint`.
+1. **Report.**
+   - **Drift found:** update the rule files and `BRAND-SYNC.yaml`
+     (`last_synced` + any mapping changes), and open a **draft PR** titled
+     `vale: sync brand-guide mirror (<date>)`. The body must list every
+     change as *guide says X → mirror said Y → now Z*, plus the
+     intentionally-unmirrored notes. Draft, not ready: tier placement
+     (blocker vs. advisory) is a human call.
+   - **No drift:** commit only the `last_synced` bump in `BRAND-SYNC.yaml`
+     directly to a PR the same way (a one-line draft PR is fine and cheap to
+     merge), or if invoked interactively, just report "in sync".
+   - Never push to `master` directly.
@@ -14,7 +14,7 @@ The `file-path` argument is optional. If not provided, the command will attempt
 
 ## Requires the `pulumi-brand` MCP server
 
-This skill delegates **all** voice, tone, prose, terminology, grammar, and naming judgment to the Pulumi brand guide served by the **`pulumi-brand` MCP server** (`https://brand.pulumi.com/mcp`). It deliberately keeps no local copy of those rules. Before analyzing anything, confirm the server is reachable and load its voice and writing-style guidance. **If you can't reach it, stop and tell the user the brand guide is unavailable — do not fall back to your own notions of Pulumi style.**
+This skill delegates **all** voice, tone, prose, terminology, grammar, and naming judgment to the Pulumi brand guide served by the **`pulumi-brand` MCP server** (`https://brand.pulumi.com/mcp`). It deliberately keeps no local copy of those rules. Before analyzing anything, confirm the server is reachable and load its voice, writing-style, and terminology guidance. **If you can't reach it, stop and tell the user the brand guide is unavailable — do not fall back to your own notions of Pulumi style.**
 
 ---
 
@@ -45,7 +45,7 @@ Read the entire target file and perform comprehensive analysis.
 
 #### Text analysis
 
-Judge the prose against the **brand guide's voice and writing-style sections** (brand.pulumi.com, also exposed through the brand MCP server) — the source of truth for voice and tone, marketing language and superlatives, inclusive language, terminology and product naming, heading case, link text, lists, paragraph length, and grammar. Consult them and flag anything that violates them, quoting the offending line. Don't re-derive those rules here.
+Judge the prose against the **brand guide's voice, writing-style, and terminology sections** (brand.pulumi.com, also exposed through the brand MCP server) — the source of truth for voice and tone, marketing language and superlatives, inclusive language, product/feature naming and the retired-names table, heading case, link text, lists, paragraph length, and grammar. Consult them and flag anything that violates them, quoting the offending line. Don't re-derive those rules here.
 
 Then flag the file-specific issues the brand guide doesn't own:
 
@@ -135,7 +135,7 @@ These references represent current branding standards. Use them to:
 
 Before proposing changes, verify understanding of:
 
-- The brand guide's voice and writing-style sections (brand.pulumi.com, also exposed through the brand MCP server) — voice, prose, terminology, grammar, and naming (the source of truth)
+- The brand guide's voice, writing-style, and terminology sections (brand.pulumi.com, also exposed through the brand MCP server) — voice, prose, grammar, and product/feature naming including retired names (the source of truth)
 - `STYLE-GUIDE.md` — this site's Hugo/repo mechanics (shortcodes, links, code fences, navigation)
 - `AGENTS.md` — Repository conventions and build workflow
 - Google Developer Documentation Style Guide — for topics covered by none of the above
 
@@ -0,0 +1,79 @@
+name: "Scheduled jobs: Brand style sync"
+
+# Weekly drift check of the offline Vale mirror (styles/Pulumi/) against the
+# Pulumi brand guide, with retired/deprecated product names as the priority.
+# Vale can't call the brand MCP at lint time, so this job is what keeps the
+# mirror honest: it re-reads the brand sections each mirrored rule tracks
+# (per styles/Pulumi/BRAND-SYNC.yaml) and opens a draft PR when they've
+# drifted. See .claude/commands/brand-vale-sync/SKILL.md for the process.
+on:
+  schedule:
+    # Mondays at 14:00 UTC — after the weekend, before the US work week.
+    - cron: '0 14 * * 1'
+  workflow_dispatch: null
+
+permissions:
+  contents: write
+  pull-requests: write
+  id-token: write # Required for ESC OIDC auth
+  actions: read
+
+jobs:
+  sync:
+    name: Check Vale mirror against brand guide
+    runs-on: ubuntu-latest
+    steps:
+      # ESC runs before checkout so the bot token can authenticate the
+      # checkout — the PR opened by claude-code-action then goes out as
+      # pulumi-bot, letting downstream workflows (docs review, etc.) fire.
+      - name: Fetch secrets from ESC
+        id: esc-secrets
+        uses: pulumi/esc-action@v3
+      - name: Checkout repository
+        uses: actions/checkout@v7
+        with:
+          token: ${{ steps.esc-secrets.outputs.PULUMI_BOT_TOKEN }}
+      # Binary only — the model runs Vale itself against fixtures/changed
+      # files while validating rule edits; there's no repo-wide report here.
+      - name: Install Vale
+        run: |
+          curl -sL https://github.com/errata-ai/vale/releases/download/v3.9.4/vale_3.9.4_Linux_64-bit.tar.gz \
+            | sudo tar xz -C /usr/local/bin vale
+          vale --version
+      - name: Run Claude Code
+        id: claude
+        uses: anthropics/claude-code-action@v1
+        with:
+          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
+          # Bot token so the PR triggers downstream workflows.
+          github_token: ${{ steps.esc-secrets.outputs.PULUMI_BOT_TOKEN }}
+          prompt: |
+            You are running in CI on a schedule.
+
+            Follow `.claude/commands/brand-vale-sync/SKILL.md` exactly: check
+            the offline Vale mirror under `styles/Pulumi/` against the Pulumi
+            brand guide via the `pulumi-brand` MCP server, prioritizing the
+            terminology section's "Retired and disallowed names" table.
+
+            - If the brand MCP server is unreachable, exit non-zero with a
+              clear error. Do not sync from memory.
+            - If the mirror has drifted, fix it and open a **draft** PR on a
+              branch named `vale/brand-sync-<YYYY-MM-DD>` with the auditable
+              body the skill describes.
+            - If nothing drifted, bump `last_synced` in
+              `styles/Pulumi/BRAND-SYNC.yaml` and open the same draft PR with
+              just that change.
+          # The public pulumi-brand MCP server is wired via --mcp-config
+          # (claude-code-action@v1 has no mcp_config input); its tools are in
+          # --allowed-tools. No auth: the server is public.
+          claude_args: |
+            --model claude-opus-5 --effort low
+            --mcp-config '{"mcpServers": {"pulumi-brand": {"type": "http", "url": "https://brand.pulumi.com/mcp"}}}'
+            --allowed-tools "Read,Write,Edit,Glob,Grep,Agent,WebFetch,mcp__pulumi-brand__get_guidelines,mcp__pulumi-brand__search_guidelines,Bash(make lint:*),Bash(make lint-prose:*),Bash(vale:*),Bash(gh pr create:*),Bash(gh pr view:*),Bash(gh pr list:*),Bash(gh search:*),Bash(gh api:*),Bash(git:*),Bash(cat:*),Bash(head:*),Bash(tail:*),Bash(wc:*),Bash(ls:*),Bash(grep:*),Bash(find:*),Bash(rg:*),Bash(sed:*),Bash(awk:*),Bash(jq:*),Bash(diff:*),Bash(echo:*),Bash(printf:*),Bash(tee:*),Bash(date:*),Bash(test:*),Bash(mkdir:*),Bash(python3 -c:*)"
+
+env:
+  ESC_ACTION_OIDC_AUTH: true
+  ESC_ACTION_OIDC_ORGANIZATION: pulumi
+  ESC_ACTION_OIDC_REQUESTED_TOKEN_TYPE: urn:pulumi:token-type:access_token:organization
+  ESC_ACTION_ENVIRONMENT: github-secrets/pulumi-docs
+  ESC_ACTION_EXPORT_ENVIRONMENT_VARIABLES: false
@@ -31,7 +31,7 @@ Do not substitute other tools or commands, or change `package.json` to use pnpm
 
 ## Code & Content Rules
 
-For all content files, Pulumi's **voice, tone, prose, product naming, and grammar** are defined in the **Pulumi brand guide** ([brand.pulumi.com](https://brand.pulumi.com/)), which is also exposed to agents through the public **brand MCP server**. Consult the relevant section (voice or writing style) before writing or reviewing. `STYLE-GUIDE.md` covers only this site's Hugo/repo mechanics (shortcodes, links, navigation, code fences, etc.) and points to the brand guide for each topic it doesn't own. If a rule is in neither, fall back to the [Google Developer Documentation Style Guide](https://developers.google.com/style). Do not invent new style conventions; ask for clarification if something is ambiguous.
+For all content files, Pulumi's **voice, tone, prose, product naming, and grammar** are defined in the **Pulumi brand guide** ([brand.pulumi.com](https://brand.pulumi.com/)), which is also exposed to agents through the public **brand MCP server**. Consult the relevant section (voice, writing style, or terminology) before writing or reviewing — the **terminology** section is the canonical reference for product/feature names and the retired names never to use again. `STYLE-GUIDE.md` covers only this site's Hugo/repo mechanics (shortcodes, links, navigation, code fences, etc.) and points to the brand guide for each topic it doesn't own. If a rule is in neither, fall back to the [Google Developer Documentation Style Guide](https://developers.google.com/style). Do not invent new style conventions; ask for clarification if something is ambiguous.
 
 **Precedence:** wherever the brand guide overlaps with anything in this repo — these conventions, `STYLE-GUIDE.md`, or any skill (including the social, SEO, and AEO guidance that still lives in this repo), the brand guide takes priority. That specialized guidance stays in the repo for now; if the brand guide later grows its own, the brand guide's version wins.
 
@@ -58,7 +58,7 @@ For all content files (docs, blogs, tutorials, etc.):
   - Code examples go under `/static/programs` with a language suffix in the filename.  
   - Mirror the structure of existing content; do not invent new layouts.
 - **Includes**: Use Hugo shortcodes for shared content, never raw Markdown copy-paste.  
-- **Naming**: Use lowercase for non-proper nouns (e.g. “stack,” not “Stack”).  
+- **Naming**: Product, feature, and category names — canonical casing, preferred terms, retired names — come from the brand guide's terminology section. Never introduce a name from memory: check the retired-names table first (e.g. it's Pulumi Discovery now, not “Pulumi Insights”; Pulumi Neo, not “Copilot”). Non-proper nouns stay lowercase (“stack,” not “Stack”).  
 - **Ordered Lists**: Every item begins with `1.` to minimize diff noise.
 - **Diagrams**: Prefer Mermaid diagrams over ASCII art. The site renders Mermaid natively via a Hugo code block hook (`layouts/_default/_markup/render-codeblock-mermaid.html`). Use ` ```mermaid ` fenced code blocks. See [Mermaid docs](https://mermaid.js.org/) for syntax.
 - **Images on template-driven pages**: Place new images for template-driven pages (homepage, product pages, event pages, case studies — anything rendered through `layouts/partials/template-partials/*`) under `assets/fingerprinted/`, mirroring the path you'd use under `static/`. The template partials route every `<img>` through `layouts/partials/fingerprinted-img.html`, which content-hashes filenames, converts rasters to WebP, and generates responsive `srcset`s. Frontmatter paths still look like `/images/foo.svg`; the partial resolves them. Missing assets cause a build panic, so there is no silent fallback. `meta_image` and assets used by non-template layouts can stay in `static/`.