@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/homelab-network-setup/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: homelab-network-setup
+description: Plans and builds a self-hosted home lab network from an address and VLAN plan through inter-VLAN firewall policy, local DNS filtering with Pi-hole or AdGuard Home, WireGuard remote access, configuration backups, and exposing a few services to the internet without opening the whole LAN. Use when someone is designing or rebuilding a home or small-office network, isolating IoT or guest devices, setting up a VPN to reach home from outside, or deciding how to publish a self-hosted app safely.
+license: MIT
+compatibility: Any Agent Skills host. Vendor-neutral; applies to OPNsense, pfSense, OpenWrt, MikroTik, UniFi and similar routers. WireGuard commands need wireguard-tools.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: devops
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# Home lab network setup
+
+Produce a written plan first, then configs. A home lab is usually run by one person with no out-of-band access, so every step must leave a way back in.
+
+WireGuard configs and key handling are in `references/wireguard.md`. A starting firewall policy matrix and DNS details are in `references/firewall-and-dns.md`. Read them when you reach those steps.
+
+## Ground rules
+
+1. **Plan before touching the router.** Write the address plan, VLAN list and firewall matrix and get the user to confirm it.
+2. **Keep a way back in.** Before changing the router or firewall: export its configuration, keep a wired port on the management network, and know how to factory-reset and restore. Never change the VLAN or rules on the port or Wi-Fi you are using to manage it without a rollback.
+3. **Default deny between segments.** Each VLAN reaches only what the matrix allows. The internet never reaches the LAN except through the VPN or an explicitly published service.
+4. **Prefer VPN to port forwards.** A service reachable only over WireGuard has no internet attack surface beyond one UDP port that ignores unauthenticated packets.
+5. **Secrets stay local.** Never print or commit private keys, PSKs, admin passwords or API tokens. Generate keys on the device that uses them.
+
+## Step 1: Gather facts (ask if unknown)
+
+- Router/firewall hardware and OS, and whether switches and access points support 802.1Q VLANs (managed or "smart" switches; unmanaged switches do not).
+- ISP setup: does the router's WAN address match the public IP shown by an external "what is my IP" check? A WAN address in `100.64.0.0/10`, or one that does not match, means CGNAT: inbound port forwards and a plain WireGuard server will not work. Stop and offer a relay option (a VPS endpoint or a mesh VPN service) or asking the ISP for a public IPv4.
+- Devices by trust level, and which services must be reachable from where.
+- Whether IPv6 is delivered. If it is, every rule below must be written for IPv6 too, because IPv6 hosts are globally addressable.
+
+## Step 2: Address and VLAN plan
+
+Use one `/24` per VLAN from `10.0.0.0/8` or `172.16.0.0/12`, and avoid `192.168.0.0/24` and `192.168.1.0/24`: they collide with most remote networks you will VPN in from. Make the third octet equal the VLAN ID so addresses are self-describing.
+
+| VLAN | Name | Example subnet | Holds |
+|---|---|---|---|
+| 10 | mgmt | 10.10.10.0/24 | Router, switch, AP and hypervisor admin interfaces |
+| 20 | trusted | 10.10.20.0/24 | Your laptops and phones |
+| 30 | servers | 10.10.30.0/24 | Self-hosted services, NAS |
+| 40 | iot | 10.10.40.0/24 | TVs, smart plugs, speakers |
+| 50 | guest | 10.10.50.0/24 | Visitors, internet only |
+| 60 | cameras | 10.10.60.0/24 | IP cameras, no internet |
+| — | wg | 10.10.99.0/24 | WireGuard clients (not a VLAN, a routed tunnel subnet) |
+
+- Use `home.arpa` (reserved for home networks by RFC 8375) or a subdomain of a domain you own for local names. Do not use `.local` (mDNS) or an invented TLD.
+- Reserve static DHCP leases for servers and infrastructure; keep a dynamic range for the rest.
+- Switch ports: trunk (tagged) to the router, APs and hypervisors; access (untagged) ports for single devices. Map each Wi-Fi SSID to one VLAN.
+
+## Step 3: Firewall policy
+
+Write the policy as a matrix, source rows by destination columns, before writing any rule. Start from `references/firewall-and-dns.md` and adapt it. Then on each internal interface, in this order:
+
+1. Allow established and related traffic.
+2. Allow DNS (UDP and TCP 53) and DHCP to the router or the DNS server only.
+3. Allow the specific source-to-destination ports from the matrix (for example trusted → servers TCP 443, 22).
+4. Block the interface's traffic to all private ranges (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, and the router's own addresses on other VLANs, including its admin UI).
+5. Allow to the internet (any remaining destination), except for VLANs that must stay offline, such as cameras.
+
+- Admin UIs (router, switch, hypervisor, NAS) answer only from mgmt and trusted, never from IoT or guest.
+- Casting and discovery across VLANs need an mDNS reflector or repeater on the router plus narrow allow rules; enable them only for the pairs that need them.
+- Turn UPnP/NAT-PMP off, or limit it to one gaming console's address. It lets any LAN device open inbound ports.
+
+## Step 4: DNS
+
+1. Run Pi-hole or AdGuard Home on a static address in the servers or mgmt VLAN, with upstream either a public DoT/DoH resolver or a local recursive resolver such as Unbound.
+2. Hand it out by DHCP on every VLAN. Do not list a public resolver as a second DNS server: clients use both, and filtering silently stops.
+3. If you want a fallback, run a second filtering instance, not a public resolver.
+4. Optionally redirect or block outbound port 53 from clients so hard-coded resolvers go through yours. Devices using DNS-over-HTTPS will bypass this; that needs DoH blocklists, not a port rule.
+5. Add local records for each service (`nas.home.arpa`) so you never browse by IP.
+
+## Step 5: WireGuard remote access
+
+Follow `references/wireguard.md`. The essentials:
+
+- Run the server on the router or a server in the servers VLAN; forward one UDP port (51820 by convention) to it.
+- One key pair per client device. `AllowedIPs` on the server side is that peer's single tunnel address (`/32`).
+- Split tunnel (clients route only the home subnets) by default; full tunnel (`0.0.0.0/0, ::/0`) only when the user wants all traffic to exit at home.
+- Treat the `wg` subnet as its own source in the firewall matrix: usually the same access as trusted, never more.
+- For a dynamic home IP, point a DNS name at it with dynamic DNS and use that name as the client `Endpoint`.
+
+## Step 6: Publishing a service safely
+
+Ask first whether the service really needs to be public. If only the user and family use it, the VPN is the answer. When it must be public:
+
+1. Put it in the servers VLAN (or a dedicated DMZ VLAN) that cannot initiate connections to trusted or mgmt.
+2. Expose only a reverse proxy on TCP 443 with automatic certificates; forward nothing else. Never forward SSH, RDP, SMB, database ports, or any admin UI.
+3. Add authentication in front of apps that lack strong login (a forward-auth or SSO layer), and rate limiting or ban-on-failure.
+4. As an alternative to a port forward, an outbound tunnel service keeps the home IP private and works behind CGNAT. Note that the provider then sees the traffic.
+5. Keep the published software patched; subscribe to its release notes.
+
+## Step 7: Backups and change safety
+
+- Export router, switch and AP configs after every change and store them off the device (encrypted if they contain keys). Note firmware versions with them.
+- Back up the DNS server's config and the WireGuard configs the same way.
+- Before applying firewall changes remotely, schedule an automatic rollback (use the router's own mechanism if it has one, such as MikroTik Safe Mode; on Linux, schedule a restore of the saved ruleset with `at` or a timer) and cancel it only once you have reconnected.
+- Follow 3-2-1 for data on the NAS: three copies, two media, one off-site.
+
+## Stop and ask the user
+
+- Before applying any change to the router, firewall or switch you connect through.
+- When CGNAT is detected, or the hardware cannot do VLANs.
+- Before exposing anything to the internet; confirm which service, who uses it, and the auth in front of it.
+
+## Never
+
+- Never put admin interfaces on the WAN or in the guest/IoT VLANs.
+- Never reuse one WireGuard key pair on several devices.
+- Never write keys, passwords or real public IPs into files that will be committed or shared.
+
+## Deliverable
+
+```
+1. Facts: hardware, ISP/CGNAT result, IPv6 yes/no
+2. Address and VLAN plan (table)
+3. Firewall matrix (table) and rule order per interface
+4. DNS: server, upstream, records, how clients get it
+5. Remote access: WireGuard server, port, peers, split or full tunnel
+6. Published services: name, path (proxy/tunnel), auth
+7. Backup and rollback plan
+8. Order of work, with the step that could cut access marked
+9. Open questions for the user
+```

package/skills/homelab-network-setup/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "I just bought a managed switch and an OPNsense box, how should I lay out VLANs for my homelab?",
+    "Help me put all my smart plugs and the TV on their own network so they can't see my NAS",
+    "Set up WireGuard so I can reach Jellyfin and my NAS at home from my phone",
+    "Should I port forward Nextcloud or is there a safer way to make it reachable from outside?",
+    "Plan a Pi-hole setup for every VLAN at home without a public DNS fallback leaking queries",
+    "I'm rebuilding my home network from scratch, guest Wi-Fi, cameras with no internet, the works"
+  ],
+  "should_not_trigger": [
+    "My laptop gets a 169.254 address and can't reach anything, how do I debug it?",
+    "Audit this pf.conf and OpenVPN server config from my firewall for weak settings",
+    "Write a docker-compose file for Nextcloud with Postgres and Redis",
+    "Create a Kubernetes Ingress with cert-manager for my cluster",
+    "Design an AWS VPC with private subnets and a NAT gateway for production",
+    "dig shows SERVFAIL for my domain but only on some resolvers, why?"
+  ]
+}

package/skills/homelab-network-setup/references/firewall-and-dns.md

@@ -0,0 +1,45 @@
+# Firewall matrix and DNS details
+
+## Starting matrix
+
+Rows are sources, columns are destinations. "Ports" means only the listed ports; everything not listed is blocked. Adapt it with the user, then turn each cell into rules.
+
+| From \ To | mgmt | trusted | servers | iot | guest | cameras | internet |
+|---|---|---|---|---|---|---|---|
+| mgmt | allow | allow | allow | allow | no | allow | allow |
+| trusted | admin ports (443, 22) | allow | service ports | control ports (casting, app) | no | NVR ports | allow |
+| wg (VPN) | admin ports, if wanted | same as trusted | service ports | no | no | NVR ports | per tunnel mode |
+| servers | no | no | allow | no | no | NVR pulls streams | allow (updates) |
+| iot | no | replies only | specific ports (Home Assistant, MQTT) | allow or no | no | no | allow |
+| guest | no | no | no | no | no (client isolation) | no | allow |
+| cameras | no | no | NVR only | no | no | no | **no** |
+
+"Replies only" is covered by the established/related rule; it never needs its own allow.
+
+Every VLAN also needs: DNS to the DNS server, DHCP to the router, and NTP to the router (or allow NTP out) so clocks stay correct for TLS.
+
+## Rule example (nftables, one internal interface)
+
+```nft
+table inet filter {
+  chain forward {
+    type filter hook forward priority 0; policy drop;
+    ct state established,related accept
+    ct state invalid drop
+    iifname "vlan40" ip daddr 10.10.30.53 meta l4proto { tcp, udp } th dport 53 accept   # iot -> Pi-hole/AdGuard
+    iifname "vlan40" ip daddr 10.10.30.10 tcp dport { 1883, 8123 } accept   # iot -> Home Assistant, MQTT
+    iifname "vlan40" ip daddr { 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16 } drop
+    iifname "vlan40" oifname "wan" accept
+  }
+}
+```
+
+Check a ruleset file without applying it: `sudo nft -c -f ruleset.nft`. Put every allow to a private address (DNS server included) above the private-range drop, or it never matches. Rules for traffic to the router itself (its DNS, admin UI) go in the `input` chain, not `forward`.
+
+## DNS details
+
+- **Recursive upstream.** Running Unbound locally as Pi-hole/AdGuard's upstream means no third-party resolver sees your queries; the trade-off is your ISP sees queries to authoritative servers in clear text. A DoT/DoH upstream hides queries from the ISP but trusts that provider.
+- **Conditional forwarding** lets the DNS server ask the router for names of DHCP clients (`laptop.home.arpa`) and for reverse lookups of local addresses.
+- **Router's own DNS.** If the router also runs a resolver, either point it at the filter too or disable it, so there is one source of truth.
+- **IPv6.** Router advertisements can hand out their own DNS server (RDNSS). Make it the filter's IPv6 address, or clients will bypass the filter over IPv6.
+- **Do not expose DNS to the WAN.** An open resolver on port 53 is abused for amplification attacks. Allow port 53 only from internal interfaces and the VPN.

package/skills/homelab-network-setup/references/wireguard.md

@@ -0,0 +1,72 @@
+# WireGuard remote access
+
+## Keys
+
+Generate each key pair on the device that will use it, so the private key never travels:
+
+```sh
+umask 077
+wg genkey | tee client.key | wg pubkey > client.pub
+wg genpsk > client.psk   # optional pre-shared key per peer, adds a symmetric layer
+```
+
+Only public keys (and the PSK, over a secure channel) are exchanged. Phone apps generate their own pair; copy only the public key off the phone. If you must generate a config for a phone elsewhere and show it as a QR code (`qrencode -t ansiutf8 < phone.conf`), delete the file afterwards.
+
+## Server (`/etc/wireguard/wg0.conf`)
+
+```ini
+[Interface]
+Address = 10.10.99.1/24
+ListenPort = 51820
+PrivateKey = <server private key>
+
+[Peer]
+# laptop
+PublicKey = <laptop public key>
+PresharedKey = <laptop psk>
+AllowedIPs = 10.10.99.2/32
+
+[Peer]
+# phone
+PublicKey = <phone public key>
+AllowedIPs = 10.10.99.3/32
+```
+
+- Server-side `AllowedIPs` is both a route and an access check: packets from that peer are accepted only from those source addresses. Give each client a single `/32` (and `/128` for IPv6). Add a subnet only for a site-to-site peer that routes a whole network.
+- The server needs IP forwarding (`net.ipv4.ip_forward=1`, and `net.ipv6.conf.all.forwarding=1` for IPv6) and firewall rules allowing `wg0` to reach the permitted VLANs. If the home subnets do not know the route back to `10.10.99.0/24` (the server is not the router), add that route on the router or NAT the tunnel traffic.
+- On router OSes (OPNsense, pfSense, OpenWrt, MikroTik) the same fields exist in the WireGuard UI; the firewall rules go on the WireGuard interface.
+
+## Client
+
+```ini
+[Interface]
+Address = 10.10.99.2/32
+PrivateKey = <laptop private key>
+DNS = 10.10.30.53           # your Pi-hole/AdGuard, so home names resolve
+
+[Peer]
+PublicKey = <server public key>
+PresharedKey = <laptop psk>
+Endpoint = vpn.example.com:51820
+AllowedIPs = 10.10.0.0/16   # split tunnel: home subnets only
+PersistentKeepalive = 25    # only needed if the client sits behind NAT and must receive traffic
+```
+
+- Full tunnel: `AllowedIPs = 0.0.0.0/0, ::/0`. Then home DNS and the server's NAT to the internet must work, or the client loses all connectivity.
+- If the client's own LAN uses the same subnet as home, routing breaks. That is why the plan avoids `192.168.0.0/24` and `192.168.1.0/24`.
+
+## Bring up and check
+
+```sh
+sudo wg-quick up wg0
+sudo wg show            # after sending traffic (ping the server tunnel IP): a recent "latest handshake" and rising transfer counters = working
+sudo systemctl enable wg-quick@wg0   # start at boot on systemd hosts
+```
+
+- No handshake at all: the UDP port forward, the ISP (CGNAT), the `Endpoint` name, or mismatched public keys.
+- Handshake but no traffic: `AllowedIPs` on either side, IP forwarding, or firewall rules on `wg0`.
+- Handshake and pings work but web pages or SSH stall: MTU. Set `MTU = 1280` in the client `[Interface]` to test, then raise it.
+
+## Revoking a device
+
+Delete its `[Peer]` block from the server's `wg0.conf`, then apply without dropping other peers: `sudo wg syncconf wg0 <(sudo wg-quick strip wg0)` (bash), or remove it live with `sudo wg set wg0 peer <pubkey> remove`. Do both, or the peer returns on the next restart. Because each device has its own key, nothing else changes.

package/skills/hubtel-integration/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: hubtel-integration
+description: Guides Ghana-focused Hubtel merchant integrations end to end, from Online Checkout (redirect or onsite iframe) and Direct Receive Money prompts on MTN, Telecel and AirtelTigo wallets to callback handling, the mandatory Transaction Status Check, Basic auth with API ID and key, the 4-IP whitelist, and sending SMS through the Hubtel SMS API. Use when accepting payments into a Hubtel Merchant Account, wiring a Hubtel callback or status check, fixing a Hubtel 403 or 4000 response, or sending transactional SMS through Hubtel.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to Hubtel's API hosts from a whitelisted server IP. 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"
+---
+
+# Hubtel integration
+
+Accept payments into a Hubtel Merchant Account so that a fake callback can't mark an order paid, a missing callback still settles, and a `clientReference` is never charged twice. Also covers sending SMS. If the project takes Ghana payments through Paystack or calls MTN MoMo directly, follow that skill instead.
+
+## Ground rules
+
+1. **Credentials stay on the server.** Sales (payments) use `Authorization: Basic base64(API ID:API Key)`; SMS uses `base64(ClientID:ClientSecret)`. Read both from the environment. They are different credential pairs.
+2. **Calls only work from whitelisted IPs.** Share your server's public egress IP with your Hubtel Retail Systems Engineer. Hubtel allows at most 4 IPs per service; anything else gets `403 Forbidden` or a timeout. Serverless functions with changing IPs need a fixed-egress proxy or NAT.
+3. **Your Collection Account Number is in the URL or body** of every payment and status call. It identifies your merchant account; keep it in config, not code.
+4. **One unique `clientReference` per attempt, stored first.** Hubtel says it must never be duplicated. Max 32 characters for Online Checkout, 36 for Direct Receive Money; use alphanumerics.
+5. **The server sets the amount.** `totalAmount` / `Amount` are decimals in cedis with at most 2 decimal places. Keep integer pesewas in your database and format at the boundary (`(pesewas / 100).toFixed(2)`), never compute with floats.
+6. **Callbacks are not signed.** Use them as a trigger only. Confirm with the Transaction Status Check, and give value only when `status` is `Paid` and the amount equals what you stored. Hubtel publishes a callback source IP per product that you can allow-list (see `references/api.md`).
+7. **Status check is mandatory when no callback arrives.** Hubtel's docs require it for any transaction with no final callback after 5 minutes. Run it from a background job.
+8. **Prevent unsolicited prompts.** For Direct Receive Money, Hubtel requires that customers can't freely type any number: either lock the number to a verified account or send an OTP to the number first.
+
+## Choose the flow
+
+| Need | Use |
+|---|---|
+| Hosted page with mobile money, card, Hubtel/G-Money wallet and GhQR | Online Checkout: `POST https://payproxyapi.hubtel.com/items/initiate`, redirect to `checkoutUrl` or embed `checkoutDirectUrl` in an iframe |
+| Prompt a wallet from your own UI | Direct Receive Money: `POST https://rmp.hubtel.com/merchantaccount/merchants/{Collection_Account_Number}/receive/mobilemoney` with `Channel` `mtn-gh`, `vodafone-gh` (Telecel) or `tigo-gh` (AirtelTigo) |
+| Notify a customer | SMS: `POST https://sms.hubtel.com/v1/messages/send` |
+
+## Flow
+
+```
+client ──(order id)──▶ server: create pending payment with clientReference
+server ──initiate checkout or receive money──▶ Hubtel
+   checkout: responseCode "0000" + checkoutUrl → redirect customer
+   receive money: ResponseCode "0001" = pending, customer approves on phone
+Hubtel ──POST callbackUrl / PrimaryCallbackURL──▶ server: 200 fast, queue a status check
+server ──GET api-txnstatus.hubtel.com/transactions/{acct}/status?clientReference=..──▶ Paid + amount match → fulfil once
+background job: status-check anything still pending after 5 minutes
+```
+
+## Implementation steps
+
+1. **Configure**: API ID and key, Collection Account Number, callback base URL, and (for SMS) client ID, secret and an approved sender ID (max 11 characters). Confirm the server's egress IP is whitelisted before debugging anything else.
+2. **Initiate** with the request bodies in `references/api.md`. `description` must not contain special characters (`&*!%@`), which Hubtel rejects.
+3. **Callback endpoint**: accept `POST`, respond `200` quickly, look up the pending payment by `ClientReference` from the body, and enqueue a status check. Unknown reference → log and ignore.
+4. **Status check** `GET https://api-txnstatus.hubtel.com/transactions/{Collection_Account_Number}/status?clientReference=...`. Map `data.status`: `Paid` → fulfil (guarded update `WHERE status = 'pending'`), `Unpaid` → keep waiting until your timeout then mark failed, `Refunded` → reverse fulfilment.
+5. **Map response codes** using `references/api.md`: `0000` success, `0001` pending, `2001` customer-side failure (insufficient funds, wrong PIN, timeout), `4000` validation error, `4070` fees not set or below minimum, `0005` unknown state (contact Hubtel; do not retry blindly).
+6. **SMS**: send with Basic auth, then store `messageId` and check delivery with `GET https://sms.hubtel.com/v1/messages/{messageId}`. `Sent` is not `Delivered`.
+7. **Persist** per payment: `clientReference`, order id, expected amount (pesewas), channel, phone, Hubtel `TransactionId` / `checkoutId`, `ExternalTransactionId`, charges, status, timestamps.
+
+## Reviewing an existing integration
+
+- Order fulfilled from the callback body, or from `0000` on the initiate response.
+- No status-check job, so payments stuck in `0001` never settle.
+- `clientReference` reused on retry, or longer than the limit.
+- Float amounts with more than 2 decimals, or a price taken from the client.
+- Sales and SMS credentials mixed up, or credentials in client code.
+- Calls from an unwhitelisted host (works locally through a VPN, fails in production with 403).
+- Direct Receive Money open to any typed phone number with no OTP or account lock.
+- Charges ignored: `AmountAfterCharges` is what settles; reconcile on it.
+
+## Stop and ask the user
+
+- Whether they already have a Hubtel Merchant Account, the Collection Account Number, and a whitelisted IP. Without these nothing can be tested live.
+- Which product they want (Online Checkout or Direct Receive Money) and whether Hubtel has enabled it on the account.
+- Before sending bulk SMS: sender ID approval and consent for marketing messages.
+
+## Before you finish
+
+Hubtel's docs at developers.hubtel.com are the final word; this skill gives the rules and the shape. Then test: a paid checkout, a cancelled checkout, a wallet prompt the customer rejects, a prompt that times out, a callback that never arrives (status job settles it), the same callback twice (fulfils once), and a forged callback for a real `clientReference` while the status check says `Unpaid` (must not fulfil).

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Integrate Hubtel online checkout for a Ghanaian school fees portal",
+    "Accept Telecel Cash payments through Hubtel in our Ghana app",
+    "Hubtel receive money returns 403 Forbidden from our server, why?",
+    "Send order confirmation SMS to customers with Hubtel",
+    "Hubtel never sent the callback for some payments, how do I check their status?"
+  ],
+  "should_not_trigger": [
+    "Let users pay with MTN MoMo through Paystack in the mobile app",
+    "Call the MTN MoMo Open API requesttopay endpoint directly",
+    "Accept Ghana mobile money with Flutterwave direct charge instead of the hosted page",
+    "Audit our payment webhook handlers for missing signature checks",
+    "Send transactional email receipts with SendGrid after checkout"
+  ]
+}

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

@@ -0,0 +1,92 @@
+# Hubtel API shapes used by this skill
+
+Payments (Sales) auth: `Authorization: Basic base64(API ID:API Key)`. SMS auth: `Authorization: Basic base64(ClientID:ClientSecret)`. Send `Content-Type: application/json`. All payment hosts only answer whitelisted IPs (max 4 per service).
+
+Confirm fields against developers.hubtel.com before shipping; this is a working summary.
+
+## Online Checkout
+
+`POST https://payproxyapi.hubtel.com/items/initiate`
+
+```json
+{
+  "totalAmount": 25.50,
+  "description": "Order 8F2C1A",
+  "callbackUrl": "https://api.example.com/hooks/hubtel/checkout",
+  "returnUrl": "https://app.example.com/pay/return",
+  "cancellationUrl": "https://app.example.com/pay/cancelled",
+  "merchantAccountNumber": "<Collection Account Number>",
+  "clientReference": "ord8f2c1aA1",
+  "payeeName": "Ama Mensah",
+  "payeeMobileNumber": "233241234567",
+  "payeeEmail": "ama@example.com"
+}
+```
+
+All fields above are mandatory except the `payee*` ones. `clientReference` max 32 characters. Response: `responseCode` `"0000"` (accepted), `data.checkoutUrl` (redirect), `data.checkoutDirectUrl` (onsite iframe), `data.checkoutId`, `data.clientReference`. The return URL is display only; fulfilment waits for the callback plus status check.
+
+Checkout callback source IP to allow-list (optional extra layer, confirm the current value in Hubtel's docs because it can change): `108.129.40.25`.
+
+## Direct Receive Money
+
+`POST https://rmp.hubtel.com/merchantaccount/merchants/{Collection_Account_Number}/receive/mobilemoney`
+
+```json
+{
+  "CustomerName": "Ama Mensah",
+  "CustomerMsisdn": "233241234567",
+  "CustomerEmail": "ama@example.com",
+  "Channel": "mtn-gh",
+  "Amount": 25.50,
+  "PrimaryCallbackURL": "https://api.example.com/hooks/hubtel/receive",
+  "Description": "Order 8F2C1A",
+  "ClientReference": "ord8f2c1aA1"
+}
+```
+
+| Channel | Network |
+|---|---|
+| `mtn-gh` | MTN Ghana |
+| `vodafone-gh` | Telecel Ghana |
+| `tigo-gh` | AirtelTigo |
+
+`CustomerMsisdn` in international format (`233...`) and on the network named by `Channel`. `ClientReference` max 36 characters. Response: `ResponseCode` `"0001"` (pending, callback follows), `Data.TransactionId`, `Data.Amount`, `Data.Charges`, `Data.AmountAfterCharges`, `Data.AmountCharged`. The final state usually arrives within about 30 seconds.
+
+Receive Money callback source IP to allow-list (optional extra layer, confirm the current value in Hubtel's docs): `18.202.122.131`.
+
+## Transaction Status Check
+
+`GET https://api-txnstatus.hubtel.com/transactions/{Collection_Account_Number}/status?clientReference=ord8f2c1aA1`
+
+Also accepts `hubtelTransactionId` or `networkTransactionId`; prefer `clientReference`. Response `data`: `status` (`Paid`, `Unpaid`, `Refunded`), `amount`, `charges`, `amountAfterCharges`, `transactionId`, `externalTransactionId`, `paymentMethod`, `clientReference`, `date`.
+
+## Response codes
+
+| Code | Meaning | Action |
+|---|---|---|
+| `0000` | Success (in a callback: paid; on checkout initiate: accepted) | Confirm with status check, then fulfil |
+| `0001` | Accepted, pending | Wait for callback; status-check after 5 minutes |
+| `0005` | HTTP failure reaching the payment partner; state unknown | Don't retry with a new reference; contact Hubtel to confirm |
+| `2001` | Customer or telco failure (insufficient funds, wrong PIN, USSD timeout, number not on channel, special characters in description) | Mark failed; let the customer retry with a new reference |
+| `4000` | Validation error | Fix the request |
+| `4070` | Fees not set or amount below minimum | Contact Hubtel account manager |
+
+## SMS
+
+`POST https://sms.hubtel.com/v1/messages/send` with `{ "From": "MyBrand", "To": "233241234567", "Content": "Your order 8F2C1A is paid." }`. `From` is the sender ID, max 11 characters. Batch: `POST /v1/messages/batch/simple/send` (`Recipients` array) or `/v1/messages/batch/personalized/send`. Status: `GET /v1/messages/{messageId}` or `/v1/messages/batch/{batchId}`; statuses include `Delivered`, `Sent`, `Pending`, `Blacklisted`, `Undeliverable`, `Rejected`. A `GET` send variant takes `clientid` and `clientsecret` in the query string; avoid it, because URLs end up in logs.
+
+## Status check client (TypeScript)
+
+```ts
+const auth = 'Basic ' + Buffer.from(`${process.env.HUBTEL_API_ID}:${process.env.HUBTEL_API_KEY}`).toString('base64');
+
+export async function hubtelIsPaid(clientReference: string, expectedPesewas: number) {
+  const acct = process.env.HUBTEL_COLLECTION_ACCOUNT!;
+  const url = `https://api-txnstatus.hubtel.com/transactions/${acct}/status?clientReference=${encodeURIComponent(clientReference)}`;
+  const res = await fetch(url, { headers: { Authorization: auth } });
+  if (res.status === 403) throw new Error('Hubtel 403: server IP is not whitelisted');
+  if (!res.ok) throw new Error(`Hubtel status check failed: ${res.status}`);
+  const { data } = await res.json();
+  return data?.status === 'Paid' && Math.round(Number(data.amount) * 100) === expectedPesewas;
+}
+```

package/skills/i18n-localization/SKILL.md

@@ -0,0 +1,114 @@
+---
+name: i18n-localization
+description: Internationalises an application so it can ship in more languages and regions, by moving user-facing text into message catalogs, writing ICU MessageFormat messages with plural and select rules, formatting dates, numbers, currency and lists through locale-aware APIs, making layouts work right-to-left, testing with pseudo-localisation, and keeping translation keys in sync across locales. Use when adding a second language or locale to an app, setting up i18next, react-intl, vue-i18n, gettext, Android or iOS string resources, fixing plurals or currency that read wrong in one language, or adding Arabic or Hebrew support.
+license: MIT
+compatibility: Any Agent Skills host. Examples use JavaScript Intl and ICU MessageFormat; the rules apply to any i18n library or platform.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: writes-files
+  kete-loom/owner: "Kete-org"
+---
+
+# i18n and localisation
+
+Make the app translatable once, correctly, so each new locale is a translation job and not a code change. For library-specific syntax and setup, read `references/libraries.md`.
+
+## 0. Before you start
+
+1. Find what the project already uses: search for `i18next`, `react-intl`/`@formatjs`, `vue-i18n`, `next-intl`, `gettext`/`.po` files, `res/values*/strings.xml`, `Localizable.strings`/`.xcstrings`, Rails `config/locales`, or a hand-rolled `t()` helper. **Use the existing system.** Never add a second one.
+2. If there is none, recommend one that fits the stack (see `references/libraries.md`) and **stop and ask the user** before adding a dependency.
+3. Ask, if not stated: target locales, the source locale, who translates (people, a translation platform, machine translation with review), and whether locale comes from the URL, user profile or `Accept-Language`.
+
+## 1. Externalise strings
+
+- Every user-visible string goes into the catalog: labels, buttons, errors, empty states, emails, push notifications, `alt`, `title`, `aria-label`, `placeholder`, page titles, and validation messages from the server.
+- Not translated: log messages, identifiers, CSS class names, enum values stored in the database, analytics event names.
+- Key names describe meaning and place, not the English text: `checkout.summary.total`, not `total_colon`. Don't reuse one key for two contexts that look the same in English ("Open" as verb and as status).
+- Add a translator description to any key whose meaning isn't obvious from its text, including what each placeholder holds.
+- Server-side errors return a code plus parameters; the client turns the code into a message. Don't send English sentences over an API for display.
+
+## 2. Write whole messages, never concatenations
+
+- Never build a sentence from pieces: `t('hello') + ' ' + name + '!'` and `"You have " + n + " items"` break in languages with different word order. Use one message with named placeholders: `Hello, {name}!`.
+- Don't put formatted values together with `+` either; pass raw values as arguments and let the message format them.
+- Markup inside a sentence (a link, bold text) stays inside the message as a tag the library supports (`<link>terms</link>` in react-intl, `<0>…</0>` in react-i18next `Trans`), so translators can move it.
+- Gender or variant wording uses `select`: `{gender, select, female {She replied} male {He replied} other {They replied}}`.
+
+## 3. Plurals
+
+- Use the library's plural support; never `n === 1 ? 'item' : 'items'`. Languages use up to six CLDR plural categories: `zero`, `one`, `two`, `few`, `many`, `other`. English uses `one` and `other`; Arabic uses all six; Japanese uses only `other`.
+- ICU form: `{count, plural, =0 {No messages} one {# message} other {# messages}}`. `#` is the locale-formatted number. `other` is required.
+- `=0` is an exact-match override, not a category. `one` is not "exactly 1" in every language (for example, in Russian `one` also covers 21, 31...), so never use `one` to mean "singular" in logic.
+- Ordinals ("1st", "2nd") use `selectordinal`, or `Intl.PluralRules(locale, { type: 'ordinal' })`.
+- When a translator adds a category your source lacks (Polish `few`, `many`), the catalog must accept it. Check that your extraction and validation tooling does not strip unknown categories.
+
+## 4. Locale-aware formatting
+
+Use platform formatting with the active locale; never hand-format. In JavaScript:
+
+| Value | API |
+|---|---|
+| Number, percent | `new Intl.NumberFormat(locale).format(n)`, `{ style: 'percent' }` |
+| Currency | `new Intl.NumberFormat(locale, { style: 'currency', currency: 'EUR' })` |
+| Date and time | `new Intl.DateTimeFormat(locale, { dateStyle: 'medium', timeStyle: 'short', timeZone })` |
+| "3 days ago" | `new Intl.RelativeTimeFormat(locale, { numeric: 'auto' })` |
+| "A, B and C" | `new Intl.ListFormat(locale, { type: 'conjunction' })` |
+| Sorting | `new Intl.Collator(locale).compare` (never default `Array.prototype.sort` on display text) |
+| Plural category | `new Intl.PluralRules(locale).select(n)` |
+
+Rules:
+
+- **Currency is data, not locale.** Store amount and ISO 4217 code together; the locale only decides how it's displayed. Never derive the currency from the user's language.
+- Store timestamps in UTC; format in the user's time zone. Date-only values (birthdays) must not be shifted by time zone.
+- Don't parse user-typed numbers with `parseFloat`: `1.234,5` is valid German. Use a locale-aware input or a single agreed format.
+- Hard-coded patterns like `MM/DD/YYYY`, `toFixed(2)` for display, and `'$' + amount` are bugs.
+- Cache formatter instances; constructing `Intl.*` objects in a hot render loop is slow.
+
+## 5. Right-to-left (Arabic, Hebrew, Persian, Urdu)
+
+1. Set `lang` and `dir="rtl"` on `<html>` from the active locale (or `android:supportsRtl="true"` on Android; iOS mirrors automatically with leading/trailing constraints).
+2. Replace physical CSS with logical properties: `margin-inline-start` not `margin-left`, `padding-inline-end`, `inset-inline-start`, `border-inline-start`, `text-align: start`. In Tailwind use `ms-*`, `me-*`, `ps-*`, `pe-*`, `rtl:`/`ltr:` variants, and for insets `start-*`/`end-*` (v3.3 to v4.1) or `inset-s-*`/`inset-e-*` (v4.2+, where `start-*`/`end-*` are deprecated).
+3. Mirror direction-bearing icons (back/forward arrows, chevrons, progress) but not logos, media playback controls, clocks or checkmarks.
+4. User-generated or mixed-direction text: use `dir="auto"` on the element, or `<bdi>` around an interpolated name, so a Latin username doesn't scramble an Arabic sentence.
+5. Numbers, phone numbers and code stay left-to-right inside RTL text.
+6. Check flex `row` order, absolutely positioned elements, transforms (`translateX`), and canvas or SVG drawing, which logical properties don't flip.
+
+## 6. Pseudo-localisation
+
+Run the UI in a pseudo-locale before real translations exist. It exposes hard-coded strings (unchanged English), truncation (translations into German or Finnish often run a third longer than English, and short labels can double), concatenation and encoding bugs.
+
+- Generate an accented, padded locale: `Settings` → `[Šéţţîñĝš one two]`. FormatJS: `formatjs compile --ast --pseudo-locale en-XA` (also `en-XB`, `xx-LS`, `xx-AC`, `xx-HA`); Android: `pseudoLocalesEnabled true` in the build type gives `en-XA` and `ar-XB`.
+- Add a bidi pseudo-locale (or `ar-XB`) to test RTL with readable text.
+- Walk every changed screen at mobile width. Anything still plain English is a missed string.
+
+## 7. Translation workflow and keeping keys in sync
+
+1. The source locale is the only catalog developers edit by hand. Other locales come from translators or the translation platform.
+2. Extract keys from code with the library's extractor (`formatjs extract`, `i18next-cli` (the replacement for the deprecated `i18next-parser`), `xgettext`, Xcode string catalog sync) instead of maintaining them by hand.
+3. Add a check to CI that fails when:
+   - a key used in code is missing from the source catalog;
+   - a key exists in a locale catalog but not in the source (orphaned);
+   - a translation's placeholders differ from the source (`{name}` renamed or dropped);
+   - a message fails ICU syntax parsing.
+4. Missing translations fall back through a defined chain (`pt-BR` → `pt` → source locale) at runtime and are reported, never shown as raw keys.
+5. When English text changes meaning, change the key (or mark translations as needing review), so stale translations don't ship silently.
+6. Never machine-translate straight into production catalogs for legal, medical, financial or safety text; a fluent human reviewer must approve those.
+
+## Never
+
+- Never concatenate translated fragments or format values with string operations.
+- Never detect language from IP address or country alone; let users choose and remember their choice.
+- Never use flags to represent languages.
+- Never put translatable text in images, or truncate text with fixed-width containers.
+- Never lowercase or uppercase translated strings in code without the locale (`toLocaleUpperCase(locale)`: Turkish dotted i).
+
+## Report back
+
+End with:
+
+- **Strings externalised:** count and files touched.
+- **Formatting changed:** which values moved to locale-aware APIs.
+- **RTL:** done, partial or not in scope, and what was checked.
+- **Sync check:** the command added or run and its result.
+- **Open items:** strings not externalised, locales without translations, anything needing a translator or reviewer.

package/skills/i18n-localization/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "We need to launch our React dashboard in French and German, set up translations for it",
+    "Our plural messages say '1 items' and break in Polish, fix the pluralisation with ICU",
+    "Add Arabic support to the web app including right-to-left layout",
+    "Prices show as $ even for EUR customers, make currency and date formatting locale-aware",
+    "Set up pseudo-localisation and a CI check that our translation JSON files stay in sync with the source keys"
+  ],
+  "should_not_trigger": [
+    "Review this pull request for hard-coded strings and broken plurals before it merges",
+    "Audit the signup form for WCAG keyboard and screen reader problems",
+    "Write the README for our CLI tool in plain English",
+    "Rewrite our marketing copy so it sounds consistent with our brand voice",
+    "Convert all timestamps in the orders table from local time to UTC in a database migration"
+  ]
+}