@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/node-backend-patterns/references/templates.md

@@ -0,0 +1,122 @@
+# Templates
+
+Adapt to the project's module system and libraries; these use ESM and zod.
+
+## Express: validation middleware and error handler
+
+```ts
+import type { Request, Response, NextFunction } from 'express';
+import { ZodError, type ZodType } from 'zod';
+
+export class AppError extends Error {
+  constructor(public status: number, public code: string, message: string) { super(message); }
+}
+
+export const validateBody = (schema: ZodType) => (req: Request, res: Response, next: NextFunction) => {
+  const result = schema.safeParse(req.body);
+  if (!result.success) {
+    return res.status(400).json({ error: { code: 'invalid_request', issues: result.error.issues.map((i) => ({ path: i.path.join('.'), message: i.message })) } });
+  }
+  req.body = result.data;
+  next();
+};
+
+// Register after all routes.
+export function errorHandler(err: unknown, req: Request, res: Response, next: NextFunction) {
+  if (res.headersSent) return next(err); // let Express close a half-sent response
+  if (err instanceof AppError) {
+    return res.status(err.status).json({ error: { code: err.code, message: err.message } });
+  }
+  if (err instanceof ZodError) {
+    return res.status(400).json({ error: { code: 'invalid_request' } });
+  }
+  req.log?.error({ err }, 'unhandled error');
+  res.status(500).json({ error: { code: 'internal', message: 'Something went wrong' } });
+}
+```
+
+## Express: server.ts with graceful shutdown
+
+```ts
+import { createApp } from './app.js';
+import { config } from './config.js';
+import { logger } from './logger.js';
+import { db } from './db.js';
+
+const app = createApp();
+const server = app.listen(config.port, () => logger.info({ port: config.port }, 'listening'));
+server.headersTimeout = 65_000;
+server.requestTimeout = 30_000;
+
+let shuttingDown = false;
+export const isReady = () => !shuttingDown; // the readiness route reads this
+
+async function shutdown(signal: string) {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  logger.info({ signal }, 'shutting down');
+  const force = setTimeout(() => { logger.error('forced exit'); process.exit(1); }, 25_000);
+  force.unref();
+  server.close(async (err) => {
+    await db.end().catch((e) => logger.error({ err: e }, 'db close failed'));
+    process.exit(err ? 1 : 0);
+  });
+  server.closeIdleConnections();
+}
+
+process.on('SIGTERM', () => shutdown('SIGTERM'));
+process.on('SIGINT', () => shutdown('SIGINT'));
+```
+
+## Fastify: schema-validated route and shutdown
+
+```ts
+import Fastify from 'fastify';
+
+const app = Fastify({ logger: { redact: ['req.headers.authorization'] }, bodyLimit: 100_000 });
+
+app.post('/orders', {
+  schema: {
+    body: {
+      type: 'object',
+      required: ['items'],
+      additionalProperties: false, // stripped, not rejected, under Fastify's default ajv options
+      properties: { items: { type: 'array', minItems: 1, items: { type: 'string' } } },
+    },
+    response: { 201: { type: 'object', properties: { id: { type: 'string' } } } },
+  },
+}, async (req, reply) => {
+  const order = await placeOrder(req.body);
+  return reply.code(201).send(order);
+});
+
+app.addHook('onClose', async () => { await db.end(); });
+
+await app.listen({ port: Number(process.env.PORT ?? 3000), host: '0.0.0.0' });
+
+for (const signal of ['SIGTERM', 'SIGINT'] as const) {
+  process.once(signal, async () => {
+    setTimeout(() => process.exit(1), 25_000).unref();
+    await app.close();
+    process.exit(0);
+  });
+}
+```
+
+## Streaming a file download
+
+```ts
+import { createReadStream } from 'node:fs';
+import { pipeline } from 'node:stream/promises';
+
+app.get('/exports/:id', async (req, res, next) => {
+  try {
+    const path = await exportPathFor(req.params.id); // validates ownership, throws AppError(404)
+    res.setHeader('Content-Type', 'text/csv');
+    res.setHeader('Content-Disposition', `attachment; filename="export-${req.params.id}.csv"`);
+    await pipeline(createReadStream(path), res);
+  } catch (err) {
+    if (!res.headersSent) next(err); else res.destroy(err as Error);
+  }
+});
+```

package/skills/nuxt-patterns/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: nuxt-patterns
+description: Nuxt 3 and 4 full-stack app guidance for choosing SSR, SPA, prerender or hybrid route rules, fetching data once with useFetch and useAsyncData instead of double-fetching with $fetch, writing Nitro server routes, wiring runtimeConfig secrets, setting SEO metadata, and tracking down hydration mismatches. Use when working in a Nuxt project on pages, server/api endpoints, nuxt.config, data loading, meta tags, or a server-versus-client rendering bug.
+license: MIT
+compatibility: Any Agent Skills host. Targets Nuxt 3.x and 4.x; Nuxt 4 differences are called out. Needs the project's package manager to run the dev server or build.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Nuxt patterns
+
+Build Nuxt pages that render the same on server and client, fetch each piece of data once, and keep secrets on the server. For plain Vue component reactivity, props and Pinia, also follow `vue-patterns`.
+
+## 0. Orient first
+
+1. Read `package.json` for the Nuxt major version and modules (`@pinia/nuxt`, `@nuxtjs/i18n`, `@nuxt/content`, `@nuxt/image`).
+2. Check the layout. Nuxt 4 uses `app/` as `srcDir` (so `~/components` is `app/components`), keeps `server/`, `public/` and `shared/` at the root. A Nuxt 4 project may keep the old layout with `srcDir: '.'`. Follow what is there.
+3. Read `nuxt.config.ts` for `ssr`, `routeRules`, `runtimeConfig`, `nitro.preset` and `app.head`.
+
+## 1. Pick a rendering mode per route
+
+| Need | Setting |
+|---|---|
+| Personalised or SEO-critical dynamic page | default SSR |
+| Marketing page, docs, blog post | `routeRules: { '/blog/**': { prerender: true } }` |
+| Mostly static but changes hourly | `{ swr: 3600 }` or `{ isr: 3600 }` on hosts that support ISR |
+| Dashboard behind login, no SEO | `{ ssr: false }` for that route |
+| Whole app is a client-only SPA | `ssr: false` at the top level |
+
+Prefer per-route `routeRules` over flipping the global `ssr` flag. Confirm the deploy target supports the rule (`isr` is host-specific).
+
+## 2. Fetch data once
+
+1. In page or component setup, use `useFetch('/api/x')` for a URL, or `useAsyncData('key', () => fn())` for any async function. Both run on the server, serialise the result into the payload, and reuse it on hydration.
+2. Never call bare `$fetch` at the top of setup in an SSR page: it runs on the server and again on the client. Use `$fetch` only in event handlers, actions, server routes, or inside `useAsyncData`.
+3. Give `useAsyncData` a stable, unique key. Calls sharing a key share state; in Nuxt 4 they must not pass conflicting `transform`, `pick`, `default` or `getCachedData` options.
+4. Make reactive inputs explicit: `useFetch('/api/items', { query: { page } })` with `page` a ref refetches automatically; for `useAsyncData` pass `watch: [page]`.
+5. Handle all states in the template with `status` (`'idle' | 'pending' | 'success' | 'error'`) and `error`, not only `data`.
+6. Nuxt 4 changes: `data` and `error` default to `undefined` (Nuxt 3: `null`), and `data` is a `shallowRef`, so mutating a nested field does not re-render. Replace the object, or pass `deep: true`.
+7. Use `lazy: true` (or `useLazyFetch`) when the page should render before the data arrives, and show a pending state.
+8. Use `server: false` only for data that must never be fetched on the server (browser-only APIs, per-user data on a cached page).
+9. During SSR, `useFetch` with a relative URL to your own API forwards the incoming request's cookies and headers (except hop-by-hop ones such as `host`). A bare `$fetch` in a composable does not; use `useRequestFetch()` when you need the incoming request's headers.
+10. For one-time app init (load the current user), use `callOnce` or a plugin, not a `useFetch` in `app.vue` that runs on every navigation.
+
+## 3. Server routes (Nitro)
+
+- Files in `server/api/` map to `/api/...`; method suffixes (`users.post.ts`) restrict the verb. `server/routes/` maps without the `/api` prefix. `server/middleware/` runs on every request, so keep it cheap.
+- Use `defineEventHandler`, read input with `getQuery`, `readBody`, `getRouterParam`, and validate it (for example `readValidatedBody(event, schema.parse)`) before use.
+- Throw `createError({ statusCode: 404, statusMessage: 'Not found' })` instead of returning error objects with a 200.
+- Check authentication and authorization in every handler that touches private data. A route in `server/api` is public unless you guard it.
+- Put code shared by server and client in `shared/` (Nuxt 4) and never import server-only modules from `app/`.
+
+## 4. Runtime config and secrets
+
+```ts
+export default defineNuxtConfig({
+  runtimeConfig: {
+    apiSecret: '',                 // server only, override with NUXT_API_SECRET
+    public: { apiBase: '/api' },   // shipped to the browser, override with NUXT_PUBLIC_API_BASE
+  },
+})
+```
+
+- Read with `useRuntimeConfig()` (in server handlers, `useRuntimeConfig(event)`).
+- Anything under `public` is visible to every visitor. Secrets go at the top level only.
+- Set values in production through `NUXT_`-prefixed environment variables; `process.env` reads in `nuxt.config` are baked in at build time.
+
+## 5. SEO and head
+
+- Use `useSeoMeta({ title, description, ogTitle, ogImage })` per page, and `useHead` for links, scripts and `htmlAttrs: { lang }`.
+- Set defaults in `app.head` in `nuxt.config.ts`; let pages override.
+- Generate canonical URLs and `og:url` from a configured site URL, not from `window.location`.
+- SEO tags only reach crawlers on SSR or prerendered routes; do not rely on them for `ssr: false` routes.
+
+## 6. Hydration mismatches
+
+When the console shows "Hydration mismatch" or "Hydration completed but contains mismatches":
+
+1. Reproduce with a production build (`nuxt build` then `nuxt preview`) and read the warning for the node that differs.
+2. Look for values that differ between server and client: `Date.now()`, `new Date().toLocaleString()`, `Math.random()`, time zones, `window`/`localStorage` reads during render, and user-agent checks.
+3. Fix by computing the value once on the server and passing it through `useState` or fetched data, by moving browser-only reads into `onMounted`, or by wrapping the subtree in `<ClientOnly>` with a fallback.
+4. Guard browser-only code with `import.meta.client` (or `.server`), not `process.client`.
+5. Check for invalid HTML nesting (a `<div>` inside a `<p>`, nested `<a>`, a `<tr>` without `<tbody>`); browsers rewrite it and the DOM no longer matches.
+6. For cross-request state, use `useState('key', () => init)` instead of a module-level `ref`, which leaks between users on the server.
+
+## Stop and ask the user
+
+- Changing the rendering mode or `nitro.preset` of a route already in production.
+- A secret is currently under `runtimeConfig.public` or committed in `nuxt.config`: flag it and ask before rotating anything.
+- The fix needs a Nuxt major upgrade.
+
+## Never
+
+- Never put API keys in `runtimeConfig.public` or client code.
+- Never hide a hydration warning with `<ClientOnly>` around a whole page without finding the cause.
+- Never leave a `server/api` handler without input validation or an auth check when it touches user data.
+
+## Report back
+
+State the files changed, the rendering mode of each touched route, how data is fetched there, the command you ran (`nuxt build`, tests, typecheck) and its result, and anything not checked in a production build.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "My Nuxt page calls the API twice, once on the server and again in the browser",
+    "Prerender the blog section of our Nuxt app but keep the dashboard client-only",
+    "How do I keep the Stripe secret out of the browser using Nuxt runtimeConfig?",
+    "Add a server/api endpoint in Nuxt that validates the POST body",
+    "Fix the hydration mismatch on my Nuxt product page caused by the date"
+  ],
+  "should_not_trigger": [
+    "Why does my Vue 3 composable lose reactivity when I destructure it?",
+    "Review my Nuxt pull request for missing watcher cleanup",
+    "Write a SvelteKit form action that validates the signup form",
+    "Set up getServerSideProps in my Next.js page",
+    "Write a Pinia store for user preferences in a plain Vite Vue app"
+  ]
+}

package/skills/parallel-agent-orchestration/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: parallel-agent-orchestration
+description: Fans a large coding job out to several subagents at once and merges the results. Covers cutting the job into independent units with disjoint file ownership, writing a self-contained brief and return contract for each worker, isolating writers in separate git worktrees or branches, and checking every result before integrating it. Use when work splits naturally into pieces that can run side by side (many modules, many packages, a survey plus several fixes), or when the user asks to run agents in parallel or orchestrate a team of subagents.
+license: MIT
+compatibility: Any Agent Skills host that can start subagents. Worktree isolation needs git 2.17 or later (for git worktree remove).
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: meta
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "git"
+  kete-loom/owner: "Kete-org"
+---
+
+# Parallel agent orchestration
+
+You are the orchestrator. Workers do the units; you own the plan, the contracts, the merge and the final verification. Parallelism only pays when units are truly independent. Two agents editing the same file is a merge conflict you chose.
+
+## 1. Decide whether to parallelise
+
+Parallelise only if all are true:
+
+- The work splits into 2 or more units that don't need each other's output to start.
+- Each unit can be checked on its own (a test, a lint, a build, a clear review question).
+- The units touch different files, or are read-only.
+
+Otherwise do it sequentially, or run a read-only survey in parallel and the edits in sequence. If the split is unclear, **stop and propose the split to the user** before starting workers.
+
+## 2. Cut the units
+
+1. Search the codebase to map what each unit touches. Write the plan as a table:
+
+   | Unit | Goal | Owns (may edit) | May read | Check command |
+   |---|---|---|---|---|
+
+2. Give every file at most one owner. Shared files (lockfiles, `package.json`, route tables, barrel `index` files, generated catalogs, changelogs) belong to **you**: workers report what they need there and you apply it at merge time.
+3. Do shared groundwork first and yourself: interfaces, types, config that several units depend on. Commit it, then start workers from that commit.
+4. Keep the count small. Three to six workers is easier to verify than twenty. More units than that: run in waves.
+
+## 3. Isolate writers
+
+- Read-only workers (search, review, research) can share the working tree.
+- Writing workers each get their own worktree and branch, so they can't clobber each other:
+
+  ```
+  git worktree add -b work/<unit> ../<repo>-<unit> <base-sha>
+  ```
+
+  Start every worktree from the groundwork commit of step 2. If the host creates worktrees for its subagents itself, use those instead. Remove them after merging with `git worktree remove ../<repo>-<unit>`.
+- If the host runs workers in the same tree, ownership from step 2 is the only protection: state it in every brief.
+
+## 4. Write each brief
+
+A worker starts with none of your context. Every brief contains:
+
+```
+Goal: <one sentence, the outcome>
+Context: <the 3-6 facts it needs: paths, conventions, decisions already made>
+You own: <files/folders you may edit>. Do not edit anything else.
+Do not: <push / commit anywhere but work/<unit> / install dependencies / touch shared files / ask the user>
+Done when: <check command> passes and <acceptance criteria>
+Return exactly:
+  status: done | blocked | partial
+  changed: list of paths
+  check: <command> -> <result>
+  needs_from_orchestrator: shared-file changes or decisions, or "none"
+  notes: max 5 lines
+```
+
+Ask for a fixed, short return format. Free-form essays are hard to merge and eat your context.
+
+## 5. Run and watch
+
+- Start the independent workers together. Don't start a worker whose inputs aren't ready.
+- If a worker returns `blocked`, decide yourself or **ask the user**; don't let it guess.
+- Don't re-run a failed worker with the same brief. Fix the brief (missing context, wrong ownership) first.
+
+## 6. Verify every result
+
+Treat worker output as a claim, not a fact:
+
+1. Check `changed` against ownership: `git diff --name-only <base-sha>..work/<unit>`, plus `git -C ../<repo>-<unit> status --short` for anything left uncommitted. Any file outside its ownership: reject or redo that part.
+2. Re-run the unit's check command yourself.
+3. Read the diff. Look for skipped or deleted tests, stubs, TODOs and silent scope creep.
+
+## 7. Merge
+
+1. Merge units one at a time onto the integration branch, in dependency order.
+2. Apply the `needs_from_orchestrator` changes to shared files yourself.
+3. After each merge run the affected checks; after the last, run the project's full check (tests, lint, build).
+4. On a conflict, resolve it yourself with both briefs in mind, or redo the smaller unit on top of the merged result. Never pick a side blindly.
+
+## Report
+
+```
+Units: <n> (<n> done, <n> redone, <n> dropped)
+Merged: <branch> at <sha>
+Full check: <command> -> <result>
+Left over: <blocked items and open questions>
+```
+
+## Never
+
+- Never give two workers write access to the same file.
+- Never merge a unit you haven't re-checked yourself.
+- Never let workers commit to the integration branch or push.
+- Never parallelise a task whose steps depend on each other's results just to go faster.

package/skills/parallel-agent-orchestration/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Spin up several subagents to migrate each of our 8 packages to ESM at the same time",
+    "Split this big refactor across parallel workers without them stepping on each other's files",
+    "Run one agent per service to add health checks, then merge everything into one branch",
+    "How should I divide this job between a team of agents and combine what they produce"
+  ],
+  "should_not_trigger": [
+    "Keep retrying the flaky integration test fix overnight until CI is green",
+    "Design the message queue so our worker processes handle jobs concurrently",
+    "The context keeps overflowing when I read this monorepo, help me budget it",
+    "Plan the implementation steps for the new invoicing feature"
+  ]
+}

package/skills/paystack-integration/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: paystack-integration
+description: Builds and reviews Paystack payment integrations, including transaction initialisation, server-side verification, webhooks with HMAC-SHA512 signature checks, idempotent fulfilment, and Ghana mobile money (MTN, Telecel, AT) charges. Use when adding Paystack checkout, card or mobile money payments, handling Paystack webhooks, or debugging a Paystack payment flow.
+license: MIT
+compatibility: Any Agent Skills host. Needs network access to api.paystack.co for live calls. Examples are TypeScript (Node 18+); the rules apply to any backend language.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Paystack integration
+
+Build a payment flow that can't be faked from the browser and never gives value twice. These rules cover cards, bank and mobile money.
+
+## Ground rules
+
+1. **The secret key stays on the server.** Read it from the environment (`PAYSTACK_SECRET_KEY`). Only the public key (`pk_...`) may reach the browser or app.
+2. **Amounts are in the currency's subunit**: pesewas for GHS, kobo for NGN, cents for USD, KES and ZAR. GHS 25.50 is `2550`. Use integers, never floats.
+3. **The server decides the price.** Compute the amount from your own database (order total, plan price). Never trust an amount sent by the client.
+4. **Value is given only after verification.** Either a webhook with a valid signature, or a call to the Verify Transaction endpoint, must confirm `status: "success"` **and** that the amount and currency match what you expected.
+5. **Fulfilment is idempotent.** Store the `reference` with a unique constraint and process each reference once, because Paystack retries webhooks and users refresh pages.
+6. **Test keys first.** Use `sk_test_` / `pk_test_` until the full flow, including failures, works end to end.
+
+## Flow
+
+```
+client ──(order id)──▶ server: create order, compute amount, POST /transaction/initialize
+server ──(authorization_url or access_code)──▶ client: redirect or open Popup
+customer pays on Paystack
+Paystack ──(charge.success webhook)──▶ server: verify signature, verify amount, fulfil once
+client returns to callback_url ──▶ server: GET /transaction/verify/:reference, show result
+```
+
+The callback page only *shows* status. Fulfilment happens in the webhook (or a verify call), guarded by the idempotency check, so it is safe whichever arrives first.
+
+## Implementation steps
+
+1. **Initialise** with `POST https://api.paystack.co/transaction/initialize`, `Authorization: Bearer <secret key>`, and a body containing `email`, `amount` (subunit), `currency`, a `reference` you generate and store, `callback_url`, and `metadata` (for example the order id). See `references/api.md` for request and response shapes.
+2. **Webhook endpoint**: follow `references/webhooks.md` exactly. Verify the signature on the **raw** body, return `200` quickly, and do the work asynchronously.
+3. **Verify** with `GET https://api.paystack.co/transaction/verify/:reference` on the callback page and as a fallback when no webhook arrives.
+4. **Mobile money (Ghana)**: use the Charge API or the standard checkout, and follow `references/mobile-money.md` for the `pay_offline` pending flow and the 180-second approval window.
+5. **Persist** an order and payment record holding `reference`, expected amount and currency, status, the Paystack transaction id, and timestamps.
+
+## Reviewing an existing integration
+
+Check each ground rule above, then look for these common bugs:
+
+- Signature computed over re-serialised JSON instead of the raw bytes.
+- Webhook does heavy work before responding, which causes timeouts and duplicate retries.
+- Fulfilment keyed on `id` from the client, or done in the callback page without verification.
+- Float arithmetic on amounts (`25.5 * 100`), or amounts in cedis instead of pesewas.
+- Secret key committed in code or exposed in a `NEXT_PUBLIC_`/`VITE_` variable.
+- No handling for `failed`, `abandoned` or `reversed` transactions.
+
+## Before you finish
+
+Confirm field names and endpoints against Paystack's current docs at paystack.com/docs when generating new code; this skill gives the rules and the shape, the docs are the final word on the API. Then test: successful payment, declined payment, a duplicate webhook delivery, a webhook with a bad signature (must be rejected), and mobile money approval timing out.

package/skills/paystack-integration/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Add Paystack checkout to our Next.js shop so Ghanaian customers can pay",
+    "My Paystack webhook says invalid signature every time, can you fix it?",
+    "Let users pay with MTN MoMo through Paystack in the mobile app",
+    "Customers are getting their orders twice when Paystack retries the webhook"
+  ],
+  "should_not_trigger": [
+    "Integrate Stripe subscriptions into the billing page",
+    "Review my last commit for security vulnerabilities",
+    "Write a blog post about mobile money adoption in West Africa",
+    "Build an invoice PDF generator for the accounting module"
+  ]
+}

package/skills/paystack-integration/references/api.md

@@ -0,0 +1,73 @@
+# Paystack API shapes used by this skill
+
+Base URL: `https://api.paystack.co`. All server calls send `Authorization: Bearer <PAYSTACK_SECRET_KEY>` and `Content-Type: application/json`. Responses look like `{ "status": true, "message": "...", "data": { ... } }`; `status` there means the API call succeeded, not that a payment did.
+
+Confirm fields against paystack.com/docs/api before shipping; this is a working summary.
+
+## Initialise a transaction
+
+`POST /transaction/initialize`
+
+```json
+{
+  "email": "customer@example.com",
+  "amount": 2550,
+  "currency": "GHS",
+  "reference": "ord_8f2c1a",
+  "callback_url": "https://app.example.com/pay/callback",
+  "channels": ["card", "mobile_money"],
+  "metadata": { "order_id": "8f2c1a" }
+}
+```
+
+Response `data`: `authorization_url` (redirect the customer here), `access_code` (for the inline Popup), `reference`.
+
+## Verify a transaction
+
+`GET /transaction/verify/:reference`
+
+Check in `data`:
+
+| Field | Expect |
+|---|---|
+| `status` | `"success"` (others: `failed`, `abandoned`, `reversed`, `pending`) |
+| `amount` | equals the amount you stored, in subunits |
+| `currency` | equals the currency you stored |
+| `reference` | the reference you generated |
+| `id` | Paystack transaction id; store it |
+| `channel` | `card`, `mobile_money`, `bank`, ... |
+
+## Minimal server client (TypeScript)
+
+```ts
+const BASE = 'https://api.paystack.co';
+
+async function paystack<T>(path: string, init: RequestInit = {}): Promise<T> {
+  const res = await fetch(`${BASE}${path}`, {
+    ...init,
+    headers: {
+      authorization: `Bearer ${process.env.PAYSTACK_SECRET_KEY}`,
+      'content-type': 'application/json',
+      ...init.headers,
+    },
+  });
+  const body = await res.json();
+  if (!res.ok || body.status !== true) throw new Error(`Paystack ${path} failed: ${body.message ?? res.status}`);
+  return body.data as T;
+}
+
+export const initialize = (input: object) =>
+  paystack<{ authorization_url: string; access_code: string; reference: string }>('/transaction/initialize', {
+    method: 'POST',
+    body: JSON.stringify(input),
+  });
+
+export const verify = (reference: string) =>
+  paystack<{ status: string; amount: number; currency: string; reference: string; id: number }>(
+    `/transaction/verify/${encodeURIComponent(reference)}`
+  );
+```
+
+## References
+
+Generate references on the server, unique per payment attempt (for example `ord_<orderId>_<random>`). A retry after a failure gets a new reference; the order keeps a list of attempts.

package/skills/paystack-integration/references/mobile-money.md

@@ -0,0 +1,50 @@
+# Ghana mobile money with Paystack
+
+Two ways to accept mobile money:
+
+1. **Standard checkout** (simplest): initialise a transaction with `currency: "GHS"`, and optionally `channels: ["mobile_money"]`. The customer picks the network and approves on their phone. Fulfil from the webhook as usual.
+2. **Charge API** (your own UI): `POST https://api.paystack.co/charge` with your secret key.
+
+## Charge API request
+
+```json
+{
+  "email": "customer@example.com",
+  "amount": 2550,
+  "currency": "GHS",
+  "reference": "ord_8f2c1a",
+  "mobile_money": {
+    "phone": "0551234987",
+    "provider": "mtn"
+  }
+}
+```
+
+Provider codes for Ghana:
+
+| Code | Network |
+|---|---|
+| `mtn` | MTN Mobile Money |
+| `vod` | Telecel Cash |
+| `atl` | AT Money / Airtel Money |
+
+`amount` is in pesewas (`2550` = GHS 25.50).
+
+## Pending flow
+
+1. The response usually has `data.status: "pay_offline"` and a `data.display_text`. Show that text to the customer ("Approve the prompt on your phone...").
+2. The customer has about **180 seconds** to approve on their handset; the networks set this limit.
+3. Wait for the `charge.success` webhook. Do not fulfil on the initial response.
+4. If no webhook arrives within ~180 seconds, call `GET /transaction/verify/:reference`. A failure reason is in `data.message`. Let the customer retry with a **new** reference.
+
+Other statuses you may see on the charge response include `send_otp` and `pending`; follow the `display_text` and the Charge API docs for the submit endpoint each one requires.
+
+## UX notes
+
+- Validate the phone number format before calling the API, and make sure the chosen provider matches the number's network.
+- Show a countdown and a "Check status" button rather than polling Paystack aggressively.
+- Make clear that the customer must approve on their phone, and that no PIN is ever entered in your app.
+
+## Testing
+
+Use test keys and the mobile money test numbers on Paystack's Test Payments page. Cover approved, declined and timed-out approvals.

package/skills/paystack-integration/references/webhooks.md

@@ -0,0 +1,80 @@
+# Paystack webhooks
+
+## What Paystack sends
+
+- `POST` with a JSON body, for example `{ "event": "charge.success", "data": { ... } }`.
+- Header `x-paystack-signature`: HMAC SHA512 of the request body, keyed with your **secret key**, hex encoded.
+- Paystack treats anything other than `200 OK` as a failed delivery and retries. In live mode it retries every 3 minutes for the first 4 tries, then hourly for 72 hours.
+- Paystack documents a fixed set of source IPs you can additionally allow-list; check the webhooks page for the current list.
+
+## Handler rules
+
+1. Read the **raw body bytes** before any JSON parsing. Re-serialising parsed JSON changes whitespace and key order and breaks the signature.
+2. Compute `HMAC_SHA512(secretKey, rawBody)` as hex and compare with the header using a **constant-time** comparison. Mismatch → respond `401` and stop.
+3. Respond `200` immediately after the signature check, then process the event asynchronously (a queue or background job).
+4. In the processor: look up your order by `data.reference`, check `data.status === "success"`, and check `data.amount` and `data.currency` equal what you stored. Then mark the order paid **in the same transaction** as an idempotency check (unique `reference`, or `UPDATE ... WHERE status = 'pending'`).
+5. Log the event id and reference. Never log card data or the secret key.
+
+## Express (TypeScript)
+
+```ts
+import crypto from 'node:crypto';
+import express from 'express';
+
+const app = express();
+const SECRET = process.env.PAYSTACK_SECRET_KEY!;
+
+app.post('/webhooks/paystack', express.raw({ type: 'application/json' }), (req, res) => {
+  const signature = req.header('x-paystack-signature') ?? '';
+  const expected = crypto.createHmac('sha512', SECRET).update(req.body).digest('hex');
+  const valid =
+    signature.length === expected.length &&
+    crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
+  if (!valid) return res.sendStatus(401);
+
+  res.sendStatus(200); // acknowledge first
+  const event = JSON.parse(req.body.toString('utf8'));
+  queue.add('paystack-event', event); // process asynchronously and idempotently
+});
+```
+
+## Next.js route handler
+
+```ts
+import crypto from 'node:crypto';
+
+export async function POST(req: Request) {
+  const raw = Buffer.from(await req.arrayBuffer());
+  const signature = req.headers.get('x-paystack-signature') ?? '';
+  const expected = crypto.createHmac('sha512', process.env.PAYSTACK_SECRET_KEY!).update(raw).digest('hex');
+  if (signature.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
+    return new Response('invalid signature', { status: 401 });
+  }
+  const event = JSON.parse(raw.toString('utf8'));
+  await enqueue(event); // keep this fast
+  return new Response('ok', { status: 200 });
+}
+```
+
+## Python (FastAPI)
+
+```python
+import hashlib, hmac, os
+from fastapi import FastAPI, Request, Response
+
+app = FastAPI()
+SECRET = os.environ["PAYSTACK_SECRET_KEY"].encode()
+
+@app.post("/webhooks/paystack")
+async def paystack_webhook(request: Request):
+    raw = await request.body()
+    expected = hmac.new(SECRET, raw, hashlib.sha512).hexdigest()
+    if not hmac.compare_digest(expected, request.headers.get("x-paystack-signature", "")):
+        return Response(status_code=401)
+    enqueue(raw)  # process asynchronously and idempotently
+    return Response(status_code=200)
+```
+
+## Local testing
+
+Webhooks can't reach `localhost`. Use a tunnel (for example `cloudflared` or `ngrok`) and set the tunnel URL in the Paystack dashboard for test mode. Use the dashboard's resend option, or the Webhook Events API, to replay an event and confirm your handler is idempotent.