claude-toolkit 0.1.22 → 0.1.24

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # 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

package/README.md

@@ -92,6 +92,7 @@ This keeps your config aligned as your project evolves — stacks you add or rem
 | `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/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

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.22",
+	"version": "0.1.24",
 	"description": "Reusable Claude Code configuration toolkit with stack-specific connectors",
 	"type": "module",
 	"bin": {

package/src/detect.ts

@@ -126,6 +126,18 @@ const DETECTORS: StackDetector[] = [
 			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 */

package/src/types.ts

@@ -9,6 +9,7 @@ export type StackName =
 	| "vite"
 	| "playwright"
 	| "storybook"
+	| "capacitor"
 	| (string & {});
 
 /** Hook configuration for post-tool-use automation */

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

package/stacks/capacitor/stack.json

@@ -0,0 +1,64 @@
+{
+	"name": "ct-capacitor-ota",
+	"description": "Capacitor 8 native runtime and Capgo OTA live updates: channels, encryption, staged rollouts",
+	"defaultMappings": {
+		"capacitor.config.ts": "ct-capacitor-ota",
+		"capacitor.config.json": "ct-capacitor-ota",
+		"ios": "ct-capacitor-ota",
+		"android": "ct-capacitor-ota"
+	},
+	"fileExtensions": [],
+	"skillRules": {
+		"ct-capacitor-ota": {
+			"description": "Capacitor 8 live updates with Capgo: notifyAppReady, channels, encryption, CLI, staged rollouts",
+			"priority": 7,
+			"triggers": {
+				"keywords": [
+					"capacitor",
+					"capgo",
+					"ota",
+					"live update",
+					"updater",
+					"notifyAppReady",
+					"channel",
+					"bundle",
+					"hot update",
+					"app store",
+					"setChannel"
+				],
+				"keywordPatterns": [
+					"\\bcapacitor\\b",
+					"\\bcapgo\\b",
+					"\\bota\\b",
+					"\\blive\\s+updates?\\b",
+					"\\bnotifyAppReady\\b"
+				],
+				"pathPatterns": [
+					"**/capacitor.config.ts",
+					"**/capacitor.config.json",
+					"**/capacitor.config.js",
+					"**/android/**",
+					"**/ios/**"
+				],
+				"intentPatterns": [
+					"(?:ship|push|deploy|roll\\s*out).*(?:update|bundle|version)",
+					"(?:setup|configure|add).*(?:capgo|capacitor|live\\s+update|ota)",
+					"(?:rollback|revert).*(?:bundle|channel|update)"
+				],
+				"contentPatterns": [
+					"@capgo/capacitor-updater",
+					"CapacitorUpdater",
+					"notifyAppReady",
+					"setChannel",
+					"@capacitor/core",
+					"autoUpdate"
+				]
+			},
+			"relatedSkills": [
+				"ct-vite-vitest-patterns",
+				"ct-playwright-patterns",
+				"ct-typescript-conventions"
+			]
+		}
+	}
+}