@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/email-deliverability/references/dns-records.md

@@ -0,0 +1,85 @@
+# DNS record shapes
+
+Replace `example.com`, selectors and provider includes with the user's values. Always read existing records first.
+
+## SPF (RFC 7208)
+
+One TXT record at each name that appears as an envelope sender (Return-Path).
+
+```
+example.com.        TXT "v=spf1 include:_spf.google.com include:amazonses.com ~all"
+```
+
+- Only one `v=spf1` record per name. Two records is a `permerror`.
+- At most 10 DNS-querying mechanisms (`include`, `a`, `mx`, `ptr`, `exists`, `redirect`), counted recursively. Over 10 is a `permerror`, which counts as a fail.
+- To get under 10: move senders to subdomains (each subdomain has its own SPF), remove services no longer used, or replace an `include` with `ip4:`/`ip6:` ranges only if the provider publishes stable ones.
+- `~all` (softfail) is normal once DMARC is in place; `-all` is fine when the list is complete. Never `+all`.
+- A domain that never sends mail: `v=spf1 -all`.
+
+## DKIM
+
+The provider gives the selector and key, usually as a CNAME so it can rotate keys.
+
+```
+s1._domainkey.example.com.  CNAME  s1.domainkey.u123.wl.provider.net.
+s1._domainkey.example.com.  TXT    "v=DKIM1; k=rsa; p=MIIBIjANBgkq..."
+```
+
+- Use 2048-bit RSA where offered. Long TXT values may need splitting into several quoted strings; most DNS hosts do this for you.
+- Check: `dig +short TXT s1._domainkey.example.com`. In a received message, `DKIM-Signature: d=` must be your domain for alignment.
+
+## DMARC (RFC 9989, which obsoletes RFC 7489)
+
+```
+_dmarc.example.com.  TXT  "v=DMARC1; p=none; rua=mailto:dmarc-reports@example.com; adkim=r; aspf=r"
+```
+
+| Tag | Meaning |
+|---|---|
+| `p` | `none` (monitor), `quarantine`, `reject` |
+| `sp` | policy for subdomains, defaults to `p` |
+| `rua` | where aggregate XML reports go; use a mailbox or a DMARC report service |
+| `pct` | RFC 7489 only: share of failing mail the policy applies to, default 100. RFC 9989 removed it (along with `rf` and `ri`) and added `t=y`, a test flag asking receivers to apply one policy level lower. Older receivers may still read `pct`; do not depend on it for rollout |
+| `adkim` / `aspf` | `r` relaxed (organisational domain match, the default) or `s` strict |
+
+Reports sent to a different domain need an authorisation record at that domain (`example.com._report._dmarc.reports.net TXT "v=DMARC1"`); report services set this up.
+
+Rollout: `p=none` for a few weeks (2 to 4 is a rule of thumb), then `p=quarantine`, then `p=reject`. Rolling out per subdomain with `sp=` is a safer stage than `pct`.
+
+## BIMI
+
+```
+default._bimi.example.com.  TXT  "v=BIMI1; l=https://example.com/bimi/logo.svg; a=https://example.com/bimi/vmc.pem"
+```
+
+- Requires DMARC at `quarantine` or `reject` on the organisational domain; Gmail also requires `pct=100` if `pct` is present.
+- `l=` is an HTTPS URL to an SVG Tiny PS file. `a=` is the PEM certificate (Gmail accepts a VMC or a CMC; other providers set their own rules).
+- Display is at the mailbox provider's discretion even when everything validates.
+
+## One-click unsubscribe headers (RFC 8058)
+
+```
+List-Unsubscribe: <https://example.com/unsub?t=opaque-token>, <mailto:unsub@example.com?subject=unsub>
+List-Unsubscribe-Post: List-Unsubscribe=One-Click
+```
+
+- The HTTPS endpoint must accept a POST with body `List-Unsubscribe=One-Click` and unsubscribe without further confirmation or login.
+- Both headers must be covered by the DKIM signature.
+- The token identifies the recipient and list; it must not be guessable or expose the address.
+
+## Useful checks
+
+```
+dig +short TXT example.com
+dig +short TXT _dmarc.example.com
+dig +short TXT default._bimi.example.com
+dig +short -x <sending-ip>        # reverse DNS (PTR)
+```
+
+## Sources
+
+- Gmail sender guidelines: https://support.google.com/a/answer/81126 and FAQ (48-hour unsubscribe): https://support.google.com/a/answer/14229414
+- Outlook.com high-volume senders (`550 5.7.515`): https://support.microsoft.com/en-us/outlook/fix-ndr-error-550-5-7-515-in-outlook-com
+- Gmail BIMI: https://knowledge.workspace.google.com/admin/security/set-up-bimi
+- SPF: https://www.rfc-editor.org/rfc/rfc7208 . DMARC: https://www.rfc-editor.org/rfc/rfc9989 . One-click unsubscribe: https://www.rfc-editor.org/rfc/rfc8058
+- CAN-SPAM: https://www.ftc.gov/business-guidance/resources/can-spam-act-compliance-guide-business

package/skills/error-handling-patterns/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: error-handling-patterns
+description: Language-agnostic rules for designing how code fails, covering when to crash versus recover, typed and wrapped errors with context, retry with exponential backoff and jitter only for idempotent work, timeouts on every remote call, and separating what the user sees from what gets logged. Use when writing or restructuring try/catch, Result or error-return code, adding retries or timeouts to a network client, or deciding what an API should return on failure.
+license: MIT
+compatibility: Any Agent Skills host. No tools required beyond the project's own test runner.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Error handling patterns
+
+Every error is either handled (something useful happens) or propagated (with context). Nothing in between.
+
+## 0. Before you change anything
+
+1. Find the project's existing error conventions: a base error class, an error-code enum, a `Result` type, a logging helper, an HTTP error middleware. Search for them before inventing new ones.
+2. Find where errors finally land: top-level handler, request middleware, job runner, CLI `main`. That is where logging and user messages belong.
+3. If the project has none of this and the change needs it, **stop and ask the user** whether to introduce a convention or keep it local.
+
+## 1. Classify the failure first
+
+| Kind | Examples | Default action |
+|---|---|---|
+| Programmer bug | null where impossible, broken invariant, bad index | Fail fast. Crash or throw; do not catch. |
+| Invalid input | bad request body, unknown CLI flag, malformed file | Reject at the boundary with a precise message. Do not retry. |
+| Expected domain outcome | not found, insufficient funds, already exists | Return it as a value or a typed error the caller must handle. |
+| Transient infrastructure | timeout, connection reset, 429, 503, deadlock | Retry with backoff if the operation is idempotent; otherwise surface. |
+| Fatal environment | missing config, disk full, bad credentials at startup | Fail at startup with a clear message, not on first request. |
+
+Decision rule: if you cannot name what the caller should do differently for an error, it is not a separate type. Do not create one error class per function.
+
+## 2. Raise and wrap with context
+
+- Throw or return the most specific type the project already has.
+- When propagating, add what *this* layer knows (the ID, the file path, the operation) and keep the original as the cause. Idioms per language are in `references/language-idioms.md`.
+- Wrap once per layer that adds information. Do not re-wrap the same error at every stack frame.
+- Never build an error message from secrets, tokens, full request bodies or personal data.
+- Never use exceptions for normal control flow (loop exits, "not found" in a hot path) where the language offers a value.
+
+## 3. Catch only what you can handle
+
+A catch block is justified only if it does one of these:
+
+1. Recovers: retries, falls back to a value that is **correct** for the caller, or takes a compensating action.
+2. Translates: converts a low-level error into the layer's own type, keeping the cause.
+3. Reports at the edge: logs once and converts to a user response or exit code.
+4. Cleans up and rethrows (prefer `finally`, `defer`, `using`, `with`, RAII instead).
+
+Never:
+- Leave a catch block empty, or with only a comment.
+- Catch the broadest type (`Exception`, `Throwable`, bare `except:`, `catch (e)`) except at the top-level edge.
+- Log and rethrow at every layer; you get the same error five times in the logs.
+- Return a default (`null`, `[]`, `0`, `false`) that the caller cannot tell apart from a real result.
+- Ignore a returned error value or an unawaited promise or future.
+
+## 4. Retries
+
+Retry only when **all** are true:
+
+- The failure is transient (timeouts, connection errors, 408, 429, 502, 503, 504, database serialisation or deadlock errors).
+- The operation is idempotent, or you send an idempotency key the server honours. A non-idempotent POST that timed out may already have succeeded.
+- There is a cap on attempts (typically 3 to 5) and on total time.
+
+How:
+1. Exponential backoff with jitter: `sleep = random(0, min(cap, base * 2^attempt))`. Without jitter, clients retry in lockstep.
+2. Honour a `Retry-After` header when the server sends one.
+3. Retry at one layer only. Retries in the HTTP client, the SDK and the job queue multiply.
+4. Log each retry at debug or warn with the attempt number; log the final failure at error.
+5. For writes that must not run twice (payments, emails, stock changes), generate the idempotency key once per logical operation and reuse it on every attempt.
+
+Prefer the retry helper the project or SDK already ships over a hand-written loop.
+
+## 5. Timeouts and cancellation
+
+- Every network call, queue read, lock wait and subprocess gets an explicit timeout. Library defaults are often infinite.
+- Pass the caller's deadline or cancellation token down (`context.Context`, `AbortSignal`, `CancellationToken`) instead of starting fresh timers at each layer.
+- The inner timeout must be shorter than the outer one, or retries never get a chance.
+- On timeout, treat the outcome of a write as unknown, not failed. Reconcile or use an idempotency key.
+
+## 6. What the user sees vs what is logged
+
+| Audience | Gets |
+|---|---|
+| End user / API client | A stable error code, a short human message, a correlation or request ID. No stack traces, SQL, paths or internal hostnames. |
+| Logs | The full error chain, stack trace, operation, relevant IDs, correlation ID. No secrets or personal data. |
+
+- Log each error exactly once, at the place that handles it (usually the edge).
+- Use the level that matches action needed: error means someone should look; expected domain outcomes are info or not logged.
+- Map error types to status codes or exit codes in one place, not scattered through handlers.
+
+## 7. Verify
+
+1. Write or update a test for each new error path: the error type or code returned, the message the user sees, and that cleanup ran.
+2. For retries, test with a fake that fails N times then succeeds, and one that always fails; assert the attempt count and that non-idempotent calls are not retried.
+3. For timeouts, test with a fake that never responds.
+4. Run the full test suite. Do not report done while it is red.
+
+## Report format
+
+When you finish, report:
+
+```
+Error handling changes
+- <file:line> <what changed> (<kind from step 1>)
+Retries: <where, policy, idempotency guarantee> | none
+Timeouts: <where, value> | none
+Tests: <command run> -> <pass/fail>
+Open questions: <anything you stopped to ask, or none>
+```

package/skills/error-handling-patterns/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Add retries with exponential backoff to our HTTP client for the shipping API",
+    "How should this service decide between crashing and recovering when the config file is missing?",
+    "Restructure the error handling in the order service so we stop leaking stack traces to API clients",
+    "Wrap these database errors with context so the logs tell us which customer failed",
+    "Our outbound calls hang forever sometimes, add timeouts and cancellation properly",
+    "Design the error types for this new payments module"
+  ],
+  "should_not_trigger": [
+    "Scan this module for empty catch blocks and swallowed errors and report them",
+    "Fix the TypeScript compile error in src/api/client.ts",
+    "Refactor this class into smaller functions without changing behaviour",
+    "Review my diff for bugs before I open the pull request",
+    "Integrate Paystack webhooks into our checkout flow",
+    "The checkout endpoint is slow, profile it and find the bottleneck"
+  ]
+}

package/skills/error-handling-patterns/references/language-idioms.md

@@ -0,0 +1,49 @@
+# Error idioms by language
+
+Read the section for the language you are editing. Follow the project's existing conventions when they differ.
+
+## TypeScript / JavaScript
+
+- Wrap with a cause: `throw new Error("loading invoice " + id, { cause: err })`.
+- Subclass `Error` for types callers branch on; set `this.name`.
+- In `catch (err)`, treat `err` as `unknown` (it is, under `strict` / `useUnknownInCatchVariables`): narrow with `instanceof` before reading fields. Anything can be thrown, not only `Error`.
+- Every promise is awaited, returned, or explicitly handled. Lint with `@typescript-eslint/no-floating-promises`.
+- Timeouts: `fetch(url, { signal: AbortSignal.timeout(5000) })`; pass an `AbortSignal` down for cancellation.
+- ESLint `no-empty` flags empty catch blocks.
+
+## Python
+
+- Wrap with `raise LoadError(f"loading invoice {id}") from err`. Use `from None` only to hide an irrelevant cause deliberately.
+- Catch specific exceptions. Bare `except:` also catches `KeyboardInterrupt` and `SystemExit`.
+- Use `with` for cleanup. Use `logger.exception(...)` inside `except` to keep the traceback.
+- Timeouts: `requests` has none by default; always pass `timeout=`. `httpx` defaults to 5 seconds.
+- Ruff rules `BLE001` (blind except) and `S110` (try-except-pass) find swallowed errors.
+
+## Go
+
+- Wrap with `fmt.Errorf("loading invoice %s: %w", id, err)`; inspect with `errors.Is` and `errors.As`.
+- Sentinel errors (`var ErrNotFound = errors.New("not found")`) for conditions callers check.
+- Never `_ =` an error without a comment saying why it is safe.
+- Pass `ctx context.Context` first; use `context.WithTimeout` and always `defer cancel()`.
+- `errcheck` (also in `golangci-lint`) finds unchecked errors.
+
+## Rust
+
+- `Result<T, E>` for recoverable errors; `panic!` only for bugs.
+- Libraries: a typed error enum (often with `thiserror`). Applications: `anyhow` with `.context("loading invoice")`.
+- `?` propagates; `.unwrap()` and `.expect()` only where failure is a bug, with an `expect` message saying why.
+- `#[must_use]` on functions whose result must not be ignored.
+
+## Java / Kotlin
+
+- Wrap with the cause constructor: `new LoadException("loading invoice " + id, e)`.
+- Use try-with-resources (Java) or `use {}` (Kotlin) for cleanup.
+- Do not catch `Throwable` or `Error`. In Kotlin coroutines, rethrow `CancellationException`.
+- Set connect and read timeouts on every HTTP client explicitly.
+
+## C#
+
+- Rethrow with `throw;` not `throw ex;` (which resets the stack trace).
+- Wrap with `new LoadException("...", ex)` using the inner-exception constructor.
+- Use `using` / `await using` for cleanup; pass `CancellationToken` through async calls.
+- Filter with `catch (HttpRequestException ex) when (ex.StatusCode == HttpStatusCode.ServiceUnavailable)`.

package/skills/estimation-and-scoping/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: estimation-and-scoping
+description: Software effort estimation and scope negotiation that breaks a project into small tasks, gives each a best, likely and worst case instead of a single number, surfaces unknowns and time-boxed spikes to resolve them, adds integration, review and release overhead, and offers concrete scope cuts that fit a deadline, finishing with a range and a stated confidence level. Use when someone asks how long a feature or project will take, needs a quote or a sizing for planning, has a fixed date and must decide what to cut, or wants to know why an earlier estimate was wrong.
+license: MIT
+compatibility: Any Agent Skills host. Reads the codebase to size the work; no other tools needed.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: docs
+  kete-loom/risk: read-only
+  kete-loom/owner: "Kete-org"
+---
+
+# Estimation and scoping
+
+An estimate is a range with a confidence level and the assumptions it depends on. It is not a promise. Give the reader what they need to make a decision: how big, how sure, and what would change it.
+
+## 0. Pin down the question
+
+1. What exactly is being estimated, and what does "done" mean (merged, released to all users, documented, migrated)? If unclear, **ask the user** before estimating.
+2. Who is doing the work, how much of their time is available, and in what unit the answer is wanted (engineer-days, calendar weeks, story points). Calendar time is effort divided by real availability, not by headcount alone.
+3. Is the date or the scope fixed? If the date is fixed, the job is scoping (section 4), not estimating.
+4. If a PRD or plan exists, read it. If the requirements are vague, estimate only the parts that are defined and list the rest as unknowns.
+
+## 1. Break it down
+
+- Read the code the work touches: search for the modules, endpoints, tables and tests involved. Note anything unexpectedly tangled.
+- Split into tasks of roughly half a day to three days each. Anything bigger is not understood yet; split again or mark it as an unknown.
+- Include the work people forget: tests, migrations and backfills, config and feature flags, docs, code review rounds, QA, deploy and rollout, monitoring, and handling feedback after release.
+- Note dependencies on other teams, approvals, vendors or environments. Waiting time goes in the calendar estimate even though it is not effort.
+
+## 2. Estimate each task as a range
+
+For each task give best case (B), likely case (L) and worst case (W) in the same unit.
+
+- B: everything goes right. W: the realistic bad case, not the apocalypse.
+- A wide B-to-W spread is information; do not narrow it to look confident.
+- Roll-up: the common three-point (PERT) expected value per task is E = (B + 4L + W) / 6. Sum the E values for the planning number; do not sum likely cases, which understates the total because overruns are larger than underruns. Summed B and summed W give the outer range ends, but say that summed W overstates the bad tail, since not every task goes wrong at once.
+- Use history if it exists: how long similar past work took, from tickets or git history. Prefer that over gut feel and say which you used.
+
+## 3. Unknowns and spikes
+
+- List every unknown: unfamiliar API, unclear requirement, performance not yet measured, legacy code nobody owns, a dependency's readiness.
+- For each, either propose a **spike**: a time-boxed investigation (for example "2 days to prototype the vendor webhook and confirm rate limits") with the question it must answer, or carry it as a risk that widens the range.
+- When unknowns dominate, recommend estimating in two stages: commit only to the spikes now, re-estimate after them.
+
+## 4. Scope to fit
+
+When the range does not fit the date or budget, offer options instead of squeezing the numbers:
+
+- Cut or defer Should and Could requirements; name each and its saving.
+- Ship a thinner first version: one platform, one customer segment, manual steps behind the scenes, no admin UI, a lower limit.
+- Buy or reuse instead of build.
+- Add people only when the work splits cleanly and there is time to onboard them; say this rarely shortens a late project.
+- Make each option concrete: what is cut, what the user loses, the new range.
+
+Never quietly lower an estimate because the requester wants a smaller number. If pushed, restate the range and offer scope cuts.
+
+## 5. Communicate confidence
+
+- State the range and a confidence level in plain words: "4 to 7 weeks; about 70% confident we finish within 7".
+- Say what the estimate assumes (staffing, no major requirement changes, the spike result) and what would move it.
+- Name the checkpoint where you will re-estimate (after the spike, at the halfway mark).
+- Use the unit asked for. If asked for story points, give points but still list the unknowns.
+
+## Output format
+
+```
+## Estimate: <work item>
+Done means: <definition>
+Assumes: <people, availability, fixed scope, other assumptions>
+
+| # | Task | Best | Likely | Worst | Notes |
+|---|------|------|--------|-------|-------|
+| 1 | ...  | 1d   | 2d     | 4d    | touches billing/invoice.ts |
+
+Effort: <sum best> to <sum worst> (expected <sum of PERT E>) engineer-days
+Calendar: <range> at <availability>, including waits on <dependencies>
+Confidence: <level and what it means>
+Unknowns and spikes: <list with time boxes>
+Scope options if it must be smaller: <option, saving, user cost>
+Re-estimate at: <checkpoint>
+```
+
+## Reviewing why an estimate was wrong
+
+Compare the original breakdown to what happened: tasks that were missing entirely, tasks that grew, waiting time, scope added mid-way, availability lower than assumed. Report the biggest causes and one change to the next estimate for each. Do not assign blame.
+
+## Never
+
+- Never give a single number without a range and its assumptions.
+- Never estimate work you have not broken down; say you need to break it down first.
+- Never present a guess about someone else's team as fact; mark it and suggest asking them.
+
+## Neighbours
+
+- Writing the requirements being sized: `prd-writing`.
+- An ordered implementation plan with files and tests: the `planner` agent or `/plan-feature`.

package/skills/estimation-and-scoping/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "How long will it take to add SSO login to our app? Give me a range, not one number",
+    "We have to launch the mobile checkout by March 1. Look at the scope and tell me what to cut to make that date",
+    "Size this epic for quarterly planning, call out the unknowns and suggest spikes",
+    "Our last project was estimated at 3 weeks and took 9. Help me figure out why and estimate the next one better"
+  ],
+  "should_not_trigger": [
+    "Write the product requirements doc for SSO login with acceptance criteria",
+    "List the files I need to change to add SSO and the order to change them in",
+    "Estimate how much this AWS setup will cost per month",
+    "Benchmark the checkout endpoint and tell me its p99 latency"
+  ]
+}

package/skills/evm-dapp-integration/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: evm-dapp-integration
+description: Connects web frontends and backends to Ethereum and EVM chains with viem (optionally wagmi) or ethers v6, covering EIP-1193 and EIP-6963 wallet discovery and connection, checking and switching chain IDs, typed contract reads, simulating before writes, token amounts kept as bigint with parseUnits and formatUnits against each token's decimals, the transaction lifecycle from signature to receipt status and confirmations, replaced or dropped transactions, event logs, and RPC rate limits and block-range caps. Use when adding a connect-wallet button, calling a deployed contract from a dapp or Node service, displaying or sending ERC-20 amounts, or debugging stuck transactions and RPC errors.
+license: MIT
+compatibility: Any Agent Skills host. Needs Node.js 18+ and the project's package manager; examples use viem 2.x and ethers 6.x. Live calls need an RPC endpoint and network access.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# EVM dapp integration
+
+Make the app talk to the chain without losing precision, sending to the wrong network, or telling the user "done" before the chain agrees. Private keys belong to the user's wallet, not your code. This is engineering guidance, not financial advice.
+
+## Ground rules
+
+1. **Amounts are `bigint` in base units, end to end.** Convert at the edges only: `parseUnits(input, decimals)` from user text, `formatUnits(value, decimals)` for display (both in viem and ethers v6). Never use `Number`, `parseFloat` or JavaScript floats for token amounts; never assume 18 decimals (USDC and USDT are 6 on most chains). Read `decimals()` from the token or a reviewed token list.
+2. **Check the chain ID before every write.** Compare the wallet's chain to the one your contract addresses belong to; prompt a switch (`switchChain` in viem/wagmi, `wallet_switchEthereumChain` via EIP-1193) rather than sending on the wrong network. Keep contract addresses in a map keyed by chain ID.
+3. **Simulate, then write.** viem: `publicClient.simulateContract(...)` then `walletClient.writeContract(request)`. ethers v6: `contract.fn.staticCall(...)` or `estimateGas` before sending. Show the decoded revert reason if the simulation fails.
+4. **A hash is not a success.** `writeContract`/`sendTransaction` returns only a hash. Wait for the receipt (`waitForTransactionReceipt({ hash, confirmations })` in viem, `await tx.wait(confirmations)` in ethers) and check it: viem returns the receipt with `status` `'success'` or `'reverted'` (it does not throw on revert); ethers v6 `wait()` throws a `CALL_EXCEPTION` error when the receipt status is `0`, so catch it.
+5. **No private keys in frontends.** Browser code signs through the user's wallet only. Backend signers load keys from a secret manager or KMS, never from the repo or a `NEXT_PUBLIC_`/`VITE_` variable.
+6. **Treat chain data as untrusted input.** Token names, symbols and metadata URIs can be anything; escape them before rendering.
+
+## Library choice
+
+| Situation | Use |
+|---|---|
+| React app with wallets | wagmi on top of viem, with a connector kit if the project already has one |
+| Non-React frontend or Node service | viem `createPublicClient` / `createWalletClient` with `http()` or `webSocket()` transport |
+| Existing ethers codebase | stay on ethers v6 (`BrowserProvider`, `JsonRpcProvider`, `Contract`); don't mix libraries in one module |
+
+Generate types from ABIs (`as const` ABI with viem, or TypeChain/wagmi CLI) so function names and argument types are checked at compile time.
+
+## Steps
+
+1. **Config**: chains the app supports, RPC URLs per chain from environment variables, contract addresses per chain ID, ABIs as `const` exports. Use a paid or self-hosted RPC for production; public endpoints rate-limit hard.
+2. **Wallet connection**: discover injected wallets with EIP-6963 (wagmi and most kits do this), fall back to `window.ethereum` (EIP-1193). Request accounts only on a user click. Listen for `accountsChanged` and `chainChanged` and reset app state on both.
+3. **Reads**: `readContract` or `multicall` (viem) / `contract.fn()` (ethers). Batch reads with multicall instead of N calls. Pin a `blockNumber` when several reads must be consistent.
+4. **Writes**:
+   - Validate inputs and convert amounts with the token's decimals.
+   - For ERC-20 spends, read `allowance` first; request an exact `approve` amount by default, not unlimited, unless the user opts in. Prefer EIP-2612 `permit` when the token supports it.
+   - Simulate, send, show the hash with an explorer link, then wait for the receipt.
+5. **Lifecycle states in the UI**: `awaiting signature` → `pending` (hash known) → `confirmed` (receipt `success` with N confirmations) or `reverted` / `rejected by user` / `replaced`. Handle user rejection (EIP-1193 error code `4001`) as a normal cancel, not an error.
+6. **Confirmations**: 1 is fine for UI feedback on L2s; for anything that releases off-chain value (crediting a deposit, shipping goods) wait for more blocks or the chain's finalized block (`getBlock({ blockTag: 'finalized' })`), and make the crediting idempotent per `(chainId, txHash, logIndex)`.
+7. **Replaced transactions**: users speed up or cancel in their wallet, which changes the hash. viem's `waitForTransactionReceipt` reports this through `onReplaced` with reason `replaced`, `repriced` or `cancelled`; ethers `tx.wait()` throws a `TRANSACTION_REPLACED` error. Follow the new hash or show the cancel.
+8. **Events**: `watchContractEvent` / `getLogs` (viem) or `contract.on` / `queryFilter` (ethers). Backfill history in block-range chunks (providers cap `eth_getLogs` ranges and result counts; check yours), and handle reorgs by re-reading recent blocks.
+9. **RPC limits**: add retries with backoff for HTTP 429 and timeouts, a fallback transport (`fallback([http(a), http(b)])` in viem), and caching for reads that don't change per block.
+
+## Backend services
+
+- Use a dedicated hot wallet with only the funds it needs; track nonces yourself if sending concurrently, or serialise sends.
+- Set `maxFeePerGas`/`maxPriorityFeePerGas` from `estimateFeesPerGas` (viem) or `getFeeData` (ethers), with a cap.
+- Index by `(chainId, txHash, logIndex)` and never credit the same log twice.
+
+## Stop and ask the user
+
+- Before sending any transaction on a mainnet, or from a key that holds real funds.
+- Which chains and which RPC provider to support in production.
+- Whether to request unlimited token approvals.
+- How many confirmations count as final for crediting value.
+
+## Never
+
+- Never hard-code a private key or mnemonic, even for a "test" wallet in committed code.
+- Never compute amounts with floats or display a balance without its token's decimals.
+- Never mark an action complete from the hash alone.
+- Never trust a contract address or chain ID that comes from URL parameters or user input without checking it against your allow-list.
+
+## Before you finish
+
+Test against a local node (`anvil`, optionally `--fork-url` for real contract state) or a testnet: connect, wrong-network prompt, a read, an approve plus a write, a user rejection, a reverting call (simulation shows the reason), and a replaced transaction. Report the library versions, chains and addresses used, and anything not tested.

package/skills/evm-dapp-integration/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Connect MetaMask to our React app with viem and show the user's USDC balance",
+    "Show the token balance with the right decimals in our wagmi frontend and send an approve transaction",
+    "Our ethers v6 code says the transaction succeeded but the receipt status is 0, how should we handle the transaction lifecycle?",
+    "Prompt the user to switch to Base when their wallet is on the wrong chain ID before minting",
+    "getLogs keeps failing with a block range too large error from our RPC provider when backfilling Transfer events"
+  ],
+  "should_not_trigger": [
+    "Write an ERC-20 token contract with a capped supply and an owner-only mint using Foundry",
+    "Audit our lending protocol contracts for oracle manipulation and reentrancy before launch",
+    "Review the Solidity diff in this PR for missing access control and storage collisions",
+    "Add Paystack checkout to our Next.js shop for Nigerian customers",
+    "Build a REST endpoint in Express that returns a user's order history"
+  ]
+}

package/skills/fastapi-patterns/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: fastapi-patterns
+description: FastAPI service construction with APIRouter modules, Pydantic models as the request and response contract, Depends-based injection for settings, database sessions and the current user, choosing async def versus def per endpoint, consistent error bodies, BackgroundTasks, lifespan startup, and tests through TestClient or httpx with dependency_overrides. Use when creating or extending a FastAPI app, wiring a database session or auth into routes, deciding whether an endpoint should be async, or writing tests for FastAPI endpoints.
+license: MIT
+compatibility: Any Agent Skills host. Needs Python and the project's FastAPI app. Assumes Pydantic v2; check the project's version first.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "python"
+  kete-loom/owner: "Kete-org"
+---
+
+# FastAPI patterns
+
+Build endpoints whose inputs and outputs are typed contracts, whose resources are opened and closed by dependencies, and which never block the event loop.
+
+## 0. Before you change anything
+
+1. Find the app object (`app = FastAPI(...)`) and how routers are included. Check the FastAPI and Pydantic versions in `pyproject.toml` or the lock file. Pydantic v1 and v2 APIs differ (`orm_mode` vs `from_attributes`, `.dict()` vs `.model_dump()`); match what is installed.
+2. Find the database layer (SQLAlchemy sync or async, SQLModel, an async driver) and the existing session dependency. Reuse it.
+3. Run the tests once (`pytest`). If they already fail, **stop and tell the user**.
+
+## 1. Layout
+
+```
+app/
+  main.py          # create FastAPI(), include routers, lifespan, exception handlers
+  config.py        # Settings(BaseSettings) read from env
+  deps.py          # get_db, get_current_user, get_settings
+  routers/orders.py
+  schemas/orders.py   # Pydantic models (API contract)
+  models/orders.py    # ORM models (storage)
+  services/orders.py  # business logic, no FastAPI imports
+```
+
+- One `APIRouter(prefix="/orders", tags=["orders"])` per resource, included with `app.include_router(...)`.
+- Keep ORM models and Pydantic schemas separate. Service functions take plain values and a session, so they can be tested without HTTP.
+
+## 2. Pydantic at the boundary
+
+- Separate input and output schemas: `OrderCreate` (what the client may send), `OrderUpdate` (all optional), `OrderRead` (what you return). Never accept the ORM model or a `dict` as a request body.
+- Forbid unknown fields on inputs where silent drops would hide client bugs: `model_config = ConfigDict(extra="forbid")`.
+- Constrain fields: `Field(gt=0)`, `Field(max_length=200)` or `Annotated[str, StringConstraints(max_length=200)]`, `EmailStr` (needs the `email-validator` package), enums for closed sets.
+- Set `response_model=OrderRead` (or a return annotation) on every route that returns data, so fields like `password_hash` or `internal_notes` can't leak. For ORM objects, `OrderRead` needs `model_config = ConfigDict(from_attributes=True)`.
+- Never let the client set server-owned fields (`id`, `owner_id`, `role`, `price`); set them from the authenticated user or your database.
+
+## 3. Dependency injection
+
+Prefer the `Annotated` style and reuse aliases:
+
+```python
+from typing import Annotated
+from fastapi import Depends
+
+def get_db():
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()
+
+DB = Annotated[Session, Depends(get_db)]
+CurrentUser = Annotated[User, Depends(get_current_user)]
+
+@router.get("/{order_id}", response_model=OrderRead)
+def read_order(order_id: int, db: DB, user: CurrentUser):
+    order = db.get(Order, order_id)
+    if order is None or order.owner_id != user.id:
+        raise HTTPException(status_code=404, detail="Order not found")
+    return order
+```
+
+- Resources (sessions, clients, files) are opened in a `yield` dependency and closed in `finally`. Never create a session at module import or store one on a global.
+- Decide commit policy once: either the dependency commits on success and rolls back on exception, or services commit explicitly. Follow the existing pattern.
+- Settings: `@lru_cache` on `get_settings()` returning a `BaseSettings` (from `pydantic-settings` in v2), injected with `Depends`.
+- Shared clients (`httpx.AsyncClient`, connection pools) are created in the `lifespan` context manager and closed when it exits; `@app.on_event` is deprecated.
+
+## 4. async def or def
+
+| Endpoint body does | Declare it |
+|---|---|
+| Only `await`s async libraries (async SQLAlchemy, `httpx.AsyncClient`, `asyncpg`) | `async def` |
+| Calls blocking code (sync SQLAlchemy, `requests`, `time.sleep`, file I/O, CPU work) | `def` (FastAPI runs it in a threadpool) |
+| Mostly async but one blocking call | `async def` plus `await run_in_threadpool(fn, ...)` (from `starlette.concurrency`) or `asyncio.to_thread` |
+
+- **Never** call blocking I/O inside `async def`. It stalls every request on that worker.
+- The same rule applies to dependencies: a sync `get_db` is fine; an `async def` dependency must not block.
+- Heavy CPU work belongs in a worker queue, not a request.
+
+## 5. Auth
+
+- Implement auth as a dependency (`get_current_user`) built on `OAuth2PasswordBearer`, `HTTPBearer` or `APIKeyHeader`. Raise `HTTPException(401, headers={"WWW-Authenticate": "Bearer"})` on a bad token.
+- Verify JWT signature, `exp`, and the expected algorithm (pass `algorithms=["HS256"]` or the one you use; never accept `none`). Check audience/issuer if you issue tokens for several services.
+- Protect whole routers with `APIRouter(dependencies=[Depends(get_current_user)])` and add per-route role checks (`require_role("admin")`) on top. Every new route on an unprotected router needs its own dependency.
+- Authorization is per object: filter by `owner_id`/tenant, and return 404 rather than 403 when revealing existence would leak data.
+
+## 6. Error responses
+
+- Raise `HTTPException(status_code, detail)` for expected client errors: 404 for not found, 409 for conflicts. FastAPI already returns 422 for request validation failures; don't reuse 422 for business-rule errors unless the API's error contract says so.
+- Map domain exceptions once with `@app.exception_handler(OrderNotFound)` instead of try/except in every route.
+- Keep one error body shape across the API. If you customise validation errors, override `RequestValidationError`'s handler and keep field locations.
+- Never return stack traces or raw database errors to clients; log them server-side with a request id.
+
+## 7. Background work
+
+- `BackgroundTasks.add_task(fn, *args)` runs after the response is sent, in the same process. Use it only for short, loss-tolerant work (sending a notification email).
+- Don't pass the request's database session to a background task; it may be closed. Open a new session inside the task.
+- Anything that must survive a restart, retry, or take more than a few seconds goes to a real queue (Celery, RQ, Arq, Dramatiq).
+
+## 8. Testing
+
+- Sync tests: `from fastapi.testclient import TestClient`; `with TestClient(app) as client:` so lifespan runs.
+- Async tests: `httpx.AsyncClient(transport=httpx.ASGITransport(app=app), base_url="http://test")` with `pytest-asyncio` or `anyio`. This client does **not** run lifespan; if the app needs it, wrap the app in `LifespanManager` from `asgi-lifespan` and pass `manager.app` to the transport.
+- Swap dependencies, not internals: `app.dependency_overrides[get_db] = override_get_db`, `app.dependency_overrides[get_current_user] = lambda: fake_user`. Clear them in fixture teardown.
+- Use a separate test database or a transaction rolled back per test. Never point tests at a shared database.
+- For every route test the happy path, a validation failure (422), an unauthenticated call (401), another user's object (404/403), and that the response omits private fields.
+
+## Rules
+
+- Never return ORM objects without a `response_model`.
+- Never block the event loop in `async def` routes or dependencies.
+- Never disable auth dependencies to make a test pass; override them in the test.
+
+## Report back
+
+End with: routes added or changed (method and path), schemas added, dependencies touched, which endpoints are `async def` and why, the test command and result, and anything left untested.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Add a FastAPI router for invoices with create and list endpoints and Pydantic schemas",
+    "How should I wire a SQLAlchemy session into my FastAPI routes with Depends?",
+    "Should this FastAPI endpoint be async def or def? It calls requests and the ORM",
+    "Write tests for my FastAPI app using TestClient and override the auth dependency",
+    "Set up JWT bearer auth as a dependency for our FastAPI service"
+  ],
+  "should_not_trigger": [
+    "Review this FastAPI pull request for blocking calls in async routes and leaked sessions",
+    "Add a Django model and migration for invoices",
+    "Restructure our Flask app into blueprints with an app factory",
+    "Explain asyncio.gather versus TaskGroup in a plain Python script",
+    "Design the REST resource naming and versioning for our public API"
+  ]
+}