@ketecode/loom 0.0.0-stage → 0.2.0

package/skills/flask-patterns/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: flask-patterns
+description: Flask application structure with a create_app factory, blueprints per feature, config loaded from objects and environment variables, extensions such as Flask-SQLAlchemy and Flask-Migrate initialised with init_app, application and request context pitfalls with current_app and g, security hardening, and pytest tests through the test client. Use when starting or restructuring a Flask app, adding a blueprint or extension, debugging "working outside of application context" errors, or testing Flask views.
+license: MIT
+compatibility: Any Agent Skills host. Needs Python and the project's Flask app. Guidance targets Flask 2.x and 3.x with Flask-SQLAlchemy 3.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "python"
+  kete-loom/owner: "Kete-org"
+---
+
+# Flask patterns
+
+Keep a Flask app importable without side effects, configurable per environment, and testable with a fresh app per test.
+
+## 0. Before you change anything
+
+1. Find the app: a `create_app()` factory or a module-level `app = Flask(__name__)`. Check Flask and extension versions in `pyproject.toml` or `requirements*.txt`.
+2. Find how it runs (`flask --app <module> run`, gunicorn target, `FLASK_APP`) and how tests run. Run the tests once; if they already fail, **stop and tell the user**.
+3. If the app is a single module-level `app`, ask the user before converting it to a factory; it touches every import of `app`.
+
+## 1. Application factory
+
+```python
+# myapp/__init__.py
+from flask import Flask
+from .extensions import db, migrate
+
+def create_app(config_object="myapp.config.Config", test_config=None):
+    app = Flask(__name__, instance_relative_config=True)
+    app.config.from_object(config_object)
+    app.config.from_prefixed_env()          # FLASK_SECRET_KEY, FLASK_SQLALCHEMY_DATABASE_URI, ...
+    if test_config:
+        app.config.update(test_config)
+
+    db.init_app(app)
+    migrate.init_app(app, db)
+
+    from .orders import bp as orders_bp
+    app.register_blueprint(orders_bp, url_prefix="/orders")
+    return app
+```
+
+- Extensions are created unbound in `extensions.py` (`db = SQLAlchemy()`) and bound with `init_app(app)` in the factory. This avoids circular imports and lets tests build many apps.
+- Import blueprints inside the factory (or in a module that doesn't import the app) to avoid import cycles.
+- No work at import time: no database connections, no reading secrets into module globals, no `app.run()` outside `if __name__ == "__main__":`.
+
+## 2. Blueprints
+
+- One blueprint per feature (`auth`, `orders`, `admin`), each in its own package with `routes.py`, templates in a per-blueprint subfolder of the templates folder.
+- Use `url_for("orders.detail", order_id=o.id)` (blueprint-qualified endpoint names), never hard-coded paths.
+- Protect a whole blueprint with `@bp.before_request` that checks login or role, then add per-view checks for object ownership.
+- Register error handlers per blueprint with `@bp.errorhandler` or app-wide with `@app.errorhandler`; return JSON for API blueprints and HTML for page blueprints, consistently.
+
+## 3. Config
+
+- Base `Config` class with safe defaults, subclasses `DevConfig`, `TestConfig`, `ProdConfig` if the project uses them; or one class plus environment variables.
+- `SECRET_KEY` and database URLs come from the environment or the `instance/` folder (which is not committed). Fail at startup in production if `SECRET_KEY` is missing.
+- Read config at request time through `current_app.config["KEY"]`, not by importing a module constant, so tests can override it.
+- `DEBUG`/`app.debug` must be off in production; the Werkzeug debugger allows arbitrary code execution.
+
+## 4. Flask-SQLAlchemy and Flask-Migrate
+
+- Use the session the extension scopes to the app context: `db.session`. It is removed at the end of each request; don't create your own `Session()` per request.
+- SQLAlchemy 2 style queries: `db.session.execute(db.select(Order).filter_by(owner_id=uid)).scalars()`, `db.get_or_404(Order, id)`, `db.paginate(...)`. Follow the existing style if the project still uses `Model.query`.
+- Avoid N+1 queries with `selectinload`/`joinedload` in `options(...)` when a template walks a relationship.
+- Commit once per unit of work; on exception call `db.session.rollback()` before re-raising or returning an error.
+- Migrations: `flask db migrate -m "add order status"`, read the generated script (autogenerate misses renames and some type changes), then `flask db upgrade`. Run `flask db downgrade` and `upgrade` again locally to prove reversibility.
+- **Stop and ask the user** before a migration that drops columns or tables or rewrites a large table. Never run `flask db upgrade` against a shared or production database yourself.
+
+## 5. Contexts: current_app, g, request, session
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `RuntimeError: Working outside of application context` | Using `current_app`, `db.session` or `g` in a script, CLI, thread or test with no app pushed | `with app.app_context():` around the work, or use a `@app.cli.command()` (which pushes one) |
+| `Working outside of request context` | Touching `request` or `session` outside a request | Pass values in as arguments; in tests use `app.test_request_context()` |
+| Data shared between users | Storing per-request state in a module global | Store it on `g` (lives for one app context) |
+| Background thread loses context | Contexts are per thread | Pass plain data and push `app.app_context()` in the thread; better, use a task queue |
+
+- Never pass `request`, `g` or `current_app` proxies to a thread or task. Use `current_app._get_current_object()` only when you must hand the real app object over.
+
+## 6. Security
+
+- Forms: Flask-WTF's `CSRFProtect` (create `csrf = CSRFProtect()` in `extensions.py`, call `csrf.init_app(app)` in the factory) for any cookie-authenticated POST. Exempt only token-authenticated API endpoints, and say why.
+- Cookies in production: `SESSION_COOKIE_SECURE=True`, `SESSION_COOKIE_HTTPONLY=True` (default), `SESSION_COOKIE_SAMESITE="Lax"`. The default session is signed, not encrypted: never put secrets in it.
+- Templates autoescape `.html` files; never use `Markup(...)` or `|safe` on user input, and never `render_template_string` with user-controlled template text.
+- Uploads: `secure_filename`, `MAX_CONTENT_LENGTH`, an allow-list of extensions, and save outside the static folder.
+- Redirects: validate `next` parameters against your own host before redirecting.
+- SQL: use the ORM or `text()` with bound parameters, never f-strings.
+- Behind a proxy, wrap with `werkzeug.middleware.proxy_fix.ProxyFix` set to the real number of proxies, not more.
+
+## 7. Testing
+
+```python
+# tests/conftest.py
+import pytest
+from myapp import create_app
+from myapp.extensions import db
+
+@pytest.fixture
+def app():
+    app = create_app(test_config={"TESTING": True,
+                                  "SQLALCHEMY_DATABASE_URI": "sqlite:///:memory:",
+                                  "WTF_CSRF_ENABLED": False})
+    with app.app_context():
+        db.create_all()
+    yield app                   # outside the context, so tests catch missing-context bugs
+    with app.app_context():
+        db.drop_all()
+
+@pytest.fixture
+def client(app):
+    return app.test_client()
+```
+
+- A fresh app per test via the factory; never import a shared global app into tests.
+- Use `client.get/post(...)`, `follow_redirects=True` where the flow redirects, and `with client.session_transaction() as s:` to set session state.
+- Test CLI commands with `app.test_cli_runner()`.
+- If production uses PostgreSQL, run at least the query-heavy tests against PostgreSQL; SQLite hides type and constraint differences.
+- For each view: happy path, invalid form, unauthenticated, another user's object.
+
+## Rules
+
+- Never leave `debug=True` or a hard-coded `SECRET_KEY` in committed code.
+- Never disable CSRF outside test config.
+- Never add global mutable state for per-request data.
+
+## Report back
+
+End with: files changed, blueprints and routes added, extensions or config keys added, migrations generated (with what you checked in the script), the test command and result, and anything left untested.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Convert my single-file Flask app into an application factory with blueprints",
+    "I get RuntimeError: Working outside of application context in my Flask CLI script",
+    "Add Flask-SQLAlchemy and Flask-Migrate to this Flask project",
+    "Write pytest tests for my Flask login view using the test client",
+    "How do I load Flask config from environment variables per environment?"
+  ],
+  "should_not_trigger": [
+    "Add a Django admin page for the orders model",
+    "Create FastAPI dependencies for the database session",
+    "Review my Django change for unsafe raw SQL",
+    "Write a Dockerfile to deploy my Python web app",
+    "Fix the pip dependency conflict that stops my Python package from installing"
+  ]
+}

package/skills/flutter-patterns/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: flutter-patterns
+description: Flutter app architecture from the widget tree up, covering small const widgets and composition over inheritance, choosing between Riverpod, Bloc and Provider for state, declarative routing with go_router or Navigator, FutureBuilder and StreamBuilder async UI with loading and error states, rebuild and jank performance, and Dart-to-native platform channels or Pigeon. Use when building or restructuring Flutter screens and widgets, picking or applying a state management approach, wiring navigation and deep links, chasing dropped frames, or calling iOS or Android code from a Flutter app.
+license: MIT
+compatibility: Any Agent Skills host. Needs the Flutter SDK (flutter analyze, flutter test); device runs need Xcode for iOS or the Android SDK.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "flutter"
+  kete-loom/owner: "Kete-org"
+---
+
+# Flutter patterns
+
+Build Flutter screens from small widgets, keep state where one decision rule puts it, and keep frames under budget. Plain Dart language features, isolates and package layout belong to `dart-patterns`; widget and golden tests belong to `dart-testing`. To review someone else's Flutter change, use the `flutter-reviewer` agent.
+
+## 0. Before you write
+
+1. Read `pubspec.yaml`: Flutter/Dart SDK constraints, and which of `flutter_riverpod`, `flutter_bloc`, `provider`, `go_router`, `auto_route` are already used.
+2. Read `analysis_options.yaml`. Keep `flutter_lints` (or the project's stricter set) on; `use_build_context_synchronously` catches real async bugs. `prefer_const_constructors` is no longer in `flutter_lints` (removed in 5.0), so enable it explicitly if the team wants const enforced.
+3. Follow the existing folder layout (feature-first `lib/features/<name>/` or layer-first). Don't reorganise unasked.
+4. Run `flutter analyze` and `flutter test` once and record the result.
+
+## 1. Widget composition
+
+- Split a widget when a part rebuilds for different reasons, is reused, or the `build` method passes ~80 lines. Extract a **widget class**, not a helper method returning `Widget`: classes get their own element, can be `const` and rebuild independently.
+- Mark constructors and instances `const` wherever possible; const subtrees are skipped on rebuild.
+- `StatelessWidget` by default. Use `StatefulWidget` only for state owned by this widget: controllers, animation, focus, local form input.
+- Every `TextEditingController`, `AnimationController`, `ScrollController`, `FocusNode`, `StreamSubscription` and `Timer` created in a `State` is disposed or cancelled in `dispose()`. Create them in `initState`, never in `build`.
+- Pass data down through constructors; pass events up through callbacks. Don't reach into a child's state with a `GlobalKey` unless a framework API (forms, navigators) needs it.
+- Keys: use `ValueKey(item.id)` on list items that can reorder, insert or delete, so state follows the item.
+
+## 2. State management
+
+Use what the project already uses. For a new project or a new kind of state, apply this rule:
+
+| State | Put it in |
+|---|---|
+| Ephemeral UI (tab index, expanded, text field) | `State` of the widget |
+| Shared app or server state, new or small-to-mid project | Riverpod (`Notifier` / `AsyncNotifier`, optionally with `riverpod_generator`) |
+| Event-driven flows where the team wants explicit events and transitions | Bloc / Cubit (`flutter_bloc`) |
+| Existing Provider app | Keep `provider` with `ChangeNotifier`; don't mix in a second library |
+
+Rules that apply to all three:
+
+- Keep business logic out of widgets: a notifier, cubit or repository owns it, and is unit-testable without a widget.
+- State objects are immutable values (`copyWith`, or `freezed` if already used); never mutate a list in place and re-emit the same instance.
+- Watch the narrowest thing: `ref.watch(provider.select((s) => s.count))`, `context.select`, or `BlocSelector`, so unrelated changes don't rebuild the screen.
+- Use `ref.read` / `context.read` in callbacks, `watch` only in `build`.
+- Model async state explicitly: loading, data, error (`AsyncValue` in Riverpod, sealed state classes in Bloc).
+
+## 3. Navigation
+
+- Apps with deep links, web, or nested tabs: `go_router` with a single route table, path parameters for IDs, and `redirect` for auth guards.
+- Small apps with no deep links: `Navigator.push` with `MaterialPageRoute` is fine.
+- Pass IDs in routes, not whole objects, so deep links and restoration work.
+- Return results with `Navigator.pop(context, value)` / `context.pop(value)` and await the push.
+- Handle the Android back button with `PopScope` where leaving would lose data.
+
+## 4. Async UI
+
+- Never start a future inside `build`. `FutureBuilder(future: fetch())` refetches on every rebuild. Create the future in `initState` (or a provider) and pass the stored future.
+- Always render all three states: loading, error with a retry, and data (including empty).
+- After every `await` in a `State` method, check `if (!mounted) return;` before using `context` or calling `setState`. For a `BuildContext` passed in as a parameter, check `context.mounted`.
+- Capture `Navigator.of(context)` or `ScaffoldMessenger.of(context)` before the `await` when you need them after it.
+- Cancel stream subscriptions in `dispose()`; prefer `StreamBuilder` or a provider so the framework does it.
+
+## 5. Performance
+
+Measure in **profile mode** (`flutter run --profile`) on a real device, with the DevTools performance view and "track widget rebuilds". Debug mode is not representative.
+
+- Long or unbounded lists: `ListView.builder` / `SliverList` with `itemExtent` or `prototypeItem` when rows are fixed height. Never `Column` + `map` inside a `SingleChildScrollView` for long data.
+- Avoid `shrinkWrap: true` on long lists inside other scrollables; use slivers in a `CustomScrollView`.
+- Keep `build` cheap: no parsing, sorting, I/O or `DateFormat` construction in it. Move heavy CPU work to `compute()` / `Isolate.run`.
+- `Opacity`, `ClipRRect`, `ShaderMask` and `BackdropFilter` over large areas are expensive; prefer `FadeTransition`, pre-clipped images or a colour with alpha.
+- Wrap independently animating regions in `RepaintBoundary` only when the DevTools repaint view shows it helps.
+- Size images: `cacheWidth` / `cacheHeight` on `Image` for thumbnails.
+
+## 6. Platform channels
+
+1. Search pub.dev for a maintained plugin (federated, with iOS and Android support) first.
+2. For your own native calls, prefer **Pigeon** to generate type-safe Dart, Kotlin and Swift code over hand-written `MethodChannel` string maps.
+3. With `MethodChannel`: one channel name per feature (`com.example.app/battery`), handle `PlatformException` and `MissingPluginException` in Dart, and return errors from native with an error code, never a crash.
+4. Platform handlers run on the platform's main thread; move long native work to a background thread and reply when done.
+5. Native code changes need a full rebuild, not a hot reload. Test on both platforms.
+
+**Stop and ask the user** before adding a new state management or routing package, raising the SDK constraint, or changing native project settings (signing, min SDK, deployment target).
+
+## Never
+
+- Never call `setState` or use `context` after an `await` without a mounted check.
+- Never create controllers, futures or streams inside `build`.
+- Never use a helper method where a const widget class would do.
+- Never ignore an analyzer warning by adding `// ignore:` without saying why.
+
+## Report back
+
+End with: widgets and files changed, state approach used and why, `flutter analyze` and `flutter test` results, and the platforms and mode (debug, profile, release) you ran it in.

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Should this Flutter app use Riverpod or Bloc for the cart and auth state?",
+    "Set up go_router with a login redirect and a product/:id route",
+    "My FutureBuilder keeps refetching every time the parent rebuilds, how do I structure this screen?",
+    "Call the Android battery API from my Flutter app using Pigeon",
+    "Break this 400-line Flutter build method into smaller widgets"
+  ],
+  "should_not_trigger": [
+    "Review this Flutter pull request for setState after await and leaked controllers",
+    "Convert these Dart enums and nullable fields into a sealed class hierarchy",
+    "Write widget tests and golden tests for the checkout screen",
+    "My React Native FlashList is janky on older Android phones",
+    "Build a Jetpack Compose list screen backed by a ViewModel"
+  ]
+}

package/skills/flutterwave-integration/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: flutterwave-integration
+description: Builds and reviews Flutterwave v3 payment integrations across African markets, covering Flutterwave Standard hosted checkout, direct charges for mobile money (Ghana, Kenya M-Pesa, Uganda, Francophone) and cards, server-side verification by transaction id, verif-hash webhook checks and fulfilment that runs once per tx_ref. Use when adding Flutterwave payments to an app, handling a Flutterwave webhook or redirect, charging a mobile money wallet through Flutterwave, or debugging why a Flutterwave order was marked paid wrongly or twice.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to api.flutterwave.com. 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"
+---
+
+# Flutterwave integration
+
+Build a Flutterwave flow where the browser can't fake a payment, every `tx_ref` gives value at most once, and pending mobile money charges still settle. This skill targets the v3 API (`https://api.flutterwave.com/v3`). If the account uses a newer API version, stop and confirm the endpoints and webhook signing scheme in the dashboard and docs before writing code.
+
+## Ground rules
+
+1. **The secret key stays on the server.** `FLW_SECRET_KEY` (`FLWSECK-...`) and the encryption key are read from the environment. Only the public key (`FLWPUBK-...`) may reach a browser or app.
+2. **The server sets the price.** Compute `amount` and `currency` from your own order record. Never accept them from the client.
+3. **One `tx_ref` per attempt, stored before you call Flutterwave**, with a unique constraint. Flutterwave requires `tx_ref` to be unique per transaction. A customer retry gets a new `tx_ref` on the same order.
+4. **Only a verify call gives value.** The redirect query string and the webhook body are hints. Call `GET /v3/transactions/{id}/verify` and require: `status === "successful"`, `tx_ref` equals yours, `currency` equals yours, and `amount >= expected` (if higher, give value and refund the difference, as Flutterwave's docs advise).
+5. **Fulfilment is idempotent.** Mark paid with a guarded update (`UPDATE payments SET status='paid' WHERE tx_ref = $1 AND status = 'pending'`) and fulfil only if a row changed. Webhooks retry, users refresh, and both paths may run at once.
+6. **Amounts are decimals in major units** in v3 (GHS 25.50 is `25.5`). Store integer minor units in your database and convert at the API boundary; never do float arithmetic on money.
+7. **Test keys first** (`FLWSECK_TEST-...`) until success, failure, cancel and duplicate-webhook paths all work.
+
+## Choose the flow
+
+| Need | Use |
+|---|---|
+| Fastest safe integration, cards + mobile money + bank, no PCI scope | Flutterwave Standard: `POST /v3/payments` returns `data.link`, redirect there |
+| Your own UI for mobile money | Direct charge: `POST /v3/charges?type=<method>` (see `references/api.md`) |
+| Your own card form | Direct card charge needs payload encryption with the account encryption key and puts you in PCI DSS scope. Stop and ask the user before building it; prefer Standard or the inline modal |
+
+## Flow (Standard)
+
+```
+client ──(order id)──▶ server: create payment row (tx_ref, expected amount/currency, pending)
+server ──POST /v3/payments──▶ Flutterwave: data.link
+client ──redirect──▶ hosted page; customer pays
+Flutterwave ──redirect_url?status=..&tx_ref=..&transaction_id=..──▶ server: verify by id, show result
+Flutterwave ──webhook charge.completed (verif-hash header)──▶ server: check hash, 200, queue verify + fulfil once
+```
+
+## Implementation steps
+
+1. **Create the payment** with `POST /v3/payments`, `Authorization: Bearer <secret key>`, body `tx_ref`, `amount`, `currency`, `redirect_url`, `customer.email` (required), optional `customer.name`, `customer.phonenumber`, `payment_options`, `meta` (put your order id here). Shapes in `references/api.md`.
+2. **Redirect handler**: read `transaction_id` from the query, call verify by id, apply ground rule 4, then show the stored status. A `status=cancelled` or `failed` redirect has nothing to verify; show the failure and offer a retry with a new `tx_ref`.
+3. **Webhook endpoint**: follow `references/webhooks.md`. Compare the `verif-hash` header to your stored secret hash in constant time, return `200` fast, then verify by `data.id` before fulfilling.
+4. **Mobile money direct charges**: follow the per-country notes in `references/api.md`. A `"success"` response with "Charge initiated" means the prompt was sent, not that money moved. Ghana returns `meta.authorization.mode: "redirect"`; send the customer to `meta.authorization.redirect`.
+5. **Reconcile pending payments**: a background job verifies payments still `pending` after a few minutes (verify by id if you have it; otherwise look up by `tx_ref` using the endpoint the current docs give) and times out stale ones.
+6. **Persist** per payment: `tx_ref`, order id, expected amount (minor units) and currency, Flutterwave transaction `id`, `flw_ref`, status, payment type, failure reason, timestamps.
+
+## Reviewing an existing integration
+
+Check every ground rule, then look for:
+
+- Fulfilment in the redirect handler based on `status=successful` in the query string, without a verify call.
+- Verify result trusted without comparing `amount`, `currency` and `tx_ref` to the stored order.
+- Webhook with no `verif-hash` check, or a check with `==` against a hard-coded value in source.
+- Webhook doing the verify and fulfilment inline before responding, so slow calls cause retries.
+- `tx_ref` reused across attempts, or generated on the client.
+- Amounts multiplied by 100 (Paystack habit) or computed with floats.
+- Secret key in a `NEXT_PUBLIC_`/`VITE_` variable or committed to the repo.
+- No handling for `failed`, `cancelled` or a charge that stays `pending`.
+
+## Stop and ask the user
+
+- Before building a raw card form (encryption plus PCI scope).
+- Which countries and currencies they sell in; payment methods differ per country.
+- Whether refunds or payouts (transfers) are in scope; they are separate APIs with their own approvals.
+
+## Before you finish
+
+Flutterwave's docs at developer.flutterwave.com are the final word on field names and versions; confirm them when writing new code. Then test in test mode: a successful payment, a declined card, a cancelled checkout, a mobile money charge that times out, the same webhook delivered twice (fulfils once), a webhook with a wrong `verif-hash` (rejected), and a tampered redirect URL (`status=successful` with a failed transaction id must not fulfil).

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

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Add Flutterwave checkout to our Nigerian e-commerce site",
+    "How do I check the verif-hash header on my Flutterwave webhook endpoint?",
+    "Charge a Kenyan customer's M-Pesa wallet through Flutterwave from our backend",
+    "Our Flutterwave redirect marks orders paid even when the transaction failed, can you fix it?",
+    "Accept Ghana mobile money with Flutterwave direct charge instead of the hosted page"
+  ],
+  "should_not_trigger": [
+    "Add Paystack checkout to our Next.js shop so Ghanaian customers can pay",
+    "Send an STK push with the Safaricom Daraja API directly",
+    "Set up Stripe subscriptions with a customer portal",
+    "Review our payment code for float money arithmetic and unverified webhooks",
+    "Integrate Hubtel online checkout for a Ghanaian school fees portal"
+  ]
+}

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

@@ -0,0 +1,73 @@
+# Flutterwave v3 API shapes used by this skill
+
+Base URL: `https://api.flutterwave.com/v3`. Server calls send `Authorization: Bearer <FLW_SECRET_KEY>` and `Content-Type: application/json`. A top-level `"status": "success"` means the API call worked, not that money moved.
+
+Confirm fields against developer.flutterwave.com before shipping; this is a working summary.
+
+## Create a Standard payment link
+
+`POST /payments`
+
+```json
+{
+  "tx_ref": "ord_8f2c1a_a1",
+  "amount": "25.50",
+  "currency": "GHS",
+  "redirect_url": "https://app.example.com/pay/flutterwave/return",
+  "customer": { "email": "customer@example.com", "name": "Ama Mensah", "phonenumber": "233241234567" },
+  "payment_options": "card, mobilemoneyghana",
+  "meta": { "order_id": "8f2c1a" },
+  "customizations": { "title": "Example Store" }
+}
+```
+
+Response: `data.link`. Redirect the customer there. `currency` defaults to NGN when omitted, so always send it. `payment_options` only applies when "Disable preferred payment methods" is off in the dashboard.
+
+Redirect back to `redirect_url`:
+- success: `?status=successful&tx_ref=...&transaction_id=...`
+- cancelled or failed: `?status=cancelled&tx_ref=...` (no transaction to verify)
+
+## Verify a transaction
+
+`GET /transactions/{id}/verify`, where `id` is `transaction_id` from the redirect or `data.id` from the webhook.
+
+| Field in `data` | Expect |
+|---|---|
+| `status` | `"successful"` (others include `failed`, `pending`) |
+| `tx_ref` | the reference you stored |
+| `currency` | the currency you stored |
+| `amount` | `>=` the expected amount; refund any excess |
+| `id`, `flw_ref` | store both |
+
+## Direct charges (mobile money)
+
+`POST /charges?type=<type>` with `tx_ref`, `amount`, `currency`, `email`, `phone_number`, and any country-specific fields.
+
+| Market | `type` | Currency | Notes |
+|---|---|---|---|
+| Ghana | `mobile_money_ghana` | GHS | Also send `network`. The docs list both `MTN`/`VODAFONE`/`TIGO` and `MTN`/`Telecel`/`AIRTEL`; confirm accepted values in the current reference. Response has `meta.authorization.mode: "redirect"`; send the customer to `meta.authorization.redirect` |
+| Kenya | `mpesa` | KES | Customer approves an STK prompt |
+| Uganda | `mobile_money_uganda` | UGX | Confirm in the reference |
+| Francophone West/Central Africa | `mobile_money_franco` | XOF / XAF | Confirm in the reference, including `country` |
+
+Every direct charge ends the same way: wait for the `charge.completed` webhook (or poll), then verify by id before giving value.
+
+## Minimal server client (TypeScript)
+
+```ts
+const FLW = 'https://api.flutterwave.com/v3';
+const headers = { Authorization: `Bearer ${process.env.FLW_SECRET_KEY}`, 'Content-Type': 'application/json' };
+
+export async function verifyFlutterwave(id: string, expected: { txRef: string; currency: string; amountMinor: number }) {
+  const res = await fetch(`${FLW}/transactions/${encodeURIComponent(id)}/verify`, { headers });
+  if (!res.ok) throw new Error(`verify failed: ${res.status}`);
+  const { data } = await res.json();
+  const paidMinor = Math.round(Number(data.amount) * 100); // shortcut: assumes 2-decimal currencies; UGX/XOF/XAF have 0
+  return (
+    data.status === 'successful' &&
+    data.tx_ref === expected.txRef &&
+    data.currency === expected.currency &&
+    paidMinor >= expected.amountMinor
+  );
+}
+```

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

@@ -0,0 +1,49 @@
+# Flutterwave webhooks (v3)
+
+## What Flutterwave sends
+
+- `POST` with JSON such as `{ "event": "charge.completed", "data": { "id": 123, "tx_ref": "...", "status": "successful", "amount": 25.5, "currency": "GHS", ... } }`.
+- Header `verif-hash`: the **secret hash** you set in the dashboard webhook settings. It is a shared secret echoed back, not an HMAC of the body, so it proves the sender knows the secret but not that the body is untouched. That is why every webhook is followed by a verify call.
+- Anything other than `200` (including `3xx`) is a failure. With retries enabled in the dashboard, Flutterwave retries 3 times, 30 minutes apart. Requests time out after 60 seconds. Response body and headers are ignored.
+
+If the dashboard or docs for your account show an HMAC signature header instead of, or as well as, `verif-hash`, verify that signature on the raw body and keep the verify call.
+
+## Handler rules
+
+1. Store the secret hash in the environment (`FLW_WEBHOOK_HASH`), not in code.
+2. Read the `verif-hash` header. Missing or not equal (constant-time compare) → respond `401` and stop.
+3. Respond `200` immediately, then enqueue `data.id` for processing.
+4. The processor calls `GET /v3/transactions/{id}/verify`, applies the checks in `api.md`, and marks the payment paid with a guarded update keyed on `tx_ref`. Unknown `tx_ref` → log and drop; never create an order from a webhook.
+5. Log event type, `id` and `tx_ref`. Never log card data, the secret key or the hash.
+
+## Express (TypeScript)
+
+```ts
+import crypto from 'node:crypto';
+import express from 'express';
+
+const app = express();
+const HASH = process.env.FLW_WEBHOOK_HASH!;
+
+function sameSecret(a: string, b: string) {
+  const x = Buffer.from(a), y = Buffer.from(b);
+  return x.length === y.length && crypto.timingSafeEqual(x, y);
+}
+
+app.post('/webhooks/flutterwave', express.json(), (req, res) => {
+  if (!sameSecret(req.header('verif-hash') ?? '', HASH)) return res.sendStatus(401);
+  res.sendStatus(200); // acknowledge first
+  if (req.body?.event === 'charge.completed' && req.body.data?.id) {
+    queue.add('flw-verify', { id: String(req.body.data.id) }); // verify + fulfil once
+  }
+});
+```
+
+## Guarded fulfilment (SQL)
+
+```sql
+UPDATE payments
+   SET status = 'paid', flw_id = $2, paid_at = now()
+ WHERE tx_ref = $1 AND status = 'pending'
+RETURNING order_id;  -- fulfil only when a row comes back
+```

package/skills/freight-carrier-management/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: freight-carrier-management
+description: Truckload, LTL and intermodal carrier sourcing and governance for shippers and brokers, covering FMCSA operating authority and safety record checks on SAFER and SMS, certificates of insurance and cargo cover, double-brokering and identity fraud red flags, lane rate benchmarking against spot and contract indices, carrier scorecards for on-time, tender acceptance and claims, routing-guide tendering, and contract and rate negotiation. Use when onboarding or vetting a new carrier, running a freight bid or RFP, building a routing guide or carrier scorecard, or deciding which carriers to keep, grow or drop on a lane.
+license: MIT
+compatibility: Any Agent Skills host. FMCSA lookups need network access to safer.fmcsa.dot.gov and ai.fmcsa.dot.gov; rate benchmarks need the user's own index or TMS data. US-centred; other countries have their own carrier registers. Not legal or insurance advice.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: business
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Freight carrier management
+
+Put only legitimate, insured, safe carriers on your freight, pay a defensible rate for each lane, and keep the routing guide honest with data. This skill covers the carrier base before and between loads. A shipment that has already gone wrong (late, damaged, lost) belongs to the `logistics-exception-management` skill; duties and border paperwork to `customs-trade-compliance`.
+
+## 0. Scope the job
+
+Ask the user, then restate:
+
+1. Mode and equipment: truckload (dry van, reefer, flatbed), LTL, intermodal (rail with drayage), or a mix.
+2. Lanes: origin and destination (3-digit ZIP or city), annual or weekly volume, seasonality, hazmat or temperature control.
+3. Who the user is: a shipper buying from carriers and brokers, or a broker buying from carriers. Brokers carry their own FMCSA duties.
+4. The output wanted: onboarding checklist, vetting result for named carriers, bid package, scorecard, or negotiation plan.
+
+If lane volumes or service requirements are missing, **stop and ask**: a bid or benchmark without them is guesswork.
+
+## 1. Vet a carrier before the first load
+
+Run every check and record the date, the source and the result.
+
+1. **Identity.** Get the USDOT number (and MC/docket number if issued) from the carrier, not from an email signature. Look it up on SAFER Company Snapshot (safer.fmcsa.dot.gov). Check legal name, DBA, physical address, phone, power units and drivers match what the carrier told you. FMCSA has been moving to a USDOT-number-only identifier; check the current FMCSA registration guidance before relying on MC numbers in your process.
+2. **Authority.** On FMCSA Licensing and Insurance (L&I), operating authority for the right type (common or contract carrier of property; broker is a separate authority) must be `ACTIVE`, not pending, revoked or inactive. Note the authority grant date: very new authority is higher risk, not disqualifying.
+3. **Safety.** Read the safety rating (Satisfactory, Conditional, Unsatisfactory, or not rated) and the SMS results at ai.fmcsa.dot.gov/SMS: out-of-service rates against the national average, crash history, and any category marked as over the intervention threshold. FMCSA has announced a revised SMS methodology that replaces the BASICs with new safety categories; read whichever version is live and record which one you used. Unsatisfactory or out-of-service: do not use.
+4. **Insurance.** Get the certificate of insurance from the agent, not the carrier, and confirm it with the agent by phone or email to an address you found yourself. Check: auto liability at or above the federal minimum for the commodity ($750,000 for general freight in interstate commerce over 10,001 lb GVWR under 49 CFR 387.9; more for hazmat) and at or above your own contract minimum (many shippers require $1,000,000); cargo cover sized to your highest load value, with exclusions read (reefer breakdown, unattended vehicle, theft, high-value commodities); general liability if they come on site; you named as certificate holder or additional insured as your contract requires. Federal filings on L&I must match. Cargo cover is not federally required for general freight, so your contract must require it.
+5. **Brokers.** When the capacity comes from a broker, check broker authority (separate from carrier authority) is `ACTIVE` on L&I and that its $75,000 financial security (BMC-84 surety bond or BMC-85 trust fund, 49 CFR 387.307) is on file. Ask which carriers they use and whether they vet them to your standard.
+6. **Paperwork.** Signed carrier agreement, W-9, remit-to details, and for brokers buying capacity, the carrier's acceptance of your no-re-brokering clause.
+7. **Fraud red flags** (any one means **stop and escalate** to whoever owns carrier risk):
+   - Contact email on a free domain that does not match the SAFER record, or phone numbers that changed recently.
+   - Recent change of address, ownership or contact details, or dormant authority suddenly active.
+   - Remit-to bank account changed by email; verify any payment change by calling a number already on file.
+   - Rates far below market with eager acceptance, or the truck's DOT on arrival differs from the one booked (double brokering).
+   - Equipment count on SAFER that cannot cover the loads being accepted.
+8. Use a carrier-monitoring service (the user's choice) for continuous alerts on authority, insurance and safety changes. Re-vet at least yearly and on any alert.
+
+## 2. Benchmark the rate
+
+1. Break every rate into linehaul, fuel surcharge (and the table it references, usually tied to the US EIA weekly diesel price), and accessorials (detention, layover, stop-off, lumper, liftgate, TONU).
+2. Compare linehaul per mile, ex-fuel, against the user's own history for the lane and a market index they subscribe to (spot and contract). State the index, date and date range; never invent a market rate.
+3. LTL is priced differently: base rate from a tariff (a carrier's own, or a neutral base such as SMC3 CzarLite), a discount percentage, an absolute minimum charge, freight class from density, and accessorials. Compare net cost per shipment on a sample of real shipments, not discount percentages.
+4. Intermodal: compare door-to-door all-in against truckload, including drayage both ends, chassis, and transit days. It usually suits lanes long enough to absorb the extra handling and that tolerate longer transit.
+5. Flag lanes where the contract rate is well below spot: tender rejections will follow.
+
+## 3. Run a bid
+
+1. Package: lanes with volume, equipment, service requirements, accessorial schedule, fuel table, payment terms, insurance minimums and contract term.
+2. Invite only vetted carriers and brokers; give a deadline and a fixed response template (one row per lane).
+3. Award per lane: a primary, one or two backups, and a spot fallback. Weigh rate against scorecard history, not rate alone.
+4. Confirm awards in writing with committed volume (a range, not a promise you cannot keep) and the rate validity period.
+
+## 4. Routing guide and tendering
+
+- Tender in routing-guide order with a response deadline (for example 2 hours for next-day pickup). On rejection, go to the next carrier; log every tender, acceptance and rejection with time.
+- Track tender acceptance rate per carrier and lane. A primary below the agreed acceptance level for several weeks gets a conversation, then a re-sequence.
+- Never tender to an unvetted carrier because a load is urgent; use a vetted broker instead.
+
+## 5. Scorecard
+
+Score monthly per carrier, from shipment data, with the same definitions for everyone:
+
+| Metric | Definition |
+|---|---|
+| Tender acceptance | accepted tenders / tenders offered |
+| On-time pickup | picked up within the appointment window / pickups |
+| On-time delivery | delivered within window / deliveries |
+| Tracking compliance | loads with location updates at the agreed interval / loads |
+| Claims ratio | claim value / freight spend, and claim count / loads |
+| Invoice accuracy | invoices paid without dispute / invoices |
+| Cost | average cost per mile or per shipment vs lane benchmark |
+
+Share the scorecard with the carrier before acting on it. Decide grow / hold / improve plan / exit per carrier, with the numbers that drove it.
+
+## 6. Contract and negotiation
+
+- Terms to set: liability for cargo loss (Carmack Amendment applies to interstate carriers by default; any limit must be agreed in writing), claims filing and payment periods, indemnity, insurance minimums, no re-brokering, confidentiality, payment terms, fuel table, accessorial schedule, detention free time, and termination.
+- Negotiate with data: lane history, volume certainty, payment speed, and drop-trailer or fast load and unload times are worth rate.
+- **Stop and ask the user to involve a transportation lawyer** for indemnity changes, cargo liability limits, broker-carrier agreements, or anything the carrier redlines in liability or insurance. Drafting the agreement itself belongs to the `contract-drafting` skill.
+
+## Rules
+
+- Never book a carrier whose authority is not active or whose insurance you have not confirmed with the agent.
+- Never change remit-to bank details on email instructions alone.
+- Never state a market rate, FMCSA rule or insurance minimum you have not checked on the day; record source and date.
+- Do not use a carrier's safety data to rank drivers or make employment decisions; it is a carrier-level signal.
+
+## Report
+
+```
+Carrier vetting: <legal name> | USDOT <n> | checked <date>
+- Authority: <type, status, granted date>       source: L&I
+- Safety: <rating>; SMS: <categories flagged / none>  methodology: <BASICs | revised>
+- Insurance: auto <limit>, cargo <limit, key exclusions>; confirmed with <agent, date>
+- Red flags: <none | list>
+- Decision: approve | approve with conditions | reject | escalate
+```
+
+For a bid or scorecard: lane table (lane, volume, incumbent rate, benchmark with source and date, bids, award), carrier scorecard table, decisions with reasons, and items that need legal or insurance review.

package/skills/freight-carrier-management/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "A new trucking company wants our Dallas to Atlanta dry van loads, check their FMCSA authority, safety record and insurance before we book",
+    "Build a monthly carrier scorecard with tender acceptance, on-time delivery and claims ratio for our top 15 truckload carriers",
+    "We're running our annual freight bid for 40 lanes next month, help me put together the RFP package and award logic",
+    "Our contract reefer rates on the Fresno to Chicago lane look high, benchmark them and plan the negotiation with the carrier",
+    "Set up a routing guide with primary and backup carriers per lane and rules for tender rejections"
+  ],
+  "should_not_trigger": [
+    "A pallet of our goods arrived crushed at the customer, help me file the freight claim and tell the customer",
+    "Work out the import duty and landed cost for parts we bring in from Mexico by truck",
+    "Plan safety stock for SKUs that ship to our regional warehouses weekly",
+    "Design the return authorisation and refurbishment flow for products customers send back",
+    "Draft a master services agreement with a software vendor from our template"
+  ]
+}