@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/hl7v2-integration/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: hl7v2-integration
+description: Parses, generates and routes pipe-delimited HL7 version 2.x messages such as ADT admit/discharge/transfer events, ORM and OML orders and ORU results, handling MSH encoding characters and escape sequences, repeating fields and components, MSH-10 control IDs, original and enhanced ACK/NACK modes, MLLP framing over TCP, interface engines like Mirth Connect (NextGen Connect), and mapping v2 segments to FHIR resources. Use when receiving or sending HL7 v2 feeds from a hospital, lab or EHR, debugging a rejected message or missing ACK, writing an MLLP listener, or converting PID, PV1, OBR and OBX data into FHIR.
+license: MIT
+compatibility: Any Agent Skills host. Live feeds need network access to the interface engine or MLLP endpoint. Rules apply to any language or HL7 library (for example HAPI HL7v2, python-hl7, hl7apy).
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# HL7 v2 integration
+
+Build an HL7 v2 interface that never loses a message, never files a result against the wrong patient, and tells the sender exactly why it rejected something. For the FHIR REST API use `fhir-integration`; for HIPAA safeguards around the feed use `hipaa-compliance`.
+
+This is engineering guidance, not clinical advice. Every live interface is validated with the sending site before go-live.
+
+## Ground rules
+
+1. **The interface specification wins.** Every site customises v2 (Z-segments, optional fields made required, local code tables). Get the sender's or receiver's interface spec and sample messages before writing a parser. If there is none, stop and ask for it.
+2. **Read encoding characters from MSH, never hard-code them.** MSH-1 is the field separator (normally `|`), MSH-2 holds component `^`, repetition `~`, escape `\`, subcomponent `&` (and truncation `#` from v2.7). Segments end with carriage return `\r` (0x0D), not `\n`.
+3. **Unescape and escape.** `\F\` `\S\` `\R\` `\E\` `\T\` stand for the separators inside data; `\X..\` is hex and `\.br\` a line break in formatted text. Escape on output; a name with `^` or `&` must not split fields.
+4. **Fields repeat.** PID-3 (identifiers), PID-5 (names), PID-13 (phones) and OBX-5 can repeat with `~`. Pick the identifier by its assigning authority and type code (PID-3.4, PID-3.5 such as `MR`), never "the first one".
+5. **Persist before you ACK.** Write the raw message to durable storage (queue or database) in the same step that decides the ACK. Send `AA`/`CA` only once it is stored. If storage fails, send `AR` with ERR-3 code `207` (application internal error) or send no ACK so the sender retries; `AE` means the content is wrong and senders usually don't resend it unchanged.
+6. **MSH-10 is the idempotency key.** Senders resend when an ACK is lost. Deduplicate on sending facility (MSH-4) plus MSH-10 and return the same ACK again for a duplicate.
+7. **Preserve order per patient.** ADT events (A01 admit, A02 transfer, A03 discharge, A08 update, A40 merge) must be processed in order for a patient. Process one connection serially, or partition by patient identifier; never parallelise blindly.
+8. **Merges and corrections are first-class.** Handle A40 (merge patient), A11/A13 (cancel admit/discharge), A08 updates, and ORU results with OBX-11 result status `C` (corrected) or `D` (delete). Never treat them as new records.
+9. **Never log full messages.** Messages contain PHI. Log message type, MSH-10, MSH-4, processing outcome and error location (segment, field) only. Keep raw messages in access-controlled storage with a retention policy.
+
+## Steps
+
+1. **Collect the spec and samples:** versions (MSH-12, for example `2.3`, `2.5.1`), message types and trigger events (MSH-9, for example `ADT^A01^ADT_A01`, `ORU^R01^ORU_R01`), required segments, Z-segments, code tables, ACK mode (MSH-15/MSH-16), and character set (MSH-18).
+2. **Transport.** For MLLP use the framing in `references/messages-and-ack.md`. Run MLLP over a VPN or TLS tunnel; MLLP itself has no encryption or authentication. Restrict the listener port to the sender's IPs.
+3. **Parse** with a maintained library, configured to read separators from MSH. Validate: required segments present, MSH-9 is a type you accept, MSH-11 processing ID (`P` production, `T` test, `D` debug) matches the environment. Reject `T` messages in production and `P` messages in test.
+4. **Acknowledge** with the ACK format in `references/messages-and-ack.md`. On a rejected message set MSA-1 to `AE` (a problem in the message content, such as a missing required field; the sender must fix it before resending) or `AR` (rejected for reasons not about the content: unsupported message type, version or processing ID, or a receiver failure), and fill ERR with the segment and field location and a code.
+5. **Map** fields to your model or to FHIR using the table in `references/messages-and-ack.md` and the HL7 Version 2 to FHIR IG (hl7.org/fhir/uv/v2mappings). Keep the original identifiers and the raw message ID on every mapped record for traceability.
+6. **Produce** outbound messages with a fresh MSH-10 per message, MSH-7 timestamp with timezone, correct MSH-3/4/5/6 sending and receiving application and facility, and wait for the ACK before sending the next on that connection. Retry with the same MSH-10 on timeout.
+7. **Test** with de-identified sample messages from the site, plus edge cases: escaped separators, repeating identifiers, missing optional segments, Z-segments, a duplicate MSH-10, a merge (A40), a corrected result, an empty OBX-5, a message with `\n` line endings.
+
+## Interface engines
+
+If the organisation runs an engine (Mirth Connect by NextGen Healthcare, commercially licensed from 4.6; Rhapsody; Cloverleaf; InterSystems HealthShare; or a cloud service such as Google Cloud Healthcare API HL7v2 stores with its MLLP adapter), put routing, filtering and transformation there rather than in each application, and keep transformations in source control. Your application then gets one well-defined feed.
+
+## Stop and ask the user
+
+- Before connecting to a production feed, or replaying messages into production.
+- When identifiers in PID-3 don't match the agreed assigning authority, or a message would update a patient that can't be matched uniquely.
+- When the sample messages contradict the interface spec.
+- Before discarding or "fixing up" messages that fail validation.
+
+## Never
+
+- Never split on `|` and `^` with hard-coded indices without handling escapes and repetitions.
+- Never ACK before the message is durably stored.
+- Never drop OBX segments you don't understand from a result; store them and flag them.
+- Never reuse an MSH-10 for a different message.
+- Never mix test and production feeds on one listener.
+
+## Report format
+
+When asked to review or design an interface, finish with:
+
+```
+Feed: <sender → receiver, message types and versions, transport>
+ACK mode: <original | enhanced>, persisted before ACK: <yes/no>
+Findings: <ranked list, file:line, rule broken, fix>
+Open questions for the interface analyst: <list>
+```

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Write an MLLP listener in Node that receives ADT messages and sends back an ACK",
+    "The lab says our ORU^R01 parser files results under the wrong patient when PID-3 has two identifiers",
+    "Our interface engine keeps resending messages because it never gets an AA back, help me debug the ACK",
+    "Map OBX segments from incoming HL7 v2 lab results into FHIR Observation resources",
+    "Generate outbound ORM order messages with proper MSH-10 control IDs and escaping of the ^ character in names"
+  ],
+  "should_not_trigger": [
+    "Query a FHIR server for all Encounters in the last week using _include for the patient",
+    "Design drug-interaction alerts so clinicians don't get alert fatigue",
+    "Set up a Kafka consumer with exactly-once processing for our order events",
+    "Check our hospital feed handler for patient data written to application logs",
+    "Write the HIPAA audit logging requirements for our EHR export feature"
+  ]
+}

package/skills/hl7v2-integration/references/messages-and-ack.md

@@ -0,0 +1,78 @@
+# HL7 v2 messages, ACKs, MLLP and FHIR mapping
+
+Sources: HL7 v2.5.1 and later chapters 2 (control) and 3 (ADT), the MLLP transport spec (HL7 v2 Appendix C / Transport Specification MLLP Release 2), and the HL7 Version 2 to FHIR IG 1.0.0. Field positions below are the common ones; the site's interface spec overrides them.
+
+## Example ADT^A01
+
+```
+MSH|^~\&|ADT1|GOOD HEALTH HOSPITAL|RCV|RCVFAC|20240612083000+0100||ADT^A01^ADT_A01|MSG00001|P|2.5.1
+EVN|A01|20240612083000+0100
+PID|1||12345^^^GHH^MR~987654321^^^NHS^NH||DOE^JANE^A||19800101|F|||1 MAIN ST^^LEEDS^^LS1 1AA^GBR
+PV1|1|I|WARD1^ROOM2^BED3||||1234^SMITH^JOHN|||MED
+```
+
+Segments are separated by `\r`. The line breaks above are for reading only.
+
+## Key fields
+
+| Field | Meaning |
+|---|---|
+| MSH-3 / MSH-4 | sending application / facility |
+| MSH-5 / MSH-6 | receiving application / facility |
+| MSH-7 | message date/time |
+| MSH-9 | message type ^ trigger event ^ structure |
+| MSH-10 | message control ID (unique per message from a sender) |
+| MSH-11 | processing ID: P, T, D |
+| MSH-12 | version ID |
+| MSH-15 / MSH-16 | accept / application acknowledgment type (AL, NE, ER, SU); blank means original mode |
+| PID-3 | patient identifier list (ID ^^^ assigning authority ^ type code) |
+| PID-5 / PID-7 / PID-8 | name / birth date / administrative sex |
+| PV1-2 / PV1-3 | patient class / assigned location |
+| ORC-1 / ORC-2 / ORC-3 | order control / placer order number / filler order number |
+| OBR-4 | universal service identifier (ordered test) |
+| OBX-2 / OBX-3 / OBX-5 / OBX-6 | value type / observation identifier / value / units |
+| OBX-8 / OBX-11 | abnormal flags / result status (F final, P preliminary, C corrected, D delete, X cannot obtain) |
+
+## ACK
+
+Original mode: the receiving application replies once.
+
+```
+MSH|^~\&|RCV|RCVFAC|ADT1|GOOD HEALTH HOSPITAL|20240612083001+0100||ACK^A01^ACK|ACK00001|P|2.5.1
+MSA|AA|MSG00001
+```
+
+- MSA-1: `AA` accepted, `AE` error, `AR` rejected.
+- MSA-2: the MSH-10 of the message being acknowledged.
+- On `AE`/`AR`, add `ERR` with location (ERR-2, for example `PID^1^3`), HL7 error code (ERR-3, from table 0357, for example `101` required field missing, `200` unsupported message type, `207` application internal error) and severity (ERR-4: `E`, `W`, `I`).
+- Swap sending and receiving application/facility relative to the inbound MSH.
+
+Enhanced mode (MSH-15/16 set): a commit ACK (`CA`, `CE`, `CR`) confirms safe receipt, and an optional application ACK (`AA`, `AE`, `AR`) follows later as a separate message.
+
+## MLLP framing
+
+```
+<VT> message <FS><CR>
+VT = 0x0B   FS = 0x1C   CR = 0x0D
+```
+
+- Read bytes until `0x1C 0x0D`; strip the leading `0x0B`. A TCP read can contain part of a message or several messages: buffer and split on the trailer.
+- One message at a time per connection: send, wait for the ACK, then the next.
+- Set an ACK timeout (often 30 to 60 seconds, agree it with the partner) and resend with the same MSH-10 on timeout.
+- Keep connections open; reconnect with backoff.
+- MLLP has no security. Use a VPN, TLS wrapper or engine-to-engine secure channel.
+
+## Mapping to FHIR (summary of the v2-to-FHIR IG)
+
+| v2 | FHIR R4 |
+|---|---|
+| PID | Patient (PID-3 → identifier, PID-5 → name, PID-7 → birthDate, PID-8 → gender via a concept map) |
+| PV1 | Encounter (PV1-2 → class, PV1-3 → location, PV1-19 visit number → identifier) |
+| ORC + OBR | ServiceRequest (placer/filler numbers → identifier) and DiagnosticReport for results |
+| OBX | Observation (OBX-3 → code, OBX-5 by OBX-2 type → value[x], OBX-6 → valueQuantity.unit, OBX-11 → status) |
+| AL1 | AllergyIntolerance |
+| DG1 | Condition |
+| NK1 | RelatedPerson or Patient.contact |
+| MSH, EVN | Provenance / MessageHeader (keep MSH-10 for traceability) |
+
+Code tables map through ConceptMaps; local codes need a site-specific map. Map OBX-11 `C` to Observation `status = corrected` and update the existing Observation rather than creating a new one; `D` maps to `entered-in-error`.

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;
+}
+```