claude-toolkit 0.1.20 → 0.1.24

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.24 (2026-06-01)
+
+- feat: add capacitor stack with Capgo OTA live updates, channels, and encryption
+
+## 0.1.22 (2026-04-11)
+
+- feat: add stack auto-detection with drift reporting
+
+## 0.1.21 (2026-04-11)
+
+- docs: improve README intro and standardize formatting
+
 ## 0.1.20 (2026-04-06)
 
 - docs: update storybook docs with Vitest 4 addon-vitest config

package/README.md

@@ -1,6 +1,12 @@
 # claude-toolkit
 
-Reusable Claude Code configuration toolkit with stack-specific connectors.
+**claude-toolkit is a toolbox that Claude Code picks up and uses on its own — no prompting required, saving tokens and ensuring consistent behavior across your team.**
+
+The toolkit auto-detects your tech stacks (SolidJS, Vite, Playwright, Cloudflare, etc.) and generates a `.claude/` directory that Claude Code automatically loads. Instead of every team member re-explaining project conventions, tooling, and patterns each session (burning tokens every time), Claude already knows — the knowledge is baked into the generated config. As your project evolves, the toolkit detects stack drift and suggests config updates to stay in sync.
+
+This means any developer on your team gets the same Claude behavior for a given project, regardless of how they prompt. The toolkit is project-specific but team-consistent: Claude follows the same debugging methodology, the same testing patterns, and the same code quality standards for everyone.
+
+Whether you're starting a new project from scratch or consolidating an existing one, the toolkit gives Claude immediate context about your stack and conventions — so it produces code that fits from day one, or aligns with what's already in place.
 
 ## Quick Start
 
@@ -19,45 +25,74 @@ bunx claude-toolkit init
 3. Claude Code picks up the generated config automatically
 
 ```ts
-import { defineConfig } from 'claude-toolkit'
+import { defineConfig } from "claude-toolkit";
 
 export default defineConfig({
-  stacks: ['solidjs', 'rust-wasm', 'cloudflare', 'protobuf'],
-  packageManager: 'bun',
+  stacks: ["solidjs", "rust-wasm", "cloudflare", "protobuf"],
+  packageManager: "bun",
   hooks: {
-    formatter: 'bun run prettier --write',
-    testRunner: 'bun run vitest run',
-    typeCheck: 'bun run tsc --noEmit',
-    extraChecks: ['cargo check --target wasm32-unknown-unknown'],
+    formatter: "bun run prettier --write",
+    testRunner: "bun run vitest run",
+    typeCheck: "bun run tsc --noEmit",
+    extraChecks: ["cargo check --target wasm32-unknown-unknown"],
   },
   git: {
-    branchPrefix: 'wq',
-    protectedBranches: ['main'],
+    branchPrefix: "feat",
+    protectedBranches: ["main"],
   },
-})
+});
 ```
 
 ## CLI Commands
 
-| Command | Description |
-|---------|-------------|
-| `bunx claude-toolkit init` | Scaffold config file and generate `.claude/` |
+| Command                    | Description                                              |
+| -------------------------- | -------------------------------------------------------- |
+| `bunx claude-toolkit init` | Scaffold config file and generate `.claude/`             |
 | `bunx claude-toolkit sync` | Regenerate `.claude/` from config (after toolkit update) |
-| `bunx claude-toolkit help` | Show available commands |
+| `bunx claude-toolkit help` | Show available commands                                  |
+
+## Stack Auto-Detection
+
+The toolkit automatically detects which stacks your project uses by scanning `package.json` dependencies, config files, and project structure.
+
+**On `init`** (new project), detected stacks are pre-filled in the generated config:
+
+```text
+Detected stacks:
+  solidjs    — found solid-js in dependencies
+  vite       — found vite.config.ts
+  cloudflare — found wrangler.toml
+
+Created claude-toolkit.config.ts
+```
+
+**On `sync`** (existing config), the toolkit compares your configured stacks against what it detects and reports any drift:
+
+```text
+Stack drift detected:
+  + playwright — found @playwright/test in dependencies (not in config)
+  - rust-wasm  — in config but not detected in project
+
+Suggested update in claude-toolkit.config.ts:
+  stacks: ["solidjs", "vite", "cloudflare", "playwright"]
+```
+
+This keeps your config aligned as your project evolves — stacks you add or remove are surfaced automatically. The suggestion is informational; your config is not modified unless you update it yourself.
 
 ## Available Stacks
 
-| Stack | Skills Added |
-|-------|-------------|
-| `solidjs` | SolidJS reactivity, signals, components |
-| `vite` | Vite build config, plugins, Vitest testing, coverage, browser mode |
-| `vanilla-extract` | Type-safe CSS, sprinkles, recipes, themes |
-| `rust-wasm` | Rust WASM for Cloudflare Workers |
-| `protobuf` | Protocol Buffers, code generation, contracts |
-| `cloudflare` | D1 database, KV cache, Wrangler |
-| `i18n-typesafe` | typesafe-i18n internationalization |
-| `playwright` | Playwright E2E testing, Page Objects, fixtures, CI/CD |
-| `storybook` | Storybook interaction testing, CSF 3, visual regression |
+| Stack             | Skills Added                                                       |
+| ----------------- | ------------------------------------------------------------------ |
+| `solidjs`         | SolidJS reactivity, signals, components                            |
+| `vite`            | Vite build config, plugins, Vitest testing, coverage, browser mode |
+| `vanilla-extract` | Type-safe CSS, sprinkles, recipes, themes                          |
+| `rust-wasm`       | Rust WASM for Cloudflare Workers                                   |
+| `protobuf`        | Protocol Buffers, code generation, contracts                       |
+| `cloudflare`      | D1 database, KV cache, Wrangler                                    |
+| `i18n-typesafe`   | typesafe-i18n internationalization                                 |
+| `playwright`      | Playwright E2E testing, Page Objects, fixtures, CI/CD              |
+| `storybook`       | Storybook interaction testing, CSF 3, visual regression            |
+| `capacitor`       | Capacitor 8 native runtime, Capgo OTA live updates, channels       |
 
 ## Core Features (always included)
 

package/bin/cli.ts

@@ -11,6 +11,7 @@
 import { existsSync } from "node:fs";
 import { readFile, writeFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
+import { detectStacks } from "../src/detect.js";
 import { generate } from "../src/generator.js";
 import type { ClaudeToolkitConfig } from "../src/types.js";
 
@@ -19,9 +20,7 @@ const CONFIG_FILENAME = "claude-toolkit.config.ts";
 async function loadConfig(projectDir: string): Promise<ClaudeToolkitConfig> {
 	const configPath = join(projectDir, CONFIG_FILENAME);
 	if (!existsSync(configPath)) {
-		throw new Error(
-			`Config not found: ${configPath}\nRun "claude-toolkit init" first.`,
-		);
+		throw new Error(`Config not found: ${configPath}\nRun "claude-toolkit init" first.`);
 	}
 	const module = await import(configPath);
 	return module.default as ClaudeToolkitConfig;
@@ -36,23 +35,37 @@ async function init(projectDir: string): Promise<void> {
 		return sync(projectDir);
 	}
 
-	// Copy starter config
-	const templatePath = join(
-		import.meta.dirname,
-		"..",
-		"templates",
-		"claude-toolkit.config.ts",
-	);
+	// Detect stacks
+	const detected = detectStacks(projectDir);
+	if (detected.length > 0) {
+		console.log("Detected stacks:");
+		const maxLen = Math.max(...detected.map((d) => d.name.length));
+		for (const d of detected) {
+			console.log(`  ${d.name.padEnd(maxLen)} — ${d.reason}`);
+		}
+	} else {
+		console.log(`No stacks detected. You can add them manually in ${CONFIG_FILENAME}`);
+	}
+
+	// Build stacks literal for config injection
+	const stacksLiteral =
+		detected.length > 0
+			? `stacks: [${detected.map((d) => `"${d.name}"`).join(", ")}]`
+			: "stacks: []";
+
+	// Copy starter config with detected stacks injected
+	const templatePath = join(import.meta.dirname, "..", "templates", "claude-toolkit.config.ts");
 	if (existsSync(templatePath)) {
 		const template = await readFile(templatePath, "utf-8");
-		await writeFile(configPath, template, "utf-8");
+		const configContent = template.replace("stacks: []", stacksLiteral);
+		await writeFile(configPath, configContent, "utf-8");
 		console.log(`Created ${CONFIG_FILENAME}`);
 	} else {
 		// Inline fallback
 		const defaultConfig = `import { defineConfig } from 'claude-toolkit'
 
 export default defineConfig({
-  stacks: [],
+  ${stacksLiteral},
   packageManager: 'bun',
   hooks: {
     formatter: 'bun run prettier --write',
@@ -75,6 +88,38 @@ export default defineConfig({
 
 async function sync(projectDir: string): Promise<void> {
 	const config = await loadConfig(projectDir);
+
+	// Compare detected stacks against config
+	const detected = detectStacks(projectDir);
+	const configuredNames = new Set(config.stacks);
+	const detectedNames = new Set(detected.map((d) => d.name));
+
+	const missing = detected.filter((d) => !configuredNames.has(d.name));
+	const stale = config.stacks.filter((s) => !detectedNames.has(s));
+
+	if (missing.length > 0 || stale.length > 0) {
+		console.log("\nStack drift detected:");
+		if (missing.length > 0) {
+			const maxLen = Math.max(...missing.map((d) => d.name.length));
+			for (const d of missing) {
+				console.log(`  + ${d.name.padEnd(maxLen)} — ${d.reason} (not in config)`);
+			}
+		}
+		if (stale.length > 0) {
+			for (const s of stale) {
+				console.log(`  - ${s} — in config but not detected in project`);
+			}
+		}
+		const suggested = [
+			...new Set([
+				...config.stacks.filter((s) => !stale.includes(s)),
+				...missing.map((d) => d.name),
+			]),
+		];
+		console.log(`\nSuggested update in ${CONFIG_FILENAME}:`);
+		console.log(`  stacks: [${suggested.map((s) => `"${s}"`).join(", ")}]\n`);
+	}
+
 	await generate(projectDir, config);
 	console.log("Sync complete.");
 }

package/docs/README.md

@@ -50,3 +50,4 @@ Stack-specific skills activated based on your `claude-toolkit.config.ts` configu
 | [ct-i18n-typesafe](stacks/i18n-typesafe.md)                       | `i18n-typesafe`   | Type-safe internationalization with compile-time key checking                  |
 | [ct-playwright-patterns](stacks/playwright-patterns.md)           | `playwright`      | E2E testing with Page Objects, fixtures, auth, network mocking, CI/CD          |
 | [ct-storybook-patterns](stacks/storybook-patterns.md)             | `storybook`       | Interaction testing, CSF 3, play functions, a11y, visual regression            |
+| [ct-capacitor-ota](stacks/capacitor-ota.md)                       | `capacitor`       | Capacitor 8 native runtime and Capgo OTA live updates, channels, encryption    |

package/docs/best-practices/capacitor/README.md

@@ -0,0 +1,64 @@
+# Capacitor & OTA Best Practices
+
+> A curated collection of best practices for Capacitor 8 native apps and Capgo over-the-air (OTA) live updates, sourced from official Capacitor documentation, the Capgo docs and blog, and the plugin maintainers as of June 2026.
+
+Capacitor wraps a web app (your `webDir` bundle) in a native iOS/Android shell. **OTA** lets you replace that web bundle on installed devices in minutes — without an app store review cycle. Capgo (`@capgo/capacitor-updater`) is the live-update layer that delivers, verifies, and rolls back those bundles.
+
+```
+        ┌─────────────────────────────┐
+        │   Native shell (store)      │  ← Capacitor core + plugins; ships via App Store / Play
+        │  ┌───────────────────────┐  │     Changes here REQUIRE a new binary.
+        │  │   Web bundle (OTA)    │  │  ← JS / HTML / CSS; swapped by Capgo in minutes.
+        │  │   notifyAppReady() ✓  │  │     Changes here ship over the air.
+        │  └───────────────────────┘  │
+        └─────────────────────────────┘
+```
+
+## The Two Layers — and the Golden Rule
+
+| Layer          | What it is                                  | How it ships                | Review latency      |
+| -------------- | ------------------------------------------- | --------------------------- | ------------------- |
+| **Native**     | Capacitor core, plugins, native deps        | App Store / Google Play     | Hours to days       |
+| **Web (OTA)**  | Your compiled `webDir` (JS/HTML/CSS/assets) | Capgo channel swap          | Minutes             |
+
+**Golden rule:** OTA the web layer only. If a change needs a native API the installed shell doesn't have — a new plugin, a native dependency, a Capacitor major bump — it **must** go through the store first. OTA-ing a native contract mismatch crashes the app. Every other rule in this guide follows from this one.
+
+## When to Use Which Channel
+
+| Question                                                          | Answer                                  |
+| ----------------------------------------------------------------- | --------------------------------------- |
+| Did I change native code, add a plugin, or bump Capacitor major?  | **Store binary** (then OTA on top)      |
+| Bug fix / copy change / styling / feature in JS only?             | **OTA** to `production`                 |
+| Needs QA sign-off before users see it?                            | **OTA** to `staging`, promote later     |
+| Testing on dev/emulator builds?                                   | **OTA** to `development`                |
+| Need to undo a bad release right now?                             | **Channel rollback** (crown icon)       |
+
+## Technology Versions (as of June 2026)
+
+| Tool                       | Version | Notes                                                            |
+| -------------------------- | ------- | ---------------------------------------------------------------- |
+| `@capacitor/core` & CLI    | ^8.3.x  | 8.3.1 (2026-04-16); Node 22+ required                            |
+| `@capacitor/ios`           | ^8.3.x  | iOS 15.0 target, Xcode 26+, SPM default for new projects         |
+| `@capacitor/android`       | ^8.3.x  | minSdk 24, compileSdk/targetSdk 36, Gradle 8.14.3, Kotlin 2.2.20 |
+| `@capgo/capacitor-updater` | ^8.x    | Major tracks Capacitor major; v8 stores channel locally          |
+| `@capgo/cli`               | latest  | `npx @capgo/cli@latest …` — pin in CI                            |
+
+## Shared Principles
+
+1. **`notifyAppReady()` is non-negotiable.** Call it at the top of bootstrap. Without it, every OTA bundle auto-rolls back after `appReadyTimeout`.
+2. **Match the bundle to the shell.** A web bundle is only valid against the native version that shipped it. Use channel version gates to prevent mismatches.
+3. **Stage every rollout.** Canary to ~10%, widen over 24h. Instant rollback beats instant deploy.
+4. **Sign your bundles.** End-to-end encryption (RSA-2048 + AES-256) means only your users can read an update — keep the private key out of git.
+5. **Keep the cloud in control of production.** Omit `defaultChannel` from production binaries so the dashboard default governs rollout and rollback.
+6. **Monitor before you widen.** Watch the `appReady` / `downloadFailed` ratio; a spike is your signal to roll back.
+7. **Pin tooling.** Unpinned `@capgo/cli@latest` in CI can change upload behavior between runs.
+
+## Guides
+
+| Guide                                             | Summary                                                                         |
+| ------------------------------------------------- | ------------------------------------------------------------------------------- |
+| [Capacitor 8 Platform](capacitor-8.md)            | Version floor, breaking changes, SPM-by-default, SystemBars, upgrade checklist. |
+| [Live Updates & OTA Strategy](live-updates-ota.md) | What to OTA vs ship native, performance, delta updates, scheduling.             |
+| [Capgo Setup & API](capgo-setup.md)               | Plugin install, config, `notifyAppReady`, autoUpdate modes, manual flow, CLI.   |
+| [Channels & Staged Rollouts](channels-and-rollouts.md) | Channel ladder, precedence, canary rollouts, rollback, monitoring.         |
+| [Security & Encryption](security-encryption.md)   | E2E encryption (v2), key management, code signing, store compliance.            |

package/docs/best-practices/capacitor/capacitor-8.md

@@ -0,0 +1,60 @@
+# Capacitor 8 Platform
+
+> Capacitor 8 raised the platform floor across the board. Get the toolchain right before touching OTA — a mismatched native baseline is the first thing that breaks live updates.
+
+Latest at time of writing: **8.3.1** (2026-04-16). 8.3.0 (2026-03-25) and 8.2.0 (2026-03-06) precede it.
+
+## Minimum Requirements
+
+| Area    | Requirement                                                                 |
+| ------- | --------------------------------------------------------------------------- |
+| Node    | **22+** (latest LTS recommended)                                            |
+| iOS     | Xcode **26.0+**, deployment target **15.0**                                 |
+| Android | Android Studio Otter (2025.2.1)+, `minSdk 24`, `compileSdk 36`, `targetSdk 36` |
+| Gradle  | Android Gradle plugin **8.13.0**, wrapper **8.14.3**, Kotlin **2.2.20**     |
+
+## Headline Changes
+
+### Swift Package Manager is the default (iOS)
+
+New iOS projects scaffold with **SPM instead of CocoaPods**. Existing CocoaPods projects keep working — the ecosystem is migrating, not forcing a cutover. 8.3.0 added experimental config for `swift-tools-version` and support for SPM package traits in the generated `Package.swift`.
+
+### Edge-to-edge via the SystemBars plugin (Android)
+
+An internal `SystemBars` plugin now handles status/navigation bar appearance for immersive layouts automatically, with a public API for fine control. It version-gates behavior and coexists with `@capacitor/status-bar`. Consequently the old config flag **`android.adjustMarginsForEdgeToEdge` was removed** — use SystemBars instead.
+
+## Breaking Changes Checklist
+
+When upgrading to Capacitor 8:
+
+- [ ] **Node 22+** on every dev machine and CI runner.
+- [ ] **Android config syntax:** Gradle properties now require `=` (e.g. `compileSdk = 36`, not `compileSdk 36`).
+- [ ] **Android layout rename:** `bridge_layout_main.xml` → `capacitor_bridge_layout_main.xml`.
+- [ ] **Android resize:** add `density` to `configChanges` in `AndroidManifest.xml` to stop the WebView reloading on resize.
+- [ ] **Remove `android.adjustMarginsForEdgeToEdge`** from `capacitor.config` — replaced by SystemBars.
+- [ ] **iOS `appendUserAgent`:** the fixed concatenation may need a leading space to preserve your intended user-agent string.
+- [ ] **iOS lifecycle:** the framework now emits `viewDidAppear` / `viewWillTransition` — delete any custom extensions that duplicated this.
+
+## 8.2–8.3 Notable Fixes
+
+These land automatically on patch upgrades but are worth knowing because they touch OTA-adjacent behavior:
+
+- **Android `server.url` with paths** is now parsed correctly (8.3.0) — relevant if you point the WebView at a custom/self-hosted update host.
+- **Android `isNewBinary()`** handles a null `versionName` (8.3.1) — the check that decides whether a native update invalidates OTA bundles.
+- **HTTP `fetch`** handles `URL` objects and form-data boundary extraction (8.3.0/8.3.1).
+- **CLI** inlines CSS sourcemaps alongside JS (8.3.0) and respects `CAPACITOR_COCOAPODS_PATH` (8.3.1).
+
+## Keeping Native and OTA in Lockstep
+
+The single most important interaction: **a native upgrade invalidates incompatible OTA bundles.** `resetWhenUpdate: true` (the Capgo default) wipes downloaded bundles when the native app updates, so users fall back to the bundle baked into the new binary rather than running a stale OTA bundle against new native code. Keep it on unless you have a specific reason not to.
+
+When you bump Capacitor or add a plugin:
+
+1. Ship a new store binary with the updated native layer.
+2. Bump your bundle's version so old shells don't pull a bundle meant for the new native contract.
+3. Use channel version gates (`--disable-auto-update major|minor`) to enforce the boundary.
+
+## See Also
+
+- [Live Updates & OTA Strategy](live-updates-ota.md) — what's safe to OTA on top of a given binary
+- [Channels & Staged Rollouts](channels-and-rollouts.md) — version gates that enforce the native/web contract

package/docs/best-practices/capacitor/capgo-setup.md

@@ -0,0 +1,151 @@
+# Capgo Setup & API
+
+> `@capgo/capacitor-updater` ships in three modes: fully managed (Capgo Cloud), self-hosted (your own update server), or manual (you drive every download/apply in JS). This guide covers the managed path and the manual escape hatch.
+
+## Install
+
+```bash
+npm i @capgo/capacitor-updater && npx cap sync
+npx @capgo/cli@latest init <API_KEY>
+```
+
+`init` is an interactive onboarding: it registers the app in Capgo Cloud, injects the `notifyAppReady()` call, builds, uploads the first bundle, and verifies the update round-trips. Run it once per app.
+
+## notifyAppReady() — Read This First
+
+```typescript
+import { CapacitorUpdater } from "@capgo/capacitor-updater";
+
+// As early as possible in bootstrap, before heavy async work.
+CapacitorUpdater.notifyAppReady();
+```
+
+The plugin arms a timer (`appReadyTimeout`, default **10000ms**) the moment a bundle loads. Call `notifyAppReady()` before it fires and the bundle is confirmed; miss it and the plugin **auto-rolls back** to the previous bundle. This is the mechanism that makes a broken release self-heal — never remove it, and don't bury it behind slow startup code.
+
+## Configuration Reference
+
+```typescript
+// capacitor.config.ts
+import type { CapacitorConfig } from "@capacitor/cli";
+
+const config: CapacitorConfig = {
+  appId: "com.example.app",
+  appName: "Example",
+  webDir: "dist",
+  plugins: {
+    CapacitorUpdater: {
+      autoUpdate: "atBackground",
+      appReadyTimeout: 10000,
+      responseTimeout: 20,
+      autoDeleteFailed: true,
+      autoDeletePrevious: true,
+      resetWhenUpdate: true,
+      // defaultChannel: "Development", // TEST/QA BUILDS ONLY
+      // publicKey: "...",              // injected by `key create` for E2E encryption
+    },
+  },
+};
+
+export default config;
+```
+
+| Setting              | Default                                | Purpose                                                       |
+| -------------------- | -------------------------------------- | ------------------------------------------------------------ |
+| `autoUpdate`         | `"atBackground"`                       | When to apply downloaded updates (see table below)           |
+| `appReadyTimeout`    | `10000` (ms)                           | Grace period for `notifyAppReady()` before rollback          |
+| `responseTimeout`    | `20` (s)                               | Update-server API call timeout                               |
+| `periodCheckDelay`   | `600` (s)                              | Poll interval; **cannot be < 600**                           |
+| `autoDeleteFailed`   | `true`                                 | Remove bundles that failed to apply                          |
+| `autoDeletePrevious` | `true`                                 | Remove the prior bundle after a successful update            |
+| `resetWhenUpdate`    | `true`                                 | Wipe OTA bundles when the native app updates                 |
+| `defaultChannel`     | _(unset)_                              | Pin a channel — **test builds only**                         |
+| `allowModifyUrl`     | `false`                                | Let JS change update/stats/channel URLs at runtime           |
+| `publicKey`          | _(unset)_                              | RSA public key for end-to-end encryption (v2)                |
+| `updateUrl`          | `https://plugin.capgo.app/updates`     | Update-check endpoint (override for self-hosted)             |
+| `statsUrl`           | `https://plugin.capgo.app/stats`       | Stats endpoint                                               |
+| `channelUrl`         | `https://plugin.capgo.app/channel_self`| Channel self-assignment endpoint                            |
+
+> `directUpdate` is deprecated. Use the `autoUpdate` string modes instead.
+
+## autoUpdate Modes
+
+| Value                        | Behavior                                                       |
+| ---------------------------- | -------------------------------------------------------------- |
+| `false` / `"off"`            | No automatic updates — you drive the lifecycle from JS         |
+| `"atBackground"` *(default)* | Download silently; apply when the app moves to the background  |
+| `"atInstall"`                | Apply immediately after a fresh install / native update        |
+| `"onLaunch"`                 | Apply immediately on next launch, then revert to background    |
+| `"always"`                   | Apply immediately whenever an update check runs                |
+| `"onlyDownload"`             | Download but never auto-apply; emits `updateAvailable`         |
+
+**Default lifecycle:** on launch Capgo checks the channel → downloads any new bundle silently → waits for background/close → user gets the update on next launch. Seamless, no spinner.
+
+## Manual Mode
+
+Set `autoUpdate: false` to control everything yourself — useful for custom UX (e.g. "Update available" prompts) or applying only on explicit user action.
+
+```typescript
+import { CapacitorUpdater } from "@capgo/capacitor-updater";
+import { App } from "@capacitor/app";
+import { SplashScreen } from "@capacitor/splash-screen";
+
+CapacitorUpdater.addListener("download", ({ percent }) => {
+  console.log(`Downloading: ${percent}%`);
+});
+
+App.addListener("appStateChange", async ({ isActive }) => {
+  if (isActive) {
+    const latest = await CapacitorUpdater.getLatest();
+    if (latest.url) {
+      const bundle = await CapacitorUpdater.download({
+        version: latest.version,
+        url: latest.url,
+      });
+      await CapacitorUpdater.next({ id: bundle.id }); // queue for next background
+    }
+  }
+});
+```
+
+### Core methods
+
+| Method            | Purpose                                                        |
+| ----------------- | -------------------------------------------------------------- |
+| `notifyAppReady()`| Confirm the current bundle booted (always required)           |
+| `getLatest()`     | Query the server for the latest bundle metadata                |
+| `download()`      | Download a bundle by `{ version, url }`                        |
+| `next({ id })`    | Queue a bundle to apply on next background                     |
+| `set({ id })`     | Apply a bundle now — **destroys the JS context** (hard reload) |
+| `current()`       | Inspect the active bundle + native version                    |
+| `reload()`        | Apply a pending update without backgrounding                   |
+| `reset()`         | Revert to the bundle baked into the native binary             |
+| `setChannel()`    | Switch the device's channel at runtime (v8+, self-assign)     |
+
+### Events
+
+`download` · `downloadComplete` · `updateAvailable` · `downloadFailed` · `appReady` · `majorAvailable`
+
+Subscribe to `downloadFailed` and `appReady` for monitoring; subscribe to `majorAvailable` to detect a bundle that requires a native update you can't OTA.
+
+## CLI Cheat Sheet
+
+```bash
+npx @capgo/cli@latest login <API_KEY>                       # store key (--local to scope to repo)
+npx @capgo/cli@latest app add com.example.app               # register an app
+npx @capgo/cli@latest bundle upload --channel=production     # build → upload → assign
+npx @capgo/cli@latest bundle upload --key-v2 --channel=production   # encrypted upload
+npx @capgo/cli@latest bundle upload --delta-only            # require delta-capable clients
+npx @capgo/cli@latest bundle compatibility -c production    # check native compatibility first
+npx @capgo/cli@latest channel set production -s default     # set the cloud default channel
+npx @capgo/cli@latest key create                            # generate the E2E key pair
+```
+
+Useful `bundle upload` flags: `--channel`, `--key-v2` / `--no-key`, `--delta` / `--delta-only`, `--external` (link your own storage), `--tus` (resumable upload), `--encrypted-checksum`.
+
+**Pin the CLI version in CI** (`@capgo/cli@8.x` rather than `@latest`) so upload behavior doesn't change between pipeline runs.
+
+## See Also
+
+- [Channels & Staged Rollouts](channels-and-rollouts.md) — what `--channel` and `setChannel` actually do
+- [Security & Encryption](security-encryption.md) — the `--key-v2` flow in full
+- [Live Updates & OTA Strategy](live-updates-ota.md) — when to use each `autoUpdate` mode

package/docs/best-practices/capacitor/channels-and-rollouts.md

@@ -0,0 +1,101 @@
+# Channels & Staged Rollouts
+
+> A channel is a pointer to one JS bundle. Devices subscribe to a channel; you change which bundle the channel points to. That indirection is what makes rollout and rollback instant and rebuild-free.
+
+## The Channel Ladder
+
+Mirror your release pipeline with channels, and version bundles with semver pre-release tags so relationships are obvious:
+
+| Channel       | Bundle version | Audience                  |
+| ------------- | -------------- | ------------------------- |
+| `development` | `1.2.3-dev.1`  | dev / emulator builds     |
+| `qa`          | `1.2.3-qa.1`   | QA verification           |
+| `staging`     | `1.2.3-rc.1`   | production-like sign-off  |
+| `production`  | `1.2.3`        | end users (store version) |
+
+Promote a build up the ladder by uploading (or re-pointing) it to the next channel — no native rebuild between stages.
+
+```bash
+npx @capgo/cli@latest bundle upload --channel=staging       # ship to staging
+# ...QA signs off...
+npx @capgo/cli@latest bundle upload --channel=production     # promote to production
+npx @capgo/cli@latest channel set production -s default      # ensure it's the cloud default
+```
+
+## Channel Precedence
+
+When a device checks for updates, Capgo resolves the channel in this order (highest wins):
+
+1. **Forced device mapping** — pin specific device IDs (testing/exception layer).
+2. **Cloud per-device override** — dashboard/API change for one device (up to ~2 min to propagate).
+3. **Config `defaultChannel`** — set in `capacitor.config` (baked into the binary).
+4. **Cloud Default Channel** — the fallback ~99% of users follow.
+
+**Production rule:** ship production binaries **without** `defaultChannel`. If you bake a channel into the binary, those users stop following the cloud default — which is exactly the lever you use for instant rollout and rollback. Reserve `defaultChannel` for builds you hand directly to testers.
+
+## Runtime Switching with setChannel()
+
+Let users opt into a beta from inside the app:
+
+```typescript
+import { CapacitorUpdater } from "@capgo/capacitor-updater";
+
+await CapacitorUpdater.setChannel({ channel: "beta", triggerAutoUpdate: true });
+```
+
+- Requires **"Allow device self-assignment"** enabled on the target channel; otherwise the call fails.
+- In **plugin v8+**, `setChannel` stores the choice **locally on the device** and takes effect on the next update check — no 2-minute backend replication lag. The backend still validates the self-assignment permission at check time.
+
+```bash
+npx @capgo/cli@latest channel set beta --self-assign        # enable opt-in
+```
+
+## Version Gates: Enforce the Native/Web Contract
+
+Channels can refuse updates that cross a version boundary the native shell can't honor:
+
+```bash
+# Block cross-major OTA on production (e.g. don't push a 2.x bundle to 1.x shells)
+npx @capgo/cli@latest channel set production --disable-auto-update major
+```
+
+| `--disable-auto-update` | Allows                                              |
+| ----------------------- | --------------------------------------------------- |
+| `major`                 | minor + patch within the same major                 |
+| `minor`                 | patch only within the same major.minor              |
+| `patch`                 | patch increments only                               |
+| `metadata`              | requires minimum version metadata on bundles        |
+| `none`                  | all semver-compatible updates                       |
+
+Also available: **disable auto-downgrade** (don't send a bundle older than the device's native version) and per-platform targeting (`--ios`, `--android`). These gates are how you keep a web bundle from landing on a shell that can't run it.
+
+## Staged Rollout Playbook
+
+1. **Canary** — point the channel at the new bundle for ~10% of users (or a dedicated `canary` channel).
+2. **Observe** — watch the success signal for 1–2 hours (next section).
+3. **Widen** — ramp to 100% over ~24h if healthy.
+4. **Schedule** — time heavy rollouts for **1–4 AM local**, Wi-Fi-preferred, so downloads don't compete with active use.
+
+**Benchmarks:** aim for **~95% adoption within 24h** and **~82% global success rate**. Falling short is a signal to pause and investigate, not to widen.
+
+## Rollback
+
+Instant and rebuild-free — the core OTA payoff:
+
+1. Open the channel in the Capgo dashboard.
+2. Find the previous good build and click the **crown icon**.
+3. Confirm. The channel now points at the old bundle; devices pick it up on next check-in.
+
+Because rollback is this cheap, bias toward shipping small and reverting fast over holding releases for exhaustive pre-launch testing.
+
+## Monitoring
+
+- **`appReady` vs `downloadFailed`** — the health ratio. A `downloadFailed` spike, or `appReady` events not keeping pace with downloads, means bundles are failing to boot → roll back.
+- **Capgo stats dashboard** — adoption curve and per-version success rate. Compare against the 95% / 82% benchmarks.
+- **Alert, then act** — wire a threshold alert so a bad canary pages you before you widen.
+
+## See Also
+
+- [Live Updates & OTA Strategy](live-updates-ota.md) — why staged rollout is the whole point
+- [Capacitor 8 Platform](capacitor-8.md) — what makes a bundle native-incompatible
+- [Security & Encryption](security-encryption.md) — signing the bundles a channel serves