@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/threat-modeling/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Threat model the new document upload and sharing feature before we build it",
+    "Do a STRIDE analysis of our payment webhook architecture",
+    "What could an attacker do to this design? Here's the data flow for our multi-tenant reporting service",
+    "We're adding an LLM agent with tool access to our support portal, map the trust boundaries and threats",
+    "Before security sign-off, list the assets, threats and mitigations for the mobile login flow and rank them"
+  ],
+  "should_not_trigger": [
+    "Scan the code in this pull request for XSS and injection flaws",
+    "Check whether any of our npm packages have known CVEs",
+    "Implement role-based access control on the admin routes",
+    "Write an architecture decision record for moving from REST to gRPC",
+    "Break this feature into implementation tasks and a delivery plan"
+  ]
+}

package/skills/transactional-email/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: transactional-email
+description: Application code that sends one-to-one system email (sign-up confirmation, password reset, receipts, alerts) through a provider HTTP API such as Postmark, Amazon SES, Resend, Mailtrap or SendGrid, with versioned templates rendered from a typed model, sends queued and made idempotent by a stored message key, test inboxes and simulator addresses instead of real recipients, verified bounce, complaint and delivery webhooks, and a suppression check before every send. Use when wiring a provider SDK into a backend, building the email-sending service or queue worker, testing email flows without mailing real users, or handling a provider's bounce and complaint events in code.
+license: MIT
+compatibility: Any Agent Skills host. Live sends need network access to the chosen provider and a verified sending domain. Examples are TypeScript; the rules apply to any language and SDK.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Transactional email
+
+Build the code path from "user did something" to "provider accepted one email", so each email goes out once, never to a suppressed address, never to a real person from a test, and every bounce or complaint comes back into the database. DNS records (SPF, DKIM, DMARC), warm-up and inbox placement belong to `email-deliverability`; this skill starts once a domain is verified.
+
+## Ground rules
+
+1. **API keys on the server, per environment.** Separate keys (or Postmark servers, SES accounts or Regions, SendGrid subusers) for development, staging and production. A dev key must be unable to reach real inboxes.
+2. **Transactional only on this path.** Marketing and bulk mail go on a separate stream, subdomain or provider account (Postmark `broadcast` stream, a separate SES configuration set, a SendGrid subuser) so a newsletter complaint spike can't block password resets.
+3. **Never send inside the request.** The web request writes an `outbound_email` row in the same database transaction as the business change, then a worker sends it (outbox pattern). The user's request never waits on the provider.
+4. **One logical email, one key.** Each row has a stable idempotency key (for example `password-reset:<user_id>:<token_id>`) with a unique index, so a retry or double-click creates no second row. Pass it to providers that support it (Resend `Idempotency-Key`, kept 24 hours); for the others, the unique row plus a `sent` status update is the guard.
+5. **Check suppression before every send.** Keep your own `email_suppressions` table fed by webhooks, check it in the worker, and do not rely on the provider silently dropping the message.
+6. **Verify every webhook** the way the provider supports (signature, SNS message signature, basic auth plus IP allow-list), on the raw body, and make processing idempotent by event ID.
+7. **Tests never hit real people.** Use a sandbox (Mailtrap sandbox inbox, SendGrid sandbox mode, Postmark test token) or simulator addresses (SES `@simulator.amazonses.com`, Resend `@resend.dev`). Details per provider in `references/providers.md`.
+
+## Choose the provider
+
+| Need | Good fit |
+|---|---|
+| Fast setup, strict transactional focus, message streams, built-in templates | Postmark |
+| Lowest unit cost at volume, already on AWS, own the event pipeline | Amazon SES v2 with configuration sets and SNS or EventBridge |
+| Developer-first API, React Email templates, native idempotency keys | Resend |
+| One vendor for a test sandbox and sending | Mailtrap |
+| Existing Twilio account, dynamic templates, suppression groups | SendGrid |
+
+If the project already uses one, keep it; the rules above are the same everywhere.
+
+## Implementation steps
+
+1. **Email module behind one interface**: `send({ template, to, model, idempotencyKey, tags })`. One adapter per provider; application code never imports a provider SDK directly. This is what lets tests swap in a sandbox.
+2. **Templates**: keep them in the repo (React Email, MJML, Handlebars) or in the provider (Postmark `TemplateAlias`, SendGrid dynamic template `d-...`). Either way: a typed model per template, an HTML and a plain-text part, a version in the template name or tag, and a snapshot test that renders each template with fixture data. Escape every user-supplied value; never put raw user input in a subject without trimming control characters and newlines.
+3. **Outbox row**: `id, idempotency_key UNIQUE, template, version, to_address, model_json, status (queued|sending|sent|failed|suppressed), provider_message_id, attempts, last_error, created_at, sent_at`.
+4. **Worker**: claim rows with `UPDATE ... SET status='sending' WHERE status='queued' ... RETURNING` (or `SELECT ... FOR UPDATE SKIP LOCKED`), check suppression (mark `suppressed` and stop), render, call the provider with the key, store `provider_message_id`, mark `sent`. Retry 429 and 5xx with backoff and jitter; mark `failed` without retry on 4xx validation errors (bad address, unverified sender).
+5. **Ambiguous timeouts**: if the provider call times out after sending the request, the email may have gone. With a provider idempotency key, retry with the same key. Without one, look the message up first (provider message search or activity API, by the tag or metadata holding your key) and retry only if it is not there. If the lookup is not possible, decide per template whether a duplicate or a missing email is worse; ask the user.
+6. **Webhook endpoint**: verify, store the raw event with its ID (unique), return 2xx quickly, process asynchronously. Map events to actions: hard bounce and spam complaint add to `email_suppressions` (reason, source event, date); soft bounce or deferral only logs; delivery updates the outbox row. Shapes in `references/providers.md`.
+7. **Suppression sync**: also import the provider's own suppression list periodically, and when a user changes their address, clear nothing automatically; a support-approved removal only.
+8. **Observability**: count sent, bounced, complained and suppressed per template per day, and alert if bounce or complaint rates jump after a deploy.
+
+## Reviewing an existing integration
+
+- Provider call inside the HTTP handler or a database transaction, so a slow provider stalls requests or a rollback still sends.
+- No idempotency: a retried job or double-submitted form sends the email twice; or the key is regenerated per attempt.
+- Webhook route without verification, or verification over re-serialised JSON.
+- Bounces and complaints received but never written to a suppression table, or soft bounces suppressed permanently.
+- Production API key in `.env.example`, tests or CI that send to real addresses; staging using the production key.
+- Password reset or magic-link tokens logged, put in tags or metadata, or left valid after use.
+- Marketing mail sharing the transactional stream or key.
+
+## Stop and ask the user
+
+- Before switching any environment to a production key or a live stream, or before sending to real recipients from a test.
+- Whether duplicate or missing email is worse for each template when a send outcome is unknown.
+- Before removing addresses from any suppression list, or before sending to a list of more than a handful of users through this path (that is bulk mail).
+
+## Before you finish
+
+Provider docs are the final word on field names and limits. Test, in the sandbox: one email per idempotency key under a forced retry; a simulator bounce lands in `email_suppressions` and blocks the next send; a simulator complaint does the same; a webhook with a bad signature or credentials is rejected; templates render in HTML and text with fixture data.

package/skills/transactional-email/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Send our password reset and order receipt emails through Postmark templates from the Node backend",
+    "Our signup confirmation email sometimes goes out twice when the job retries, how do we make sends idempotent with Resend?",
+    "Set up an SES sandbox test using the mailbox simulator so our test suite never emails real customers",
+    "Verify SendGrid's signed event webhook and add bounced addresses to our own suppression table",
+    "Point staging at a Mailtrap sandbox inbox and assert in our tests that the welcome email arrived",
+    "Move our email sending out of the request handler into an outbox table and a worker"
+  ],
+  "should_not_trigger": [
+    "Set up SPF, DKIM and DMARC records for our new sending domain",
+    "Write a five-email welcome nurture sequence for trial users",
+    "Our receipts land in Gmail spam even though DKIM passes, what is wrong with our reputation?",
+    "Write a four-step cold email sequence for operations managers at hospitals",
+    "Triage my unread email and draft replies for the urgent ones"
+  ]
+}

package/skills/transactional-email/references/providers.md

@@ -0,0 +1,63 @@
+# Provider notes for transactional email
+
+Read the section for the provider in use. Confirm field names against the provider's current API reference before shipping.
+
+## Postmark
+
+- Send: `POST https://api.postmarkapp.com/email` (`From`, `To`, `Subject`, `HtmlBody`, `TextBody`, `MessageStream`, `Tag`, `Metadata`). Templates: `POST /email/withTemplate` with `TemplateAlias` or `TemplateId` and `TemplateModel`; batch with templates: `POST /email/batchWithTemplates`, up to 500 messages, returns 200 even if some fail, so check each result's `ErrorCode`.
+- Auth header: `X-Postmark-Server-Token`. Test token: send `POSTMARK_API_TEST` as the server token to validate requests without delivering.
+- Streams: `outbound` is the default transactional stream; create a broadcast stream for bulk mail. Omitting `MessageStream` uses `outbound`.
+- Idempotency: no idempotency key in the API. Rely on your outbox unique key.
+- Webhooks: Delivery, Bounce, Spam complaint, Open, Click, Subscription change. Postmark does **not** sign webhooks: protect the URL with HTTP basic auth credentials in the URL, HTTPS, and an allow-list of Postmark's published webhook IPs. Retries 5xx, 408, 429 and network failures (1, 5, 10, 10, 10, 15 minutes); other 4xx are dropped, so return 2xx once stored.
+- Suppressions are per stream; hard bounces and spam complaints suppress automatically; a `SubscriptionChange` webhook tells you when one is added or removed.
+
+## Amazon SES (API v2)
+
+- Send: `SendEmail` (SDK `SESv2Client` + `SendEmailCommand`) with `Content.Simple`, `Content.Template` (stored template) or `Content.Raw`, `ConfigurationSetName`, and `EmailTags` for your own message key.
+- Sandbox (per Region): send only to verified addresses or the mailbox simulator, at most 200 messages per 24 hours and 1 per second. Request production access per Region.
+- Mailbox simulator (works in the sandbox, does not hurt reputation, still billed): `success@simulator.amazonses.com`, `bounce@`, `complaint@`, `ooto@`, `suppressionlist@`. Add labels (`bounce+order123@simulator.amazonses.com`) to match events to messages.
+- Events: configuration set event destinations to SNS, EventBridge, Firehose or CloudWatch. For SNS over HTTPS, confirm the `SubscriptionConfirmation` and verify every message's SNS signature (the AWS SDK message validator) before trusting it; also check the topic ARN.
+- Account-level suppression list (on by default for bounces and complaints in accounts created after 25 Nov 2019; enable older ones with `aws sesv2 put-account-suppression-attributes --suppressed-reasons BOUNCE COMPLAINT`); manage with `PutSuppressedDestination`, `DeleteSuppressedDestination`, `ListSuppressedDestinations`. Only hard bounces (not soft) are added. Sending treats address case as equal, but the suppression management API needs the exact case stored, so keep the original address alongside your normalised one. Configuration sets can override it. Messages to suppressed addresses are accepted, not delivered, and still count toward the daily sending quota.
+- Gmail does not send complaint feedback to SES, so a Gmail "Report spam" will not reach your suppression list.
+- Idempotency: none in the API. Rely on your outbox key.
+
+## Resend
+
+- Send: `POST https://api.resend.com/emails` with `from`, `to`, `subject`, `html`/`text` or `react` (Node SDK), `tags`. Header `Authorization: Bearer re_...`.
+- Idempotency: `Idempotency-Key` header (SMTP: `Resend-Idempotency-Key`), 1-256 chars, kept 24 hours. Same key with a different payload returns `409 invalid_idempotent_request`; a request still in flight returns `409 concurrent_idempotent_requests` (safe to retry later).
+- Test addresses: `delivered@resend.dev`, `bounced@resend.dev`, `complained@resend.dev` (these three accept `+label`, e.g. `bounced+signup1@resend.dev`) and `suppressed@resend.dev` (no labels). Test sends count against the account's sending quota.
+- Webhooks are signed via Svix: headers `svix-id`, `svix-timestamp`, `svix-signature`; verify the raw body string with `resend.webhooks.verify` or the `svix` library `Webhook` class. Email events: `email.sent`, `email.delivered`, `email.delivery_delayed`, `email.bounced`, `email.complained`, `email.failed`, `email.suppressed`, `email.opened`, `email.clicked`, `email.scheduled`, `email.received`. Suppress on `email.bounced` and `email.complained`; mark the outbox row on `email.failed` and `email.suppressed`.
+
+## Mailtrap
+
+- Testing: a sandbox inbox catches everything; nothing reaches real recipients. API: `POST https://sandbox.api.mailtrap.io/api/send/{inbox_id}` with the `Api-Token` header (or bearer token); SMTP credentials come from the inbox's Integration tab. Use it for development and staging, including automated tests that read the inbox through the API.
+- Sending: transactional sending API for production with a separate token from the testing token. Check the current host and stream (transactional versus bulk) in the Mailtrap docs.
+
+## SendGrid (Twilio)
+
+- Send: `POST https://api.sendgrid.com/v3/mail/send` with `personalizations[]`, `from`, `template_id` (`d-...` dynamic template) and `personalizations[].dynamic_template_data`, `custom_args` for your message key, `asm.group_id` for an unsubscribe group. `202 Accepted` on success.
+- Sandbox mode: `"mail_settings": { "sandbox_mode": { "enable": true } }` validates and returns `200 OK` without delivering. The boolean must not be quoted.
+- Signed Event Webhook: ECDSA signature in `X-Twilio-Email-Event-Webhook-Signature`, timestamp in `X-Twilio-Email-Event-Webhook-Timestamp`; verify over timestamp + raw body with the public key from the webhook settings, using the helper library. OAuth 2.0 client credentials can be enabled as well.
+- Events arrive batched as a JSON array: `processed`, `dropped`, `delivered`, `deferred`, `bounce`, `open`, `click`, `spamreport`, `unsubscribe`, `group_unsubscribe`. Each has `sg_event_id`; dedupe on it.
+- Suppressions: bounces, blocks, spam reports and invalid emails each have a `/v3/suppression/{bounces|blocks|spam_reports|invalid_emails}` endpoint; global unsubscribes are managed at `/v3/asm/suppressions/global` and unsubscribe-group suppressions at `/v3/asm/groups/{group_id}/suppressions`.
+- Idempotency: none in the API. Rely on your outbox key.
+
+## Webhook handler shape (any provider)
+
+```ts
+app.post("/webhooks/email", express.raw({ type: "*/*" }), async (req, res) => {
+  let events;
+  try {
+    events = verifyAndParse(req.headers, req.body); // provider-specific; returns an array (SendGrid batches events)
+  } catch {
+    return res.sendStatus(401); // bad signature or credentials: reject, never process
+  }
+  for (const event of events) {
+    const inserted = await db.emailEvents.insertIfAbsent({ id: event.id, provider, raw: JSON.stringify(event) });
+    if (inserted) await queue.add("email-event", { id: event.id });
+  }
+  res.sendStatus(200); // only after every event is stored, so a crash mid-batch gets a retry
+});
+```
+
+Map in the job: hard bounce or complaint → upsert `email_suppressions(address_normalised, reason, event_id, created_at)`; soft bounce → log and count; delivered → mark the outbox row.

package/skills/typescript-patterns/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: typescript-patterns
+description: Idiomatic TypeScript and modern JavaScript for Node.js and the browser, covering strict tsconfig settings, discriminated unions and narrowing, restrained generics, typed error handling, async/await pitfalls, ESM versus CommonJS packaging, project layout and ESLint/Prettier setup. Use when writing or restructuring TS/JS code, designing types for a module, setting up tsconfig or package.json "type"/"exports", or choosing lint and format tooling.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node.js 18+ and the project's package manager (npm, pnpm, yarn or bun).
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/requires: "node"
+  kete-loom/owner: "Kete-org"
+---
+
+# TypeScript patterns
+
+Write TypeScript that the compiler can actually check. Every rule here exists to keep the types honest about what happens at runtime.
+
+## 0. Read the project first
+
+1. Read `package.json` (`type`, `exports`, `engines`, scripts), every `tsconfig*.json`, and the lint/format config (`eslint.config.*`, `.eslintrc*`, `.prettierrc*`, `biome.json`).
+2. Note the lockfile (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`, `bun.lock*`) and use only that package manager.
+3. Follow the existing style, folder layout and module system. Do not convert a codebase between ESM and CJS, or between tools, unless the user asked.
+4. Find the type-check command (often `tsc --noEmit` or a `typecheck` script) and run it before and after your change.
+
+## 1. tsconfig baseline
+
+For new projects, or when the user asks to tighten settings, start from:
+
+```jsonc
+{
+  "compilerOptions": {
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "exactOptionalPropertyTypes": true,   // optional; stricter about `undefined`
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true,
+    "skipLibCheck": true,
+    "target": "ES2022",
+    "module": "NodeNext",                 // Node apps and libraries
+    "moduleResolution": "NodeNext"
+    // bundled browser apps: "module": "ESNext", "moduleResolution": "Bundler"
+  }
+}
+```
+
+- Turning on `strict` in an existing codebase can produce hundreds of errors. **Stop and ask** before enabling it repo-wide; offer to enable it per package or fix errors in batches.
+- `verbatimModuleSyntax` suits ESM packages (`"type": "module"`) and bundled apps. In files that compile to CommonJS it rejects `import`/`export` syntax (you would need `import x = require()`), so leave it off for CJS packages.
+- Never weaken a compiler option to make an error go away.
+
+## 2. Type design
+
+- Model states as **discriminated unions**, not bags of optional fields:
+  `type Result = { ok: true; value: User } | { ok: false; error: string }`.
+- Narrow with `typeof`, `instanceof`, `in`, a discriminant check, or a type predicate (`(x): x is Foo`). End exhaustive `switch` statements with `default: return assertNever(x)`, where `function assertNever(x: never): never { throw new Error("Unexpected: " + String(x)) }`, so a new variant fails to compile.
+- Prefer `unknown` over `any` for values you have not checked. Parse untrusted input (HTTP bodies, `JSON.parse`, env vars, files) at the boundary with a schema library the project already uses (zod, valibot, io-ts) or a hand-written guard.
+- Use `as const` and `satisfies` to keep literal types while checking shape: `const routes = {...} satisfies Record<string, Route>`.
+- Use `readonly` arrays and properties for data you do not mutate.
+- Generics: add a type parameter only when it links two or more positions (input to output). If a parameter appears once, replace it with its constraint. Avoid conditional and mapped types in application code unless they remove real duplication.
+- Prefer `type` aliases for unions and `interface` for object shapes that are extended; follow the project if it already chose.
+- Avoid `enum`; use a union of string literals or an `as const` object. Avoid `namespace` in new code.
+
+## 3. Things never to do
+
+- `any`, `as any`, `@ts-ignore`, or `!` non-null assertions to silence an error. If a cast is truly needed, use `@ts-expect-error` with a reason, or a checked guard.
+- Double casts (`x as unknown as T`) outside tests.
+- `Function`, `Object` or `{}` as types.
+- Default exports in a codebase that uses named exports (or the reverse).
+
+## 4. Errors
+
+1. Throw `Error` subclasses, never strings or plain objects. Set `name` and pass `{ cause }` when wrapping: `throw new ConfigError("bad port", { cause: err })`.
+2. In `catch (err)`, `err` is `unknown`. Narrow before reading properties: `if (err instanceof HttpError) ...`.
+3. Catch only where you can handle, add context, or translate the error. Do not catch and log and continue unless losing the operation is acceptable.
+4. For expected failures (validation, not-found), returning a result union is often clearer than throwing. Pick one style per module.
+
+## 5. Async/await pitfalls
+
+| Pitfall | Fix |
+|---|---|
+| Floating promise: `save(x);` with no `await` | `await` it, return it, or mark intentional fire-and-forget with `void save(x).catch(log)` |
+| `arr.forEach(async x => ...)` does not wait | `for (const x of arr) await f(x)` (serial) or `await Promise.all(arr.map(f))` (parallel) |
+| Async callback passed where a sync one is expected (event handlers, `Array.filter`) | Wrap and handle the promise explicitly |
+| Sequential awaits on independent work | `await Promise.all([...])`; use `Promise.allSettled` when one failure must not cancel the rest |
+| Unbounded `Promise.all` over thousands of items | Batch, or use a concurrency limiter the project already has |
+| `return promise` inside `try` without `await` | `return await promise` so the `catch`/`finally` applies |
+| Shared mutable state across awaits (check-then-act) | Re-read after the await, or serialise with a lock/queue |
+| No timeout on network calls | `fetch(url, { signal: AbortSignal.timeout(5000) })` |
+
+Turn on `@typescript-eslint/no-floating-promises` and `@typescript-eslint/no-misused-promises` (they need type-aware linting) to catch the first three.
+
+## 6. ESM versus CommonJS
+
+- `"type": "module"` in `package.json` makes `.js` files ESM; otherwise they are CJS. `.mjs`/`.mts` are always ESM, `.cjs`/`.cts` always CJS.
+- With `module: NodeNext`, relative imports in ESM need the runtime extension: `import { x } from "./util.js"` even though the source is `util.ts`.
+- ESM has no `require`, `__dirname` or `__filename`. Use `import.meta.url` with `fileURLToPath`, or `import.meta.dirname` / `import.meta.filename` (Node 20.11+).
+- Libraries: declare entry points with `exports` (with a `types` condition first in each block). Shipping both ESM and CJS needs a build tool such as tsup; verify with `npx @arethetypeswrong/cli --pack .` before publishing.
+- With `verbatimModuleSyntax`, write `import type { Foo }` for type-only imports.
+- **Stop and ask** before changing `type`, `exports` or `main` on a published package: it is a breaking change for consumers.
+
+## 7. Project layout
+
+- Source in `src/`, build output in `dist/` (git-ignored), tests next to code (`foo.test.ts`) or in `test/`, following the project.
+- Monorepos: use the package manager's workspaces (`pnpm-workspace.yaml`, `workspaces` in `package.json`) and TypeScript project references (`composite`, `references`) when packages build separately.
+- Keep side effects out of module top level; export functions and wire them in an entry file.
+- Read config from `process.env` once, validate it, and export a typed object.
+
+## 8. Lint and format
+
+- ESLint 9+ uses flat config (`eslint.config.js`/`.mjs`). Use `typescript-eslint` with `recommendedTypeChecked` (or `strictTypeChecked`) and `parserOptions.projectService: true`.
+- Let Prettier (or Biome, if the project uses it) own formatting; disable stylistic lint rules that conflict (`eslint-config-prettier`).
+- Do not add a new linter, formatter or major dependency without asking.
+
+## 9. Finish
+
+1. Run, in this order, whatever the project defines: format check, lint, type-check, tests.
+2. Fix what you introduced. Report pre-existing failures instead of fixing them silently.
+
+## Report back
+
+End with: files changed, the commands you ran with pass/fail, any `any`/casts you could not remove and why, and anything that needs the user's decision (strictness, module system, new dependency).

package/skills/typescript-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Set up a strict tsconfig for a new Node 20 library that ships ESM",
+    "How should I type this API response so the success and error cases can't get mixed up?",
+    "Our package mixes require and import and half the files are .mjs, what's the right way to structure ESM vs CommonJS here?",
+    "Refactor this user service to stop using any and use proper unions and narrowing",
+    "Configure ESLint flat config with typescript-eslint and Prettier for our monorepo"
+  ],
+  "should_not_trigger": [
+    "Write Vitest tests for the date formatting helpers and mock the clock",
+    "Review my TypeScript pull request for unhandled promises before I merge",
+    "tsc fails with TS2307 Cannot find module '@app/config', make the build pass",
+    "Add a useMemo to stop this React component re-rendering on every keystroke",
+    "Write idiomatic Python dataclasses for the order model"
+  ]
+}

package/skills/typescript-testing/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: typescript-testing
+description: Vitest and Jest test suites for TypeScript and JavaScript projects, picking whichever runner the repo already uses, with module mocks, spies, fake timers, async assertions, fixtures, coverage thresholds and a procedure for diagnosing flaky tests. Use when writing or fixing unit and integration tests in a TS/JS codebase, mocking an import or the clock, raising coverage, or chasing a test that passes locally and fails in CI.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node.js 18+ and the project's package manager and test runner.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "node"
+  kete-loom/owner: "Kete-org"
+---
+
+# TypeScript testing
+
+Tests that run fast, fail for one reason, and give the same answer every time. Use the runner the project already has.
+
+## 0. Detect the setup
+
+1. Check `package.json` (`devDependencies`, `scripts.test`) and config files: `vitest.config.*` or a `test` block in `vite.config.*` means Vitest; `jest.config.*` or a `jest` key means Jest. `node:test` imports mean the built-in Node runner: keep using it (`node --test`, `mock` from `node:test`) and apply the rules below, not the Vitest/Jest APIs.
+2. If none exists, **stop and ask** which to add. Suggest Vitest for Vite or ESM-first projects, and Jest only if the team already knows it.
+3. Note the environment (`node`, `jsdom`, `happy-dom`), setup files, path aliases and whether globals (`describe`, `it`) are enabled or imported.
+4. Run the suite once. If it already fails, report which tests fail before changing anything.
+5. Run a single file while working: `npx vitest run path/to/file.test.ts` or `npx jest path/to/file.test.ts`. Filter by name with `-t "name"`.
+
+## 1. Write the test
+
+- One behaviour per test; name it after that behaviour (`"rejects an expired token"`).
+- Arrange, act, assert. Test through the public API of the module, not private helpers.
+- Use the narrowest matcher that says what you mean: `toEqual` for structure, `toStrictEqual` when `undefined` properties matter, `toBe` for identity and primitives, `toThrow(ErrorClass)` for errors.
+- Build test data with small factory functions (`makeUser({ role: "admin" })`) rather than large shared fixtures that every test mutates.
+- Keep fixtures in files next to tests (`__fixtures__/`) for large payloads; load them, do not inline 200 lines.
+
+## 2. Async code
+
+- Always `await` (or `return`) the promise under test. A missing `await` lets the test pass before the assertion runs.
+- Rejections: `await expect(fn()).rejects.toThrow(NotFoundError)`. Never wrap in `try/catch` without `expect.assertions(n)`.
+- Resolutions: `await expect(fn()).resolves.toEqual(value)`.
+- Do not use real `setTimeout` sleeps to wait for work; await the operation, or use fake timers.
+
+## 3. Mocks and spies
+
+Mock only boundaries: network, clock, randomness, filesystem, third-party SDKs. Never mock the unit under test.
+
+| Need | Vitest | Jest |
+|---|---|---|
+| Mock a module | `vi.mock("./db", () => ({ query: vi.fn() }))` | `jest.mock("./db", () => ({ query: jest.fn() }))` |
+| Keep the rest of the real module | `vi.mock(import("./db"), async (orig) => ({ ...(await orig()), query: vi.fn() }))` | `jest.mock("./db", () => ({ ...jest.requireActual("./db"), query: jest.fn() }))` |
+| Variable used inside a mock factory | `const m = vi.hoisted(() => vi.fn())` | name it with a `mock` prefix |
+| Spy on a method | `vi.spyOn(obj, "method")` | `jest.spyOn(obj, "method")` |
+| Typed mock | `vi.mocked(fn)` | `jest.mocked(fn)` |
+| Reset between tests | `vi.restoreAllMocks()` in `afterEach`, or `restoreMocks: true` in config | `restoreMocks: true` in config |
+
+- `vi.mock` and `jest.mock` are hoisted above imports, so a factory cannot reference normal top-level variables.
+- Jest with native ESM cannot use `jest.mock` on ESM imports; use `jest.unstable_mockModule` followed by a dynamic `await import()`, or run Jest through a CJS transform.
+- For HTTP, prefer intercepting at the network layer (`msw`, `nock`, or `undici` `MockAgent`) over mocking `fetch` by hand, if the project already has one of them.
+- Assert on what matters (`toHaveBeenCalledWith(expected)`), not on call counts that are an implementation detail.
+
+## 4. Timers and dates
+
+```ts
+beforeEach(() => { vi.useFakeTimers(); vi.setSystemTime(new Date("2025-01-01T00:00:00Z")); });
+afterEach(() => { vi.useRealTimers(); });
+
+it("retries after 1s", async () => {
+  const p = withRetry(task);
+  await vi.advanceTimersByTimeAsync(1000);   // async variant flushes promises between timers
+  await expect(p).resolves.toBe("ok");
+});
+```
+
+Jest equivalents: `jest.useFakeTimers()`, `jest.setSystemTime()`, `jest.advanceTimersByTimeAsync()`. Always restore real timers in `afterEach`.
+
+## 5. Coverage
+
+- Vitest: `npx vitest run --coverage` (needs `@vitest/coverage-v8` or `@vitest/coverage-istanbul`). Jest: `npx jest --coverage`.
+- Set thresholds in config (`test.coverage.thresholds` in Vitest, `coverageThreshold` in Jest) only if the team wants them enforced.
+- Read the uncovered-lines report and test the **branches** that matter (error paths, boundaries). Do not write tests that only execute lines without asserting.
+
+## 6. Flaky tests
+
+Follow this order and stop when you find the cause:
+
+1. Reproduce: run the single test many times (a shell loop or the runner's repeat option) and the whole file in random order (Vitest `--sequence.shuffle`, Jest `--randomize`).
+2. Run it alone and with the full suite. Passing alone but failing together means **shared state**: module-level variables, unrestored mocks, leftover DB rows, `process.env` changes. Reset in `beforeEach`/`afterEach`.
+3. Look for real time (`Date.now()`, `new Date()`), real timers, randomness, or locale/timezone (`TZ=UTC` in the test script).
+4. Look for missing `await`, unawaited promises in setup, or assertions on work still in progress.
+5. Look for real network, ports already in use, or order-dependent file writes. Use temp dirs (`fs.mkdtemp`) and port `0`.
+6. CI-only failures: compare Node version, CPU count (worker pools), and environment variables.
+
+Never fix flakiness by adding retries, longer timeouts or `.skip` without telling the user; those hide the bug.
+
+## Rules
+
+- Never delete, skip or loosen an existing assertion to get green. If a test is wrong, explain why and ask first.
+- No real network calls, no real time, no dependence on test order.
+- Do not add a new test runner or mocking library without asking.
+
+## Report back
+
+End with: tests added or changed (file and name), the command you ran, pass/fail counts, coverage change if measured, and for a flaky test the root cause you found.

package/skills/typescript-testing/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write Vitest unit tests for the invoice calculator in src/billing",
+    "How do I mock the ./db module in Jest but keep the rest of its real exports?",
+    "This retry test uses setTimeout and takes 30 seconds, use fake timers instead",
+    "Our auth.test.ts passes locally but fails randomly in CI, find out why",
+    "Get coverage on the payments package above 80% with jest --coverage"
+  ],
+  "should_not_trigger": [
+    "Set up a strict tsconfig and decide between ESM and CommonJS for the new package",
+    "Write Playwright end-to-end tests for the signup flow in the browser",
+    "Review this TypeScript diff for type holes and async races",
+    "npm run build fails with ERR_REQUIRE_ESM after upgrading a dependency, fix it",
+    "Write pytest fixtures for the Django order views"
+  ]
+}

package/skills/ui-demo-recording/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: ui-demo-recording
+description: Produces polished, repeatable product demo videos and feature walkthroughs of a web app by scripting the story as a Playwright run with recordVideo, seeding fixed demo data and a frozen clock, pacing actions for a human viewer, injecting a visible cursor and click ripples, adding captions or chapter titles, then trimming, scaling and encoding the WebM with FFmpeg into MP4 or GIF. Use when marketing, docs or a release note needs a screen recording of the app, when an existing demo video is out of date after a UI change, or when the same walkthrough must be re-recorded on every release.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node 18+, the @playwright/test or playwright package with a Chromium browser installed, and ffmpeg. The app must run locally or on a staging URL with demo data.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "node, npx, ffmpeg"
+  kete-loom/owner: "Kete-org"
+---
+
+# UI demo recording
+
+A demo video is a script, not a screen grab. Write the walkthrough as code so it records identically every time, looks like a calm human is driving, and can be re-run after the next UI change. This skill makes videos for people to watch; for tests that assert behaviour, use the `e2e-testing-playwright` skill.
+
+## 0. Agree the storyboard
+
+Ask the user (stop until you have answers):
+
+1. **Story**: the 3 to 7 steps the viewer should see, and the one outcome to end on.
+2. **Output**: length target, resolution (1920x1080 or 1280x720 for docs, 1080x1920 for vertical), MP4, WebM or GIF, with or without captions.
+3. **Environment**: local or staging URL, a demo account, and confirmation that **no real customer data** appears.
+4. **Branding**: light or dark theme, browser chrome or none (Playwright records the page only, without browser chrome).
+
+Write the storyboard as a numbered list of scenes, each with an action, the on-screen caption and a hold time. Get a yes before recording.
+
+## 1. Make the app deterministic
+
+The recording must look the same on every run.
+
+- **Data**: seed a dedicated demo tenant or database with believable fake names, round numbers and no lorem ipsum. Reset it before each recording.
+- **Time**: freeze the clock so dates and "5 minutes ago" labels are stable (`page.clock.setFixedTime` in Playwright 1.45+; see `references/playwright-recording.md`).
+- **Network noise**: block analytics, chat widgets and cookie banners with `page.route`, or set the consent cookie in advance.
+- **Randomness**: disable onboarding tours, A/B variants and "what's new" pop-ups through feature flags or localStorage before the first navigation.
+- **Login**: sign in once in setup and save `storageState`; never record typing a real password.
+- **Animations**: keep the app's own animations (they look good on video), but wait for them to finish before the next action.
+
+## 2. Write the recording script
+
+Use a plain Playwright library script (or a dedicated Playwright Test project) separate from the test suite. Skeleton in `references/playwright-recording.md`.
+
+1. Create the context with `viewport` equal to the output size and `recordVideo: { dir, size }` set to the same size, plus `deviceScaleFactor: 1`. A mismatch gives blurry or letterboxed video.
+2. Inject the cursor overlay with `context.addInitScript` before the first page loads (`references/cursor-and-captions.md`).
+3. Drive each scene with role-based locators, moving the mouse to the target first (`page.mouse.move` with `steps`) so the viewer sees the pointer travel, then click.
+4. Type with `locator.pressSequentially(text, { delay: 40 to 80 })` so typing is visible; use `fill` for fields the viewer does not need to watch.
+5. Hold after each meaningful change (`page.waitForTimeout(800 to 1500)`). Holds are fine here because this is a recording, not a test; always wait for the visible result first (`expect(locator).toBeVisible()` or `locator.waitFor()`).
+6. Show captions or chapter titles through the overlay, or leave them for post-production (step 4).
+7. Close the context (`await context.close()`): the video file is only finished then. Get the path from `page.video().path()` or `saveAs`.
+
+## 3. Review the raw take
+
+Play it back at full speed and check:
+
+- [ ] Every scene from the storyboard appears in order, nothing extra.
+- [ ] No spinners, flashes of unstyled content, error toasts, scrollbars jumping or debug panels.
+- [ ] No real personal data, internal URLs, API keys or staff names visible.
+- [ ] The cursor is visible and never teleports.
+
+If a scene is flaky, fix the wait in the script; do not cut around it in the edit.
+
+## 4. Post-process with FFmpeg
+
+Recipes in `references/post-processing.md`:
+
+1. Trim the blank first frames and the tail after the last hold.
+2. Convert WebM to H.264 MP4 with `yuv420p` and `+faststart` for the web.
+3. Optionally speed up dull stretches, add a title card or fade, burn in or attach captions (SRT or WebVTT), and add a music bed at low level if the user supplies a licensed track.
+4. For GIF, use the two-pass palette method, at most about 15 fps and 800 px wide, and keep it short.
+5. Probe the output (duration, resolution, size) before handing it over.
+
+## 5. Make it repeatable
+
+- Commit the script, the seed data and the storyboard next to each other (for example `demos/<name>/`).
+- Add an npm script such as `"demo:onboarding": "node demos/onboarding/record.mjs"`.
+- If the user wants it refreshed each release, run it in CI against staging and upload the MP4 as an artifact; a human approves before it replaces the published video.
+
+## Never
+
+- Never record production with real customer accounts or data.
+- Never leave real credentials in the script; read them from the environment for a demo-only account.
+- Never publish a recording without the user watching it first.
+
+## Report back
+
+```
+Demo: <name>   Length: mm:ss   Output: <path> (WxH, fps, MB)
+Script: <path>   Seed: <path>   Run: <command>
+Scenes: 1 ... 2 ... (one line each with start time)
+Checks: data is fake, no secrets on screen, cursor visible
+Known gaps: ...
+```

package/skills/ui-demo-recording/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Record a 60-second demo video of our signup and first project flow for the landing page",
+    "Our product walkthrough video is out of date after the redesign, script it so we can re-record it every release",
+    "Make a Playwright script that records the dashboard demo with a visible cursor and click highlights",
+    "Turn the recorded WebM of our app tour into an MP4 and a small GIF for the release notes",
+    "Capture a screencast of the checkout feature with fake demo data and captions explaining each step"
+  ],
+  "should_not_trigger": [
+    "Write Playwright tests that check the checkout flow still works after each deploy",
+    "Our Playwright suite fails in CI on the login test, find out why",
+    "Cut my interview footage into a three-minute story with B-roll",
+    "Build an animated explainer video in React with spring animations",
+    "Click through the staging app and look for bugs in the settings page"
+  ]
+}

package/skills/ui-demo-recording/references/cursor-and-captions.md

@@ -0,0 +1,48 @@
+# Cursor highlight and caption overlay
+
+Headless Chromium does not draw the OS cursor into the video, so draw one in the page. Pass this function to `context.addInitScript` so it runs before every page's scripts.
+
+```js
+// demos/onboarding/cursor-overlay.mjs
+export function cursorOverlay() {
+  const install = () => {
+    if (document.getElementById('__demo-cursor')) return;
+    const style = document.createElement('style');
+    style.textContent = `
+      #__demo-cursor { position: fixed; top: 0; left: 0; width: 22px; height: 22px; margin: -11px 0 0 -11px;
+        border-radius: 50%; background: rgba(255,255,255,.9); border: 2px solid rgba(0,0,0,.6);
+        box-shadow: 0 1px 4px rgba(0,0,0,.35); pointer-events: none; z-index: 2147483647;
+        transition: transform .08s ease-out; }
+      #__demo-cursor.down { transform: scale(.75); }
+      .__demo-ripple { position: fixed; width: 44px; height: 44px; margin: -22px 0 0 -22px; border-radius: 50%;
+        border: 3px solid rgba(59,130,246,.8); pointer-events: none; z-index: 2147483646;
+        animation: __demo-r .5s ease-out forwards; }
+      @keyframes __demo-r { from { transform: scale(.3); opacity: 1 } to { transform: scale(1.4); opacity: 0 } }
+      #__demo-caption { position: fixed; left: 50%; bottom: 48px; transform: translateX(-50%); max-width: 70%;
+        padding: 12px 20px; border-radius: 10px; background: rgba(17,24,39,.85); color: #fff;
+        font: 600 28px/1.3 system-ui, sans-serif; text-align: center; pointer-events: none;
+        z-index: 2147483647; opacity: 0; transition: opacity .25s; }
+      #__demo-caption.on { opacity: 1; }`;
+    document.head.appendChild(style);
+    const c = document.createElement('div'); c.id = '__demo-cursor';
+    const cap = document.createElement('div'); cap.id = '__demo-caption';
+    document.body.append(c, cap);
+    addEventListener('mousemove', (e) => { c.style.left = e.clientX + 'px'; c.style.top = e.clientY + 'px'; }, true);
+    addEventListener('mousedown', (e) => {
+      c.classList.add('down');
+      const r = document.createElement('div'); r.className = '__demo-ripple';
+      r.style.left = e.clientX + 'px'; r.style.top = e.clientY + 'px';
+      document.body.appendChild(r); setTimeout(() => r.remove(), 600);
+    }, true);
+    addEventListener('mouseup', () => c.classList.remove('down'), true);
+    window.__demoCaption = (t) => { cap.textContent = t; cap.classList.toggle('on', !!t); };
+  };
+  if (document.body) install(); else addEventListener('DOMContentLoaded', install);
+}
+```
+
+Rules:
+- The overlay has `pointer-events: none` so it never intercepts clicks.
+- Keep captions short (one line, under about 50 characters) and on screen for at least 1.5 seconds.
+- If captions must be translatable or editable later, produce an SRT in post-processing instead of burning them into the page.
+- A strict Content-Security-Policy can block injected styles in some apps; if the overlay is missing, run against a demo build that relaxes CSP, or use `bypassCSP: true` on the context.