/onboard

Repo overlay: if .streamsnow/overlays/onboard.md exists in this repo, read it first: committed, repo-specific additions and overrides (_shared/overlays.md). Outside Claude Code, also read _shared/other-agents.md.

Gets this machine, this repo and its Snowflake account ready to build and ship apps. Everything that needs no answers runs first, then one round of questions, then the build, then the steps that wait on other people. Re-running re-checks and does only what is missing. The trust rules at the top of setup.md apply throughout.

Narrate every step

• Open each stage with one line: what it does, and whether it will ask anything.
• Before each action, one line of what and why; after it, one line with the result. Actions that need no approval are narrated too.
• Every question says what it decides and what each answer changes. Setup questions follow the question rule in Stage 2.
• Close each stage with what got done and what is next. Plain words, no walls of text.

Stage 1 · Detect and prepare (no questions except one install approval)

1. Native Windows outside WSL: stop and follow setup.md §0.
2. Detect: streamsnow doctor --format json (no CLI: setup.md §0b first), whether streamsnow.config.yaml exists, whether apps/*/streamlit_app.py exists, whether .claude/settings.json enables streamsnow@streamsnow, and the Snowflake access inventory (setup.md §2a). Report the state in one line.
3. With any Snowflake access: the read-only investigation (setup.md §2b), including the admin check (setup.md §2d step 1).
4. One batched approval for every missing tool, then install one at a time and re-run doctor after each (setup.md §0b and §1). If snow was just installed or fixed, redo step 3.
5. The project Python environment (setup.md §1c) and the browser check (setup.md §1b).
6. Add the plugin to the repo's Claude settings when missing (setup.md §2e).

Nothing in Stage 1 writes streamsnow.config.yaml or the governed repo files.

Stage 2 · One round of questions

The question rule. Explain each setting immediately before its separate question. Use the host agent's question interface when it has one (Claude Code: AskUserQuestion, up to 4 per call); otherwise ask in chat and wait for an explicit answer. Detection never counts as confirmation: what Stage 1 found is the recommended first option. With a config already present nothing is being decided, so skip the setup questions (setup.md §2c). In order:

• no Snowflake connection: set it up for them, or guide them (setup.md §2a); then redo Stage 1 step 3;
• one question each: runtime, sources, app-data schema, denied schemas, deploy source, and the connection when §2a has not confirmed it (setup.md §2c);
• the defaults it does not ask: bullets explaining each, then one keep or change question (§2c);
• git name and email, only if missing;
• apps but no config: confirm the adopt plan (adopt.md);
• admin setup not confirmed: explain the script, then ask who runs it (setup.md §2d).

Stage 3 · Build (after the user confirms)

• No config, no apps: streamsnow configure with the confirmed flags, then streamsnow init --no-starter-app (setup.md §2c).
• Apps, no config: the adopt flow (adopt.md).
• Config present and doctor's repo-files lists missing files: init --no-starter-app writes only those.
• A non-default connection: choose how local preview reads it (setup.md §3).
• Then pre-commit install, and doctor until every required row passes. Show the tree and the result.

Stage 4 · Finish what waits on others

1. Snowflake admin setup when not confirmed (setup.md §2d): streamsnow ci-key create, the admin file in .internal/, the hand-off. Never run the admin SQL.
2. Once the admin objects are confirmed: offer ci-key verify, then streamsnow ci-key push (setup.md §2e).
3. With a GitHub remote, whether or not step 2 ran: read whether GitHub deletes merged branches and, if it does not, ask yes or no before turning it on (setup.md §2e).
4. Offer to commit the new repo files and .claude/settings.json.

Done when

Name the end state:

• Ready to build and preview: Stages 1 to 3 pass. Next: /build-app.
• Ready to deploy: Stage 4 passes too.

With only the first, name what is pending ("waiting on your Snowflake admin") and say that re-running /onboard re-checks.

Out of scope

Building an app: /build-app. Porting one: /migrate-app. Deploying: /ship-app.