claude-toolkit 0.1.20 → 0.1.24

package/docs/best-practices/capacitor/live-updates-ota.md

@@ -0,0 +1,75 @@
+# Live Updates & OTA Strategy
+
+> OTA is a delivery mechanism for the **web layer**, not a way around the app stores. The strategy is mostly about discipline: knowing what you can ship over the air, keeping bundles small, and rolling out so a mistake is recoverable.
+
+## What You Can — and Cannot — Ship Over the Air
+
+| Change                                          | OTA? | Why                                                          |
+| ----------------------------------------------- | ---- | ----------------------------------------------------------- |
+| Bug fix in JS/TS                                | ✅   | Pure web layer                                              |
+| Copy, translations, styling                     | ✅   | Static assets in the bundle                                 |
+| New feature built on existing native APIs       | ✅   | No new native contract                                      |
+| Web-only dependency upgrade                     | ✅   | Compiles into the bundle                                    |
+| New Capacitor **plugin** (native code)          | ❌   | Native shell lacks the implementation → crash              |
+| Native dependency / SDK upgrade                 | ❌   | Native binary change                                        |
+| Capacitor **major** version bump                | ❌   | Native runtime change                                       |
+| Permission / entitlement / manifest change      | ❌   | Declared in the native binary                               |
+
+The failure mode is concrete: a bundle that calls `SomePlugin.doThing()` on a shell where that plugin isn't compiled in throws at runtime. **Match every bundle to the native version that can run it.**
+
+## Store Compliance
+
+OTA of interpreted code is explicitly permitted:
+
+- **Apple** — Developer Agreement **§3.3.2** allows OTA of JavaScript and assets executed by the system WebView (since iOS 4.3).
+- **Google Play** — the restriction on non-Play code updates **does not apply** to code running in a VM with limited API access, i.e. JavaScript in a WebView.
+
+What gets apps pulled is shipping *native* executable code OTA. Stay in the web layer and you stay compliant.
+
+## Performance: Keep Bundles Small
+
+Smaller bundles download faster, fail less, and adopt quicker.
+
+- **Delta / differential updates.** Capgo transfers only the files that changed between versions (auto-enabled with direct/instant updates). The win depends on file-level stability — see below.
+- **Deterministic builds.** Strip build timestamps and pin your build tooling so unchanged source produces byte-identical output. Otherwise every file looks "changed" and the delta degrades to a full download.
+- **Compression.** Capgo applies ZSTD compression to full-image updates; you don't configure it, but deterministic builds are what let delta + compression actually shrink the payload.
+- **Prioritize the critical path.** Load auth and main navigation eagerly; lazy-load analytics, settings, animations, and heavy media after first paint. A small critical bundle reaches `notifyAppReady()` faster, which matters because of the rollback timeout.
+
+## Update Timing & Scheduling
+
+- **Off-peak rollouts.** Schedule heavy rollouts for **1–4 AM local time** and prefer Wi-Fi so you're not competing with active use or burning cellular data.
+- **Background application.** The default `atBackground` mode downloads silently and applies when the app backgrounds, so users never watch a spinner. Reserve `onLaunch` / `always` for updates that must take effect immediately (e.g. a hotfix).
+- **Respect `periodCheckDelay`.** Minimum 600s (10 min). Don't try to poll faster — it's clamped.
+
+## Roll Out So You Can Roll Back
+
+The whole point of OTA is that mistakes are cheap to undo. Treat every release as staged:
+
+1. **Canary** to ~10% of users.
+2. **Watch** the success signal (`appReady` vs `downloadFailed`, Capgo stats) for 1–2 hours.
+3. **Widen** to 100% over ~24h if healthy.
+4. **Roll back instantly** from the channel dashboard if not — devices pick up the previous bundle on next check-in.
+
+Healthy benchmarks: **~95% adoption within 24h**, **~82% global success rate**. Below that, investigate before widening.
+
+## The notifyAppReady() Safety Net
+
+This is what makes the above safe. The plugin starts a timer (`appReadyTimeout`, default 10s) when a new bundle loads. If your JS calls `notifyAppReady()` before it fires, the bundle is "confirmed." If it doesn't — because the bundle white-screened or threw on boot — the plugin **automatically reverts** to the last good bundle. A broken OTA release self-heals on the next launch even before you notice.
+
+Call it as early as possible, before heavy async work, so a slow boot doesn't trip the timeout on an otherwise-fine bundle.
+
+## Anti-Patterns
+
+| Anti-pattern                                | Consequence                                                       |
+| ------------------------------------------- | ----------------------------------------------------------------- |
+| OTA-ing a native change                     | Runtime crash on the mismatched shell                            |
+| Non-deterministic builds                    | Delta updates degrade to full downloads                          |
+| 100% rollout, no canary                     | A bad bundle hits the entire user base at once                   |
+| Eager-loading everything                    | Slow boot risks tripping `appReadyTimeout` → false rollback      |
+| Polling faster than 600s                    | Silently clamped; wasted assumption                             |
+
+## See Also
+
+- [Capacitor 8 Platform](capacitor-8.md) — keeping native and OTA in lockstep
+- [Capgo Setup & API](capgo-setup.md) — config and the manual update lifecycle
+- [Channels & Staged Rollouts](channels-and-rollouts.md) — the mechanics of canarying and rollback

package/docs/best-practices/capacitor/security-encryption.md

@@ -0,0 +1,68 @@
+# Security & Encryption
+
+> An OTA bundle travels over the network and lands on devices you don't control. End-to-end encryption with code signing makes each update unreadable in transit and verifiable on arrival — only your users can decrypt it, and only your signed bundles are accepted.
+
+## Why Encrypt
+
+A channel controls *who is eligible* for an update; it does **not** keep the bundle secret. An unencrypted bundle should be treated as a public asset. If your web layer contains anything you don't want readable — proprietary logic, embedded config — encryption is the only thing that keeps it private end to end, including from Capgo itself.
+
+## How v2 Encryption Works (Hybrid RSA + AES)
+
+RSA can't efficiently encrypt large payloads, so Capgo uses a hybrid scheme:
+
+1. A **random AES-256 key** is generated for every upload and encrypts the bundle.
+2. Your **private RSA-2048 key** encrypts (signs) the AES key and the bundle checksum.
+3. The app holds your **public RSA key** (injected at build) and decrypts the AES key + signature.
+4. The app decrypts the bundle with the AES key, recomputes the checksum, and compares it against the decrypted signature.
+
+The result: the bundle is confidential (AES) **and** authenticated (RSA signature over the checksum). Tampering breaks the checksum match; a bundle not signed by your private key won't validate.
+
+> Industry baseline this matches: **AES-256** for payloads, **RSA-2048** for key exchange, **SHA-256** for integrity.
+
+## Setup
+
+```bash
+npx @capgo/cli@latest key create                            # generate the RSA key pair
+npx @capgo/cli@latest bundle upload --key-v2 --channel=production
+```
+
+`key create` writes two files and injects the public key into your Capacitor config:
+
+| File                  | Sensitivity | Rule                                                       |
+| --------------------- | ----------- | ---------------------------------------------------------- |
+| `.capgo_key_v2`       | **Private** | **Never commit.** Store as a CI secret. Loss = can't sign. |
+| `.capgo_key_v2.pub`   | Public      | Safe to commit — it's a backup of the embedded public key. |
+
+Add `.capgo_key_v2` to `.gitignore` immediately. The private key only ever lives on trusted dev machines and in CI secret storage; it's used at upload time to sign, never shipped to devices.
+
+## Strict Enforcement
+
+Once encryption is configured, the plugin **requires** a valid signature on every update — this is enforced, not advisory. An unsigned or tampered bundle is **rejected**, not applied. Practical consequences:
+
+- Every CI upload must run with `--key-v2` and access to the private key, or devices will reject the bundle.
+- Rotating keys requires shipping a new native binary with the new public key; plan it as a store release, not an OTA.
+- `--no-key` (unencrypted) and encrypted uploads don't mix on the same channel for the same audience — pick one posture per channel.
+
+## Integrity Beyond Encryption
+
+- **Checksums** verify the decrypted bundle matches what you signed — corruption or tampering fails closed.
+- **`notifyAppReady()`** is the runtime backstop: even a validly-signed bundle that crashes on boot rolls back automatically (see [Capgo Setup](capgo-setup.md)). Signing proves *authenticity*; `notifyAppReady` proves *it actually runs*. You want both.
+
+## Store Compliance
+
+Encryption doesn't change what you're allowed to ship — it just protects the payload. The compliance rule is unchanged: OTA of **JavaScript/HTML/CSS** is permitted (Apple Developer Agreement §3.3.2; Google Play's webview/JS-VM exemption). Encrypting that web bundle is fine. Encrypting and shipping *native* executable code OTA is still not allowed — encryption is not a loophole around the native/web boundary.
+
+## Checklist
+
+- [ ] `npx @capgo/cli key create` run; `.capgo_key_v2` added to `.gitignore`.
+- [ ] Private key stored as a CI secret; `--key-v2` used on every production upload.
+- [ ] `.capgo_key_v2.pub` committed as a backup.
+- [ ] `notifyAppReady()` present so signed-but-broken bundles still self-heal.
+- [ ] Key rotation planned as a native binary release, not an OTA.
+- [ ] Only web-layer code shipped OTA — never native code, encrypted or not.
+
+## See Also
+
+- [Capgo Setup & API](capgo-setup.md) — the upload flow and `publicKey` config
+- [Channels & Staged Rollouts](channels-and-rollouts.md) — per-channel encryption posture
+- [Live Updates & OTA Strategy](live-updates-ota.md) — what's legal to ship over the air

package/docs/stacks/capacitor-ota.md

@@ -0,0 +1,145 @@
+# Capacitor OTA (Capgo) Patterns
+
+> Capacitor 8 native runtime and Capgo over-the-air live updates: channels, encryption, staged rollouts, and store-safe delivery.
+
+**Type:** Stack Skill (requires `capacitor` stack)
+**Source:** [`stacks/capacitor/skills/ct-capacitor-ota/SKILL.md`](../../stacks/capacitor/skills/ct-capacitor-ota/SKILL.md)
+**Directory Mappings:** `capacitor.config.ts`, `capacitor.config.json`, `ios/`, `android/`
+**File Extensions:** _(none — keyed on config + content)_
+
+## Overview
+
+Capacitor wraps a web app in a native iOS/Android shell. Capgo's `@capgo/capacitor-updater` lets you replace the web bundle that shell loads, shipping JS/HTML/CSS fixes in minutes instead of waiting on store review.
+
+**Golden rule:** OTA updates the **web layer only**. Native code changes (new plugin, native dependency, Capacitor major bump) require a new store binary. Never OTA a bundle whose native contract differs from the installed shell.
+
+## Versions (as of June 2026)
+
+| Package                    | Version | Notes                                                            |
+| -------------------------- | ------- | ---------------------------------------------------------------- |
+| `@capacitor/core` & CLI    | ^8.3.x  | 8.3.1 (2026-04-16); Node 22+, SPM default for new iOS apps       |
+| `@capgo/capacitor-updater` | ^8.x    | Major version tracks Capacitor major; v8 stores channels locally |
+| `@capgo/cli`               | latest  | `npx @capgo/cli@latest …` — pin in CI                            |
+
+## Setup
+
+```bash
+npm i @capgo/capacitor-updater && npx cap sync
+npx @capgo/cli@latest init <API_KEY>   # adds app, injects notifyAppReady, builds, uploads, tests
+```
+
+## Critical: notifyAppReady()
+
+Call it as early as possible after the bundle boots. If the plugin doesn't hear it within `appReadyTimeout` (default 10s), it assumes the bundle is broken and **auto-rolls back** to the previous one — the safety net that makes OTA reversible.
+
+```typescript
+import { CapacitorUpdater } from "@capgo/capacitor-updater";
+
+CapacitorUpdater.notifyAppReady(); // top of bootstrap, before heavy async work
+```
+
+## Configuration
+
+```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", // apply when app backgrounds
+      appReadyTimeout: 10000,
+      autoDeleteFailed: true,
+      autoDeletePrevious: true,
+      resetWhenUpdate: true, // wipe OTA bundles on native app update
+      // defaultChannel: "Development", // TEST/QA BUILDS ONLY — omit in production
+    },
+  },
+};
+
+export default config;
+```
+
+### autoUpdate modes
+
+| Value                        | Behavior                                                      |
+| ---------------------------- | ------------------------------------------------------------ |
+| `false` / `"off"`            | No automatic updates — drive everything from JS              |
+| `"atBackground"` *(default)* | Download silently, apply when app moves to background        |
+| `"atInstall"`                | Apply right after a fresh install / native update            |
+| `"onLaunch"`                 | Apply on next launch, then background                        |
+| `"always"`                   | Apply immediately whenever a check runs                      |
+| `"onlyDownload"`             | Download only; emit `updateAvailable` for you to act         |
+
+`periodCheckDelay` sets poll frequency (seconds, **minimum 600** / 10 min).
+
+## Channels
+
+A channel points to one JS bundle. Swap which bundle a channel points to for instant rollout/rollback without rebuilding.
+
+```bash
+npx @capgo/cli@latest bundle upload --channel=production    # build → upload → assign
+npx @capgo/cli@latest channel set production -s default     # make it the cloud default
+npx @capgo/cli@latest channel set beta --self-assign        # allow in-app setChannel()
+```
+
+**Precedence** (highest first): forced device mapping → cloud per-device override → config `defaultChannel` → cloud Default Channel.
+
+Ship production binaries **without** `defaultChannel` so users follow the cloud default. Recommended ladder:
+
+| 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) |
+
+```typescript
+// Runtime switch — needs "Allow device self-assignment" on the channel (v8+).
+await CapacitorUpdater.setChannel({ channel: "beta", triggerAutoUpdate: true });
+```
+
+## End-to-end encryption (v2)
+
+Hybrid RSA-2048 + AES-256: a random AES key encrypts each bundle; your private RSA key signs the key + checksum; the app decrypts with the embedded public key.
+
+```bash
+npx @capgo/cli@latest key create
+npx @capgo/cli@latest bundle upload --key-v2 --channel=production
+```
+
+- `.capgo_key_v2` (private) — **never commit**; store as a CI secret.
+- `.capgo_key_v2.pub` (public) — safe to commit.
+- With encryption configured, the plugin **strictly enforces** a valid signature; tampered/unsigned bundles are rejected.
+
+## Staged rollouts & monitoring
+
+- Start at ~10% of users, widen over 24h; schedule heavy rollouts 1–4 AM local, Wi-Fi-preferred.
+- Targets: ~95% adoption within 24h, ~82% global success rate.
+- Roll back instantly from the channel dashboard (crown icon on the previous build).
+- Watch the `downloadFailed` / `appReady` ratio in Capgo stats; a spike means roll back.
+
+## Store compliance
+
+OTA of JS/HTML/CSS is permitted — Apple §3.3.2 (since iOS 4.3) and Google Play (webview/JS VM code is exempt). Shipping native code OTA is not.
+
+## Anti-Patterns
+
+| Anti-pattern                              | Why it's wrong                                                            |
+| ----------------------------------------- | ------------------------------------------------------------------------ |
+| **Not calling `notifyAppReady()`**        | Every bundle auto-rolls back after `appReadyTimeout`. The #1 OTA failure. |
+| **OTA-ing a native change**               | Bundle needs a native API the shell lacks → crash. Bump the binary first. |
+| **`defaultChannel` in production builds** | Pins users off the cloud default; breaks instant rollback.               |
+| **Committing `.capgo_key_v2`**            | Leaks your signing key. Commit only the `.pub`.                          |
+| **`periodCheckDelay` < 600**              | Silently clamped; never polls faster than 10 min.                        |
+| **100% rollout with no canary**           | A bad bundle hits everyone at once. Stage it.                            |
+| **Unpinned `@capgo/cli@latest` in CI**    | A CLI minor can change upload behavior mid-pipeline. Pin it.             |
+
+## See Also
+
+- [Capacitor & OTA Best Practices](../best-practices/capacitor/README.md) — full reference set
+- [ct-vite-vitest-patterns](vite-vitest-patterns.md) — the build that produces `webDir`
+- [ct-playwright-patterns](playwright-patterns.md) — E2E-verify a bundle before upload

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claude-toolkit",
-	"version": "0.1.20",
+	"version": "0.1.24",
 	"description": "Reusable Claude Code configuration toolkit with stack-specific connectors",
 	"type": "module",
 	"bin": {

package/src/detect.ts

@@ -0,0 +1,152 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { StackName } from "./types.js";
+
+/** Result of detecting a stack in a project */
+export interface DetectedStack {
+	name: StackName;
+	reason: string;
+}
+
+interface PackageJson {
+	dependencies?: Record<string, string>;
+	devDependencies?: Record<string, string>;
+}
+
+interface StackDetector {
+	name: StackName;
+	detect: (projectDir: string, pkg: PackageJson | null) => DetectedStack | null;
+}
+
+function loadPackageJson(projectDir: string): PackageJson | null {
+	const pkgPath = join(projectDir, "package.json");
+	if (!existsSync(pkgPath)) return null;
+	try {
+		return JSON.parse(readFileSync(pkgPath, "utf-8")) as PackageJson;
+	} catch {
+		return null;
+	}
+}
+
+function hasDep(pkg: PackageJson | null, name: string): boolean {
+	if (!pkg) return false;
+	return name in (pkg.dependencies ?? {}) || name in (pkg.devDependencies ?? {});
+}
+
+function fileExists(projectDir: string, ...segments: string[]): boolean {
+	return existsSync(join(projectDir, ...segments));
+}
+
+function rootConfigExists(projectDir: string, prefix: string): string | null {
+	const glob = new Bun.Glob(`${prefix}.*`);
+	for (const match of glob.scanSync({ cwd: projectDir, onlyFiles: true })) {
+		return match;
+	}
+	return null;
+}
+
+const DETECTORS: StackDetector[] = [
+	{
+		name: "solidjs",
+		detect: (_dir, pkg) =>
+			hasDep(pkg, "solid-js")
+				? { name: "solidjs", reason: "found solid-js in dependencies" }
+				: null,
+	},
+	{
+		name: "vite",
+		detect: (dir, pkg) => {
+			if (hasDep(pkg, "vite")) return { name: "vite", reason: "found vite in dependencies" };
+			const viteConfig = rootConfigExists(dir, "vite.config");
+			if (viteConfig) return { name: "vite", reason: `found ${viteConfig}` };
+			const vitestConfig = rootConfigExists(dir, "vitest.config");
+			if (vitestConfig) return { name: "vite", reason: `found ${vitestConfig}` };
+			return null;
+		},
+	},
+	{
+		name: "vanilla-extract",
+		detect: (_dir, pkg) =>
+			hasDep(pkg, "@vanilla-extract/css")
+				? { name: "vanilla-extract", reason: "found @vanilla-extract/css in dependencies" }
+				: null,
+	},
+	{
+		name: "rust-wasm",
+		detect: (dir) =>
+			fileExists(dir, "Cargo.toml") ? { name: "rust-wasm", reason: "found Cargo.toml" } : null,
+	},
+	{
+		name: "protobuf",
+		detect: (dir) => {
+			if (fileExists(dir, "buf.yaml")) return { name: "protobuf", reason: "found buf.yaml" };
+			if (fileExists(dir, "buf.gen.yaml"))
+				return { name: "protobuf", reason: "found buf.gen.yaml" };
+			const glob = new Bun.Glob("**/*.proto");
+			for (const _match of glob.scanSync({ cwd: dir, onlyFiles: true })) {
+				return { name: "protobuf", reason: "found .proto files" };
+			}
+			return null;
+		},
+	},
+	{
+		name: "cloudflare",
+		detect: (dir) => {
+			if (fileExists(dir, "wrangler.toml"))
+				return { name: "cloudflare", reason: "found wrangler.toml" };
+			if (fileExists(dir, "wrangler.jsonc"))
+				return { name: "cloudflare", reason: "found wrangler.jsonc" };
+			return null;
+		},
+	},
+	{
+		name: "i18n-typesafe",
+		detect: (_dir, pkg) =>
+			hasDep(pkg, "typesafe-i18n")
+				? { name: "i18n-typesafe", reason: "found typesafe-i18n in dependencies" }
+				: null,
+	},
+	{
+		name: "playwright",
+		detect: (dir, pkg) => {
+			if (hasDep(pkg, "@playwright/test"))
+				return { name: "playwright", reason: "found @playwright/test in dependencies" };
+			const config = rootConfigExists(dir, "playwright.config");
+			if (config) return { name: "playwright", reason: `found ${config}` };
+			return null;
+		},
+	},
+	{
+		name: "storybook",
+		detect: (dir, pkg) => {
+			if (hasDep(pkg, "storybook"))
+				return { name: "storybook", reason: "found storybook in dependencies" };
+			if (fileExists(dir, ".storybook"))
+				return { name: "storybook", reason: "found .storybook/ directory" };
+			return null;
+		},
+	},
+	{
+		name: "capacitor",
+		detect: (dir, pkg) => {
+			if (hasDep(pkg, "@capgo/capacitor-updater"))
+				return { name: "capacitor", reason: "found @capgo/capacitor-updater in dependencies" };
+			if (hasDep(pkg, "@capacitor/core"))
+				return { name: "capacitor", reason: "found @capacitor/core in dependencies" };
+			const config = rootConfigExists(dir, "capacitor.config");
+			if (config) return { name: "capacitor", reason: `found ${config}` };
+			return null;
+		},
+	},
+];
+
+/** Scan a project directory and detect which stacks are present */
+export function detectStacks(projectDir: string): DetectedStack[] {
+	const pkg = loadPackageJson(projectDir);
+	const detected: DetectedStack[] = [];
+	for (const detector of DETECTORS) {
+		const result = detector.detect(projectDir, pkg);
+		if (result) detected.push(result);
+	}
+	return detected;
+}

package/src/index.ts

@@ -1,3 +1,5 @@
+export type { DetectedStack } from "./detect.js";
+export { detectStacks } from "./detect.js";
 export type {
 	ClaudeToolkitConfig,
 	GitConfig,

package/src/types.ts

@@ -6,6 +6,10 @@ export type StackName =
 	| "protobuf"
 	| "cloudflare"
 	| "i18n-typesafe"
+	| "vite"
+	| "playwright"
+	| "storybook"
+	| "capacitor"
 	| (string & {});
 
 /** Hook configuration for post-tool-use automation */
@@ -24,7 +28,7 @@ export interface HookConfig {
 
 /** Git workflow configuration */
 export interface GitConfig {
-	/** Branch name prefix (e.g., "wq" → "wq/feature-name") */
+	/** Branch name prefix (e.g., "feat" → "feat/feature-name") */
 	branchPrefix?: string;
 	/** Branches protected from direct edits */
 	protectedBranches?: string[];

package/stacks/capacitor/skills/ct-capacitor-ota/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: ct-capacitor-ota
+description: Capacitor 8 native runtime and Capgo OTA live updates — channels, encryption, staged rollouts, and store-safe over-the-air delivery
+---
+
+# Capacitor OTA (Capgo) Patterns
+
+Ship JavaScript, HTML, and CSS changes to installed apps in minutes instead of waiting days for app store review. Capgo's `@capgo/capacitor-updater` swaps the web bundle the native shell loads; native code still ships through the stores.
+
+**Golden rule:** OTA updates only the **web layer**. Anything that changes native code (new plugin, native dependency, Capacitor major bump) requires a new store binary. Never OTA a bundle whose native contract differs from the installed shell.
+
+## Versions (as of June 2026)
+
+| Package                    | Version  | Notes                                                       |
+| -------------------------- | -------- | ----------------------------------------------------------- |
+| `@capacitor/core` & CLI    | ^8.3.x   | 8.3.1 (2026-04-16); Node 22+, SPM default for new iOS apps  |
+| `@capgo/capacitor-updater` | ^8.x     | Major version tracks Capacitor major; v8 stores channels locally |
+| `@capgo/cli`               | latest   | `npx @capgo/cli@latest …` — pin in CI                       |
+
+Capacitor 8 platform floor: Node 22, iOS deployment target 15.0 (Xcode 26+), Android `minSdk 24` / `compileSdk 36` / `targetSdk 36`, Gradle plugin 8.13.0, wrapper 8.14.3, Kotlin 2.2.20.
+
+## Setup
+
+```bash
+npm i @capgo/capacitor-updater && npx cap sync
+npx @capgo/cli@latest init <API_KEY>   # adds app, injects notifyAppReady, builds, uploads, tests
+```
+
+## Critical: notifyAppReady()
+
+Call it **as early as possible** after the web bundle boots. If the plugin doesn't hear it within `appReadyTimeout` (default 10s), it assumes the bundle is broken and **auto-rolls back** to the previous one.
+
+```typescript
+import { CapacitorUpdater } from "@capgo/capacitor-updater";
+
+// Run once, at the top of app bootstrap — before heavy async work.
+CapacitorUpdater.notifyAppReady();
+```
+
+This is the safety net that makes OTA reversible. A bundle that white-screens never sticks.
+
+## Configuration
+
+```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", // default — apply when app backgrounds
+      appReadyTimeout: 10000,
+      responseTimeout: 20,
+      autoDeleteFailed: true,
+      autoDeletePrevious: true,
+      resetWhenUpdate: true, // wipe OTA bundles on native app update
+      // defaultChannel: "Development", // TEST/QA BUILDS ONLY — omit in production
+    },
+  },
+};
+
+export default config;
+```
+
+### autoUpdate modes
+
+| Value                       | Behavior                                                              |
+| --------------------------- | -------------------------------------------------------------------- |
+| `false` / `"off"`           | No automatic updates — drive everything from JS                      |
+| `"atBackground"` *(default)* | Download silently, apply when app moves to background                |
+| `"atInstall"`               | Apply immediately after a fresh install / native update, then background |
+| `"onLaunch"`                | Apply immediately on next launch, then background                    |
+| `"always"`                  | Apply immediately whenever an update check runs                      |
+| `"onlyDownload"`            | Download but never auto-apply; emit `updateAvailable` for you to act |
+
+`periodCheckDelay` controls how often the plugin polls (seconds, **minimum 600** / 10 min).
+
+## Channels
+
+A channel points to one JS bundle. Devices check their assigned channel; you swap which bundle a channel points to for instant rollout/rollback — no rebuild.
+
+```bash
+npx @capgo/cli@latest bundle upload --channel=production    # build → upload → assign
+npx @capgo/cli@latest channel set production -s default     # make it the cloud default
+npx @capgo/cli@latest channel set beta --self-assign        # allow in-app setChannel()
+```
+
+**Channel precedence** (highest first): forced device mapping → cloud per-device override → config `defaultChannel` → cloud Default Channel (the ~99% path).
+
+**Production rule:** ship production binaries **without** `defaultChannel` so users follow the cloud default. Only set `defaultChannel` in builds explicitly handed to testers.
+
+Recommended ladder with semver pre-release tags:
+
+| 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) |
+
+### Runtime channel switching
+
+```typescript
+// Requires "Allow device self-assignment" enabled on the channel (plugin v8+).
+await CapacitorUpdater.setChannel({ channel: "beta", triggerAutoUpdate: true });
+```
+
+In v8 `setChannel` stores the choice **locally** and takes effect on the next check (no replication lag). The backend still validates self-assignment permission.
+
+## Manual / background update flow
+
+For full control, set `autoUpdate: false` and drive the lifecycle yourself:
+
+```typescript
+import { App } from "@capacitor/app";
+import { SplashScreen } from "@capacitor/splash-screen";
+
+CapacitorUpdater.addListener("download", ({ percent }) => console.log(`↓ ${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 }); // apply on next background
+    }
+  }
+});
+```
+
+Key methods: `getLatest()`, `download()`, `next()` (queue), `set()` (apply now — destroys JS context), `current()`, `reload()`, `reset()`. Events: `download`, `downloadComplete`, `updateAvailable`, `downloadFailed`, `appReady`, `majorAvailable`.
+
+## End-to-end encryption (v2)
+
+Hybrid RSA-2048 + AES-256: a random AES key encrypts each bundle; your **private** RSA key signs the AES key + checksum; the app decrypts with the embedded **public** key. Only your users can read the bundle — not even Capgo.
+
+```bash
+npx @capgo/cli@latest key create          # generates the key pair
+npx @capgo/cli@latest bundle upload --key-v2 --channel=production
+```
+
+- `.capgo_key_v2` (private) — **never commit**; store as a CI secret.
+- `.capgo_key_v2.pub` (public) — safe to commit; injected into the app.
+- Once encryption is configured, the plugin **strictly enforces** a valid signature — an unsigned/tampered bundle is rejected.
+
+## Delta updates
+
+Direct/instant updates auto-enable delta updates — only changed files transfer, not the whole bundle. Keep deltas small: pin build tooling and strip build timestamps so unchanged files hash identically. Use `--delta-only` to require delta-capable clients.
+
+## Staged rollouts & monitoring
+
+- Start at ~10% of users, widen over 24h; schedule heavy rollouts for 1–4 AM local time, Wi-Fi-preferred.
+- Healthy targets: ~95% adoption within 24h, ~82% global success rate.
+- Roll back instantly from the channel dashboard (crown icon on the previous build) — devices pick it up on next check-in.
+- Watch the `downloadFailed` / `appReady` ratio and Capgo stats; a spike means rollback.
+
+## Store compliance
+
+OTA of JS/HTML/CSS is allowed: **Apple** developer agreement §3.3.2 (since iOS 4.3) and **Google Play** (code in a webview/JS VM is exempt from the non-Play update restriction). Shipping *native* code OTA is not — that's what gets apps pulled.
+
+## Anti-Patterns
+
+1. **Not calling `notifyAppReady()`** — every bundle auto-rolls back after `appReadyTimeout`. This is the #1 "OTA doesn't work" cause.
+2. **OTA-ing a native change** — bundle that needs a plugin/native API the installed shell lacks crashes. Match the bundle to the shipped native version; bump the store binary first.
+3. **`defaultChannel` in production builds** — pins users off the cloud default and breaks instant rollback. Test builds only.
+4. **Committing `.capgo_key_v2`** — leaks your signing key. Commit only the `.pub`.
+5. **`periodCheckDelay` < 600** — silently clamped; the plugin won't poll faster than 10 minutes.
+6. **100% rollout with no canary** — a bad bundle hits everyone at once. Stage it.
+7. **Unpinned `@capgo/cli@latest` in CI** — a CLI minor can change upload behavior mid-pipeline. Pin the version.
+
+## See Also
+
+- `ct-vite-vitest-patterns` — the build that produces `webDir`
+- `ct-playwright-patterns` — E2E-verify a bundle before you upload it
+- `ct-typescript-conventions` — typing `capacitor.config.ts` and the updater API