wotann 0.5.0

package/skills/think-in-code.md

@@ -0,0 +1,147 @@
+---
+name: think-in-code
+description: Replace bulk reads/scans with one sandboxed script — only the console.log result enters context, achieving 10-100x token reduction on aggregate ops
+context: fork
+paths: []
+---
+
+# Think in Code
+
+The default agent loop reads files, then makes a decision. For aggregate operations — "count failures across 200 logs," "find all callers of `foo`," "diff two configs," "summarize 50 markdown files" — that's the wrong loop.
+
+The right loop: write one sandbox script, run it, read only the script's output. The 200 files never enter your context. The 50 markdown blobs never enter your context. Just the answer.
+
+## When to use
+
+If your next action is one of these, switch to think-in-code:
+
+- "Read these 20 files and tell me which ones contain X."
+- "Aggregate the cost over the last 100 sessions."
+- "Find all functions that call `foo` and summarize their callers."
+- "Compare these two JSON configs."
+- "Sum the line counts for every TypeScript file under src/."
+- "Build a frequency table of error messages from these logs."
+- "Scan tests/ and tell me which test files have the longest setup."
+
+## When NOT to use
+
+If your next action requires understanding context — refactoring code, writing a new function, making a design decision — read the files normally. Think-in-code only helps for *aggregation*, not *comprehension*.
+
+## Workflow
+
+### 1. State the question precisely
+
+Bad: "What's the deal with our cost tracker?"  
+Good: "Across the last 1000 records in `~/.wotann/cost-events.jsonl`, what's the median cost-per-call by provider?"
+
+### 2. Write a script that prints only the answer
+
+```js
+// sandbox.run("aggregate.js")
+import { readFileSync } from 'node:fs';
+const lines = readFileSync(`${process.env.HOME}/.wotann/cost-events.jsonl`, 'utf8').trim().split('\n');
+const recent = lines.slice(-1000).map(l => JSON.parse(l));
+const byProvider = {};
+for (const r of recent) (byProvider[r.provider] ??= []).push(r.cost);
+const median = arr => { const s = [...arr].sort((a,b) => a-b); return s[Math.floor(s.length/2)]; };
+const result = Object.fromEntries(Object.entries(byProvider).map(([p, costs]) => [p, median(costs).toFixed(4)]));
+console.log(JSON.stringify(result, null, 2));
+```
+
+The agent reads ONLY the JSON output (~150 chars). Without this skill, the agent would have grep'd, read each match, then aggregated in-context — burning ~50,000 tokens on the same answer.
+
+### 3. Run via sandbox
+
+`sandbox.run` (TypeScript daemon RPC) or `wotann sandbox run script.js` (CLI) — same sandbox, same outputs.
+
+### 4. Iterate on the script, not your context
+
+If the answer is wrong/incomplete, fix the script. Each iteration costs ~150 chars of round-trip — not 50K of file content. You can iterate 10 times for the cost of one full-context read.
+
+## Output discipline
+
+The script's `console.log` is the *only* thing that enters context. Therefore:
+
+- Print structured JSON, not free-form text. The agent re-parses it cleaner than prose.
+- Print *only* the answer; no debug, no progress.
+- If you need progress for the user, print it to stderr (`console.error`) — by default, sandboxes don't stream stderr to the agent.
+
+## Patterns
+
+### Pattern 1: Aggregate over many files
+
+```js
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+function* walk(dir) {
+  for (const e of readdirSync(dir)) {
+    const p = join(dir, e);
+    if (statSync(p).isDirectory()) yield* walk(p);
+    else yield p;
+  }
+}
+let total = 0;
+for (const p of walk('src')) if (p.endsWith('.ts')) total += readFileSync(p, 'utf8').split('\n').length;
+console.log(JSON.stringify({ totalLines: total }));
+```
+
+### Pattern 2: Find callers of a function (better than grep+read)
+
+Use `execFileNoThrow` from the WOTANN utils to safely run git from the sandbox script:
+
+```js
+import { execFileNoThrow } from '../utils/execFileNoThrow.js';
+const r = await execFileNoThrow('git', ['grep', '-nE', String.raw`\bfoo\(`, '--break', '--heading']);
+const byFile = {};
+for (const line of r.stdout.split('\n').slice(0, 200)) {
+  const m = line.match(/^([^:]+):(\d+):/);
+  if (m) (byFile[m[1]] ??= []).push(parseInt(m[2]));
+}
+console.log(JSON.stringify(byFile, null, 2));
+```
+
+### Pattern 3: Compare two large objects
+
+```js
+import { readFileSync } from 'node:fs';
+const a = JSON.parse(readFileSync('configA.json'));
+const b = JSON.parse(readFileSync('configB.json'));
+function diff(a, b, path = '') {
+  const out = [];
+  const keys = new Set([...Object.keys(a ?? {}), ...Object.keys(b ?? {})]);
+  for (const k of keys) {
+    const pa = a?.[k], pb = b?.[k];
+    if (typeof pa === 'object' && typeof pb === 'object') out.push(...diff(pa, pb, `${path}.${k}`));
+    else if (pa !== pb) out.push({ path: `${path}.${k}`, a: pa, b: pb });
+  }
+  return out;
+}
+console.log(JSON.stringify(diff(a, b), null, 2));
+```
+
+### Pattern 4: Process logs into a frequency table
+
+```js
+import { readFileSync } from 'node:fs';
+const lines = readFileSync('app.log', 'utf8').split('\n');
+const errors = {};
+for (const l of lines) {
+  const m = l.match(/ERROR (\w+):/);
+  if (m) errors[m[1]] = (errors[m[1]] ?? 0) + 1;
+}
+const top10 = Object.entries(errors).sort((a, b) => b[1] - a[1]).slice(0, 10);
+console.log(JSON.stringify(Object.fromEntries(top10), null, 2));
+```
+
+## Telemetry
+
+WOTANN's telemetry tracks `tokensSavedByThinkInCode` per session. After a session, run `wotann context report` to see the savings — typical aggregation tasks hit 50-95% reduction.
+
+## Anti-patterns
+
+- **Don't think-in-code for tasks requiring synthesis.** "Refactor this function" requires understanding the code, not aggregating it.
+- **Don't print the entire dataset.** That defeats the purpose.
+- **Don't write a 500-line script when 10 lines work.** This skill is about minimizing the agent's *input*, not minimizing the script's elegance.
+- **Don't stop at the first run.** If the answer is wrong, iterate the script — each iteration is cheap.
+- **Don't switch back to in-context reads after the script returns.** That re-loses what you saved.
+- **Always use `execFileNoThrow` from `src/utils/execFileNoThrow.ts` for shelling out.** `child_process.exec` shell-escapes user input poorly and is a command-injection risk on untrusted input. The WOTANN sandbox blocks raw `exec`.

package/skills/trace-analysis.md

@@ -0,0 +1,65 @@
+---
+name: trace-analysis
+description: Evidence-driven causal tracing to find the real root cause
+context: main
+paths: []
+---
+
+# Trace Analysis
+
+## When to Use
+- Something broke and the cause is not obvious from the error.
+- The easy explanation feels too easy; you suspect a deeper cause.
+- Reviewing an incident post-mortem before sign-off.
+- Multiple independent symptoms appear together.
+- A "working code" suddenly stops working after no apparent change.
+
+## Rules
+- Separate **observation** from **interpretation** — write symptoms as plain facts first.
+- Generate at least three competing hypotheses before committing to any one.
+- Each hypothesis needs both confirming AND disconfirming evidence.
+- Follow the data, not the control flow. Where did the wrong value come from?
+- Trace from symptom to cause, then back forward once to confirm the chain.
+- If every hypothesis survives, you lack evidence — collect more, don't guess.
+
+## Patterns
+- **Five whys**: ask "why" five times, but stop when you reach a system-level cause.
+- **Bisection**: git bisect across commits, binary search over configuration.
+- **Differential analysis**: compare a working and a broken case, observe the delta.
+- **Fault-tree analysis**: top-down decomposition of a failure into component faults.
+- **Post-mortem format**: timeline → detection → contributing factors → root cause → action items.
+
+## Example
+```markdown
+# Trace: WebSocket reconnect storm
+
+## Observation
+At 14:02 UTC, 3,200 clients reconnected within 10s after daemon restart.
+
+## Hypotheses
+1. Clients lack exponential backoff → all hit at t+1s.
+2. LB stickiness expired and redirected → reconnect cascade.
+3. JWT expiry aligned with restart window → all refreshed simultaneously.
+
+## Evidence
+- (1) confirmed: client code uses fixed 1s retry (git blame L42).
+- (2) disconfirmed: LB logs show no rebalance event.
+- (3) disconfirmed: token logs show staggered issuance.
+
+## Root cause
+Fixed 1s retry on clients. Ship v1.3 with exponential backoff + jitter.
+```
+
+## Checklist
+- [ ] Symptoms recorded with timestamps and quantities.
+- [ ] At least three hypotheses considered.
+- [ ] Each hypothesis has both supporting and opposing evidence.
+- [ ] Root cause is system-level, not "developer X made a typo".
+- [ ] Action items are specific, owned, and dated.
+
+## Common Pitfalls
+- **Blaming a person** — the system let the person do the wrong thing.
+- **Stopping at the first plausible cause** — almost always wrong.
+- **Confirmation bias** — looking only for evidence that fits.
+- **Vague root cause** ("flakiness") that doesn't point to a fix.
+- **Skipping the timeline** — order of events matters.

package/skills/tree-search.md

@@ -0,0 +1,21 @@
+---
+name: tree-search
+description: Parallel hypothesis exploration for complex bugs (4+ causes)
+context: fork
+paths: []
+---
+# Tree Search (BFTS)
+## When to Use
+- Bug has 4+ possible root causes.
+- Linear debugging has failed 3+ times.
+- The fix requires exploring multiple code paths simultaneously.
+## Process
+1. Generate hypothesis tree (root = symptom, branches = possible causes).
+2. Score each branch by likelihood (prior probability).
+3. Explore highest-scored branch first (best-first search).
+4. If branch is ruled out, backtrack and explore next.
+5. Parallelize: assign each branch to a separate subagent.
+## Rules
+- Each branch gets its own fresh context (no pollution).
+- Time-box each exploration (max 5 minutes per branch).
+- Aggregate findings from all branches before deciding.

package/skills/turing-pyramid.md

@@ -0,0 +1,113 @@
+---
+name: turing-pyramid
+description: Andrej Karpathy's 5-layer hierarchy of agent capabilities (sense, understand, plan, act, reflect). Use when designing a new agent capability or debugging why an agent cannot complete a task.
+type: cognitive-framework
+source: openclaw
+---
+
+# Turing Pyramid — Agent Capability Hierarchy
+
+A diagnostic and design framework for agent capability. Inspired by Andrej Karpathy's
+formulation of agent intelligence as a strict hierarchy of layered competencies. An
+agent that fails at task X almost always fails at the LOWEST layer that is broken,
+not the highest. Diagnose top-down; build bottom-up.
+
+## The Five Layers
+
+```
+Layer 5: REFLECT  — "what did I learn from running this?"
+Layer 4: ACT      — "carry out the chosen action"
+Layer 3: PLAN     — "decide what to do next"
+Layer 2: UNDERSTAND — "what does the input mean?"
+Layer 1: SENSE    — "what raw signals are present?"
+```
+
+Each upper layer DEPENDS on the layer below it. A perfect Layer-3 planner with a
+broken Layer-1 sensor produces confidently wrong plans. A perfect Layer-4 actor
+with a broken Layer-3 planner produces fast nonsense.
+
+## When to invoke
+
+- Designing a new agent capability — walk down the pyramid to enumerate every layer the new feature requires
+- Debugging "why can't the agent finish this task?" — walk UP the pyramid; the first broken layer is the answer
+- Code-reviewing an autonomous agent — verify each layer is testable and tested
+- Writing a behavioral spec — split the spec into 5 layer-scoped sub-specs
+- Triaging a production failure — classify the failure by the layer it surfaced from
+
+## Process
+
+### Diagnostic Mode (debugging a broken agent)
+
+1. Reproduce the failure with verbose tracing on
+2. Inspect the trace top-down (most recent action first)
+3. For each layer, ask the diagnostic question:
+   - **Layer 5 — Reflect**: did the agent record what just happened?
+   - **Layer 4 — Act**: did the action match what was planned?
+   - **Layer 3 — Plan**: was the plan reasonable given the understanding?
+   - **Layer 2 — Understand**: did the agent correctly interpret the input?
+   - **Layer 1 — Sense**: did the right raw signals reach the agent at all?
+4. The first NO is the bug. Fix that layer. Re-run.
+5. NEVER fix a higher layer when a lower layer is broken — the fix will leak.
+
+### Design Mode (building a new capability)
+
+1. Write a one-line capability statement: "the agent can do X"
+2. For each layer, write the layer-scoped sub-requirement:
+   - Layer 1: which inputs/files/streams must be sensed?
+   - Layer 2: what schema/structure must be parsed from those inputs?
+   - Layer 3: what decision rule chooses an action from the parsed input?
+   - Layer 4: what action surface (file edits, shell calls, API calls) must be reachable?
+   - Layer 5: what gets recorded so the next iteration can improve?
+3. Build BOTTOM-UP. Layer 1 first. Each layer ships with a test before moving up.
+4. Reject any feature that skips a layer — skipping = future bug.
+
+## Examples
+
+### Example 1 — debugging a stuck agent
+
+User report: "the agent says it ran the tests but the test file wasn't even imported."
+
+Walk up the pyramid:
+- Layer 5: trace shows "tests passed". Reflect layer says success.
+- Layer 4: the bash invocation in the trace is `vitest run nonexistent.test.ts`. Action ran fine.
+- Layer 3: plan picked the wrong test file. Plan layer is buggy.
+- Layer 2: understand layer parsed user request as "run tests for the new feature".
+- Layer 1: but the new feature's test file is in a sibling directory the agent never sensed.
+
+Conclusion: Layer 1 (sense) failed. The agent's working-set didn't include the sibling
+directory, so its understand and plan layers couldn't possibly know about the right
+test file. Fix the SENSE layer (broaden the file walker), not the PLAN layer.
+
+### Example 2 — designing the Editor capability
+
+Capability: "the agent can edit a TSX file in the IDE-style Editor pane".
+
+- Sense: tail the file's bytes from disk; subscribe to filesystem events
+- Understand: parse the TSX into an AST, locate the symbol the user named
+- Plan: choose between insert / replace / delete based on the user's intent
+- Act: emit the edit through the Editor's text-buffer API; assert the resulting AST is valid
+- Reflect: log the diff + LSP diagnostics; if compilation broke, surface for review
+
+This decomposition reveals you cannot ship the Editor feature without an LSP integration
+(needed by both Understand and Reflect). That's a useful constraint to surface BEFORE
+you start coding the edit-applying code in isolation.
+
+## Anti-patterns
+
+- "Polishing the prompt" when the actual bug is at Layer 1 (the right file isn't in context)
+- Adding more reflection logic when the agent's understand layer is producing wrong parses
+- Designing top-down ("first I'll plan how the agent decides") and discovering at integration time that the sense layer is missing entirely
+- Treating the layers as parallel — they are STRICTLY hierarchical
+
+## Stopping criteria
+
+- Every layer is testable in isolation
+- Every layer has at least one passing test that proves it works
+- A failure at any layer is observable in the trace (no silent failures)
+- The capability ships with a runbook that maps user-visible failures to layer-scoped checks
+
+## Provenance
+
+Karpathy framing of agent intelligence as layered hierarchy. Ported into WOTANN as a
+reusable diagnostic skill so any agent debugging session can ask "what layer broke?"
+before guessing.

package/skills/typescript-deep.md

@@ -0,0 +1,70 @@
+---
+name: typescript-deep
+description: Pocock-style deep TypeScript patterns — branded types, discriminated unions, conditional types, template literal types, and exhaustiveness checks. Invoke when designing types for new APIs, modeling domain primitives, or refactoring `any`-laden code into precise types. Pairs with the existing typescript-pro skill.
+type: workflow
+---
+
+# TypeScript Deep — Type-Level Patterns
+
+The shallow TypeScript answer is "use a type alias". The deep answer is to make invalid states unrepresentable. This skill covers the patterns that turn TypeScript from a linter into a compile-time correctness check.
+
+## When to invoke
+
+- Designing a new public API where misuse should be a compile error, not a runtime bug.
+- Modeling domain primitives (UserId, Email, Cents) where mixing them up is a real risk.
+- Refactoring code that passes `string` everywhere into something the compiler can verify.
+- Writing utility types that future callers will compose with.
+
+## Core patterns
+
+### Branded types
+Prevent string-typed primitives from being interchangeable. A `UserId` and a `PostId` are both strings at runtime, but at compile time they should never be assignable to each other.
+
+```pseudo
+type Brand<T, B> = T & { readonly __brand: B }
+type UserId = Brand<string, "UserId">
+type PostId = Brand<string, "PostId">
+```
+
+Construct via a single factory function — never cast directly. The brand is the entire point: lose the factory, lose the guarantee.
+
+### Discriminated unions
+Model state machines with a `kind` (or `type`, or `_tag`) field. Each member of the union carries a different payload, and `switch (state.kind)` becomes exhaustive.
+
+```pseudo
+type Loading = { kind: "loading" }
+type Loaded = { kind: "loaded"; data: User }
+type Error_ = { kind: "error"; message: string }
+type State = Loading | Loaded | Error_
+```
+
+Pair with an exhaustiveness check (a `never`-typed default branch) so adding a new state is a compile error everywhere a switch lives.
+
+### Conditional types
+`T extends U ? A : B` lets a generic produce different types based on its input. Use sparingly — they are hard to read. Best for: stripping null, extracting return types, mapping over tuple types.
+
+### Template literal types
+`` `user-${string}` `` and `` `${Method} /${Path}` `` let you encode string formats at the type level. Useful for: route IDs, event names, format strings.
+
+### Mapped types
+`{ [K in keyof T]: ... }` rewrites every key of a type. Combine with `as` clauses for key remapping (`as `prefix-${K}``).
+
+## Anti-patterns
+
+- **`any` as escape hatch**: every `any` is a hole in the type system. Use `unknown` and narrow.
+- **Type assertions over guards**: `x as Foo` is a lie to the compiler. Write a `isFoo(x): x is Foo` guard instead.
+- **Overusing conditional types**: if a type is unreadable, it is a maintenance hazard. Extract a named alias.
+- **Optional everywhere**: `field?: T` proliferates `undefined` checks downstream. Make it required and nullable, or split the type.
+
+## Reference completeness
+
+Before changing a public type signature:
+1. Search for ALL callers (`grep -r "<TypeName>"`).
+2. Update every consumer in the same change.
+3. Add a regression test that locks in the new shape.
+
+## Related
+
+- `typescript-pro` — broader TS coverage, less type-theory-heavy
+- `api-patterns` — when the type design is for an API contract
+- `mattpocock/skills` — deeper pattern catalog (in awesome-imports)

package/skills/typescript-pro.md

@@ -0,0 +1,33 @@
+---
+name: typescript-pro
+description: TypeScript strict mode, generics, type-level programming, no any
+context: main
+paths: ["**/*.ts", "**/*.tsx"]
+requires:
+  bins: ["node", "npx"]
+---
+
+# TypeScript Pro
+
+## Rules
+- NEVER use `any`. Use `unknown` + type guards, generics, or explicit types.
+- Enable and respect `strict: true`, `noUncheckedIndexedAccess: true`.
+- Prefer `readonly` properties and `ReadonlyArray`/`ReadonlyMap`/`ReadonlySet`.
+- Use discriminated unions over optional fields for state machines.
+- Use `satisfies` for type-safe object literals without widening.
+- Use template literal types for string patterns.
+
+## Patterns
+- Error handling: Use `Result<T, E>` pattern or typed `Error` subclasses.
+- Immutability: Return new objects from functions, never mutate parameters.
+- Type narrowing: Use `in` operator, `instanceof`, and custom type guards.
+- Branded types: `type UserId = string & { readonly __brand: unique symbol }`.
+
+## Anti-Patterns
+- `as any` or `@ts-ignore` — fix the types instead.
+- `Object`, `Function`, `{}` as types — use specific interfaces.
+- Excessive type assertions (`as`) — usually means wrong architecture.
+- Enums — use `const` objects with `as const` instead.
+
+## Verification
+After every change: `npx tsc --noEmit`. Fix ALL errors before moving on.

package/skills/ultraplan.md

@@ -0,0 +1,61 @@
+---
+name: ultraplan
+description: Extended-thinking planning for complex WOTANN architecture and migration problems
+context: fork
+paths: []
+---
+
+# ULTRAPLAN
+
+## When to Use
+
+- Architecting a new WOTANN subsystem that crosses 5+ existing modules.
+- Rewriting a critical path (e.g., `src/providers/router.ts`) with irreversible consequences.
+- Planning a phase of the mega-plan (`~/.claude/plans/glistening-wondering-nova.md`).
+- Designing a migration (SQLite schema, memory taxonomy, provider API v2).
+- Deciding between competing architectures with long-term lock-in (TurboQuant vs. alternatives).
+
+## Rules
+
+- Offload planning to the most capable model (Opus + 1M context) — never a smaller one.
+- Allocate extended thinking budget (>=10K tokens, up to 50K for mega-plans).
+- Each phase must declare acceptance criteria and a rollback plan.
+- Adversarially review the plan before execution (dispatch `critic` agent).
+- Record the plan to `plans/<slug>.md` for later session recovery.
+- Never start implementation until the plan has been reviewed and approved.
+
+## Patterns
+
+- **Phase decomposition**: split into 3-7 phases, each with its own checkpoints.
+- **Dependency graph**: list upstream/downstream for every phase to unlock parallelism.
+- **Acceptance criteria**: each phase has a measurable "done" signal.
+- **Rollback plan**: every phase has an inverse operation documented.
+- **Review loop**: `planner` -> `critic` -> revise -> `critic` again until green.
+
+## Example
+
+```
+ULTRAPLAN: Migrate WOTANN memory from JSONL to SQLite+FTS5
+  budget: 25K thinking tokens
+  phases:
+    1. Design schema (depends: none)          accept: schema diff reviewed
+    2. Build migration tool (depends: 1)      accept: dry-run on sample data
+    3. Dual-write adapter (depends: 2)        accept: parity tests pass
+    4. Cutover + verify (depends: 3)          accept: 7 days of shadow reads
+    5. Decommission JSONL path (depends: 4)   accept: feature flag removed
+  rollback: re-enable JSONL reader, flip read path via config flag
+  review: critic agent -> 2 rounds -> approved 2026-04-13
+```
+
+## Checklist
+
+- [ ] Plan written to `plans/<slug>.md`.
+- [ ] Every phase has acceptance criteria and rollback steps.
+- [ ] Dependency graph shows parallel vs. serial phases.
+- [ ] `critic` agent has reviewed and signed off.
+
+## Common Pitfalls
+
+- Skipping acceptance criteria — "done when it feels right" leads to scope drift.
+- Designing only the happy path; a phase without rollback is a one-way door.
+- Starting implementation before `critic` review; rework cost far exceeds planning cost.

package/skills/vue-expert.md

@@ -0,0 +1,71 @@
+---
+name: vue-expert
+description: Vue 3 Composition API, Pinia, Nuxt 3 with TypeScript-first patterns
+context: fork
+paths: ["**/*.vue"]
+requires:
+  bins: ["node"]
+---
+
+# Vue Expert
+
+## When to Use
+
+- Building a Vue 3 app with `<script setup>` + TypeScript.
+- Adding Pinia stores for shared state across routes.
+- Building a Nuxt 3 app with SSR, file-based routing, and server routes.
+- Migrating Options API code to Composition API incrementally.
+- Composing reusable logic via composables (`use*` functions).
+
+## Rules
+
+- Composition API with `<script setup lang="ts">` only; Options API is legacy.
+- Pinia for state (never Vuex); one store per feature.
+- `ref()` for primitives, `reactive()` for objects — don't mix the two for the same value.
+- Typed `defineProps<{ ... }>()` / `defineEmits<{ ... }>()` — no runtime declarations.
+- Use `defineModel()` for two-way binding; avoid prop/emit handshakes.
+- Nuxt: avoid `useState` for secrets; use server-only composables.
+
+## Patterns
+
+- **Composables**: extract reusable reactive logic into `useSomething()` functions.
+- **Provide/inject**: typed with `InjectionKey<T>` for dependency injection.
+- **Teleport**: for modals, tooltips, toasts mounted outside the root DOM tree.
+- **Suspense**: wrap async components for loading boundaries.
+- **Transitions**: `<Transition name="fade">` with CSS-only animations.
+
+## Example
+
+```vue
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+
+const props = defineProps<{ initial?: number }>();
+const emit = defineEmits<{ change: [value: number] }>();
+
+const count = ref(props.initial ?? 0);
+const doubled = computed(() => count.value * 2);
+
+function increment() {
+  count.value += 1;
+  emit('change', count.value);
+}
+</script>
+
+<template>
+  <button @click="increment">{{ count }} (x2 = {{ doubled }})</button>
+</template>
+```
+
+## Checklist
+
+- [ ] All components use `<script setup lang="ts">`.
+- [ ] State lives in Pinia stores, not `provide/inject` for globals.
+- [ ] Props and emits typed with generic declarations.
+- [ ] Composables named `useX` and return reactive values only.
+
+## Common Pitfalls
+
+- Destructuring a `reactive()` object loses reactivity; use `toRefs()` first.
+- Mutating a prop directly; Vue warns, but it still breaks parent-child contracts.
+- Forgetting `.value` when accessing `ref()` outside templates.

package/skills/web-scraper.md

@@ -0,0 +1,35 @@
+---
+name: web-scraper
+description: 6-phase web scraping with anti-bot bypass and validation
+context: fork
+paths: []
+requires:
+  bins: ["node"]
+---
+
+# Web Scraper
+
+## 6-Phase Pipeline
+1. **Recon** — Analyze target site structure, robots.txt, rate limits.
+2. **Stealth** — Set appropriate headers, respect rate limits, use delays.
+3. **Extract** — Parse HTML/JSON, handle pagination, follow links.
+4. **Validate** — Verify extracted data completeness and correctness.
+5. **Protect** — Sanitize data, remove PII if not needed, check legal.
+6. **Report** — Output structured data (JSON, CSV) with metadata.
+
+## Tools (prefer in order)
+1. **Lightpanda** — Fastest headless browser (9x faster, 16x less memory).
+2. **Playwright** — Full browser automation when JS rendering needed.
+3. **fetch/curl** — Simple HTTP when no JS rendering needed.
+
+## Rules
+- ALWAYS respect robots.txt.
+- ALWAYS add delays between requests (1-3 seconds minimum).
+- ALWAYS set a descriptive User-Agent header.
+- NEVER scrape personal data without explicit consent.
+- NEVER overload target servers.
+
+## Error Handling
+- Retry with exponential backoff on 429/503.
+- Rotate User-Agent on repeated blocks.
+- Save checkpoint data to resume interrupted scrapes.