Alpaca BrowserOS authentication recovery

Use this procedure whenever the trading runtime says Alpaca credentials are missing even though the user is signed into Alpaca in BrowserOS Neo.

Hard rules

1. Load skills/trading-ops/SKILL.md first.
2. Use the authenticated BrowserOS Neo profile. Do not ask for credentials and do not use a fresh browser profile.
3. Paper credentials only. Never create, reveal, copy, store, or test live brokerage credentials through this procedure.
4. Never print, OCR, log, screenshot, paste into chat, or write either credential to a repo file.
5. Store each value directly from the clipboard into macOS Keychain, then clear the clipboard.
6. Broker reads are evidence only after an authenticated API request succeeds. A dashboard screenshot is not broker API proof.
7. Never treat a failed refresh as current state. Preserve the last confirmed timestamp and report the refresh as inconclusive.

Keychain contract

Value	Keychain service	Account
Paper API key	trading.alpaca.paper.api-key	paper
Paper API secret	trading.alpaca.paper.api-secret	paper

The helper scripts never print secret values.

Recovery workflow

1. Confirm the BrowserOS account

In BrowserOS Neo, open Alpaca and confirm all of the following before touching API credentials:

• The banner explicitly says Paper Trading.
• The account switcher is on PA3C5AG0CECQ (validation paper, ~$94,181.95, SPY 261016 put credit).
• Do not bind Keychain to PA3PYE08C9MN ($30k) or PA36N5ZP8S40 ($5k). Those books do not count toward n=30.
• Live brokerage 979807421 is blocked. Never copy live keys into the paper Keychain slots.
• Record the paper account identifier and visible equity as non-secret evidence.
• Do not infer that this is the repository's expected account. The API verification below decides that. scripts/sync_alpaca_state.py refuses to write data/system_state.json unless the broker account_number is PA3C5AG0CECQ.

2. Open Alpaca API keys

Use Alpaca's API navigation item. If a paper key already exists, use its reveal/copy controls. Create a new paper key only when the UI proves no reusable paper key exists.

Alpaca may display the secret only once. Store it immediately before navigating away.

3. Store values without transcript exposure

For the API key:

1. Click Alpaca's copy button for the paper API key.
2. Run:

uv run python scripts/store_alpaca_keychain.py api-key --from-clipboard

For the secret:

1. Click Alpaca's copy button for the paper API secret.
2. Run:

uv run python scripts/store_alpaca_keychain.py api-secret --from-clipboard

Each command validates a non-empty clipboard, writes the value to Keychain, verifies retrieval by digest, and clears the clipboard. Output contains only service name, length, and a short SHA-256 fingerprint.

4. Verify credential presence

uv run python scripts/run_with_alpaca_keychain.py --check

Expected result: both Keychain entries are present. No credential value is displayed.

5. Refresh broker truth

Run the canonical read paths with credentials injected only into the child process:

uv run python scripts/run_with_alpaca_keychain.py -- \
  uv run python scripts/sync_alpaca_state.py
uv run python scripts/run_with_alpaca_keychain.py -- \
  uv run python scripts/sync_closed_positions.py
uv run python scripts/put_credit_cohort_scorecard.py

Then verify the actual paper workflow:

uv run python scripts/run_with_alpaca_keychain.py -- make dry-run

A valid completion requires:

• sync_health.last_successful_sync advances to the current run.
• The authenticated account identifier matches the intended paper account.
• Inventory was fetched from Alpaca rather than inferred from a local empty list.
• make dry-run either produces a valid no-submit plan or fails for a market/risk reason, not BROKER_INVENTORY_UNVERIFIED.
• paper_only=true and live_blocked=true remain unchanged.

Failure handling

• BrowserOS not connected: start or attach BrowserOS Neo. Do not silently switch profiles.
• Clipboard empty: copy again. Do not create a placeholder.
• Keychain verification mismatch: stop. Do not run the broker client.
• API returns unauthorized: return to the paper API page and rotate only the paper key pair.
• API authenticates to an unexpected account: stop and preserve both account identifiers as non-secret evidence. Do not trade.
• Refresh leaves the prior last_successful_sync: report it as failed or inconclusive, never current.

Why this exists

The Alpaca dashboard can be authenticated while non-browser shells have no exported credentials. This skill bridges that gap without persisting secrets in .env, logs, chat, shell history, or Git, and forces a provider-authenticated read before any profitability or readiness claim.