---
name: setup-browser-app
description: Prepare a student's local browser-app project, Git history, and browser preview with agent-operated tools. Use for Browser App Builder setup or missing local prerequisites.
---

# Set up a browser app

Read the [shared workflow](../../references/workflow.md). Help the student reach a working preview and local revision history without typing commands themselves.

1. **Inspect first.** Confirm the selected folder, operating system, file/shell access, Git, and browser/preview tools. Check host-provided tool paths as well as PATH before deciding software is missing. Inspect existing files and `git rev-parse --show-toplevel` if inside a repository. Do not accidentally operate on an enclosing repository. If this is not the intended project root, resolve the destination before initialization or staging.
2. **Prepare Git only if missing.** Reuse a working installation. Check the official [macOS](https://git-scm.com/install/mac) or [Windows](https://git-scm.com/install/windows) instructions before downloading. On Mac, the normal route is `xcode-select --install`; on Windows with WinGet, `winget install --id Git.Git -e --source winget`; otherwise use the official architecture-appropriate installer. Run commands through authorized shell tools. The student completes OS prompts, administrator authentication, or installer terms. Verify `git --version` in a fresh invocation afterward; a success dialog is not enough. Record the actual executable if PATH has not refreshed. Respect managed-device restrictions rather than bypassing them.
3. **Choose the setup path.** Read any agreed plan and [library selection](../../references/library-selection.md). For a new library app follow [managed setup](../../references/managed-build.md), including verified Node/npm, its starter/lockfile and actual development/test/production preview commands. If managed setup is selected, skip the next two plain-only steps and resume Start history. If no library is selected, retain the plain path below. Rerunning Setup adds only missing work; a working plain app is not permission to migrate it.
4. **Establish plain preview.** Prefer the host's preview service. Otherwise use an already-installed runtime to serve the project on loopback only. For the plain path do not install a runtime merely for preview; managed Node setup follows the separate instructions. Do not install Python, Homebrew, WSL, or an editor. For plain apps serve the project root so `/app/` and later `/tests/` can load JavaScript modules. Opening `file://` is not a substitute for verifying module-based preview. If no suitable service or browser tool exists, say exactly which capability is missing; planning can continue.
5. **Add the plain starter.** Inspect [starter files](../../assets/starter/) and copy them with file tools into an empty folder. In an existing folder, compare first and add only missing files. Preserve plans and host-created files. If a needed path has different content, explain the collision before replacing it; do not reset a working app to the starter. Merge missing ignore entries into an existing `.gitignore`, preserving its rules. Do not copy the Pages workflow yet.
6. **Start history.** Initialize the intended new project with `git init -b main`; preserve an existing repository's branch and settings. Follow the shared attribution rule and set any identity using `git config --local`. If attribution is deferred, do not commit. Inspect files, stage only intended public/synthetic content, inspect `git diff --cached`, and make the initial commit. Avoid global Git changes and unrelated remotes.
7. **Prove readiness.** Open the starter through the preview, confirm its module changes the status, and activate its button. On an existing app, verify its actual module loading and a representative interaction instead; do not require starter controls. Verify the project root and initial commit. Save `SETUP.md` with actual Git invocation/version, preview tool or exact existing-runtime invocation, app URL, test-page location, restart procedure, completed steps, and gaps. Record host-local paths only where needed for resuming; exclude private account details.

On rerun, recheck current state and finish missing work. Do not reinstall working tools, create duplicate history, overwrite files, or claim setup complete while preview or history is missing. Hand off to [Plan](../plan-browser-app/SKILL.md), or resume the stage that requested setup.