X-App setup: inject visual guidance (arrows + color coding) onto console.x.com to walk the operator through credential capture

[WiggidyW]

Summary

The psychological-operations x_app setup flow spawns Chromium with the auth extension (psychological-operations-chromium-extension-auth/) loaded and lands the operator on https://console.x.com/. The operator then has to traverse the X Developer Console — create a Project, create an App, set User Authentication Settings, copy three credentials from two different pages — and finally paste those credentials into the extension popup. Today the only guidance is (a) seven lines of stderr text printed by the CLI before the browser opens, and (b) hint strings inside the popup form. The operator has to mentally map between those and whatever screen they're currently looking at.

This issue: the auth extension should inject visual guidance — arrows and color coding — directly onto the relevant console.x.com pages, so the operator is told exactly where to click and what to copy at each step, on the page where it matters.

Motivation

The current text-based guidance has two failure modes:

1. The OAuth-1.0a / OAuth-2.0 collision. Two of the three credentials (Client ID, Client Secret) come from "User authentication settings" (OAuth 2.0). The third (Bearer Token) comes from "Keys and Tokens". That page also exposes Consumer Key / Secret Key (OAuth 1.0a) which look identical and are not what we want. The extension popup has a hint string saying "NOT the Consumer Key" but the operator only sees that hint after they've already navigated away from the page and opened the popup. Wrong credentials silently break psyops oauth <name> later with confusing failures.
2. Required configuration that's easy to skip. The OAuth 2.0 callback URI must be registered as http://127.0.0.1/callback (host only, no port) and the app must be set to "Web App" with "Read and write" permissions. Forgetting any of these blocks every per-psyop OAuth handshake. None of these settings are visible in the popup, so the operator has no feedback that they missed a step until much later.

Visual guidance on the page itself fixes both: the extension highlights the correct field, the operator can't pick the wrong one, and required-configuration screens get explicit "do this here" annotations.

Current flow (what the operator does today)

From psychological-operations-cli/src/x_app/setup.rs:55-66 and the auth extension popup at psychological-operations-chromium-extension-auth/popup.html:

1. Sign into the X account that owns the dev app.
2. On console.x.com: create a Project + App. Provision credits.
3. On the App's "User authentication settings": set type = Web App, permissions = Read and write, register http://127.0.0.1/callback as a Callback URI.
4. Copy the OAuth 2.0 Client ID and Client Secret (visible only at app-creation time, then accessible via the regenerate flow).
5. On the App's "Keys and Tokens" page: copy the Bearer Token (NOT Consumer Key, NOT Secret Key — those are OAuth 1.0a).
6. Click the auth extension's toolbar icon, paste the three values into the popup, click Save. background.js relays to the native host, which writes ~/.psychological-operations/x_app.json.

Proposed enhancement

Add a content-script-driven UI overlay layer to the auth extension that runs on console.x.com. The overlay knows the current step and renders:

• Arrows anchored to the DOM element the operator should interact with next (a sidebar entry, a button, a credential field). Use SVG arrows positioned by getBoundingClientRect() so they reflow with the page; reposition on window.resize and on a MutationObserver for SPA-route changes.
• Color coding by step:
  • green — "click this / copy this / do this now"
  • red — "do NOT use this" (the OAuth-1.0a Consumer Key and Secret Key on the Keys and Tokens page get a red translucent overlay with the label "OAuth 1.0a — not used")
  • blue — informational ("this is the page you want", "this credential goes into Field X of the popup")
• A small floating step tracker in the corner showing Step N of 6: <current step name> plus a "next" button so the operator can advance manually if the heuristic for auto-advancing misfires.
• Field-to-popup labels on the credential pages: when the operator hovers a value they need to copy, a tooltip shows which popup field it belongs in (-> Client ID / -> Client Secret / -> Bearer Token).

The popup retains its current form; the overlay is purely additive guidance on the dev console.

Technical approach

• Add content_scripts to psychological-operations-chromium-extension-auth/manifest.json matching https://console.x.com/*. The auth extension currently has host_permissions for the dev console but no content scripts (per its README: "No content_scripts (no DOM walker; the popup form is the only surface)") — that statement is what changes. While we're in the manifest, drop the now-stale https://developer.x.com/* host-permission since the flow lands on and stays within console.x.com.
• New file overlay.js (content script) + overlay.css. Detects the current page via URL pattern, looks up DOM anchors with selectors that target the dev console's stable structural elements (data-attributes preferred over class hashes, since X churns class names).
• Step state is per-tab, kept in chrome.storage.session. The popup reads the state to color its own form fields green when the matching credential is the current expected paste target.
• Step transitions: most steps auto-advance on the operator clicking the highlighted element (capture the click via the same content script). Manual "next" button as a fallback for edge cases (page-load failures, redesigns).
• Selector resilience: every selector goes through a findAnchor(strategies[]) helper that tries multiple patterns in order — data-testid, then ARIA labels, then text content, then class-name match. If all strategies miss, the overlay logs a warning and silently downgrades to "show step text only, no arrow". X's dev console does redesign occasionally; the overlay should never block the operator if its selectors break.
• Keep the overlay localized to the auth extension. The scrape extension (psychological-operations-chromium-extension-scrape/) is a separate ID and only runs on x.com — no overlap.

Acceptance criteria

• On first launch of psychological-operations x_app setup, the operator sees an arrow + step-1 banner pointing at "Create Project" on console.x.com without reading any CLI output.
• The OAuth 2.0 Client ID and Client Secret on the User Authentication Settings page are visually marked as -> Client ID / -> Client Secret.
• The OAuth 1.0a Consumer Key and Secret Key on the Keys and Tokens page are visually marked red with "OAuth 1.0a — do not use".
• The Bearer Token on the Keys and Tokens page is visually marked as -> Bearer Token.
• The User Authentication Settings page shows an annotation calling out that callback URI must be http://127.0.0.1/callback (host only, no port) and that permissions must be Read and write.
• After all three credentials are saved (the popup notifies state), the overlay shows a "setup complete" banner and stops drawing arrows.
• If a selector fails to resolve, the overlay logs a warning and shows step text without crashing; the operator is never blocked by missing arrows.
• The scrape extension is unaffected.

Files

• psychological-operations-chromium-extension-auth/manifest.json — add content_scripts block; drop the https://developer.x.com/* host-permission.
• psychological-operations-chromium-extension-auth/overlay.js (new) — overlay renderer + step machine.
• psychological-operations-chromium-extension-auth/overlay.css (new) — arrow / color / banner styles.
• psychological-operations-chromium-extension-auth/popup.js — read shared step state from chrome.storage.session to highlight the currently expected field.
• psychological-operations-chromium-extension-auth/README.md — update the "no content scripts" note; drop the developer.x.com reference.
• psychological-operations-cli/src/x_app/setup.rs:50-66 — once the overlay carries the guidance, the CLI's seven-line stderr block can be trimmed to a one-line "follow the in-page arrows" message.

Out of scope

• Auto-filling the popup form by scraping the credentials off the page — those values are sometimes obscured behind copy buttons / regenerate flows, and the X dev console layout shifts. Manual paste with strong visual guidance is more robust than fragile auto-fill.
• Localization of the overlay text — English only for v1.
• Detecting a partially-completed app (existing Project, missing user-auth settings, etc.). v1 assumes clean-slate setup; resumable mid-flow detection is a follow-up.