@ketecode/loom 0.0.0-stage → 0.2.0

package/scripts/lib/skills.js

@@ -0,0 +1,87 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseFrontmatter } = require('./frontmatter');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..');
+const SKILLS_DIR = path.join(REPO_ROOT, 'skills');
+const AGENTS_DIR = path.join(REPO_ROOT, 'agents');
+const COMMANDS_DIR = path.join(REPO_ROOT, 'commands');
+const HOOKS_DIR = path.join(REPO_ROOT, 'hooks');
+const RULES_DIR = path.join(REPO_ROOT, 'rules');
+
+const csv = (s) => (s || '').split(',').map((x) => x.trim()).filter(Boolean);
+
+// Reads one markdown item (SKILL.md, AGENT.md or a command file). `dir` is the item's name.
+function loadDoc(file, extra) {
+  const text = fs.readFileSync(file, 'utf8');
+  const { data, body, errors } = parseFrontmatter(text);
+  const meta = (data && data.metadata) || {};
+  return {
+    file,
+    text,
+    body,
+    data: data || {},
+    parseErrors: errors,
+    name: data && data.name,
+    description: data && data.description,
+    version: meta['kete-loom/version'],
+    category: meta['kete-loom/category'],
+    risk: meta['kete-loom/risk'],
+    requires: csv(meta['kete-loom/requires']),
+    tools: meta['kete-loom/tools'] === undefined ? null : csv(meta['kete-loom/tools']),
+    argumentHint: meta['kete-loom/argument-hint'],
+    event: meta['kete-loom/event'],
+    optIn: meta['kete-loom/opt-in'] === 'true',
+    paths: csv(meta['kete-loom/paths']),
+    ...extra,
+  };
+}
+
+function listFolders(root, file, load) {
+  if (!fs.existsSync(root)) return [];
+  return fs
+    .readdirSync(root, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && fs.existsSync(path.join(root, d.name, file)))
+    .map((d) => load(path.join(root, d.name)))
+    .sort((a, b) => a.dir.localeCompare(b.dir));
+}
+
+function loadSkill(skillPath) {
+  return loadDoc(path.join(skillPath, 'SKILL.md'), { kind: 'skill', dir: path.basename(skillPath), path: skillPath });
+}
+
+function loadAgent(agentPath) {
+  return loadDoc(path.join(agentPath, 'AGENT.md'), { kind: 'agent', dir: path.basename(agentPath), path: agentPath });
+}
+
+function loadHook(hookPath) {
+  return loadDoc(path.join(hookPath, 'HOOK.md'), { kind: 'hook', dir: path.basename(hookPath), path: hookPath });
+}
+
+function loadCommand(file) {
+  return loadDoc(file, { kind: 'command', dir: path.basename(file, '.md'), path: file });
+}
+
+function loadRule(file) {
+  return loadDoc(file, { kind: 'rule', dir: path.basename(file, '.md'), path: file });
+}
+
+const listSkills = (root = SKILLS_DIR) => listFolders(root, 'SKILL.md', loadSkill);
+const listAgents = (root = AGENTS_DIR) => listFolders(root, 'AGENT.md', loadAgent);
+const listHooks = (root = HOOKS_DIR) => listFolders(root, 'HOOK.md', loadHook);
+
+function listFiles(root, load) {
+  if (!fs.existsSync(root)) return [];
+  return fs
+    .readdirSync(root)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => load(path.join(root, f)))
+    .sort((a, b) => a.dir.localeCompare(b.dir));
+}
+
+const listCommands = (root = COMMANDS_DIR) => listFiles(root, loadCommand);
+const listRules = (root = RULES_DIR) => listFiles(root, loadRule);
+
+module.exports = { REPO_ROOT, SKILLS_DIR, AGENTS_DIR, COMMANDS_DIR, HOOKS_DIR, RULES_DIR, listSkills, listAgents, listCommands, listHooks, listRules, loadSkill, loadAgent, loadCommand, loadHook, loadRule };

package/scripts/lib/targets.js

@@ -0,0 +1,123 @@
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+// Where each host looks for skills, agents and commands (verified against host docs, Oct 2026).
+// `agents` is the shared open-standard folder: Codex, OpenCode, Cursor, Gemini CLI, GitHub Copilot
+// and Kete Code all read its skills. It defines nothing for agents or commands.
+// Claude Code reads only its own folders; Cursor and VS Code Copilot also read `.claude/agents`.
+// So the default install is `agents` + `claude`, plus agents and commands for hosts that need their
+// own copy (`auto`, including Kete Code) when that host is detected. The other targets exist for people who want one host only.
+// Kinds a target doesn't list are not supported there: Codex prompts are deprecated, Copilot CLI has
+// no prompt files and Cursor commands are beta, so commands go to Claude, OpenCode and Gemini only.
+const TARGETS = {
+  agents: {
+    label: 'Shared .agents folder (Codex, OpenCode, Cursor, Gemini CLI, Copilot, Kete Code)',
+    user: { skills: ['.agents', 'skills'] },
+    project: { skills: ['.agents', 'skills'] },
+    default: true,
+  },
+  claude: {
+    label: 'Claude Code (its agents are also read by Cursor and VS Code Copilot)',
+    // Rules go in a kete-loom subfolder (Claude Code scans .claude/rules recursively), so ours stay apart.
+    user: { skills: ['.claude', 'skills'], agents: ['.claude', 'agents'], commands: ['.claude', 'commands'], rules: ['.claude', 'rules', 'kete-loom'] },
+    project: { skills: ['.claude', 'skills'], agents: ['.claude', 'agents'], commands: ['.claude', 'commands'], rules: ['.claude', 'rules', 'kete-loom'] },
+    default: true,
+    hooks: true,
+  },
+  codex: {
+    label: 'Codex (agents only; skills come from .agents)',
+    user: { agents: ['.codex', 'agents'] },
+    project: { agents: ['.codex', 'agents'] },
+    detect: { user: ['.codex'], project: ['.codex'] },
+    auto: true,
+    hooks: true,
+  },
+  opencode: {
+    label: 'OpenCode',
+    user: { skills: ['.config', 'opencode', 'skills'], agents: ['.config', 'opencode', 'agents'], commands: ['.config', 'opencode', 'commands'] },
+    project: { skills: ['.opencode', 'skills'], agents: ['.opencode', 'agents'], commands: ['.opencode', 'commands'] },
+    detect: { user: ['.config', 'opencode'], project: ['.opencode'] },
+    auto: true,
+    hooks: true,
+  },
+  // Kete Code (an OpenCode fork) reads skills from .agents and .claude, but agents and commands only from its own folders.
+  // shortcut: user paths assume XDG_CONFIG_HOME is ~/.config (as for opencode); honour it if users report custom roots.
+  kete: {
+    label: 'Kete Code',
+    user: { skills: ['.config', 'kete', 'skills'], agents: ['.config', 'kete', 'agents'], commands: ['.config', 'kete', 'commands'] },
+    project: { skills: ['.kete', 'skills'], agents: ['.kete', 'agents'], commands: ['.kete', 'commands'] },
+    detect: { user: ['.config', 'kete'], project: ['.kete'] },
+    auto: true,
+    hooks: true,
+  },
+  cursor: {
+    label: 'Cursor only',
+    user: { skills: ['.cursor', 'skills'], agents: ['.cursor', 'agents'] },
+    // Cursor reads rule files only per project (user rules live in its settings UI).
+    project: { skills: ['.cursor', 'skills'], agents: ['.cursor', 'agents'], rules: ['.cursor', 'rules', 'kete-loom'] },
+    // Detected only for hooks: Cursor already reads agents from .claude.
+    detect: { user: ['.cursor'], project: ['.cursor'] },
+    hooks: true,
+  },
+  gemini: {
+    label: 'Gemini CLI',
+    user: { skills: ['.gemini', 'skills'], agents: ['.gemini', 'agents'], commands: ['.gemini', 'commands'] },
+    project: { skills: ['.gemini', 'skills'], agents: ['.gemini', 'agents'], commands: ['.gemini', 'commands'] },
+    detect: { user: ['.gemini'], project: ['.gemini'] },
+    auto: true,
+    hooks: true,
+  },
+  copilot: {
+    label: 'GitHub Copilot only',
+    user: { skills: ['.copilot', 'skills'], agents: ['.copilot', 'agents'], rules: ['.copilot', 'instructions', 'kete-loom'] },
+    project: { skills: ['.github', 'skills'], agents: ['.github', 'agents'], rules: ['.github', 'instructions', 'kete-loom'] },
+    detect: { user: ['.copilot'], project: ['.github'] },
+    hooks: true,
+  },
+  // Kiro reads skills only from its own folders, agents as Markdown, prompts (slash commands) and steering files.
+  kiro: {
+    label: 'Kiro (IDE and CLI)',
+    user: { skills: ['.kiro', 'skills'], agents: ['.kiro', 'agents'], commands: ['.kiro', 'prompts'], rules: ['.kiro', 'steering'] },
+    project: { skills: ['.kiro', 'skills'], agents: ['.kiro', 'agents'], commands: ['.kiro', 'prompts'], rules: ['.kiro', 'steering'] },
+    detect: { user: ['.kiro'], project: ['.kiro'] },
+    auto: true,
+    ownSkills: true,
+  },
+};
+
+const KINDS = ['skills', 'agents', 'commands', 'rules'];
+
+// Which folders each host reads skills from, used by `doctor` to show where a skill is visible.
+const HOST_READS = {
+  'Claude Code': ['claude'],
+  Codex: ['agents'],
+  OpenCode: ['agents', 'claude', 'opencode'],
+  Cursor: ['agents', 'claude', 'cursor'],
+  'Gemini CLI': ['agents', 'gemini'],
+  'GitHub Copilot': ['agents', 'claude', 'copilot'],
+  'Kete Code': ['agents', 'claude', 'kete'],
+  Kiro: ['kiro'],
+};
+
+function baseDir({ scope = 'user', home = os.homedir(), cwd = process.cwd() } = {}) {
+  return scope === 'project' ? cwd : home;
+}
+
+// Returns the folder for one kind, or null when the target doesn't support that kind.
+function resolveTarget(name, { scope = 'user', home = os.homedir(), cwd = process.cwd(), kind = 'skills' } = {}) {
+  const t = TARGETS[name];
+  if (!t) throw new Error(`unknown target "${name}". Known: ${Object.keys(TARGETS).join(', ')}`);
+  const segments = t[scope === 'project' ? 'project' : 'user'][kind];
+  return segments ? path.join(baseDir({ scope, home, cwd }), ...segments) : null;
+}
+
+function detected(name, opts = {}) {
+  const t = TARGETS[name];
+  const segments = t.detect && t.detect[opts.scope === 'project' ? 'project' : 'user'];
+  return Boolean(segments) && fs.existsSync(path.join(baseDir(opts), ...segments));
+}
+
+module.exports = { TARGETS, KINDS, HOST_READS, resolveTarget, detected };

package/skills/accounting-api-integration/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: accounting-api-integration
+description: Connects an application's sales and payments to QuickBooks Online and Xero through their accounting APIs, handling the OAuth 2.0 authorisation code flow with rotating refresh tokens, per-company realm or tenant IDs, chart of accounts and tax code mapping, posting customers, invoices, payments and credit notes, safe retries with requestid or Idempotency-Key, HMAC-verified webhooks, 429 rate-limit backoff, and nightly reconciliation against the ledger. Use when building a QuickBooks or Xero sync, fixing duplicate or missing invoices in the books, debugging invalid_grant or token expiry, mapping products to income accounts, or reconciling app revenue with what the accountant sees.
+license: MIT
+compatibility: Any Agent Skills host. Live calls need network access to quickbooks.api.intuit.com (or the sandbox) and api.xero.com. Examples are HTTP and TypeScript-like pseudocode; official SDKs exist for most languages.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: integrations
+  kete-loom/risk: network
+  kete-loom/owner: "Kete-org"
+---
+
+# Accounting API integration (QuickBooks Online, Xero)
+
+Push your app's financial events into the customer's books exactly once, mapped to accounts their accountant chose, and prove it with a reconciliation. Your app stays the source of truth for what was sold; the ledger is the source of truth for the books. API detail: `references/quickbooks.md` and `references/xero.md`.
+
+## Ground rules
+
+1. **One connection per company.** QuickBooks identifies a company by `realmId`; Xero by tenant ID (send `xero-tenant-id` on every call). Store tokens per connection, encrypted at rest, never in logs.
+2. **Refresh tokens rotate.** Each refresh can return a new refresh token; store it atomically before using the new access token, and serialise refreshes per connection (a lock), or two workers will race and one gets `invalid_grant`. Treat `invalid_grant` as "reconnect needed": mark the connection, alert the user, stop syncing it.
+3. **Accounts are mapped, never guessed.** The customer (or their accountant) maps each of your product types, discounts, fees, tax rates and payment methods to an account, item and tax code in their ledger. Store the mapping by remote ID, not name. Block syncing until it is complete.
+4. **Every write is idempotent.** QuickBooks: a unique `requestid` query parameter per logical operation. Xero: an `Idempotency-Key` header. Derive the key from your own record (`invoice:<id>:create`), never a fresh random value per retry. Also store the remote ID on your record and check it before creating.
+5. **Your record links to the remote record.** Keep `remote_id`, `remote_type`, last sync status and error per record, so you can resume, update and reconcile.
+6. **Don't post what the ledger already has.** If the customer's payment provider has its own QuickBooks or Xero feed, agree with the user which system posts what, or invoices and payments appear twice.
+7. **Rate limits are mostly per company.** Queue writes per connection, back off on `429` (honour `Retry-After` where Xero sends it; QuickBooks says wait 60 seconds), and batch where the API supports it. Xero also has an app-wide per-minute limit across all tenants.
+8. **Sandbox first.** QuickBooks sandbox companies and a Xero demo company; never test against a customer's live books.
+
+## Workflow
+
+1. **Confirm scope with the user**: which provider(s), which objects flow (customers, invoices, payments, credit notes, refunds, fees, payouts), one-way or two-way, and start date for the backfill. Stop and ask if two-way: conflict rules are a product decision.
+2. **OAuth 2.0 authorisation code flow** with a `state` value bound to the user's session, the minimum scopes, and a callback that stores tokens and the realm or tenant. Endpoints and scopes in the references.
+3. **Read the chart of accounts and tax codes** and present a mapping screen. Validate mapped accounts are active and of the right type (income for sales lines, bank or undeposited funds for payments).
+4. **Sync customers** (look up by your external ID or email first; create if absent).
+5. **Post invoices** with lines carrying the mapped item/account and tax code, your invoice number, dates and currency. Amounts must match your invoice exactly; send line amounts and tax as computed by your billing or tax system rather than letting the ledger recompute them when the API allows it, and verify the total on the response.
+6. **Post payments** linked to the invoice, into the mapped deposit account, on the actual payment date. Post refunds and credit notes as their own objects linked to the original.
+7. **Webhooks** (optional, for changes made in the ledger): verify the HMAC signature on the raw body, respond fast, then fetch the changed records by ID. Payloads carry IDs, not trusted data.
+8. **Reconcile nightly** (below), and surface failures to the user with the remote error message.
+
+## Updates and conflicts
+
+- QuickBooks updates need the current `SyncToken`; read, modify, write, and on a stale-object error re-read and retry once.
+- Don't update invoices that are paid, or in a locked period: QuickBooks and Xero both support closing dates/lock dates and will reject or warn. Stop and ask the user how to handle changes to a closed period; usually a credit note in the current period.
+- Deleting or voiding in the ledger is the accountant's call. Never auto-delete remote records.
+
+## Reconciliation
+
+For each connection, for a date range:
+
+1. Count and sum your invoices, payments and credit notes by currency.
+2. Query the same in the ledger (QuickBooks query endpoint; CDC only looks back 30 days; Xero list endpoints with `where` filters, paging and `If-Modified-Since`).
+3. Match by stored remote ID; list missing-remote, missing-local, and amount or status mismatches.
+4. Retry missing-remote ones idempotently; report the rest to the user. Don't "fix" amounts in the ledger automatically.
+
+## Errors to recognise
+
+| Symptom | Likely cause |
+|---|---|
+| `invalid_grant` on refresh | Refresh token already used (race), revoked, or expired; reconnect |
+| `401` or `403` with a fresh token (Xero) | Missing scope (`401`, `WWW-Authenticate` names `insufficient_scope`), or `xero-tenant-id` missing, wrong or no longer authorised (`403 AuthenticationUnsuccessful`); call `/connections` to check |
+| Duplicate invoices | Retry without idempotency key, or key regenerated per attempt; or the payment provider's own feed also posts |
+| Total differs by a cent | Ledger recomputed tax with its own rounding; send tax explicitly or align rounding rules |
+| Stale object (QuickBooks) | Old `SyncToken`; re-read and retry |
+| `429` | Per-company rate limit; slow the queue for that connection |
+
+## Never
+
+- Never log access or refresh tokens, or webhook verifier keys.
+- Never post to a ledger without a completed account mapping.
+- Never create a record without first checking for an existing remote ID or idempotency key.
+- Never write to a closed period or delete accountant-entered data.
+
+## Report format
+
+```
+Connection: <provider, realm/tenant, scopes>
+Objects synced: <type: direction, trigger>
+Mapping: <complete | gaps listed>
+Idempotency: <how keys are derived>
+Reconciliation <range>: local <count/sum> vs ledger <count/sum>; mismatches <list>
+Needs user/accountant decision: <list>
+```

package/skills/accounting-api-integration/evals/triggers.json

@@ -0,0 +1,17 @@
+{
+  "should_trigger": [
+    "Sync our app's invoices and payments into QuickBooks Online for each customer company that connects",
+    "Our Xero refresh keeps failing with invalid_grant after a few days when two workers run at once",
+    "Build a screen where the accountant maps our product types to their Xero chart of accounts and tax rates",
+    "Retries are creating duplicate invoices in QuickBooks; how do we make the posting idempotent?",
+    "Verify the intuit-signature header on QuickBooks webhooks and fetch the changed invoices",
+    "We hit 429 errors from the Xero API during our nightly backfill of 20,000 invoices"
+  ],
+  "should_not_trigger": [
+    "Set up Stripe webhooks so we fulfil orders when checkout.session.completed arrives",
+    "How should VAT be shown on invoices to EU business customers under reverse charge?",
+    "Design our dunning emails and retry schedule for failed card renewals",
+    "Prepare the month-end close checklist and journal entries for our finance team",
+    "Review our billing code for proration and timezone bugs before release"
+  ]
+}

package/skills/accounting-api-integration/references/quickbooks.md

@@ -0,0 +1,48 @@
+# QuickBooks Online Accounting API
+
+Check developer.intuit.com for current details; Intuit changes OAuth policy and webhook formats from time to time. Facts below were checked against Intuit's docs in October 2026: [OAuth 2.0 setup](https://developer.intuit.com/app/developer/qbo/docs/develop/authentication-and-authorization/oauth-2.0), [minor versions](https://developer.intuit.com/app/developer/qbo/docs/learn/explore-the-quickbooks-online-api/minor-versions), [limits and throttles](https://static.developer.intuit.com/output_html/qbo/docs/learn/limits-and-throttles.html), [change data capture](https://developer.intuit.com/app/developer/qbo/docs/learn/explore-the-quickbooks-online-api/change-data-capture), [configure webhooks](https://developer.intuit.com/app/developer/qbo/docs/develop/webhooks/configure-webhooks) and the [release notes](https://developer.intuit.com/app/developer/qbo/docs/release-notes/general-release-notes).
+
+## OAuth 2.0
+
+- Authorise: `https://appcenter.intuit.com/connect/oauth2` with `client_id`, `response_type=code`, `scope=com.intuit.quickbooks.accounting`, `redirect_uri`, `state`.
+- Token exchange and refresh: `POST https://oauth.platform.intuit.com/oauth2/v1/tokens/bearer` (Basic auth with client ID and secret).
+- The callback receives `code`, `state` and `realmId`. Store `realmId` with the tokens.
+- Access tokens last one hour (`expires_in` starts at 3600). Refresh tokens have a rolling 100-day expiry, the value can change on any refresh, and they now have a maximum lifetime of five years; the token response reports the remaining time in `x_refresh_token_expires_in` and `x_refresh_token_hard_expires_in` (seconds). Always store the refresh token returned by the latest refresh, and plan a reconnect before the hard expiry. The developer portal has a reconnect URL field for when users must re-authorise.
+
+## Base URLs
+
+- Production: `https://quickbooks.api.intuit.com/v3/company/{realmId}/...`
+- Sandbox: `https://sandbox-quickbooks.api.intuit.com/v3/company/{realmId}/...`
+- Send `Accept: application/json`. Support for minor versions 1–74 ended on 1 Aug 2025; a `minorversion` below 75, or none, is answered as minor version 75. Pin `minorversion` explicitly and test before raising it.
+
+## Core entities
+
+| Need | Entity / endpoint |
+|---|---|
+| Accounts | `Account` via `GET /query?query=select * from Account where Active = true` |
+| Products and services | `Item` (each links to an income account) |
+| Tax | `TaxCode`, `TaxRate` (behaviour differs between US and non-US companies) |
+| Customers | `Customer` |
+| Invoices | `POST /invoice` with `CustomerRef`, `Line[]` (`DetailType: SalesItemLineDetail`, `SalesItemLineDetail.ItemRef`, `Amount`), `DocNumber`, `TxnDate`, `CurrencyRef` |
+| Payments | `POST /payment` with `CustomerRef`, `TotalAmt`, `Line[].LinkedTxn[{ TxnId, TxnType: "Invoice" }]`, `DepositToAccountRef` |
+| Credit notes | `CreditMemo`; refunds `RefundReceipt` |
+| Changes since | `GET /cdc?entities=Invoice,Payment&changedSince=<ISO time>` (look-back limited to 30 days; use `/query` for older ranges) |
+| Batch | `POST /batch` with several operations in one request (Intuit's batch page says up to 10 payloads; its limits page recommends at most 30; keep batches small) |
+
+Updates: send `Id` and the current `SyncToken`; add `"sparse": true` to change only the fields you send. A stale `SyncToken` returns a stale object error.
+
+## Idempotency
+
+Add `?requestid=<unique id>` to write requests. A repeat with the same `requestid` for the same company returns the original response instead of creating a duplicate. Use a deterministic ID per logical operation, unique per company. Maximum length is 50 characters (36 for batch requests), so hash long keys. Intuit does not publish how long it remembers a request ID, so also check for the remote record before retrying a create.
+
+## Rate limits
+
+Intuit documents 500 requests per minute per realm ID and 10 requests per second per realm ID and app; batch calls are throttled at 40 per minute per realm ID and app. Requests taking over 120 seconds time out. On `429`, Intuit says to wait 60 seconds before retrying; retry with the same `requestid`.
+
+## Webhooks
+
+- Configure the endpoint and entities in the developer portal; it shows a verifier token per environment.
+- Verify: HMAC-SHA256 of the raw request body keyed with the verifier token, base64-encoded, compared in constant time to the `intuit-signature` header. Reject if the header is missing or the token is unset.
+- Payloads now use the CloudEvents format: a JSON array of events, each with `type` (for example `qbo.invoice.created.v1`), `intuitentityid` and `intuitaccountid` (the realm ID). One notification can carry events for several companies, so route each event by its realm. The legacy format's retirement date moved more than once; check Intuit's current webhook docs if you still receive the old shape.
+- Payloads carry entity types, IDs and operations, not the record. Fetch the entity, or use CDC, to get the data.
+- Respond quickly with `200` and process asynchronously; also run CDC periodically, because webhooks can be missed.

package/skills/accounting-api-integration/references/xero.md

@@ -0,0 +1,45 @@
+# Xero Accounting API
+
+Check developer.xero.com for current details, especially scopes, which changed in 2026. Facts below were checked in October 2026 against Xero's [token types](https://developer.xero.com/documentation/guides/oauth2/token-types/), [scopes](https://developer.xero.com/documentation/guides/oauth2/scopes/), [granular scopes FAQ](https://developer.xero.com/faq/granular-scopes), [limits](https://developer.xero.com/documentation/guides/oauth2/limits/), [idempotency](https://developer.xero.com/documentation/guides/idempotent-requests/idempotency/), [troubleshooting](https://developer.xero.com/documentation/guides/oauth2/troubleshooting/) and [webhooks](https://developer.xero.com/documentation/guides/webhooks/overview/) pages.
+
+## OAuth 2.0
+
+- Authorise: `https://login.xero.com/identity/connect/authorize` with `response_type=code`, `client_id`, `redirect_uri`, `scope`, `state`.
+- Token exchange and refresh: `POST https://identity.xero.com/connect/token`.
+- Include `offline_access` to get a refresh token. Access tokens last up to 30 minutes. Refresh tokens are valid for up to 60 days and rotate on every use; always store the newest one. If you lose the response, the previous refresh token still works for a 30-minute grace period, then the user must re-authorise.
+- After authorising, `GET https://api.xero.com/connections` lists the tenants the user connected. Store each `tenantId`; send it as `xero-tenant-id` on every API call. A user can connect several organisations.
+- **Scopes**: apps created on or after 2 March 2026 use granular scopes (for example `accounting.invoices` instead of the broad `accounting.transactions`). Older apps can request granular scopes from April 2026 and can keep broad scopes until September 2027; existing tokens only gain new scopes when the user re-authorises. Calling an endpoint without the needed scope returns `401` with a `WWW-Authenticate` header naming `insufficient_scope`.
+
+## Base URL
+
+`https://api.xero.com/api.xro/2.0/...` with `Authorization: Bearer <token>`, `xero-tenant-id`, `Accept: application/json`.
+
+## Core endpoints
+
+| Need | Endpoint |
+|---|---|
+| Accounts | `GET /Accounts` (use `Code` or `AccountID`; check `Status` is `ACTIVE`) |
+| Tax rates | `GET /TaxRates` (`TaxType` values go on lines) |
+| Items | `GET/POST /Items` |
+| Contacts | `GET/POST /Contacts` (search by `ContactNumber` or email before creating) |
+| Invoices | `POST /Invoices` (create or update) with `Type: "ACCREC"`, `Contact.ContactID`, `Date`, `DueDate`, `InvoiceNumber`, `LineAmountTypes` (`Exclusive`, `Inclusive`, `NoTax`), `LineItems[]` (`Description`, `Quantity`, `UnitAmount`, `AccountCode`, `TaxType`, optionally `TaxAmount`), `Status` (`DRAFT`, `SUBMITTED`, `AUTHORISED`), `CurrencyCode` |
+| Payments | `PUT /Payments` with `Invoice.InvoiceID`, `Account.Code` or `AccountID` (a bank account or one with payments enabled), `Amount`, `Date` |
+| Credit notes | `POST /CreditNotes` with `Type: "ACCRECCREDIT"`; allocate to an invoice with `PUT /CreditNotes/{id}/Allocations` |
+| Changes since | `If-Modified-Since` header on list endpoints, plus `where` filters and paging |
+
+Send several records in one request where the endpoint accepts an array; add `?SummarizeErrors=false` to get a status and validation errors per record instead of failing the whole batch. List endpoints page with `?page=` and `pageSize` (default 100, maximum 1000). Some changes (for example `DueDate` or `SentToContact` on paid transactions) don't update `UpdatedDateUTC`, so `If-Modified-Since` can miss them.
+
+## Idempotency
+
+Send an `Idempotency-Key` header (at most 128 characters) on `POST`, `PUT` and `PATCH`; other methods ignore it. Use a deterministic key per logical operation and keep it for retries. Xero keeps keys for only 6 minutes, and reusing a key with a different request returns `400`, so for retries after that window rely on the stored remote ID check, not the key.
+
+## Rate limits
+
+Per tenant: 5 concurrent calls, 60 calls per minute, and a daily limit of 1,000 calls on the starter tier or 5,000 on higher tiers; plus an app-wide limit of 10,000 calls per minute across all tenants. Responses include `X-DayLimit-Remaining`, `X-MinLimit-Remaining` and `X-AppMinLimit-Remaining`. A `429` carries `X-Rate-Limit-Problem` naming the limit hit, and `Retry-After` (seconds) when the minute or daily limit was exceeded.
+
+## Webhooks
+
+- Configure in the developer portal; it gives a webhook key.
+- Verify: HMAC-SHA256 of the raw request body keyed with the webhook key, base64-encoded, compared in constant time to the `x-xero-signature` header. Return a `2xx` for a valid signature and `401` for an invalid one, over HTTPS on port 443, within 5 seconds, with no cookies in the response.
+- "Intent to receive": when you set up the endpoint, Xero sends test requests, some with bad signatures, and only activates the webhook if you answer correctly. Process events asynchronously. Xero retries failed deliveries and disables the webhook after 24 hours of failures.
+- Events carry `resourceId`, `eventCategory` (for example `INVOICE`, `CONTACT`), `eventType` and `tenantId`. Fetch the resource by ID; don't trust the payload as data.

package/skills/agent-failure-debugging/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: agent-failure-debugging
+description: Post-mortem for a single failed or poor LLM agent run, reading its transcript, tool-call log or trace to find the first step where it went wrong, sorting the cause into a fixed taxonomy (tool loop, tool error mishandled, context lost or overflowed, ambiguous or conflicting instructions, wrong tool chosen, missing tool or permission, model limit), then changing the prompt, tool definitions or harness and re-running the same task to prove the fix. Use when an agent got stuck repeating itself, ignored an instruction, gave up early, edited the wrong files, hallucinated a tool result, or produced a bad answer and someone has the session log and wants to know why.
+license: MIT
+compatibility: Any Agent Skills host. Needs read access to the run's transcript, JSONL session log or trace export, and a way to re-run the agent on the same task.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: ai
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Agent failure debugging
+
+Debug one bad run the way you would debug a crash: get the evidence, find the first wrong step, name the cause, change one thing, re-run, compare.
+
+Scope: one run (or a handful of runs of the same task). To score many outputs against a rubric, use `llm-evals` or the `agent-evaluator` agent. To redesign the harness from scratch, use `agent-harness-design`. To rewrite a prompt in general, use `prompt-engineering`.
+
+## 1. Collect the evidence
+
+Ask for, or find, all of:
+
+- The task as given: the user prompt and any files or links it named.
+- The full transcript or log: every model turn, every tool call with its arguments, every tool result, and any errors from the harness. Session logs are usually JSONL (one event per line).
+- The system prompt, instruction files (`AGENTS.md`, `CLAUDE.md` and similar), loaded skills, and the tool definitions as the model saw them.
+- The model and settings: model name, temperature or effort, context window, max turns, timeouts.
+- What "good" would have looked like: the expected result in one or two sentences.
+
+If the transcript is missing or truncated, stop and say so. Do not reconstruct a run from memory or from the final answer alone.
+
+Large logs: don't read them whole. Extract a compact timeline first (turn number, role, tool name, first 200 characters of arguments and result, token count if logged), then read in full only the turns around the failure. `context-budget` covers techniques for huge files.
+
+## 2. Find the first wrong step
+
+Walk the timeline from the start and mark:
+
+1. The last step where the agent was clearly on track.
+2. The first step that was wrong: a wrong tool, wrong arguments, a misread result, a skipped instruction, or a false claim.
+3. What the agent had in view at that moment: was the needed fact in the context, already compacted away, or never provided?
+
+The first wrong step, not the final symptom, is what you fix. A run that ends in a loop often went wrong five turns earlier when a tool error was misread.
+
+## 3. Classify the failure
+
+Pick one primary cause (and at most one contributing cause):
+
+| Cause | Signs in the log | Usual fix |
+|---|---|---|
+| **Loop** | Same tool and near-identical arguments 3+ times, no new information gained | Return clearer tool results; add a repeat detector or turn cap in the harness; tell the agent what to do when stuck |
+| **Tool error mishandled** | Error result ignored, misread as success, or retried unchanged | Make errors explicit and actionable (`isError`, what to change); instruct "on error, read it and change the call or stop" |
+| **Context lost** | Agent forgets an earlier decision or file after compaction or truncation; re-reads the same file | Keep key facts in a notes file or pinned summary; compact earlier and keep decisions; split the task |
+| **Context overflow** | Huge tool output (logs, lockfiles, minified code) right before quality drops; window near its limit | Cap and paginate tool output; search instead of dumping; delegate bulky reads to a subagent |
+| **Ambiguous instructions** | Two reasonable readings; agent picked the other one; instruction files contradict each other or the user | Rewrite the instruction with a concrete example; remove the contradiction; say which source wins |
+| **Wrong tool** | A tool that exists and fits was skipped for a worse one (shell `cat` instead of a read tool, guessing instead of searching) | Sharpen tool names and descriptions so the right one is obvious; remove overlapping tools |
+| **Missing tool or permission** | Agent improvises around a denied or absent capability, or hallucinates a result | Grant the narrow capability, or tell the agent to stop and ask when it is missing |
+| **Premature stop** | Agent declares done without running the check the task required | Add an explicit completion check; harness verifies before accepting "done" |
+| **Hallucinated result** | Claims a file, test pass or API field that the log shows never existed | Require evidence (command output, path:line) in the answer; verify in the harness |
+| **Model limit** | Task needs reasoning or knowledge the model lacks even with perfect inputs | Break the task down, give examples, or use a more capable model |
+
+If nothing fits, write a one-line new category rather than forcing one.
+
+## 4. Fix one thing
+
+1. State a hypothesis: "The run failed at turn N because X; changing Y will make it succeed."
+2. Make the smallest change in the right layer: prompt or instruction file, tool definition or result format, or harness (caps, compaction, retries, permissions).
+3. Change one thing at a time so the re-run tells you something.
+4. Show the user the diff before editing a shared system prompt, instruction file or tool schema.
+
+Never "fix" a run by adding instructions that hard-code the answer to this one task.
+
+## 5. Re-run and confirm
+
+1. Re-run the same task with the same inputs and model settings, changing only the fix.
+2. Agents are not deterministic: run it 3 times if cost allows (more for a flaky failure) and count successes before and after.
+3. Compare timelines: the failing step should now go right, and no new failure should appear later.
+4. Re-run one or two other tasks that the change could affect, so the fix doesn't break something else.
+5. If the failure persists after two hypotheses, stop and report what you tried; the cause may be in an area you don't control (provider outage, model limit).
+
+Stop and ask the user before re-running anything that writes outside a scratch area, costs real money, sends messages or touches production.
+
+## Report
+
+```
+## Agent run diagnosis: <task, run id or log path>
+Expected: <one line>
+Got: <one line>
+First wrong step: turn <N> — <what happened> (evidence: <quoted log excerpt, under 3 lines>)
+Cause: <category> (contributing: <category or none>)
+Fix: <layer: prompt | tools | harness> — <change, with diff or file:line>
+Re-run: <k>/<n> succeeded before, <k>/<n> after; side checks: <tasks re-run and result>
+Remaining risk: <what this fix does not cover>
+```

package/skills/agent-failure-debugging/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Here's the JSONL log of our coding agent's run. It called grep 30 times in a row and never finished. Why?",
+    "The agent ignored the rule in AGENTS.md about not touching migrations. Figure out from the transcript what went wrong",
+    "Our support bot made up an order status that the lookup tool never returned. Diagnose this session and fix it",
+    "After context compaction the agent forgot which files it had already changed and redid them. Here's the trace",
+    "Why did the agent stop and say done without running the tests? I attached the session transcript"
+  ],
+  "should_not_trigger": [
+    "Grade these 200 agent transcripts against our rubric and tell me the overall pass rate",
+    "Design the context compaction and tool permissions for the new agent harness we're building",
+    "My Python service crashes with a KeyError in production, here is the stack trace",
+    "Write a blameless postmortem for last week's database outage",
+    "Summarise how many tokens and dollars my agent sessions used this week"
+  ]
+}