settld 0.1.2 → 0.2.0

package/docs/gitbook/quickstart.md

@@ -0,0 +1,103 @@
+# Quickstart
+
+Get from zero to a verified paid agent action in minutes.
+
+## Prerequisites
+
+- Node.js 20+
+- Settld API URL
+- Tenant ID
+- Tenant API key (`keyId.secret`)
+
+## 0) One-command setup
+
+Run guided setup:
+
+```bash
+settld setup
+```
+
+The guided setup uses arrow-key menus for host/wallet/policy decisions, then asks only the next required fields.
+
+Non-interactive example:
+
+```bash
+settld setup --non-interactive \
+  --host codex \
+  --base-url http://127.0.0.1:3000 \
+  --tenant-id tenant_default \
+  --settld-api-key sk_live_xxx.yyy \
+  --wallet-mode managed \
+  --wallet-bootstrap remote \
+  --profile-id engineering-spend \
+  --smoke \
+  --out-env ./.tmp/settld.env
+```
+
+What this does:
+
+- configures host MCP wiring
+- sets runtime env and policy passport
+- applies starter profile
+- runs connectivity smoke checks
+
+## 1) Activate your host
+
+If you wrote an env file, load it:
+
+```bash
+source ./.tmp/settld.env
+```
+
+Then restart your host app (Codex/Claude/Cursor/OpenClaw) so it reloads MCP config.
+
+## 2) Verify MCP connectivity
+
+```bash
+npm run mcp:probe -- --call settld.about '{}'
+```
+
+Expected outcome:
+
+- `settld.about` succeeds
+- host can discover `settld.*` tools
+
+## 3) Run first paid call
+
+```bash
+npm run demo:mcp-paid-exa
+```
+
+Expected output includes:
+
+- `PASS artifactDir=...`
+- `gateId=...`
+- `decisionId=...`
+- `settlementReceiptId=...`
+
+## 4) Verify first receipt (proof packet)
+
+```bash
+jq -c 'first' <artifactDir>/x402-receipts.export.jsonl > /tmp/settld-first-receipt.json
+settld x402 receipt verify /tmp/settld-first-receipt.json --format json --json-out /tmp/settld-first-receipt.verify.json
+```
+
+`/tmp/settld-first-receipt.verify.json` is your deterministic verification artifact for audit/compliance.
+
+## 5) Optional: policy profile workflows
+
+```bash
+settld profile list
+settld profile init engineering-spend --out ./profiles/engineering-spend.profile.json
+settld profile validate ./profiles/engineering-spend.profile.json --format json
+settld profile simulate ./profiles/engineering-spend.profile.json --format json
+```
+
+## Troubleshooting
+
+- `SETTLD_API_KEY must be a non-empty string`
+  - ensure key is present in setup flags or shell env.
+- `BYO wallet mode missing required env keys`
+  - provide all required Circle keys in `docs/QUICKSTART_MCP_HOSTS.md`.
+- Host cannot find MCP tools
+  - rerun setup, restart host, then rerun `npm run mcp:probe`.

package/docs/gitbook/replay-and-audit.md

@@ -0,0 +1,30 @@
+# Replay and Audit
+
+Replay proves your stored settlement result still matches recomputed evaluation under the same pinned context.
+
+## Replay goals
+
+- verify decision consistency
+- detect policy/verifier drift impact
+- produce audit-ready evidence for incident/compliance reviews
+
+## Tool-call replay
+
+Use replay endpoint with agreement hash and compare:
+
+- decision outcome
+- reason codes/evaluation summary
+- pinned policy/verifier references
+- expected deterministic adjustment behavior
+
+## Audit workflow
+
+1. Fetch artifacts for subject agreement.
+2. Run replay-evaluate.
+3. Export closepack.
+4. Run offline verify.
+5. Store replay + verify reports with incident/release packet.
+
+## Release gate recommendation
+
+Make replay mismatch rate and closepack verify failures release-blocking thresholds.

package/docs/gitbook/sdk-reference.md

@@ -0,0 +1,35 @@
+# SDK Reference
+
+Settld provides JavaScript and Python SDKs to reduce raw-HTTP integration overhead.
+
+## JavaScript SDK
+
+Path: `packages/api-sdk`
+
+Typical workflow methods:
+
+- create/submit lifecycle requests
+- fetch artifacts and replay checks
+- dispute operations and status reads
+- reputation fact queries
+
+## Python SDK
+
+Path: `packages/api-sdk-python`
+
+Typical workflow methods mirror JS flow:
+
+- settlement lifecycle calls
+- dispute flow operations
+- replay checks
+- reputation reads
+
+## Integration pattern
+
+1. Keep artifact IDs in your own datastore.
+2. Treat settlement artifacts as first-class business records.
+3. Use replay + closepack verification for sensitive incident paths.
+
+## Versioning
+
+Keep SDK versions aligned with protocol/object compatibility requirements for your deployment window.

package/docs/gitbook/security-model.md

@@ -0,0 +1,58 @@
+# Security Model
+
+Settld minimizes trust assumptions in settlement outcomes by making critical claims signed, bound, and independently verifiable.
+
+## Threats this design addresses
+
+- artifact tampering after execution
+- ambiguous money movement without decision lineage
+- unauthorized economic actions outside authority scope
+- silent drift between stored decisions and replayed outcomes
+
+## Core controls
+
+## Signed artifacts + canonical hashing
+
+Critical objects are signed and hash-bound.
+
+## Authority-scoped execution
+
+Authority grants constrain spend, scope, and time.
+
+## Agreement/evidence binding
+
+Evidence must align with agreement commitments (`callId`, `inputHash`, terms).
+
+## Deterministic idempotent effects
+
+Deterministic IDs and uniqueness constraints prevent duplicate financial side effects.
+
+## Dispute legitimacy
+
+Non-admin dispute open requires signer-bound envelope proof.
+
+## Replay and closepack verification
+
+Stored outcomes can be recomputed and verified offline.
+
+## Boundaries (what Settld does not solve alone)
+
+- correctness beyond configured policy/verifier semantics
+- private key compromise
+- unsafe tenant policy configuration
+- jurisdiction-specific legal/compliance obligations by default
+
+## Operational minimums
+
+- signer key rotation + inventory controls
+- monitor replay mismatches and dispute lag
+- keep strict separation between demo/test/prod tokens
+- include closepack verify in release and incident workflows
+
+## References
+
+- `SECURITY.md`
+- `docs/spec/THREAT_MODEL.md`
+- `docs/THREAT_MODEL.md`
+- `docs/ALERTS.md`
+- `docs/ONCALL_PLAYBOOK.md`

package/docs/integrations/README.md

@@ -0,0 +1,15 @@
+# Integrations
+
+Copy/paste adoption templates and guardrails:
+
+- `github-actions.md` — composite action usage and trust anchor wiring.
+- `github-actions-verify.yml` — pasteable workflow template.
+- `openclaw/PUBLIC_QUICKSTART.md` — public npm onboarding flow for OpenClaw (`npx settld@latest setup`).
+- `openclaw/settld-mcp-skill/SKILL.md` — OpenClaw skill payload for Settld MCP.
+- `openclaw/CLAWHUB_PUBLISH_CHECKLIST.md` — publish + validation checklist for ClawHub.
+
+See also:
+
+- `docs/QUICKSTART_VERIFY.md`
+- `docs/ADOPTION_CHECKLIST.md`
+- `docs/QUICKSTART_MCP_HOSTS.md`

package/docs/integrations/github-actions-verify.yml

@@ -0,0 +1,31 @@
+name: verify bundles (settld)
+
+on:
+  workflow_dispatch:
+
+jobs:
+  verify:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Replace this with the path to the bundle produced by your pipeline.
+      # For demo/conformance, we point at committed fixtures.
+      - name: Verify bundle (strict)
+        id: verify
+        # For external adoption:
+        # uses: settld/settld/.github/actions/settld-verify@vX.Y.Z
+        uses: ./.github/actions/settld-verify
+        with:
+          bundle_path: test/fixtures/bundles/v1/jobproof/strict-pass
+          strict: "true"
+          fail_on_warnings: "false"
+          hash_concurrency: "8"
+          trust_file: test/fixtures/bundles/v1/trust.json
+          output_json_path: settld-verify-output.json
+
+      - name: Upload verification output JSON
+        uses: actions/upload-artifact@v4
+        with:
+          name: settld-verify-output
+          path: settld-verify-output.json

package/docs/integrations/github-actions.md

@@ -0,0 +1,34 @@
+# GitHub Actions integration: `settld-verify`
+
+This repo ships a **first-party composite action** that runs `settld-verify` with stable machine output (`VerifyCliOutput.v1`) and supports strict/non-strict + warning gating.
+
+## Minimal workflow (strict, archive JSON)
+
+See `docs/integrations/github-actions-verify.yml` for a pasteable workflow.
+
+For usage from another repo, reference the action by tag:
+
+```yaml
+uses: settld/settld/.github/actions/settld-verify@vX.Y.Z
+```
+
+## Trust anchors
+
+Pass a `trust.json` file (same shape as `test/fixtures/bundles/v1/trust.json`):
+
+- `governanceRoots`: map of `keyId -> publicKeyPem`
+- `timeAuthorities`: optional map of `keyId -> publicKeyPem`
+
+The action exports these to the verifier via:
+
+- `SETTLD_TRUSTED_GOVERNANCE_ROOT_KEYS_JSON`
+- `SETTLD_TRUSTED_TIME_AUTHORITY_KEYS_JSON` (when present)
+
+## What to archive for audit
+
+Recommended posture:
+
+- Archive the **bundle** itself (immutable artifact store).
+- Archive the CI `VerifyCliOutput.v1` JSON (what you verified, when, with what tool identity).
+
+If you store the bundle, you already retain `verify/verification_report.json` inside it (the signed receipt).

package/docs/integrations/openclaw/CLAWHUB_PUBLISH_CHECKLIST.md

@@ -0,0 +1,65 @@
+# ClawHub Publish Checklist (Settld MCP Skill)
+
+Use this to publish and validate the Settld OpenClaw skill safely.
+
+## 1) Pre-Publish Validation
+
+Run local MCP sanity checks first:
+
+```bash
+npm run mcp:probe
+node --test test/mcp-stdio-spike.test.js test/mcp-http-gateway.test.js test/mcp-paid-exa-tool.test.js test/mcp-paid-weather-tool.test.js
+```
+
+Confirm required files exist:
+
+- `docs/integrations/openclaw/settld-mcp-skill/SKILL.md`
+- `docs/integrations/openclaw/settld-mcp-skill/mcp-server.example.json`
+
+## 2) Prepare Skill Metadata
+
+In `SKILL.md`, verify:
+
+- `name` is unique in ClawHub
+- `description` is short and explicit
+- `version` bumped for every publish
+
+## 3) Publish To ClawHub
+
+Publish the folder `docs/integrations/openclaw/settld-mcp-skill/` as your skill package.
+
+If ClawHub UI requests install instructions, use:
+
+- command: `npx`
+- args: `-y settld-mcp`
+- env: `SETTLD_BASE_URL`, `SETTLD_TENANT_ID`, `SETTLD_API_KEY`, optional `SETTLD_PAID_TOOLS_BASE_URL`
+
+## 4) Post-Publish Smoke Test
+
+Install the skill in a clean OpenClaw environment and verify:
+
+1. Tools are discoverable (`settld.*` visible).
+2. `settld.about` succeeds.
+3. One paid call succeeds:
+   - `settld.exa_search_paid`, or
+   - `settld.weather_current_paid`
+4. Result includes `x-settld-*` verification headers.
+
+## 5) Rollback Plan
+
+If smoke fails in production:
+
+1. Unlist or disable latest skill version in ClawHub.
+2. Revert to previous working skill version.
+3. Fix and republish with incremented `version`.
+
+## 6) Release Notes Template
+
+Capture these fields each publish:
+
+- Skill version
+- Settld package version used
+- Added/changed tools
+- Known limitations
+- Validation run timestamp
+

package/docs/integrations/openclaw/PUBLIC_QUICKSTART.md

@@ -0,0 +1,95 @@
+# OpenClaw Public Quickstart (No Repo Clone)
+
+Use this when you want a public user to set up Settld from npm in a fresh machine.
+
+## 1) Install and onboard OpenClaw
+
+Follow OpenClaw docs:
+
+- https://docs.openclaw.ai/install/index
+- https://docs.openclaw.ai/start/wizard
+
+Then run onboarding:
+
+```bash
+openclaw onboard --install-daemon
+openclaw doctor
+```
+
+If `openclaw` is not on PATH yet, use the npx fallback:
+
+```bash
+npx -y openclaw@latest onboard --install-daemon
+```
+
+## 2) Run Settld setup from npm
+
+Interactive path (recommended):
+
+```bash
+npx -y settld@latest setup
+```
+
+Choose:
+
+1. `host`: `openclaw`
+2. wallet mode (`managed` recommended first)
+3. wallet bootstrap (`remote` recommended for first setup)
+4. keep preflight + smoke enabled
+5. apply a starter profile (`engineering-spend`)
+
+Non-interactive path (automation/support):
+
+```bash
+npx -y settld@latest setup \
+  --non-interactive \
+  --host openclaw \
+  --base-url https://api.settld.work \
+  --tenant-id tenant_default \
+  --settld-api-key 'sk_live_xxx.yyy' \
+  --wallet-mode managed \
+  --wallet-bootstrap remote \
+  --profile-id engineering-spend \
+  --smoke
+```
+
+## 3) Verify OpenClaw + Settld are wired
+
+Run:
+
+```bash
+openclaw doctor
+```
+
+Then from OpenClaw chat/test prompt:
+
+- `Call settld.about and return JSON.`
+
+Expected result: success payload with Settld tool metadata.
+
+## 4) Run first paid tool call
+
+From OpenClaw prompt:
+
+- `Run settld.weather_current_paid for city=Chicago unit=f and include x-settld-* headers in the response.`
+
+Expected result:
+
+- tool call succeeds
+- response includes policy/decision/settlement headers (`x-settld-*`)
+
+## 5) Verify receipt artifact (when available)
+
+If you exported a receipt JSON from your Settld environment, verify it offline:
+
+```bash
+npx -y settld@latest x402 receipt verify ./receipt.json --format json
+```
+
+## Notes for operators
+
+- Public users do not need to clone the Settld repo.
+- Public path is valid only after publishing a package version that includes the current setup flow.
+- For OpenClaw skill packaging and publish flow, see:
+  - `docs/integrations/openclaw/settld-mcp-skill/SKILL.md`
+  - `docs/integrations/openclaw/CLAWHUB_PUBLISH_CHECKLIST.md`

package/docs/integrations/openclaw/settld-mcp-skill/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: settld-mcp-payments
+description: Connect OpenClaw agents to Settld MCP for paid tool calls with quote-bound authorization and verifiable receipts.
+version: 0.1.0
+author: Settld
+---
+
+# Settld MCP Payments Skill
+
+This skill teaches OpenClaw agents to use Settld for paid MCP tool calls.
+
+## What This Skill Enables
+
+- Discover Settld MCP tools (`settld.*`)
+- Run paid tool calls with x402 challenge/authorize/retry flow
+- Return verifiable payment/settlement headers from tool responses
+- Produce audit-grade artifacts and receipts in Settld
+
+## Prerequisites
+
+- Node.js 20+
+- Settld API key (`SETTLD_API_KEY`)
+- Settld API base URL (`SETTLD_BASE_URL`)
+- Tenant id (`SETTLD_TENANT_ID`)
+- Optional paid tools base URL (`SETTLD_PAID_TOOLS_BASE_URL`)
+
+## MCP Server Registration
+
+Use the server definition in `mcp-server.example.json`.
+
+Server command:
+
+- command: `npx`
+- args: `["-y","settld-mcp"]`
+
+Required env vars:
+
+- `SETTLD_BASE_URL`
+- `SETTLD_TENANT_ID`
+- `SETTLD_API_KEY`
+
+Optional env vars:
+
+- `SETTLD_PAID_TOOLS_BASE_URL`
+- `SETTLD_PROTOCOL`
+
+## Agent Usage Pattern
+
+1. Call `settld.about` to verify connectivity.
+2. For paid search/data calls, use:
+   - `settld.exa_search_paid`
+   - `settld.weather_current_paid`
+3. For agreement lifecycle demo calls, use:
+   - `settld.create_agreement`
+   - `settld.submit_evidence`
+   - `settld.settle_run`
+   - `settld.resolve_settlement`
+
+## Smoke Prompts
+
+- "Call `settld.about` and return the result JSON."
+- "Run `settld.weather_current_paid` for Chicago in fahrenheit and include the `x-settld-*` headers."
+
+## Safety Notes
+
+- Treat `SETTLD_API_KEY` as secret input.
+- Do not print full API keys in chat output.
+- Keep paid tools scoped to trusted providers and tenant policy.
+

package/docs/integrations/openclaw/settld-mcp-skill/mcp-server.example.json

@@ -0,0 +1,12 @@
+{
+  "name": "settld",
+  "command": "npx",
+  "args": ["-y", "settld-mcp"],
+  "env": {
+    "SETTLD_BASE_URL": "http://127.0.0.1:3000",
+    "SETTLD_TENANT_ID": "tenant_default",
+    "SETTLD_API_KEY": "sk_live_xxx.yyy",
+    "SETTLD_PAID_TOOLS_BASE_URL": "http://127.0.0.1:8402"
+  }
+}
+

package/docs/kernel-compatible/capabilities.json

@@ -0,0 +1,36 @@
+{
+  "schemaVersion": "KernelCompatibleDirectory.v0",
+  "updatedAt": "2026-02-11T00:00:00.000Z",
+  "entries": [
+    {
+      "id": "reference-deterministic-latency-threshold",
+      "name": "Reference Capability: Deterministic Latency Threshold",
+      "owner": "settld",
+      "type": "reference",
+      "repoPath": "examples/reference-capabilities/deterministic-latency-threshold",
+      "deterministicVerifierRef": "verifier://settld/deterministic/latency-threshold-v1",
+      "conformanceCaseIds": [
+        "tool_call_holdback_release",
+        "tool_call_holdback_refund"
+      ],
+      "closepackVerified": true,
+      "lastVerifiedAt": "2026-02-11T00:00:00.000Z",
+      "status": "listed"
+    },
+    {
+      "id": "reference-deterministic-schema-check",
+      "name": "Reference Capability: Deterministic Schema Check",
+      "owner": "settld",
+      "type": "reference",
+      "repoPath": "examples/reference-capabilities/deterministic-schema-check",
+      "deterministicVerifierRef": "verifier://settld/deterministic/schema-check-v1",
+      "conformanceCaseIds": [
+        "tool_call_holdback_release",
+        "marketplace_run_replay_evaluate"
+      ],
+      "closepackVerified": true,
+      "lastVerifiedAt": "2026-02-11T00:00:00.000Z",
+      "status": "listed"
+    }
+  ]
+}

package/docs/marketing/agent-commerce-substrate.md

@@ -0,0 +1,78 @@
+# Settld: Commerce And Trust Substrate For Agent Tool Execution
+
+Settld is the trust and settlement layer for paid agent tool calls.
+
+In an agent economy, the unit of work is not a human checkout flow. It is an agent invoking tools. The moment those calls become paid, teams need authorization, budget controls, replay safety, verifiable execution proof, and settlement that does not collapse on micro-transaction costs.
+
+Settld exists to standardize that layer so paid tool calls are safe, composable, and auditable by default.
+
+## What Settld Is
+
+Settld is a protocol-native commerce rail for agent tools:
+
+- Payment challenge to authorization to retry (`402 -> authorize -> paid retry`).
+- Offline-verifiable SettldPay authorization tokens (`/.well-known/settld-keys.json`).
+- Provider-side cryptographic accountability (signed response proofs).
+- Receipt bindings that tie `authorizationRef`, request hash, response hash, and provider signature verification status together.
+- Provider self-publish flow (manifest -> conformance -> certified listing).
+- Batch-oriented settlement path for scalable payout economics.
+
+## What Settld Is Not
+
+- Not an agent framework.
+- Not a wallet company.
+- Not a bespoke integrations shop.
+
+Settld integrates with frameworks and wallets while owning the trust, policy, receipts, and settlement contract.
+
+## Product Promise
+
+Settld should make a paid tool call as reliable and auditable as a mature payment API:
+
+1. An agent can pay for a tool call without custom billing glue.
+2. A provider can accept payment with offline verification, not blind trust.
+3. Every call produces machine-verifiable receipts, not only logs.
+4. Finance and compliance teams can audit outcomes without trusting a mutable database.
+5. Settlement can be batched and replay-safe, so economics work at agent scale.
+
+## The Ecosystem Flywheel
+
+1. Providers scaffold paid tools from OpenAPI or HTTP.
+2. Providers publish a manifest and endpoint.
+3. Settld runs conformance and issues certification status.
+4. Certified tools become discoverable to agent builders.
+5. Agents execute with autopay and receive deterministic receipts.
+6. More trust drives more providers and more demand.
+
+The key is that new tools should be published by providers, not hand-integrated by Settld engineers.
+
+## Core CTAs
+
+Use one primary call to action per audience:
+
+- Agent builders: run paid tool demo and inspect receipts.
+- Tool providers: scaffold, publish, and certify in under 10 minutes.
+- Operators and finance: review receipt and settlement artifacts.
+
+## Metrics That Matter
+
+Track only the metrics that prove substrate adoption and reliability:
+
+- Weekly paid tool calls.
+- Reserve failure rate (7-day rolling).
+- Settlement success rate (batch execution).
+
+Optional expansion metrics:
+
+- Certified providers.
+- Time from publish to first paid call.
+- Replay rejection rate.
+
+## Near-Term Execution Sequence
+
+1. Harden real-money reserve path (Circle sandbox to constrained production pilot).
+2. Ship idempotent batch settlement worker and payout registry as default operations.
+3. Expand reference demos beyond search (weather + LLM/embeddings).
+4. Tighten publish UX so first certified paid tool is consistently under 10 minutes.
+
+This is how Settld becomes default infrastructure for paid agent tool execution instead of an integrations treadmill.