README.md

@@ -24,9 +24,11 @@ irm https://git.mosaicstack.dev/mosaic/bootstrap/raw/branch/main/remote-install.
 
 ```bash
 git clone https://git.mosaicstack.dev/mosaic/bootstrap.git ~/src/mosaic-bootstrap
-bash ~/src/mosaic-bootstrap/install.sh
+cd ~/src/mosaic-bootstrap && bash install.sh
 ```
 
+If Node.js 18+ is available, the remote installer automatically uses the TypeScript wizard instead of the bash installer for a richer setup experience.
+
 The installer will:
 - Install the framework to `~/.config/mosaic/`
 - Add `~/.config/mosaic/bin` to your PATH
@@ -44,11 +46,32 @@ After install, open a new terminal (or `source ~/.bashrc`) and run:
 mosaic init
 ```
 
-This generates three files loaded into every agent session:
+If Node.js 18+ is installed, this launches an interactive wizard with two modes:
+
+- **Quick Start** (~2 min): agent name + communication style, sensible defaults for everything else
+- **Advanced**: full customization of identity, user profile, tools, runtimes, and skills
+
+The wizard configures three files loaded into every agent session:
 - `SOUL.md` — agent identity contract (name, style, guardrails)
 - `USER.md` — your user profile (name, timezone, accessibility, preferences)
 - `TOOLS.md` — machine-level tool reference (git providers, credentials, CLI patterns)
 
+It also detects installed runtimes (Claude, Codex, OpenCode), configures sequential-thinking MCP, and offers curated skill selection from 8 categories.
+
+### Non-Interactive Mode
+
+For CI or scripted installs:
+
+```bash
+mosaic init --non-interactive --name Jarvis --style direct --user-name Jason --timezone America/Chicago
+```
+
+All flags: `--name`, `--role`, `--style`, `--user-name`, `--pronouns`, `--timezone`, `--mosaic-home`, `--source-dir`.
+
+### Legacy Fallback
+
+If Node.js is unavailable, `mosaic init` falls back to the bash-based `mosaic-init` script.
+
 ## Launching Agent Sessions
 
 ```bash
@@ -78,6 +101,7 @@ You can still launch runtimes directly (`claude`, `codex`, etc.) — thin runtim
 ├── guides/PRD.md          ← Mandatory PRD requirements gate before coding
 ├── guides/DOCUMENTATION.md ← Mandatory documentation standard and gates
 ├── bin/                   ← CLI tools (mosaic, mosaic-init, mosaic-doctor, etc.)
+├── dist/                  ← Bundled wizard (mosaic-wizard.mjs)
 ├── guides/                ← Operational guides
 ├── rails/                 ← Quality rails, git scripts, portainer scripts
 ├── runtime/               ← Runtime adapters + runtime-specific references
@@ -111,7 +135,7 @@ requires `guides/PRD.md` before coding and `guides/DOCUMENTATION.md` for code/AP
 
 ```bash
 mosaic help                # Show all commands
-mosaic init                # Generate SOUL.md (agent identity)
+mosaic init                # Interactive wizard (or legacy init)
 mosaic doctor              # Health audit — detect drift and missing files
 mosaic sync                # Sync skills from canonical source
 mosaic bootstrap <path>    # Bootstrap a repo with Mosaic standards
@@ -243,6 +267,20 @@ mosaic doctor                                          # Standard audit
 ~/.config/mosaic/bin/mosaic-doctor --fail-on-warn      # Strict mode
 ```
 
+## Wizard Development
+
+The installation wizard is a TypeScript project in the root of this repo.
+
+```bash
+pnpm install              # Install dependencies
+pnpm dev                  # Run wizard from source (tsx)
+pnpm build                # Bundle to dist/mosaic-wizard.mjs
+pnpm test                 # Run tests (30 tests, vitest)
+pnpm typecheck            # TypeScript type checking
+```
+
+The wizard uses `@clack/prompts` for the interactive TUI and supports `--non-interactive` mode via `HeadlessPrompter` for CI and scripted installs. The bundled output (`dist/mosaic-wizard.mjs`) is committed to the repo so installs work without `node_modules`.
+
 ## Re-installing / Updating
 
 Pull the latest and re-run the installer:

STANDARDS.md

@@ -24,6 +24,7 @@ Master/slave model:
 - For runtime-agnostic delegation/orchestration, use `~/.config/mosaic/rails/orchestrator-matrix/` with repo-local `.mosaic/orchestrator/` state.
 - Avoid hardcoded secrets and token leakage in remotes/commits.
 - Do not perform destructive git/file actions without explicit instruction.
+- Browser automation (Playwright, Cypress, Puppeteer) MUST run in headless mode. Never launch a visible browser — it collides with the user's display and active session.
 
 ## Session Lifecycle Contract
 

guides/QA-TESTING.md

@@ -79,6 +79,17 @@ Template:
 | AC-2: ... | ... | ... |
 ```
 
+## Browser Automation (Hard Rule)
+
+All browser automation (Playwright, Cypress, Puppeteer) MUST run in **headless mode**.
+Launching a visible browser collides with the user's display and active session.
+
+- Playwright: use `headless: true` in config or `--headed` must NOT be passed
+- Cypress: use `cypress run` (headless by default), never `cypress open`
+- Puppeteer: use `headless: true` (default)
+
+If a project's `playwright.config.ts` does not explicitly set `headless: true`, add it before running tests.
+
 ## Test Quality Rules
 
 1. Test behavior and outcomes, not private implementation details.