claude-toolkit 0.15.0 → 0.17.0-rc.1

package/src/refresh-hint.ts

@@ -0,0 +1,95 @@
+/**
+ * The "keep .claude/ in sync" hint printed after a bare CLI run. The toolkit never
+ * edits the consumer's package.json (a committed file); it only says what to add.
+ * Wording rule: no URLs and no filename literals with a TLD-like extension, since
+ * Socket's URL-strings detector reads both as links.
+ */
+
+/** Script body a consumer adds. `|| exit 0` keeps an install working when bun is missing. */
+export const REFRESH_COMMAND = "claude-toolkit refresh || exit 0";
+/** Script name suggested when the lifecycle script already exists. */
+export const REFRESH_SCRIPT_NAME = "claude-toolkit:refresh";
+/** First release that no longer regenerates .claude/ from a dependency install script. */
+export const INSTALL_SCRIPT_REMOVED_IN = "0.17.0";
+
+export type PackageManager = "bun" | "npm" | "pnpm" | "yarn";
+
+export interface RefreshHintInput {
+	/** `scripts` from the project's package.json ({} when it has none). */
+	scripts: Record<string, unknown>;
+	/** `packageManager` from the toolkit config. */
+	packageManager: PackageManager;
+	/** True when the project uses Yarn 2+ (a `.yarnrc.yml` exists). */
+	yarnBerry: boolean;
+	/** `.claude/.toolkit-version` as it was before this run, or null. */
+	previousVersion: string | null;
+}
+
+/**
+ * When each package manager runs the project's own root lifecycle scripts, verified
+ * 2026-09-28 with a root project whose `prepare` and `postinstall` append to a file:
+ *   bun 1.3.11                       prepare on install, add and update
+ *   npm 10.9.3, 11.20.0, 12.1.0      prepare on a plain install only (not install <pkg>, not update)
+ *   pnpm 10.34.5, 11.28.0, 12.6.0    prepare on install and update, not on add
+ *   Yarn 4.18.1                      never prepare; postinstall whenever the dependency tree changes
+ */
+const CAVEATS: Record<PackageManager | "yarn-berry", string | null> = {
+	bun: null,
+	npm: 'npm runs "prepare" only on a plain "npm install"; after "npm install <pkg>" or "npm update", run "bunx claude-toolkit refresh".',
+	pnpm: 'pnpm skips "prepare" on "pnpm add"; after upgrading claude-toolkit that way, run "bunx claude-toolkit refresh".',
+	yarn: null,
+	"yarn-berry":
+		'Yarn 2+ never runs "prepare" for your own project; "postinstall" runs whenever your dependencies change.',
+};
+
+/** Compare x.y.z numerically. A prerelease counts as its release: 0.17.0-rc.0 is not before 0.17.0. */
+export function isBefore(version: string, floor: string): boolean {
+	const parts = (v: string) =>
+		(v.split("-")[0] ?? "").split(".").map((n) => Number.parseInt(n, 10) || 0);
+	const a = parts(version);
+	const b = parts(floor);
+	for (let i = 0; i < 3; i++) {
+		const x = a[i] ?? 0;
+		const y = b[i] ?? 0;
+		if (x !== y) return x < y;
+	}
+	return false;
+}
+
+/** True when some package.json script already runs `claude-toolkit refresh`. */
+export function hasRefreshScript(scripts: Record<string, unknown>): boolean {
+	return Object.values(scripts).some(
+		(s) => typeof s === "string" && s.includes("claude-toolkit refresh"),
+	);
+}
+
+/** Lines of the hint, or [] when a script already runs `claude-toolkit refresh`. */
+export function buildRefreshHint(input: RefreshHintInput): string[] {
+	const { scripts, packageManager, yarnBerry, previousVersion } = input;
+	const lifecycle = yarnBerry ? "postinstall" : "prepare";
+	// Yarn 2+ never runs "prepare", so only a refresh reachable from "postinstall" counts there.
+	const satisfied = yarnBerry
+		? /claude-toolkit[ :]refresh/.test(String(scripts.postinstall ?? ""))
+		: hasRefreshScript(scripts);
+	if (satisfied) return [];
+
+	const runner = yarnBerry ? "yarn" : packageManager;
+	const lines: string[] = [];
+	if (previousVersion !== null && isBefore(previousVersion, INSTALL_SCRIPT_REMOVED_IN)) {
+		lines.push(
+			`Automatic regeneration on install was removed in ${INSTALL_SCRIPT_REMOVED_IN} (it relied on a dependency install script).`,
+		);
+	}
+	lines.push('Keep .claude/ in sync after toolkit upgrades — add to your package.json "scripts":');
+	if (scripts[lifecycle] === undefined) {
+		lines.push(`  "${lifecycle}": "${REFRESH_COMMAND}"`);
+	} else {
+		lines.push(`  "${REFRESH_SCRIPT_NAME}": "${REFRESH_COMMAND}"`);
+		lines.push(
+			`and append "&& ${runner} run ${REFRESH_SCRIPT_NAME}" to your existing "${lifecycle}" script.`,
+		);
+	}
+	const caveat = CAVEATS[yarnBerry ? "yarn-berry" : packageManager];
+	if (caveat !== null) lines.push(caveat);
+	return lines;
+}

package/templates/skill-rules.base.json

@@ -43,14 +43,37 @@
 			}
 		},
 		"ct-typescript-conventions": {
-			"description": "TypeScript strict mode and conventions",
+			"description": "TypeScript strict mode, conventions, and TS7 compiler selection",
 			"priority": 5,
 			"triggers": {
-				"keywords": ["typescript", "type", "interface", "generic", "strict mode"],
-				"keywordPatterns": ["\\btype\\b", "\\binterface\\b", "\\bgeneric\\b"],
-				"pathPatterns": ["**/*.d.ts", "**/types/**", "**/types.ts"],
-				"intentPatterns": ["(?:define|create).*(?:type|interface)", "(?:type).*(?:error|issue)"],
-				"contentPatterns": ["interface ", "type ", ": unknown", "as const"]
+				"keywords": [
+					"typescript",
+					"type",
+					"interface",
+					"generic",
+					"strict mode",
+					"tsc",
+					"tsgo",
+					"tsconfig",
+					"typecheck",
+					"compiler"
+				],
+				"keywordPatterns": [
+					"\\btype\\b",
+					"\\binterface\\b",
+					"\\bgeneric\\b",
+					"\\btsc\\b",
+					"\\btsconfig\\b",
+					"\\bts\\s?7\\b"
+				],
+				"pathPatterns": ["**/*.d.ts", "**/types/**", "**/types.ts", "**/tsconfig*.json"],
+				"intentPatterns": [
+					"(?:define|create).*(?:type|interface)",
+					"(?:type).*(?:error|issue)",
+					"(?:run|fix).*type.?check",
+					"(?:upgrade|migrate|update).*typescript"
+				],
+				"contentPatterns": ["interface ", "type ", ": unknown", "as const", "compilerOptions"]
 			},
 			"excludePatterns": ["issue type", "type of bug"]
 		},

package/bin/postinstall.mjs

@@ -1,69 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * claude-toolkit postinstall
- *
- * Runs in the consumer project after install. If a claude-toolkit.config.ts
- * exists, it regenerates .claude/ — but only when the installed toolkit version
- * differs from the one that last generated it, so it fires on a toolkit update,
- * not on every install.
- *
- * Guarantees:
- *  - Never fails the consumer's install (all errors swallowed; always exit 0).
- *  - Never runs inside the toolkit's own repo (dev install).
- *  - Never creates or edits the committed config — only regenerates .claude/.
- *  - Writes no committed files when there's no config (prints a one-line nudge).
- */
-
-import { spawnSync } from "node:child_process";
-import { existsSync, readFileSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-
-function readJsonSafe(path) {
-	try {
-		return JSON.parse(readFileSync(path, "utf8"));
-	} catch {
-		return null;
-	}
-}
-
-try {
-	const toolkitDir = resolve(dirname(fileURLToPath(import.meta.url)), "..");
-	// INIT_CWD is set by npm/bun/pnpm/yarn to the dir where install was invoked.
-	const consumerRoot = resolve(process.env.INIT_CWD || process.cwd());
-
-	// 1. Skip when running inside the toolkit's own repo (dev install).
-	if (consumerRoot === toolkitDir) process.exit(0);
-	const consumerPkg = readJsonSafe(join(consumerRoot, "package.json"));
-	if (consumerPkg?.name === "claude-toolkit") process.exit(0);
-
-	// 2. No config -> stay hands-off; just nudge once. Never write committed files.
-	const hasConfig =
-		existsSync(join(consumerRoot, "claude-toolkit.config.ts")) ||
-		existsSync(join(consumerRoot, "claude-toolkit.config.js"));
-	if (!hasConfig) {
-		console.log(
-			'[claude-toolkit] Run "bunx claude-toolkit" to set up your Claude Code config (.claude/).',
-		);
-		process.exit(0);
-	}
-
-	// 3. Only regenerate when the toolkit version changed since the last generation.
-	const toolkitVersion = readJsonSafe(join(toolkitDir, "package.json"))?.version;
-	const markerPath = join(consumerRoot, ".claude", ".toolkit-version");
-	const lastVersion = existsSync(markerPath) ? readFileSync(markerPath, "utf8").trim() : null;
-	if (toolkitVersion && lastVersion === toolkitVersion) process.exit(0);
-
-	// 4. Regenerate via the CLI (reuses config loading + clean rebuild). Best-effort:
-	//    spawnSync sets `.error` if bun is missing — we ignore it rather than fail.
-	spawnSync("bun", [join(toolkitDir, "bin", "cli.ts"), "postinstall"], {
-		cwd: consumerRoot,
-		stdio: "inherit",
-		env: { ...process.env, INIT_CWD: consumerRoot },
-	});
-} catch {
-	// Never break the consumer's install over config regeneration.
-}
-
-process.exit(0);

package/docs/README.md

@@ -1,59 +0,0 @@
-# claude-toolkit Documentation
-
-Complete reference for all skills, commands, and agents provided by claude-toolkit.
-
-## Setup
-
-Run `bunx claude-toolkit` in your project — on the first run it creates `claude-toolkit.config.ts` (pre-filled from stack detection) and generates `.claude/`. Run it again anytime to regenerate; add `--update` to pull newly-detected stacks into the config. `.claude/` also regenerates automatically on install when the toolkit version changes. See the [README](../README.md#cli-commands) for the full CLI.
-
-## Core Skills
-
-Skills that are always included regardless of stack configuration.
-
-| Skill                                                                      | Description                                                                 |
-| -------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| [ct-systematic-debugging](skills/systematic-debugging.md)                     | Four-phase methodology for diagnosing and fixing bugs without guesswork     |
-| [ct-testing-patterns](skills/testing-patterns.md)                             | Framework-agnostic TDD practices, mocking strategies, and test organization |
-| [ct-typescript-conventions](skills/typescript-conventions.md)                 | Strict TypeScript patterns for type safety and maintainability              |
-| [ct-verification-before-completion](skills/verification-before-completion.md) | Evidence-based completion claims with structured verification checklist     |
-| [ct-code-style](skills/code-style.md)                                         | Code structure & style: guard clauses, lookup tables, no magic values       |
-
-## Commands
-
-Slash commands available in Claude Code sessions.
-
-| Command                                   | Description                                                                |
-| ----------------------------------------- | -------------------------------------------------------------------------- |
-| [/ct:code-quality](commands/code-quality.md) | Run lint, typecheck, and format checks with structured reporting           |
-| [/ct:pr-review](commands/pr-review.md)       | Checklist-based code review against project standards                      |
-| [/ct:pr-summary](commands/pr-summary.md)     | Generate a structured PR summary from branch diff and commits              |
-| [/ct:onboard](commands/onboard.md)           | Systematically explore and understand a codebase area                      |
-| [/ct:ticket](commands/ticket.md)             | Work end-to-end on a ticket: understand, explore, plan, implement, deliver |
-| [/ct:proto-check](commands/proto-check.md)   | Validate protobuf definitions, lint, breaking changes, and code generation |
-
-## Agents
-
-Specialized agents with dedicated models and review capabilities.
-
-| Agent                                        | Model  | Description                                                                |
-| -------------------------------------------- | ------ | -------------------------------------------------------------------------- |
-| [ct-code-reviewer](agents/ct-code-reviewer.md)     | Opus   | Senior code reviewer with stack-aware analysis and severity-based feedback |
-| [ct-github-workflow](agents/ct-github-workflow.md) | Sonnet | Git workflow assistant for branching, commits, and PR creation             |
-
-## Stack Skills
-
-Stack-specific skills activated based on your `claude-toolkit.config.ts` configuration.
-
-| Skill                                                          | Stack             | Description                                                                    |
-| -------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------ |
-| [ct-solidjs-patterns](stacks/solidjs-patterns.md)                 | `solidjs`         | Reactivity, signals, effects, component patterns, and props handling           |
-| [ct-vite-vitest-patterns](stacks/vite-vitest-patterns.md)         | `vite`            | Vite build config, plugins, env vars, Vitest testing, coverage, browser mode   |
-| [ct-vanilla-extract-patterns](stacks/vanilla-extract-patterns.md) | `vanilla-extract` | Type-safe CSS with zero runtime: styles, recipes, themes, sprinkles            |
-| [ct-rust-wasm-patterns](stacks/rust-wasm-patterns.md)             | `rust-wasm`       | Rust WASM for Cloudflare Workers: routing, handlers, env bindings              |
-| [ct-protobuf-contracts](stacks/protobuf-contracts.md)             | `protobuf`        | Protocol Buffers for API contracts: schema design, versioning, code generation |
-| [ct-cloudflare-d1-kv](stacks/cloudflare-d1-kv.md)                 | `cloudflare`      | D1 database and KV cache: queries, migrations, caching patterns                |
-| [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    |
-| [ct-esnext-idioms](stacks/esnext-idioms.md)                       | `esnext`          | Modern ECMAScript runtime idioms: Temporal, iterator helpers, using, structuredClone |

package/docs/agents/code-reviewer.md

@@ -1,76 +0,0 @@
-# Code Reviewer Agent
-
-> Senior code reviewer with stack-aware analysis.
-
-**Type:** Agent
-**Model:** Opus (highest capability)
-**Source:** [`core/agents/ct-code-reviewer.md`](../core/agents/ct-code-reviewer.md)
-
-## Overview
-
-A senior code reviewer agent that thoroughly reviews code changes, providing actionable feedback organized by severity. It adapts review criteria to the project's stack and conventions.
-
-## Review Process
-
-1. **Read the full diff** and all changed files in their entirety -- understands surrounding context, not just changed lines
-2. **Identify the stack** by reading project config files -- adapts criteria accordingly
-3. **Apply the review checklist** to every changed file
-4. **Compile findings** with severity levels and specific file/line references
-
-## Review Checklist
-
-### Critical Issues
-
-| Category | Checks |
-| --- | --- |
-| **Logic Correctness** | Off-by-one errors, inverted conditions, unhandled edge cases, race conditions, incorrect state transitions, dead code |
-| **Error Handling** | Swallowed errors, missing context in error messages, leaked resources, unhandled crashes, missing error boundaries |
-| **Security** | SQL/XSS/command injection, missing auth, secrets in code, CORS issues, missing rate limiting |
-
-### Warnings
-
-| Category | Checks |
-| --- | --- |
-| **Type Safety** | `any` usage, unsafe casts, missing null checks, implicit coercions, overly broad generics |
-| **Performance** | Unnecessary re-renders, N+1 queries, missing pagination, sync-when-should-be-async, memory leaks |
-| **Testing** | New behavior without tests, implementation-detail tests, missing edge cases, flaky patterns |
-
-### Suggestions
-
-| Category | Checks |
-| --- | --- |
-| **Naming and Readability** | Misleading names, abbreviations, functions doing too much, deep nesting, comments describing "what" instead of "why" |
-
-## Output Format
-
-```markdown
-## Code Review
-
-**Reviewed:** {files or PR description}
-**Verdict:** APPROVE | REQUEST_CHANGES | COMMENT
-
-### Critical ({count})
-### Warnings ({count})
-### Suggestions ({count})
-### Looks Good
-### Summary
-```
-
-## Best Practices Reference
-
-Stack-aware review informed by these guides:
-
-| Review Area | Guide |
-| --- | --- |
-| `any` usage, type safety patterns | [any & unknown](../best-practices/typescript/any-and-unknown.md) |
-| `type` vs `interface` conventions | [Type vs Interface](../best-practices/typescript/type-vs-interface.md) |
-| SolidJS-specific mistakes (destructuring, effects) | [SolidJS Anti-Patterns](../best-practices/solidjs/anti-patterns.md) |
-| Props reactivity issues | [SolidJS Props Patterns](../best-practices/solidjs/props-patterns.md) |
-
-## Principles
-
-- **Be specific** -- "This catch block on line 42 swallows the database connection error" is useful; "This could be improved" is not
-- **Distinguish severity honestly** -- not everything is critical, not everything is a suggestion
-- **Acknowledge good work** -- reviews that only list problems are incomplete
-- **Stay in scope** -- review the changes, not the entire codebase
-- **Offer alternatives, not just objections** -- suggest a fix or direction for every problem flagged

package/docs/agents/github-workflow.md

@@ -1,98 +0,0 @@
-# GitHub Workflow Agent
-
-> Git workflow assistant for branching, commits, and PRs.
-
-**Type:** Agent
-**Model:** Sonnet
-**Source:** [`core/agents/ct-github-workflow.md`](../core/agents/ct-github-workflow.md)
-
-## Overview
-
-A Git workflow assistant that helps with branch management, commit formatting, and pull request creation following consistent conventions.
-
-## Branch Naming
-
-Format: `{prefix}/{short-description}`
-
-| Prefix | Use Case | Example |
-|---|---|---|
-| `feat` | New feature | `feat/user-avatar-upload` |
-| `fix` | Bug fix | `fix/login-redirect-loop` |
-| `chore` | Maintenance, deps, config | `chore/upgrade-eslint-9` |
-| `refactor` | Code restructuring | `refactor/extract-auth-service` |
-| `docs` | Documentation only | `docs/api-authentication` |
-| `test` | Test additions or fixes | `test/payment-edge-cases` |
-| `hotfix` | Urgent production fix | `hotfix/null-crash-checkout` |
-
-**Rules:** lowercase with hyphens, under 4 words, specific enough to identify at a glance.
-
-## Conventional Commits
-
-Format: `{type}({scope}): {description}`
-
-| Type | When |
-|---|---|
-| `feat` | New feature visible to users |
-| `fix` | Bug fix |
-| `refactor` | Code change with no behavior difference |
-| `test` | Adding or updating tests |
-| `docs` | Documentation changes |
-| `chore` | Build, CI, dependency updates |
-| `perf` | Performance improvement |
-| `style` | Formatting, whitespace (no logic change) |
-
-**Examples:**
-```
-feat(auth): add JWT refresh token rotation
-fix(cart): prevent duplicate items on rapid clicks
-refactor(api): extract validation middleware from route handlers
-chore(deps): upgrade next.js to 15.1
-```
-
-**Rules:**
-- Scope is optional but encouraged (module or feature area)
-- Description starts lowercase, imperative mood ("add" not "added")
-- Body explains "why" not "what"
-- Breaking changes: add `!` after type/scope (e.g., `feat(api)!: change auth response format`)
-
-## PR Creation Workflow
-
-### 1. Pre-flight Checks
-- Tests pass
-- Types check
-- No lint errors
-- No merge conflicts
-
-### 2. PR Title
-Same conventional format as commits, under 70 characters.
-
-### 3. PR Description
-```markdown
-## Summary
-{1-3 bullet points: what and why}
-
-## Changes
-- {Grouped list of meaningful changes}
-
-## Testing
-- [ ] {How to test}
-- [ ] {Edge cases verified}
-
-## Notes
-{Trade-offs, follow-up work, deployment considerations}
-```
-
-### 4. Pre-Open Checklist
-- Branch up to date with base
-- All tests pass
-- Types check cleanly
-- No lint errors
-- PR title follows conventional format
-- Changes are focused (one concern per PR)
-
-## Principles
-
-- **Small PRs** -- if a PR touches more than 10 files or 300 lines, consider splitting
-- **One concern per PR** -- do not mix a feature with a refactor with a dependency upgrade
-- **Commit history matters** -- each commit should be a logical, buildable unit
-- **PR description is for the reviewer** -- write it to save their time

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

@@ -1,64 +0,0 @@
-# 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

@@ -1,60 +0,0 @@
-# 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