feat: automate valid_paths.json refresh on Settings UI changes

.agents/skills/validate_ui_refs/SKILL.md

@@ -12,7 +12,7 @@ This skill scans Warp's Astro Starlight documentation for references to UI paths
 From the docs repo root:
 
 ```bash
-python3 .warp/skills/validate_ui_refs/validate_ui_refs.py --all
+python3 .agents/skills/validate_ui_refs/validate_ui_refs.py --all
 ```
 
 ### Options
@@ -23,8 +23,9 @@ python3 .warp/skills/validate_ui_refs/validate_ui_refs.py --all
 - `--all`: Run all checks (default)
 - `--fix`: Auto-fix high-confidence issues (e.g. case mismatches)
 - `--create-pr`: Create a branch and PR with auto-fixes (requires `gh` CLI)
-- `--slack-notify`: Post results to Slack (only sends when issues are found; requires `SLACK_BOT_TOKEN` and `GROWTH_DOCS_SLACK_CHANNEL_ID` env vars)
-- `--slack-channel ID`: Override default Slack channel
+- `--slack-notify`: Post results to `#growth-docs` Slack channel when unfixed issues remain (requires `SLACK_BOT_TOKEN` env var; channel is hardcoded in the script)
+- `--slack-channel ID`: Override the default Slack channel (`C09BVK0PL3Y`)
+- `--self-test`: Run internal sanity checks against the current snapshot and exit (no `warp-internal` needed)
 - `--include-changelog`: Include `changelog/` in the scan (excluded by default since it's a historical record)
 - `--refresh-valid-paths`: Re-extract valid paths from `warp-internal` and update `valid_paths.json`
 - `--warp-internal-path PATH`: Path to the `warp-internal` repo (default: `../warp-internal` relative to docs root, or `WARP_INTERNAL_PATH` env var)
@@ -33,13 +34,13 @@ python3 .warp/skills/validate_ui_refs/validate_ui_refs.py --all
 ### Quick path-only check:
 
 ```bash
-python3 .warp/skills/validate_ui_refs/validate_ui_refs.py --check-paths
+python3 .agents/skills/validate_ui_refs/validate_ui_refs.py --check-paths
 ```
 
 ### Full check with auto-fix and PR:
 
 ```bash
-python3 .warp/skills/validate_ui_refs/validate_ui_refs.py --all --fix --create-pr
+python3 .agents/skills/validate_ui_refs/validate_ui_refs.py --all --fix --create-pr
 ```
 
 ## Output Format
@@ -74,7 +75,7 @@ Files scanned: 174
 The `valid_paths.json` file is a static snapshot of valid UI paths. To update it from the latest `warp-internal` source:
 
 ```bash
-python3 .warp/skills/validate_ui_refs/validate_ui_refs.py --refresh-valid-paths --warp-internal-path /path/to/warp-internal
+python3 .agents/skills/validate_ui_refs/validate_ui_refs.py --refresh-valid-paths --warp-internal-path /path/to/warp-internal
 ```
 
 This parses:
@@ -127,51 +128,52 @@ Fixes that require manual review (e.g. renamed sections, removed features) are r
 
 ## Slack Notifications
 
-Slack notifications are designed for scheduled/automated runs, not ad-hoc usage. When running the skill manually (e.g., during a PR review or docs update), you can review results directly in the terminal output.
+Slack notifications are designed for automated runs, not ad-hoc usage. When running the skill manually, review results directly in the terminal output.
 
-### Current behavior
+The `--slack-notify` flag posts a summary to `#growth-docs` when unfixed issues remain after a run. If the scan is clean (0 issues), no notification is sent.
 
-The `--slack-notify` flag posts a summary to the configured Slack channel when unfixed issues remain after a run. If the scan is clean (0 issues), no notification is sent.
-
-### Intended behavior for scheduled runs
-
-When this skill is configured as a scheduled cloud agent, Slack notifications should alert the team in two cases:
+### Setup (one-time)
 
-1. **Auto-fixes applied** — the script found and corrected issues, and created a PR. The notification should include the PR link so the team can review and merge.
-2. **Unfixed issues remain** — some issues could not be auto-corrected (e.g., a renamed or removed section) and require manual attention. The notification should list these for triage.
+Add `SLACK_BOT_TOKEN` as a repository secret in `warpdotdev/docs` (**Settings** > **Secrets and variables** > **Actions**). The token needs `chat:write` scope.
 
-If a scheduled run finds no issues at all, the notification should be skipped (no noise).
+### Usage
 
-> **Note:** This two-condition notification logic is not yet implemented. The current `--slack-notify` flag only covers condition 2 (unfixed issues). When we set up scheduled runs, the script should be updated to also notify on condition 1 (auto-fixes with PR link).
+```bash
+python3 .agents/skills/validate_ui_refs/validate_ui_refs.py --all --slack-notify
+```
 
-### Setup (one-time)
+## Automated refresh
 
-Create a Warp team secret for the Slack bot token:
+`valid_paths.json` is refreshed automatically via the `refresh-ui-paths` GitHub Actions workflow (`.github/workflows/refresh-ui-paths.yml`).
 
-```bash
-oz secret create SLACK_BOT_TOKEN --team --description "Slack bot token for UI ref validation reports"
-```
+### How it works
 
-The token needs `chat:write` scope.
+1. A push to `master` in `warpdotdev/warp-internal` that touches `app/src/settings_view/**` sends a `repository_dispatch` event (`settings-ui-changed`) to `warpdotdev/docs`.
+2. The `refresh-ui-paths` workflow fires, checks out both repos, and runs `--refresh-valid-paths`.
+3. If the snapshot changed, it runs `--all --fix --slack-notify`, commits all changes (updated snapshot + any doc fixes), and opens a PR.
+4. If unfixed issues remain, a notification is posted to `#growth-docs`.
+5. If the snapshot is unchanged, the workflow exits with no-op.
 
-### Usage
+### Secrets required
 
-```bash
-python3 .warp/skills/validate_ui_refs/validate_ui_refs.py --all --slack-notify
-```
+| Secret | Repo | Purpose |
+|---|---|---|
+| `DOCS_DISPATCH_PAT` | `warp-internal` | Fine-grained PAT — **Actions: write** on `warpdotdev/docs` (to trigger `repository_dispatch`; no Contents access needed) |
+| `WARP_INTERNAL_READ_PAT` | `docs` | Fine-grained PAT — Contents read on `warpdotdev/warp-internal` |
+| `SLACK_BOT_TOKEN` | `docs` | Slack bot token with `chat:write` scope |
 
-## Cloud Agent / Scheduling
+### Manual trigger
 
-For scheduled cloud agent runs:
+To trigger the workflow manually (e.g., if the PAT expired or a migration was missed):
 
-1. Configure the environment with the docs repo
-2. Keep `valid_paths.json` up-to-date by running `--refresh-valid-paths` as a pre-step (requires `warp-internal` in the environment)
-3. Set the `SLACK_BOT_TOKEN` secret in the environment
-4. Run: `python3 .warp/skills/validate_ui_refs/validate_ui_refs.py --all --fix --create-pr --slack-notify`
+1. In the `warpdotdev/docs` repo, go to **Actions** > **Refresh UI paths snapshot** > **Run workflow**.
+2. Or run locally:
 
-A typical scheduled agent would:
-1. Run `--refresh-valid-paths` to update the snapshot
-2. Run `--all --fix --create-pr --slack-notify` to check, fix, and report
+```bash
+python3 .agents/skills/validate_ui_refs/validate_ui_refs.py \
+  --refresh-valid-paths \
+  --warp-internal-path /path/to/warp-internal
+```
 
 ## Dependencies
 

.agents/skills/validate_ui_refs/valid_paths.json

@@ -1,4 +1,76 @@
 {
+  "umbrellas": {
+    "Agents": {
+      "subpages": [
+        "Oz",
+        "Profiles",
+        "MCP servers",
+        "Knowledge",
+        "Third party CLI agents"
+      ],
+      "source_file": "app/src/settings_view/mod.rs"
+    },
+    "Code": {
+      "subpages": [
+        "Indexing and projects",
+        "Editor and Code Review"
+      ],
+      "source_file": "app/src/settings_view/mod.rs"
+    },
+    "Cloud platform": {
+      "subpages": [
+        "Environments",
+        "Oz Cloud API Keys"
+      ],
+      "source_file": "app/src/settings_view/mod.rs"
+    }
+  },
+  "deprecated_sections": {
+    "AI": {
+      "umbrella": "Agents",
+      "default_subpage": "Oz",
+      "subsection_to_subpage": {
+        "Active AI": "Oz",
+        "Input": "Oz",
+        "Voice": "Oz",
+        "Other": "Oz",
+        "Experimental": "Oz",
+        "Usage": "Profiles",
+        "Agents": "Profiles",
+        "Profiles": "Profiles",
+        "Permissions": "Profiles",
+        "Command allowlist": "Profiles",
+        "Command denylist": "Profiles",
+        "MCP Servers": "MCP servers",
+        "MCP servers": "MCP servers",
+        "Knowledge": "Knowledge",
+        "CLI Agents": "Third party CLI agents",
+        "Coding Agents": "Third party CLI agents",
+        "Third party CLI agents": "Third party CLI agents"
+      },
+      "subsection_aliases": [
+        "Agents",
+        "Profiles",
+        "MCP Servers",
+        "MCP servers",
+        "Knowledge",
+        "CLI Agents",
+        "Third party CLI agents"
+      ]
+    },
+    "MCP Servers": {
+      "umbrella": "Agents",
+      "default_subpage": "MCP servers"
+    },
+    "Environments": {
+      "umbrella": "Cloud platform",
+      "default_subpage": "Environments"
+    },
+    "Platform": {
+      "umbrella": "Cloud platform",
+      "default_subpage": "Oz Cloud API Keys"
+    }
+  },
   "settings_sections": {
     "About": {
       "display_name": "About",
@@ -10,38 +82,85 @@
       "sub_sections": [],
       "source_file": "app/src/settings_view/mod.rs"
     },
-    "AI": {
-      "display_name": "AI",
+    "Oz": {
+      "display_name": "Oz",
+      "umbrella": "Agents",
       "sub_sections": [
-        "Usage",
         "Active AI",
-        "Agents",
         "Input",
-        "MCP Servers",
-        "Knowledge",
         "Voice",
-        "CLI Agents",
-        "Experimental",
-        "API Keys",
-        "AWS Bedrock"
+        "Other",
+        "Experimental"
       ],
       "source_file": "app/src/settings_view/ai_page.rs"
     },
-    "Environments": {
-      "display_name": "Environments",
+    "Profiles": {
+      "display_name": "Profiles",
+      "umbrella": "Agents",
+      "sub_sections": [
+        "Usage",
+        "Profiles",
+        "Agents",
+        "Permissions",
+        "Command allowlist",
+        "Command denylist",
+        "MCP permissions"
+      ],
+      "source_file": "app/src/settings_view/ai_page.rs"
+    },
+    "MCP servers": {
+      "display_name": "MCP servers",
+      "umbrella": "Agents",
       "sub_sections": [],
-      "source_file": "app/src/settings_view/mod.rs"
+      "source_file": "app/src/settings_view/mcp_servers_page.rs"
     },
-    "MCP Servers": {
-      "display_name": "MCP Servers",
+    "Knowledge": {
+      "display_name": "Knowledge",
+      "umbrella": "Agents",
       "sub_sections": [],
-      "source_file": "app/src/settings_view/mod.rs"
+      "source_file": "app/src/settings_view/ai_page.rs"
+    },
+    "Third party CLI agents": {
+      "display_name": "Third party CLI agents",
+      "umbrella": "Agents",
+      "sub_sections": [],
+      "source_file": "app/src/settings_view/ai_page.rs"
     },
     "Billing and usage": {
       "display_name": "Billing and usage",
       "sub_sections": [],
       "source_file": "app/src/settings_view/billing_and_usage_page.rs"
     },
+    "Indexing and projects": {
+      "display_name": "Indexing and projects",
+      "umbrella": "Code",
+      "sub_sections": [
+        "Codebase Indexing"
+      ],
+      "source_file": "app/src/settings_view/code_page.rs"
+    },
+    "Editor and Code Review": {
+      "display_name": "Editor and Code Review",
+      "umbrella": "Code",
+      "sub_sections": [
+        "Code Editor and Review"
+      ],
+      "source_file": "app/src/settings_view/code_page.rs"
+    },
+    "Environments": {
+      "display_name": "Environments",
+      "umbrella": "Cloud platform",
+      "sub_sections": [],
+      "source_file": "app/src/settings_view/environments_page.rs"
+    },
+    "Oz Cloud API Keys": {
+      "display_name": "Oz Cloud API Keys",
+      "umbrella": "Cloud platform",
+      "sub_sections": [
+        "API Keys"
+      ],
+      "source_file": "app/src/settings_view/platform_page.rs"
+    },
     "Appearance": {
       "display_name": "Appearance",
       "sub_sections": [
@@ -58,11 +177,6 @@
       ],
       "source_file": "app/src/settings_view/appearance_page.rs"
     },
-    "Code": {
-      "display_name": "Code",
-      "sub_sections": [],
-      "source_file": "app/src/settings_view/code_page.rs"
-    },
     "Features": {
       "display_name": "Features",
       "sub_sections": [
@@ -83,11 +197,6 @@
       "sub_sections": [],
       "source_file": "app/src/settings_view/mod.rs"
     },
-    "Platform": {
-      "display_name": "Platform",
-      "sub_sections": [],
-      "source_file": "app/src/settings_view/platform_page.rs"
-    },
     "Privacy": {
       "display_name": "Privacy",
       "sub_sections": [],
@@ -108,6 +217,11 @@
       "sub_sections": [],
       "source_file": "app/src/settings_view/teams_page.rs"
     },
+    "Warp Drive": {
+      "display_name": "Warp Drive",
+      "sub_sections": [],
+      "source_file": "app/src/settings_view/warp_drive_page.rs"
+    },
     "Warpify": {
       "display_name": "Warpify",
       "sub_sections": [
@@ -117,6 +231,23 @@
       "source_file": "app/src/settings_view/warpify_page.rs"
     }
   },
+  "top_level_sidebar": [
+    "Account",
+    "Agents",
+    "Billing and usage",
+    "Code",
+    "Cloud platform",
+    "Teams",
+    "Appearance",
+    "Features",
+    "Keyboard shortcuts",
+    "Warpify",
+    "Referrals",
+    "Shared blocks",
+    "Warp Drive",
+    "Privacy",
+    "About"
+  ],
   "macos_menu_bar": {
     "File": [
       "New Tab",
@@ -313,5 +444,5 @@
     {"name": "input:toggle_vim_keybindings", "description": "Enable Editing Commands With Vim Keybindings"},
     {"name": "workspace:share_pane", "description": "Share Pane"}
   ],
-  "generated_at": "2026-02-19T20:37:00Z"
+  "generated_at": "2026-04-23T23:55:00Z"
 }