--- name: dashboard-forge description: Supervised browser automation of vendor dashboards and admin consoles for operations that have NO public API — minting scoped API tokens, creating OAuth apps, flipping account-level toggles, console-only settings. The method skill of web-forge, the one harness for this - recipes as data run by the web-forge CLI (idempotent ensure, read-back, a screenshot per step, a login gate that never types a credential) or node forge scripts; two connection modes (a signed-in profile of your everyday Chrome through the Playwright Extension, or a persistent per-site profile over CDP where a human logs in once); secrets extracted DOM-to-vault without ever being exposed; UI drift survived via the step-and-shoot method and a dated Vendor Quirks log. Use when a task needs a dashboard click-path (Cloudflare token/Zero Trust, GitHub OAuth apps, any admin console) and the vendor offers no API or your token lacks the scope to grant itself more. Triggers - "no API for this", "create an OAuth app", "mint a token in the dashboard", "automate the admin console", "browser-automate the setup", "write a console recipe". allowed-tools: Read, Bash, Grep, Glob --- # dashboard-forge — supervised dashboard automation doctrine Some operations exist ONLY behind a vendor's web UI (GitHub fine-grained PATs and OAuth apps have no creation API; a Cloudflare token cannot grant itself new scopes). This skill is the canonical method for automating those click-paths safely: the human supervises and handles logins/2FA; the scripts do everything else, reproducibly. **Harness (SSoT): this plugin, in two forms on shared foundations** ([plugin CLAUDE.md](../../CLAUDE.md) has the file map): - **Recipes** — [`scripts/web-forge.ts`](../../scripts/web-forge.ts) (Bun): the step-and-shoot method as a CLI. A recipe is data (flags or a `--spec` JSON file → form operations), with idempotent ensure, read-back from a fresh load, a screenshot per step, a login gate that never types a credential, and `Driver.extractToVault` for reveals. **Write new console automation as a recipe.** Worked family: [admin-console](../admin-console/SKILL.md) (Google Admin). `bun "$(cc-plugin-root web-forge)/scripts/web-forge.ts" recipes --json` lists every recipe, flag and exit code. - **Forge scripts** — [`lib/browser-forge.mjs`](../../lib/browser-forge.mjs) (node ONLY: Bun's `connectOverCDP` times out; needs `playwright-core`, pinned at the repo root): Playwright held directly over CDP, for flows a recipe does not cover yet — token capture off the wire (`captureBearer`), consent dismissal, exact-name clicks. The cf-access-wall and azure-provision scripts use it. Both take their browser from [`lib/forge-chrome.mjs`](../../lib/forge-chrome.mjs) and their secret sink from [`lib/vault.mjs`](../../lib/vault.mjs). **Route choice — the two connection modes.** If the session you need is already signed in to a profile of your everyday Chrome, use **extension** mode (recipes: `--connect extension`, the default): [`chrome-profiles`](../../../chrome-profiles/skills/browser-automation/SKILL.md) (`chrome-profile.sh setup `, zero clicks). For a supervised flow that wants its own isolated, persistent profile, use **cdp** mode (recipes: `--connect cdp --site `; forge scripts: `launchChrome(site)`). Route ladder and Chrome-136 mechanics: chrome-profiles is the SSoT. > **Self-Evolving Skill**: dashboards drift constantly. When a selector misses or a flow changes, fix the recipe or forge script AND append the drift note to the Vendor Quirks section below — immediately, not later. Only update for real, reproducible breakage. ## The method — step-and-shoot Write the forge as small, resumable steps against a LONG-LIVED Chrome (launch once; each step connects, acts, disconnects — `browser.close()` on a CDP connection only detaches, Chrome keeps running). Never author one monolithic script against an unseen UI. 1. **Launch + human login.** `launchChrome(site, loginUrl)` (a recipe: its family's login gate); the human signs in (incl. 2FA). Detect completion with `waitForLogin(ctx, probeUrl, ok)` — poll an authenticated endpoint via `ctx.request` with the context cookies. NEVER navigate a visible tab to poll: you would reload a half-typed login form. 2. **Identity preflight.** Before ANY mutating step, extract the signed-in identity (a meta tag, a settings-page marker, an API echo) and `assertIdentity(actual, expected, resource)`. An account-owned resource created under the wrong login is a silent disaster (it happened: an OAuth app landed under the wrong GitHub user mid-forge because the human switched accounts). 3. **Act in small steps, screenshot between.** One interaction cluster per step; `shot(page, name)` after each. When a locator misses, READ the latest shot, adapt, re-run just that step. Prefer role/label-based locators (`getByRole`, description-text anchoring) over CSS classes; for checkbox grids, `page.evaluate` walking from a UNIQUE description text up to its row is far more drift-proof than nth-child chains. 4. **Expect interceptors.** Cookie/consent overlays (OneTrust & co.) swallow clicks and produce pure timeouts with no visible cause — call `dismissConsent(page)` when a click times out mysteriously, then retry. GitHub-style sudo/2FA walls mid-flow: pause and let the supervising human clear them (or see gh-fine-grained-pat's `autosudo.mjs` for the autonomous passkey path). 5. **Extract secrets DOM-only.** On a token/secret reveal page: `page.evaluate` → match the value → `vaultSet(scope, path, value)` (a recipe: `Driver.extractToVault`, which never shoots and logs only the length). **NEVER screenshot a reveal page** — an agent reading that screenshot puts the secret into the conversation context permanently. If a reveal was accidentally captured, purge the file AND treat the secret as context-exposed (rotate if the transcript leaves the machine). 6. **End-of-run hygiene.** `purgeShots()` (breadcrumbs can show near-secret state), then `teardown(site)` — shuts down through chrome-profiles' port script (exact port flag), never `pkill -f` (process-storm policy, `~/.claude/CLAUDE.md`). ## Hybrid rule — forge the key, then use the door Browser-automate the MINIMUM: usually just (a) the login and (b) the one form that mints a scoped credential. Everything after that goes through the vendor's REAL API with the minted credential, written as an **idempotent GET-before-POST bootstrap** (see the cf-access-wall skill for the worked template). UI automation is the crowbar, not the workflow. ## Borrowed-session mode — driving a browser the HUMAN already logged into A third mode, distinct from launching a per-site profile over CDP. Instead of owning a session, you **borrow one that is already open** in the operator's own Chrome and drive it via AppleScript: ```applescript tell application "Google Chrome" execute (tab N of window M) javascript "…" end tell ``` Requires **View → Developer → Allow JavaScript from Apple Events** (persisted per profile as `browser.allow_javascript_apple_events` in `Preferences` — grep it to check before promising anything). You then have full DOM read/write with no driver, no profile copy, and no port. **When it is the RIGHT tool:** the console is behind a passkey / hardware-key / step-up flow that you must not automate, and a human session already exists. You never touch the credential — you type inside a door somebody else opened. That distinction is the whole justification, and it is worth stating out loud in whatever you write afterwards. **When it is the WRONG tool:** anything unattended, anything needing isolation, anything that should not be able to see the operator's other tabs. It has no sandbox by construction. Hard-won rules, each one paid for: - **Address tabs by URL, never by index.** `activate` and `set index` REORDER windows, so an index captured a moment ago can point somewhere else by the time you use it. Re-resolve on every call. Make the URL needle specific — `"admin.google.com"` will happily match a different admin tab and you will read the wrong page and believe it. - **Read the JS from a FILE** (`set js to read POSIX file "/tmp/step.js" as «class utf8»`). Interpolating JS through bash → osascript → AppleScript string literals mangles quotes and backslashes in ways that fail silently or, worse, alter the script. - **`offsetParent` is null for `position: fixed`,** which is how essentially every Material/modal dialog is rendered. A "is it visible" filter built on `offsetParent !== null` therefore hides the dialog you are looking for and you conclude the form never opened. Use `getBoundingClientRect()` width/height instead. - **Framework inputs need the NATIVE setter.** Assigning `el.value` updates the DOM but leaves Angular/React/Closure's model stale, so the form submits empty. Use `Object.getOwnPropertyDescriptor(HTMLInputElement.prototype,'value').set.call(el, v)` then dispatch `input` + `change` (+ `blur`). Read the value back and assert it. - **Verify what is under the point before any coordinate-based click** — `document.elementFromPoint(x,y)` and compare to the intended element. In an admin console a mis-aimed click is not a failed test, it is an unintended action. - **Chrome can be RUNNING with zero windows and refuse `open -a`.** `make new window` via Apple Events still works. Never quit or restart the operator's browser to "fix" it; you will destroy their tabs. ## Secrets discipline (non-negotiable) - Values ride PIPES: `vault set --stdin ` (SCS vault). Never argv, never stdout, never a chat transcript. - Scripts print LENGTHS and vault paths, not values (`✓ vaulted (len 53)`). - Profile dirs (`~/.local/share/web-forge/profile-`) hold live sessions — sensitive, never committed, listed in backups as credential-equivalent. - Public identifiers (OAuth client_id, account ids) may be logged; anything CONCEALED may not. ## Vendor quirks (drift log — append, with dates) - **Cloudflare 2026-07 token UI**: the old template-picker → 3-combobox flow is GONE. "Create Token" lands directly on a categorized checkbox form ("Cloudflare One / Zero Trust" section → per-group Read/Revoke/Edit boxes); submit is **"Review token"** → "Create token" → modal reveal. Tokens are `cfat_…` (53 chars), not the old 40-char format. - **Cloudflare account-owned tokens** (2026-07-23): `/user/tokens/verify` ALWAYS rejects them ("Invalid API Token"); verify with `/accounts/{id}/tokens/verify`. Don't misdiagnose a working token as dead. - **Cloudflare dashboard consent** (2026-07-23): OneTrust overlay appears minutes into a session and intercepts pointer events page-wide. - **GitHub OAuth apps** (2026-07-23): no creation API (same as fine-grained PATs). Form fields: `oauth_application[name|url|callback_url]`. "Generate a new client secret" triggers sudo mode; a FRESH login usually has a sudo grace window — create the app right after login and the secret generation is prompt-free. Client secrets render as a 40-hex blob. The callback field was renamed on 2026-11-16 (entry below). - **Azure Portal — ambiguous accessible names** (2026-08-02): every blade's close button is labelled `"Close content ''"`, so on "Register an application" a fuzzy `getByRole("button", {name:/register/i}).first()` matches the CLOSE button, not the submit. It clicks, Playwright reports success, the blade shuts and nothing is created. Cost two runs, and the second created a DUPLICATE once the truth surfaced. Use `clickExact()` — it refuses on a non-exact name and prints the candidate list (verified live: `["Close content 'Register an application'","Register"]`). - **Azure Portal — two elements match `input[placeholder*="Search"]`** (2026-08-02): the page-wide search in the masthead matches BEFORE any blade's own filter. Typing the role name into it left the role grid unfiltered, so an exact row lookup found 0 rows and the wizard advanced with no role selected. Anchor on the distinctive placeholder (`"Search by role name, description, permission, or ID"`). - **Azure Portal — a list view can lie about creation** (2026-08-02): after successfully creating an app registration as a GUEST (`#EXT#`) user, **App registrations → Owned applications** said "This account isn't listed as an owner of any applications in this directory." True (a guest creator is not auto-assigned owner) and deeply misleading. Ground truth is the **notifications pane** ("Successfully created application X") or the **All applications** tab. Never confirm a mutation from the same console's default list view. - **Azure Portal — tokens are in memory, not localStorage** (2026-08-02): an MSAL SPA of this generation keeps ARM/Graph access tokens in memory; a localStorage sweep returns nothing. Capture them off the wire with `captureBearer(page, "management.azure.com" | "graph.microsoft.com")`. With an ARM token the whole 3-tab role-assignment wizard collapses into one idempotent `PUT` (HTTP 201 first try) — the clearest instance of the Hybrid rule in this log. - **Azure Portal — a cached blade issues no request** (2026-08-02): navigating to a view the SPA has already hydrated produces zero traffic, so token capture silently yields `null`, which reads exactly like "no permission". `captureBearer` retries with a `reload()` for this reason. The App-registrations LIST blade reliably re-queries Graph; the Entra Overview blade often does not. - **Azure — the Portal and the CLI are DIFFERENT Entra apps** (2026-08-02): portal `c44b4083-3bb0-49c1-b47d-974e53cbdf3c`, CLI `04b07795-8ddb-461a-bbee-02f9e1bf7b46`. A Conditional Access policy scoped to the CLI (`AADSTS530035`, "Device state: Unregistered") therefore does **not** block the portal. This asymmetry is what makes a browser forge the only way in — and note that `az account list` then returns `[]`, which is a consequence of the block and **not** evidence that no subscription exists. - **Tailscale — console moved and OAuth clients were renamed** (2026-08-05): `login.tailscale.com` redirects to **`console.tailscale.com`**, and `/admin/settings/oauth` redirects to **`/admin/settings/trust-credentials`** ("OAuth clients" is now "Trust credentials", created via a button labelled just **`Credential`**). Auth keys stayed at `/admin/settings/keys`. - **Tailscale — Radix checkboxes: the `` is a decoy** (2026-08-05): every scope checkbox renders a real `` that is `aria-hidden`, `opacity:0`, **`pointer-events:none`**, next to a `