diff --git a/AGENTS.md b/AGENTS.md
index 41e2ddd..4105d00 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -121,6 +121,22 @@ Operator-specific memories at `~/.claude/projects/-Users-macpro-Projects-keysat/
   independently confirmed**; verify the StartOS UI shows `0.2.0:57`). `publish.sh` now runs
   `make install` as step 5, so future ships auto-deploy (best-effort, non-fatal).
 
+- **Onboarding doc-harness — Stage 1 (Path 1, no payments): `completed-clean` this session.**
+  New disposable harness at `licensing-service-startos/onboarding-harness/` boots a fresh
+  fixture, mints a `merchant-onboard` key, serves `keysat-docs/` as the corpus, scaffolds a
+  pristine Next.js/TS proof-of-work (`sandbox-template/`), then runs the global
+  `onboarding-tester` agent **docs-only**. Loop converged 5→1→0 stumbles over 3 runs; the
+  publishable walkthrough is harvested into `keysat-docs/agent.html` (#worked-example). Doc
+  fixes shipped: `integrate.html` (real v0.3 SDK shape — `verify()` throws + returns
+  `VerifyOk{payload,…}`, no `valid` bool, `LicensingError`/`.code`), `agent.html`
+  (merchant-onboard role row, product/policy-create workflows, `buyer_note`→`note`, license
+  `/search` endpoint, worked example), `wire-format.html` (issuer-pubkey response shape). Also
+  `openapi.rs` (licenses `product_id` filter, removed phantom `GET /v1/admin/products`, added
+  `/v1/admin/licenses/search`, price-field notes) — **served-spec fixes; fixture was rebuilt to
+  test, but these reach the live spec only on the next daemon release.** keysat-docs static
+  fixes deploy independently. Full record: `onboarding-harness/STAGE1-RESULT.md`. **Stage 2
+  (Path 2, regtest buyer-pays) is gated on agent-payment-connect slices 3–5 below.**
+
 - **In progress — agent-payment-connect (phase 2)**. Approved spec:
   `plans/agent-payment-connect-scope.md`. Lets a scoped key connect a BTCPay provider, but
   ONLY on a sandbox daemon and ONLY for a non-mainnet network — never folded into a role
diff --git a/ROADMAP.md b/ROADMAP.md
index cbf147f..e5bbb82 100644
--- a/ROADMAP.md
+++ b/ROADMAP.md
@@ -16,8 +16,18 @@ Longer-term backlog. Near-term state lives in `AGENTS.md` → Current state.
   (never bundled into `merchant-onboard`), gated by a daemon-level **sandbox-mode flag** as the
   outer gate (production daemons reject scoped connect entirely) with a **network gate** inner
   defense (regtest/testnet/signet only, fail-closed to mainnet). BTCPay network is derived from
-  an on-chain address prefix (no `server/info` field exists). Feeds the doc-harness Path 2
-  (regtest buyer-pays). Ships after doc-harness Path 1.
+  an on-chain address prefix (no `server/info` field exists).
+- **Onboarding doc-harness — Stage 2 (Path 2, regtest buyer-pays).** Gated on slices 3–5 above.
+  Stage 1 (Path 1, no payments) shipped `completed-clean` this session — harness at
+  `licensing-service-startos/onboarding-harness/`, record in its `STAGE1-RESULT.md`. Stage 2
+  reuses the harness but boots the fixture with `KEYSAT_SANDBOX_MODE` on, stands up a Dockerized
+  BTCPay regtest stack (bitcoind regtest + NBXplorer + Postgres + BTCPay) as additional
+  disposable infra, and grants the agent `merchant-onboard` + `payment_providers:write`. Goal:
+  the agent connects BTCPay (regtest) over the API and drives a test buyer payment that activates
+  a license, with zero master-key steps. The walkthrough must be explicitly labeled
+  regtest/test-network and must state that connecting a real mainnet wallet is the one
+  operator-reserved step **by design** (a key that can redirect funds stays with the human) — a
+  security feature, not a gap.
 
 ## Packaging & distribution