claude-toolkit 0.1.27 → 0.10.0

package/core/hooks/skill-eval.js

@@ -129,14 +129,7 @@ function matchDirectoryMapping(filePath, mappings) {
 /**
  * Evaluate a single skill against the prompt and context
  */
-function evaluateSkill(
-	skillName,
-	skill,
-	prompt,
-	promptLower,
-	filePaths,
-	rules,
-) {
+function evaluateSkill(skillName, skill, prompt, promptLower, filePaths, rules) {
 	const { triggers = {}, excludePatterns = [], priority = 5 } = skill;
 	const scoring = rules.scoring;
 
@@ -207,10 +200,7 @@ function evaluateSkill(
 	// 6. Check directory mappings
 	if (rules.directoryMappings && filePaths.length > 0) {
 		for (const filePath of filePaths) {
-			const mappedSkill = matchDirectoryMapping(
-				filePath,
-				rules.directoryMappings,
-			);
+			const mappedSkill = matchDirectoryMapping(filePath, rules.directoryMappings);
 			if (mappedSkill === skillName) {
 				score += scoring.directoryMatch;
 				reasons.push(`directory mapping`);
@@ -279,14 +269,7 @@ function evaluate(prompt) {
 
 	const matches = [];
 	for (const [name, skill] of Object.entries(skills)) {
-		const match = evaluateSkill(
-			name,
-			skill,
-			prompt,
-			promptLower,
-			filePaths,
-			rules,
-		);
+		const match = evaluateSkill(name, skill, prompt, promptLower, filePaths, rules);
 		if (match && match.score >= config.minConfidenceScore) {
 			matches.push(match);
 		}

package/core/skills/ct-testing-patterns/SKILL.md

@@ -107,6 +107,18 @@ Bun supports `describe`, `it`/`test`, `expect`, lifecycle hooks, and snapshot te
 
 See 3-Layer Testing Strategy above. Many unit tests (fast, focused) > some interaction tests (component sandbox) > few E2E tests (full flow). Aim for 70/20/10 distribution.
 
+## Test Speed
+
+Three levers recur across every runner (Vitest, Playwright, Storybook browser mode). Stated once here; each stack skill carries the framework-specific syntax.
+
+- **Parallelism sized to the runner.** Enable file-level parallelism (Vitest `fileParallelism`, Playwright `fullyParallel`), but cap workers to the runner's *real* vCPUs (`"50%"` or a measured count). GitHub standard runners are 2 vCPU (private) / 4 (public); oversubscribing thrashes.
+- **Shard across CI jobs, then merge the blob reports.** Sharding splits at the *file* level (`--shard=i/n`), so wall-clock is gated by the slowest shard -- balance file sizes. Always emit a blob report per shard (`--reporter=blob`) and merge it (`merge-reports` / `--merge-reports`) in a dependent job, or results and coverage are fragmented and incomplete.
+- **Skip isolation where state is clean.** Per-file environment isolation is the safe default but the biggest run-speed cost. Disable it (Vitest `isolate: false`, `pool: 'threads'`) only for side-effect-free logic suites; keep it where tests mutate globals/env/timers.
+
+Profile before tuning, and never `sleep` to mask timing -- use the framework's auto-waiting (see Shared Principles).
+
+Per-runner config: `ct-vite-vitest-patterns`, `ct-playwright-patterns`, `ct-storybook-patterns`.
+
 ## Anti-Patterns
 
 1. **Testing implementation** -- Asserting internal state or call counts breaks on refactors.

package/docs/README.md

@@ -2,6 +2,10 @@
 
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "claude-toolkit",
-	"version": "0.1.27",
+	"version": "0.10.0",
 	"description": "Reusable Claude Code configuration toolkit with stack-specific connectors",
 	"type": "module",
 	"bin": {
@@ -25,6 +25,7 @@
 		"typecheck": "tsc --noEmit",
 		"lint": "biome check --write",
 		"lint:check": "biome check",
+		"postinstall": "bun bin/postinstall.mjs || node bin/postinstall.mjs || exit 0",
 		"prepare": "npx husky"
 	},
 	"lint-staged": {

package/src/generator.ts

@@ -1,7 +1,7 @@
-import { copyFile as fsCopyFile } from "node:fs/promises";
+import { copyFile as fsCopyFile, readdir } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import type { ClaudeToolkitConfig, ResolvedConfig, StackPack } from "./types.js";
-import { copyDir, exists, readJson, writeFileEnsureDir } from "./utils.js";
+import { copyDir, exists, readJson, removePath, writeFileEnsureDir } from "./utils.js";
 
 const TOOLKIT_ROOT = resolve(import.meta.dirname, "..");
 
@@ -48,11 +48,52 @@ async function resolveConfig(config: ClaudeToolkitConfig): Promise<ResolvedConfi
 	return { config, skills, directoryMappings: allMappings, hooks, stacks };
 }
 
+/** Remove only `ct-` prefixed entries in a directory (preserves user-authored files). */
+async function removeCtPrefixed(dir: string): Promise<void> {
+	if (!exists(dir)) return;
+	const entries = await readdir(dir);
+	await Promise.all(
+		entries.filter((e) => e.startsWith("ct-")).map((e) => removePath(join(dir, e))),
+	);
+}
+
+/**
+ * Remove toolkit-generated artifacts from .claude/ before a rebuild, so a stack
+ * removed from the config doesn't leave an orphaned skill behind.
+ *
+ * Scoped to what the toolkit owns: `ct-` prefixed skills/agents, the generated
+ * skills index, the `ct/` command namespace, and the toolkit's own hook files.
+ * `.claude/skills`, `/agents`, and `/hooks` are shared Claude Code namespaces, so
+ * any user-authored files there — and the user files at the .claude root
+ * (settings.local.json, user-team-info.json, tasks/) — are preserved.
+ * (settings.json and .gitignore are single generated files, overwritten by generate.)
+ */
+async function removeGenerated(claudeDir: string): Promise<void> {
+	const coreHooks = join(TOOLKIT_ROOT, "core", "hooks");
+	const hookFiles = exists(coreHooks) ? await readdir(coreHooks) : [];
+	await Promise.all([
+		removeCtPrefixed(join(claudeDir, "skills")),
+		removeCtPrefixed(join(claudeDir, "agents")),
+		removePath(join(claudeDir, "skills", "README.md")),
+		removePath(join(claudeDir, "commands", "ct")),
+		// Toolkit hook files (copied from core/hooks) + the generated skill-rules.json.
+		...hookFiles.map((f) => removePath(join(claudeDir, "hooks", f))),
+		removePath(join(claudeDir, "hooks", "skill-rules.json")),
+	]);
+}
+
 /** Generate the .claude/ directory from resolved config */
-export async function generate(projectDir: string, config: ClaudeToolkitConfig): Promise<void> {
+export async function generate(
+	projectDir: string,
+	config: ClaudeToolkitConfig,
+	options: { quiet?: boolean; scaffold?: boolean } = {},
+): Promise<void> {
 	const resolved = await resolveConfig(config);
 	const claudeDir = join(projectDir, ".claude");
 
+	// 0. Clean previously-generated output so removed stacks don't leave stale skills.
+	await removeGenerated(claudeDir);
+
 	// 1. Copy core hooks
 	await copyDir(join(TOOLKIT_ROOT, "core", "hooks"), join(claudeDir, "hooks"));
 
@@ -92,18 +133,30 @@ export async function generate(projectDir: string, config: ClaudeToolkitConfig):
 			"# Task-specific context",
 			"tasks/",
 			"",
+			"# Toolkit regeneration marker",
+			".toolkit-version",
+			"",
 		].join("\n"),
 	);
 
-	// 9. Scaffold base configs
-	await scaffoldConfigs(projectDir, resolved);
+	// 9. Scaffold base configs into the project root (committed files). Skipped for
+	//    automatic/postinstall regeneration so an install never writes committed files.
+	if (options.scaffold !== false) {
+		await scaffoldConfigs(projectDir, resolved, options.quiet);
+	}
 
 	// 10. Generate skills README
 	await generateSkillsReadme(claudeDir, resolved);
 
-	console.log(
-		`Generated .claude/ with ${resolved.stacks.length} stack(s) and ${resolved.skills.length} core skills`,
-	);
+	// Record the toolkit version that produced this output — drives auto-regen on update.
+	const { version } = await readJson<{ version: string }>(join(TOOLKIT_ROOT, "package.json"));
+	await writeFileEnsureDir(join(claudeDir, ".toolkit-version"), `${version}\n`);
+
+	if (!options.quiet) {
+		console.log(
+			`Generated .claude/ with ${resolved.stacks.length} stack(s) and ${resolved.skills.length} core skills`,
+		);
+	}
 }
 
 /** Generate skill-rules.json from resolved config */
@@ -271,7 +324,11 @@ async function generateSettings(claudeDir: string, resolved: ResolvedConfig): Pr
 }
 
 /** Scaffold base config files (biome.json, tsconfig.json) into the project */
-async function scaffoldConfigs(projectDir: string, resolved: ResolvedConfig): Promise<void> {
+async function scaffoldConfigs(
+	projectDir: string,
+	resolved: ResolvedConfig,
+	quiet = false,
+): Promise<void> {
 	if (resolved.config.scaffoldConfigs === false) return;
 
 	const configsDir = join(TOOLKIT_ROOT, "templates", "configs");
@@ -283,10 +340,10 @@ async function scaffoldConfigs(projectDir: string, resolved: ResolvedConfig): Pr
 	for (const { src, dest } of configs) {
 		const destPath = join(projectDir, dest);
 		if (exists(destPath)) {
-			console.log(`  Skipped ${dest} (already exists)`);
+			if (!quiet) console.log(`  Skipped ${dest} (already exists)`);
 		} else {
 			await fsCopyFile(join(configsDir, src), destPath);
-			console.log(`  Scaffolded ${dest}`);
+			if (!quiet) console.log(`  Scaffolded ${dest}`);
 		}
 	}
 }

package/src/utils.ts

@@ -1,11 +1,5 @@
 import { existsSync } from "node:fs";
-import {
-	copyFile,
-	mkdir,
-	readdir,
-	readFile,
-	writeFile,
-} from "node:fs/promises";
+import { copyFile, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
 
 /** Recursively copy a directory */
@@ -24,11 +18,13 @@ export async function copyDir(src: string, dest: string): Promise<void> {
 	}
 }
 
+/** Remove a file or directory recursively. No-op if the path doesn't exist. */
+export async function removePath(path: string): Promise<void> {
+	await rm(path, { recursive: true, force: true });
+}
+
 /** Write a file, creating parent directories as needed */
-export async function writeFileEnsureDir(
-	filePath: string,
-	content: string,
-): Promise<void> {
+export async function writeFileEnsureDir(filePath: string, content: string): Promise<void> {
 	await mkdir(dirname(filePath), { recursive: true });
 	await writeFile(filePath, content, "utf-8");
 }
@@ -45,9 +41,6 @@ export function exists(filePath: string): boolean {
 }
 
 /** Simple template replacement: {{key}} → value */
-export function renderTemplate(
-	template: string,
-	vars: Record<string, string>,
-): string {
+export function renderTemplate(template: string, vars: Record<string, string>): string {
 	return template.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? "");
 }

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

@@ -39,6 +39,21 @@ CapacitorUpdater.notifyAppReady();
 
 This is the safety net that makes OTA reversible. A bundle that white-screens never sticks.
 
+### Boot ordering: splash vs notifyAppReady
+
+A freshly-applied OTA bundle re-runs your bootstrap. Hide the splash *after* the first real view paints, or users see a white webview between hide and first render. Requires `launchAutoHide: false` (otherwise the OS hides the splash on its own schedule and you can't sequence it).
+
+```typescript
+// capacitor.config.ts → plugins.SplashScreen.launchAutoHide: false
+import { SplashScreen } from "@capacitor/splash-screen";
+
+CapacitorUpdater.notifyAppReady();   // fire-and-forget — never gate first paint on it
+await firstMeaningfulView();         // await your app's first real paint
+await SplashScreen.hide();           // only now reveal the webview
+```
+
+`notifyAppReady()` returns a Promise but the 10s `appReadyTimeout` is generous — call it early and move on; do not `await` it before painting. (Webview rendering performance and native feel live in `ct-capacitor-ui`.)
+
 ## Configuration
 
 ```typescript
@@ -176,3 +191,4 @@ OTA of JS/HTML/CSS is allowed: **Apple** developer agreement §3.3.2 (since iOS
 - `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
+- `ct-capacitor-ui` — webview UI performance & native feel (safe areas, touch targets, compositor-only animation)

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

@@ -0,0 +1,66 @@
+---
+name: ct-capacitor-ui
+description: Capacitor webview UI performance and native feel — safe areas, touch targets, tap feedback, compositor-only animation, and on-device profiling
+---
+
+# Capacitor Webview UI & Native Feel
+
+> _Verified against Capacitor 8 (iOS 15 floor; `content-visibility` on iOS 18+) (2026-06)._
+
+The webview *is* the runtime. A Capacitor app lives or dies on whether it feels native — safe-area-aware, instant to tap, smooth to scroll — on a low-end phone, not on your desktop. This skill is the UI/runtime side; OTA delivery lives in `ct-capacitor-ota`.
+
+## Performance & Native Feel
+
+The webview *is* the runtime — budget like a low-end Android phone, not desktop Chrome. Profile on a real cheap device or throttled emulation (4x CPU, "Slow 4G"); effects that are free on a desktop GPU jank in WebView.
+
+```html
+<!-- index.html — required for env() safe-area tokens to resolve to non-zero -->
+<meta name="viewport"
+      content="width=device-width, initial-scale=1, viewport-fit=cover" />
+```
+
+`width=device-width` (above) already removes the legacy ~300ms tap delay on modern iOS/Android WebViews. The block below is about *tap feel*, not latency:
+
+```css
+/* No grey tap-flash; suppress double-tap-to-zoom pause on controls */
+* { -webkit-tap-highlight-color: transparent; }
+button, a, [role="button"], input, label { touch-action: manipulation; }
+
+/* If you kill the default highlight, give back your OWN press feedback —
+   otherwise buttons feel dead. */
+button:active, [role="button"]:active { opacity: 0.7; }
+:focus-visible { outline: 2px solid; outline-offset: 2px; }
+```
+
+```css
+/* Respect notch / home indicator — paint edge-to-edge, pad with env() */
+.app-header { padding-top: env(safe-area-inset-top); }
+.app-footer { padding-bottom: env(safe-area-inset-bottom); }
+
+/* Native scroll feel */
+:where(html, body) { overscroll-behavior: none; }   /* no rubber-band on the shell */
+.scroll-region { overflow-y: auto; overscroll-behavior: contain; }
+```
+
+| Concern       | Do                                                              | Why                                              |
+| ------------- | -------------------------------------------------------------- | ------------------------------------------------ |
+| Touch targets | min 44x44px (iOS) / 48dp (Android)                             | HIG / Material minimum; fewer mis-taps           |
+| Animation     | animate `transform` / `opacity` only                          | compositor-only; skips layout & paint            |
+| Long lists    | `content-visibility: auto` + `contain-intrinsic-size`         | skips offscreen layout on Android & iOS 18+ WebView; older iOS ignores it (harmless). Need it everywhere → use a JS virtualizer |
+| Scroll jank   | avoid `box-shadow` / `filter` / `backdrop-filter` on scrolled nodes | repaint per frame on low-end GPUs           |
+
+Keep the webview locked down regardless of perf work: tight `server.allowNavigation`, no loading remote origins into the shell, and web debugging off in production builds.
+
+## Anti-Patterns
+
+1. **Profiling only in desktop Chrome** — desktop GPU hides jank that cripples low-end Android WebView. Test on a real cheap device or throttled emulation.
+2. **Omitting `viewport-fit=cover`** — `env(safe-area-inset-*)` resolves to 0; content slides under the notch / home indicator and looks like a wrapped website.
+3. **Killing `-webkit-tap-highlight-color` without a replacement press state** — buttons feel dead (no touch acknowledgement). Remove the grey flash *and* add your own `:active` / `:focus-visible` feedback. (Note: the legacy 300ms delay is already gone on modern WebViews via `width=device-width`; `touch-action: manipulation` only suppresses the double-tap-zoom pause.)
+4. **Animating `top` / `left` / `width` or shadows on scroll** — forces layout/paint each frame; use `transform` / `opacity`.
+
+## See Also
+
+- `ct-capacitor-ota` — OTA delivery, channels, `notifyAppReady`, and the splash/boot-ordering note.
+- `ct-solidjs-patterns` — `lazy()` + `<Suspense>` screen splitting protects webview cold-start.
+- `ct-vanilla-extract-patterns` — author the safe-area / logical-property styles; animate `transform`/`opacity` only.
+- `ct-i18n-typesafe` — defer locale loading so first paint isn't blocked.

package/stacks/capacitor/stack.json

@@ -57,7 +57,53 @@
 			"relatedSkills": [
 				"ct-vite-vitest-patterns",
 				"ct-playwright-patterns",
-				"ct-typescript-conventions"
+				"ct-typescript-conventions",
+				"ct-capacitor-ui"
+			]
+		},
+		"ct-capacitor-ui": {
+			"description": "Capacitor webview UI performance and native feel: safe areas, touch targets, tap feedback, compositor-only animation, on-device profiling",
+			"priority": 7,
+			"triggers": {
+				"keywords": [
+					"safe area",
+					"safe-area",
+					"viewport",
+					"touch target",
+					"tap highlight",
+					"native feel",
+					"splash",
+					"overscroll",
+					"notch",
+					"home indicator",
+					"webview"
+				],
+				"keywordPatterns": [
+					"\\bsafe-area\\b",
+					"\\bviewport-fit\\b",
+					"\\btouch-action\\b",
+					"\\boverscroll\\b"
+				],
+				"pathPatterns": ["**/index.html"],
+				"intentPatterns": [
+					"(?:safe area|notch|home indicator)",
+					"(?:native feel|touch target|tap feedback)",
+					"(?:scroll|animation).*(?:jank|smooth|perf)"
+				],
+				"contentPatterns": [
+					"safe-area-inset",
+					"viewport-fit",
+					"touch-action",
+					"-webkit-tap-highlight-color",
+					"overscroll-behavior",
+					"content-visibility"
+				]
+			},
+			"relatedSkills": [
+				"ct-capacitor-ota",
+				"ct-solidjs-patterns",
+				"ct-vanilla-extract-patterns",
+				"ct-i18n-typesafe"
 			]
 		}
 	}

package/stacks/cloudflare/skills/ct-cloudflare-d1-kv/SKILL.md

@@ -96,6 +96,83 @@ Key points:
 - Always use Hyperdrive for external database connections from Workers.
 - Connection pool size is configurable per Hyperdrive config.
 
+## Performance
+
+> _Verified against Cloudflare Workers / D1 / KV (2026-06)._
+
+Latency on Workers is dominated by **network round trips**, not CPU. Every `await` on D1/KV/`fetch` is a hop -- collapse and parallelize them.
+
+### Don't serialize independent round trips
+
+```rust
+// BAD: ~2x latency -- two independent reads run back to back
+let user = get_user(&db, id).await?;
+let prefs = get_prefs(&kv, id).await?;
+
+// GOOD: one round-trip wall-time -- run concurrently
+let (user, prefs) = futures::try_join!(get_user(&db, id), get_prefs(&kv, id))?;
+```
+```typescript
+// TS equivalent
+const [user, prefs] = await Promise.all([getUser(db, id), getPrefs(kv, id)]);
+```
+
+I/O overlaps in the single-threaded isolate, so wall-time approaches the slowest call. (A Worker can have only ~6 connections waiting on response headers at once -- so fan-out is no substitute for collapsing N reads into one query.)
+
+Kill N+1: never loop per-row queries. Use one `IN (...)`/JOIN, or `db.batch()` of selects.
+
+```rust
+// BAD: 1 + N round trips
+for id in ids { rows.push(db.prepare("SELECT * FROM u WHERE id=?1").bind(&[id.into()])?.first(None).await?); }
+// GOOD: 1 round trip
+let placeholders = ids.iter().map(|_| "?").collect::<Vec<_>>().join(",");
+let users = db.prepare(&format!("SELECT * FROM u WHERE id IN ({placeholders})"))
+    .bind(&binds)?.all().await?.results::<User>()?;   // .all() -> D1Result; .results() -> typed rows
+```
+
+### Verify the index is actually used
+
+An index exists != the planner uses it. Functions on columns, leading-`%` LIKE, and TEXT/INT mismatches force a SCAN.
+
+```sql
+EXPLAIN QUERY PLAN SELECT * FROM users WHERE email = ?1;
+-- want: SEARCH users USING INDEX idx_users_email   (NOT: SCAN users)
+```
+
+### Cache API for full responses (not just KV)
+
+`caches.default` is data-center-local (contents don't replicate across colos): sub-ms in-colo, cheaper than a KV read, no eventual-consistency lag. Use it for whole GET responses (only GET is cacheable); use KV read-through for sub-response values. Fill the cache off the response path with `waitUntil`.
+
+```typescript
+const cache = caches.default;
+let res = await cache.match(request);
+if (!res) {
+  res = await render(request);                 // Cache-Control sets TTL
+  ctx.waitUntil(cache.put(request, res.clone())); // non-blocking write
+}
+return res;
+```
+
+`cache.put` rejects non-GET, `206`, `Vary: *`, and `Set-Cookie` responses (strip the cookie or set `Cache-Control: private=Set-Cookie` first).
+
+Same rule for cache/KV writes and invalidation: `ctx.waitUntil(kv.put(...))` so writes never add to TTFB.
+
+### Stream instead of buffering
+
+Buffering the full body adds total generation time to TTFB. Return a `ReadableStream` (or pipe an upstream body) so bytes flush as produced.
+
+### Smart Placement for origin/Hyperdrive-heavy Workers
+
+Smart Placement moves the isolate closer to your **back-end** (origin APIs, or an external Postgres/MySQL behind Hyperdrive) when latency is dominated by multiple **sequential** calls to it:
+
+```toml
+# wrangler.toml
+[placement]
+mode = "smart"
+```
+
+It does **not** help D1 or KV: D1 routing is governed by the primary-instance location + read replication (use the Sessions API to read from a nearby replica), and KV is already served from the data center the Worker runs in. Leave Smart Placement off for single-hop, D1/KV-only, or static-heavy Workers.
+
 ## Anti-Patterns
 
 1. **Unbounded queries** -- Always LIMIT. D1 has 5MB response cap.
@@ -104,3 +181,12 @@ Key points:
 4. **Skipping batch** -- Each D1 call is a network round trip.
 5. **KV without TTL** -- Stale data persists indefinitely.
 6. **Untested migrations** -- Always `--local` before `--remote`.
+7. **Sequential awaits on independent reads** -- each is a round trip; use `try_join!`/`Promise.all`.
+8. **Per-row query loops (N+1)** -- batch into one `IN (...)`/JOIN or `db.batch()`.
+9. **Awaiting cache/KV writes before responding** -- use `ctx.waitUntil()` so puts don't add to TTFB.
+10. **Assuming the index is used** -- check `EXPLAIN QUERY PLAN` for `USING INDEX`, not `SCAN`.
+11. **Smart Placement for D1/KV latency** -- it targets origins/Hyperdrive, not D1/KV; use D1 read replication (Sessions API) instead.
+
+## See Also
+
+- `ct-rust-wasm-patterns` — the same D1 round-trip / `IN`-with-bound-params batching, from the Rust handler side.

package/stacks/i18n-typesafe/skills/ct-i18n-typesafe/SKILL.md

@@ -54,6 +54,49 @@ Types are inferred from base locale: `{name:string}`, `{count:number}`. TypeScri
 
 Organize by feature (common, auth, events), one level deep. Avoid deep nesting -- it makes keys verbose.
 
+## Performance
+
+> _Verified against typesafe-i18n + SolidJS (2026-06)._
+
+Ship one locale, not all. typesafe-i18n generates both loaders -- pick the async one.
+
+```ts
+// CORRECT: per-locale dynamic import -> separate chunk, only active locale fetched
+import { loadLocaleAsync } from './i18n/i18n-util.async';
+await loadLocaleAsync(detectLocale());   // e.g. 'en' loads the i18n/en chunk only
+
+// WRONG: i18n-util.sync static-imports every dictionary at module top -> all in this bundle
+import { loadLocale } from './i18n/i18n-util.sync';
+loadLocale('en');                        // loadAllLocales() is worse
+```
+
+Build formatters once per locale; never construct Intl objects in a component or list row. (Measured: constructing `Intl.NumberFormat` ~20x slower than reusing one instance.)
+
+```ts
+// src/i18n/formatters.ts -- constructed once via loadFormatters(locale)
+export const initFormatters: FormattersInitializer<Locales, Formatters> = (locale) => ({
+  // Intl.* is expensive to construct; reuse the instance across all calls
+  currency: (v: number) => new Intl.NumberFormat(locale, { style: 'currency', currency: 'EUR' }).format(v),
+});
+// usage in en/index.ts: price: 'Total: {amount:number|currency}'  -- typed param, not new Intl.* at the call site
+```
+
+Don't block first paint on the locale fetch. In Solid, `<Suspense>` only suspends on a tracked resource read -- a bare `await loadLocaleAsync()` will NOT trip the boundary. Drive it off a resource (or use the Solid adapter's `<TypesafeI18n>`, which withholds children until the locale loads):
+
+```tsx
+import { createResource, Suspense } from 'solid-js';
+// loaded() is read inside the boundary, so Suspense shows the shell until the chunk arrives
+const [loaded] = createResource(detectLocale, loadLocaleAsync);
+<Suspense fallback={<AppShell />}>{loaded.state === 'ready' && props.children}</Suspense>
+// index.html: a modulepreload link for /assets/i18n-en-*.js overlaps with the main bundle fetch
+```
+
+RTL: drive the html dir attribute from the locale; use CSS logical properties so layout flips with zero extra CSS or JS.
+
+```css
+.card { margin-inline-start: 1rem; padding-inline: 1rem; inset-inline-start: 0; } /* not margin-left */
+```
+
 ## Anti-Patterns
 
 1. **Hardcoded strings** -- Every user-visible string goes through `LL()`.
@@ -62,3 +105,12 @@ Organize by feature (common, auth, events), one level deep. Avoid deep nesting -
 4. **Dynamic key access** -- `LL()[dynamicKey]()` bypasses type safety. Use conditional rendering.
 5. **Forgetting loadLocale** -- Must call before rendering or get runtime errors.
 6. **Over-splitting namespaces** -- Group by feature, not by component.
+7. **Sync `loadLocale` / `loadAllLocales` in app code** -- `i18n-util.sync` static-imports every dictionary into the bundle that pulls it in. Use `loadLocaleAsync` so each locale is its own chunk.
+8. **Constructing `Intl.NumberFormat`/`DateTimeFormat` per render** -- ~20x costlier than reuse; build once in `formatters.ts` and reference via `{v:number|formatter}`.
+9. **Awaiting `loadLocaleAsync` without a Suspense-tracked resource** -- Blanks the screen until the JSON loads, and a bare `await` never trips Solid's `<Suspense>`. Gate via `createResource` (or `<TypesafeI18n>`), show a shell fallback, and modulepreload the active locale.
+10. **Physical CSS for layout (`margin-left`, `left`)** -- Breaks RTL and needs per-dir overrides. Use logical properties (`margin-inline-start`, `inset-inline-start`).
+
+## See Also
+
+- `ct-solidjs-patterns` — the `createResource`-tracked `<Suspense>` boundary (a bare `await` never suspends in Solid) and `lazy()` cold-start splitting.
+- `ct-vanilla-extract-patterns` — RTL = `dir` from locale (here) + logical properties authored in `.css.ts` (there).

package/stacks/i18n-typesafe/stack.json

@@ -19,7 +19,8 @@
 					"(?:translat).*(?:key|string)"
 				],
 				"contentPatterns": ["useI18nContext", "LL\\.", "baseLocale", "Locales"]
-			}
+			},
+			"relatedSkills": ["ct-solidjs-patterns", "ct-vanilla-extract-patterns"]
 		}
 	}
 }