settld 0.1.2 → 0.1.5

package/docs/ops/THROUGHPUT_DRILL_10X.md

@@ -0,0 +1,48 @@
+# Throughput Drill 10x Runbook
+
+Objective: execute `STLD-T177` as an auditable gate artifact, not a one-off benchmark.
+
+## Command
+
+```bash
+BASE_URL=http://127.0.0.1:3000 \
+OPS_TOKEN=ops_ci \
+TENANTS=3 \
+ROBOTS_PER_TENANT=3 \
+BASELINE_JOBS_PER_MIN_PER_TENANT=10 \
+THROUGHPUT_MULTIPLIER=10 \
+DURATION=120s \
+TARGET_P95_MS=5000 \
+MAX_FAILURE_RATE=0.05 \
+node scripts/ci/run-10x-throughput-drill.mjs
+
+BASE_URL=http://127.0.0.1:3000 \
+OPS_TOKEN=ops_ci \
+node scripts/ci/run-10x-throughput-incident-rehearsal.mjs
+```
+
+If local `k6` is not installed, the runner automatically falls back to `docker` (`grafana/k6:0.48.0`).
+Set `ALLOW_DOCKER_K6_FALLBACK=0` to require native `k6`.
+
+## Outputs
+
+- K6 summary: `artifacts/throughput/10x-drill-k6-summary.json`
+- Gate report: `artifacts/throughput/10x-drill-summary.json`
+- Incident rehearsal report: `artifacts/throughput/10x-incident-rehearsal-summary.json`
+
+## Gate conditions
+
+- k6 exits with status `0`
+- `http_req_duration p(95)` <= `TARGET_P95_MS`
+- `http_req_failed rate` <= `MAX_FAILURE_RATE`
+- ingest rejection rate <= `MAX_INGEST_REJECTED_PER_MIN`
+
+## Incident rehearsal checklist
+
+- Run `node scripts/ci/run-10x-throughput-incident-rehearsal.mjs` immediately after the load drill.
+- Confirm `artifacts/throughput/10x-incident-rehearsal-summary.json` has `verdict.ok=true`.
+- Verify rehearsal checks are green:
+  - degraded-mode signal was emitted,
+  - rollback returned active policy to stable,
+  - communications markers were captured in `/ops/audit`,
+  - command-center post-rollback breach count is zero.

package/docs/ops/TRUST_CONFIG_WIZARD.md

@@ -0,0 +1,47 @@
+# Trust Config Wizard
+
+The Trust Config Wizard is a lightweight way to bootstrap SLA policy configuration for common autonomous workflows.
+
+## What it provides
+
+- Built-in SLA policy templates for `delivery` and `security` verticals.
+- Template rendering with override support for SLA and metrics fields.
+- A validation path for preflight checks before policy deployment.
+
+## API endpoint
+
+- `GET /ops/sla-templates`
+  - Scope: `ops_read`
+  - Optional query: `vertical=delivery|security`
+  - Response: `SlaPolicyTemplateCatalog.v1` template catalog
+
+Example:
+
+```sh
+curl -sS "http://localhost:3000/ops/sla-templates?vertical=security" \
+  -H "x-proxy-ops-token: <ops_read_token>" | jq
+```
+
+## CLI usage
+
+Run via npm script:
+
+```sh
+npm run trust:wizard -- list --format json
+```
+
+Supported commands:
+
+- `list [--vertical delivery|security] [--format json|text]`
+- `show --template <templateId> [--format json|text]`
+- `render --template <templateId> [--overrides-json <json>] [--out <path>] [--format json|text]`
+- `validate --template <templateId> [--overrides-json <json>] [--format json|text]`
+
+Example render command:
+
+```sh
+npm run trust:wizard -- render \
+  --template delivery_standard_v1 \
+  --overrides-json '{"metrics":{"targetCompletionMinutes":60}}' \
+  --format json
+```

package/docs/ops/X402_PILOT_WEEKLY_METRICS.md

@@ -0,0 +1,76 @@
+# X402 Pilot Weekly Reliability Metrics
+
+Use this report to publish weekly reliability numbers for the Circle-backed paid tool pilot.
+
+The report is artifact-driven and summarizes paid MCP/x402 runs under `artifacts/mcp-paid-exa`.
+
+## Why this exists
+
+Before broad provider expansion, the pilot must prove:
+
+- reserve behavior is stable,
+- token and provider signature verification are stable,
+- settlement execution is stable.
+
+This command produces a deterministic JSON report you can commit or attach to release notes.
+
+## Run
+
+```bash
+npm run ops:x402:pilot:weekly-report -- \
+  --artifact-root artifacts/mcp-paid-exa \
+  --days 7 \
+  --out artifacts/ops/x402-pilot-reliability-report.json
+```
+
+Optional reliability gates:
+
+```bash
+npm run ops:x402:pilot:weekly-report -- \
+  --artifact-root artifacts/mcp-paid-exa \
+  --days 7 \
+  --max-reserve-fail-rate 0.10 \
+  --max-token-verify-fail-rate 0.01 \
+  --max-provider-sig-fail-rate 0.01 \
+  --min-settlement-success-rate 0.98
+```
+
+If threshold gates are supplied, command exit code is non-zero when any gate fails.
+
+## Output schema
+
+`X402PilotReliabilityReport.v1` includes:
+
+- `runCounts`
+  - `runsInWindow`
+  - `infraBootFailures`
+  - `toolCallAttempts`
+  - `successfulPaidCalls`
+- `metrics`
+  - `timeToFirstPaidCallMs`
+  - `reserveFailRate`
+  - `tokenVerifyFailRate`
+  - `providerSigFailRate`
+  - `settlementSuccessRate`
+  - `replayDuplicateRate`
+- `samples`
+  - run ids for reserve/token/signature/settlement failures
+- `verdict`
+  - threshold check results when thresholds are passed
+
+## Metric notes
+
+- `reserveFailRate` is inferred from attempted runs with `gateway_error` today.
+- Infrastructure boot failures are excluded from economic reliability denominators.
+- `replayDuplicateRate` uses provider replay counters emitted by paid demo artifacts (`provider-replay-probe.json` or `summary.replayCounters`).
+
+## Recommended weekly publish set
+
+- `timeToFirstPaidCallMs`
+- `reserveFailRate`
+- `tokenVerifyFailRate`
+- `providerSigFailRate`
+- `settlementSuccessRate`
+- `replayDuplicateRate`
+
+Keep provider expansion gated on these metrics, not on raw demo volume.

package/docs/ops/tool-call-disputes-holdback.md

@@ -0,0 +1,52 @@
+# Tool-Call Disputes and Holdback (Ops Runbook)
+
+## When To Use Party Open vs Ops Override
+
+- Use **party open** when:
+  - payer/payee is within the hold challenge window
+  - the dispute is expected and can be resolved by normal arbitration timelines
+
+- Use **ops/admin override** when:
+  - the challenge window is closed but funds are still held (exception path)
+  - an incorrect hold configuration needs remediation
+  - you need to open a case for forensic/incident reasons
+
+Ops override requires `ops_write` and must include an explicit override reason in the case metadata.
+
+## How Holds Get “Stuck”
+
+A hold can remain in `held` if:
+
+- an arbitration case exists for the hold and the case `status` is not `closed`
+- the verdict has been issued but the adjustment was not applied (should be rare; indicates an idempotency/DB failure)
+- escrow balances are inconsistent (wallet has insufficient escrow locked to complete release/refund)
+
+## Debug Checklist
+
+1. Identify the `holdHash`:
+   - from the hold record (FundingHold.v1)
+   - or from the arbitration case metadata (`metadata.holdHash`)
+2. List tool-call arbitration cases for the agreement:
+   - `GET /tool-calls/arbitration/cases?agreementHash=...`
+3. Verify the case metadata:
+   - `caseType: "tool_call"`
+   - `agreementHash`, `receiptHash`, `holdHash` are present and 64-hex sha256
+4. If the case is not closed, the auto-release tick will skip the hold.
+
+## Maintenance Tick
+
+The tool-call holdback maintenance tick:
+
+- will **not** auto-release holds referenced by any non-closed tool-call arbitration case
+- will skip holds whose challenge window has not yet ended
+- operates on held escrow funds only
+
+Endpoint:
+
+- `POST /ops/maintenance/tool-call-holdback/run`
+
+Suggested alerting:
+
+- Alert on `tool_call_holdback_auto_release_skipped_total{reason="arbitration_case_open"}` growth without a corresponding decrease in open case count.
+- Alert on holds blocked beyond an SLA threshold (derive from hold `createdAt` and current time).
+

package/docs/pilot-kit/PILOT_PACKAGE_SCORECARD_X402.md

@@ -0,0 +1,46 @@
+# Pilot Package + Success Scorecard (x402 Wedge)
+
+This defines the default pilot offer and measurable success gates for Settld x402 deployments.
+
+## 1. Pilot Package
+
+- Scope: 1 paid tool workflow, 1 buyer, 1 provider, 1 tenant.
+- Duration: 4-6 weeks.
+- Success proof: deterministic receipts + offline verification + export for finance.
+- Out of scope: broad marketplace rollout, unrestricted side-effect tools.
+
+## 2. Delivery Timeline
+
+1. Week 0: scope lock, baseline capture, env + keys provisioned.
+2. Week 1: first paid call in production-like flow (`402 -> retry -> verify`).
+3. Week 2-3: volume ramp + policy tuning (caps, allowlists, dispute windows).
+4. Week 4-6: KPI review, case-study artifacts, expansion decision.
+
+## 3. Scorecard (Baseline + Target)
+
+| Metric | Baseline (before Settld) | Target (pilot) | Measurement |
+|---|---:|---:|---|
+| Integration time to first paid call | > 2 days | < 1 afternoon | Start-to-first successful settled paid call |
+| Auto-resolve rate (%) | < 40% | >= 80% | `released / total verified` for in-scope runs |
+| Dispute rate (%) | > 10% | <= 5% | `disputed / settled` over pilot window |
+| Time-to-settle (p95) | > 24h | < 15m | verification-to-settlement latency |
+
+## 4. Required Evidence Artifacts
+
+- x402 gate trace (`gateId`, authorization ref, reserve id where applicable)
+- Decision + settlement binding hashes
+- Receipt export for pilot window
+- Offline verifier output sample on exported receipts
+- Weekly reliability report (`reserveFailRate`, `providerSigFailRate`, `settlementSuccessRate`)
+
+## 5. Expansion Triggers
+
+- Two or more teams request onboarding.
+- Finance requests recurring automated exports.
+- Scorecard targets met for two consecutive weekly checkpoints.
+
+## 6. No-Go / Re-scope Conditions
+
+- Integration time target misses twice.
+- Dispute rate trend worsens versus baseline.
+- Settlement reliability below threshold for two consecutive checkpoints.

package/docs/pilot-kit/README.md

@@ -0,0 +1,29 @@
+# Pilot Kit (Verify Cloud / Magic Link)
+
+This folder is the “send to prospects” kit for running a paid pilot:
+
+- Buyer materials (what the page means, what to download, how to re-verify offline)
+- Security posture summary (what we harden against)
+- Integration starting point (webhooks)
+- Simple ROI / billing templates
+
+## Recommended pilot flow
+
+1. Operator produces an `InvoiceBundle.v1` and uploads it to Verify Cloud (Magic Link).
+2. Buyer receives the link, reviews Green/Amber/Red, and (optionally) records **Approve/Hold** on the page.
+3. Buyer downloads the audit packet for archiving (bundle ZIP + deterministic JSON outputs).
+4. Operator consumes the webhook event to drive their internal workflow.
+
+## Contents
+
+- `buyer-one-pager.md` — what the buyer sees and what to do.
+- `buyer-email.txt` — copy/paste email template for sending links.
+- `offline-verify.md` — how a buyer/auditor re-verifies locally.
+- `security-summary.md` — zip and bundle hardening posture.
+- `security-qa.md` — short procurement/security questionnaire answers.
+- `architecture-one-pager.md` — deployment and data flow overview for security reviewers.
+- `procurement-one-pager.md` — procurement-facing overview (adoption + security posture).
+- `rfp-clause.md` — draft procurement / RFP language.
+- `roi-calculator-template.csv` — simple template for pilot ROI tracking.
+- `gtm-pilot-playbook.md` — outreach templates, pilot KPI gates, and case-study format.
+- `PILOT_PACKAGE_SCORECARD_X402.md` — default x402 pilot package, baseline/target scorecard, and expansion triggers.

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

@@ -0,0 +1,48 @@
+# Verify Cloud (Magic Link) — Architecture one-pager
+
+This document describes the hosted verification service used in pilots (“Verify Cloud”, implemented by the Magic Link service).
+
+## Data flow (high level)
+
+1. Vendor uploads a Settld bundle ZIP (e.g. `InvoiceBundle.v1` / `ClosePack.v1`) using a vendor-scoped ingest key.
+2. Verify Cloud stores the ZIP and runs deterministic verification in a budgeted worker.
+3. Verify Cloud writes deterministic outputs + a redacted render model.
+4. Buyer views a hosted report link and/or downloads exports (audit packet, CSV, support bundle).
+5. (Optional) webhooks deliver verification status events.
+
+## Components
+
+- **HTTP handlers**
+  - Vendor ingest: `POST /v1/ingest/:tenantId` (Bearer ingest key)
+  - Admin upload: `POST /v1/upload` (admin `x-api-key`)
+  - Hosted report/downloads: `GET /r/:token` and `GET /r/:token/<artifact>`
+  - Exports: audit packet, support bundle, security packet, CSV
+- **Verification worker**
+  - Safe unzip with explicit budgets (rejects zip-slip/symlinks/duplicates/encrypted entries/zip bombs)
+  - Deterministic verification producing `VerifyCliOutput.v1`
+- **Storage (filesystem under `MAGIC_LINK_DATA_DIR`)**
+  - Run blobs: bundle zip, verifier output, redacted summaries, PDFs, receipts, ClosePack surfaces
+  - Minimal immutable run record: `runs/<tenant>/<token>.json` (metadata-only)
+  - Audit/usage logs (JSONL) for accounting and operations
+- **Maintenance**
+  - Retention sweeper deletes heavy artifacts after effective retention windows
+
+## Trust and integrity model
+
+- Buyers supply governance trust roots and pricing signer keys out-of-band.
+- Verification can run in strict or compat mode depending on policy and configured trust.
+- Offline verifiability: the buyer can archive the bundle ZIP and deterministically re-verify it later without access to vendor systems.
+
+## Access control model
+
+- Admin API: `x-api-key` (`MAGIC_LINK_API_KEY`)
+- Vendor uploads: ingest keys (upload-only)
+- Buyer sessions (optional): email OTP allowlist + RBAC roles (`viewer|approver|admin`)
+- Decision capture (optional): email OTP gating for approve/hold
+
+## Operational exports
+
+- **Audit packet**: archive-friendly, deterministic
+- **Support bundle**: time-bounded; metadata-first; redacted settings snapshot; no raw bundles by default
+- **Security & controls packet**: threat model + budgets + retention/redaction manifests + checksums
+

package/docs/pilot-kit/buyer-email.txt

@@ -0,0 +1,19 @@
+Subject: Verified invoice link (evidence-backed)
+
+Hi,
+
+Here is your verified invoice link:
+<PASTE_MAGIC_LINK_HERE>
+
+This link provides:
+- Green/Amber/Red verification status
+- Invoice totals + line item summary
+- Stable error/warning codes when something fails
+- Downloads for audit/offline replay (bundle ZIP + deterministic verification JSON + audit packet)
+- Optional Approve/Hold decision capture with exportable record
+
+If you need to re-verify offline, download the bundle ZIP from the page and run your verifier under your trust policy.
+
+Thanks,
+<YOUR_NAME>
+

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

@@ -0,0 +1,31 @@
+# Settld Verified Invoice (Buyer one-pager)
+
+This invoice link is backed by a **cryptographically verifiable bundle** (an `InvoiceBundle.v1`) that can be archived and re-verified later, offline.
+
+## What you see on the page
+
+- **Green**: Verified with no warnings.
+- **Amber**: Verified, but warnings are present (common early: governance trust anchors not configured for strict verification).
+- **Red**: Verification failed.
+
+## What you can download
+
+- **Bundle ZIP**: the exact artifact that was verified (archive this for audit).
+- **Verification JSON** (`VerifyCliOutput.v1`): deterministic, machine-readable result (codes + hashes).
+- **Producer receipt** (if present): `verify/verification_report.json` from inside the bundle (producer-signed).
+- **Audit packet ZIP**: bundle ZIP + hosted verification JSON + any embedded receipt + PDF summary + decision record.
+- **PDF summary**: non-normative human summary for compatibility (not the source of truth).
+
+## Approve / Hold
+
+The page can record a simple **Approve / Hold** decision with a name + email + optional reason.
+
+This decision record is a **service record** (non-normative) and can be exported as `decision_record_v0.json`.
+
+## Offline re-verification (recommended for audit)
+
+1. Download the **Bundle ZIP**.
+2. Verify locally using `settld-verify` (or another conforming verifier) under your trust policy.
+
+See `offline-verify.md`.
+

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`.
+