# Gyro onboarding — 14 September 2026

Implemented on Gyro only, following the refined A intent chooser. Native HTML/CSS
diagrams distinguish assets, vault shares, an option quote and a seller offer.
The optional step disclosures are static explanations, not transaction forms or
numerical simulations. Eiko, Meryl, beta, app.js and financial helpers are unchanged.

## First visitor and returning flow

| Entry | Behaviour |
|---|---|
| Fresh browser, plain app URL | Show inline intro; app remains accessible below it |
| Skip intro / Escape while inside intro | Close it and remember `skipped` |
| Explore Vault / buying / listing | Open the existing destination and remember `completed` with its route |
| Returning preference present | Normal app; Guide stays beside Vault/Market |
| Existing Gyro fee or vault metadata cache | Normal app, including older cache versions |
| Direct `chain`, `asset` or `strike` URL | Preserve the direct-entry flow; no automatic intro |
| `demo=1` | No automatic intro, no onboarding storage reads/writes; manual Guide still works |
| `intro=1` | Explicit temporary preview, even for a returning or demo view |
| `intro=0` | Suppress this visit only; not a stored dismissal |

`completed` means the visitor chose an app destination, not that they completed
a transaction or passed a comprehension test. Opening Guide later does not reset
the stored preference. The guide has no auto-play, timed popup, forced connection,
modal, focus trap or mandatory quiz. Automatic display does not steal focus.

The prior-use snapshot is taken before app.js boots or writes new caches, avoiding
the race where a first visitor could appear to be returning. Only Gyro cache key
names are examined; values, balances and wallet identities are not read. This is
a browser-use hint, not a claim about whether an account has traded before.

## Preference and privacy boundary

Local storage key: `gyro:onboarding:v1`. Values contain only `version`, `status`
and, after a route choice, `route`. No cookies, analytics, account address,
timestamp or server calls are added. Existing application network behaviour is
unchanged. The preference is local to this browser and origin, not synced to a wallet.

If local storage is unavailable, session storage is tried. If both are denied,
the intro still closes and navigation still works; it may return on a later
visit. Bad JSON or unknown record versions cannot break the app. Clearing site
data or using another browser may show the intro again. Minor content edits do
not bump the preference version and nag established users.

## Engineering boundary

- `onboarding.js`: preference/UI controller, loaded before app.js for the snapshot.
- `onboarding.css`: Gyro-owned responsive styles; no cross-site dependency.
- Existing `switchMarketSubtab` and `switchTab` are the only engine operations.
  Routing preserves selected chain, asset, strike, form inputs and entry gates.
- No provider, signer, wallet connection, approval, deposit, buy or list is started
  by the guide. It never changes a disabled transaction control.
- Market pause/availability is still displayed by the existing Market page.
  “Explore” is navigation, not an assertion that trading is currently available.
- If onboarding.js fails to load, the intro/opener stay hidden and existing app
  controls stay intact. Missing engine navigation keeps the intro open with a retry/skip message.
  Configuration boot failure remains the app's blocking error.
- Skip/Escape returns focus to Guide. Choosing a destination focuses the visible
  Vault/Market navigation; manual reopening focuses the intro heading. Native
  details and buttons remain keyboard accessible.

## Checks

`node gyro/test-onboarding.mjs`: 30 cases covering fresh/returning/old-cache visits,
skip/completion, storage failures, direct links, preview flags, demo without storage,
configuration refusal, early-load retry, real navigation handlers and existing gates.

Existing demo, user-layout, three-site design, Markets pause and integrated
position UI tests pass. Fresh independent Astra reviewed the implementation and
tests. Live browser checks confirm skip → plain-URL reload stays closed, Guide →
Seller opens the correct role with wallet disconnected, and 320px has no horizontal
overflow or interactive target below 44px. Primary intro actions are 54px.

Screenshots in `img/designs/2026-09-14/`: `live-intro-desktop.png`,
`live-intro-mobile.png`, `returning-desktop.png`, `returning-mobile.png`.
They show real app rendering, not generated controls. All concept images and full
prompts remain in `ONBOARDING-STUDY-20260914.md` and `designs.html#sep14`.
No wallet transaction or public share publication was performed.