feat(installer): add browser installation wizard for clean machines

.github/workflows/ci.yml

@@ -115,3 +115,39 @@ jobs:
       - name: Run Windows native consent boundary
         shell: pwsh
         run: pnpm exec node --experimental-strip-types --test tests/native-review-consent.test.ts
+
+  # The installer suites import only Node built-ins and repository files, so no
+  # dependency installation is needed.
+  installer:
+    name: installer (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 20
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    steps:
+      - name: Checkout
+        uses: actions/checkout@34e114876b0b11c390a56381ad16ebd13914f8d5 # v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        with:
+          node-version: "24"
+
+      - name: Run installer suites
+        run: node --experimental-strip-types --test tests/install-wizard.test.ts tests/installer-server.test.ts tests/verify-package-files.test.ts tests/installer-probes.test.ts tests/installer-runner.test.ts tests/installer-preflight.test.ts tests/installer-posix-bootstrap.test.ts tests/installer-windows-bootstrap.test.ts
+
+      # The native tests skip off Windows; here every one must run and pass.
+      - name: Require native Windows installer tests
+        if: runner.os == 'Windows'
+        shell: pwsh
+        run: |
+          $output = & node --experimental-strip-types --test --test-reporter=tap --test-name-pattern "^native Windows" tests/installer-windows-bootstrap.test.ts 2>&1
+          $status = $LASTEXITCODE
+          $output | Write-Output
+          if ($status -ne 0) { exit $status }
+          $text = $output -join "`n"
+          $passes = [regex]::Match($text, "(?m)^# pass (\d+)$")
+          $skips = [regex]::Match($text, "(?m)^# skipped (\d+)$")
+          if (!$passes.Success -or [int]$passes.Groups[1].Value -lt 14 -or !$skips.Success -or [int]$skips.Groups[1].Value -ne 0) { throw "Native Windows installer tests were skipped or not selected" }

README.md

@@ -339,6 +339,7 @@ Start with the product-facing destination, then move into the operational refere
 | [Telemetry](docs/telemetry.md) | Approved fields and source limitations. |
 | [Delegated verification](docs/delegated-verification.md) | Practical verification guidance. |
 | [Skill style guide](docs/skill-style-guide.md) | The package skill contract. |
+| [Installation wizard (in development)](docs/install-wizard.md) | The browser installation wizard's design, security model and preview. Not a supported installation path yet. |
 
 <p align="right"><a href="#top">Back to top ↑</a></p>
 

assets/install-wizard/index.html

@@ -0,0 +1,47 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="color-scheme" content="dark">
+<title>Install Gentle Shell</title>
+<!-- The host's CSP is default-src 'self': no inline script or style, no
+     external resources. wizard.js renders every step with DOM APIs only. -->
+<link rel="stylesheet" href="/wizard.css">
+<script type="module" src="/wizard.js"></script>
+</head>
+<body>
+<a class="skip-link" href="#main">Skip to content</a>
+<div class="backdrop" aria-hidden="true"></div>
+<header class="topbar">
+	<p class="wordmark"><span class="wordmark-mark" aria-hidden="true">&gt;_</span> Gentle <span class="wordmark-accent">Shell</span></p>
+	<p class="topbar-note"><span class="dot" aria-hidden="true"></span> Local installer</p>
+</header>
+<main id="main" tabindex="-1">
+	<nav class="stages-nav" aria-label="Installation progress">
+		<ol id="stages" class="stages">
+			<li class="stage stage-current" aria-current="step"><span class="stage-dot" aria-hidden="true">1</span><span class="stage-label">Check</span></li>
+			<li class="stage stage-upcoming"><span class="stage-dot" aria-hidden="true">2</span><span class="stage-label">Review</span></li>
+			<li class="stage stage-upcoming"><span class="stage-dot" aria-hidden="true">3</span><span class="stage-label">Install</span></li>
+			<li class="stage stage-upcoming"><span class="stage-dot" aria-hidden="true">4</span><span class="stage-label">Done</span></li>
+		</ol>
+	</nav>
+	<div id="alert" class="alert-region" role="alert" aria-live="assertive" aria-atomic="true"></div>
+	<div id="view" class="view">
+		<section class="panel" aria-labelledby="view-title" data-stage="check">
+			<p class="eyebrow">Step 1 of 4 · Check</p>
+			<h1 id="view-title" tabindex="-1">Checking this computer</h1>
+			<p class="lead">Looking for Node.js, pnpm, Pi and Gentle Shell. Nothing changes until you confirm a plan.</p>
+			<div class="loader" aria-hidden="true"><span></span><span></span><span></span></div>
+			<noscript>
+				<p class="alert alert-warning">This installer needs JavaScript. Enable it for this page, or close this tab and press Ctrl+C in the terminal. Nothing was installed.</p>
+			</noscript>
+		</section>
+	</div>
+	<div id="status" class="sr-only" role="status" aria-live="polite" aria-atomic="true"></div>
+</main>
+<footer class="footer">
+	<p>This page talks only to the installer running on this computer at 127.0.0.1. Closing the tab does not stop it; use <strong>Close installer</strong> or press Ctrl+C in the terminal.</p>
+</footer>
+</body>
+</html>