sanook-cli 0.4.0

package/skills/build-etl-pipeline/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: build-etl-pipeline
+description: Designs and implements ETL/ELT pipelines — extract from sources, transform/normalize, load to a warehouse — with idempotency, incremental loads, scheduling, and orchestration patterns.
+when_to_use: When the user wants to build or refactor a data pipeline that moves data between systems — ingest from API/DB/files, transform and load into a warehouse, set up incremental/CDC loads, or structure an Airflow/dbt-style orchestration. Distinct from one-off tabular wrangling: use this for scheduled, multi-source, repeatable pipelines.
+---
+
+## When to Use
+
+Use when the work is a **repeatable, scheduled flow** that moves data from one or more sources into a sink/warehouse — not a one-off transform of a single file. Signals: "ingest from the API every hour", "incremental load", "CDC", "backfill", "dedup on load", "Airflow DAG", "dbt models", "the nightly job".
+
+If it's a single ad-hoc clean/reshape of one dataset with no schedule, that's tabular wrangling, not this skill.
+
+## Steps
+
+1. **Pin the contract before writing code.** Lock down per source: format (JSON/CSV/Parquet/DB rows), grain (one row = ?), natural/business key, and the timestamp you'll use for incrementality (`updated_at`? event time? ingestion time?). Lock down per sink: target table, primary/unique key, partition column, and SLA (freshness target + max runtime). Write these as a short table — every later decision hangs off it.
+
+2. **Choose extraction mode per source — don't default to full reload.**
+   - **Full snapshot**: small/dimension tables, no reliable change marker. Reload whole table each run.
+   - **Incremental (watermark)**: source has a monotonic `updated_at`/`id`. Store last successful high-watermark in a state table/file; next run pulls `WHERE updated_at > :watermark`. Advance the watermark **only after the load commits**, never at extract time.
+   - **CDC**: high-volume mutable tables where you need deletes/updates. Consume a log (Debezium/WAL/binlog) or a change-tracking table; map `op = c/u/d` to upsert/delete.
+   - Always pull with **overlap** (`>=` watermark minus a small lag window, e.g. 5–15 min) to catch rows committed out of clock order, then rely on idempotent load to dedup.
+
+3. **Make extract resumable and bounded.** Paginate/chunk by key range or time window, not `OFFSET` (offset drifts under concurrent writes). Cap page size. Persist a per-window cursor so a crash resumes mid-source instead of restarting from zero. Land raw extracts to a staging/bronze layer first (immutable, partitioned by load date) before any transform — this is your replay buffer.
+
+4. **Transform in a staging layer with explicit schema mapping.** Normalize types and timezones (store UTC). Apply: dedup (keep latest by key + version/`updated_at`), surrogate keys (hash of natural key — stable across reloads, e.g. `md5(coalesce(cols))`), and schema mapping source→target column by column (no `SELECT *` into the warehouse). Handle **late-arriving data**: dimensions arriving after facts → either staging buffer + retry, or an "unknown" placeholder key you backfill later. Keep transforms deterministic so the same input always yields the same output (required for idempotency).
+
+5. **Load idempotently — every run must be safe to re-run.**
+   - Prefer `MERGE`/upsert keyed on the business/surrogate key, or **partition-overwrite** (delete-then-insert the affected partition in one transaction). Never bare `INSERT` from an at-least-once source — it duplicates on retry.
+   - Wrap delete+insert per partition in a transaction so a failure leaves the partition fully old, never half-loaded.
+   - For append-only event sinks, dedup by a unique event id (`INSERT ... ON CONFLICT DO NOTHING`).
+   - **Backfill = the same load path with a date-range param**, not a separate script. Backfill one partition/day at a time so reruns and forward jobs share idempotency guarantees.
+
+6. **Orchestrate with idempotent tasks and explicit deps.** Model as a DAG: `extract → stage → transform → load → validate`. Each task must be retry-safe in isolation. Set bounded retries with exponential backoff + jitter. Make tasks **parameterized by execution window** (the run's logical date), so a backfill of an old date hits exactly that partition. In Airflow, key off `execution_date`/`data_interval`, not `now()`. In dbt, use incremental models with a unique_key and `is_incremental()` filter. Set `max_active_runs` per DAG to avoid two runs racing the same watermark.
+
+7. **Isolate failures and observe.** Route bad rows to a **dead-letter / quarantine** table (with raw payload + error reason) instead of failing the whole batch — but fail loudly if the dead-letter rate crosses a threshold. Emit per-run metrics: rows in/out, rejected count, watermark advanced from→to, runtime. Add freshness + row-count + null-key assertions as a post-load `validate` task that fails the run (e.g. dbt tests, Great Expectations, or plain `SELECT` checks).
+
+## Common Errors
+
+- **Watermark advanced before load committed** → on crash you skip rows permanently. Advance watermark only in the success path, after the load transaction commits.
+- **Non-idempotent reload (bare INSERT) on an at-least-once source** → duplicates on every retry. Use MERGE/upsert or partition-overwrite; key on business/surrogate key.
+- **Half-loaded partition** → reader sees old+new mixed, sums wrong. Delete+insert the partition inside one transaction; don't insert then separately delete.
+- **`OFFSET`-based pagination under concurrent writes** → rows skipped or doubled as the table shifts. Paginate by key/time range with a stored cursor.
+- **No overlap window on incremental pull** → rows committed slightly out of order (clock skew, long transactions) are missed forever. Re-pull a small lag window each run; idempotent load absorbs the overlap.
+- **Schema drift breaks the load silently** → new/renamed/dropped source column. Validate the incoming schema against expected and fail (or quarantine) on mismatch; never `SELECT *` into the warehouse.
+- **Orchestrator uses `now()` instead of the run's logical date** → backfills land in the wrong partition and reruns aren't reproducible. Parameterize every task by execution window.
+- **Late-arriving dimensions create orphan facts** → fact rows point to a key the dim doesn't have yet. Use placeholder/unknown keys + a backfill pass, or buffer-and-retry.
+- **One bad row kills the whole batch** → no progress until manual fix. Dead-letter the row, continue, alert on rate.
+
+## Verify
+
+Run these checks before declaring done — show output, don't assert "it works":
+
+1. **Idempotency**: run the same window twice; row counts and key aggregates are identical the second time (no growth, no dups). `SELECT key, count(*) FROM target GROUP BY key HAVING count(*) > 1` returns zero rows.
+2. **Incrementality**: confirm watermark/state advances only on success — kill the job mid-load, rerun, verify no rows lost and none duplicated.
+3. **Backfill = forward path**: backfill one historical partition and confirm it produces the same shape as a live run for that date.
+4. **Failure isolation**: inject a malformed row; verify it lands in dead-letter and the run still completes (or fails only if over threshold).
+5. **Validation gate**: confirm the post-load assertions (freshness, row count, null-key) actually fail the run when violated — break one deliberately and watch it red.
+6. **Schema drift**: add/rename a source column in a fixture; confirm the pipeline fails or quarantines instead of loading garbage.

package/skills/build-form-validation/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: build-form-validation
+description: Implements type-safe forms with React Hook Form + Zod (or server-action validation) — schemas, field arrays, multi-step flows, and accessible error handling; used when building or fixing forms.
+when_to_use: When the user builds or fixes a form, mentions React Hook Form, Zod, form validation, multi-step/wizard forms, field arrays, or server-action input validation.
+---
+
+## When to Use
+
+Use this skill when building or fixing a form in a React/Next.js codebase — anything touching `react-hook-form`, `zod`, `zodResolver`, field arrays, multi-step/wizard flows, or server-action input validation. This covers the **client form layer**: schema-driven validation, RHF wiring, accessible errors, and the client↔server-action contract.
+
+Not this skill: pure REST/RPC contract or response-shape review (that is API design review). This skill stops at "the action received validated input and returned a typed result."
+
+First, detect the stack before writing code:
+- `grep -r "next" package.json` and check for an `app/` dir → App Router (server actions + `useActionState` available on React 19).
+- Check installed versions: `react-hook-form` v7+, `zod` v3 vs v4 (error API differs), `@hookform/resolvers`.
+- Look for an existing form in the repo and **match its pattern** (UI lib, resolver setup, error component) instead of inventing a new one.
+
+## Steps
+
+1. **One Zod schema = source of truth.** Write the schema once, derive the TS type with `z.infer`, and import the *same* schema on client and server. Never hand-write a parallel `interface`.
+   ```ts
+   // schema.ts — shared
+   export const signupSchema = z.object({
+     email: z.string().email(),
+     password: z.string().min(8),
+     confirm: z.string(),
+   }).refine((d) => d.password === d.confirm, {
+     message: "Passwords must match",
+     path: ["confirm"], // attaches error to the field, not the form root
+   });
+   export type SignupInput = z.infer<typeof signupSchema>;
+   ```
+   For inputs that arrive as strings but mean numbers/dates, use `z.coerce.number()` / `z.coerce.date()` so form values and server `FormData` both parse.
+
+2. **Wire React Hook Form with the resolver.** Use `zodResolver`, set `defaultValues` for *every* field (uncontrolled inputs need them or they switch controlled→uncontrolled mid-edit), and pick a sane `mode`.
+   ```ts
+   const form = useForm<SignupInput>({
+     resolver: zodResolver(signupSchema),
+     defaultValues: { email: "", password: "", confirm: "" },
+     mode: "onTouched", // validate after blur, then re-validate onChange — best UX default
+   });
+   ```
+   - Native inputs (`<input>`, `<select>`): use `{...form.register("email")}`.
+   - Custom/headless components (Select, DatePicker, anything not exposing a ref): wrap in `<Controller name=... control={form.control} render={...} />`. Mixing `register` on a controlled component silently drops values.
+
+3. **Field arrays + nested objects** use `useFieldArray`. Key the rows by `field.id` (RHF's stable id), **never by array index** — index keys corrupt state on remove/reorder.
+   ```ts
+   const { fields, append, remove } = useFieldArray({ control: form.control, name: "items" });
+   // register nested path:
+   {...form.register(`items.${index}.name`)}
+   ```
+   Read nested errors via `form.formState.errors.items?.[index]?.name`.
+
+4. **Multi-step / wizard:** one sub-schema per step; validate only the current step's fields before advancing with `await form.trigger(["fieldA","fieldB"])`. Keep all steps in **one** `useForm` instance (do not remount per step or you lose state). Persist between steps with a single `useForm` + (optionally) `localStorage`/URL state; validate the *full* schema on final submit. Compose with `signupSchema.pick({...})` or `.partial()` per step so the final type stays one source of truth.
+
+5. **Next.js server actions** — validate inside the action, **return** typed errors, do not `throw` for validation:
+   ```ts
+   "use server";
+   export async function signup(_prev: State, formData: FormData): Promise<State> {
+     const parsed = signupSchema.safeParse(Object.fromEntries(formData));
+     if (!parsed.success) {
+       return { ok: false, errors: parsed.error.flatten().fieldErrors };
+     }
+     // ...mutate DB...
+     revalidatePath("/dashboard"); // or revalidateTag — refresh cache after mutation
+     return { ok: true };
+   }
+   ```
+   On the client (React 19): `const [state, action, pending] = useActionState(signup, { ok: false });`. Bind RHF to the action with `<form action={action}>` and `form.handleSubmit` for client-side pre-check, or surface `state.errors` back into RHF via `form.setError`. **Always** re-validate server-side — client validation is UX, not security.
+
+6. **Accessible errors** on every field:
+   - `aria-invalid={!!errors.email}` on the input.
+   - `aria-describedby="email-error"` pointing at the error node; the error node has `id="email-error"` and `role="alert"` (or sits in an `aria-live="polite"` region) so SRs announce it.
+   - Associate a real `<label htmlFor>`; placeholders are not labels.
+   - On failed submit, **focus the first errored field**. RHF does this with `shouldFocusError: true` (default) for registered native inputs; for `Controller`/custom inputs, focus manually in the submit-error handler.
+
+7. **Async validation** (e.g. "username taken"): debounce the check (~300–500ms), and validate server-side too. Either a Zod `.refine(async ...)` (requires `parseAsync`/`safeParseAsync` — `zodResolver` handles this) or `form.setError("username", { message })` after a fetch. Disable submit while `formState.isValidating || isSubmitting` to prevent races.
+
+## Common Errors
+
+- **`defaultValues` missing → "controlled to uncontrolled" warning** and lost values. Always seed every field, including arrays (`{ items: [] }`).
+- **Field array keyed by index** → on `remove(2)` the wrong rows re-render / values shift. Key by `field.id`.
+- **`Controller` value not updating** because the inner component fires a non-standard onChange — map it: `onChange={(v) => field.onChange(v)}`. Don't spread `register` onto a controlled component.
+- **`refine`/`superRefine` error lands on form root, not the field** → user sees no inline message. Set `path: ["confirm"]`.
+- **`z.coerce` forgotten for number/checkbox inputs** → `FormData` gives `"3"`/`"on"`, schema expects `number`/`boolean`, every submit fails validation silently.
+- **Server action `throw` for invalid input** → blows up as an error boundary / 500 instead of inline errors. Use `safeParse` + return.
+- **Forgot `revalidatePath`/`revalidateTag` after mutation** → UI shows stale cached data post-submit even though the DB changed.
+- **Re-mounting `useForm` per wizard step** wipes earlier answers. One instance, conditionally render steps.
+- **Trusting client validation only** — bypassable; the server action must re-`safeParse`.
+- **Zod v3 vs v4 mismatch**: `.flatten()` and the error object shape changed across majors. Check the installed version before copying error-extraction code.
+- **`mode: "onChange"` on a big form** → validates on every keystroke, janky + noisy errors before the user finishes typing. Prefer `onTouched` / `onBlur`.
+
+## Verify
+
+Run these before declaring done — show evidence, not just "fixed":
+
+1. **Type check:** `npx tsc --noEmit` (or the project's typecheck script) passes — confirms `z.infer` and form generics line up.
+2. **Lint:** project ESLint passes on touched files.
+3. **Happy path:** submit valid data → action runs, success state shows, cache revalidates (data refreshes without a hard reload).
+4. **Validation path:** submit each invalid field → inline error appears under the right field, submit is blocked, no 500/error boundary.
+5. **A11y spot-check:** invalid field has `aria-invalid="true"` and `aria-describedby` resolving to a visible error node; first errored field receives focus on failed submit. Verify in the DOM/accessibility tree (e.g. devtools snapshot), not by eye alone.
+6. **Field array / wizard** (if present): add → remove a middle row → values of remaining rows stay correct; advancing a step only validates that step; final submit validates the whole schema.
+7. If a contract or behavior is testable, add/run a unit test on the schema (`safeParse` of good + bad payloads) so the validation can't silently regress.

package/skills/build-office-docs/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: build-office-docs
+description: Generates and edits Office documents (DOCX/PPTX) programmatically from data or templates, including styled reports, tables, headers/footers, tracked changes, and slide decks.
+when_to_use: When the user asks to create or edit a Word document or PowerPoint deck — generate a report, fill a DOCX/PPTX template, mail-merge data into letters/memos, build slides from an outline, or apply tracked-changes edits to an existing .docx.
+---
+
+## When to Use
+
+Trigger this skill when the task produces or modifies a `.docx` or `.pptx` file:
+
+- Generate a Word report/letter/memo from data or a written outline.
+- Fill a DOCX/PPTX **template** that has `{{placeholder}}` fields or named shapes.
+- **Mail-merge** one template over a row set (one output file per row, or one file with repeated sections).
+- Build a slide deck from a structured outline (title + bullets + notes per slide).
+- Edit an **existing** `.docx`: find-replace, insert/restyle tables, add headers/footers/page numbers, or apply **tracked changes**.
+
+Do NOT use this for: plain `.txt`/`.md`/`.csv` output, PDFs (use a PDF/HTML-to-PDF path), or `.doc`/`.ppt` legacy binary formats (convert to OOXML first via LibreOffice `soffice --headless --convert-to docx`).
+
+## Steps
+
+1. **Classify the job along two axes before writing code:**
+   - Format: `docx` (Word) vs `pptx` (PowerPoint). Decide from the request, not the extension alone.
+   - Mode: `from-scratch` (build a new file) · `template` (fill placeholders in an existing file) · `edit-existing` (mutate a real document, preserving its styles).
+   Print the chosen `{format, mode}` before proceeding — the library and approach differ per cell.
+
+2. **Pick the library by {format, mode}. Do not invent a new dependency if one is already in the repo:**
+   - docx, from-scratch / edit-existing → `python-docx`.
+   - docx, template with `{{fields}}`/Jinja loops → `docxtpl` (renders Jinja2 inside a real .docx, keeps styles).
+   - pptx, any mode → `python-pptx`.
+   - Low-level changes these libraries can't express (tracked changes `w:ins`/`w:del`, custom XML, content controls, theme colors) → edit the OOXML directly: a `.docx`/`.pptx` is a **zip** of XML parts (`word/document.xml`, `ppt/slides/slideN.xml`). Unzip, edit XML via `lxml`, re-zip.
+   Confirm the package is installed (`pip show python-docx docxtpl python-pptx`); install into the project env, not globally, if missing.
+
+3. **DOCX — from scratch (`python-docx`):**
+   - Structure with real styles, not manual formatting: `doc.add_heading(text, level=N)`, `doc.add_paragraph(text, style='List Bullet'|'List Number')`. Reuse `doc.styles` / a base template (`Document('template.docx')`) so output inherits the org's fonts and theme.
+   - Tables: `t = doc.add_table(rows, cols)`, set `t.style = 'Light Grid Accent 1'` (must be a style that exists in the doc, else it errors). Cell styling lives on the **run** inside the cell paragraph: `cell.paragraphs[0].add_run(text).bold = True`; widths need `tblLayout` fixed (`t.autofit = False` + set each `cell.width`).
+   - Headers/footers/page numbers: `section.header` / `section.footer`; a page-number field requires a `fldSimple`/`w:instrText PAGE` XML run (`python-docx` has no helper — inject the XML via `run._r.append(...)`).
+   - Images: `doc.add_picture(path, width=Inches(...))`; missing files raise, so check the path first.
+
+4. **DOCX — template fill & mail-merge (`docxtpl`):**
+   - Author the template with Jinja in real Word text: `{{ customer_name }}`, `{% for row in items %}...{% endfor %}` (use `{%tr ... %}` to repeat **table rows**, `{%p ... %}` to repeat paragraphs). Tag names must match the context dict keys exactly.
+   - Render: `tpl = DocxTemplate('tpl.docx'); tpl.render(context); tpl.save(out)`.
+   - Mail-merge = loop the data rows: render one output per row → `out_{i}.docx` (or `_{key}.docx`), OR pass a list into one template and use a `{%tr%}`/`{%p%}` loop for a single combined file. Decide which the user wants up front.
+   - Insert images/rich runs via `tpl.new_subdoc()` / `InlineImage`, not raw strings, so styling survives.
+
+5. **PPTX (`python-pptx`):**
+   - Start from `Presentation('template.pptx')` to inherit master/layouts; `Presentation()` alone gives the default theme only.
+   - Per slide: pick a layout (`prs.slide_layouts[idx]`), `slide = prs.slides.add_slide(layout)`, then fill **named placeholders** by index/type (`slide.placeholders[0].text = title`) — do not assume placeholder 1 is always the body; inspect `[ph.placeholder_format.idx for ph in slide.placeholders]`.
+   - Bullets: write into the body placeholder's `text_frame`, one `paragraph` per bullet, set `paragraph.level` for indent.
+   - Speaker notes: `slide.notes_slide.notes_text_frame.text = notes`.
+   - Charts/tables: `slide.shapes.add_chart(...)` with a `CategoryChartData`, or `add_table(rows, cols, x, y, w, h)`.
+
+6. **Edit-existing without nuking styles:** open the real file, mutate only target nodes. For find-replace in `python-docx`, replace at the **run** level (text can be split across runs — naive `paragraph.text = ...` drops formatting); join/split runs carefully or use a known replace helper.
+
+7. **Tracked changes** are not in `python-docx`'s API — do it at the XML layer: an insertion is a `<w:ins w:author w:date>` wrapping the new run; a deletion wraps the old run in `<w:del>` with the text in `<w:delText>`. Set author/date attributes. Verify Word shows them under Review → Track Changes after opening.
+
+8. **Render to the requested path, then validate (step into ## Verify) before declaring done.** Report the absolute output path and confirm the file opens.
+
+## Common Errors
+
+- **Corrupt file after manual XML edits** — re-zipping with wrong compression/structure, missing `[Content_Types].xml`, or a stray byte breaks the package and Word says "needs repair". Always round-trip through `zipfile` (preserve all parts), and re-open with the library after writing to catch corruption early.
+- **Style does not exist → exception or silent no-op.** `t.style = 'Some Style'` / `add_paragraph(style=...)` only works if that style is defined in the document. Build from a template that contains the style, or add the style definition first. Style names are case- and space-sensitive.
+- **Fonts/styles "not embedded" → output looks wrong on another machine.** OOXML references fonts by name; it does not embed them. If a specific font is required, embed it (`<w:embedRegular>` font part) or restrict to fonts the consumer has. Theme colors only resolve if the theme part is present (another reason to start from a real template).
+- **Merge-field / placeholder mismatch.** A `{{tag}}` with no matching context key renders empty or raises (`jinja2.UndefinedError`); a key with no tag is silently ignored. Diff the template's tag set against the context dict keys before rendering. Word sometimes splits `{{ tag }}` across runs so `docxtpl` can't see it — keep each tag typed in one run (retype it cleanly in Word).
+- **find-replace drops formatting** because Word stores one logical word across multiple `<w:r>` runs. Replacing `paragraph.text` collapses runs and loses bold/italic/links. Operate run-by-run or use a run-aware replacer.
+- **PPTX placeholder index assumption** — layouts differ; index 1 is not always the content body. Always enumerate `slide.placeholders` and match by `placeholder_format.type`/`idx`.
+- **`add_picture`/template path is relative** and the working dir differs at run time → `FileNotFoundError`. Use absolute paths.
+- **Tracked changes invisible** because `w:author`/`w:date` are missing or the run wasn't wrapped in `w:ins`/`w:del` — Word then shows the edit as a normal change. Confirm the wrapping nodes and attributes exist.
+
+## Verify
+
+A generated/edited Office file is done only when ALL hold:
+
+- [ ] The file exists at the reported absolute path and has non-trivial size (> a few KB; a 0-byte or tiny file means the write failed).
+- [ ] **It is a valid OOXML package:** `unzip -l <file>` lists parts including `[Content_Types].xml` and `word/document.xml` (docx) or `ppt/presentation.xml` (pptx) — no zip error.
+- [ ] **It re-opens with the library** without exception: `Document(out)` (docx) or `Presentation(out)` (pptx) loads, and a spot-check reads back expected content (a heading's text, a known cell value, slide count == expected).
+- [ ] For templates/mail-merge: no `{{` / `}}` / `{%` literals remain in the output (`unzip -p <file> word/document.xml | grep -c '{{'` returns 0), and one output file exists per data row when per-row mode was chosen.
+- [ ] For tracked changes: `word/document.xml` contains the expected `<w:ins>`/`<w:del>` nodes with author+date; opening in Word shows them under Review.
+- [ ] If a specific font/style/theme was requested, it is present (style name resolves; theme/font part exists in the zip).
+
+If validation cannot run (no Word/LibreOffice available and the library re-open is the only check), state that the file passed structural+library validation but was not opened in a real Office client.

package/skills/build-react-component/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: build-react-component
+description: Scaffolds production-grade React/Next.js components with proper props typing, server vs client component boundaries, and composition; used when building or restructuring UI components.
+when_to_use: When the user asks to create, scaffold, or restructure a React/Next.js component, page, or layout — especially deciding Server vs Client Component, prop typing, and folder structure.
+---
+
+## When to Use
+
+Use this skill when creating, scaffolding, or restructuring a React/Next.js component, page, or layout. It is most valuable when you must decide Server vs Client Component boundaries, design a typed props contract, or lay out files. Skip it for trivial edits to an existing component (text/className tweaks, prop renames) — just edit directly.
+
+Assumes Next.js App Router + React 19 + TypeScript. For pages/ router or React ≤18, drop the App Router steps and the `useActionState`/server-action patterns.
+
+## Steps
+
+1. **Default to a Server Component. Add `'use client'` only when the component actually needs the browser.** A file is client-only if it uses any of: `useState`/`useReducer`, `useEffect`/`useLayoutEffect`, event handlers (`onClick`, `onChange`, …), refs to DOM nodes, browser APIs (`window`, `localStorage`, `IntersectionObserver`), or a third-party lib that calls these. None of those → leave it a Server Component (no directive). `'use client'` is a **boundary**, not a per-file tag: it marks the entry point; every child imported into it becomes client too. So push it **down the tree** to the smallest interactive leaf.
+
+2. **Keep the boundary thin: pass Server Components into Client Components as `children`/props, don't import them.** A Client Component can *render* Server Component output if it arrives via props/children — it just can't `import` one. Pattern:
+   ```tsx
+   // page.tsx (server) — fetches data, composes
+   <ClientShell><ServerHeavyList /></ClientShell>
+   ```
+   This keeps the data-fetching + heavy markup on the server while the interactive wrapper stays small.
+
+3. **Write the props contract first, as a named `interface`, with defaults.**
+   ```tsx
+   interface CardProps {
+     title: string;
+     description?: string;
+     variant?: 'default' | 'outline';   // union, not string
+     children?: React.ReactNode;
+   }
+   export function Card({ title, description, variant = 'default', children }: CardProps) { … }
+   ```
+   Rules: no `React.FC` (breaks generics, implies legacy `children`). Use string-literal unions over `string` for variants. Default values in the destructure, not `defaultProps`. Extend native props when wrapping an element: `interface ButtonProps extends React.ComponentProps<'button'> { variant?: … }` then spread `{...rest}` onto the element so consumers keep `aria-*`, `type`, `onClick`, etc.
+
+4. **Fetch data in the Server Component with `async`/`await` — no `useEffect` fetching.**
+   ```tsx
+   export default async function Page() {
+     const data = await getData();          // runs on server, no client JS shipped
+     return <View data={data} />;
+   }
+   ```
+   `fetch` is auto-deduped/cached per request. Set freshness with `{ next: { revalidate: 60 } }` or `cache: 'no-store'`. Never lift this into a Client Component — that ships the fetch + waterfalls it.
+
+5. **Colocate files; reach for App Router special files when the route needs them.**
+   ```
+   components/card/
+     card.tsx          # component
+     card.test.tsx     # test
+     card.module.css   # styles (or Tailwind inline)
+   app/dashboard/
+     page.tsx          # route UI
+     layout.tsx        # shared shell (persists across child routes)
+     loading.tsx       # Suspense fallback — auto-wraps page
+     error.tsx         # 'use client' error boundary (gets error + reset)
+     not-found.tsx
+   ```
+   Add `loading.tsx`/`error.tsx` only when the route does async work or can fail. Barrel `index.ts` files only at package/public boundaries — not inside feature folders (they bloat bundles and create import cycles).
+
+6. **Compose, don't configure.** Prefer `children` and slot props over a pile of booleans. When a component has tightly-coupled parts, use the **compound pattern** instead of `tabs={[…]}` config:
+   ```tsx
+   <Tabs defaultValue="a">
+     <Tabs.List><Tabs.Trigger value="a">A</Tabs.Trigger></Tabs.List>
+     <Tabs.Panel value="a">…</Tabs.Panel>
+   </Tabs>
+   ```
+   Shared state goes through a Context created *inside* the parent (see step 8). This beats prop explosions and lets consumers control layout.
+
+7. **For forms/mutations use Server Actions + React 19 hooks, not manual fetch + useState.**
+   ```tsx
+   // actions.ts
+   'use server';
+   export async function save(prev, formData: FormData) { …; return { ok: true }; }
+   ```
+   ```tsx
+   'use client';
+   const [state, action, pending] = useActionState(save, null);
+   return <form action={action}><button disabled={pending}>Save</button></form>;
+   ```
+   Use `useOptimistic` to reflect the change in UI before the action resolves; use `useFormStatus()` inside a child to read pending state without prop-passing.
+
+8. **Kill prop drilling by lifting state or scoping a Context — not by threading props 3+ levels.** If two siblings need the same state, lift it to their nearest common parent. If many descendants need it, create a typed Context **co-located with the feature** (provider in the parent, a `useX()` hook that throws if used outside the provider):
+   ```tsx
+   const Ctx = React.createContext<T | null>(null);
+   export function useTabs() {
+     const c = React.useContext(Ctx);
+     if (!c) throw new Error('useTabs must be used within <Tabs>');
+     return c;
+   }
+   ```
+   Don't reach for global state (Zustand/Redux) for what is local UI coordination.
+
+9. **Apply the accessibility baseline, then hand deep a11y to the a11y skill.** Use the semantic element (`<button>` for actions, `<a>`/`<Link>` for navigation, `<nav>`/`<main>`/`<ul>`), associate every input with a `<label htmlFor>`, give icon-only controls an `aria-label`, and don't trap keyboard users. Anything beyond this baseline (focus management, ARIA widget roles, live regions) → defer to the dedicated accessibility skill.
+
+## Common Errors
+
+- **`useState`/event handler in a Server Component** → build error: *"You're importing a component that needs useState… add 'use client'."* Fix: add the directive to that leaf, or move just the interactive bit into a small client child. Don't slap `'use client'` on the whole page.
+- **Importing a Server Component into a Client Component** → it silently becomes a client component (loses server-only access to DB/secrets/`async`). Fix: pass it as `children`/prop from a server parent (step 2).
+- **Passing a non-serializable prop (function, Date, class instance) across the server→client boundary** → *"Only plain objects can be passed to Client Components."* Event handlers/functions can't cross it. Fix: serialize, or move the handler into the client side.
+- **`React.FC<Props>`** → swallows generics and implies an optional `children` you may not want. Use a plain function with a typed param.
+- **Fetching in `useEffect` for first paint** → request waterfall + spinner + larger bundle. Fix: `await` it in the Server Component (step 4).
+- **`async` Client Component** (`'use client'` + `async function`) → not supported; only Server Components can be async. Fetch on the server or use a data hook / `use()`.
+- **Reading `process.env.SECRET` in client code** → it's `undefined` in the browser (only `NEXT_PUBLIC_*` is exposed) and leaks if it weren't. Keep secrets in Server Components/actions.
+- **Barrel `index.ts` re-exporting a whole feature folder** → defeats tree-shaking, drags client code into server bundles, and risks circular imports. Import from the specific file.
+- **`error.tsx` without `'use client'`** → error boundaries must be Client Components; it won't catch otherwise.
+- **Mutating data then expecting the UI to refresh** → call `revalidatePath`/`revalidateTag` in the server action; client state won't update on its own.
+
+## Verify
+
+- [ ] `npx tsc --noEmit` passes — props contract is sound, no `any` leaking in.
+- [ ] `next build` (or `next dev` with no console errors) — confirms no Server/Client boundary violation or serialization error.
+- [ ] Every `'use client'` sits on the **smallest** interactive component; server data-fetching stays server-side (grep the tree: a `'use client'` file should not contain `await fetch`/DB calls).
+- [ ] Props use named unions + extend native element props where wrapping; no `React.FC`; no `defaultProps`.
+- [ ] Interactive controls are real semantic elements with labels/`aria-label`; tab order works.
+- [ ] No prop drilled past 2 levels without a lift or Context; no global store for purely local UI state.
+- [ ] Tests/lint run green if the repo has them (`npm test`, `npm run lint`).

package/skills/build-spreadsheet/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: build-spreadsheet
+description: Creates and edits XLSX workbooks with formulas, multi-sheet references, cell formatting, conditional formatting, pivot-style summaries, and native Excel charts.
+when_to_use: When the user asks to build or modify an Excel/XLSX file — add columns with formulas (SUM/VLOOKUP), format cells, build multi-sheet workbooks with cross-sheet references, create native charts, or turn data into a structured financial-model-style workbook.
+---
+
+## When to Use
+
+Use this skill to **produce a `.xlsx` artifact a human will open in Excel** — a financial model, budget, tracker, report, or dashboard. The deliverable is a live workbook: formulas recalculate, charts re-render, sheets cross-reference.
+
+Reach for it when the request includes any of: "add a column that sums/looks-up", "format these cells", "highlight values over X", "build a summary sheet that pulls from the detail tabs", "make a chart", "turn this CSV into a real Excel model".
+
+**Not this skill** — if the goal is to *analyze* data and report numbers back in chat (use pandas/data-wrangle). The line: data-wrangle answers a question, build-spreadsheet hands over a file.
+
+Default engine: **openpyxl** (read + write + formatting + native charts in one library). Only switch to `xlsxwriter` for write-only generation of very large files (>50k rows) where speed matters — it is faster but **cannot read or edit existing files**.
+
+## Steps
+
+1. **Install + import.** `pip install openpyxl` if missing. Then:
+   ```python
+   from openpyxl import Workbook, load_workbook
+   from openpyxl.styles import Font, PatternFill, Alignment, Border, Side
+   from openpyxl.formatting.rule import ColorScaleRule, CellIsRule, FormulaRule
+   from openpyxl.chart import BarChart, LineChart, PieChart, ScatterChart, Reference, Series
+   from openpyxl.utils import get_column_letter
+   ```
+   New file → `wb = Workbook()`. Editing an existing file → `wb = load_workbook("in.xlsx")` (add `data_only=False` to keep formulas as formulas, not last-cached values).
+
+2. **Lay out sheets and headers.** `ws = wb.active; ws.title = "Detail"`; add more with `wb.create_sheet("Summary")`. Write headers, then write **typed** cell values — pass real `int`/`float`/`datetime`, not strings, or Excel treats numbers as text and SUM returns 0. Set `cell.number_format = "yyyy-mm-dd"` for dates.
+
+3. **Write formulas as strings, never precompute.** Store the formula so Excel computes it:
+   ```python
+   ws["D2"] = "=B2*C2"
+   ws["E2"] = "=SUM(D2:D100)"
+   ws["F2"] = '=VLOOKUP(A2,Detail!$A$2:$C$100,3,FALSE)'
+   ```
+   A leading `=` is what makes it a formula. openpyxl does **not** evaluate it — the cell has no value until Excel/LibreOffice opens and recalcs the file.
+
+4. **Cross-sheet refs and named ranges.** Reference another sheet with `SheetName!A1`; quote sheet names containing spaces: `'Q1 Detail'!A1`. For reusable ranges:
+   ```python
+   from openpyxl.workbook.defined_name import DefinedName
+   wb.defined_names.add(DefinedName("tax_rate", attr_text="Assumptions!$B$1"))
+   ws["C2"] = "=B2*tax_rate"
+   ```
+
+5. **Formatting.** Apply per cell (styles do **not** cascade from columns/rows):
+   ```python
+   ws["A1"].font = Font(bold=True, color="FFFFFF")
+   ws["A1"].fill = PatternFill("solid", fgColor="305496")
+   ws["B2"].number_format = '#,##0.00'          # or '$#,##0', '0.0%', '#,##0;[Red](#,##0)'
+   ws.column_dimensions["A"].width = 22
+   ws.freeze_panes = "A2"                        # lock header row
+   ```
+
+6. **Conditional formatting** is bound to a range and re-evaluates live in Excel:
+   ```python
+   ws.conditional_formatting.add("D2:D100",
+       ColorScaleRule(start_type="min", start_color="F8696B",
+                      end_type="max", end_color="63BE7B"))
+   ws.conditional_formatting.add("E2:E100",
+       CellIsRule(operator="greaterThan", formula=["1000"],
+                  fill=PatternFill("solid", fgColor="FFC7CE")))
+   ```
+
+7. **Pivot-style summary** — don't try to write a real PivotTable (openpyxl support is fragile). Instead build a summary sheet of unique keys + `SUMIF`/`COUNTIF`/`AVERAGEIF` against the detail sheet, so totals stay live:
+   ```python
+   ws_sum["B2"] = '=SUMIF(Detail!$A:$A,A2,Detail!$D:$D)'
+   ```
+
+8. **Native charts** bound to `Reference` ranges (these recalc/redraw in Excel, unlike pasted images):
+   ```python
+   chart = BarChart(); chart.title = "Sales by Region"; chart.type = "col"
+   data = Reference(ws, min_col=2, min_row=1, max_col=2, max_row=10)  # include header row
+   cats = Reference(ws, min_col=1, min_row=2, max_row=10)
+   chart.add_data(data, titles_from_data=True)
+   chart.set_categories(cats)
+   ws.add_chart(chart, "H2")   # anchor cell
+   ```
+   Swap `BarChart`→`LineChart`/`PieChart`/`ScatterChart` as needed. Scatter needs `Series(yvalues, xvalues)` explicitly.
+
+9. **Save** with `wb.save("out.xlsx")`. Pick a clear, descriptive filename.
+
+## Common Errors
+
+- **Formula shows as text / SUM = 0.** Either the string lacks a leading `=`, or the summed cells hold strings not numbers. Write numeric values as real `int`/`float`. Also: a cell can hold a formula **or** a literal value, not both — openpyxl never fills in the computed result, so the file looks "empty" until opened and recalced.
+- **Reading back gives `None` for formula cells.** `load_workbook(data_only=True)` returns the *last cached value Excel saved*. A file written purely by openpyxl was never opened by Excel, so there is no cache → `None`. Use `data_only=False` to read the formula string; open in Excel once and save if you need cached values.
+- **Styles/charts vanish after editing an existing file.** `load_workbook` drops what it can't model — VBA macros (unless `keep_vba=True`), some chart types, and many embedded PivotTables/images are lost on re-save. Verify after round-trip; for macro files keep `.xlsm` + `keep_vba=True`.
+- **Style applied to a whole column doesn't show.** openpyxl styles are per-cell; setting `column_dimensions[...].font` only affects *new* cells, not existing ones. Loop the actual cells.
+- **A `Font`/`Fill`/`Border` object shared across cells** can raise `StyleProxy`/copy errors — create a fresh style object (or `copy()`) per cell instead of reusing one instance.
+- **Sheet name with spaces in a formula not quoted** → `#REF!`. Wrap in single quotes: `'My Sheet'!A1`.
+- **Huge files blow memory.** For tens of thousands of rows, write with `Workbook(write_only=True)` + `ws.append(row_list)` (no random cell access, no formatting mid-stream), or use `xlsxwriter`.
+- **Color hex** is `RRGGBB` (or `AARRGGBB`), no `#`. `"#FF0000"` fails silently or errors.
+
+## Verify
+
+After saving, reopen and assert structure programmatically — never assume the write succeeded:
+
+```python
+chk = load_workbook("out.xlsx")
+assert {"Detail", "Summary"} <= set(chk.sheetnames)
+assert chk["Detail"]["D2"].value == "=B2*C2"          # formula stored as string
+assert chk["Detail"]["D2"].data_type == "f"           # 'f' = formula
+assert len(chk["Detail"]._charts) >= 1                 # chart survived save
+```
+
+Then do a real recalc check: open the file once in Excel or headless LibreOffice (`libreoffice --headless --convert-to xlsx out.xlsx`) and confirm formula cells show numbers, not `0`/`#REF!`/text. If totals are `0`, the inputs were strings — go back to step 2.

package/skills/caching-strategy/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: caching-strategy
+description: Designs caching layers (cache-aside, write-through, TTLs, invalidation, stampede protection) typically with Redis to cut latency and database load when responses are slow or repeated.
+when_to_use: User wants to add or fix caching, choose a cache pattern, set TTLs, solve stale data, cache stampede, or thundering-herd problems, or reduce DB load. NOT for measuring where time goes (use performance-profiling).
+---
+
+## When to Use
+
+Reach for this skill when a read is **slow or repeated** and the underlying data is **more read than written** and **tolerant of some staleness**.
+
+- Use when: hot read path hits the DB/external API every request; identical responses recomputed; DB CPU/connection pool saturated by reads; p99 latency dominated by one query/call.
+- Do NOT use when: you don't yet know *where* time goes (profile first), data must be strictly fresh on every read (auth tokens, balances, inventory-at-checkout), write-heavy with near-zero re-reads (cache churns, hit ratio stays low), or working set fits in one cheap query already.
+
+Decision gate before writing any code, answer all four:
+1. What exact key identifies this read? (must be deterministic from request inputs)
+2. How stale can the value be — seconds, minutes, hours? (sets TTL ceiling)
+3. What's the current read:write ratio on this data? (<5:1 → caching rarely pays)
+4. What's the blast radius if a stale value is served? (decides invalidation rigor)
+
+If you can't answer #2 and #4, stop — caching here risks a correctness bug, not a speedup.
+
+## Steps
+
+1. **Pick exactly one hot read to cache first.** Confirm it's read-heavy and idempotent (same inputs → same output). Resist caching writes or per-user-unique reads with no reuse.
+
+2. **Design the key namespace.** Format: `{domain}:{entity}:{id}:{version}` e.g. `user:profile:42:v3`. Rules:
+   - Include a schema/serializer **version segment** so a deploy with a changed shape can't read old bytes as the new type.
+   - Never put unbounded/unhashed user input in the key (cardinality explosion + injection); hash long or composite keys.
+   - Keep one key = one entity. Avoid baking query params you'll later need to invalidate independently into a single blob.
+
+3. **Choose the pattern:**
+   - **Cache-aside (default, start here):** read → on miss, load from source, write to cache with TTL, return. App owns cache; source stays the truth.
+   - **Write-through:** on write, update source **then** cache synchronously. Use when reads must reflect writes immediately and you accept slower writes.
+   - **Write-behind:** buffer writes, flush to source async. Only with a durable queue and an accepted data-loss window — most teams should not.
+   - Default to cache-aside unless a concrete requirement forces the others.
+
+4. **Set TTL deliberately, never "just put a number."** TTL = max acceptable staleness from step 2. Add **jitter**: store with `ttl ± rand(0..ttl*0.1)` so keys created together don't all expire on the same tick. Pick eviction policy explicitly (e.g. `allkeys-lru` for a pure cache, `volatile-ttl` if the instance also holds non-expiring data) — don't inherit `noeviction`, which turns a full cache into write errors.
+
+5. **Invalidate on write, don't rely on TTL alone for correctness.** On every mutation of the source, in the same transaction boundary: **delete** the affected key(s) (don't try to update them — update-in-place races with concurrent reads). For derived/list keys, track an index of dependent keys or use a key prefix + versioned namespace you can bump. After a DB commit, delete; if the delete can fail independently of the commit, prefer the **delete-after-commit + short TTL safety net** so a missed invalidation self-heals.
+
+6. **Add stampede protection before it bites in prod.** When a hot key expires under load, all callers miss at once and dogpile the source. Use one of:
+   - **Single-flight / per-key lock:** first miss acquires a short-lived lock (`SET lock:{key} 1 NX EX 5`), recomputes, fills cache; others briefly wait/retry or serve stale.
+   - **Stale-while-revalidate:** store `{value, soft_expiry, hard_expiry}`; serve stale past soft_expiry while one worker refreshes in background. Best UX for read-heavy paths.
+   - **Jittered TTL** (step 4) handles synchronized expiry; SWR/lock handles a single hot key. Use both.
+
+7. **Layer only if measured need.** Optional L1 in-process cache (small, short TTL, e.g. 1–5s) in front of L2 (Redis) for ultra-hot keys. Cap L1 size and remember L1 is **per-instance → harder to invalidate**; keep its TTL short enough that staleness from a missed L1 invalidation is tolerable.
+
+8. **Serialize compactly and cap size.** Pick a stable serializer (JSON for debuggability, msgpack/protobuf for size/speed). Reject caching values over a sane ceiling (e.g. a few hundred KB) — large values blow network and memory; cache an id/handle and fetch the body separately instead.
+
+9. **Verify (step below) — never declare done on "it returns faster once."**
+
+## Common Errors
+
+- **Caching null/error as if it were data.** A miss that returns "not found" or throws must be cached **differently** (short negative-TTL sentinel) or not at all — otherwise either you re-hammer the DB for every missing id, or you pin a transient error for the full TTL.
+- **Update-in-place on invalidation.** Reader loads old value → writer updates DB → writer overwrites cache → reader writes its stale value back. **Always delete, never set, on invalidation.** And delete *after* the source commit, not before.
+- **Cache stampede ignored until launch.** Works fine in dev (1 caller), melts the DB on a hot key at scale. Add jitter + single-flight/SWR up front for any key you expect to be hot.
+- **Unbounded key cardinality.** Caching per-request keys with no reuse (full query strings, timestamps, paginated infinite scroll) → near-zero hit ratio + memory bloat. Verify reuse exists before caching.
+- **No serializer version in key.** Deploy changes the struct shape; new code deserializes old bytes → crash or silent corruption. Version segment in the key (step 2) prevents it.
+- **`noeviction` on a cache instance.** When memory fills, writes start erroring instead of evicting cold keys, cascading into request failures. Set an `allkeys-*` / `volatile-*` policy.
+- **TTL = correctness crutch.** Long TTL "to be safe" serves stale data; short TTL "to be fresh" kills hit ratio and re-stampedes. TTL is the staleness budget; explicit invalidation is the correctness mechanism. Use both.
+- **Caching strongly-consistent data.** Balances, inventory at checkout, permission checks, auth state — do not cache, or cache only with write-through + immediate invalidation and a hard correctness review.
+- **Thundering herd on cold start / flush.** After a cache restart or mass eviction, everything misses at once. Warm critical keys on deploy, or rely on per-key locks so only one caller rebuilds each key.
+
+## Verify
+
+Caching is "done" only when measured, not when it "felt faster."
+
+1. **Hit ratio:** instrument hits/misses per key namespace; a working cache settles at a high hit ratio (target depends on path; a hot read should be well north of 80%). Persistently low → wrong key, no reuse, or TTL too short. Caching was the wrong move there.
+2. **Latency:** compare p50 **and p99** of the cached path before/after under realistic concurrency, not a single warm call. Confirm the source load (DB QPS / external calls) actually dropped — that's the real win.
+3. **Correctness under write:** write a test that (a) reads (populates cache), (b) mutates the source, (c) reads again and asserts the new value — proves invalidation fires. Add a test that a missing id doesn't repeatedly hit the source (negative caching) and doesn't pin an error.
+4. **Stampede:** fire N concurrent requests at a freshly-expired hot key; assert the source is hit ~once, not N times (single-flight/SWR working).
+5. **Eviction/memory:** confirm the eviction policy is set and the instance evicts rather than erroring when full; watch memory under load.
+6. **Failure mode:** kill/disconnect the cache and confirm the app **degrades to the source** (slower but correct), not 500s. The cache is an optimization, not a dependency.
+
+If hit ratio is low or latency didn't move, the data wasn't cacheable here — revert and profile instead.