@spicyapi/skill 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SpicyAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# @spicyapi/skill
+
+Official standalone Agent Skill for SpicyAPI. It follows the portable Agent Skills directory format
+and contains the Skill assets plus an atomic installer; it does not include the SDK, CLI, or MCP
+server. Codex is one supported client, not the package's scope or identity.
+
+```bash
+npx --yes --package=@spicyapi/skill spicyapi-skill install
+```
+
+The default destination is `~/.agents/skills/spicyapi`. Set `AGENTS_SKILLS_DIR` to another shared
+skills directory, or pass the exact client-specific directory with `--target`.
+
+Inspect the packaged source directory with:
+
+```bash
+npx --yes --package=@spicyapi/skill spicyapi-skill path
+```
+
+Use `--target <absolute-directory>` for Codex, Claude Code, Cursor, or another Agent
+Skills-compatible client when it uses a different skills directory. Use `--force` only when you
+intend to replace that exact destination.

package/SECURITY.md

@@ -0,0 +1,4 @@
+# Security
+
+Report suspected vulnerabilities privately at <https://spicyapi.ai/security>. Never include API
+keys, private media, signed URLs, recovery codes, or customer data in a public issue.

package/dist/src/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/src/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":""}

package/dist/src/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import process from "node:process";
+import { getBundledSkillPath, installSpicySkill } from "./skill/index.js";
+function usage() {
+    return [
+        "Usage: spicyapi-skill [path | install] [--target <directory>] [--force] [--json]",
+        "",
+        "Commands:",
+        "  path       Show the packaged Skill directory",
+        "  install    Install the Skill into the shared Agent Skills directory (default)",
+    ].join("\n");
+}
+function optionValue(args, name) {
+    const index = args.indexOf(name);
+    if (index < 0)
+        return undefined;
+    const value = args[index + 1];
+    if (!value || value.startsWith("--"))
+        throw new Error(`${name} requires a value`);
+    return value;
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.includes("--help") || args.includes("-h")) {
+        process.stdout.write(`${usage()}\n`);
+        return;
+    }
+    const command = args[0]?.startsWith("--") ? "install" : (args[0] ?? "install");
+    const json = args.includes("--json");
+    let result;
+    if (command === "path") {
+        result = { path: await getBundledSkillPath() };
+    }
+    else if (command === "install") {
+        const target = optionValue(args, "--target");
+        result = await installSpicySkill({
+            ...(target === undefined ? {} : { destination: target }),
+            force: args.includes("--force"),
+        });
+    }
+    else {
+        throw new Error(`unknown command: ${command}`);
+    }
+    process.stdout.write(json ? `${JSON.stringify(result)}\n` : `${JSON.stringify(result, null, 2)}\n`);
+}
+main().catch((error) => {
+    const message = error instanceof Error ? error.message : "unknown error";
+    process.stderr.write(`${message}\n`);
+    process.exitCode = 1;
+});
+//# sourceMappingURL=cli.js.map

package/dist/src/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../../src/cli.ts"],"names":[],"mappings":";AAEA,OAAO,OAAO,MAAM,cAAc,CAAC;AAEnC,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAE1E,SAAS,KAAK;IACZ,OAAO;QACL,kFAAkF;QAClF,EAAE;QACF,WAAW;QACX,gDAAgD;QAChD,iFAAiF;KAClF,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AACf,CAAC;AAED,SAAS,WAAW,CAAC,IAAc,EAAE,IAAY;IAC/C,MAAM,KAAK,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACjC,IAAI,KAAK,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAChC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IAC9B,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,mBAAmB,CAAC,CAAC;IAClF,OAAO,KAAK,CAAC;AACf,CAAC;AAED,KAAK,UAAU,IAAI;IACjB,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACnD,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,KAAK,EAAE,IAAI,CAAC,CAAC;QACrC,OAAO;IACT,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC,CAAC;IAC/E,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACrC,IAAI,MAAe,CAAC;IACpB,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,MAAM,GAAG,EAAE,IAAI,EAAE,MAAM,mBAAmB,EAAE,EAAE,CAAC;IACjD,CAAC;SAAM,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,WAAW,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAC7C,MAAM,GAAG,MAAM,iBAAiB,CAAC;YAC/B,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,MAAM,EAAE,CAAC;YACxD,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;SAChC,CAAC,CAAC;IACL,CAAC;SAAM,CAAC;QACN,MAAM,IAAI,KAAK,CAAC,oBAAoB,OAAO,EAAE,CAAC,CAAC;IACjD,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAC9E,CAAC;AACJ,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAc,EAAE,EAAE;IAC9B,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,eAAe,CAAC;IACzE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,OAAO,IAAI,CAAC,CAAC;IACrC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/src/skill/index.d.ts

@@ -0,0 +1,13 @@
+export interface InstallSpicySkillOptions {
+    destination?: string;
+    force?: boolean;
+    env?: NodeJS.ProcessEnv;
+}
+export interface InstalledSpicySkill {
+    destination: string;
+    replaced: boolean;
+}
+export declare function getBundledSkillPath(): Promise<string>;
+export declare function getDefaultAgentSkillPath(env?: NodeJS.ProcessEnv): string;
+export declare function installSpicySkill(options?: InstallSpicySkillOptions): Promise<InstalledSpicySkill>;
+//# sourceMappingURL=index.d.ts.map

package/dist/src/skill/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/skill/index.ts"],"names":[],"mappings":"AAMA,MAAM,WAAW,wBAAwB;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;CACzB;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,OAAO,CAAC;CACnB;AAYD,wBAAsB,mBAAmB,IAAI,OAAO,CAAC,MAAM,CAAC,CAU3D;AAED,wBAAgB,wBAAwB,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAGrF;AAED,wBAAsB,iBAAiB,CACrC,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,mBAAmB,CAAC,CA+B9B"}

package/dist/src/skill/index.js

@@ -0,0 +1,66 @@
+import { randomUUID } from "node:crypto";
+import { access, cp, mkdir, rename, rm } from "node:fs/promises";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+async function exists(target) {
+    try {
+        await access(target);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+export async function getBundledSkillPath() {
+    const candidates = [
+        new URL("../../../skills/spicyapi/", import.meta.url),
+        new URL("../../skills/spicyapi/", import.meta.url),
+    ];
+    for (const candidate of candidates) {
+        const directory = fileURLToPath(candidate);
+        if (await exists(path.join(directory, "SKILL.md")))
+            return directory;
+    }
+    throw new Error("the packaged SpicyAPI Skill could not be found");
+}
+export function getDefaultAgentSkillPath(env = process.env) {
+    const skillsRoot = env.AGENTS_SKILLS_DIR?.trim() || path.join(homedir(), ".agents", "skills");
+    return path.resolve(skillsRoot, "spicyapi");
+}
+export async function installSpicySkill(options = {}) {
+    const source = await getBundledSkillPath();
+    const destination = path.resolve(options.destination ?? getDefaultAgentSkillPath(options.env));
+    const destinationExists = await exists(destination);
+    if (destinationExists && !options.force) {
+        throw new Error(`skill already exists at ${destination}; pass --force to replace that exact directory`);
+    }
+    const parent = path.dirname(destination);
+    const nonce = randomUUID();
+    const staging = path.join(parent, `.spicyapi-install-${nonce}`);
+    const backup = path.join(parent, `.spicyapi-backup-${nonce}`);
+    await mkdir(parent, { recursive: true });
+    try {
+        await cp(source, staging, { recursive: true, errorOnExist: true, force: false });
+        if (destinationExists)
+            await rename(destination, backup);
+        try {
+            await rename(staging, destination);
+        }
+        catch (error) {
+            if (destinationExists && (await exists(backup)))
+                await rename(backup, destination);
+            throw error;
+        }
+        if (destinationExists)
+            await rm(backup, { recursive: true, force: true });
+    }
+    catch (error) {
+        await rm(staging, { recursive: true, force: true });
+        throw error;
+    }
+    return { destination, replaced: destinationExists };
+}
+//# sourceMappingURL=index.js.map

package/dist/src/skill/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/skill/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@spicyapi/skill",
+  "version": "0.1.0",
+  "description": "Official installable Agent Skill for SpicyAPI",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SpicyAPI/spicy-devkit.git",
+    "directory": "packages/skill"
+  },
+  "homepage": "https://spicyapi.ai",
+  "bugs": {
+    "url": "https://spicyapi.ai/contact"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "main": "./dist/src/skill/index.js",
+  "types": "./dist/src/skill/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/skill/index.d.ts",
+      "import": "./dist/src/skill/index.js"
+    }
+  },
+  "bin": {
+    "spicyapi-skill": "dist/src/cli.js"
+  },
+  "files": [
+    "dist/src",
+    "skills/spicyapi",
+    "README.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}

package/skills/spicyapi/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: spicyapi
+description:
+  Use the SpicyAPI public developer API through the official SDK, CLI, or MCP server to inspect live
+  models, create, retry, and wait for media tasks, upload inputs, retrieve outputs, check balances,
+  and verify webhooks. Use for SpicyAPI integration and API operations; not for browser-account
+  administration, payments, or publishing provider models.
+metadata:
+  short-description: Operate SpicyAPI through its SDK, CLI, or MCP server
+---
+
+# SpicyAPI
+
+Use the packaged `spicyapi_*` MCP tools when they are connected. Otherwise use the `spicyapi` CLI
+for operations or `SpicyClient` for application code. Treat the live model catalog and the bundled
+OpenAPI contract as authoritative.
+
+Read [references/api-workflows.md](references/api-workflows.md) before composing API, CLI, or MCP
+operations. Read [references/safety.md](references/safety.md) before billable calls, real
+integration tests, webhook handling, credential work, or cleanup.
+
+## Required behavior
+
+- Query the live catalog and fetch the selected model with its input schema before creating a task.
+  Never invent a model ID, price, provider capability, or input field.
+- Pass the model-specific `input` object through unchanged. The SpicyAPI server owns schema, price,
+  balance, operational API-key scope, and routing decisions.
+- Treat `mature` as caller-declared execution metadata. Pass the requested boolean unchanged; the
+  platform does not inspect or gate it by account, API key, model, channel, age, consent, or a
+  content classifier. A selected model service may still refuse under its own behavior, and the
+  customer remains responsible for applicable law, age, consent, and end-user controls.
+- Treat task creation and retry as billable. Obtain explicit confirmation and preserve one
+  idempotency key for the entire logical attempt, including recovery from an uncertain response.
+- Use environment variables for API keys and webhook secrets. Never put them in arguments, source
+  code, prompts, logs, support messages, or committed configuration.
+- Preserve `request_id`, task IDs, upload keys, and idempotency keys in operational results. They
+  are necessary for reconciliation and support.
+- Do not invent task listing, cancellation, deletion, estimate, or webhook-redelivery calls. They
+  are absent from the public developer contract.
+- Keep browser-session identity, payment, privacy, account closure, and admin operations in the
+  SpicyAPI Console. Do not emulate cookie/CSRF Console routes in this server-side skill.
+- Provider/model onboarding and production enablement are outside this skill unless the user
+  explicitly supplies a separate supported contract.
+
+## Real validation
+
+When the user asks for a real test, make a real request against the selected environment; do not
+substitute a mock and call it verified. Record every created identifier before continuing. Use the
+smallest user-approved billable scenario that the live catalog actually offers, then verify it
+through task retrieval or waiting.
+
+Clean up only exact artifacts that the environment exposes a supported deletion mechanism for. The
+public developer API has no task or uploaded-object delete operation, so report those retained
+artifacts and their identifiers honestly instead of claiming deletion or reaching into unrelated
+data stores.
+
+## Completion
+
+Report the surface used (SDK, CLI, or MCP), live model ID when applicable, idempotency key,
+task/request identifiers, final observed state, and any artifact that could not be removed through a
+supported API. Never report a provider call or cleanup as successful without observing it.

package/skills/spicyapi/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "SpicyAPI"
+  short_description: "Operate SpicyAPI safely through SDK, CLI, or MCP"
+  default_prompt:
+    "Use $spicyapi to inspect the live model catalog and run this SpicyAPI workflow safely."
+
+policy:
+  allow_implicit_invocation: true

package/skills/spicyapi/references/api-workflows.md

@@ -0,0 +1,108 @@
+# SpicyAPI API workflows
+
+## Runtime configuration
+
+Set credentials through the process environment or a secret manager:
+
+- `SPICY_API_KEY`: required for authenticated public API operations.
+- `SPICY_API_BASE_URL`: defaults to `https://api.spicyapi.ai/api/v1`.
+- `SPICY_SERVICE_BASE_URL`: defaults to `https://api.spicyapi.ai` and is used for health/readiness.
+- `SPICY_WEBHOOK_SECRET`: used only for local webhook verification.
+
+Plain HTTP base URLs are accepted only for loopback development hosts.
+
+## Verified public surface
+
+| Purpose        | CLI                                     | MCP tool                       | Public route                         |
+| -------------- | --------------------------------------- | ------------------------------ | ------------------------------------ |
+| Service status | `spicyapi status`                       | `spicyapi_service_status`      | `/healthz`, `/readyz`                |
+| Search docs    | `spicyapi docs search [query]`          | `spicyapi_docs_search`         | Bundled first-party index            |
+| List models    | `spicyapi models list --include-schema` | `spicyapi_models_list`         | `GET /models`                        |
+| Get model      | `spicyapi models get <model>`           | `spicyapi_model_get`           | `GET /models/{model}`                |
+| Balance        | `spicyapi balance`                      | `spicyapi_balance_get`         | `GET /chat/credit`                   |
+| Create task    | `spicyapi tasks create ...`             | `spicyapi_task_create`         | `POST /jobs/createTask`              |
+| Get task       | `spicyapi tasks get <task-id>`          | `spicyapi_task_get`            | `GET /jobs/recordInfo`               |
+| Wait for task  | `spicyapi tasks wait <task-id>`         | `spicyapi_task_wait`           | Composes task retrieval              |
+| Retry task     | `spicyapi tasks retry <task-id>`        | `spicyapi_task_retry`          | `POST /jobs/retry`                   |
+| Prepare upload | SDK                                     | `spicyapi_upload_prepare`      | `POST /common/upload-url`            |
+| Upload file    | `spicyapi files upload <path>`          | Keep bytes outside MCP         | Presigned storage `PUT`, then commit |
+| Commit upload  | SDK                                     | `spicyapi_upload_commit`       | `POST /files/{fileId}/commit`        |
+| Output URL     | `spicyapi files download-url <task-id>` | `spicyapi_download_url_create` | `POST /common/download-url`          |
+| Verify webhook | `spicyapi webhooks verify ...`          | Local library/CLI              | No network call                      |
+
+These are the complete public developer operations in the bundled contract. Model listing is not
+paginated.
+
+## Generation sequence
+
+1. Check readiness and authenticated balance.
+2. List models with `--include-schema` and get the exact candidate model.
+3. Build only the `input` object described by the returned live schema. Preserve unknown future
+   fields rather than remapping them.
+4. If the caller requests mature execution, send `mature: true` unchanged. It is recorded and
+   forwarded as execution metadata; it is not checked against an account, API key, catalog label,
+   channel, or platform content classifier. The selected model service may still refuse.
+5. Upload local media first when the model input requires a hosted asset. Use the returned committed
+   file reference exactly as the model schema specifies.
+6. Choose one idempotency key for the logical creation attempt.
+7. Confirm the current action and create the task. CLI confirmation is interactive unless `--yes` is
+   explicitly supplied; MCP uses protocol elicitation.
+8. Save the returned task ID, request ID when present, and idempotency key.
+9. Poll with `tasks wait`, or retrieve the task after a signed terminal webhook.
+10. Create a short-lived download URL for a successful task output. Do not persist the presigned URL
+    as a durable asset identifier.
+
+Example CLI shape, after inspecting the live schema:
+
+```bash
+spicyapi --json models get provider/model
+spicyapi --json tasks create \
+  --model provider/model \
+  --input-file ./input.json \
+  --mature \
+  --idempotency-key 7b5a89dd-1ec3-4ec8-8246-6c76cc863665 \
+  --yes \
+  --wait
+```
+
+The model and fields above are structural placeholders, not claims that a model exists. Replace them
+only with values returned by the live catalog. Omit `--mature` when the caller did not request that
+execution mode.
+
+## Uncertain responses and retries
+
+- Read-only requests can use bounded automatic retries for transient failures.
+- Task creation and retry are automatically retryable only when an idempotency key is present.
+- After a timeout or lost response, reuse the same idempotency key. Never generate a second key
+  merely because the first response was uncertain.
+- A task retry creates a new task and may reserve funds again. It is valid only for server-accepted
+  source states such as `failed` or `expired`; the server remains authoritative.
+- Use `request_id` and `Retry-After` metadata from structured errors. Do not expose the API key
+  while reporting an error.
+
+## SDK outline
+
+```ts
+import { SpicyClient } from "@spicyapi/sdk";
+
+const client = new SpicyClient();
+const model = await client.getModel("live/catalog-id");
+const accepted = await client.createTask(
+  { model: model.model, input: {/* fields from model.inputSchema */} },
+  { idempotencyKey: crypto.randomUUID() },
+);
+const terminal = await client.waitForTask(accepted.taskId);
+```
+
+## Webhook verification
+
+Verify the exact raw request bytes before parsing. Current signatures are Base64-encoded HMAC-SHA256
+over:
+
+```text
+taskId.timestamp.hex(sha256(raw_body))
+```
+
+Payload version 1 reads `task_id`; version 2 reads `data.taskId`. Perform constant-time signature
+comparison before checking timestamp tolerance. For v2, use `request_id` as the stable delivery
+identifier when present.

package/skills/spicyapi/references/safety.md

@@ -0,0 +1,82 @@
+# SpicyAPI safety and cleanup
+
+## Credentials and privacy
+
+- Load `SPICY_API_KEY`, webhook secrets, and local MCP tokens from environment variables or a secret
+  manager.
+- Never accept an API key through a CLI flag. Do not serialize secrets into JSON output, shell
+  history, MCP prompts, screenshots, telemetry, test snapshots, or error reports.
+- Treat generation prompts, uploaded media, outputs, callbacks, and task metadata as private
+  customer content. Log identifiers and correlation metadata, not payload bodies or presigned URLs.
+- A presigned upload or download URL is a temporary credential. Redact it and do not send the Spicy
+  API key to its storage host.
+
+## Billable operations
+
+Task creation and retry can reserve funds. Before execution:
+
+1. Fetch the live model record and balance.
+2. Explain the exact model ID and that live price, operational API-key scope, balance, and routing
+   are decided on acceptance.
+3. Obtain explicit user confirmation, unless the user's current request already explicitly
+   authorizes that exact billable test.
+4. Mint or preserve one idempotency key and surface it to the user.
+
+Decline, cancellation of confirmation, schema mismatch, or missing confirmation must result in zero
+API calls.
+
+## Mature request metadata
+
+- `mature` is a caller-declared request value, not an account or API-key entitlement.
+- Forward the boolean unchanged. Do not preflight it against the catalog capability, selected
+  channel, age, consent, or a platform content policy, and do not claim the platform approved it.
+- A model service may still return its own refusal. Report that observed task failure normally;
+  never invent a platform gate or retry under a different mode without user direction.
+- Applicable legal, age, consent, real-person, and end-user access responsibilities remain with the
+  customer and are not established by technical success.
+
+## Real integration tests
+
+- Use a dedicated test account/key and a unique marker in permissible metadata or prompt text when
+  the live model schema supports it.
+- Record start time, model ID, idempotency key, request IDs, task IDs, uploaded file IDs/keys, and
+  output keys immediately.
+- Bound cost and count before starting. Stop after the first representative success for each
+  distinct route unless more cases are explicitly required.
+- Verify boundaries with real server responses: unauthorized, invalid schema, insufficient balance,
+  idempotent replay, terminal polling, ownership-safe 404, and webhook tampering where the
+  environment safely permits them.
+- Never manufacture a success when provider credentials, model availability, funds, or policy
+  prevent the route from completing. Preserve the observed error and request ID.
+
+## Cleanup
+
+Build an exact artifact ledger during testing. Delete or revoke only entries from that ledger and
+verify each deletion through the same supported control plane.
+
+The public SpicyAPI developer contract does not expose task cancellation, task deletion,
+uploaded-object deletion, output deletion, or webhook redelivery. Therefore:
+
+- Do not claim public-API cleanup for those records.
+- Do not delete adjacent account data or reach into production databases as a workaround.
+- If an authorized isolated local environment exposes direct cleanup, match exact unique IDs,
+  confirm the environment, remove only those rows/objects, and verify zero remaining matches.
+- Otherwise report retained task/file IDs and their documented retention behavior to the user.
+
+## MCP boundaries
+
+- Prefer stdio for local clients.
+- The packaged HTTP server binds only to loopback and requires a separate `SPICY_MCP_HTTP_TOKEN` of
+  at least 32 bytes. It must not equal `SPICY_API_KEY`.
+- Never expose the local static-token HTTP mode to a remote interface. Internet-facing MCP requires
+  a standards-compliant OAuth resource server with audience-bound tokens and is intentionally not
+  provided here.
+- MCP tool annotations are hints, not authorization. Billable execution remains gated by protocol
+  elicitation and signed request state.
+
+## Account and payment boundaries
+
+Registration, login, password recovery, team membership, checkout, saved payment methods, automatic
+recharge, privacy export/deletion, account closure, support, and admin operations use
+browser-session Console contracts. Keep those flows in the product UI unless a first-class
+non-browser authorization contract is explicitly added.