settld 0.1.2 → 0.2.0

package/docs/pilot-kit/gtm-pilot-playbook.md

@@ -0,0 +1,182 @@
+# GTM Pilot Playbook (Autonomous Workflows)
+
+This playbook turns Settld pilot work into repeatable pipeline and expansion motion.
+
+## 1) Pilot objective
+
+Win a paid pilot that proves three things in 30-60 days:
+
+- Adoption: teams can reach first verified invoice fast.
+- Economic value: decisions and payout workflow move faster with fewer disputes.
+- Reliability: verification and buyer decision workflows are stable under real usage.
+
+## 2) ICP and sequencing
+
+Start with workflows where SLA ambiguity already causes payment friction:
+
+1. Agent-driven service workflows (fastest path, clear completion evidence)
+2. Delivery/security/field operations (high compliance pressure, recurring SLA checks)
+3. Maintenance/inspection workflows (higher contract value, longer cycle)
+
+Buyer personas:
+
+- Ops owner (workflow + dispute pain)
+- Finance/procurement owner (payable controls + auditability)
+- Security/compliance reviewer (trust and evidence integrity)
+
+## 3) 6-week pilot motion
+
+Week 0:
+
+- Scope one vendor, one buyer, one contract workflow.
+- Lock target KPIs and baseline current process.
+- Configure tenant settings, SLA template, webhook endpoint.
+
+Week 1-2:
+
+- Run onboarding wizard and first production-like uploads.
+- Validate buyer approve/hold flow and receipt downloads.
+- Confirm webhook delivery into buyer/vendor systems.
+
+Week 3-4:
+
+- Increase run volume and edge-case coverage (amber/red paths).
+- Tune template overrides and policy behavior.
+- Track decision latency and dispute deltas weekly.
+
+Week 5-6:
+
+- Publish KPI delta vs baseline.
+- Package evidence + case study draft.
+- Convert pilot to annual expansion plan.
+
+## 4) Outreach templates
+
+### A) Cold outreach (ops leader)
+
+Subject: Reduce automation-work invoice disputes in 30 days
+
+Hi {{Name}},
+
+Teams using external agents and automation vendors often lose time in invoice review because SLA evidence and approvals are fragmented.
+Settld gives buyers a single verification link with signed artifact evidence and approve/hold decisions.
+
+For a pilot, we scope one workflow and target:
+
+- faster buyer decision cycle
+- fewer disputed invoices
+- audit-ready packet export per run
+
+Open to a 20-minute fit check next week?
+
+### B) Security/procurement intro
+
+Subject: Pilot review packet for autonomous-work verification controls
+
+Hi {{Name}},
+
+Sharing our pilot security/procurement packet:
+
+- architecture and data flow
+- redaction and retention behavior
+- deterministic verification and audit outputs
+
+If useful, we can run a narrow pilot with your current workflow and keep controls aligned to your review process.
+
+### C) Follow-up after demo
+
+Subject: Proposed pilot scope and KPI gates
+
+Thanks for the walkthrough.
+
+Proposed pilot scope:
+
+- Workflow: {{workflow}}
+- Duration: {{6 weeks}}
+- KPI gates:
+  - first verified invoice < {{target}}
+  - buyer decision within 24h > {{target}}
+  - dispute rate reduction > {{target}}
+
+If this looks right, we can start setup this week.
+
+## 5) Pilot success criteria
+
+Use these default gates unless the customer sets stricter values:
+
+- Time-to-first-verified-invoice: < 30 minutes
+- Buyer decision within 24h: > 50%
+- Webhook delivery success: > 99%
+- Verification latency p95: < 10 seconds
+- Run listing latency (100+ runs): < 500ms
+- Dispute rate delta vs baseline: at least 25% reduction
+
+Must-have exit criteria:
+
+- At least one full approve path and one hold path demonstrated.
+- Buyer confirms artifact-derived evidence is sufficient for decisions.
+- Finance/procurement accepts exported audit packet format.
+
+## 6) Weekly pilot operating cadence
+
+Weekly 45-minute review with customer:
+
+1. KPI dashboard review (adoption/economic/reliability)
+2. Incident and edge-case review (red/amber failures)
+3. Template/policy updates needed
+4. Next-week volume and success targets
+
+Internal Settld cadence:
+
+- Monday: KPI check + risk log update
+- Wednesday: technical blockers + integration follow-up
+- Friday: customer summary + expansion signal scoring
+
+## 7) Case study format
+
+Use this exact structure for repeatable proof:
+
+1. Customer context
+2. Baseline process and pain
+3. Pilot scope (workflow, parties, duration)
+4. Implementation (wizard, verify flow, buyer decisions, webhooks)
+5. Measured results (before vs after)
+6. Security/compliance posture summary
+7. Customer quote + rollout plan
+
+Required evidence bundle for every case study:
+
+- KPI table with baseline and pilot values
+- sample verification status outputs (green/amber/red)
+- decision receipt examples
+- audit packet index snapshot
+- webhook delivery success stats
+
+## 8) Expansion conversion checklist
+
+Before conversion:
+
+- Multi-team onboarding plan approved
+- Contract templates mapped into SLA templates
+- Buyer users and approval roles defined
+- Reporting/export requirements confirmed
+
+Expansion triggers:
+
+- >2 workflows requesting integration
+- finance team asks for monthly audit exports
+- procurement asks to standardize verification language across vendors
+
+## 9) Kill criteria
+
+Stop or re-scope if, by week 3:
+
+- no measurable KPI movement,
+- buyer does not use decision workflow,
+- integration owner cannot maintain webhook/ops path.
+
+Every GTM and product action must improve at least one of:
+
+- adoption speed,
+- auto-approval rate,
+- retention/expansion probability.

package/docs/pilot-kit/offline-verify.md

@@ -0,0 +1,33 @@
+# Offline verification (buyer/audit)
+
+This is the “no SaaS required” verification path.
+
+## 1) Download artifacts
+
+From the Magic Link page, download:
+
+- `bundle.zip` (the canonical input)
+- `verify.json` (hosted `VerifyCliOutput.v1`, for reference)
+
+## 2) Verify locally with `settld-verify`
+
+Extract the bundle ZIP to a directory, then run:
+
+```sh
+node packages/artifact-verify/bin/settld-verify.js --format json --strict --invoice-bundle /path/to/extracted/bundle > out.verify.json
+```
+
+### Trust anchors (strict mode)
+
+Strict verification requires governance trust roots to be provided out-of-band. If you have a trust file:
+
+```sh
+export SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON='{"key_...":"-----BEGIN PUBLIC KEY-----..."}'
+export SETTLD_TRUSTED_TIME_AUTHORITY_KEYS_JSON='{"key_...":"-----BEGIN PUBLIC KEY-----..."}'
+```
+
+Then rerun the strict command above.
+
+## 3) Compare results deterministically
+
+`VerifyCliOutput.v1` is deterministic (stable ordering of errors/warnings and normalized paths). You can archive it and replay verification later.

package/docs/pilot-kit/procurement-one-pager.md

@@ -0,0 +1,50 @@
+# Verify Cloud (Magic Link) — Procurement one-pager
+
+Verify Cloud is a hosted (or self-hosted) verification layer for **evidence-backed invoices**. Vendors submit a Settld bundle (typically `InvoiceBundle.v1` or `ClosePack.v1`), and buyers get a deterministic verification result plus audit-grade exports.
+
+## What you get
+
+- A read-only “Green / Amber / Red” hosted report link per invoice
+- Deterministic verifier output (`VerifyCliOutput.v1`) suitable for archiving and automation
+- An **audit packet** export (bundle ZIP + hosted verification JSON + receipt surfaces + non-normative PDF summary + decision record, when present)
+- Offline verifiability: download the bundle ZIP and re-verify using `settld-verify` under buyer-controlled trust anchors
+
+## What you need to adopt (pilot)
+
+- Decide trust configuration:
+  - governance trust roots (buyer-supplied)
+  - pricing signer keys (buyer-supplied)
+- Decide enforcement policy:
+  - strict vs compat default mode
+  - whether Amber (warnings) is acceptable for payment eligibility
+- (Optional) enable buyer email OTP + RBAC for inbox and exports
+
+## Integration options
+
+- Vendor upload via ingest key (simple HTTP upload)
+- Webhooks for `verification.completed` / `verification.failed`
+- CSV export for AP workflows
+- Support bundle export for debugging without SSH/screen recordings
+
+## Security posture (high level)
+
+- Hostile ZIP defenses: traversal/zip-slip, symlinks, duplicates, encrypted entries, zip-bomb budgets
+- Rate limiting and concurrency budgets (upload + verify)
+- Tenant settings secrets encrypted at rest when `MAGIC_LINK_SETTINGS_KEY_HEX` is configured
+- Explicit data retention enforcement (heavy artifacts deleted after retention)
+- Redaction allowlist for UI/PDF/CSV/support exports (HTML escaped + truncated deterministically)
+
+## One-email security review
+
+Download the **Security & Controls packet** (zip). It includes:
+
+- data inventory + retention behavior summary
+- threat model + budgets/defaults
+- redaction allowlist manifest
+- this procurement one-pager and `security-qa.md`
+- file checksums for internal handling/audit
+
+## Offline verification (buyer/auditor)
+
+See `offline-verify.md`.
+

package/docs/pilot-kit/rfp-clause.md

@@ -0,0 +1,46 @@
+# Draft RFP clause (evidence-backed invoices)
+
+This clause is intended to be copy/pasted and then tuned to your policy (strict vs amber, evidence types, SLA/acceptance criteria, etc.).
+
+## Verifiable invoice artifacts
+
+Vendor MUST provide an evidence-backed invoice artifact for each billing period that is independently verifiable without access to vendor systems.
+
+The artifact MUST be one of:
+
+- `InvoiceBundle.v1` (invoice claim + metering + pricing terms + evidence references), or
+- `ClosePack.v1` (invoice claim + metering + pricing terms + evidence references + optional SLA/acceptance evaluation surfaces).
+
+The artifact MUST:
+
+- be an archived bundle (ZIP or directory) containing payload evidence and protocol metadata
+- include a manifest committing (via hashes) to the file set (excluding verifier outputs to avoid circular hashing)
+- include attestations and signatures binding verification receipts to the manifest hash and bundle head attestation hash
+- include buyer-signed pricing terms (e.g. `PricingMatrixSignatures.v2` referencing a canonical pricing matrix hash)
+- support strict verification under explicit buyer-supplied governance trust anchors (provided out-of-band)
+
+## Payment eligibility
+
+Buyer MAY require that an invoice is eligible for payment only when:
+
+- verification is **strict** and **passes** with **no errors**, and
+- warnings (Amber) are either:
+  - disallowed (auto-hold), or
+  - allowed only under an explicit buyer policy, with manual review/audit trail.
+
+## Deliverables and auditability
+
+Vendor MUST provide, per invoice:
+
+- the bundle ZIP bytes (for archiving)
+- deterministic verifier output (`VerifyCliOutput.v1`) and any embedded producer receipt (when present)
+
+Vendor SHOULD provide:
+
+- a hosted view-only verification link for buyer review
+- an “audit packet” export (bundle ZIP + hosted verification JSON + receipt surfaces + non-normative summary PDF + decision record, where applicable)
+
+## Key lifecycle / rotation
+
+Buyer MUST be able to rotate vendor ingest keys without downtime.
+

package/docs/pilot-kit/roi-calculator-template.csv

@@ -0,0 +1,2 @@
+date,tenantId,invoiceId,bundleSha256,mode,ok,verificationOk,warningsCount,errorsCount,disputeAvoided,notes
+

package/docs/pilot-kit/security-qa.md

@@ -0,0 +1,153 @@
+# Verify Cloud (Magic Link) — Security Q&A (pilot)
+
+This document is designed to be pasted into common procurement/security portals with minimal edits.
+
+If you need a single attachment, download the **Security & Controls packet** — it includes this Q&A, an architecture one-pager, a data inventory, and checksums.
+
+## Product summary (what is Verify Cloud?)
+
+Verify Cloud accepts a vendor-submitted **Settld bundle** (typically `InvoiceBundle.v1` or `ClosePack.v1`), verifies it deterministically, and exposes:
+
+- a read-only hosted report page (Green/Amber/Red)
+- deterministic machine-readable outputs (`VerifyCliOutput.v1`)
+- export bundles for audit (audit packet, support bundle)
+
+## Data handling
+
+### What is uploaded?
+
+- A ZIP containing a Settld bundle directory (evidence + protocol metadata + manifest + attestations).
+
+### What is stored?
+
+Storage is filesystem-backed under `MAGIC_LINK_DATA_DIR` (often a PVC mount). Per run, Verify Cloud stores:
+
+- **Bundle ZIP bytes (optional)**: `zips/<token>.zip` (controlled by `TenantSettings.v2.artifactStorage.storeBundleZip`)
+- **Hosted verification output** (`VerifyCliOutput.v1`): `verify/<token>.json`
+- **Redacted public summary** (what feeds hosted UI / exports): `public/<token>.json`
+- **Non-normative PDF summary (optional)** (redacted): `pdf/<token>.pdf` (when invoice claim is present; controlled by `TenantSettings.v2.artifactStorage.storePdf`)
+- **Producer receipt** (when present inside the bundle): `receipt/<token>.json`
+- **ClosePack evaluation/index surfaces** (when present): `closepack/<token>/...`
+- **Webhook delivery records** (optional, no secrets): `webhooks/{attempts,record}/<token>_*.json`
+- **Minimal immutable run record** (metadata-only, for support/accounting): `runs/<tenant>/<token>.json`
+
+Verify Cloud does **not** separately parse and persist raw evidence file contents outside of the uploaded bundle ZIP bytes (other than the allowlisted, redacted “render model” fields used for UI/PDF/CSV/support exports).
+
+### Retention (defaults + enforcement)
+
+- Default retention: `TenantSettings.v2.retentionDays` (default `30` days).
+- Optional per-vendor / per-contract overrides: `TenantSettings.v2.vendorPolicies[*].retentionDays`, `TenantSettings.v2.contractPolicies[*].retentionDays`.
+- Enforcement:
+  - a background maintenance sweeper deletes retained artifacts (default daily), and
+  - uploads opportunistically trigger a sweep before quota checks.
+
+After retention, heavy artifacts (bundle ZIP, verify JSON, PDFs, cached exports, webhook records) are deleted and downloads return `410 retained`. The metadata-only run record remains for support/accounting.
+
+## Security controls
+
+### Authentication models
+
+- **Admin API access**: `x-api-key` header (set `MAGIC_LINK_API_KEY`).
+- **Vendor ingest**: vendor-scoped ingest keys (`Authorization: Bearer <ingestKey>`) with upload-only capability.
+- **Buyer access (optional)**: email OTP login restricted to allowlisted domains (`TenantSettings.v2.buyerAuthEmailDomains`) and per-email roles (`TenantSettings.v2.buyerUserRoles`).
+- **Decision capture (optional)**: approve/hold can be gated by OTP (`TenantSettings.v2.decisionAuthEmailDomains`).
+
+### RBAC roles (buyer)
+
+- `viewer`: view inbox and exports
+- `approver`: export CSV/audit packet, approve/hold
+- `admin`: settings, onboarding packs, support bundle, security packet
+
+### Audit logging
+
+Verify Cloud appends JSONL audit records for:
+
+- tenant settings changes
+- ingest key creation/revocation
+- buyer login events (when enabled)
+- settlement decision capture (approve/hold)
+
+Exports:
+
+- Security & Controls packet (monthly)
+- Audit packet (monthly; deterministic)
+- Optional archival export sink (S3-compatible): push monthly audit packet ZIP + CSV (tenant-configurable)
+- Support bundle (time-bounded; redacted settings + metadata-first)
+
+### Token security (hosted report links)
+
+- Token format: `ml_` + 24 random bytes (192-bit entropy).
+- Token TTL: configurable via `MAGIC_LINK_TOKEN_TTL_SECONDS` (default 7 days).
+- Tokens are revocable via the admin API.
+
+### Rate limiting and budgets
+
+Verify Cloud enforces:
+
+- upload size bound (`MAGIC_LINK_MAX_UPLOAD_BYTES`, default 50 MiB)
+- tenant + IP rate limiting (`TenantSettings.v2.rateLimits.*`; default `uploadsPerHour=100`, `verificationViewsPerHour=1000`)
+- verification timeout (`MAGIC_LINK_VERIFY_TIMEOUT_MS`, default 60s)
+- concurrency caps (`MAGIC_LINK_MAX_CONCURRENT_JOBS`, `MAGIC_LINK_MAX_CONCURRENT_JOBS_PER_TENANT`)
+- queued verify workers with retries + dead-letter accounting (`MAGIC_LINK_VERIFY_QUEUE_*`)
+- hostile ZIP extraction budgets (entry count, path length, per-file bytes, total bytes, compression ratio)
+
+### Secrets handling
+
+- Tenant settings secrets (webhook secret, delegated signer bearer token, etc.) are encrypted at rest when `MAGIC_LINK_SETTINGS_KEY_HEX` is configured (AES-256-GCM).
+- Support exports redact secrets by default (e.g. webhook secret material is removed).
+
+## Threat model (short)
+
+Verify Cloud is designed to resist:
+
+- hostile ZIP attacks (zip-slip traversal, symlinks, duplicates/overwrite, encrypted entries, zip bombs)
+- resource exhaustion (huge uploads, decompression bombs, long-running verification)
+- HTML injection / XSS in rendered fields
+- token guessing / link leakage
+
+Mitigations are summarized in the exported **Security & Controls packet** along with the exact budgets/defaults in effect for that deployment.
+
+## Cryptography / verification integrity
+
+- Bundles are verifiable offline: download the bundle ZIP and run `settld-verify` under buyer-controlled trust anchors.
+- Trust anchors are supplied out-of-band by the buyer (governance roots, pricing signer keys). Hosted verification can run in `strict` or `compat` depending on trust configuration/policy.
+- Cryptographic primitives: SHA-256 hashes and Ed25519 signatures; canonical JSON is used where required for stable hashing.
+
+## Infrastructure expectations
+
+- Verify Cloud is intended to run behind TLS termination (ingress/load balancer). The service itself is HTTP-only by default.
+- Encryption at rest is provided by your underlying storage layer (PVC/disk + cloud/KMS configuration).
+
+## Compliance posture
+
+- Verify Cloud is not currently SOC 2 audited.
+- It is designed with controls that map well to SOC 2 expectations (authn/authz, audit logging, retention enforcement, secure defaults, and exportability for audit).
+
+## Incident response / vulnerability reporting
+
+- Security issues / vulnerability reports: email `aiden@settld.work` (private disclosure).
+- Operational support: see `docs/SUPPORT.md` and `docs/ONCALL_PLAYBOOK.md`.
+
+## Configuration knobs (most commonly requested)
+
+- Environment:
+  - `MAGIC_LINK_API_KEY` — admin access
+  - `MAGIC_LINK_SETTINGS_KEY_HEX` — encrypt secrets at rest (tenant settings)
+  - `MAGIC_LINK_DATA_DIR` — storage location (mount point)
+  - `MAGIC_LINK_TOKEN_TTL_SECONDS` — report link TTL
+  - `MAGIC_LINK_MAX_UPLOAD_BYTES` — upload cap
+  - `MAGIC_LINK_VERIFY_TIMEOUT_MS` — verification timeout
+  - `MAGIC_LINK_RATE_LIMIT_UPLOADS_PER_HOUR` — default per-tenant upload limit (overrideable per tenant)
+  - `MAGIC_LINK_MAX_CONCURRENT_JOBS`, `MAGIC_LINK_MAX_CONCURRENT_JOBS_PER_TENANT` — concurrency caps
+  - `MAGIC_LINK_VERIFY_QUEUE_WORKERS`, `MAGIC_LINK_VERIFY_QUEUE_MAX_ATTEMPTS`, `MAGIC_LINK_VERIFY_QUEUE_RETRY_BACKOFF_MS` — verify queue worker behavior
+  - `MAGIC_LINK_RUN_STORE_MODE`, `MAGIC_LINK_RUN_STORE_DATABASE_URL` — run metadata control-plane store mode (`fs|dual|db`)
+  - `MAGIC_LINK_MAINTENANCE_INTERVAL_SECONDS` — retention sweep interval (maintenance runner)
+- Tenant settings (API):
+  - `retentionDays`, `vendorPolicies[*].retentionDays`, `contractPolicies[*].retentionDays`
+  - `artifactStorage.storeBundleZip`, `artifactStorage.storePdf`, `artifactStorage.precomputeMonthlyAuditPackets`
+  - `archiveExportSink` (S3 archival export sink)
+  - `rateLimits` (per-tenant/per-IP windows for upload/view/decision/OTP endpoints)
+  - `buyerNotifications` (buyer recipient + delivery mode settings)
+  - `buyerAuthEmailDomains`, `buyerUserRoles`
+  - `decisionAuthEmailDomains`
+  - `webhooks[*]` (with secrets encrypted-at-rest when settings key is configured)

package/docs/pilot-kit/security-summary.md

@@ -0,0 +1,35 @@
+# Security summary (Verify Cloud / Magic Link)
+
+This is a short, operator-facing security posture summary for pilots.
+
+## Hostile ZIP ingestion
+
+Magic Link ingestion uses a single safe unzip implementation:
+
+- rejects absolute paths and traversal (`..`) after normalization
+- rejects backslashes and drive letters (`:`)
+- rejects duplicate entries
+- rejects encrypted entries
+- rejects symlinks via external attributes
+- enforces budgets:
+  - max entry count
+  - max per-file bytes
+  - max total uncompressed bytes
+  - max path length
+  - max compression ratio (zip bombs)
+- extracts into a fresh temp dir and never overwrites existing files
+
+## Deterministic outputs (CI / audit friendly)
+
+- Verification output is deterministic JSON (`VerifyCliOutput.v1`) and is intended to be archived.
+- Audit packet ZIP is deterministic and bundles:
+  - bundle ZIP
+  - hosted verify JSON
+  - embedded producer receipt (if present)
+  - PDF summary (non-normative)
+  - decision record (if present)
+
+## Multi-implementation parity
+
+The repo includes a Python reference verifier and a conformance pack; parity is tested in CI.
+

package/docs/plans/2026-02-13-mcp-spike-design.md

@@ -0,0 +1,113 @@
+# MCP Stdio Spike (Sprint 23) Design
+
+Date: 2026-02-13
+
+Owner: Platform
+
+Tickets: `STLD-T2305`, `STLD-T2306`
+
+## Goal
+
+Prove that an MCP-compatible agent can reliably discover and invoke a *curated* set of Settld tools over `stdio`, using a **restricted API key** (not an ops token).
+
+This is a spike: correctness and minimal compatibility matter more than feature breadth. Production hardening (SSE transport, rate limiting, etc.) is explicitly deferred to Sprint 25.
+
+## Non-Goals (S23)
+
+- No SSE transport.
+- No multi-tenant discovery. Tenant is configured via env.
+- No generic “HTTP proxy tool”. We expose curated tools only.
+- No persistence inside the MCP server. It is a stateless bridge to the Settld API.
+
+## Transport + Protocol
+
+- Transport: `stdio`
+- Protocol: JSON-RPC 2.0 message stream.
+- Framing: newline-delimited JSON; additionally accepts `Content-Length:` framed messages for compatibility.
+- Required methods:
+  - `initialize`
+  - `tools/list`
+  - `tools/call`
+- Optional methods (implemented as no-ops / trivial):
+  - `ping`
+  - `notifications/initialized` (ignored)
+
+## Auth Model
+
+- The MCP server requires `SETTLD_API_KEY` and uses `x-proxy-api-key` for all API calls.
+- The API key must have the minimum scopes needed for:
+  - registering agents
+  - marketplace RFQ/bid/accept
+  - wallet credit (requires `x-settld-protocol` header)
+  - agent run event appends (requires `x-settld-protocol` + `x-proxy-expected-prev-chain-hash`)
+  - run dispute transitions (requires `x-settld-protocol`)
+
+No ops token handling is included in the spike.
+
+## Configuration
+
+Environment variables:
+
+- `SETTLD_BASE_URL` (default: `http://127.0.0.1:3000`)
+- `SETTLD_TENANT_ID` (default: `tenant_default`)
+- `SETTLD_API_KEY` (required)
+- `SETTLD_PROTOCOL` (optional; if unset the server attempts to discover via `GET /healthz` response header `x-settld-protocol`, falling back to `1.0`)
+
+## Tool Surface (Curated)
+
+### `settld.create_agreement`
+
+Creates a real marketplace-backed agreement by executing:
+
+1. `POST /agents/register` (payer)
+2. `POST /agents/register` (payee)
+3. `POST /agents/{payerAgentId}/wallet/credit` (fund payer)
+4. `POST /marketplace/rfqs`
+5. `POST /marketplace/rfqs/{rfqId}/bids`
+6. `POST /marketplace/rfqs/{rfqId}/accept` (returns `runId`, agreement, settlement)
+
+Returns IDs needed for subsequent tools: `payerAgentId`, `payeeAgentId`, `rfqId`, `bidId`, `runId`, `settlementId`, `agreementId`.
+
+### `settld.submit_evidence`
+
+Appends an agent run event:
+
+- `GET /agents/{agentId}/runs/{runId}/events` to obtain current `prevChainHash`
+- `POST /agents/{agentId}/runs/{runId}/events` with `type=EVIDENCE_ADDED` and `x-proxy-expected-prev-chain-hash`
+
+### `settld.settle_run`
+
+Moves a run to terminal state (which triggers auto-resolution in the Settld API):
+
+- `GET /agents/{agentId}/runs/{runId}/events` (prevChainHash)
+- `POST /agents/{agentId}/runs/{runId}/events` with `type=RUN_COMPLETED` (or `RUN_FAILED`)
+
+### `settld.open_dispute`
+
+Opens a dispute for a resolved run settlement:
+
+- `POST /runs/{runId}/dispute/open`
+
+## Error Handling
+
+- API errors are surfaced as tool results with `isError=true` and a text payload containing `{ statusCode, message, details }` when available.
+- JSON-RPC protocol errors use standard JSON-RPC error responses.
+
+## Latency Measurement
+
+Each tool call returns `durationMs` measured inside the MCP process (wall-clock). This measures bridge overhead + API time; it is sufficient for spike validation and can be compared against direct API calls later.
+
+## Testing
+
+- A `node --test` smoke test exercises:
+  - `initialize`
+  - `tools/list` (tool names + schemas)
+  - one `tools/call` against a local stub HTTP server (no secrets required)
+
+## Roll Forward Path (S25)
+
+- Add SSE transport.
+- Add richer auth modes (service tokens, per-tool scopes, per-tenant selection).
+- Add stronger redaction of tool outputs.
+- Add structured telemetry and rate limiting.
+