# Spoolis skill

Compile economic intent into verifiable acceptance criteria, verify fulfillment, and determine what was earned. Use Spoolis when payment depends on whether work actually passed.

The signed Outcome Receipt is the public, portable artifact for another system or third party to verify for authenticity.

## Two-call flow

1. Compile the task into extracted terms, ambiguities, proposed protections, and a verification plan.
2. Verify the delivered result against that plan and read the signed Outcome Receipt.

## Outcome Receipt

- The canonical schema is `spoolis/outcome-receipt@1`.
- Verify receipt authenticity with `@spoolis/receipt-verifier` and pinned receipt entries from `https://spoolis.com/.well-known/spoolis-keys.json`. A valid Ed25519 signature proves the receipt is genuine and unaltered. It does not prove every underlying check is reproducible or that the evidence reflects real-world truth.
- The signed attestation is the lower-level in-band verdict underneath the receipt. Use `POST /api/v1/attestations/verify` only when that lower-level layer is needed.
- Receipt validity records what was earned. It does not grant payment authority or prove that a payment was executed.

## REST

- Compile a task: `POST /api/compile`. Use `action: "create"` to persist the compiled Spool.
- Create a structured Spool: `POST /api/v1/spools`
- Read a Spool: `GET /api/v1/spools/{id}`
- Submit evidence: `POST /api/v1/spools/{id}/evidence`
- Run verification: `POST /api/v1/spools/{id}/verify`
- Read events: `GET /api/v1/spools/{id}/events`
- Create a counterparty invitation: `POST /api/v1/spools/{id}/invite` with the initiator's full-scope key.
- Exchange the returned one-time grant: `POST /api/v1/keys/exchange`. The counterparty key can read its bound Spool and can accept, decline, or submit evidence while the outcome is active.

## MCP

The repository includes an MCP stdio server. Use `create_spool` to provide structured terms and a verification plan, then `verify_spool` after evidence is submitted. Use `create_counterparty_invite` when the initiator needs a machine counterparty to exchange a grant and claim the open party slot on acceptance.

### MCP tools

- `compile_spool`: Compile transaction intent and create a demo or production Spool.
- `create_spool`: Create a Spool.
- `get_spool`: Get the canonical Spool, including raw status dimensions and allowed actions.
- `create_counterparty_invite`: Create a 15-minute, single-use counterparty grant for an active Spool. Requires the initiator's full-scope key.
- `propose_spool`: Propose a draft Spool.
- `accept_spool`: Accept a proposed Spool.
- `abandon_spool`: Abandon an active Spool before settlement is committed.
- `decline_spool`: Decline a proposed Spool.
- `cancel_spool`: Cancel a Spool.
- `commit_payment`: Ask the configured settlement adapter to authorize and, where supported, hold for a Spool.
- `submit_evidence`: Submit evidence for a Spool condition.
- `verify_spool`: Run verification; authenticated v1 returns the Outcome Receipt with its lower-level attestation when signing is configured, while sandbox returns a demo attestation and, for unitized verification, a signed demo Outcome Receipt with units and proportional earned value.
- `complete_spool`: Read a Spool whose outcome is already completed. This tool does not run verification or settlement.
- `get_spool_events`: Get the canonical event history for a Spool.

## Discovery

- Read `/llms.txt` for the concise machine index.
- Read `/llms-full.txt` for the complete public-page dump.
- Every public marketing and content page has a Markdown twin at `<path>.md`, such as `/agents.md`.

## Authentication and settlement

Create production API keys after signing in at `/dashboard/api-keys`, then send them as bearer tokens. A machine counterparty can instead exchange a Spool-bound invitation grant without signing in. This credential is agreement identity only. It does not grant settlement or payment authority. Spoolis applies the agreed economic rule and determines earned value, but it does not hold funds. The payment authority and configured rail or adapter move money according to their own authorization and execution semantics. A sample or demo transaction is not proof of a real payment.