@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/mobile-accessibility/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: mobile-accessibility
+description: Makes native iOS and Android screens usable with VoiceOver and TalkBack by fixing labels, traits and roles, grouping and reading order, focus moves after navigation, Dynamic Type and sp font scaling, 44pt and 48dp touch targets and colour contrast, across SwiftUI, UIKit, Jetpack Compose and Android Views, then proving it with Accessibility Inspector, Accessibility Scanner and automated audits in UI tests. Use when a native mobile screen must work with a screen reader, large text or switch access, an app store or customer audit flagged accessibility issues, or accessibility checks need adding to XCUITest, Espresso or Compose tests.
+license: MIT
+compatibility: Any Agent Skills host. Testing needs Xcode (Accessibility Inspector, XCUITest) or Android Studio with an emulator or device (Accessibility Scanner, Espresso or Compose UI tests).
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Mobile accessibility
+
+Fix native iOS and Android UI so people using a screen reader, large text, switch control or low vision can finish every task. For web pages use the web accessibility skill; for React Native or Flutter, apply the same rules through that framework's accessibility props.
+
+## 0. Before you start
+
+1. Find the UI toolkit per screen: SwiftUI, UIKit, Jetpack Compose or Android Views. Many apps mix them.
+2. List the critical journeys (sign in, search, checkout, settings). Audit those first, not every screen.
+3. Ask the user whether a target standard applies (WCAG 2.2 AA is the usual reference for mobile, and some contracts or laws name it). Do not claim legal compliance; report findings against the criteria.
+
+## 1. Audit each screen in this order
+
+For every screen, check and record each item:
+
+1. **Every control has a name.** Icon-only buttons, images that carry meaning and custom views need a label. Decorative images are hidden from assistive tech.
+2. **Role and state are announced.** A tappable row says "button", a toggle says on/off, a selected tab says selected, a heading is a heading.
+3. **Grouping.** A card with title, price and rating is read as one element, not five swipes.
+4. **Reading and focus order** follows the visual order. After a screen change, sheet or error, focus moves to the new content.
+5. **Text scales.** At the largest accessibility text size nothing is clipped or overlapped; layouts wrap or scroll instead of truncating.
+6. **Touch targets** are at least 44 x 44 pt on iOS (Human Interface Guidelines) and 48 x 48 dp on Android (Material). Expand the hit area rather than the visible icon if needed.
+7. **Contrast** is at least 4.5:1 for body text and 3:1 for large text and essential icons or control borders (WCAG 1.4.3, 1.4.11). Never convey state by colour alone.
+8. **Motion and transparency** respect Reduce Motion and Reduce Transparency (iOS) and Remove animations (Android).
+9. **Custom gestures** (swipe to delete, long press) also have an accessible action.
+
+## 2. Fix with the platform API
+
+Use the native control first: a real `Button`/`Toggle` gets role, state and focus for free. Add modifiers only where a native control is not possible.
+
+| Need | SwiftUI | UIKit | Compose | Android Views |
+|---|---|---|---|---|
+| Name | `.accessibilityLabel("Delete")` | `accessibilityLabel` | `Modifier.semantics { contentDescription = "Delete" }` or `Icon(contentDescription=)` | `android:contentDescription` |
+| Hide decorative | `.accessibilityHidden(true)`, `Image(decorative:)` | `isAccessibilityElement = false` | `contentDescription = null` | `importantForAccessibility="no"` |
+| Role/state | `.accessibilityAddTraits(.isButton)`, `.accessibilityValue` | `accessibilityTraits`, `accessibilityValue` | `Modifier.semantics { role = Role.Button; stateDescription = "On" }`, `Modifier.toggleable` | `ViewCompat.setAccessibilityDelegate`, `stateDescription` |
+| Heading | `.accessibilityAddTraits(.isHeader)` | `.header` trait | `Modifier.semantics { heading() }` | `android:accessibilityHeading="true"` |
+| Group | `.accessibilityElement(children: .combine)` | container view as one element with a combined label | `Modifier.semantics(mergeDescendants = true) {}` or `clickable` on the row | `android:focusable="true"` on the parent, `screenReaderFocusable` |
+| Order | `.accessibilitySortPriority` | `accessibilityElements` array | `Modifier.semantics { traversalIndex = 1f; isTraversalGroup = true }` | `android:accessibilityTraversalBefore/After` |
+| Move focus | `@AccessibilityFocusState` | `UIAccessibility.post(notification: .screenChanged, argument: view)` | `Modifier.semantics { paneTitle = "..." }` on the new pane; `FocusRequester` moves input focus, which TalkBack may not follow, so check on a device | `view.sendAccessibilityEvent` or `performAccessibilityAction(ACTION_ACCESSIBILITY_FOCUS)` |
+| Announce | `AccessibilityNotification.Announcement("Saved").post()` | `UIAccessibility.post(notification: .announcement, argument:)` | `Modifier.semantics { liveRegion = LiveRegionMode.Polite }` | `android:accessibilityLiveRegion="polite"` |
+| Custom action | `.accessibilityAction(named: "Delete") {}` | `accessibilityCustomActions` | `Modifier.semantics { customActions = listOf(...) }` | `ViewCompat.addAccessibilityAction` |
+| Text scaling | `.font(.body)` text styles, `@ScaledMetric` | `UIFont.preferredFont(forTextStyle:)` + `adjustsFontForContentSizeCategory = true` | `sp` units via `MaterialTheme.typography` | `sp` for `textSize`, avoid fixed `dp` heights on text |
+| Touch target | `.frame(minWidth: 44, minHeight: 44)` + `.contentShape(Rectangle())` | override `point(inside:with:)` or larger frame | `Modifier.minimumInteractiveComponentSize()` (Material 3 does this for its components) | `minWidth`/`minHeight` 48dp or `TouchDelegate` |
+
+Label rules:
+
+- Say what it does, not what it looks like: "Delete message", not "trash can". Do not add "button" to a label; the role says it.
+- Keep labels short and put the important word first. Put extra guidance in a hint (`accessibilityHint`) only when the action is not obvious.
+- Localise labels with the rest of the strings.
+
+## 3. Verify
+
+1. **Manual screen reader pass** of each critical journey: VoiceOver on iOS (Settings, Accessibility, VoiceOver, or the Accessibility Shortcut), TalkBack on Android. Swipe through every element; activate every control; complete the task without looking.
+2. **Largest text size**: iOS Settings, Accessibility, Display and Text Size, Larger Text; Android Settings, Display, Font size (and Display size). Use Xcode's Environment Overrides or the Compose `@Preview(fontScale = 2f)` while iterating.
+3. **Inspectors**: Xcode's Accessibility Inspector (Audit tab, and inspect an element's label, traits and frame); Android's Accessibility Scanner app on a device or emulator.
+4. **Automated checks in UI tests**, so regressions fail CI:
+   - iOS 17+ XCUITest: `try app.performAccessibilityAudit()` on each critical screen; narrow with `for: [.contrast, .dynamicType, .hitRegion]` and filter known false positives in the issue handler (return `true` to ignore an issue), with a comment why.
+   - Espresso: add `androidx.test.espresso:espresso-accessibility` and call `AccessibilityChecks.enable()` in the test setup.
+   - Compose 1.8+: add `androidx.compose.ui:ui-test-junit4-accessibility`, call `composeTestRule.enableAccessibilityChecks()` on an `AndroidComposeTestRule`; checks run on actions, or call `onRoot().tryPerformAccessibilityChecks()`.
+5. Rerun the tests and the manual pass after every fix.
+
+Automated audits catch only part of the real problems (they cannot judge whether a label makes sense or a journey can be finished). A clean audit never replaces the screen reader pass.
+
+## Stop and ask the user
+
+- A fix would change the visual design (bigger targets, colours that pass contrast, text wrapping onto more lines). Show the before and after and let design decide how, not whether.
+- A custom control (chart, canvas, game view, map) has no obvious accessible equivalent; propose a text summary or alternative view first.
+- The project has no UI test target and adding one is a large change.
+
+## Never
+
+- Never hide a focusable, interactive element from assistive tech to silence an audit warning.
+- Never cap or disable Dynamic Type or font scaling (`maximumContentSizeCategory`, fixed `dp` text) to save a layout, unless the user agrees for that specific element and the content stays readable another way.
+- Never put the same label on several different controls in one screen ("Button", "Image", "More").
+- Never rely on a tooltip, colour or position alone to convey meaning.
+
+## Report back
+
+```
+Screens audited: <list>
+Issues: <id> | <screen> | <criterion, e.g. name, order, target size> | <severity: blocker/major/minor> | <fix or status>
+Verified with: <VoiceOver/TalkBack pass, largest text, Inspector/Scanner, UI test audits added (test names)>
+Open: <items needing design decisions or not fixed>
+```

package/skills/mobile-accessibility/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "VoiceOver reads our SwiftUI product card as five separate items, make it one element with a sensible label",
+    "TalkBack just says 'unlabelled button' on all the icon buttons in our Compose toolbar",
+    "At the largest Dynamic Type size our UIKit settings screen clips text, fix it so it scales",
+    "Add automated accessibility audits to our XCUITest and Espresso suites so regressions fail CI",
+    "Accessibility Scanner flags touch target too small and low contrast on our Android login screen"
+  ],
+  "should_not_trigger": [
+    "Make our React web checkout pass WCAG 2.2 AA with keyboard navigation and axe",
+    "Our Compose LazyColumn janks when scrolling, reduce recomposition",
+    "Migrate this SwiftUI screen from ObservableObject to @Observable",
+    "Write XCTest unit tests for the login view model with a fake network client",
+    "Translate the Android app strings into Arabic and support right-to-left layouts"
+  ]
+}

package/skills/mongodb-patterns/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: mongodb-patterns
+description: MongoDB document modelling and query tuning, from embed-versus-reference decisions and unbounded-array traps to compound indexes ordered by the ESR rule, reading explain executionStats, aggregation pipelines, multi-document transactions on replica sets, and $jsonSchema collection validation. Use when designing or changing MongoDB collections, a MongoDB query or aggregation is slow, adding indexes or validators, or deciding whether a write needs a transaction, with the native driver, Mongoose or another ODM.
+license: MIT
+compatibility: Any Agent Skills host. Commands are mongosh syntax; the same options exist in every official driver. Atlas-only features (Atlas Search, Performance Advisor) are noted as such.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: data
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "mongosh"
+  kete-loom/owner: "Kete-org"
+---
+
+# MongoDB patterns
+
+Model documents around how the application reads them, index for the queries it actually runs, and prove every performance claim with `explain`. The detailed recipes live in `references/indexes-and-aggregation.md`.
+
+## 0. Before you start
+
+1. Find the driver or ODM (native driver, Mongoose, Motor, Spring Data, Prisma) and where the connection string comes from. Search for `MongoClient`, `mongoose.connect` or the `mongodb://` / `mongodb+srv://` variable.
+2. Get the server version and topology with `db.version()` and `db.hello()` (look for `setName` for a replica set, `msg: "isdbgrid"` for mongos). Transactions and change streams need a replica set or sharded cluster.
+3. List the queries the feature will run: filter fields, sort, projection, and how many documents each returns. If you can't list them, **stop and ask the user**; a model can't be judged without them.
+4. Never run `dropDatabase`, `drop`, `deleteMany({})`, `updateMany` without a tight filter, or a `collMod` that tightens validation on a shared or production database without the user's explicit approval. Build indexes on large production collections only after the user has agreed on timing; they consume I/O while they build.
+
+## 1. Embed or reference
+
+Embed when the data is read together, owned by the parent, and bounded in size. Reference when it is shared, updated on its own, or grows without limit.
+
+| Relationship | Default |
+|---|---|
+| One-to-few, read with the parent (addresses, line items of an order) | Embed an array |
+| One-to-many, unbounded (comments on a post, events of a device) | Separate collection with the parent's `_id` indexed on the child |
+| Many-to-many (students and courses) | Array of IDs on the side queried most, or a link collection |
+| Data shared by many parents and edited (product name in old orders) | Reference; copy only fields that should freeze at write time (the price paid) |
+
+Rules:
+
+- A document is at most 16 MiB. Any array that grows with user activity must have a hard cap or live in its own collection. Large, frequently rewritten arrays also make every update expensive.
+- Design so the common page loads with **one query**. If it needs `$lookup` on every request, reconsider the model (or accept it knowingly for low-traffic paths).
+- Duplicating a field is fine when you know who updates the copies. Write it down in the code next to the update.
+- Use the **bucket** pattern for time series on older servers (one document per device per hour), or a native time series collection (`db.createCollection(name, { timeseries: { timeField, metaField } })`).
+- Use the **subset** pattern for large related lists: embed the latest N, keep the rest in a separate collection.
+
+## 2. Indexes
+
+- Every query in a request path needs an index that supports its filter and sort. A `COLLSCAN` in `explain` on a large collection is a bug.
+- Order compound index keys by **ESR**: **E**quality fields first, then **S**ort fields, then **R**ange fields (`$gt`, `$lt`, `$in` with many values, regex).
+- One compound index can serve its prefixes: `{ tenantId: 1, status: 1, createdAt: -1 }` also serves `{ tenantId: 1 }`. Drop indexes that are a prefix of another.
+- Use partial indexes (`partialFilterExpression`) for queries that only touch a subset, unique indexes for invariants, and TTL indexes (`expireAfterSeconds`) for expiring data.
+- Each index costs RAM and slows every write. Check usage with `db.coll.aggregate([{ $indexStats: {} }])` before adding more, and propose removing unused ones (hide them first with `db.coll.hideIndex(name)` to test safely).
+
+Verify with:
+
+```js
+db.orders.find({ tenantId: t, status: "open" }).sort({ createdAt: -1 }).explain("executionStats")
+```
+
+Read `winningPlan` (want `IXSCAN`, no in-memory `SORT` stage), `totalKeysExamined` and `totalDocsExamined` against `nReturned` (want them close), and `executionTimeMillis`. Report these numbers before and after.
+
+## 3. Aggregation
+
+- Put `$match` first and `$project`/`$unset` early so later stages see fewer, smaller documents; only the leading `$match` and `$sort` can use an index.
+- `$lookup` needs an index on the foreign field. Avoid `$lookup` inside hot request paths when an embed would do.
+- Each blocking stage (`$group`, `$sort` without an index, `$bucket`) has a 100 MB memory limit before it spills to disk or errors, depending on `allowDiskUse` and the server default. Spilling is slow; prefer narrowing earlier.
+- Use `$facet` for several counts over one result set instead of several round trips, and `$merge`/`$out` to precompute heavy reports on a schedule.
+- Paginate with a range on an indexed key (`_id > lastSeenId`), not large `skip` values.
+
+## 4. Transactions
+
+- A single-document write is already atomic, including its embedded arrays. Model so most invariants live in one document; reach for a transaction only when several documents must change together.
+- Transactions need a replica set or sharded cluster, and by default must finish within 60 seconds (`transactionLifetimeLimitSeconds`). Keep them short and touch few documents.
+- Use the driver's callback API (`session.withTransaction(fn)`), which retries on `TransientTransactionError` and `UnknownTransactionCommitResult`. Pass the session to **every** operation inside, or that operation runs outside the transaction.
+- Use `writeConcern: { w: "majority" }` and `readConcern: "snapshot"` for transactions whose result must survive failover.
+- Outside transactions, guard concurrent updates with conditional filters (`updateOne({ _id, version: 3 }, { $set: {...}, $inc: { version: 1 } })`) and check `matchedCount`.
+
+## 5. Schema validation
+
+Keep the database honest even if one service skips the ODM's checks:
+
+```js
+db.runCommand({
+  collMod: "orders",
+  validator: { $jsonSchema: {
+    bsonType: "object",
+    required: ["tenantId", "status", "total"],
+    properties: {
+      status: { enum: ["open", "paid", "cancelled"] },
+      total: { bsonType: "decimal" }
+    }
+  }},
+  validationLevel: "moderate",
+  validationAction: "error"
+})
+```
+
+- Roll out on an existing collection with `validationAction: "warn"` first, check the logs for violations, fix the data, then switch to `"error"`. `validationLevel: "moderate"` checks inserts and updates to documents that are already valid; updates to documents that were already invalid are not checked, so fix those in a backfill.
+- Store money as `Decimal128` or integer minor units, never as a double. Store dates as BSON dates, not strings.
+
+## Never
+
+- Build query filters from raw request JSON; a body like `{ "$ne": null }` becomes an operator. Validate types or use a sanitiser, and reject keys starting with `$`.
+- Use `$where` or server-side JavaScript on user input.
+- Let arrays grow without a limit inside a document.
+- Claim a query is fast without `explain("executionStats")` output.
+
+## Report format (when reviewing)
+
+```
+MongoDB review: <collections or feature>
+Topology/version: <replica set | sharded | standalone>, <version>
+Findings:
+1. [severity] <file:line or collection>: <problem> → <fix>
+Explain evidence: <query> keys/docs examined vs returned, before → after
+Not verified: <anything you could not run>
+```

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

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Should I embed comments inside the post document or put them in their own MongoDB collection?",
+    "This Mongo aggregation with $lookup and $group takes 8 seconds, help me speed it up",
+    "explain() shows COLLSCAN on our orders collection, what compound index do we need?",
+    "Add a $jsonSchema validator to the users collection without breaking existing documents",
+    "Do I need a transaction in Mongoose to move credits between two wallet documents?",
+    "Design the document model for a multi-tenant SaaS on MongoDB Atlas"
+  ],
+  "should_not_trigger": [
+    "Cache the user profile in Redis with a five minute TTL",
+    "Write a Prisma schema for users and posts on Postgres",
+    "Design a ClickHouse table for billions of analytics events",
+    "Normalise this Postgres schema and add foreign keys",
+    "Write a zero-downtime migration that renames a column in MySQL",
+    "Review this pull request for SQL injection and auth bugs"
+  ]
+}

package/skills/mongodb-patterns/references/indexes-and-aggregation.md

@@ -0,0 +1,94 @@
+# MongoDB indexes and aggregation recipes
+
+Read this when designing an index for a specific query, debugging a slow aggregation, or writing a migration that reshapes documents. Confirm option names against the MongoDB manual for the server version in use.
+
+## ESR worked example
+
+Query:
+
+```js
+db.orders.find({ tenantId: t, status: "open", total: { $gte: 100 } }).sort({ createdAt: -1 })
+```
+
+- Equality: `tenantId`, `status`
+- Sort: `createdAt`
+- Range: `total`
+
+Index: `{ tenantId: 1, status: 1, createdAt: -1, total: 1 }`. Putting `total` before `createdAt` forces an in-memory sort.
+
+A covered query (only indexed fields in filter and projection, `_id: 0` unless `_id` is indexed in that index) shows `totalDocsExamined: 0`.
+
+## Reading explain
+
+```js
+db.coll.find(filter).sort(sort).explain("executionStats")
+db.coll.aggregate(pipeline, { explain: true })   // or .explain("executionStats") on the cursor
+```
+
+| Field | Good sign | Bad sign |
+|---|---|---|
+| `winningPlan.stage` tree | `IXSCAN` → `FETCH` | `COLLSCAN`; `SORT` stage (in-memory sort) |
+| `totalKeysExamined` / `nReturned` | close to 1 | much larger: index not selective or wrong order |
+| `totalDocsExamined` / `nReturned` | close to 1 | large: filter applied after fetch |
+| `rejectedPlans` | few | many similar indexes competing |
+
+Use the profiler only with the user's agreement on shared servers: `db.setProfilingLevel(1, { slowms: 100 })`, then `db.system.profile.find().sort({ ts: -1 }).limit(10)`. Turn it off afterwards with `db.setProfilingLevel(0)`. On Atlas, the Query Profiler and Performance Advisor show the same without changing settings.
+
+## Index options
+
+```js
+db.users.createIndex({ email: 1 }, { unique: true, collation: { locale: "en", strength: 2 } })   // case-insensitive unique
+db.sessions.createIndex({ expiresAt: 1 }, { expireAfterSeconds: 0 })                             // TTL at the stored date
+db.orders.createIndex({ status: 1, createdAt: -1 }, { partialFilterExpression: { status: "open" } })
+db.coll.hideIndex("old_index_name")    // test dropping without losing it
+db.coll.unhideIndex("old_index_name")
+```
+
+- A query uses a collation-specific index only if it specifies the same collation.
+- A partial index is used only when the query filter implies the partial expression.
+- The TTL monitor runs periodically, so expired documents disappear with some delay; don't rely on it for exact expiry.
+- A multikey index (on an array field) can't be compound with a second array field.
+
+## Aggregation patterns
+
+Top N per group:
+
+```js
+db.orders.aggregate([
+  { $match: { tenantId: t, createdAt: { $gte: since } } },
+  { $sort: { customerId: 1, total: -1 } },
+  { $group: { _id: "$customerId", top: { $firstN: { input: "$$ROOT", n: 3 } } } }
+])
+```
+
+(`$firstN` needs MongoDB 5.2 or later; on older servers use `$push` then `$slice`.)
+
+Indexed `$lookup` with a sub-pipeline (combining `localField`/`foreignField` with `pipeline` needs MongoDB 5.0 or later; older servers need `let` and `$expr`):
+
+```js
+{ $lookup: {
+    from: "customers",
+    localField: "customerId",
+    foreignField: "_id",
+    pipeline: [{ $project: { name: 1, tier: 1 } }],
+    as: "customer"
+}}
+```
+
+Several counts in one pass:
+
+```js
+{ $facet: {
+    byStatus: [{ $group: { _id: "$status", n: { $sum: 1 } } }],
+    total:    [{ $count: "n" }]
+}}
+```
+
+Precompute a report: end the pipeline with `{ $merge: { into: "daily_sales", on: "_id", whenMatched: "replace" } }` and run it from a scheduled job.
+
+## Reshaping documents safely
+
+1. Add the new field in code that writes both shapes; read with a fallback.
+2. Backfill in batches with `bulkWrite` filtered on documents missing the new field, so the job can be re-run.
+3. Switch reads to the new field, then stop writing the old one, then remove it with `$unset` in batches.
+4. Tighten the `$jsonSchema` validator last.

package/skills/mpesa-daraja-integration/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: mpesa-daraja-integration
+description: Implements and audits direct Safaricom M-Pesa integrations on the Daraja API in Kenya, including the OAuth client-credentials token, Lipa na M-Pesa Online (STK Push) with the base64 shortcode+passkey+timestamp password, stkCallback parsing, confirmation through the STK Push Query endpoint, C2B URL registration with validation and confirmation, B2C payouts with SecurityCredential, and the sandbox-to-production go-live path. Use when calling Daraja endpoints yourself rather than via Flutterwave or another aggregator, wiring an M-Pesa paybill or till into an app, or debugging Daraja errors such as invalid access token, wrong credentials or ResultCode 1032.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to sandbox.safaricom.co.ke or api.safaricom.co.ke. 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"
+---
+
+# M-Pesa Daraja integration
+
+Build an M-Pesa flow where a forged callback can't mark an order paid, a lost callback still settles, and a payout is never sent twice. This skill is for Safaricom's Daraja API called directly. If the project collects M-Pesa through Flutterwave, Paystack or another aggregator, follow that provider's flow instead.
+
+## Ground rules
+
+1. **Credentials stay on the server.** Consumer key and secret, passkey, initiator name and initiator password are secrets in the environment. Sandbox and production have different keys, shortcodes, passkeys and base URLs (`https://sandbox.safaricom.co.ke` vs `https://api.safaricom.co.ke`).
+2. **Cache the access token.** `GET /oauth/v1/generate?grant_type=client_credentials` with Basic auth (`consumerKey:consumerSecret`) returns a token valid for about an hour (`expires_in` 3599 or 3600). Refresh before expiry; don't request one per payment.
+3. **The server sets the amount.** Daraja `Amount` is whole shillings. Compute it from your own order; never accept it from the client.
+4. **`ResponseCode: "0"` means accepted, not paid.** The STK Push response only says the prompt was queued. Store `CheckoutRequestID` and `MerchantRequestID` against the order straight away.
+5. **Callbacks are unsigned.** Daraja does not sign `stkCallback`, C2B or B2C results. Never give value from the callback body alone. Put an unguessable per-payment token in the callback path, match `CheckoutRequestID` to a stored pending payment, and confirm with STK Push Query (or Transaction Status) before fulfilling. If Safaricom gives you its callback IP range, allow-list it as an extra layer.
+6. **Fulfilment is idempotent.** Guarded update keyed on `CheckoutRequestID` (`... WHERE status = 'pending'`), and a unique constraint on `MpesaReceiptNumber`. Callbacks, queries and retries can all arrive.
+7. **Payouts are never sent blind twice.** Generate and store a unique `OriginatorConversationID` per payout before the call. Daraja is not documented to reject a repeated ID, so after a timeout or lost result check Transaction Status first and retry only when it shows the payout did not happen.
+
+## STK Push flow
+
+```
+client ──(order id, phone 2547XXXXXXXX)──▶ server: create pending payment
+server ──POST /mpesa/stkpush/v1/processrequest──▶ Daraja: ResponseCode "0", CheckoutRequestID
+customer enters M-Pesa PIN on the phone
+Daraja ──POST CallBackURL {Body.stkCallback}──▶ server: 200 at once, queue a check
+server ──POST /mpesa/stkpushquery/v1/query──▶ ResultCode 0 + amount matches → fulfil once
+background job: query payments still pending after ~1-2 minutes; expire them later
+```
+
+## Implementation steps
+
+1. **Configure** environment variables: base URL, consumer key/secret, `BusinessShortCode`, passkey, callback base URL, and for B2C the initiator name and production certificate. Shapes and samples: `references/api.md`.
+2. **Build the password**: `Timestamp` is `YYYYMMDDHHmmss` in Kenyan time (EAT, UTC+3); `Password = base64(BusinessShortCode + Passkey + Timestamp)`. Generate both per request; a stale timestamp or one in the wrong timezone causes "Wrong credentials".
+3. **Send STK Push** with `TransactionType` `CustomerPayBillOnline` (paybill) or `CustomerBuyGoodsOnline` (till; then `PartyB` is the till number while `BusinessShortCode` is the store/HO number). Normalise the phone to `2547XXXXXXXX` or `2541XXXXXXXX`. `AccountReference` is at most 12 characters, `TransactionDesc` at most 13.
+4. **Handle the callback** as in `references/callbacks.md`: respond quickly, match on `CheckoutRequestID`, read `ResultCode` and `CallbackMetadata`, then confirm with STK Push Query.
+5. **Map result codes** to customer messages: `1032` cancelled, `1037` phone unreachable, `1` insufficient balance, `2001` wrong PIN, `1019` expired, `17` duplicate request within 2 minutes. Let the customer retry with a new STK Push.
+6. **C2B (customer pays your paybill/till from their phone)**: register Confirmation and Validation URLs once with `/mpesa/c2b/v2/registerurl`; see `references/callbacks.md`. Match payments to orders by `BillRefNumber` (the account number the customer typed) and dedupe on `TransID`.
+7. **B2C payouts**: `/mpesa/b2c/v3/paymentrequest` with `SecurityCredential` (initiator password RSA-encrypted with Safaricom's certificate for that environment, base64). The result arrives at `ResultURL`; a timeout at `QueueTimeOutURL`. Treat a queue timeout as unknown, not failed: check Transaction Status before retrying.
+8. **Persist** per payment: order id, phone, amount, `MerchantRequestID`, `CheckoutRequestID`, `MpesaReceiptNumber`, `ResultCode`, `ResultDesc`, status, timestamps.
+
+## Reviewing an existing integration
+
+Check each ground rule, then look for:
+
+- Order marked paid when the STK Push request returns `ResponseCode "0"`.
+- Callback body trusted with no match to a stored `CheckoutRequestID` and no query.
+- `Amount` read from `CallbackMetadata` without comparing it to the stored order amount.
+- Token fetched on every request, causing spike-arrest or quota errors (`500.003.02`, `500.003.03`).
+- Timestamp built from server UTC or local time instead of EAT.
+- Callback URL that is not public HTTPS, uses a tunnel URL in production, or contains blocked words such as `mpesa`, `safaricom`, `sql`, `exec`, `cmd` or `query`.
+- Sandbox shortcode `174379` or sandbox passkey left in production config.
+- B2C retried after a timeout or missing result without a Transaction Status check first.
+
+## Stop and ask the user
+
+- Paybill or till, and which shortcode is used on go-live.
+- Whether C2B validation is needed; it is off by default and Safaricom has to enable it.
+- Before writing any B2C code: payouts move real money and need a B2C shortcode and an API initiator created on the M-Pesa org portal.
+
+## Before you finish
+
+Daraja's docs at developer.safaricom.co.ke are the final word on fields and endpoints; this skill gives the rules and the shape. Production endpoints and the production passkey are issued at go-live. Then test in the sandbox: a successful STK Push, a cancelled prompt (1032), a phone that never answers, a callback that never arrives (the query job must settle it), a forged callback with a known `CheckoutRequestID` but a failed query (must not fulfil), and the same callback twice.

package/skills/mpesa-daraja-integration/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Implement Lipa na M-Pesa STK push for our Kenyan delivery app using Daraja",
+    "Daraja keeps returning Wrong credentials for my STK push password, what's wrong?",
+    "Register C2B confirmation and validation URLs for our paybill number",
+    "Pay out refunds to customers' M-Pesa numbers with the B2C API",
+    "Our stkCallback never arrives in production, how do we still confirm the payment?"
+  ],
+  "should_not_trigger": [
+    "Charge a Kenyan customer's M-Pesa wallet through Flutterwave from our backend",
+    "Integrate MTN MoMo request to pay for Ugandan customers",
+    "Accept Telecel Cash payments through Hubtel in our Ghana app",
+    "Check our checkout code for client-trusted amounts and missing idempotency",
+    "Add Stripe Checkout for card payments in Kenya"
+  ]
+}

package/skills/mpesa-daraja-integration/references/api.md

@@ -0,0 +1,103 @@
+# Daraja API shapes used by this skill
+
+Base URLs: sandbox `https://sandbox.safaricom.co.ke`, production `https://api.safaricom.co.ke`. Every call except the token call sends `Authorization: Bearer <token>` and `Content-Type: application/json` (a missing content type gives "Bad Request - Invalid BusinessShortCode").
+
+Confirm fields against developer.safaricom.co.ke before shipping; this is a working summary.
+
+## Access token
+
+`GET /oauth/v1/generate?grant_type=client_credentials` with `Authorization: Basic base64(consumerKey:consumerSecret)`.
+
+Response: `{ "access_token": "...", "expires_in": "3599" }`. `404.001.03 Invalid Access Token` means expired or from the wrong app.
+
+## STK Push (M-Pesa Express)
+
+`POST /mpesa/stkpush/v1/processrequest`
+
+```json
+{
+  "BusinessShortCode": "174379",
+  "Password": "<base64(BusinessShortCode + Passkey + Timestamp)>",
+  "Timestamp": "20260618092408",
+  "TransactionType": "CustomerPayBillOnline",
+  "Amount": "150",
+  "PartyA": "254712345678",
+  "PartyB": "174379",
+  "PhoneNumber": "254712345678",
+  "CallBackURL": "https://api.example.com/hooks/daraja/stk/<per-payment-token>",
+  "AccountReference": "ORD8F2C1A",
+  "TransactionDesc": "Order"
+}
+```
+
+Response: `MerchantRequestID`, `CheckoutRequestID`, `ResponseCode` (`"0"` = accepted), `ResponseDescription`, `CustomerMessage`.
+
+Limits from the Daraja FAQ: minimum KES 1, up to KES 250,000 per transaction, daily KES 500,000. Only one prompt can be live per subscriber; "Unable to lock subscriber" means wait about a minute.
+
+## STK Push Query
+
+`POST /mpesa/stkpushquery/v1/query`
+
+```json
+{ "BusinessShortCode": "174379", "Password": "<fresh>", "Timestamp": "<fresh>", "CheckoutRequestID": "ws_CO_..." }
+```
+
+Response has `ResultCode` and `ResultDesc`. `ResultCode` `"0"` = paid. While the customer has not answered, the query returns an error rather than a final code; retry with backoff.
+
+## Result codes (STK)
+
+| Code | Meaning |
+|---|---|
+| 0 | Paid |
+| 1 | Insufficient balance |
+| 17 | Same amount to same customer within 2 minutes |
+| 1019 | Transaction expired |
+| 1025 | Push failed (prompt over 182 characters; shorten AccountReference) |
+| 1032 | Cancelled by user |
+| 1037 | Phone unreachable |
+| 2001 | Wrong PIN |
+| 2028 | TransactionType / PartyB don't match the shortcode type |
+
+## C2B register URLs
+
+`POST /mpesa/c2b/v2/registerurl`
+
+```json
+{ "ShortCode": "600638", "ResponseType": "Completed", "ConfirmationURL": "https://api.example.com/hooks/daraja/c2b/confirm", "ValidationURL": "https://api.example.com/hooks/daraja/c2b/validate" }
+```
+
+`ResponseType` (`Completed` or `Cancelled`) is what M-Pesa does when your validation URL is unreachable. In production, registration is one-time; change URLs by deleting them in the URL management self-service and re-registering. Sandbox has `/mpesa/c2b/v2/simulate` for test payments.
+
+## B2C payment
+
+`POST /mpesa/b2c/v3/paymentrequest`
+
+```json
+{
+  "OriginatorConversationID": "payout_7d1e9b",
+  "InitiatorName": "apiop",
+  "SecurityCredential": "<RSA-encrypt(initiator password, Safaricom cert) as base64>",
+  "CommandID": "BusinessPayment",
+  "Amount": "500",
+  "PartyA": "600997",
+  "PartyB": "254712345678",
+  "Remarks": "Refund ORD8F2C1A",
+  "QueueTimeOutURL": "https://api.example.com/hooks/daraja/b2c/timeout/<token>",
+  "ResultURL": "https://api.example.com/hooks/daraja/b2c/result/<token>",
+  "Occassion": "Refund"
+}
+```
+
+`CommandID`: `BusinessPayment`, `SalaryPayment` or `PromotionPayment`. Note the API's spelling `Occassion`. The sandbox and production certificates differ. The response (`ConversationID`, `OriginatorConversationID`, `ResponseCode`) only means accepted; the outcome is the `Result` posted to `ResultURL` (`ResultCode`, `TransactionID`, `ResultParameters.ResultParameter[]`).
+
+## Password and timestamp (TypeScript)
+
+```ts
+export function stkPassword(shortCode: string, passkey: string, now = new Date()) {
+  // Daraja expects Kenyan time (EAT, UTC+3), formatted YYYYMMDDHHmmss
+  const eat = new Date(now.getTime() + 3 * 60 * 60 * 1000).toISOString();
+  const timestamp = eat.slice(0, 19).replace(/[-T:]/g, '');
+  const password = Buffer.from(shortCode + passkey + timestamp).toString('base64');
+  return { timestamp, password };
+}
+```

package/skills/mpesa-daraja-integration/references/callbacks.md

@@ -0,0 +1,74 @@
+# Daraja callbacks
+
+None of these are signed. Treat every body as untrusted: match it to a record you created, then confirm with a query before giving value.
+
+## STK Push callback
+
+`POST` to your `CallBackURL`:
+
+```json
+{
+  "Body": {
+    "stkCallback": {
+      "MerchantRequestID": "29115-34620561-1",
+      "CheckoutRequestID": "ws_CO_191220191020363925",
+      "ResultCode": 0,
+      "ResultDesc": "The service request is processed successfully.",
+      "CallbackMetadata": {
+        "Item": [
+          { "Name": "Amount", "Value": 1.0 },
+          { "Name": "MpesaReceiptNumber", "Value": "NLJ7RT61SV" },
+          { "Name": "TransactionDate", "Value": 20191219102115 },
+          { "Name": "PhoneNumber", "Value": 254708374149 }
+        ]
+      }
+    }
+  }
+}
+```
+
+A failed or cancelled payment has `ResultCode` other than `0` and no `CallbackMetadata`. Read items by `Name`, not by position; `Balance` sometimes appears and shifts the order.
+
+### Handler rules
+
+1. Check the per-payment token in the path, then find the pending payment by `CheckoutRequestID`. Unknown → log and return 200; never create an order from a callback.
+2. Respond `200` with `{ "ResultCode": 0, "ResultDesc": "Accepted" }` quickly and queue the work.
+3. In the worker: if `ResultCode !== 0`, mark failed with the code. If `0`, run STK Push Query; fulfil only if the query says `0` **and** `Amount` equals the stored amount. Guarded update on status, unique `MpesaReceiptNumber`.
+
+```ts
+app.post('/hooks/daraja/stk/:token', express.json(), async (req, res) => {
+  const cb = req.body?.Body?.stkCallback;
+  const payment = cb && (await payments.findPending(cb.CheckoutRequestID, req.params.token));
+  res.json({ ResultCode: 0, ResultDesc: 'Accepted' });
+  if (payment) await queue.add('daraja-confirm', { checkoutRequestId: cb.CheckoutRequestID, resultCode: cb.ResultCode });
+});
+```
+
+## C2B validation and confirmation
+
+Both URLs receive the same shape:
+
+```json
+{
+  "TransactionType": "Pay Bill",
+  "TransID": "RKTQDM7W6S",
+  "TransTime": "20191122063845",
+  "TransAmount": "10",
+  "BusinessShortCode": "600638",
+  "BillRefNumber": "invoice008",
+  "InvoiceNumber": "",
+  "OrgAccountBalance": "",
+  "ThirdPartyTransID": "",
+  "MSISDN": "25470****149",
+  "FirstName": "John",
+  "MiddleName": "",
+  "LastName": "Doe"
+}
+```
+
+- **Validation** (only if Safaricom enabled external validation on your shortcode): reply `{ "ResultCode": "0", "ResultDesc": "Accepted" }` to accept, or `{ "ResultCode": "C2B00012", "ResultDesc": "Rejected" }` to reject (`C2B00011` invalid MSISDN, `C2B00012` invalid account number, `C2B00013` invalid amount, `C2B00014` invalid KYC, `C2B00015` invalid shortcode, `C2B00016` other). Reply fast; if it is unreachable M-Pesa applies the registered `ResponseType`.
+- **Confirmation**: the payment is complete. Dedupe on `TransID`, match `BillRefNumber` to an open invoice, compare `TransAmount`, and park anything that doesn't match for manual review instead of dropping it: the customer's money has already moved. `MSISDN` may be masked or hashed, so don't rely on it to identify the payer.
+
+## B2C result
+
+`POST` to `ResultURL` with `{ "Result": { "ResultType", "ResultCode", "ResultDesc", "OriginatorConversationID", "ConversationID", "TransactionID", "ResultParameters": { "ResultParameter": [ { "Key", "Value" } ] } } }`. Match on `OriginatorConversationID`. `ResultCode` `0` = paid. A post to `QueueTimeOutURL` means the outcome is unknown: run Transaction Status (`/mpesa/transactionstatus/v1/query`) before any retry.