@kaleidorg/mind 0.0.1 → 0.2.0

package/skills/bitrefill/references/mcp.md

@@ -0,0 +1,150 @@
+# Path: MCP
+
+**Preferred purchase channel.** Typed tool calls, OAuth or API key, no shell, works in 10+ hosts.
+
+## Two MCP servers
+
+### eCommerce MCP — for purchases
+
+URL: `https://api.bitrefill.com/mcp` (OAuth) **or** `https://api.bitrefill.com/mcp/YOUR_API_KEY` (header-less, key-in-path).
+
+7 tools:
+
+- `search-products` — keyword + country + category
+- `product-details` — packages (denominations) + pricing
+- `buy-products` — create invoice
+- `get-invoice-by-id` — poll payment status
+- `get-order-by-id` — get redemption info (codes, eSIM QR)
+- `list-invoices` — invoice history
+- `list-orders` — order history
+
+Auth: OAuth (recommended for interactive use) or API key from <https://www.bitrefill.com/account/developers>.
+
+### Development MCP — for docs only
+
+URL: `https://docs.bitrefill.com/mcp`. Indexes the docs site for code-help. **Not for purchases.** Use only when authoring an integration against the Bitrefill API/CLI.
+
+## Per-client setup
+
+### Cursor — `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global)
+
+```json
+{
+  "mcpServers": {
+    "bitrefill": {
+      "url": "https://api.bitrefill.com/mcp",
+      "autoApprove": [
+        "search-products", "product-details",
+        "list-invoices", "get-invoice-by-id",
+        "list-orders", "get-order-by-id"
+      ]
+    }
+  }
+}
+```
+
+Keep `buy-products` **out** of `autoApprove`. Cursor caps at 40 active tools across all servers.
+
+### Claude Code
+
+With the **bitrefill** plugin installed from this repo’s marketplace, the eCommerce MCP is auto-registered; `claude mcp add` below is for manual-only setups.
+
+```bash
+claude mcp add bitrefill --url https://api.bitrefill.com/mcp
+```
+
+Or edit `~/.claude.json`. Override output cap with `MAX_MCP_OUTPUT_TOKENS` (default 25 000).
+
+### Claude Desktop — `claude_desktop_config.json`
+
+macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`. Windows: `%APPDATA%\Claude\claude_desktop_config.json`.
+
+```json
+{
+  "mcpServers": {
+    "bitrefill": { "url": "https://api.bitrefill.com/mcp" }
+  }
+}
+```
+
+### Claude.ai (web) — Pro / Max / Team / Enterprise
+
+Settings → Connectors → Add custom connector → URL `https://api.bitrefill.com/mcp`. Free tier cannot add custom URLs.
+
+### ChatGPT (Plus / Pro / Business / Enterprise / Edu)
+
+Settings → Apps & Connectors → Add → URL `https://api.bitrefill.com/mcp`. Toggle **Developer Mode** to allow `buy-products` (write tool). Free tier blocked.
+
+### Codex CLI — `~/.codex/config.toml`
+
+```toml
+[mcp_servers.bitrefill]
+url = "https://api.bitrefill.com/mcp"
+bearer_token_env_var = "BITREFILL_API_KEY"
+```
+
+OAuth: `codex mcp login bitrefill`.
+
+### Gemini CLI — `~/.gemini/settings.json` (or project `.gemini/settings.json`)
+
+```json
+{
+  "mcpServers": {
+    "bitrefill": {
+      "url": "https://api.bitrefill.com/mcp",
+      "headers": { "Authorization": "Bearer ${BITREFILL_API_KEY}" }
+    }
+  }
+}
+```
+
+OAuth: `gemini mcp auth bitrefill`.
+
+### OpenCode — `opencode.jsonc`
+
+```jsonc
+{
+  "mcp": {
+    "bitrefill": {
+      "url": "https://api.bitrefill.com/mcp",
+      "headers": { "Authorization": "Bearer ${BITREFILL_API_KEY}" }
+    }
+  }
+}
+```
+
+### OpenClaw — see [host-openclaw.md](host-openclaw.md)
+
+```bash
+openclaw mcp set bitrefill --url "https://api.bitrefill.com/mcp/$BITREFILL_API_KEY"
+```
+
+## Workflow
+
+```
+search-products  →  product-details  →  buy-products  →  get-invoice-by-id  →  get-order-by-id
+```
+
+1. **Search**: `search-products(query="Steam", country="US", product_type="giftcard")`. `country` is uppercase Alpha-2.
+2. **Details**: `product-details(product_id="steam-usa", currency="USDC")`. Returns `packages` array with `package_id` in form `{product_id}<&>{value}`.
+3. **Buy**: `buy-products(cart_items=[{product_id, package_id}], payment_method, return_payment_link=true)`. Max 15 items per call.
+   - For instant fulfillment: `payment_method: "balance"` + `auto_pay: true`.
+   - For agent-driven crypto: `payment_method: "usdc_base"` + `return_payment_link: true` → use `x402_payment_url`.
+4. **Poll**: `get-invoice-by-id(invoice_id)`. Statuses: `unpaid` → `payment_detected` → `payment_confirmed` → `complete`.
+5. **Redeem**: `get-order-by-id(order_id, include_redemption_info=true)` → returns code / link / eSIM install URL.
+
+Confirm with user before step 3. Logging per [safeguards.md](safeguards.md).
+
+## Caveats
+
+- **ChatGPT** custom MCP requires Plus+; write tools require Developer Mode (admin-enabled on workspaces).
+- **Cursor** 40-tool cap across all servers.
+- **Claude.ai** consumer needs Pro+ for custom URLs.
+- **Code-execution sandboxes** (Claude.ai analysis tool, ChatGPT Code Interpreter) have **no network egress** — they can't call MCP servers; install MCP at the chat level instead.
+
+## Source of truth
+
+- <https://docs.bitrefill.com/docs/ecommerce-mcp>
+- <https://docs.bitrefill.com/docs/development-mcp>
+- <https://docs.bitrefill.com/docs/setup-guides>
+- Per-client setup: <https://docs.bitrefill.com/docs/use-with-cursor>, `/use-with-claude-chat`, `/use-with-claude-code`, `/use-with-chatgpt`

package/skills/bitrefill/references/safeguards.md

@@ -0,0 +1,138 @@
+# Spending Safeguards
+
+This skill enables **real-money transactions**. Purchases are fulfilled instantly after payment confirms. Digital codes are non-refundable per EU consumer rights once delivered.
+
+This page is the **agent-policy layer** — not in upstream Bitrefill or host docs. Read fully before any purchase tool call.
+
+## Universal rules
+
+- **Default: always confirm before purchasing.** Present product, denomination, price, payment method. Wait for explicit user approval. Autonomous purchasing only when user explicitly opts in for the current session.
+- **Codes are cash-like.** A gift card code or eSIM QR is bearer money. Store securely. Never share publicly.
+- **Prefer in-memory storage.** Don't write codes to plain-text logs, transcripts, or unencrypted files. Programmatically read code → use it → discard.
+- **If user asks for the code**: return it but advise to (a) store securely, (b) not share, (c) redeem ASAP.
+- **Dedicated, low-balance account.** Never give the agent access to high-balance accounts. Pre-fund only what the agent may spend in the current session.
+- **Headless CLI: agent-owned inbox.** Register Bitrefill with an agent inbox ([AgentMail](https://www.agentmail.to/) or equivalent — [cli-headless-auth.md](cli-headless-auth.md)), not the human's primary email. Inbox compromise = account takeover.
+- **Not a wallet.** This skill does not store private keys or manage crypto wallets. Never give the agent seed phrases, hardware-wallet PINs, or signing keys.
+- **Log every purchase.** `invoice_id`, product slug, amount, payment method, timestamp.
+- **Refunds**: digital goods refundable only if they don't work as expected (defective code). EU 14-day change-of-mind does **not** apply.
+- **Browser redemption fallback.** If trying to redeem on a brand site triggers anti-bot, ask the user to complete redemption manually and return the code.
+
+Terms: <https://www.bitrefill.com/terms/>.
+
+## Per-host hardening
+
+### OpenClaw
+
+Defaults are permissive (sandboxing off, `security: full`, `ask: off`). Tighten:
+
+- **Prefer guest CLI via `exec`** for first purchases (no auth); sign in only when human wants `balance` cap or cashback. See [host-openclaw.md](host-openclaw.md).
+
+- `channels.<ch>.allowFrom: ["<your_id>"]` + `dmPolicy: "pairing"` on every channel.
+- `~/.openclaw/exec-approvals.json`: `security: allowlist` + `ask: on-miss`. Allowlist read tools (`bitrefill search-products`, `bitrefill list-*`, `bitrefill get-*`). Force `/approve` for `bitrefill buy-products` and the MCP `buy-products` call.
+- `agents.list[]` Bitrefill persona with `tools.deny: ["gateway"]` so the agent cannot rewrite Gateway config.
+- Disable voice readback (`audio_as_voice` / TTS) for the Bitrefill agent. Codes spoken aloud over voice notes leak.
+- Force text-only delivery — no `MEDIA:<url>` for redemption code output.
+
+Full detail in [host-openclaw.md](host-openclaw.md) §8.
+
+### Cursor
+
+`.cursor/mcp.json` `autoApprove` may include read tools. **Never** include `buy-products`:
+
+```json
+{
+  "mcpServers": {
+    "bitrefill": {
+      "url": "https://api.bitrefill.com/mcp",
+      "autoApprove": [
+        "search-products", "product-details",
+        "list-invoices", "get-invoice-by-id",
+        "list-orders", "get-order-by-id"
+      ]
+    }
+  }
+}
+```
+
+### Codex CLI
+
+Run with sandbox + approval:
+
+```bash
+codex --sandbox workspace-write --ask-for-approval on-request
+```
+
+Put `BITREFILL_API_KEY` in a profile (`~/.codex/config.toml` `[profiles.bitrefill]`), not in committed config.
+
+### Claude Code
+
+In `~/.claude/settings.json` (or project `.claude/settings.json`):
+
+```json
+{
+  "sandbox": {
+    "filesystem": {
+      "denyRead": ["~/.ssh", ".env", "*.pem", "**/.bitrefill_token"],
+      "denyWrite": ["~/.ssh", ".env"]
+    },
+    "network": {
+      "allow": ["api.bitrefill.com", "registry.npmjs.org"]
+    }
+  }
+}
+```
+
+### Claude Desktop / Claude.ai web
+
+Per-tool approval prompts on by default. Keep them on. Don't whitelist `buy-products`.
+
+### ChatGPT (web / Desktop / Atlas / Agent)
+
+Developer Mode required for write tools. Keep it **off** unless actively purchasing. Confirm in-chat before every `buy-products`.
+
+### Gemini CLI
+
+Run with `--sandbox` (Seatbelt / Docker / gVisor). Per-shell command confirmation prompts on by default.
+
+### OpenCode
+
+Set permissions per agent:
+
+```jsonc
+{
+  "agents": {
+    "bitrefill": {
+      "permissions": {
+        "edit": "ask",
+        "bash": { "*": "ask", "bitrefill list-*": "allow", "bitrefill get-*": "allow" },
+        "webfetch": "ask"
+      }
+    }
+  }
+}
+```
+
+## Payment method risk
+
+- `balance` — instant, capped by pre-funded amount. **Lowest blast radius.**
+- `usdc_base` via x402 — autonomous payment from agent-controlled wallet. Bound the wallet balance.
+- `lightning` — fast, low fee. Manual pay or Lightning-capable agent.
+- Other on-chain crypto — slow, requires polling. Higher chance of expired invoices (180 min).
+
+Default recommendation: pre-fund `balance` with low cap → use `payment_method: "balance"` + `auto_pay: true`.
+
+## What to NEVER do
+
+- Pass redemption codes through group chats, public channels, screen-shared sessions, or shared documents.
+- Speak codes aloud via TTS / voice notes.
+- Store codes in version control, even private repos.
+- Give the agent seed phrases or hardware-wallet PINs.
+- Auto-approve `buy-products` in any host's MCP config.
+- Run the Bitrefill skill from an account with stored payment cards or high balances.
+
+## Source of truth
+
+- Bitrefill ToS: <https://www.bitrefill.com/terms/>
+- Refund policy: <https://docs.bitrefill.com/docs/refunds>
+- Path setup: [mcp.md](mcp.md), [cli.md](cli.md), [api.md](api.md), [browse.md](browse.md)
+- OpenClaw hardening: [host-openclaw.md](host-openclaw.md)

package/skills/bitrefill/references/troubleshooting.md

@@ -0,0 +1,182 @@
+# Troubleshooting
+
+Common errors across all paths. Full enum: <https://docs.bitrefill.com/docs/error-codes> and <https://docs.bitrefill.com/docs/References>.
+
+## Browse path
+
+### `403 Forbidden` when fetching bitrefill.com
+
+Cloudflare blocks datacenter IPs. Fix: switch to residential browser (ChatGPT Atlas, Cursor browser, Claude+Chrome ext, OpenClaw on user host) or pivot to MCP/CLI/API.
+
+### Product appears in listing but not purchasable
+
+Geolock at IP level. URL country only filters listed inventory; checkout enforces user's IP. Tell user to access from the matching country (or VPN) — but warn this may violate ToS.
+
+## MCP path
+
+### Tool not visible to agent
+
+- Cursor: 40-tool cap exceeded across all servers. Disable an unused MCP server.
+- ChatGPT: Developer Mode off → write tools (`buy-products`) hidden. Toggle in Settings.
+- Claude.ai consumer: Free tier cannot add custom MCP URLs. Upgrade to Pro+.
+- OpenClaw: `tools.deny: ["bundle-mcp"]` accidentally hiding the server, or per-agent `tools.allow` whitelist excluding it.
+
+### `StreamableHTTPError` with HTML body
+
+Wrong `MCP_URL` — pointing at non-Bitrefill endpoint. Unset `MCP_URL` env var or set to `https://api.bitrefill.com/mcp`.
+
+### OAuth loop in Cursor / Claude.ai
+
+Clear browser cookies for `bitrefill.com`, try a different browser, ensure pop-ups not blocked.
+
+### MCP server filtered out (OpenClaw)
+
+OpenClaw startup safety filter rejects env keys: `NODE_OPTIONS`, `PYTHONSTARTUP`, `PYTHONPATH`, `PERL5OPT`, `RUBYOPT`, `SHELLOPTS`, `PS4`. Use only standard `*_API_KEY` / `GITHUB_TOKEN` / proxy vars in MCP server `env` blocks.
+
+### MCP output truncated
+
+Default cap varies by host. Claude Code: `MAX_MCP_OUTPUT_TOKENS=50000` to raise. OpenClaw: `tools.toolResultMaxChars` (default 16000). Use pagination: `--per_page 25`, multiple `list-orders` calls.
+
+## CLI path
+
+### `cart_items` JSON shape error
+
+```
+# WRONG (object)
+--cart_items '{"product_id": "steam-usa", "package_id": 5}'
+
+# RIGHT (array)
+--cart_items '[{"product_id": "steam-usa", "package_id": 5}]'
+```
+
+### `Invalid denomination 'undefined'`
+
+Both `product_id` AND `package_id` required per item.
+
+### `Too big: expected array to have <=15 items`
+
+Split into multiple `buy-products` calls.
+
+### `per_page must be less than 500`
+
+Server limit. Use 500 max.
+
+### `error: required option '--<name>' not specified`
+
+Client-side validation. Add the missing option.
+
+### "Must be one of" enum errors
+
+| Option | Valid values | Common mistakes |
+|--------|--------------|-----------------|
+| `--payment_method` | `bitcoin`, `lightning`, `ethereum`, `usdc_polygon`, `usdt_polygon`, `usdc_erc20`, `usdt_erc20`, `usdc_arbitrum`, `usdc_solana`, `usdc_base`, `eth_base`, `balance` | `paypal`, `visa`, `USDC_BASE` (case-sensitive) |
+| `--product_type` | `giftcard`, `esim` | `giftcards`, `gift_card`, `sim` |
+| `--country` | `US`, `IT`, `BR` (uppercase Alpha-2) | `us`, `USA`, `"United States"` |
+
+### Wrong `package_id` for named denominations
+
+Exact, case-sensitive. WRONG `"1GB"`, `"300 nc"`. RIGHT `"1GB, 7 Days"`, `"PUBG New State 300 NC"`. Get exact strings from `get-product-details` `packages` array.
+
+### Compound key in `package_id`
+
+```
+# WRONG
+--cart_items '[{"product_id": "steam-usa", "package_id": "steam-usa<&>5"}]'
+
+# RIGHT (value after <&>)
+--cart_items '[{"product_id": "steam-usa", "package_id": 5}]'
+```
+
+### CLI auth failure (≥ 0.3.0)
+
+CLI uses OAuth client_credentials + email magic link — not API keys, not browser OAuth.
+
+```bash
+bitrefill reset                                    # clear corrupt state
+bitrefill login --email you@example.com
+bitrefill verify --code 123456                     # add --otp for TOTP
+bitrefill whoami --json
+```
+
+| Error | Fix |
+|-------|-----|
+| `Access token is required for login/verify` | Any command first (MCP connect), or `reset` then retry |
+| `No pending login` | Run `login --email` before `verify` |
+| `No OTP code provided` on verify | Account has 2FA — add `--otp` (authenticator), keep `--code` (email magic link) |
+| `Invalid code` on verify | Wrong email code or wrong TOTP; don't swap them — email code → `--code`, authenticator → `--otp` |
+| `unknown option '--code'` on login | Code goes on `verify --code`, not `login` |
+| `unknown command 'login'` | Already signed in — `logout` first |
+| `Failed to establish a session` | `reset`, then retry |
+| Invalid / expired code | Re-run `login --email`; headless → poll agent inbox (AgentMail or equivalent — [cli-headless-auth.md](cli-headless-auth.md)) |
+| Missing TOTP | `verify --code … --otp "$(op read 'op://Vault/Item/one-time password?attribute=otp')"` |
+
+State: `~/.config/bitrefill-cli/<host>.v1.json`. `logout` revokes session; `reset` clears everything.
+
+Pre-0.3.0 (`credentials.json`, `--api-key`): upgrade CLI. Developer API keys still work for [mcp.md](mcp.md) / [api.md](api.md) paths only.
+
+### Empty search results, no error
+
+`found: 0` with no error message. Causes:
+
+- `--category` slug doesn't exist (silent miss).
+- Product not available in `--country`.
+- `--in_stock true` (default) filters out-of-stock.
+
+Fix: drop `--category`, change `--country`, or `--in_stock false`.
+
+### Unpaid invoices missing from list
+
+`list-invoices` defaults `--only_paid true`. Use `--only_paid false`.
+
+## API path
+
+### `401 Unauthorized`
+
+- Personal: `Authorization: Bearer $BITREFILL_API_KEY` missing or wrong key.
+- Business / Affiliate: `Authorization: Basic $(echo -n "$ID:$SECRET" | base64)` malformed.
+
+### `429 Too Many Requests`
+
+Rate limited. Defaults: 60 req / 10 min on most endpoints, 60 req/min on `/products` + `/products/search` plus 1000 product req/hr quota, 1 req / 3 s on `/ping`. Back off + retry. Cache product catalog locally.
+
+### `RESOURCE_NOT_FOUND` on `GET /invoices/{id}`
+
+Bad invoice ID. Verify via `list-invoices`.
+
+### `Product '{slug}' is not available`
+
+Bad product slug. Verify via `search-products`.
+
+### Invoice expired
+
+Invoices expire after **180 minutes**. Cannot re-pay. Create new one.
+
+## OpenClaw-specific
+
+### Cron purchase failed silently
+
+`exec-approvals.json` set to `ask: on-miss` but no operator online to `/approve`. Either pre-approve `bitrefill buy-products` for trusted SKU/amount, or schedule when operator available.
+
+### Pi agent can't see the Bitrefill MCP
+
+Check:
+
+1. `openclaw mcp list` shows entry.
+2. `~/.openclaw/openclaw.json` parses (no trailing commas).
+3. Agent profile not denying `bundle-mcp` or whitelisting tools narrowly.
+4. CLI signed in (`bitrefill whoami --json`) or MCP OAuth completed — not just shell env vars.
+
+### Mobile node camera tool unavailable
+
+Node not paired or paired but offline. Check `openclaw nodes list`. Re-pair via Control UI (`openclaw dashboard`).
+
+### Telegram message not reaching agent
+
+`channels.telegram.dmPolicy: "pairing"` and sender not paired. Run `openclaw pairing approve telegram <CODE>` (codes expire 1 hr).
+
+## Source of truth
+
+- Bitrefill error codes: <https://docs.bitrefill.com/docs/error-codes>
+- Bitrefill error handling: <https://docs.bitrefill.com/docs/References>
+- Rate limits: <https://docs.bitrefill.com/docs/rate-limits>
+- OpenClaw troubleshooting: <https://docs.openclaw.ai/help> + per-tool pages

package/skills/kaleido-trading/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: kaleido-trading
+description: "Trade and manage a portfolio on KaleidoSwap: get live prices and market data, quote and place atomic swaps between BTC and RGB assets (USDT, XAUT), acquire inbound liquidity from the LSP, and check positions. Triggers when the user wants a price, a quote, to swap or trade assets, to rebalance a portfolio, or to acquire a Lightning channel from the LSP."
+tools: get_price, get_market_data, kaleidoswap_get_pairs, kaleidoswap_get_quote, kaleidoswap_place_order, kaleidoswap_get_order_status, kaleidoswap_get_position, kaleidoswap_lsp_get_info, kaleidoswap_lsp_create_order
+triggers: price, quote, swap, trade, rebalance, portfolio, market, slippage, liquidity, channel order
+metadata:
+  author: kaleidoswap
+  version: "0.1.0"
+  surface: "kaleido-mcp (KaleidoSwap maker + market data)"
+---
+
+# KaleidoSwap trading
+
+Quote, swap, and manage a portfolio through the KaleidoSwap maker and market
+data MCP tools.
+
+## Flow
+
+1. **Price first.** Use `get_price` / `get_market_data` for context and
+   `kaleidoswap_get_quote` for an executable price before proposing a trade.
+2. **Confirm the trade.** Show pair, direction, amount in, expected amount out,
+   and fees. Wait for explicit approval before `kaleidoswap_place_order`.
+3. **Track it.** After placing, poll `kaleidoswap_get_order_status` until the
+   swap settles, then report the result and the new `kaleidoswap_get_position`.
+4. **Need inbound liquidity?** If a swap can't route for lack of a channel, use
+   `kaleidoswap_lsp_get_info` then `kaleidoswap_lsp_create_order` to buy one.
+
+## Rules
+
+- Never trade on a stale quote — re-quote if the user hesitates.
+- Surface slippage and fees explicitly; small local models must not hide cost.

package/skills/kaleido-wallet/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: kaleido-wallet
+description: "Manage a KaleidoSwap Lightning + RGB wallet: check BTC and asset balances, get a receive address, create or pay Lightning invoices, send on-chain BTC, open or list channels. Triggers when the user asks about their balance, wants to receive or send funds, pay an invoice, or manage Lightning channels."
+tools: wdk_get_balances, wdk_get_asset_balance, wdk_get_address, wdk_create_ln_invoice, wdk_pay_invoice, wdk_send_btc, wdk_list_channels, wdk_open_channel, wdk_get_node_info
+triggers: balance, receive, address, send, pay, invoice, channel, deposit, withdraw, funds
+metadata:
+  author: kaleidoswap
+  version: "0.1.0"
+  surface: "kaleido-mcp (WDK node)"
+---
+
+# KaleidoSwap wallet
+
+Operate the user's KaleidoSwap node (Lightning + RGB assets) through the
+`wdk_*` MCP tools.
+
+## Rules
+
+- **Read before you write.** Check the balance (`wdk_get_balances`) before any
+  send or channel open, and confirm the node is healthy (`wdk_get_node_info`).
+- **Confirm every spend.** State the amount, destination, and resulting balance,
+  then wait for explicit approval before calling `wdk_send_btc`,
+  `wdk_pay_invoice`, or `wdk_open_channel`.
+- **Match the rail to the asset.** Lightning for fast BTC/asset payments,
+  on-chain for settlement or channel funding. Use `wdk_get_asset_balance` for
+  RGB assets (USDT, XAUT, …).
+- Never reveal seeds or private keys — this skill operates a node, it is not a
+  key vault.

package/src/capabilities.ts

@@ -0,0 +1,67 @@
+/**
+ * Capability profiling — decide which features to turn on for a given device +
+ * model, so a 2 GB phone running a 0.6B model doesn't try to do everything.
+ *
+ * Pure heuristic. Hosts call this once (with device RAM + the model's context
+ * size + whether an embedder is available) and get back feature flags + sane
+ * retrieval defaults to feed the ContextBuilder.
+ */
+
+import { contextBudgetTokens } from './context/budget.js';
+
+export interface CapabilityInput {
+  /** Total device RAM in bytes (e.g. react-native-device-info getTotalMemory). */
+  ramBytes?: number;
+  /** The loaded model's context window in tokens (modelConfig.ctx_size). */
+  modelCtxTokens: number;
+  /** Whether an EmbeddingProvider is wired (QVAC embed, etc.). */
+  hasEmbeddings?: boolean;
+  /** Running inference on a remote provider (desktop/server) — relaxes limits. */
+  delegated?: boolean;
+}
+
+export interface MindCapabilities {
+  /** Long-term memory (cheap — on unless the window is tiny). */
+  memory: boolean;
+  /** Semantic recall for memory (needs embeddings). */
+  semanticMemory: boolean;
+  /** Retrieval-augmented generation (needs embeddings + enough RAM/context). */
+  rag: boolean;
+  /** Token budget for injected system context. */
+  contextBudgetTokens: number;
+  /** Memories to auto-recall into context. */
+  topKMemory: number;
+  /** Knowledge chunks the search_knowledge tool returns. */
+  topKRag: number;
+}
+
+const GiB = 1024 * 1024 * 1024;
+
+export function capabilityProfile(input: CapabilityInput): MindCapabilities {
+  const ramGb = input.delegated ? Infinity : (input.ramBytes ?? 0) / GiB;
+  const ctx = input.modelCtxTokens;
+  const hasEmb = !!input.hasEmbeddings;
+
+  const budget = contextBudgetTokens(ctx);
+
+  // Memory: on whenever there's room for a few lines. Semantic needs embeddings.
+  const memory = budget >= 256;
+  const semanticMemory = memory && hasEmb;
+
+  // RAG is the expensive one: needs embeddings, a non-tiny context window, and
+  // (on-device) enough RAM to hold an embedding model + index.
+  const rag = hasEmb && ctx >= 4096 && (input.delegated || ramGb >= 3);
+
+  // Scale how much we pull in with the available window.
+  const topKMemory = budget >= 1500 ? 4 : budget >= 700 ? 3 : 2;
+  const topKRag = rag ? (budget >= 2500 ? 5 : 3) : 0;
+
+  return {
+    memory,
+    semanticMemory,
+    rag,
+    contextBudgetTokens: budget,
+    topKMemory,
+    topKRag,
+  };
+}

package/src/context/budget.ts

@@ -0,0 +1,46 @@
+/**
+ * Context budgeting — the hardware-aware part.
+ *
+ * Small on-device models have small context windows (a 0.6B may run at 2k, a
+ * desktop 8B at 8k+). Memory, skills, RAG and tool schemas all compete for that
+ * window. These helpers turn a model's `ctx_size` into a token budget for the
+ * injected context, so we never overflow a tiny model.
+ *
+ * Token estimation is deliberately rough (≈ 4 chars/token) — no tokenizer dep.
+ */
+
+/** Rough token count for a string (no tokenizer — ~4 chars/token). */
+export function estimateTokens(text: string): number {
+  return Math.ceil(text.length / 4);
+}
+
+/** Trim text to at most `maxTokens` (on a word boundary where possible). */
+export function clampToTokens(text: string, maxTokens: number): string {
+  const maxChars = maxTokens * 4;
+  if (text.length <= maxChars) return text;
+  const cut = text.slice(0, maxChars);
+  const sp = cut.lastIndexOf(' ');
+  return (sp > maxChars * 0.6 ? cut.slice(0, sp) : cut).trimEnd() + '…';
+}
+
+export interface BudgetReserves {
+  /** Tokens to leave for the model's reply. Default 512. */
+  output?: number;
+  /** Tokens to budget for tool schemas the engine sends. Default 600. */
+  tools?: number;
+  /** Tokens to budget for the running conversation (user + history). Default 768. */
+  conversation?: number;
+}
+
+/**
+ * Tokens available for the *injected system context* (soul + instructions +
+ * skill + memory + RAG), given the model's context window and what else must
+ * fit. Never negative; clamped to a sane floor so something always gets in.
+ */
+export function contextBudgetTokens(ctxSize: number, reserves: BudgetReserves = {}): number {
+  const output = reserves.output ?? 512;
+  const tools = reserves.tools ?? 600;
+  const conversation = reserves.conversation ?? 768;
+  const available = ctxSize - output - tools - conversation;
+  return Math.max(256, available);
+}