@myapihq/cli 2.20.1 → 2.21.1

package/dist/commands/audience.js

@@ -2,6 +2,11 @@ import { audience as sdkAudience } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { success, error, printTable, info, printJson } from '../output.js';
 import { requireOrg, requireArg } from '../helpers.js';
+import { retryFunds } from '../utils.js';
+// Billable: the backend reserves funds before serving these, so an empty
+// wallet with an auto-recharge in flight answers 402 in_flight with a
+// retry hint. retryFunds waits it out instead of killing an unattended
+// run. Only create/update/members/refresh gate — list, get and delete are free and stay unwrapped.
 export const EXPOSES = [
     'POST /audience/orgs/{org_id}/audiences',
     'GET /audience/orgs/{org_id}/audiences',
@@ -59,9 +64,9 @@ async function create(nameArg, flags) {
     }
     const filter = parseFilter(flags.filter);
     const description = typeof flags.description === 'string' ? flags.description : undefined;
-    const res = await sdkAudience.createAudience(config.api_key, orgId, {
+    const res = await retryFunds(() => sdkAudience.createAudience(config.api_key, orgId, {
         name, source: source, filter, description,
-    });
+    }));
     if (flags.json) {
         printJson(res);
         return;
@@ -102,7 +107,7 @@ async function update(id, flags) {
     if (Object.keys(patch).length === 0) {
         error('Pass at least one of --name / --description / --filter to update.');
     }
-    const res = await sdkAudience.updateAudience(config.api_key, orgId, id, patch);
+    const res = await retryFunds(() => sdkAudience.updateAudience(config.api_key, orgId, id, patch));
     if (flags.json) {
         printJson(res);
         return;
@@ -125,7 +130,7 @@ async function members(id, flags) {
         opts.limit = flags.limit;
     if (typeof flags.offset === 'number')
         opts.offset = flags.offset;
-    const res = await sdkAudience.getAudienceMembers(config.api_key, orgId, id, opts);
+    const res = await retryFunds(() => sdkAudience.getAudienceMembers(config.api_key, orgId, id, opts));
     if (flags.json) {
         printJson(res);
         return;
@@ -161,7 +166,7 @@ async function refresh(id, flags) {
     const config = requireConfig();
     const orgId = requireOrg(flags, config, 'myapi audience refresh <id> [--org <id>]');
     requireArg(id, 'id', 'myapi audience refresh <id> [--org <id>]');
-    const res = await sdkAudience.refreshAudience(config.api_key, orgId, id);
+    const res = await retryFunds(() => sdkAudience.refreshAudience(config.api_key, orgId, id));
     if (flags.json) {
         printJson(res);
         return;

package/dist/commands/company.js

@@ -2,6 +2,11 @@ import { company as sdkCompany } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { error, printTable, info, printJson } from '../output.js';
 import { requireOrg, requireArg } from '../helpers.js';
+import { retryFunds } from '../utils.js';
+// Billable: the backend reserves funds before serving these, so an empty
+// wallet with an auto-recharge in flight answers 402 in_flight with a
+// retry hint. retryFunds waits it out instead of killing an unattended
+// run. Both handlers gate; there is no free company call.
 export const EXPOSES = [
     'POST /company/orgs/{org_id}/search',
     'GET /company/orgs/{org_id}/{company_id}',
@@ -72,7 +77,7 @@ async function search(flags) {
     const config = requireConfig();
     const orgId = requireOrg(flags, config, 'myapi company search [filters...] [--org <id>]');
     const options = buildSearch(flags);
-    const res = await sdkCompany.searchCompanies(config.api_key, orgId, options);
+    const res = await retryFunds(() => sdkCompany.searchCompanies(config.api_key, orgId, options));
     if (flags.json) {
         printJson(res);
         return;
@@ -94,7 +99,7 @@ async function get(companyId, flags) {
     const orgId = requireOrg(flags, config, 'myapi company get <company_id> [--include-people N] [--org <id>]');
     requireArg(companyId, 'company_id', 'myapi company get <company_id> [--include-people N] [--org <id>]');
     const includePeople = typeof flags['include-people'] === 'number' ? flags['include-people'] : undefined;
-    const res = await sdkCompany.getCompany(config.api_key, orgId, companyId, includePeople);
+    const res = await retryFunds(() => sdkCompany.getCompany(config.api_key, orgId, companyId, includePeople));
     printJson(res);
 }
 export const SUBCOMMAND_USAGE = {

package/dist/commands/llm.d.ts

@@ -5,4 +5,5 @@ export declare const EXPOSES: Exposes;
 export declare const SCHEMA: FlagSchema;
 export declare function _parseJsonObjectFlag(raw: unknown, flagName: string): Record<string, unknown> | undefined;
 export declare const SUBCOMMAND_USAGE: Record<string, string>;
+export declare const NESTED_SUBCOMMAND_USAGE: Record<string, Record<string, string>>;
 export declare function run(subcommand: string | undefined, args: string[], flags: Flags): Promise<void>;

package/dist/commands/llm.js

@@ -2,13 +2,16 @@ import * as fs from 'fs';
 import { llm as sdkLlm } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { error, info, printTable, printJson } from '../output.js';
-import { requireOrg } from '../helpers.js';
+import { requireOrg, requireArg } from '../helpers.js';
 import { retryFunds } from '../utils.js';
 export const EXPOSES = [
     'POST /llm/orgs/{org_id}/complete',
     'POST /llm/orgs/{org_id}/embed',
     'GET /llm/orgs/{org_id}/models',
     'POST /llm/orgs/{org_id}/tasks/{verb}',
+    'POST /llm/orgs/{org_id}/caches',
+    'GET /llm/orgs/{org_id}/caches',
+    'DELETE /llm/orgs/{org_id}/caches/{id}',
 ];
 export const SCHEMA = {
     org: 'string',
@@ -30,6 +33,10 @@ export const SCHEMA = {
     context: 'string',
     prompt: 'string',
     tier: 'string',
+    // context caches
+    cache: 'string',
+    ttl: 'number',
+    yes: 'boolean',
 };
 // Cache the catalog once per CLI invocation so verbs (which don't take a
 // --model flag) can fall back to "the first chat model" without an extra
@@ -161,6 +168,7 @@ async function complete(promptArg, flags) {
     const res = await retryFunds(() => sdkLlm.complete(config.api_key, orgId, {
         model,
         messages,
+        cache_id: typeof flags.cache === 'string' && flags.cache ? flags.cache : undefined,
         max_tokens: typeof flags['max-tokens'] === 'number' ? flags['max-tokens'] : undefined,
         temperature: typeof flags.temperature === 'number' ? flags.temperature : undefined,
         stop,
@@ -171,7 +179,12 @@ async function complete(promptArg, flags) {
     }
     info(res.content);
     // Usage footer on stderr so it doesn't pollute piped output.
-    process.stderr.write(`\n— ${res.model} · ${res.usage.input_tokens}+${res.usage.output_tokens ?? 0} tokens · ${fmtCostCents(res.usage.cost_cents)} · ${res.finish_reason}\n`);
+    // Cached tokens are shown as "N of M cached", never added to the input
+    // count: `cached_input_tokens` is a SUBSET of `input_tokens`, and a footer
+    // that summed them would report more tokens than were sent.
+    const cached = res.usage.cached_input_tokens ?? 0;
+    const cachedNote = cached > 0 ? ` (${cached} cached)` : '';
+    process.stderr.write(`\n— ${res.model} · ${res.usage.input_tokens}${cachedNote}+${res.usage.output_tokens ?? 0} tokens · ${fmtCostCents(res.usage.cost_cents)} · ${res.finish_reason}\n`);
 }
 async function embed(inputArg, flags) {
     const config = requireConfig();
@@ -209,6 +222,81 @@ async function listModels(flags) {
         'out ¢/1M': m.output_cost_per_1m_cents != null ? m.output_cost_per_1m_cents : '',
     })), { flags, empty: 'No models available.' });
 }
+// ── context caches ────────────────────────────────────────────────────────
+// A cache bills for EXISTING, not for being read: storage accrues per hour
+// from the moment it is created. That is why this surface is explicit and why
+// `delete` is documented as the way to stop paying — the alternative, waiting
+// out the TTL, means paying the TTL in full.
+const CACHE_HELP = `Usage: myapi llm cache <create|list|delete>
+
+  create   Store a prompt prefix (--file <path>, --model <id>, [--ttl <secs>])
+  list     Live caches with size, expiry, and what they cost to hold
+  delete   Delete a cache and stop paying for it
+
+A cache costs a TENTH to re-read: pass it to complete with --cache <id>.
+It is bound to ONE model — a cache made for one model cannot be read by
+another. Storage is billed per hour whether or not anybody reads it, so
+delete one you are done with rather than waiting out its TTL.`;
+async function cacheCreate(flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi llm cache create --file <path> [--model <id>] [--ttl <seconds>] [--org <id>]');
+    const content = readPromptArg(undefined, flags);
+    if (!content.trim()) {
+        error('Empty content. Pass --file <path> (the content is long by definition — that is the reason to cache it).');
+    }
+    const model = typeof flags.model === 'string' && flags.model
+        ? flags.model
+        : await defaultChatModel(config.api_key, orgId);
+    const ttl = typeof flags.ttl === 'number' ? flags.ttl : undefined;
+    const res = await retryFunds(() => sdkLlm.createCache(config.api_key, orgId, {
+        model,
+        content,
+        ttl_seconds: ttl,
+    }));
+    if (flags.json) {
+        printJson(res);
+        return;
+    }
+    info(`Cached ${res.tokens} tokens for ${res.model} → ${res.id}`);
+    info(`Expires ${res.expires_at}. Read it with: myapi llm complete --model ${res.model} --cache ${res.id} "..."`);
+    // Said on create because this is the moment the meter starts, and the
+    // request's own --ttl is not what was necessarily granted.
+    info(`Billed per hour until then whether or not you read it — "myapi llm cache delete ${res.id}" stops the charge.`);
+}
+async function cacheList(flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi llm cache list [--org <id>]');
+    const res = await sdkLlm.listCaches(config.api_key, orgId);
+    if (flags.json) {
+        printJson(res);
+        return;
+    }
+    printTable(res.caches.map(c => ({
+        id: c.id,
+        model: c.model,
+        tokens: c.tokens,
+        expires_at: c.expires_at,
+    })), { flags, empty: 'No live caches. (Expired ones are not listed — and are no longer billed.)' });
+}
+async function cacheDelete(args, flags) {
+    const config = requireConfig();
+    const orgId = requireOrg(flags, config, 'myapi llm cache delete <id> [--org <id>]');
+    const id = requireArg(args[0], '<id>', 'myapi llm cache delete <id>');
+    await sdkLlm.deleteCache(config.api_key, orgId, id);
+    info(`Deleted ${id}. Storage for it is no longer billed.`);
+}
+async function cacheRun(sub, args, flags) {
+    if (!sub || flags.help) {
+        info(CACHE_HELP);
+        return;
+    }
+    switch (sub) {
+        case 'create': return cacheCreate(flags);
+        case 'list': return cacheList(flags);
+        case 'delete': return cacheDelete(args, flags);
+        default: error(`Unknown subcommand: llm cache ${sub}. Run "myapi llm cache --help" for the list.`);
+    }
+}
 // ── verbs ────────────────────────────────────────────────────────────────
 function printVerbFooter(usage) {
     process.stderr.write(`\n— tier=${usage.tier_used} · ${usage.tokens_in}+${usage.tokens_out} tokens · ${fmtCostCents(usage.cost_cents)}\n`);
@@ -315,7 +403,7 @@ async function draft(inputArg, flags) {
 }
 // ── help ─────────────────────────────────────────────────────────────────
 export const SUBCOMMAND_USAGE = {
-    complete: `myapi llm complete "<prompt>" [--model <id>]
+    complete: `myapi llm complete "<prompt>" [--model <id>] [--cache <id>]
        [--system "<system msg>"] [--max-tokens N] [--temperature 0..1]
        [--stop <csv>] [--file <path>] [--org <id>] [--json]
 
@@ -326,9 +414,31 @@ export const SUBCOMMAND_USAGE = {
   one-line usage footer (tokens + cost in cents) goes to stderr so it
   doesn't pollute piped output.
 
+  --cache <id> re-reads a stored prefix at a TENTH the input price; make one
+  with "myapi llm cache create". The cache must belong to the same model.
+
   Examples:
     myapi llm complete "summarize: $(cat README.md)"
-    cat draft.md | myapi llm complete - --system "You are an editor" --max-tokens 200`,
+    cat draft.md | myapi llm complete - --system "You are an editor" --max-tokens 200
+    myapi llm complete "what changed?" --model myapi-fast --cache cch_...`,
+    cache: `myapi llm cache <create|list|delete>
+
+  create   myapi llm cache create --file <path> [--model <id>] [--ttl <secs>]
+  list     myapi llm cache list
+  delete   myapi llm cache delete <id>
+
+  Store a prompt prefix once and re-read it at a TENTH the input price. Worth
+  it for anything long you send on every call — a system prompt, a reference
+  document, a schema.
+
+  Two things that cost money if you skip them:
+  - A cache bills for EXISTING, not for being read. Storage accrues per hour
+    from creation whether or not anybody reads it. "cache delete" is how you
+    stop paying; waiting out the TTL means paying the whole TTL.
+  - --ttl is capped at 24h. A longer request is silently shortened, not
+    refused, so read expires_at from the reply rather than trusting your input.
+
+  A cache belongs to ONE model and cannot be read by another.`,
     embed: `myapi llm embed "<text>" [--model <id>] [--file <path>] [--org <id>] [--json]
 
   Embed text into a dense vector. --model is optional when the catalog serves
@@ -381,6 +491,13 @@ export const SUBCOMMAND_USAGE = {
       --context '{"recipient":"a new signup","product":"MyAPI"}'
     cat inbound.eml | myapi llm draft - --kind reply --prompt "Acknowledge and ask for the order ID"`,
 };
+export const NESTED_SUBCOMMAND_USAGE = {
+    cache: {
+        'create': 'myapi llm cache create --file <path> [--model <id>] [--ttl <seconds>] [--org <id>] [--json]',
+        'list': 'myapi llm cache list [--org <id>] [--json]',
+        'delete': 'myapi llm cache delete <id> [--org <id>]',
+    },
+};
 export async function run(subcommand, args, flags) {
     if (!subcommand || (flags.help && !subcommand)) {
         info(`Usage: myapi llm <subcommand>
@@ -392,6 +509,7 @@ Two surfaces:
           is never named in the response.
 
 Subcommands:
+  cache       Store a prompt prefix; re-read it at a tenth the input price
   classify    Pick a label from a set
   complete    Raw chat completion against a catalog model
   draft       Write something (email | reply | message | …)
@@ -421,6 +539,7 @@ for your own reasoning. The agent has its own model already.`);
         case 'extract': return extract(args[0], flags);
         case 'summarize': return summarize(args[0], flags);
         case 'draft': return draft(args[0], flags);
+        case 'cache': return cacheRun(args[0], args.slice(1), flags);
         default: error(`Unknown subcommand: ${subcommand}. Run "myapi llm --help" for valid subcommands.`);
     }
 }

package/dist/commands/people.js

@@ -2,6 +2,11 @@ import { people as sdkPeople } from '@myapihq/sdk';
 import { requireConfig } from '../config.js';
 import { error, printTable, info, printJson } from '../output.js';
 import { requireOrg, requireArg } from '../helpers.js';
+import { retryFunds } from '../utils.js';
+// Billable: the backend reserves funds before serving these, so an empty
+// wallet with an auto-recharge in flight answers 402 in_flight with a
+// retry hint. retryFunds waits it out instead of killing an unattended
+// run. Both handlers gate; there is no free people call.
 export const EXPOSES = [
     'POST /people/orgs/{org_id}/search',
     'GET /people/orgs/{org_id}/{person_id}',
@@ -61,7 +66,7 @@ async function search(flags) {
     const config = requireConfig();
     const orgId = requireOrg(flags, config, 'myapi people search [filters...] [--org <id>]');
     const filter = buildFilter(flags);
-    const res = await sdkPeople.searchPeople(config.api_key, orgId, filter);
+    const res = await retryFunds(() => sdkPeople.searchPeople(config.api_key, orgId, filter));
     if (flags.json) {
         printJson(res);
         return;
@@ -80,7 +85,7 @@ async function get(personId, flags) {
     const config = requireConfig();
     const orgId = requireOrg(flags, config, 'myapi people get <person_id> [--org <id>]');
     requireArg(personId, 'person_id', 'myapi people get <person_id> [--org <id>]');
-    const res = await sdkPeople.getPerson(config.api_key, orgId, personId);
+    const res = await retryFunds(() => sdkPeople.getPerson(config.api_key, orgId, personId));
     printJson(res);
 }
 export const SUBCOMMAND_USAGE = {

package/dist/completion.js

@@ -51,7 +51,7 @@ export const SUBCOMMANDS = {
     people: ['search', 'get'],
     company: ['search', 'get'],
     audience: ['create', 'list', 'get', 'update', 'delete', 'members', 'refresh'],
-    llm: ['complete', 'embed', 'models', 'classify', 'extract', 'summarize', 'draft'],
+    llm: ['complete', 'embed', 'models', 'classify', 'extract', 'summarize', 'draft', 'cache'],
     database: ['namespaces', 'create', 'delete-namespace', 'keys', 'get', 'set', 'del'],
     crm: ['contacts', 'companies'],
     url: ['shorten'],

package/dist/flags.d.ts

@@ -5,4 +5,4 @@ export interface ParsedArgs {
     args: string[];
     flags: Record<string, string | boolean | number>;
 }
-export declare function parseFlags(argv: string[], schema?: FlagSchema): ParsedArgs;
+export declare function parseFlags(argv: string[], schema?: FlagSchema, quiet?: boolean): ParsedArgs;

package/dist/flags.js

@@ -12,7 +12,11 @@ export const GLOBAL_FLAGS = {
     yes: 'boolean',
     y: 'boolean',
 };
-export function parseFlags(argv, schema = {}) {
+// `quiet` suppresses the unknown-flag note. The dispatcher parses twice — once
+// to learn the command, once under that command's own schema — and only the
+// second pass knows which flags are genuinely foreign, so the first must stay
+// silent or every typo would be reported twice.
+export function parseFlags(argv, schema = {}, quiet = false) {
     const merged = { ...GLOBAL_FLAGS, ...schema };
     const args = [];
     const flags = {};
@@ -126,7 +130,7 @@ export function parseFlags(argv, schema = {}) {
     // Surface unknown flags so typos and hallucinated flags don't silently
     // disappear. Don't block — the value is still in `flags` for any handler
     // that wants it — just print one line on stderr.
-    if (unknownFlags.length > 0 && !process.env.MYAPI_QUIET_UNKNOWN_FLAGS) {
+    if (unknownFlags.length > 0 && !quiet && !process.env.MYAPI_QUIET_UNKNOWN_FLAGS) {
         process.stderr.write(`› Note: unknown flag(s) not recognized by this command: ${unknownFlags.join(', ')} — check for typos.\n`);
     }
     return { args, flags };

package/dist/index.js

@@ -158,7 +158,23 @@ async function main() {
         handleCompletionRequest(); // computes candidates / emits the script, then exits
         return;
     }
-    const { args, flags } = parseFlags(process.argv.slice(2), COMBINED_SCHEMA);
+    // Two passes. The first only has to find the command, because the schema
+    // that types the flags depends on it: COMBINED_SCHEMA is a merge, and a
+    // merge silently resolves collisions by declaration order. `ttl` is declared
+    // `number` by domain and llm and `string` by storage, and because storage
+    // merges last EVERY --ttl in the CLI was parsed as a string — so
+    // `domain records create --ttl 3600` sent "3600" and `llm cache create
+    // --ttl 600` dropped the value entirely on a `typeof === 'number'` check.
+    //
+    // Re-parsing under the command's own schema makes each command's declared
+    // types authoritative, which is what every command already assumes, and what
+    // warnForeignFlags already assumes when it decides a flag is foreign.
+    const first = parseFlags(process.argv.slice(2), COMBINED_SCHEMA, /* quiet */ true);
+    const commandName = first.args[0];
+    const ownSchema = commandName ? COMMAND_SCHEMAS[commandName] : undefined;
+    // The second pass is the one that speaks: it knows the command, so it is the
+    // only one that can tell a foreign flag from a flag another command declares.
+    const { args, flags } = parseFlags(process.argv.slice(2), ownSchema ?? COMBINED_SCHEMA);
     warnForeignFlags(args[0], flags);
     if (flags.version || flags.v || flags.V) {
         // Read the last-known published version from cache — no network call, so

package/dist/skills/my-api-hq/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: my-api-hq
-version: 1.2.1
+version: 1.2.2
 description: >
   Auth, organizations, and billing hub. Start here to get an api_key and org_id — every other service depends on both.
 triggers: [api key, account, organization, org, billing, balance, topup, credits, setup, defaults, brand, sync brand, doctor, health check, is my org healthy]
-checksum: sha256-b4eef3d505e92f2b9fe8dfa45b74d4221e3c646947ebfe8961aa5a2445bfa139
+checksum: sha256-e7f0a16a130603ca5664cf5c268658bffd85230fe89dc82a4fda715ff81135b8
 ---
 
 # MyApiHQ
@@ -13,7 +13,7 @@ The root service. It manages accounts, API keys, organizations, and billing. No
 
 ## Capabilities
 <!-- llm:start -->
-MyApiHQ is the platform's foundation. Every other service (domain, funnel, auth, payments, fn, workflow, database, storage, email, webhook, crm, llm, image, pixel, url) requires both an `api_key` and (for org-scoped resources) an `org_id` minted here. Setup is one command — `myapi account setup` — which provisions an account, generates an api_key, creates a default org, and stores everything in `~/.myapi/config.json`. Subsequent commands pick up those defaults automatically.
+MyApiHQ is the platform's foundation. Every other service requires both an `api_key` and (for org-scoped resources) an `org_id` minted here. Setup is one command — `myapi account setup` — which provisions an account, generates an api_key, creates a default org, and stores everything in `~/.myapi/config.json`. Subsequent commands pick up those defaults automatically.
 
 ### Anonymous vs registered accounts
 
@@ -153,6 +153,7 @@ reply  { "success": true, "data": …, "error": null, "meta": {…} }
 
 - **Per-slot host** — do not assume one host serves every slot.
 - **Org id goes in the PATH** — there is no `X-Org-Id` header.
+- **Lists page** — one page is not the whole list; check `meta.has_more`.
 <!-- http:end -->
 
 Run `myapi --help` or `myapi <command> --help` for full flag reference.

package/dist/skills/my-auth-api/SKILL.md

@@ -4,7 +4,7 @@ version: 1.1.1
 description: >
   Add authentication to apps you build on MyAPI — a managed OIDC identity provider for your app's END USERS (à la Kinde/Auth0). One auth tenant per org; register OIDC clients; sign users in with managed Google or the hosted login page; verify RS256 tokens against the tenant JWKS.
 triggers: [auth, authentication, login, sign-in, oidc, oauth, jwt, jwks, sso, google sign-in, user accounts, identity provider, kinde, auth0, clerk]
-checksum: sha256-ef6a4a0c3b6199fe0335d38b51306301f64bc6e293770700daef625f0deacd33
+checksum: sha256-92ed5cff8e8cd5bed3f59564b3ebb6a66eb572f0914de28322fbda1b8b6ae943
 ---
 
 # MyAuthAPI
@@ -142,4 +142,5 @@ reply  { "success": true, "data": …, "error": null, "meta": {…} }
 
 - **Per-slot host** — do not assume one host serves every slot.
 - **Org id goes in the PATH** — there is no `X-Org-Id` header.
+- **Lists page** — one page is not the whole list; check `meta.has_more`.
 <!-- http:end -->

package/dist/skills/my-container-api/SKILL.md

@@ -1,15 +1,15 @@
 ---
 name: my-container-api
-version: 1.1.0
+version: 1.1.1
 description: >
   Run containers on demand — long-running services, background workers, and scheduled jobs. The heavier-duty sibling of edge functions, for native deps and long execution.
 triggers: [container, cloud run, dynamic app, custom domain app, service, worker, scheduled job, deploy container, docker image]
-checksum: sha256-0a83428114cbc7065d1a4db4f8a0cf39ff965c51acac78f5eeff159345a08da2
+checksum: sha256-80d64f6086e3d16549e530464b8188d9b9db2db5b54696e85c9ddde60d5b40a0
 ---
 
 # MyContainerAPI
 
-A container runs a pre-built image on managed cloud infrastructure. Three types: a **service** (HTTP server, scales to zero), a **worker** (always-on background process), or a **job** (runs to completion — the only type that takes a cron schedule).
+A container runs a pre-built image on managed cloud infrastructure. Three types: a **service** (HTTP server, scales to zero), a **worker** (always-on process), or a **job** (runs to completion — the only type that takes a cron schedule).
 
 ## Capabilities
 <!-- llm:start -->
@@ -55,8 +55,6 @@ it, so the probe would never reach your container.
 
 `myapi container domain <id> <domain>` binds a custom domain to a **deployed** container, over HTTPS automatically. The path for a dynamic backend on a real domain — unlike `my-funnel-api`, which serves static sites.
 
-Get it right:
-
 - **Deploy first.** Binding a domain to a container that has never deployed fails (422) — there is nothing running to route to.
 - **Register the parent domain first** via `my-domain-api`. Binding `app.synthesisdaily.com` requires `synthesisdaily.com` registered in MyAPI; otherwise 422.
 - **One domain per container.** Re-binding, or binding a hostname already taken, fails (409).
@@ -168,6 +166,7 @@ reply  { "success": true, "data": …, "error": null, "meta": {…} }
 
 - **Per-slot host** — do not assume one host serves every slot.
 - **Org id goes in the PATH** — there is no `X-Org-Id` header.
+- **Lists page** — one page is not the whole list; check `meta.has_more`.
 <!-- http:end -->
 
 Run `myapi container --help` for the full flag reference.

package/dist/skills/my-crm-api/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: my-crm-api
-version: 1.0.1
+version: 1.0.2
 description: >
   The canonical store of engaged contacts + companies for an org. Auto-ingests from inbound webhooks via a configurable dot-path. Fixed lifecycle_stage enum (cold | warm | qualified | customer | churned). Append-only event timeline with reserved kinds. Soft delete + restore. Promote-from-Goldfox closes the discovery → engagement loop.
 triggers: [crm, contact, company, lead, engagement, pipeline, lifecycle, qualified, customer, webhook ingest, promote]
-checksum: sha256-285ad94b1266588d103119ec139f11f0d19831bcbfd12779130f9fbeaf7f33f5
+checksum: sha256-ac33bd091d64089bf1d43b20431eff5361e018406bb5046f3c27fd628f7082fb
 ---
 
 # MyCRMAPI
@@ -63,7 +63,7 @@ Coming next (backend wiring in progress):
 
 If a contact doesn't exist for the matched email, it's auto-created with `source=` matching the originating service. The contact's company is auto-linked by email domain (creates the company on first sight).
 
-**Missing lead? Check `myapi webhook deliveries` before concluding it never arrived.** A deadlock under concurrent ingest could drop the contact *after* the form returned success (fixed 2026-07-27). Raw payloads are always stored, so the delivery is there even when the contact isn't.
+**Missing lead? Check `myapi webhook deliveries` before concluding it never arrived.** Raw payloads are always stored, so the delivery is there even when the contact isn't.
 
 ### Soft delete + restore
 
@@ -71,7 +71,7 @@ If a contact doesn't exist for the matched email, it's auto-created with `source
 
 ### Goldfox enrichment (deferred)
 
-A contact promoted from Goldfox carries a `goldfox_person_id`. In v2 the GET response will embed the row as `goldfox_person`; today it is null. Goldfox-only fields are not yet searchable.
+A contact promoted from Goldfox carries a `goldfox_person_id`; the embedded `goldfox_person` is null today, and Goldfox-only fields are not searchable.
 
 ### Search filter — re-engagement semantics
 
@@ -180,6 +180,7 @@ reply  { "success": true, "data": …, "error": null, "meta": {…} }
 
 - **Per-slot host** — do not assume one host serves every slot.
 - **Org id goes in the PATH** — there is no `X-Org-Id` header.
+- **Lists page** — one page is not the whole list; check `meta.has_more`.
 <!-- http:end -->
 
 Run `myapi crm --help` or `myapi crm <namespace> --help` for inline reference.

package/dist/skills/my-database-api/SKILL.md

@@ -4,7 +4,7 @@ version: 1.0.0
 description: >
   Per-org KV store with named namespaces, JSON values up to 256 KB, prefix-scan listing, and compare-and-swap via etag. The substrate for any stateful agent-built app on MyAPI — user tables, session stores, idempotency keys, per-user lookup maps.
 triggers: [database, kv, key value, namespace, store, state, etag, cas, session, idempotency]
-checksum: sha256-9b6f14fa5b0115ce042c71f861cb71ec8993aa68447d740b63f5b3689c23b629
+checksum: sha256-91f0ba9f2dba98bcb322951455b153584b667c4570e5536d39dcf10c6cec44c6
 ---
 
 # MyDatabaseAPI
@@ -119,6 +119,7 @@ reply  { "success": true, "data": …, "error": null, "meta": {…} }
 
 - **Per-slot host** — do not assume one host serves every slot.
 - **Org id goes in the PATH** — there is no `X-Org-Id` header.
+- **Lists page** — one page is not the whole list; check `meta.has_more`.
 <!-- http:end -->
 
 Run `myapi database --help` for inline reference.

package/dist/skills/my-feedback-api/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: my-feedback-api
-version: 1.7.0
+version: 1.7.1
 description: >
   Collect feedback from the people using what you built. A public widget key lets a page submit without a credential; you list, filter and resolve the results. Kind is chosen by the person reporting, not inferred from their wording.
 triggers: [feedback, bug report, user feedback, feature request, widget, support, complaints, praise]
-checksum: sha256-a76c44ae06a9693ec4874132f52675d0344dfdbb174fff668cb602b16dca59b7
+checksum: sha256-144cac696fd3eecf228682929be063a9c26ad3d0f921c41d9ccb433255609c7e
 ---
 
 # MyFeedbackAPI
@@ -75,8 +75,8 @@ probed), `ORIGIN_NOT_ALLOWED`, `RATE_LIMITED`, `INVALID_KIND`, `BODY_REQUIRED`,
 says it is**. A `bug` means they believe the product is broken — more urgent
 than a wish for something new. Do not re-classify from the wording.
 
-Classification and duplicate-grouping are designed but not built, so treat
-`kind` as the person's label, not a processed signal.
+Nothing classifies or de-duplicates it: `kind` is the person's label, not a
+processed signal.
 
 ### Controlling what a report contains
 
@@ -148,7 +148,7 @@ one, so success is not proof it existed — so ids cannot be probed.
 | Command | What it does |
 |---|---|
 | `myapi feedback create "<text>" --kind <k>` | Record one item (`--page-url`, `--route` for context) |
-| `myapi feedback list [--kind bug\|issue\|suggestion] [--status open\|resolved] [--limit N] [--offset N] [--trace]` | List feedback, newest first. Each report summarises what was pointed at, what happened before, and whether a screenshot exists; `--trace` expands the events |
+| `myapi feedback list [--kind bug\|issue\|suggestion] [--status open\|resolved] [--limit N] [--offset N] [--trace]` | List feedback, newest first. Each report summarises what was pointed at and whether a screenshot exists; `--trace` expands the events |
 | `myapi feedback resolve <id>` | Close an item, keeping it |
 | `myapi feedback test <id> [--base <url>] [--out <p>]` | Render the report as a Playwright spec (stdout, or `--out`) |
 | `myapi feedback delete <id>` | Erase an item — for spam, or personal details typed into the box |
@@ -199,6 +199,7 @@ reply  { "success": true, "data": …, "error": null, "meta": {…} }
 
 - **Per-slot host** — do not assume one host serves every slot.
 - **Org id goes in the PATH** — there is no `X-Org-Id` header.
+- **Lists page** — one page is not the whole list; check `meta.has_more`.
 <!-- http:end -->
 
 Run `myapi feedback --help` for the full flag reference.

package/dist/skills/my-function-api/SKILL.md

@@ -4,7 +4,7 @@ version: 1.1.0
 description: >
   Deploy JavaScript functions to the MyAPI edge runtime. Register a function, upload a single-file JS bundle, get a live HTTP invocation URL or run it on a cron schedule. Each function gets a scoped capability key for cross-slot calls.
 triggers: [function, deploy function, edge function, serverless, cloudflare worker, cron, scoped api key, capability key, invocation url, bundle]
-checksum: sha256-3702cfd630b5ff8a892704c4f6aee9f6678881c73fd3522ce4bd52be865e639e
+checksum: sha256-1e3179c62d2eb1978c6e857e11c7a86c39f3cf784b7de7755ebcb05666b90a17
 ---
 
 # MyFunctionAPI
@@ -159,6 +159,7 @@ reply  { "success": true, "data": …, "error": null, "meta": {…} }
 
 - **Per-slot host** — do not assume one host serves every slot.
 - **Org id goes in the PATH** — there is no `X-Org-Id` header.
+- **Lists page** — one page is not the whole list; check `meta.has_more`.
 <!-- http:end -->
 
 Run `myapi fn --help` or `myapi fn <subcommand> --help` for full flag reference.

package/dist/skills/my-llm-api/SKILL.md

@@ -1,26 +1,21 @@
 ---
 name: my-llm-api
-version: 1.2.1
+version: 1.3.0
 description: >
   Two-surface LLM primitive. Raw chat completion against self-hosted
   open-source models (you pick the model), and objective verbs
   (classify / extract / summarize / draft) that hide the model behind a
   task. Pricing in cents per 1M tokens; charged from your MyAPI balance.
 triggers: [llm, completion, chat, embed, embedding, inference, classify, extract, summarize, draft, qwen]
-checksum: sha256-d89e5c7ccadb7e967f97ec201b745f2313e4263f8f08a695f4cc9fbaa0c4b500
+checksum: sha256-d63ee7e22984a21313b70af961cee46525c60e7c727372b6c0e2b369c81989d4
 ---
 
 # MyLLMAPI
 
-A two-surface LLM gateway:
-
-- **Raw** — `complete` / `embed` / `models`. You pick a self-hosted catalog model (run `myapi llm models` for the live list). Proprietary models are not callable here.
-- **Verbs** — `classify` / `extract` / `summarize` / `draft`. You ask for a task done; the model is implementation detail.
+A two-surface LLM gateway: **raw** (`complete`/`embed`/`models`) against a self-hosted catalog you pick from, and **verbs** (`classify`/`extract`/`summarize`/`draft`) where the model is implementation detail. Proprietary models are not callable here.
 
 ## Capabilities
 <!-- llm:start -->
-For workflow tasks — summarize, classify, extract, draft. The reply goes to stdout and the usage footer (tokens, cost, finish reason) to stderr, so `myapi llm complete ... | jq` works.
-
 **Don't use this as your own model.** If you are an agent reading this, you already have a more capable model. Reach for the LLM verbs when scripting a recurring step where a small, cheap model is the right tool — not for one-shot reasoning you can do yourself.
 
 Reach for raw `complete` when shape matters (you build the `messages` array and set `max_tokens`/`temperature`/`stop`); reach for a verb when you want a *result* and don't care which model produced it.
@@ -55,6 +50,26 @@ Roles: `system | user | assistant`. Multiple system messages collapse to one ins
 
 If `model` isn't in the self-hosted catalog the server returns `MODEL_NOT_IN_RAW_CATALOG` — that's the signal to use a verb instead, not to retry with a different `--model`.
 
+### Context caches — a tenth to re-read
+
+Sending the same long prefix on every call (system prompt, reference doc,
+schema)? Store it once and re-read it at a **tenth** the input price. Measured
+on the same 6.9k-token prefix: **0.0073¢ cached vs 0.0629¢ inline.**
+
+```bash
+myapi llm cache create --file ./system-prompt.md --model <id> --ttl 3600
+myapi llm complete "..." --model <id> --cache <cache-id>
+```
+
+- **Bound to ONE model** — another model cannot read it.
+- **It bills for EXISTING, not for being read.** Storage accrues per hour from
+  creation whether anyone reads it or not, so `cache delete` is how you stop
+  paying; letting the TTL lapse means paying the TTL in full.
+- **`ttl_seconds` is capped at 24h** — silently shortened, not refused. Read
+  `expires_at` from the reply rather than trusting your own input.
+- **`usage.cached_input_tokens` is a SUBSET of `input_tokens`**, never an
+  addition — summing them double-counts every cached read.
+
 ### Raw `embed`
 
 Embed text into a dense vector. `--model` is optional when the catalog serves exactly one embed model; else pass one from `myapi llm models --kind embed`. Returns `EMBED_NOT_AVAILABLE` when none is served.
@@ -63,7 +78,7 @@ Embed text into a dense vector. `--model` is optional when the catalog serves ex
 - Chat models: `id`, `kind: 'chat'`, `context_window`, `input_cost_per_1m_cents`, `output_cost_per_1m_cents`
 - Embed models: `id`, `kind: 'embed'`, `dimensions`, `input_cost_per_1m_cents`
 
-The catalog is **live** — it reflects what the inference gateway actually serves, refreshed every 15 minutes. Always query `models` rather than hard-coding ids.
+The catalog is **live**, refreshed every 15 minutes.
 
 ### Verb requests + responses
 
@@ -89,13 +104,8 @@ The model/provider is **never** named in the verb response — the verb is the c
 `POST /llm/orgs/{org_id}/chat/completions` (alias `/v1/chat/completions`) takes and returns the OpenAI shape — **no envelope**. Same catalog and pricing as `complete`. Use it when an existing OpenAI SDK or LangChain integration should point at MyAPI unchanged.
 
 ```python
-from openai import OpenAI
-client = OpenAI(
-    api_key="hq_live_…",
-    base_url="https://api.myapihq.com/llm/orgs/<org_id>/v1",
-)
-r = client.chat.completions.create(model="<model-id>",
-    messages=[{"role":"user","content":"Hi"}])
+client = OpenAI(api_key="hq_live_…",
+    base_url="https://api.myapihq.com/llm/orgs/<org_id>/v1")
 ```
 
 <!-- llm:end -->
@@ -111,6 +121,7 @@ r = client.chat.completions.create(model="<model-id>",
 | `myapi llm extract "<input>" --schema <path\|json> [--tier <t>] [--json]` | Pull structured data conforming to a JSON Schema |
 | `myapi llm summarize "<input>" [--style brief\|exec\|bullet] [--tier <t>] [--json]` | Summarize text |
 | `myapi llm draft --kind <what> [--prompt "<s>"] [--facts <json>] [--directives <json>] ["<src>"] [--tier <t>] [--json]` | Draft an email / reply / message / … |
+| `myapi llm cache <create --file <p> [--model <id>] [--ttl N] \| list \| delete <id>>` | Store a prompt prefix; re-read it at a tenth the input price |
 <!-- generated:end -->
 
 Pass `-` as the prompt/input to read from stdin. Pass `--file <path>` to read longer content from disk.
@@ -120,24 +131,17 @@ Pass `-` as the prompt/input to read from stdin. Pass `--file <path>` to read lo
 ```bash
 # List the live catalog
 myapi llm models
-myapi llm models --kind chat --json | jq '.models[].id'
 
 # Raw completion — picks the first chat model from the catalog
 myapi llm complete "Summarize in 12 words: $(cat README.md)"
 
-# Pin a specific model (ids come from `myapi llm models`)
-myapi llm complete "Refactor this function: ..." \
-  --model <model-id> \
-  --system "You are a careful Go reviewer." \
-  --max-tokens 600
-
 # ── Verbs (recommended for workflow steps) ──────────────────────────────
 
 myapi llm classify "I was charged twice — please refund." \
   --labels billing,technical,sales,spam
 
 myapi llm extract "Acme Corp employs 250 people in Berlin." \
-  --schema '{"type":"object","properties":{"company":{"type":"string"},"employees":{"type":"integer"}}}'
+  --schema '{"type":"object","properties":{"company":{"type":"string"}}}'
 
 myapi llm summarize --file long-thread.txt --style bullet
 
@@ -154,25 +158,13 @@ INTENT=$(printf '%s' "$BODY" | myapi llm classify - \
 
 ## Notes
 
-- **`draft --facts` safety.** Fact values are quoted into the prompt verbatim and sensitive-named keys (`secret`, `api_key`, `password`, …) are NOT redacted. Two guards: injection-defense strips `instructions`/`system`/`prompt`/`override` keys into `meta.warnings`; an output guardrail substring-scans fact values (≥4 chars) and lists hits in `meta.guardrails.facts_in_output` (signal, not redaction). Never put credentials, PII, or internal metadata in `--facts` — pass identifiers and reference them indirectly.
+- **`draft --facts` safety.** Fact values are quoted verbatim and sensitive-named keys are NOT redacted. Instruction-like keys are stripped into `meta.warnings`, and fact values echoed in the output are listed in `meta.guardrails.facts_in_output` — signal, not redaction. Never put credentials or PII in `--facts`; pass identifiers and reference them indirectly.
+- **`--facts` vs `--directives`.** Facts are referent data (recipient, dates, amounts), quoted as reference and never as instructions; directives are writer controls only (tone, max_words, format). They are trusted differently. `--context` is the old name for `--facts`.
 - **`402`** — `INSUFFICIENT_FUNDS`: top up or enable `myapi billing auto-recharge`. `SPEND_CAP_EXCEEDED`: raise your own ceiling with `myapi billing spend-cap`.
 - **Self-hosted raw, server-picked verbs.** Raw runs on MyAPI's TPU; verbs route wherever the server picks.
 - **Cost + latency.** `usage.cost_cents` is authoritative — no markup. Varies by tier: 200–600 ms to first token, 1–3 s end-to-end.
 - **Live catalog, no streaming, no BYOK.** Don't hard-code ids — `models` is truth (CLI auto-picks if `--model` omitted). Full reply only.
 
-## `--facts` vs `--directives` on draft
-
-`--facts '<json>'` is referent data, quoted as reference and never as
-instructions (recipient, dates, amounts). `--directives '<json>'` is writer
-controls only: tone, max_words, format, style. They are trusted differently.
-
-```bash
-myapi llm draft --kind email --prompt "the invoice is due" \
-  --facts '{"to":"Ada"}' --directives '{"tone":"warm"}'
-```
-
-`--context` is the old name for `--facts`; accepted, deprecated upstream.
-
 ## HTTP (from deployed code)
 
 <!-- http:start -->

package/dist/skills/my-queue-api/SKILL.md

@@ -4,7 +4,7 @@ version: 1.0.1
 description: >
   Durable job queue — enqueue work and have it retried against your HTTP consumer, with concurrency caps and a dependency DAG.
 triggers: [queue, job queue, background job, enqueue, retry, async work, dead letter, delayed job, concurrency]
-checksum: sha256-ad874e1229df9381fc92881b2a1fada40859983c24fe4386d43922398323b05c
+checksum: sha256-762f5f68386044a4313935f14643c8cbd784e7c6a4133308d0f14658062c9a0b
 ---
 
 # MyQueueAPI
@@ -89,6 +89,7 @@ reply  { "success": true, "data": …, "error": null, "meta": {…} }
 
 - **Per-slot host** — do not assume one host serves every slot.
 - **Org id goes in the PATH** — there is no `X-Org-Id` header.
+- **Lists page** — one page is not the whole list; check `meta.has_more`.
 <!-- http:end -->
 
 ## workflow vs queue vs task

package/dist/skills/my-storage-api/SKILL.md

@@ -4,7 +4,7 @@ version: 1.1.0
 description: >
   Edge-hosted asset storage. Upload a local file of any content type directly, or have the server fetch from a public URL. Each asset gets a stable public CDN URL.
 triggers: [storage, upload, ingest, asset, cdn, image hosting, file upload, get-url, download, public url]
-checksum: sha256-1452c30c103d0bb8b76a8f6d8e1688cadd556922b8c60e7ac754222c33b65524
+checksum: sha256-ef0154ed196082be84192c7ddfb4cab47641549ed9703087c9eb4643daea678a
 ---
 
 # MyStorageAPI
@@ -134,6 +134,7 @@ reply  { "success": true, "data": …, "error": null, "meta": {…} }
 
 - **Per-slot host** — do not assume one host serves every slot.
 - **Org id goes in the PATH** — there is no `X-Org-Id` header.
+- **Lists page** — one page is not the whole list; check `meta.has_more`.
 <!-- http:end -->
 
 Run `myapi storage --help` for full flag reference.

package/dist/skills/my-webhook-api/SKILL.md

@@ -4,7 +4,7 @@ version: 1.0.1
 description: >
   Inbound webhook endpoints for non-funnel sources — Stripe, GitHub, custom services. Funnel forms use the my-funnel-api proxy.
 triggers: [webhook, inbound, receiver, stripe events, github webhook, slack notification, delivery, payload, event ingest]
-checksum: sha256-737e0572ef7c414dab568e60af676aa8e50900ed368ba7bcdf81fc65516be9eb
+checksum: sha256-aff831f651b965cc48fd26bbd20c04bd44443a2073917a4660aefaffc5091dcd
 ---
 
 # MyWebhookAPI
@@ -127,6 +127,7 @@ reply  { "success": true, "data": …, "error": null, "meta": {…} }
 
 - **Per-slot host** — do not assume one host serves every slot.
 - **Org id goes in the PATH** — there is no `X-Org-Id` header.
+- **Lists page** — one page is not the whole list; check `meta.has_more`.
 <!-- http:end -->
 
 Run `myapi webhook --help` for full flag reference.

package/dist/skills/my-workflow-api/SKILL.md

@@ -4,7 +4,7 @@ version: 1.0.0
 description: >
   Run actions when a webhook fires. Trigger emails, Slack notifications, or HTTP calls in response to inbound webhook deliveries — without writing a backend.
 triggers: [workflow, automation, on webhook, send email on, slack notification, payload templating, drip, trigger, run]
-checksum: sha256-35b09cb26aa3781c78abdc2b362bdb8f0817a9580467bf94e65e0f2f335d502a
+checksum: sha256-0a1607bd1a89cd13a052b426fa2262cc1cef71c52acf8c63fc7e8026ba6ba52c
 ---
 
 # MyWorkflowAPI
@@ -128,6 +128,7 @@ reply  { "success": true, "data": …, "error": null, "meta": {…} }
 
 - **Per-slot host** — do not assume one host serves every slot.
 - **Org id goes in the PATH** — there is no `X-Org-Id` header.
+- **Lists page** — one page is not the whole list; check `meta.has_more`.
 <!-- http:end -->
 
 Run `myapi workflow --help` for full flag reference.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@myapihq/cli",
   "license": "Apache-2.0",
-  "version": "2.20.1",
+  "version": "2.21.1",
   "description": "MyAPI command-line interface",
   "repository": {
     "type": "git",
@@ -46,7 +46,7 @@
     "lint:skills:strict": "node scripts/copy-skills.js && node scripts/lint-skills.js --strict"
   },
   "dependencies": {
-    "@myapihq/sdk": "^2.20.1"
+    "@myapihq/sdk": "^2.21.1"
   },
   "devDependencies": {
     "@types/node": "^25.6.0",