Grant
b6758cf30a
teardown-stage2.sh stops every Stage 2 run (daemon + docs + sandbox), kills any orphaned sandbox dev server on :4311 the onboarding-tester left behind, and stops the regtest BTCPay docker stack + volumes (--keep-btcpay to leave it up). README documents it as the always-run cleanup step, and adds a harvest note: on a clean run, check whether the existing public docs already cover the success story before adding anything.
80 lines
4.1 KiB
Markdown
80 lines
4.1 KiB
Markdown
# Keysat onboarding harness
|
|
|
|
A disposable test rig that runs the global **`onboarding-tester`** agent against
|
|
Keysat's developer SDK-integration journey, to find every place the *published
|
|
docs* leave a newcomer stuck — and, on a clean run, to harvest a publishable
|
|
"all it took was X, Y, Z" walkthrough.
|
|
|
|
The premise (from `~/Projects/standards/guides/onboarding-tester.md`): the agent
|
|
is a fresh adopter who may use **only the published docs corpus**, never Keysat
|
|
source. The harness builder (you) may read Keysat freely; the agent may not.
|
|
|
|
## What a run sets up
|
|
|
|
| Piece | What it is | Disposable via |
|
|
|-------|------------|----------------|
|
|
| Fixture daemon | a fresh `keysat` release binary on `127.0.0.1:<port>`, throwaway SQLite, fresh issuer keypair | `teardown.sh` |
|
|
| Provisioning | a **merchant-onboard** scoped key minted with the fixture's master key (the operator's job, not the agent's) | — |
|
|
| Docs corpus | `keysat-docs/` served over HTTP — the only how-to source the agent may read | `teardown.sh` |
|
|
| Sandbox | a pristine Next.js/TS proof-of-work (`sandbox-template/`) copied to `/tmp/onboarding-tester/`, with one ungated "Pro export" to gate | `teardown.sh` |
|
|
|
|
The fixture's dummy `BTCPAY_URL` is never dialed in this path: **Stage 1 is
|
|
license issuance + SDK integration, no payments.**
|
|
|
|
## Usage
|
|
|
|
```sh
|
|
./run.sh # boot + provision + serve docs + sandbox; writes AGENT_BRIEF.md
|
|
# → feed runs/<id>/AGENT_BRIEF.md to the onboarding-tester agent
|
|
./teardown.sh runs/<id> # stop daemon + docs server, remove sandbox
|
|
./teardown.sh runs/<id> --purge # also delete the run dir
|
|
```
|
|
|
|
Individual stages (`boot-fixture.sh`, `provision.sh`, `serve-docs.sh`,
|
|
`make-sandbox.sh`) can be run on their own; each reads/writes
|
|
`runs/<id>/state.env` and `runs/current` points at the active run.
|
|
|
|
## The loop
|
|
|
|
1. `./run.sh`, then run the `onboarding-tester` agent on the brief.
|
|
2. Read `runs/<id>/reports/friction.md`. If `completed-clean`, harvest the
|
|
walkthrough into `keysat-docs/agent.html`. Otherwise fix the highest-severity
|
|
**doc** gaps (additively — document missing API/how-to; don't rewrite
|
|
marketing copy), tear down, and re-run on a fresh fixture.
|
|
3. Repeat until `completed-clean`.
|
|
|
|
## Stage 2 (buyer pays on regtest) — built, `completed-clean`
|
|
|
|
Lives in `stage2/`. Boots a **sandbox** daemon (`KEYSAT_SANDBOX_MODE=1`) wired to
|
|
a Dockerized BTCPay **regtest** stack and grants the agent `merchant-onboard` +
|
|
`payment_providers:write` so it connects BTCPay (regtest) and drives a test buyer
|
|
payment end to end. Connecting a *mainnet* wallet stays operator-only by design —
|
|
that boundary is a feature, not a gap.
|
|
|
|
```sh
|
|
(cd stage2/btcpay-regtest && docker compose -p keysat-btcpay up -d) # one-time
|
|
./stage2/btcpay-regtest/probe.sh # mints the BTCPay store token into .live-env (one-time)
|
|
./stage2/run-stage2.sh # boots sandbox daemon + regtest wiring + scoped key
|
|
# feed runs/<id>/AGENT_BRIEF.md to the onboarding-tester agent
|
|
./stage2/teardown-stage2.sh # WHEN DONE: stop daemon(s) + docs + sandbox dev server + BTCPay stack
|
|
```
|
|
|
|
- `stage2/btcpay-regtest/` — the BTCPay regtest compose + de-risk probe (`FINDINGS.md`).
|
|
- `stage2/validate-gate.sh` — end-to-end gate check (deny mainnet/undetermined, allow regtest).
|
|
- `stage2/buyer-pay.sh` — the test buyer's wallet (pay invoice on regtest + mine).
|
|
- `stage2/teardown-stage2.sh` — full cleanup: tears down every Stage 2 run, kills any orphaned
|
|
sandbox dev server (`:4311`), and stops the BTCPay docker stack + volumes (`--keep-btcpay`
|
|
to leave it up between runs). **Always run this when finished** — the agent can leave a
|
|
daemon, a docs server, or an `npm run dev` behind.
|
|
- `stage2/STAGE2-RESULT.md` — convergence + the publishable walkthrough.
|
|
|
|
**Harvesting on a clean run:** do NOT reflexively bolt a new success story onto the public
|
|
HTML. First check whether `keysat-docs/agent.html` (the connect workflow + worked example)
|
|
and the docs already cover the buyer-pays + SDK-gating case well enough; only propose
|
|
additions for a genuine gap, with operator approval.
|
|
|
|
## Requirements
|
|
|
|
`cargo`, `node`/`npm`, `python3`, `curl`, `jq`, `openssl`. (Docker is only
|
|
needed for Stage 2.)
|