sanook-cli 0.4.0 → 0.5.1

package/skills/optimize-llm-cost-latency/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: optimize-llm-cost-latency
+description: Cuts LLM token cost and tail latency via context trimming, provider prompt caching on stable prefixes, model tiering/routing, semantic answer caching, batch APIs, and streaming, proving a measured before/after on cost-per-request and p50/p95 at equal output quality.
+when_to_use: An LLM feature is too slow or too expensive, or usage is scaling and the bill/latency matters. Distinct from prompt-engineering (output quality), rag-pipeline (retrieval quality), and harden-llm-app-reliability (timeouts/retries/fallback).
+---
+
+## When to Use
+
+Reach for this skill when the problem is **spend or speed**, not what the model says:
+
+- "Our LLM bill is $X/month and climbing — cut it"
+- "This call takes 8s; make it feel fast"
+- "Token usage per request is huge — trim it"
+- "We send the same 6k-token system prompt on every call"
+- "We re-answer near-identical questions all day"
+- "We have a nightly batch of 50k classifications — too slow/expensive"
+
+NOT this skill:
+- Making the *output* better/more correct/structured → prompt-engineering
+- Improving *what gets retrieved* into context (chunking/embeddings/reranking) → rag-pipeline
+- Timeouts, retries, fallback models, circuit breakers when a call fails → harden-llm-app-reliability
+- Blocking malicious instructions in inputs/tools → defend-llm-prompt-injection
+- Generic HTTP/data response caching unrelated to LLM token economics → caching-strategy
+- Cutting compute/storage/egress spend on the infra bill → cloud-cost-optimize
+
+## Steps
+
+1. **Measure first — no optimization without a baseline.** Log per request: `input_tokens`, `output_tokens`, model id, end-to-end latency, and time-to-first-token (TTFT). Get exact counts from the provider's usage object or a count-tokens endpoint — never estimate from `len(text)/4` for billing decisions. Compute `$/req` from current per-token prices and aggregate **p50/p95** (means hide the tail that users actually feel). You cannot claim a win without these numbers before and after.
+
+   ```python
+   # cost per request from the provider usage object (Anthropic-style)
+   u = resp.usage  # input_tokens / output_tokens / cache_creation_input_tokens / cache_read_input_tokens
+   cost = (u.input_tokens*IN + u.output_tokens*OUT
+           + u.cache_creation_input_tokens*CACHE_WRITE   # ~1.25x input
+           + u.cache_read_input_tokens*CACHE_READ) / 1e6 # ~0.1x input
+   ```
+
+2. **Apply levers in ROI order — cheapest, highest-impact first.** Do not jump to a fancy router before you've capped output and cached the prefix.
+
+   | Lever | Typical win | Effort | Use when |
+   |---|---|---|---|
+   | Cap `max_tokens` + stop sequences | 10–40% output cost | trivial | output runs longer than needed |
+   | Context diet (trim history, drop dead few-shot) | 20–60% input cost | low | long/growing prompts |
+   | **Prompt caching** (cache stable prefix) | **up to 90% on the cached portion**, lower TTFT | low | long fixed system prompt / RAG docs reused across calls |
+   | Streaming | TTFT 5–10x better (perceived) | low | user-facing chat/UI |
+   | Model tiering/routing | 50–95% on easy traffic | medium | mixed easy/hard requests |
+   | Semantic cache | ~100% on a cache hit | medium | repeated/near-duplicate queries |
+   | Batch API | ~50% on $ | medium | offline, non-urgent jobs |
+
+3. **Context diet — shrink input before you optimize how you send it.** Every input token is paid on every call. (a) **Cap history**: keep the last N turns; once over a token budget, **summarize** older turns into a compact running summary instead of carrying raw transcript. (b) **Cut dead few-shot examples**: drop each example and re-run the eval — keep only those that move accuracy. Most prompts carry 3–4 examples that earn nothing. (c) Strip boilerplate, redundant instructions, and verbose tool schemas. Re-measure tokens after each cut.
+
+4. **Prompt caching — usually the single biggest win.** Put the **stable, large** content first (system prompt, tool definitions, RAG documents, long instructions) and the **variable** part (the user's actual turn) last, then mark the boundary with the provider's cache control so the prefix is reused across requests. Order matters: the cache keys on an exact prefix match, so one moving token near the top busts the whole cache.
+
+   ```python
+   # Anthropic: cache_control breakpoint on the stable prefix; variable user msg stays uncached
+   system=[{"type":"text","text":BIG_STABLE_PROMPT,"cache_control":{"type":"ephemeral"}}]
+   # OpenAI: automatic prefix caching — just keep the prefix byte-identical and put it first
+   ```
+   Cache reads are ~10% of input price; writes ~25% more than input — so caching pays off once a prefix is reused even a handful of times within its TTL (~5 min ephemeral). Verify hits via `cache_read_input_tokens > 0`.
+
+5. **Model tiering + routing — send easy work to the cheap model.** Default the bulk of traffic to a small/fast model; escalate only when needed. Pick a **deterministic router** over an LLM-classifier router when you can (no extra call, no extra latency): route on cheap signals — input length, required output schema, presence of code/math, retrieval confidence, or an explicit difficulty flag. Use a tiny classifier model only when rules can't separate easy from hard. Always escalate on low-confidence or a validation failure rather than returning a bad cheap answer.
+
+   ```python
+   def route(req):
+       if req.tokens < 800 and not req.needs_reasoning: return SMALL   # ~1/10 the cost
+       if req.needs_long_reasoning or req.high_stakes:  return LARGE
+       return MID
+   # escalate: if small-model output fails schema/confidence check -> retry once on LARGE
+   ```
+
+6. **Semantic cache for repeated/near-duplicate queries.** Embed the normalized query, look it up in a vector store; on cosine similarity ≥ ~0.95 return the cached answer (0 LLM tokens). Set a conservative threshold (too low → wrong cached answers), scope the key by anything that changes the answer (user/tenant/locale/tool-version), and TTL it so stale facts expire. Bypass the cache for personalized or time-sensitive responses. This is *exact/near-exact answer reuse*, layered on top of prompt caching (which reuses the prefix, not the answer).
+
+7. **Batch the offline work.** Anything not blocking a user — nightly classification, backfills, evals, bulk summarization — goes through the provider **Batch API** (Anthropic Message Batches / OpenAI Batch) for ~50% off, accepting up to ~24h turnaround. Never batch interactive requests.
+
+8. **Stream to cut *perceived* latency.** For any user-facing surface, stream tokens (`stream=True` / SSE) so first text shows in a few hundred ms instead of after the full generation. This doesn't reduce cost or total wall-clock, but it collapses TTFT — often the only latency users perceive. Combine with caching: a cached prefix also lowers real TTFT.
+
+9. **Re-measure and prove equal quality.** Re-run the same metrics (step 1) after changes, and run your eval set to confirm output quality didn't regress (see Verify). A cost win that drops accuracy is not a win — report cost/latency **and** the quality delta together.
+
+## Common Errors
+
+- **Optimizing without a baseline.** "Feels faster/cheaper" is not a number. Capture p50/p95 and $/req before touching anything, or you can't prove (or trust) the result.
+- **Estimating tokens with `len/4`.** Fine for a rough guess, wrong for billing and for `max_tokens` budgeting. Use the provider usage object / count-tokens endpoint.
+- **Cache-busting the prefix.** Putting a timestamp, request id, randomized example order, or the user message *before* the stable block invalidates the cache every call. Stable content first, byte-identical; variable content last.
+- **Caching the wrong span.** Marking a tiny or rarely-reused prefix as cached pays the ~25% write premium for no reads. Cache large prefixes reused within the TTL; confirm with `cache_read_input_tokens`.
+- **Semantic-cache threshold too loose.** A 0.85 similarity match returns a confidently wrong answer for a different question. Start ≥0.95, log near-miss hits, and never cache personalized/time-sensitive answers.
+- **Unscoped cache key.** Caching by query text alone leaks one tenant/user/locale's answer to another. Include every dimension that changes the correct answer in the key.
+- **Router that always escalates.** A misconfigured or overcautious router sends everything to the big model — you pay more *and* added a routing hop. Verify the cheap-model hit rate; if <50% on easy traffic, the rules are wrong.
+- **Unbounded `max_tokens`.** Leaving it at the model max lets a runaway generation bill thousands of output tokens. Set it to the real ceiling and add stop sequences.
+- **Batching interactive traffic.** Batch APIs trade latency for price; a user waiting on a 24h-window response is a broken product. Batch only offline work.
+- **Streaming to a non-interactive consumer.** Streaming into code that just `.join()`s the whole thing adds complexity with zero benefit — and can hide errors that arrive mid-stream. Stream only where a human sees partial output.
+- **Trimming context until quality silently drops.** Aggressive history truncation or cutting a load-bearing few-shot example tanks accuracy. Gate every cut behind the eval (step 9).
+
+## Verify
+
+1. **Baseline captured:** before/after table exists with `input_tokens`, `output_tokens`, `$/req`, p50, p95, and TTFT — real measured numbers, not estimates.
+2. **Cost dropped:** post-change `$/req` is measurably lower (state the %), computed from the provider usage object at current prices.
+3. **Latency dropped:** p95 (and TTFT for user-facing paths) improved; report the actual ms, not "feels faster."
+4. **Cache is hot:** `cache_read_input_tokens > 0` on repeat requests, and the measured hit rate is reported. A prompt cache that never reads is dead config.
+5. **Router behaves:** the cheap model handles the majority of easy traffic (hit-rate stated), and escalation fires on low-confidence/validation-fail (one logged example each).
+6. **Semantic cache is safe:** a deliberately *different* query below threshold does **not** return a cached answer; key scoping (tenant/locale) prevents cross-leak.
+7. **Quality held:** the eval set scores within tolerance of baseline (state the delta) — the cost/latency win did not regress accuracy. If it did, the change is rejected.
+
+Done = a before/after table shows lower $/req and lower p50/p95 (with cache hit rate and cheap-model share stated), and the eval confirms output quality is unchanged at the new, cheaper, faster configuration.

package/skills/optimize-react-rerenders/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: optimize-react-rerenders
+description: Eliminates wasted React re-renders by measuring first then fixing — profile with the React DevTools Profiler (flamegraph + "why did this render") and why-did-you-render to find the actual offenders, then apply the right fix: stable references (hoist constants, useCallback/useMemo only where a referentially-equal prop/dep actually matters), correct list keys (stable id, never index), React.memo with a custom comparator on genuinely-hot leaf components, context splitting + selector subscriptions (useSyncExternalStore / Zustand / use-context-selector) to stop whole-tree re-renders, derive-don't-store to kill redundant state, and list virtualization (TanStack Virtual) for long lists — while knowing when NOT to memo (cheap renders, unstable deps, and the React 19 Compiler which auto-memoizes and makes most manual memo dead weight).
+when_to_use: A React app re-renders too much — typing lags, a list re-renders every row on one change, the Profiler shows components rendering with unchanged props, or you're sprinkling useMemo/useCallback/React.memo and want to know what actually helps. Distinct from optimize-core-web-vitals (load/paint metrics — LCP/INP/CLS and asset/JS strategy, not render-count) and manage-client-server-state (data-fetching/caching architecture with TanStack Query; this skill fixes the render churn that fetched data triggers).
+---
+
+## When to Use
+
+Reach for this skill when the problem is **too many React renders / render churn**, not load time, not data fetching:
+
+- "Typing in this input lags / the whole form re-renders on every keystroke"
+- "Changing one row re-renders the entire list of 500 items"
+- "The Profiler shows components re-rendering even though their props didn't change"
+- "I added `useMemo`/`useCallback`/`React.memo` everywhere and it's not faster (or slower)"
+- "A context update re-renders half the tree"
+- "Should I memoize this?" / "Is this `useMemo` worth it?" / "We're on React 19 — do I still need this?"
+- "Long list scrolls slowly / mounts thousands of DOM nodes"
+
+NOT this skill:
+- Slow initial load, late paint, layout shift, or a red Lighthouse score (LCP/INP/CLS, image/font/JS-bundle strategy) → optimize-core-web-vitals (it owns paint/load metrics; this skill owns render *count*. Note: cutting re-renders during interaction also improves INP, but go there for the metric-driven workflow)
+- Data fetching, cache invalidation, optimistic updates, SSR hydration, or picking a store (TanStack Query / Zustand / Redux) → manage-client-server-state (it architects *where state lives and how it's fetched*; this skill stops the renders that state changes cause)
+- Building a new component's structure/props/a11y from scratch → build-react-component
+- A big interactive grid feature (sorting/filtering/column resize/selection) as a unit → build-data-table (it builds the table; this skill makes its rows stop re-rendering)
+- Backend/server query latency or a CPU profile of non-React code → performance-profiling
+- Using the browser/Chrome DevTools to debug a runtime bug (state, network, errors) generally → debug-frontend-browser (this skill is the render-perf specialization of profiling)
+
+## Steps
+
+1. **Measure before you touch anything — never memoize on a hunch.** Manual memoization is a tradeoff (extra comparisons + cache memory); applied blindly it often makes things *slower* and always makes them harder to read. Get evidence first:
+
+   | Tool | What it tells you | How |
+   |---|---|---|
+   | **React DevTools Profiler** | which components rendered, how long, **why** | record an interaction → flamegraph + ranked chart |
+   | **"Highlight updates when components render"** (DevTools → ⚙ → Components) | visual flash on every render — instant "this re-renders on every keystroke" signal | toggle on, interact |
+   | **`why-did-you-render`** | logs the *exact prop/state/hook that changed* (and whether it was a deep-equal-but-referentially-different value) | dev-only, see step 2 |
+   | **React 19 `<Profiler onRender>`** / `performance.measure` | programmatic render timings in tests/CI | wrap a subtree |
+
+   In the Profiler, enable **"Record why each component rendered"** (⚙ → Profiler). Re-renders show a reason: *props changed*, *hooks changed*, *parent rendered*, *context changed*. That reason picks the fix below — don't guess.
+
+2. **Wire up `why-did-you-render` to catch referential-equality bugs (dev only).** It surfaces the classic "props are deep-equal but a new object/array/function identity every render" case that React.memo can't catch.
+   ```js
+   // wdyr.js — import FIRST, before React renders anything
+   import React from 'react';
+   if (process.env.NODE_ENV === 'development') {
+     const wdyr = require('@welldone-software/why-did-you-render');
+     wdyr(React, { trackAllPureComponents: true, collapseGroups: true });
+   }
+   ```
+   A log like *"props.style changed: ({}) → ({}) (different objects that are equal by value)"* means: hoist the literal or memoize the reference — not wrap the child in `memo`.
+
+3. **If you're on React 19, turn on the React Compiler FIRST — it auto-memoizes and makes most manual memo dead weight.** The compiler (`babel-plugin-react-compiler`, also in the Next.js / Vite plugin) memoizes components and hook values automatically at build time, so `useMemo`/`useCallback`/`React.memo` become largely redundant. Before hand-tuning:
+   - Install and enable it; run `npx react-compiler-healthcheck` to see how many components are compatible (it skips components that break the Rules of React — those are your real bugs to fix).
+   - **Don't mix strategies blindly:** keep code Rules-of-React-clean (no mutation of props/state, no conditional hooks) so the compiler can optimize. New manual `useMemo`/`useCallback` you add on top is usually noise. Lean on `<StrictMode>` to surface impurity.
+   - The compiler does **not** fix algorithmic problems (huge lists, O(n²) renders) — you still need virtualization (step 9) and correct keys (step 7). Treat the rest of these steps as either pre-19 work or the things the compiler can't do.
+
+4. **Kill unstable references at the source — this is the #1 cause of "memo doesn't work".** `React.memo` and dep arrays compare by reference (`Object.is`). A new `{}`, `[]`, or arrow function created in render is a new identity every time, so it busts every downstream memo and effect. Fix the *source*, don't paper over it:
+
+   | Anti-pattern (new identity each render) | Fix |
+   |---|---|
+   | `<Child style={{ margin: 8 }} />` | hoist the object to a module-level `const` (it never changes) |
+   | `<Child onClick={() => doX(id)} />` passed to a memoized child | `useCallback(() => doX(id), [id])` |
+   | `const opts = { a, b }` then used in a dep array | `useMemo(() => ({ a, b }), [a, b])` |
+   | `data.filter(...)` computed inline each render into a memoized child | `useMemo(() => data.filter(...), [data])` |
+   | default prop `items = []` (new array each call) | hoist `const EMPTY = []` and default to it |
+
+   Static values (handlers with no closure deps, constant config) belong **outside the component** entirely — zero runtime cost.
+
+5. **Use `useCallback`/`useMemo` only where a referentially-equal value actually changes behavior — otherwise skip it.** They are not free: each stores a closure + dep array and runs an equality check every render. They earn their keep in exactly these cases — and nowhere else:
+   - The memoized value/callback is **a dependency of another hook** (`useEffect`, `useMemo`) where a changing identity would refire the effect.
+   - It's **passed as a prop to a `React.memo`'d child** (otherwise the child's memo is pointless).
+   - `useMemo` wraps a **genuinely expensive computation** (sort/filter of thousands, parse, heavy derive) — measure; "expensive" is rarely a `.map` over 20 items.
+
+   **Skip them when** the consumer isn't memoized, the deps change every render anyway (then the cache never hits — pure overhead), or the body is cheap. A `useCallback` whose result flows only into a non-memoized DOM `<button onClick>` does nothing useful.
+
+6. **`React.memo` only the genuinely-hot leaf, and give it the right comparator.** `memo` skips a re-render when props are shallow-equal. Apply it to a component that (a) renders often due to *parent* re-renders, (b) is expensive or numerous (list rows), and (c) gets **stable props** (you did step 4). Without stable props it's worse than nothing.
+   - Default shallow compare is correct most of the time. Provide a custom `areEqual(prev, next)` only for a known-shape prop where shallow misses (e.g. compare `prev.item.id === next.item.id && prev.selected === next.selected`) — and keep it cheaper than the render it saves.
+   - `memo` compares **props only** — it does **not** stop re-renders from internal `useState`/`useContext` changes. If the offender is context (step 8) or state, `memo` won't help.
+   ```jsx
+   const Row = memo(function Row({ item, onSelect }) { /* ... */ },
+     (a, b) => a.item.id === b.item.id && a.item.label === b.item.label && a.onSelect === b.onSelect);
+   ```
+
+7. **Fix list keys — wrong keys force remounts and break memoized rows.** Use a **stable, unique id** from the data (`item.id`), never the array index for any list that can reorder, insert, or delete. Index keys make React reuse the wrong DOM/state on reorder (lost input focus, wrong row highlighted) and defeat per-row `memo`. Don't use `Math.random()`/`uuid()` in render either — a new key every render remounts the row each time. Stable identity → React diffs in place → memoized rows actually skip.
+
+8. **Stop context from re-rendering the whole subtree — split it or use a selector.** Every consumer of a context re-renders whenever **any** field of the context value changes, even fields it doesn't read. Three escalating fixes:
+
+   | Technique | When | How |
+   |---|---|---|
+   | **Memoize the provider value** | value is `{}`/`[]` literal inline | `value={useMemo(() => ({ user, setUser }), [user])}` — without this *every* consumer re-renders every parent render |
+   | **Split contexts by change frequency** | one context mixes hot + cold data (e.g. `theme` + live `cursorPosition`) | separate providers; a component subscribes only to what it uses → high-frequency updates don't touch theme consumers |
+   | **Selector subscription** | consumers read different slices of a big store | `useSyncExternalStore` with a selector, `use-context-selector`, or a store lib (**Zustand**: `useStore(s => s.field)`, **Redux**: `useSelector`) — re-render only when the *selected* slice changes |
+
+   Splitting state-vs-dispatch contexts is a cheap classic win: a component that only dispatches never re-renders on state changes.
+
+9. **Virtualize long lists instead of memoizing 10,000 rows.** No amount of `memo` saves you from mounting thousands of DOM nodes. Render only the visible window (+overscan) with **TanStack Virtual** (`@tanstack/react-virtual`, headless, framework-agnostic) or `react-virtuoso`. It computes which rows intersect the viewport and absolutely-positions them; DOM stays ~constant regardless of dataset size. Combine with stable keys (step 7) and a memoized row. This is the fix when the *count* is the problem, not per-row work.
+
+10. **Derive, don't store — redundant state is redundant renders.** Anything computable from props/existing state during render should be **computed in render** (optionally `useMemo`'d), not held in its own `useState` synced via `useEffect`. The `useState`+`useEffect`-to-sync pattern adds an extra render every change and drifts out of sync. Likewise: lift state **down** (push it into the smallest component that needs it so updates don't re-render siblings), and split a god-component so a chatty piece of state isn't wired into a large subtree. Fewer state cells in fewer places = fewer renders.
+
+11. **Don't over-memoize — premature memoization has a real cost.** Each `memo`/`useMemo`/`useCallback` adds an equality check + retained closure + cognitive load, and a wrong dep array becomes a stale-closure bug. Rules of thumb: leave cheap components un-memoized; never wrap a component whose props are unstable (fix the props instead); never memoize purely to "be safe." On React 19, prefer the compiler over manual memo. Memoize when the Profiler shows a *measured* hot path — not before. Remove memos that the Profiler shows aren't being hit.
+
+## Common Errors
+
+- **`React.memo` with unstable props.** Memo'd child still re-renders because a parent passes a fresh `{}`/`() => {}` each render. Fix: stabilize the prop at the source (step 4) — `memo` without stable props is pure overhead.
+- **`useCallback`/`useMemo` feeding a non-memoized consumer.** A stable callback handed to a plain `<button>` or non-`memo` child changes nothing but adds overhead. Fix: only memoize values that cross into a `memo`'d child or another hook's deps.
+- **Dep array that changes every render.** The memo never caches (cache miss every time) — all cost, no benefit. Fix: stabilize the deps too, or drop the memo.
+- **Index as list key.** Reorders/inserts reuse the wrong DOM/state and break per-row memo; lost focus, wrong highlight. Fix: stable `item.id` key.
+- **`Math.random()`/`uuid()` key in render.** Remounts every row every render — the opposite of memoization. Fix: derive a stable id once.
+- **Inline object/array provider value.** `<Ctx.Provider value={{a,b}}>` re-renders every consumer on every parent render. Fix: `useMemo` the value, or split contexts.
+- **One fat context for hot + cold data.** A 60fps field re-renders theme/auth consumers. Fix: split by update frequency; use a selector subscription.
+- **`useState` mirrored from props via `useEffect`.** Extra render + drift. Fix: derive in render (`useMemo` if pricey).
+- **Memoizing everything by default.** Slower and unreadable; stale-closure bugs from wrong deps. Fix: memoize measured hot paths only; on React 19 let the compiler do it.
+- **Expecting `memo` to stop context/state re-renders.** `memo` compares props only. Fix: address the actual reason the Profiler reports (context → split/selector; state → derive/lift).
+
+## Verify
+
+1. **Profiler shows the offender gone:** record the same interaction before/after — the component that flashed/rendered "props changed (but equal)" or "parent rendered" no longer appears in the commit (or its render time drops). Keep the before flamegraph as proof.
+2. **`why-did-you-render` is silent on the fixed path:** no "different objects that are equal by value" logs for the props you stabilized.
+3. **Typing/interaction is smooth:** the input/list that lagged updates per keystroke without re-rendering unrelated siblings; "Highlight updates" flashes only the changed node.
+4. **One-row change → one row renders:** mutating a single list item re-renders that row only, not the whole list (visible in the Profiler ranked chart).
+5. **Context change is scoped:** updating a hot context field re-renders only its real consumers; theme/auth consumers stay dark.
+6. **Long list DOM is bounded:** the virtualized list mounts ~viewport+overscan rows, and node count stays roughly constant as the dataset grows from 100 → 10,000.
+7. **No memo is dead weight:** every remaining `memo`/`useMemo`/`useCallback` corresponds to a Profiler-confirmed hot path or a real dep/`memo`-prop boundary; the rest were removed. On React 19, `react-compiler-healthcheck` passes and manual memo is minimal.
+
+Done = the measured re-render(s) the Profiler flagged are eliminated by the matching fix (stable refs, correct keys, context split/selector, derive-don't-store, or virtualization), every remaining manual memo is justified by evidence (or replaced by the React 19 compiler), and the before/after Profiler traces prove the churn is gone — not added overhead.

package/skills/orchestrate-agent-workflow/SKILL.md

@@ -0,0 +1,100 @@
+---
+name: orchestrate-agent-workflow
+description: Designs reliable multi-step LLM agent loops — tool-call orchestration, state/memory between steps, explicit stop conditions, per-step verification, retries/replanning, subagent decomposition, and budget/approval gates — so an agent finishes long tasks without drifting or looping forever.
+when_to_use: Building an agent that plans and calls tools across multiple steps, not a single prompt-and-response. Distinct from agent-tool-mcp-builder (designing the individual tools/MCP server), prompt-engineering (single-prompt/structured-output design), and harden-llm-app-reliability (transport-level retry/timeout of one model call).
+---
+
+## When to Use
+
+Reach for this skill when the work spans **multiple model→tool→observe turns** under one goal:
+
+- "Build an agent that researches, then drafts, then files a PR / ticket"
+- "My agent loops forever / repeats the same tool call / never decides it's done"
+- "It drifts off-task halfway through and starts solving a different problem"
+- "Split this big task across subagents and stitch the results back together"
+- "Add a cost/step cap and a human-approval gate before it deletes / deploys / pays"
+
+NOT this skill:
+- Designing the tool schemas / error shapes / MCP server the agent calls → agent-tool-mcp-builder
+- Writing or hardening a single prompt or its JSON/function-call contract → prompt-engineering
+- Making *one* model call survive timeouts/429s/5xx (retry, backoff, circuit breaker) → harden-llm-app-reliability
+- Cutting token cost / latency of the model calls themselves (caching, model routing) → optimize-llm-cost-latency
+- Treating tool output / web content as untrusted input → defend-llm-prompt-injection
+
+## Steps
+
+1. **Pick the simplest topology that works — escalate only when forced.** Default down this ladder, not up.
+
+   | Pattern | Use when | Control flow | Failure mode to fear |
+   |---|---|---|---|
+   | **Single-agent tool loop** | One goal, <~15 steps, work fits one context | Model decides each next tool | Infinite loop / drift |
+   | **Code-orchestrated workflow (DAG)** | Steps + order are known *ahead of time* | Your code sequences; model fills each node | Rigid; can't adapt mid-run |
+   | **Multi-agent (planner + subagents)** | One context literally can't hold the work, or independent parallel branches | Orchestrator spawns sub-loops, merges summaries | Coordination cost, lost context at handoff |
+
+   Start with the loop. Move to a coded DAG the moment the step graph is fixed (cheaper, deterministic, testable). Reach for multi-agent **only** when a single context window can't hold the task — never for "it feels big."
+
+2. **Make the loop terminate — two independent kills.** Every loop needs BOTH a semantic stop and a hard cap. One alone is insufficient: the model's "I'm done" can be wrong, and a raw cap truncates good work.
+
+   ```python
+   MAX_STEPS, MAX_USD, t0 = 12, 0.50, time.time()
+   for step in range(MAX_STEPS):                 # hard cap (anti-infinite-loop)
+       msg = model(messages, tools)
+       if msg.stop_reason == "end_turn":         # semantic stop: model emits final, no tool call
+           return msg.text
+       result = run_tool(msg.tool_call)          # exactly one tool per turn keeps it auditable
+       messages += [msg, tool_result(result)]
+       if spent_usd() > MAX_USD or time.time()-t0 > 120:   # budget / wall-clock guard
+           return escalate("budget exceeded", messages)
+   return escalate("max steps reached", messages)   # NEVER silently return partial as success
+   ```
+   Also detect a **no-progress loop**: hash `(tool_name, args)`; if the same call repeats ≥2× with no state change, break and replan — don't wait for MAX_STEPS.
+
+3. **Carry state in an explicit scratchpad — not the raw message list.** The growing transcript is not memory; it's noise that costs tokens and dilutes the goal. Keep a small structured state object the loop reads/writes every turn:
+   ```json
+   {"goal": "<one immutable sentence>", "facts": [...], "open_questions": [...],
+    "done": ["fetched X", "parsed Y"], "next": "draft summary", "artifacts": {"pr_url": null}}
+   ```
+   Re-inject `goal` + `next` into the prompt **every step** (anti-drift re-grounding). When the transcript grows large, summarize old turns into `facts`/`done` and drop the raw tool dumps — keep state, discard chatter.
+
+4. **Verify each step's output before continuing — gate, don't trust.** After every tool result, check it actually advanced the goal *before* the model plans the next move. Cheapest sufficient check wins:
+   - Schema/shape check on tool output (parses? non-empty? expected fields?) — pure code, no model.
+   - Goal-relevance check: "does this result move us toward `goal`, or sideways?" If sideways → discard and re-ground, don't append it as progress.
+   - For generated artifacts (code, SQL, configs): run the real check (compile/lint/`pytest`/dry-run), not a model's self-assessment. A failing check feeds back into the loop as a tool result.
+
+5. **Retry then replan on tool failure — distinguish transient from logical.** Tool error ≠ retry-forever.
+   - **Transient** (timeout, 429, 5xx): bounded retry with backoff — but that's transport reliability; delegate it to harden-llm-app-reliability, don't re-implement here.
+   - **Logical** (bad args, "not found", validation reject): do **not** retry the identical call. Feed the error text back as an observation and let the model *replan* (fix args, pick another tool, or revise the plan). Cap replans (≤2) per subgoal; exceeding it → escalate, don't thrash.
+
+6. **Decompose to subagents only when one context can't hold the work — and return summaries, not dumps.** A subagent gets a *narrow* objective, its own fresh context and tool subset, and returns a **compact result** (the answer + key facts + artifact refs), never its raw transcript. The orchestrator merges summaries into parent state. This is the whole point: parallel/large work happens in child contexts so the parent stays lean. If you find yourself piping a subagent's full message history back up, you've defeated it.
+
+7. **Gate irreversible actions behind explicit approval; meter spend.** Classify each tool: read-only / reversible-write / **irreversible** (delete, deploy, send money, email customers, `DROP`). Irreversible tools require a human-approval checkpoint (or a strict policy allowlist) *before* execution — the loop pauses and surfaces the proposed action + args. Track cumulative tokens/$ per run (step 2's `MAX_USD`); a runaway agent is a billing incident. Emit a structured per-step trace (step #, tool, args, result-status, cost) so a stuck run is debuggable after the fact → build-audit-logging.
+
+8. **Prove it on a multi-step harness with machine-checkable success criteria — built before you ship.** A loop that works on one happy-path demo proves nothing. Write the harness first: define each scenario's *success oracle* in code (artifact exists / `pytest` green / expected end-state reached / final answer matches a regex), not a model's "looks good." Cover ≥3 scenarios — one happy path, one designed-to-fail (asserts escalation, never an infinite loop), one with a distractor in tool output (asserts the goal held). Run it in CI on every change to the loop, prompt, or tool set; a passing harness is the only evidence the orchestration is reliable. Spec the checks in the Verify section below.
+
+## Common Errors
+
+- **Stop condition = only "model says done".** The model declares victory early or never. Always pair the semantic stop with a hard `MAX_STEPS` cap.
+- **No max-step / max-cost cap.** One bad plan → infinite tool calls → runaway bill. Both caps are mandatory, and hitting them must escalate, not silently return a partial answer as if it succeeded.
+- **Treating the message list as memory.** Relying on the growing transcript means the goal drowns in tool noise and context blows up. Keep an explicit scratchpad; re-inject the goal every step.
+- **Never re-grounding → drift.** Without re-stating `goal` each turn, a long run quietly migrates to a neighboring task. Inject goal + next-action every step and discard off-goal results.
+- **Retrying a logical error unchanged.** Re-sending the same bad args on a validation failure just burns steps. Transient → backoff retry; logical → replan with the error fed back as an observation.
+- **Subagents returning raw transcripts.** Dumping a child's full history into the parent defeats decomposition and re-bloats the context you spun it off to avoid. Children return summaries + artifact refs only.
+- **Multi-agent when a loop would do.** Coordination overhead, lost context at handoffs, and harder debugging — for work one context could have held. Escalate topology only when forced (step 1).
+- **More than one tool call per turn without isolation.** Parallel tool calls in one turn make the trace ambiguous and ordering bugs invisible. Keep one tool per turn unless the calls are provably independent.
+- **No verification between steps.** Appending an empty/erroring/irrelevant tool result as "progress" compounds garbage across the run. Gate every result before it enters state.
+- **Irreversible action with no approval gate.** The agent deletes/deploys/pays on a hallucinated plan. Classify tools; pause for human approval on irreversible ones.
+- **No per-step trace.** When a run gets stuck you have nothing to debug. Emit structured step records (tool, args, status, cost) from day one.
+
+## Verify
+
+1. **Terminates on success:** a happy-path multi-step task reaches the semantic stop and returns the artifact *before* `MAX_STEPS` — caps are a safety net, not the normal exit.
+2. **Terminates on failure:** force an unsolvable goal → the run hits `MAX_STEPS`/`MAX_USD` and **escalates** (returns a clear "could not complete" + trace), never an infinite loop and never a partial dressed up as success.
+3. **No-progress break:** inject a tool that returns the same value forever → the loop detects the repeated `(tool,args)` and breaks/replans within ≤2 repeats, not at MAX_STEPS.
+4. **Anti-drift:** run a long task with a distractor in tool output → final answer still serves the original `goal`; the off-goal result was discarded, not built upon.
+5. **Replan on logical error:** make a tool reject the first args → the agent fixes args / switches tool and proceeds, and does **not** re-send the identical failing call.
+6. **Budget guard:** set `MAX_USD` low → the run halts and escalates when spend exceeds it; cumulative cost in the trace matches actual usage.
+7. **Approval gate:** an irreversible tool is never executed without the approval checkpoint firing first (assert it pauses and surfaces args).
+8. **Subagent isolation:** parent context size after a subagent task stays bounded — the child returned a summary, not its transcript (check token count, not just correctness).
+9. **Harness:** ≥3 multi-step scenarios with machine-checkable success criteria (artifact exists / check passes / expected state reached) run green in CI, including at least one designed-to-fail case from check 2.
+
+Done = on the multi-step harness the agent finishes happy-path tasks via the semantic stop, every failure/runaway path escalates within the step+budget caps (no infinite loops, no partial-as-success), each step is verified and re-grounded on the goal, irreversible actions are gated, and subagents return summaries — all evidenced by the per-step trace.

package/skills/payments-billing-integration/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: payments-billing-integration
+description: Integrates payment, subscription, and billing flows against a payment provider — hosted/PCI-offloaded checkout and payment-intent surfaces, idempotency-keyed money-mutating calls that survive retries, webhook-driven order/subscription state reconciliation keyed on stored provider event ids, subscription lifecycle (trial/upgrade/downgrade/proration/cancel/dunning), and an append-only ledger of charges, refunds, and credits that reconciles to the provider balance.
+when_to_use: Integrating a payment provider (checkout, PaymentIntents, subscriptions), handling plan changes/proration/cancellations, processing payment webhooks, preventing double-charges, reconciling payment state, or implementing dunning. Distinct from ingest-webhook-secure (verifies the generic signature/replay/dedup of any inbound webhook — this skill drives billing state from those verified events), money-decimal-arithmetic (the rounding/allocation/FX math this skill calls into for totals), and auth-jwt-session (your users' identity, not a PSP charge).
+---
+
+## When to Use
+
+Reach for this when the request mutates money or subscription state through a payment provider (Stripe, Adyen, Braintree, PayPal):
+
+- "Add a checkout / let users pay for X"
+- "Set up subscription billing with monthly/annual plans and a free trial"
+- "Handle upgrade/downgrade with proration" or "cancel at period end vs immediately"
+- "We double-charged a customer / a retry created two charges" — make money calls idempotent
+- "Order shows paid but the webhook said failed" — reconcile state from webhooks, not the redirect
+- "Implement dunning / retry failed renewals / grace period before we revoke access"
+- "Refund or partially refund, issue account credit, keep the ledger auditable"
+
+NOT this skill:
+- Verifying the raw signature, timestamp window, and replay/dedup of the inbound webhook itself → ingest-webhook-secure (this skill consumes an already-verified, deduped event and decides what billing state it changes)
+- Rounding cents, splitting a charge across line items so it sums exactly, banker's rounding, FX triangulation → money-decimal-arithmetic (call into it; don't re-implement allocation here)
+- Authenticating *your* logged-in user before they reach checkout → auth-jwt-session
+- The background worker/queue that processes a handed-off event → message-queue-jobs
+- Storing the PSP secret/webhook signing key → secrets-management
+
+## Steps
+
+1. **Never let raw card data or client-supplied amounts touch your server.** Use a hosted/PCI-offloaded surface so PAN never hits your backend — keeps you in SAQ-A, not SAQ-D.
+
+   | Need | Use | Why |
+   |---|---|---|
+   | Fastest, lowest PCI scope, one-off or sub | **Hosted checkout** (Stripe Checkout / Adyen Drop-in / PayPal Smart Buttons) | provider hosts the card form, redirects back |
+   | Custom in-page UI, still PCI-offloaded | **PaymentIntents + provider Elements/SDK** | card tokenized client-side; you only see a token + intent id |
+   | Recurring | **Subscriptions API** on a saved payment method | provider runs the renewal schedule + retries |
+   | You handle raw PAN | **don't** | SAQ-D, audits, liability — almost never justified |
+
+   The **provider is the source of truth for amount and currency**. Compute the price server-side from your catalog, create the intent server-side with that amount, and ignore any amount the client posts. A client that sends `amount=1` for a $100 cart must still be charged $100.
+
+2. **Every money-mutating call carries an idempotency key — no exceptions.** Charges, captures, refunds, and subscription creates must be safe to retry after a timeout, because "request timed out" does NOT mean "charge didn't happen." Derive the key deterministically from your own intent (e.g. `charge:order_42:attempt_1`), persist it before the call, and reuse the *same* key on retry.
+
+   ```python
+   # Stripe — header makes the create idempotent for 24h
+   intent = stripe.PaymentIntent.create(
+       amount=order.total_minor,          # integer minor units, computed server-side
+       currency=order.currency,           # ISO 4217, lowercased for Stripe
+       customer=order.customer_id,
+       idempotency_key=f"pi:order:{order.id}",   # SAME key on every retry of THIS order
+       metadata={"order_id": order.id},   # your id, so webhooks map back
+   )
+   ```
+   Rules: a new key per *logical* operation, the same key across *retries* of that operation. Never reuse a key for a different amount (providers return a conflict/error). Generating a fresh UUID per HTTP attempt defeats the entire mechanism — that's how double-charges happen.
+
+3. **Drive durable state from verified webhooks, not the redirect.** The browser redirect/return is a UX hint only — the user may close the tab, the network may drop, or the 3DS challenge may resolve seconds later. Treat the synchronous result as "pending"; flip to `paid`/`active`/`failed` **only** when the matching verified webhook arrives.
+
+   - Inbound verification (signature over raw body, timestamp window, replay/seen-id dedup) is owned by **ingest-webhook-secure** — do that first.
+   - Store the **provider event id** (`evt_…`) in a `processed_events` table with a unique constraint; INSERT-or-skip makes re-delivery a no-op.
+   - Map by **your** id from `metadata` (set in step 2), not by position or amount.
+   - Return `2xx` fast so the provider stops retrying; do the heavy lifting async (hand to message-queue-jobs).
+
+4. **Make state transitions a guarded machine, tolerant of out-of-order delivery.** Webhooks arrive out of order and duplicated; a `payment_failed` can land after a later `payment_succeeded`. Never overwrite blindly — apply only forward transitions.
+
+   ```
+   pending ──succeeded──▶ paid ──refunded──▶ refunded
+      │                    ▲
+      └──failed──▶ failed ─┘ (manual retry / new intent)
+   ```
+   Guard: ignore a `failed` event for an intent already `paid` by a later event; key the decision on the event's intent status + your stored status, not arrival order. Use the event's own timestamp/sequence to drop stale ones.
+
+5. **Subscription lifecycle — pick defaults, don't hand-roll proration.**
+
+   | Change | Default behavior | How |
+   |---|---|---|
+   | Trial → paid | charge at trial end; webhook flips `trialing`→`active` | provider `trial_period_days` + `payment_behavior=default_incomplete` so a failed first charge stays `incomplete` instead of silently activating; gate access on the webhook-confirmed status |
+   | **Upgrade** (to pricier plan) | **immediate**, prorate, charge the difference now | swap price with `proration_behavior=create_prorations` and invoice now |
+   | **Downgrade** | **at period end** (avoid mid-cycle credit/refund churn) | schedule the price change for next period |
+   | Cancel | **at period end** by default (keep paid access they bought); offer immediate+refund only if asked | `cancel_at_period_end=true`; immediate = cancel now + prorated credit/refund |
+   | Quantity/seats | prorate immediately | update quantity, `create_prorations` |
+
+   Let the provider compute proration — it knows the exact second of the cycle. **Gate feature access on the subscription's webhook-confirmed status** (`active`/`trialing`/`past_due`), never on "they clicked upgrade."
+
+6. **Dunning — let the provider retry, you handle the lifecycle.** On a failed renewal the provider enters smart-retries and moves the subscription to `past_due`. Subscribe to `invoice.payment_failed` (notify + start grace), `invoice.payment_succeeded` (recovered → `active`), and `subscription.deleted`/`unpaid` (retries exhausted → revoke). Default grace: keep access through `past_due`, revoke only on terminal `unpaid`/`canceled`. Don't build your own retry timer — you'll race the provider's.
+
+7. **Ledger and invoice correctness — append-only, money math delegated.** Record every money event as an immutable ledger row (`charge`/`refund`/`credit`/`fee` with provider id, minor-unit integer amount, currency, timestamp); never UPDATE an amount in place — post a compensating row. Store amounts as integer minor units or `NUMERIC`, never float. **All splitting/rounding/tax/FX goes through money-decimal-arithmetic** so line items reconcile to the captured total exactly. Refunds reference the original charge and can't exceed it (track remaining refundable). Reconcile the ledger sum against the provider's balance/payout for each charge.
+
+8. **Periodically reconcile against the provider** — webhooks get missed (endpoint down, dropped delivery). Run a scheduled job that lists provider charges/subscriptions since the last cursor and repairs any local row that drifted (missing `paid`, stale `active`). The provider is authoritative; your DB is a cache that must converge.
+
+## Common Errors
+
+- **Acting on the redirect instead of the webhook.** User bounces before the success URL → order stuck `pending` though they paid; or the redirect fires before the charge settles → premature fulfillment. Fulfill on the verified webhook only.
+- **Fresh idempotency key per HTTP retry.** A timeout retried with a new key creates a second charge. Key must be deterministic per logical operation and identical across retries.
+- **Trusting the client amount/currency.** Always compute price server-side from your catalog; the client value is display-only and spoofable.
+- **No `processed_events` dedup.** Providers deliver each event at-least-once; processing a redelivered `payment_succeeded` double-fulfills or double-credits. Unique-constrain the provider event id and skip on conflict.
+- **Overwriting state on out-of-order events.** A late `payment_failed` clobbers a `paid` order. Apply forward-only transitions guarded by stored status + event status, not arrival order.
+- **Hand-rolling proration math.** Off-by-cents and wrong on leap/short months. Let the provider prorate; if you must do money math, route it through money-decimal-arithmetic.
+- **Granting access on the click, not the confirmed status.** Failed first charge on a trial → user gets the product free. Gate on webhook-confirmed `active`/`trialing`.
+- **Floating-point money.** `0.1 + 0.2 != 0.3`; totals drift by a cent. Integer minor units or `NUMERIC` only — see money-decimal-arithmetic.
+- **Refund without a remaining-refundable check.** Two partial refunds can exceed the charge or the provider rejects the second. Track refunded-so-far against the original charge.
+- **Slow webhook handler.** Doing DB writes + emails synchronously blows the provider's timeout → it retries → storms. `2xx` fast, process async.
+- **Logging the full PAN / CVV / signing key.** PCI violation and secret leak. Never log card data; keep the webhook signing key in secrets-management.
+- **Testing only the happy path.** Ship without simulating `card_declined`, `insufficient_funds`, 3DS challenge, expired card, or webhook redelivery and you'll discover them in production.
+
+## Verify
+
+1. **Double-charge under retry:** create one PaymentIntent, fire the create twice with the **same** idempotency key (or kill the first mid-flight and retry) → exactly one charge on the provider dashboard, one ledger row.
+2. **Redirect-independent fulfillment:** complete a test payment but **don't** follow the success redirect (close the tab) → the webhook still flips the order to `paid`. Then never deliver the webhook → order stays `pending` (proves you don't fulfill on redirect).
+3. **Webhook dedup:** replay the same `evt_…` (provider "Resend" or `stripe trigger` + manual re-POST) → second delivery is a no-op; one fulfillment, one ledger entry.
+4. **Out-of-order:** deliver `payment_succeeded` then a stale `payment_failed` for the same intent → final state stays `paid`.
+5. **Lifecycle:** in provider test mode run trial→active, upgrade (immediate prorated charge appears), downgrade (applies next period), cancel-at-period-end (access persists to period end) — each confirmed by the corresponding webhook.
+6. **Dunning:** force a renewal decline (`4000000000000341` / provider test card) → subscription `past_due`, grace access holds, then succeed a retry → back to `active`; exhaust retries → access revoked on terminal event.
+7. **Failure paths:** simulate `card_declined`, `insufficient_funds`, expired card, and a 3DS-required card → each yields the correct user-facing error and no partial fulfillment.
+8. **Ledger reconciliation:** for a charge + partial refund, the ledger sum equals the provider's net for that charge; a refund exceeding remaining refundable is rejected.
+9. **Drift repair:** delete a local order row (simulate a missed webhook), run the reconcile job → it re-creates/repairs from the provider.
+
+Done = under retried/duplicated/out-of-order webhooks there is exactly one charge and one fulfillment per order, durable state is driven only by verified+deduped webhooks (never the redirect), the full subscription lifecycle + dunning are exercised in provider test mode, the ledger reconciles to the provider's balance, and every failure path is tested.

package/skills/pin-toolchain-versions/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: pin-toolchain-versions
+description: Pins language/runtime/CLI versions for identical toolchains across machines and CI — a version manager (mise/asdf/Volta/nvm), exact .tool-versions/.mise.toml pins, engines + packageManager via corepack, frozen-lockfile installs, auto-switch on cd, and CI reading the same pin file.
+when_to_use: Version drift across machines or CI ("wrong node/python version"), painful onboarding, or a "works locally, fails in CI" toolchain mismatch. NOT bumping library deps (dependency-upgrade), a containerized env (setup-devcontainer-env), or workspace task orchestration (setup-monorepo-tooling).
+---
+
+## When to Use
+
+Reach for this skill when the problem is **which version of the tool runs**, not which library version is installed:
+
+- "CI uses node 18, my laptop has 20 — build passes locally, fails in CI"
+- "New hire spent a day getting the right Python/Ruby/Go installed"
+- "`pnpm install` produces a different lockfile on the CI runner"
+- "Every machine must resolve the exact same node + package-manager version"
+- A flaky build traced to a runtime/CLI version that differs by host
+
+NOT this skill:
+- Bumping a library/framework dependency and fixing the breakage → dependency-upgrade
+- Reproducibility via a container/devcontainer image → setup-devcontainer-env
+- Wiring up workspace task runners / package-manager workspaces → setup-monorepo-tooling
+- Publishing the resulting package to a registry → publish-package-registry
+
+## Steps
+
+1. **Pick one manager and commit to it — never run two.** Two managers fighting over `PATH` shims is the #1 cause of "it switched back."
+
+   | Manager | Use when | Notes |
+   |---|---|---|
+   | **mise** | **Default.** Polyglot (node/python/go/ruby/rust/…), fast Rust shims, reads `.tool-versions` *and* `.mise.toml`, runs tasks + env | One tool for every language; drop-in upgrade path from asdf |
+   | asdf | Already standardized on it org-wide | Plugin-per-language, slower; mise reads its files unchanged |
+   | Volta | JS/TS-only repo, want the toolchain pinned *in package.json* | Pins node+pm under `"volta"`, no separate file |
+   | nvm | Minimal, node-only, can't install other tools | `.nvmrc` only, no pm pin, manual `nvm use` |
+
+   Default to **mise** unless the repo is JS-only and you specifically want package.json-embedded pins (Volta).
+
+2. **Pin EXACT versions — never a range, `latest`, or `lts`.** A range re-introduces drift the moment a new patch ships. `.mise.toml`:
+
+   ```toml
+   [tools]
+   node   = "20.18.1"
+   python = "3.12.7"
+   pnpm   = "9.15.0"
+   ```
+   Or `.tool-versions` (asdf/mise compatible):
+   ```
+   node 20.18.1
+   python 3.12.7
+   pnpm 9.15.0
+   ```
+   Full `MAJOR.MINOR.PATCH`. `node = "20"` or `"lts"` resolves differently on a machine that synced its index yesterday vs today — that defeats the purpose.
+
+3. **Pin the package manager too — runtime alone is not enough.** A pinned node with a floating pnpm still produces different lockfiles. Declare both in `package.json` and let corepack enforce it:
+
+   ```jsonc
+   {
+     "packageManager": "pnpm@9.15.0",            // corepack pins the exact pm
+     "engines": { "node": "20.18.1", "pnpm": "9.15.0" }
+   }
+   ```
+   `corepack enable` makes the `pnpm`/`yarn` shim resolve that exact version. Add `engine-strict=true` to `.npmrc` so an out-of-range node **errors** instead of warning. (Volta users: put `"volta": { "node": "20.18.1", "pnpm": "9.15.0" }` in package.json instead — it owns both.)
+
+4. **Commit the lockfile and install frozen in CI.** Pinned tools are wasted if installs still resolve fresh versions. Commit `pnpm-lock.yaml` / `package-lock.json` / `poetry.lock` / `Cargo.lock`, and in CI use the **frozen** install that fails on any drift, never re-resolves:
+
+   | PM | Local install | CI (must fail on drift) |
+   |---|---|---|
+   | pnpm | `pnpm install` | `pnpm install --frozen-lockfile` |
+   | npm | `npm install` | `npm ci` |
+   | yarn (berry) | `yarn install` | `yarn install --immutable` |
+   | poetry | `poetry install` | `poetry install` after `poetry lock --check` |
+   | cargo | `cargo build` | `cargo build --locked` |
+
+5. **Auto-switch on `cd` so nobody runs the wrong version by hand.** Hook the manager into the shell once: append `mise activate zsh` (or `bash`/`fish`) to the rc file; nvm users add `.nvmrc` auto-use logic. Entering the repo now selects the pinned tools automatically — no `nvm use`, no stale shell. Run `mise install` once to materialize the versions and `mise trust` to allow the repo's config.
+
+6. **Make CI read the SAME pin file — never retype versions in YAML.** A hardcoded `node-version: 20` in the workflow is a second source of truth that silently drifts. GitHub Actions:
+
+   ```yaml
+   # Option A: native setup reads the pin file directly
+   - uses: actions/setup-node@v4
+     with:
+       node-version-file: '.tool-versions'   # or .nvmrc / package.json
+   - uses: actions/setup-python@v5
+     with:
+       python-version-file: '.tool-versions'
+
+   # Option B (polyglot, simplest): let mise install everything
+   - uses: jdx/mise-action@v2                 # reads .mise.toml / .tool-versions
+   ```
+   `mise-action` is cleanest when you pin >2 languages — one step, the same file the dev uses.
+
+7. **Go hermetic only when "same versions" isn't enough.** A version manager pins the tool but still links the host's system libraries (openssl, glibc), so two "same node" builds can still differ. For bit-for-bit reproducibility (security/compliance), use **Nix flakes** (`flake.nix` + `flake.lock`, `nix develop`) or **devbox** (`devbox.json`, mise-like UX over Nix). Reserve this for projects that genuinely need it — it's heavier and steeper than mise.
+
+## Common Errors
+
+- **Pinning a range or `latest`/`lts`.** `node = "20"` resolves to different patches over time and across machines. Always full `MAJOR.MINOR.PATCH`.
+- **Pinning the runtime but not the package manager.** Floating pnpm/yarn/npm produces divergent lockfiles even on identical node. Pin via `packageManager` + corepack.
+- **Two managers installed (nvm + mise, or asdf + Volta).** Their `PATH` shims clash and one wins nondeterministically per shell. Pick one; uninstall the other's shell hook.
+- **`engine-strict` not set, so `engines` is just a warning.** npm ignores an `engines` mismatch by default. Set `engine-strict=true` in `.npmrc` to make it a hard error.
+- **CI hardcodes the version in YAML.** `node-version: 20` drifts from the repo's pin file the day someone bumps one and not the other. Use `node-version-file:` / `mise-action`.
+- **Non-frozen install in CI.** Plain `npm install` / `pnpm install` re-resolves and can pick newer deps than the lockfile. Use `npm ci` / `--frozen-lockfile` / `--immutable` / `--locked`.
+- **Forgot `corepack enable`.** Then the `pnpm` on PATH is whatever was globally installed, ignoring `packageManager`. Enable corepack locally and in CI before install.
+- **Lockfile not committed (or in `.gitignore`).** Frozen install has nothing to enforce against. Commit every lockfile.
+- **`.mise.toml` not trusted on a fresh clone.** mise refuses untrusted config and silently skips it. Run `mise trust` (or set `MISE_TRUSTED_CONFIG_PATHS`) in onboarding/CI.
+- **Pinning the tool but using system libs.** A "same node version" build still differs if it links a different openssl. If that bites you, go hermetic (Nix/devbox), not just a version manager.
+
+## Verify
+
+1. **Pin file is exact:** `grep -E '[0-9]+\.[0-9]+\.[0-9]+' .mise.toml .tool-versions package.json` shows full triples — no bare majors, no `latest`/`lts`/`*`.
+2. **Single source of truth:** the version in the pin file, `package.json` `engines`/`packageManager`, and the CI workflow all match — no hardcoded version in YAML that diverges from the file.
+3. **Clean machine A:** fresh clone → `mise install && corepack enable` → `node -v`, `python -V`, `pnpm -v` print the pinned versions with zero manual selection.
+4. **Clean machine B (or container):** repeat step 3 on a second OS/host → identical version strings.
+5. **CI parity:** the CI job logs the same `node -v`/`pnpm -v` as the two machines (read the pin file via `setup-*` `version-file` or `mise-action`).
+6. **Frozen install holds the line:** bump a dep without updating the lock → `npm ci` / `pnpm install --frozen-lockfile` **fails** (drift is rejected, not silently resolved).
+7. **Auto-switch works:** `cd` out of the repo and back → the active `node`/`python` flips to the pinned versions with no manual command.
+8. **engine-strict bites:** temporarily set a wrong node in the pin file → install **errors** on the mismatch instead of warning.
+
+Done = two clean machines and CI all print identical tool + package-manager versions resolved from one committed pin file, the frozen install fails on any lockfile drift, and switching is automatic on `cd`.