@stellar-agent-services/dev-mcp 0.0.0-stage → 0.1.1

package/repository/examples/python-upstream/README.md

@@ -0,0 +1,44 @@
+# Python API behind the gateway
+
+An existing Python API, [app.py](app.py), that knows nothing about payments, sold as a paid Stellar service
+with only a config file: [provider.config.json](provider.config.json). This is gateway mode of the
+[Provider Kit](../../packages/provider-kit).
+
+| Piece | Role |
+| --- | --- |
+| `app.py` | The existing API: `POST /summarize` takes `{ "text", "sentences" }`, answers JSON. Python standard library only. |
+| `provider.config.json` | The gateway config: price (0.01 USDC, charged on success), schemas, capacity, upstream URL |
+| `schemas/` | The input and output JSON Schemas, kept as files |
+
+The gateway publishes the manifest, refuses invalid input before anyone pays, asks for the x402 payment, calls
+`app.py` with only the validated input, checks its answer against the output schema, settles, and keeps the job
+so a client that lost the response can collect it.
+
+## Run it
+
+From the repository root, after `npm install && npm run build`:
+
+```bash
+PUBLIC_ORIGIN=http://localhost:8787 node packages/provider-kit/dist/cli/index.js dev \
+  --config examples/python-upstream/provider.config.json --with "python3 examples/python-upstream/app.py"
+```
+
+`dev` starts the API on 127.0.0.1:5000, waits until it takes connections, then serves the gateway in front of it.
+`PAY_TO` is the public address that receives the USDC. Without one, `dev` makes a throwaway testnet account to be paid
+to, whose key is dropped at once; set `PAY_TO=G...` to an account in your own wallet to be paid there instead (see the
+[setup guide](../../docs/provider-setup-guide.md)). Then pay it once from another terminal, with its example input:
+
+```bash
+node packages/provider-kit/dist/cli/index.js try summarize --manifest http://localhost:8787/.well-known/stellar-agent-services.json
+```
+
+It pays from a throwaway testnet account it funds itself, after you approve the exact payment, and shows the summary
+and the transfer on chain.
+
+`packages/provider-kit/test/gateway.test.ts` runs this example end to end, with a stand-in facilitator.
+
+## In Docker
+
+Build the image as the [setup guide](../../docs/provider-setup-guide.md) shows. On Docker, the gateway reaches
+`app.py` at the host's address rather than `127.0.0.1`, so change `upstream.url` accordingly (for example
+`http://host.docker.internal:5000/summarize`) and set `"store": "/data/jobs.sqlite"`.

package/repository/llms.txt

@@ -0,0 +1,65 @@
+# Stellar Agent Services
+
+> Provider Standard v1 (`stellar-agent-services/provider@1`) and its tools: an open standard for paid AI services on Stellar. A provider publishes a manifest at `/.well-known/stellar-agent-services.json`, is paid per job in USDC through x402 v2 (`exact` scheme), and lets a client collect a paid job's result without paying again. This repository holds the spec, a TypeScript Provider Kit (a library, and a gateway that puts any existing HTTP API behind payments), a payment client, a verifier and an MCP server for coding agents. Development runs on Stellar testnet.
+
+- The spec is the source of truth. Cite its rules by id, such as `[J13]`.
+- A provider never holds a Stellar secret key: only its public `payTo` address and a facilitator URL.
+- Everything starts on testnet, with test money. Mainnet (`stellar:pubnet`) is real USDC: `create-stellar-service --network mainnet`, and its facilitator wants an API key (`FACILITATOR_AUTH`). Never pay on mainnet unless the user asked.
+- The packages are on npm: `npm create stellar-service` makes a new provider project. `@stellar-agent-services/provider-kit`, `payment-client` and `verifier` install into your own. AGENTS.md shows how.
+- Agents should start with AGENTS.md, which picks a path and points to the right reference.
+
+## Start here
+
+- [AGENTS.md](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/AGENTS.md): For AI coding agents: what this is, which path to take (new service, existing API, other language, paying client, verification, contributing), the rules that must not be broken, and when the work is done
+- [README.md](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/README.md): Project overview, packages and status
+- [SECURITY.md](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/SECURITY.md): Key boundaries every package keeps
+
+## Standard
+
+- [Provider Standard v1](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/docs/provider-standard.md): The normative spec: manifest, services, payment, jobs, capacity, errors, identity, conformance levels. Rule ids M, S, P, J, Q, E, I, V, X
+- [Standard reference for AI coding agents](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/docs/standard/README-AI.md): The spec as an implementation reference: paths, constants, the create-job algorithm, headers, states, a rule index, common mistakes
+- [Standard summary for people](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/docs/standard/README.md): What the standard does and why, without the detail
+- [Test vectors](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/packages/protocol/test-vectors/README.md): Known-answer tests for an implementation in any language: canonical JSON, binding hashes, headers, manifests, challenges, job states, errors
+- [Protocol package](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/packages/protocol/README.md): The standard as dependency-free TypeScript: types, constants and rule checks
+
+## Build a provider
+
+- [Provider setup guide](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/docs/provider-setup-guide.md): Step by step, from an idea or an existing API to a registered, verified paid service on testnet
+- [Provider Kit](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/packages/provider-kit/README.md): The library (`defineService`, `createProvider`), gateway mode, the `provider-kit` CLI, payment safety, capacity
+- [create-stellar-service](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/packages/create-stellar-service/README.md): `npm create stellar-service`: a new project around an existing API, a TypeScript service or a Python service, ready to run, try and deploy
+- [Example paid service](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/examples/paid-service/README.md): The template for a new TypeScript provider
+- [Example Python API behind the gateway](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/examples/python-upstream/README.md): An existing API made a paid service with only a config file
+
+## Build a client
+
+- [Client integrations for AI coding agents](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/docs/client-integration/README-AI.md): Signer adapters, payment method adapters, and native clients in any language, with their rules and conformance checks
+- [Client integrations summary](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/docs/client-integration/README.md): The same, for people
+- [Payment client design](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/docs/payment-client.md): Approval, spending policy, journal, payment and recovery
+- [Payment client package](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/packages/payment-client/README.md): `PaymentClient`, the `stellar-pay` CLI and a testnet walkthrough
+- [Agent Wallet page](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/apps/wallet/README.md): The web page where a person approves and pays a service
+
+## Verify
+
+- [Verification](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/docs/verification.md): Checks C1–C7, receipts, badges and the Stellar 8004 Validation Registry
+- [Verifier package](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/packages/verifier/README.md): The `verifier` CLI and library
+
+## Job recovery
+
+- [Job recovery](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/docs/job-recovery.md): How a lost response is recovered without paying twice, and how uncertain payments are decided on chain
+- [Job recovery for AI coding agents](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/docs/recovery/README-AI.md): Invariants, file map and spec mapping for changing recovery code
+- [Job recovery summary](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/docs/recovery/README.md): The same, for people
+
+## Tools for coding agents
+
+- [MCP server](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/packages/dev-mcp/README.md): Spec rules, docs, manifest validation and provider checks as MCP tools. It never pays
+- [Claude Code plugin](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/plugins/stellar-agent-services/README.md): Skills for building providers and clients, and for verifying them
+
+## Optional
+
+- [SOW closeout](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/docs/sow-closeout.md): Readiness, remaining acceptance work, testnet deployment and evidence handoff
+- [Contributing](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/CONTRIBUTING.md): How changes are made: the spec first, then the kit, client and verifier
+- [ERC compatibility](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/docs/erc-compatibility.md): How the standard lines up with ERC-8126 (agent verification) and ERC-8196 (agent authenticated wallet)
+- [Developer experience improvements](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/docs/dx-improvements.md): What each phase of the developer-experience work changed for providers, and how it was checked
+- [Manifest JSON Schema](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/packages/protocol/schemas/manifest.schema.json): The schema every manifest must pass [M9]
+- [Gateway config JSON Schema](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/packages/provider-kit/schemas/gateway-config.schema.json): The schema of `provider.config.json`
+- [Implementation plan](https://raw.githubusercontent.com/AlgoriaLabs/stellar-agent-services/main/IMPLEMENTATION_PLAN.md): The project plan and its weekly milestones

package/repository/packages/create-stellar-service/README.md

@@ -0,0 +1,143 @@
+# create-stellar-service
+
+`npm create stellar-service` makes a project that sells an AI service on Stellar: agents pay per call in USDC through
+x402, under [Provider Standard v1](../../docs/provider-standard.md). The project runs, takes a paid testnet call and
+goes live as it comes, with no wallet needed until it goes live.
+
+```text
+$ npm create stellar-service
+
+Project folder [my-stellar-service]: captioner
+What are you making?
+  1. Wrap an API you already run, in any language (no code changes)
+  2. A new service in TypeScript
+  3. A new service in Python (FastAPI)
+Pick 1, 2 or 3 [1]: 1
+Your API's OpenAPI document, or the URL a paid call goes to [http://127.0.0.1:8000/openapi.json]:
+In one sentence, what does it offer? Agents search for it by these words and its name.
+[Enter: the document's]: Captions for product photos, in English and Turkish.
+What does a call cost, in USDC? [0.01]: 0.05
+```
+
+Then it writes the project and installs it. Next:
+
+```bash
+cd captioner
+npm run dev       # runs it here, paid to a throwaway testnet account: no wallet needed yet
+npm run try       # pays for one call with test money, from another terminal
+npm run launch    # goes live: one approval in your wallet, then Fly.io
+```
+
+`npm run launch` opens a page where your own wallet (Freighter, xBull, Albedo and others) approves the USDC trustline,
+the Stellar 8004 registration and a request for verification, in one go. Then it saves `PAY_TO` and `AGENT_ID`,
+deploys to Fly.io if you say yes, and waits until the service answers at its public address. `npm run status` shows
+where it stands at any time.
+
+The project depends on the Provider Kit released with this command. To try changes not released yet, run it from a
+clone of the repository, built once (`npm install && npm run build`):
+
+```bash
+node packages/create-stellar-service/dist/index.js captioner
+```
+
+From a clone, it packs the Provider Kit into the project's `vendor/` folder, so the project installs and builds by
+itself, in Docker too.
+
+## What it makes
+
+| Kind | You get |
+| --- | --- |
+| `wrap` | The [gateway](../provider-kit/README.md#gateway-mode) in front of an API you already run, in any language, with no code changes. With an OpenAPI document (FastAPI serves `/openapi.json`), `provider-kit init --openapi` makes a service of each POST endpoint it can call; without one, a starter service calls the URL you give. |
+| `typescript` | A new service with the [Provider Kit library](../provider-kit/README.md#library-in-short): `src/server.ts` and an example service to replace, `src/services/summarize.ts`. |
+| `python` | A new FastAPI app, `app.py`, with the gateway in front of it, and one container that runs both. |
+
+Every project has `.env` (the settings, kept out of git) and `.env.example`, a `Dockerfile` that keeps the job
+database on a volume at `/data`, a `fly.toml` for Fly.io, a `README.md`, and these scripts:
+
+| Script | What it does |
+| --- | --- |
+| `npm run dev` | Starts the service, or the gateway (and the Python kind's API), at http://localhost:8787. With `PAY_TO` empty it is paid to a throwaway testnet account ([`provider-kit dev`](../provider-kit/README.md#the-throwaway-payout-account)) |
+| `npm run try` | Pays for one call with test money, from a throwaway testnet account, and starts the service for it when it isn't running ([`provider-kit try`](../provider-kit/README.md#trying-a-paid-call)) |
+| `npm run check` | Checks the provider against the standard and shows how agents see it |
+| `npm run launch` | Takes it live: one page in your wallet for the trustline, the 8004 registration and verification, then the deploy ([`provider-kit launch`](../provider-kit/README.md#launching)) |
+| `npm run status` | Where it stands, from running here to verified, and the command to run next |
+| `npm run deploy` | Deploys again to Fly.io (`fly deploy`) |
+| `npm start` | Starts it for production: `PUBLIC_ORIGIN` must be your HTTPS origin |
+
+A gateway config reads `baseUrl`, `payTo`, `store` and the agent id from `.env` (`env:PUBLIC_ORIGIN`, `env:PAY_TO`,
+`env:JOB_DB_PATH`, `env:AGENT_ID`), so the same file runs on a laptop and in a container.
+
+**Fly.io.** `fly.toml` names the app after the folder, so the public address, `https://<app>.fly.dev`, is known before
+the first deploy: `launch` registers the service with it, writes `PUBLIC_ORIGIN`, `PAY_TO` and `AGENT_ID` under
+`[env]`, and deploys once. The job database lives on a volume Fly makes on the first deploy. Another host works too:
+`npm run launch -- --url https://your.domain --no-deploy`.
+
+**Python.** With [uv](https://docs.astral.sh/uv/) installed, `npm run dev` starts the API with
+`uv run --with-requirements requirements.txt`, so there is no virtual environment to make. Without it, the next steps
+give the two commands that make `.venv`.
+
+## Mainnet
+
+`--network mainnet` makes a project that takes real USDC on `stellar:pubnet`. What changes:
+
+- **The facilitator.** Payments settle through OpenZeppelin's facilitator, `https://channels.openzeppelin.com/x402`,
+  which Stellar's docs list for mainnet (x402.org's settles testnet only). It wants an API key: get one at
+  [channels.openzeppelin.com/gen](https://channels.openzeppelin.com/gen) and set `FACILITATOR_AUTH="Bearer <key>"` in
+  `.env`. A gateway config sends it as `"facilitatorHeaders": { "Authorization": "env:FACILITATOR_AUTH" }`; the
+  TypeScript service reads it in `src/server.ts`. Without it, the service stops at start and says so.
+- **The RPC.** `SOROBAN_RPC_URL` in `.env` starts as `https://mainnet.sorobanrpc.com`, the RPC the Stellar 8004 SDK
+  uses. Mainnet has no default one. For production traffic, an [RPC provider](https://developers.stellar.org/docs/data/apis/rpc/providers)'s
+  is safer.
+- **No test money.** There is no throwaway account and no `npm run try`. `npm run launch` sets up the account clients
+  pay in your own wallet, which needs a few XLM, and `npm run dev` runs once `PAY_TO` is set.
+- **The deploy.** `launch` stages `FACILITATOR_AUTH` and `SOROBAN_RPC_URL` as Fly secrets. A TypeScript service reads its
+  network from `STELLAR_NETWORK`, which `launch` also writes to `fly.toml`. It won't call a deploy live while it takes
+  payments on another network than the one it registered on.
+
+To take a testnet project to mainnet, make these changes by hand: in a gateway config, `network`, `facilitator`,
+`facilitatorHeaders` and `rpcUrl`; in a TypeScript project's `.env`, `STELLAR_NETWORK=stellar:pubnet`. In both, add
+`FACILITATOR_AUTH` and `SOROBAN_RPC_URL` to `.env`. Then empty `PAY_TO` and `AGENT_ID` (testnet's agent ids don't exist
+on mainnet), delete `DEV_PAY_TO`, and run `npm run launch`.
+
+## For scripts and coding agents
+
+Flags answer every question. Without a terminal it asks nothing, and `--kind` is needed:
+
+```bash
+create-stellar-service captioner --kind wrap --openapi http://127.0.0.1:8000/openapi.json \
+  --description "Captions for product photos, in English and Turkish." --price 0.05
+```
+
+| Flag | Answers |
+| --- | --- |
+| `--kind wrap\|typescript\|python` | What to make |
+| `--openapi <file \| url>` | The API's OpenAPI document (`wrap`). It is read first, so nothing is written for an API that isn't running. With a file whose servers are relative, `--upstream` is the API's base URL. |
+| `--upstream <url>` | Without `--openapi`: the URL a paid call goes to (`wrap`) |
+| `--description <text>` | One sentence on what it offers: search matches it and the name |
+| `--name <text>` | The provider's name. Default: the folder's, or the document's title. |
+| `--price <usdc>` | What a call costs, in USDC. Default `0.01`. |
+| `--network testnet\|mainnet` | Where clients pay. Default `testnet`, with test money. `mainnet` takes real USDC: see [Mainnet](#mainnet). |
+| `--wallet`, `--pay-to <G…>` | Set up the payout account now in your wallet, or use an address you have. Without either, nothing is needed until `npm run launch`. |
+| `--yes` | Take the defaults for the questions no flag answers |
+
+`--wallet` opens a page in the user's browser, so a coding agent asks the user first. It signs nothing itself. So
+does `npm run launch` later: a coding agent runs it with `--no-open` and gives the user the link.
+
+## Safety
+
+- **No secret key, anywhere.** It never asks for one, makes one or writes one. The payout account is set up in the
+  developer's own wallet, on `provider-kit launch`'s approval page, and only its public address is saved. Until then,
+  `npm run dev`'s throwaway testnet account has no key anyone keeps.
+- **It never pays.** `npm run try` pays later, when the developer runs it, from a throwaway account with test money.
+- **Testnet unless asked.** Every project starts on `stellar:testnet`; only `--network mainnet` makes a mainnet one.
+- **Nothing is overwritten.** It refuses a folder that already has files in it.
+
+## Files
+
+| File | Contents |
+| --- | --- |
+| `src/main.ts` | The questions, the flags, and the run: write, install, the gateway config, the payout account if asked |
+| `src/files.ts` | The files each kind writes: `package.json` and its scripts, `.env`, the README, the Python kind's gateway config, and the templates filled in |
+| `src/kit.ts` | Where the Provider Kit comes from: a clone (packed into `vendor/`) or npm, and the npm overrides a project needs |
+| `src/index.ts` | The command |
+| `templates/` | The code and Dockerfiles each kind starts from, and `fly.toml` |

package/repository/packages/dev-mcp/README.md

@@ -0,0 +1,51 @@
+# @stellar-agent-services/dev-mcp
+
+An MCP server for coding agents that build on [Provider Standard v1](../../docs/provider-standard.md): a provider,
+a gateway config, a native implementation or a paying client. It answers from this repository's documents and runs
+the verifier's unpaid checks.
+
+**It holds no key and never pays.** It is not the payment client's MCP server, which would let an agent hire
+providers. That one is planned in [packages/payment-client](../payment-client/README.md).
+
+| Tool | What it does |
+| --- | --- |
+| `list_docs` | The documentation index, [llms.txt](../../llms.txt) |
+| `read_doc` | One document from that index, by repository path (`AGENTS.md`, `docs/provider-standard.md`) or llms.txt URL. Nothing outside the index can be read. |
+| `search_docs` | Lines of the indexed documents that contain every term of a query, as `path:line` |
+| `get_spec_rule` | A rule of the standard by id (`J13`, `[M5]`), with its section |
+| `validate_manifest` | Check C1 on a manifest document before it is served: JSON Schema [M9], the rules it can't express, service schemas, SHOULD rules. Same code as the verifier. |
+| `check_provider` | `verifier check` on a running provider: C1, C2, C3, C6 and an unpaid C7 burst. C4 and C5 need a payer, so they are skipped. |
+
+## Use
+
+```bash
+# Claude Code
+claude mcp add stellar-agent-services -- npx -y @stellar-agent-services/dev-mcp
+```
+
+Any other MCP client takes the same command as a stdio server:
+
+```json
+{
+  "mcpServers": {
+    "stellar-agent-services": { "command": "npx", "args": ["-y", "@stellar-agent-services/dev-mcp"] }
+  }
+}
+```
+
+Installed from npm, it reads the documents packed with it in `repository/`, from the same commit as its code. Run from
+a clone instead (`node packages/dev-mcp/dist/index.js`, after `npm install && npm run build`), it reads the clone's
+documents, so `git pull && npm run build` updates it.
+
+As a library, `createServer(options)` returns the `McpServer`. `options.verify` passes options to
+`verifyProvider()`, such as an offline provider's `fetch` in tests. It never takes a payer.
+
+## Files
+
+| File | Contents |
+| --- | --- |
+| `src/server.ts` | `createServer()`: the tools |
+| `src/docs.ts` | The llms.txt index, document reads and search, spec rule parsing |
+| `src/index.ts` | The stdio entry point |
+| `scripts/pack-docs.mjs` | Before npm packs the package: copies llms.txt and every document it links to into `repository/` |
+| `test/server.test.ts` | Every tool through a real MCP client; `check_provider` against the verifier's offline provider |

package/repository/packages/payment-client/README.md

@@ -0,0 +1,98 @@
+# @stellar-agent-services/payment-client
+
+The buyer side: approval, spending policy, a hash-chained journal, payment and job recovery. The design is in
+[docs/payment-client.md](../../docs/payment-client.md).
+
+**Status: proof of concept.** The core flow works end to end on Stellar testnet with the built-in signer and
+payment method, both in Node (the `stellar-pay` CLI) and in the browser (the minimal web page in
+[apps/wallet](../../apps/wallet)). The MCP server, browser-wallet and passkey signers come later and reuse this core.
+
+Signers and payment methods are strategies: the core keeps every safety step, and adapters for other wallets or
+payment infrastructure plug in without changing it (docs/payment-client.md, "Strategies"). To build one, see
+[docs/client-integration](../../docs/client-integration/README.md).
+
+```ts
+const client = new PaymentClient({
+  signer: localKeySigner(secret, "stellar:testnet"), // or a wallet adapter
+  methods: [x402ExactStellar()],                      // the default
+  policy, journal, secrets,
+});
+```
+
+The main entry point runs in Node and the browser. Journal storage depends on where it runs:
+
+| Entry point | Contents |
+| --- | --- |
+| `@stellar-agent-services/payment-client` | The core, the built-in signer and payment method |
+| `…/node` | `fileJournalStorage`, `fileSecretStore`: files only the owner can read |
+| `…/browser` | `indexedDbJournalStorage`, `indexedDbSecretStore`: IndexedDB with strict durability |
+| `…/conformance` | The checks every adapter must pass |
+
+| File | Contents |
+| --- | --- |
+| `src/client.ts` | `PaymentClient`: `quote()` (nothing signed), `pay()` (signs once), `decline()`, `recover()` (never pays) |
+| `src/strategies.ts` | The `Signer` and `PaymentMethod` interfaces |
+| `src/local-key-signer.ts` | The built-in signer: a secret key in this process |
+| `src/x402-exact-stellar.ts` | The built-in payment method: x402 `exact` on Stellar, the only one Provider Standard v1 allows |
+| `src/conformance.ts` | Checks that every signer and payment-method adapter must pass (`./conformance` entry point) |
+| `src/policy.ts` | Spending policy with ERC-8196 field names; `checkPolicy()` fails closed |
+| `src/verification.ts` | Application-trusted verification source; binds evidence to the approved manifest, payee, network and validity window [V1] |
+| `src/journal.ts` | Append-only, hash-chained journal; job tokens kept apart in a `SecretStore` |
+| `src/file-storage.ts` | Journal and job-token storage in files (`./node` entry point) |
+| `src/browser-storage.ts` | Journal and job-token storage in IndexedDB (`./browser` entry point) |
+| `src/manifest.ts` | Fetches and validates a provider manifest |
+| `src/onchain.ts` | Confirms the settlement transaction on chain |
+| `src/cli.ts` | `stellar-pay`, the PoC surface |
+
+## Try it on testnet
+
+```bash
+npm install && npm run build
+
+# A provider wallet (it only needs a USDC trustline) and a payer wallet with testnet USDC.
+STELLAR_PAY_HOME=~/.stellar-pay-provider npx stellar-pay wallet create
+STELLAR_PAY_HOME=~/.stellar-pay-provider npx stellar-pay wallet fund --usdc 0
+npx stellar-pay wallet create
+npx stellar-pay wallet fund --usdc 2          # buys testnet USDC on the testnet DEX
+
+# The sample provider, paid to the provider wallet's address.
+PAY_TO=G... node examples/paid-service/dist/server.js
+
+# Pay, with an approval prompt.
+MANIFEST=http://localhost:8787/.well-known/stellar-agent-services.json
+npx stellar-pay services $MANIFEST --dev
+npx stellar-pay pay $MANIFEST text-stats '{"text":"Hello agents."}' --dev
+```
+
+Job Recovery: start the provider with `DRILL_LOSE_RESPONSE=1 REPORT_DELAY_SECONDS=8`, pay `delayed-report`,
+then run the `stellar-pay recover <job-id> --dev` command it prints. `stellar-pay jobs` and
+`stellar-pay journal verify` show the journal.
+
+`followPaymentUncertain: true` optionally follows an uncertain job within `followSeconds` while the provider
+reconciles it [J13]. It only reads the original job and never pays again [J11]. The default returns uncertainty
+immediately, so a UI can offer manual recovery. `provider-kit try` enables the bounded wait.
+
+## Verification policy
+
+Configured verification limits are checked at `quote()` and again at `pay()`, before signing [V1]. Install a
+`verificationSource` in `PaymentClientOptions` to supply authenticated evidence. Without a source, or when it
+returns missing, stale, mismatched or unreadable evidence, a payment requiring verification is blocked.
+
+- `minVerificationScore` keeps ERC-8196's name and meaning: the **maximum allowed risk score**, 0–100, lower is
+  safer. It compares with the source's `riskScore`, not a receipt's higher-is-better conformance score.
+- `stellar.minProviderLevel` is the minimum Provider Standard §8 level, 0–3.
+- Even a configured value of zero requires evidence. Leaving both fields unset requires no source.
+- Sources are trusted application code. They must authenticate validators and receipt/registry data, bind the
+  answer to the requested subject, set `checkedAt` and `expiresAt`, and bound their network calls. Never use a
+  provider's own claims as proof. No built-in registry/risk-source adapter is supplied yet.
+- Recovery collects an already paid job without consulting the source or signing again [J11], [J13].
+
+See [the design](../../docs/payment-client.md#verification-source) for the interface and trust boundary.
+
+## Not done in the PoC
+
+- No built-in Validation Registry or ERC-8126 risk-source adapter. Configured verification limits fail closed
+  until the application supplies its own trusted source.
+- The wallet secret is a plain file (mode 600). Testnet only.
+- No MCP server yet.
+- Only the built-in signer and method. Adapters for other wallets come later, each in its own package.

package/repository/packages/protocol/README.md

@@ -0,0 +1,15 @@
+# @stellar-agent-services/protocol
+
+Provider Standard v1 as code. It holds the manifest, job, receipt and header definitions that every other
+package shares. Specification: [docs/provider-standard.md](../../docs/provider-standard.md).
+
+| Path | Contents |
+| --- | --- |
+| [`schemas/manifest.schema.json`](schemas/manifest.schema.json) | The manifest JSON Schema (2020-12) |
+| [`schemas/verification-receipt.schema.json`](schemas/verification-receipt.schema.json), [`schemas/validation-request.schema.json`](schemas/validation-request.schema.json) | The two Validation Registry documents: the verifier's receipt and the owner's request |
+| [`test-vectors/`](test-vectors) | Known-answer tests that implementations in any language can use |
+| `src/` | Types (manifest, `JobView`, `Problem`, `PaymentReceipt`, `VerificationReceipt`, `ValidationRequest`), constants and the reference checks: `canonicalJson`, `bindingHash`, `checkManifestRules`, `checkChallenge`, `stellarAddressKind`, `canTransition`, `chargedFor`, `conformanceLevel`, `validationRequestHash`, `validationRequestDataUri` |
+
+- No runtime dependencies and no signing code, so the read-only discovery server can import it safely.
+- It ships the schema rather than a validator. To validate a manifest, run any JSON Schema 2020-12 validator,
+  then `checkManifestRules()` (spec §2.4).