@officexapp/vidfarm-devcli 0.21.62 → 0.21.64

package/.agents/skills/dollarplatoon-skill/skill/staging.md

@@ -0,0 +1,178 @@
+# Building against staging
+
+Staging is a complete, independent copy of Dollar Platoon on a test chain. It is the environment
+to build against: same code, same API surface, its own accounts, and money that costs nothing to
+be wrong with.
+
+## Contents
+
+- The two stages, side by side
+- Where the documentation lives on each stage
+- Getting an account and a key
+- Getting testnet money
+- Autologin, so a link lands somewhere useful
+- What staging has that production does not
+- What is NOT production-ready — read before you ship
+- Moving an integration from staging to production
+
+---
+
+## The two stages, side by side
+
+| | Staging | Production |
+|---|---|---|
+| Frontend | `https://staging.dollarplatoon.com` | `https://dollarplatoon.com` |
+| API | `https://staging.dollarplatoon.com/api` | `https://dollarplatoon.com/api` |
+| Chain | **Base Sepolia** (chain id `84532`) | Base mainnet (chain id `8453`) |
+| USDC | **MockUSDC** `0xE4E5…c6a8` — worthless by design | Real USDC `0x8335…2913` |
+| Treasury | `0x932B9D4CA0e11D7859C43F7e58492F2C6206D485` | `0xE4E5…c6a8` |
+| Accounts | Entirely separate. Your production key does **not** work here. | |
+| `inbound_order` | **Available** | Not deployed — see below |
+| Inbound email | `…@fwd.zoomgtm.com`, with a `staging.` infix in the address | same domain, no infix |
+
+The two Treasury addresses are not a copy-paste error, and neither is production's Treasury
+matching staging's MockUSDC: they are the same deployer account at the same nonce on two
+different chains. Nothing is shared between them.
+
+Everything in the rest of this skill is written with production URLs. To read it as a staging
+integrator, substitute the host — every path is identical. `POST /gigs` means
+`POST https://staging.dollarplatoon.com/api/gigs`.
+
+## Where the documentation lives on each stage
+
+This skill is served as plain Markdown from whichever stage you are pointed at:
+
+```
+https://staging.dollarplatoon.com/SKILL.md          the index
+https://staging.dollarplatoon.com/skill/orders.md   any linked page
+```
+
+`/skill.md`, `/skill` and `/skill/` all resolve to the index too, case-insensitively.
+
+**The links inside these files are absolute production URLs.** That is a deliberate trade — one
+copy of the text, not one per stage — but it means an agent following them from staging silently
+crosses over to production's copy. The two are kept identical, so the *content* is the same; if
+you are pinning a version, fetch siblings from the host you started on rather than following the
+link as written.
+
+## Getting an account and a key
+
+Accounts are email plus a one-time code. There are no passwords, and a staging account is
+created by the first login.
+
+```json
+POST /auth/send-otp    { "email": "you@example.com" }
+POST /auth/verify-otp  { "email": "you@example.com", "code": "1234" }
+→ { "email": "you@example.com", "api_key": "…" }
+```
+
+A first login also **auto-provisions a hot wallet** on Base Sepolia. Logging in again returns the
+existing key rather than rotating it, so a login never breaks a running agent. For a fleet of
+agents, `POST /admin/users/provision` with an `x-admin-key` header is idempotent — see
+[quickstart.md](https://dollarplatoon.com/skill/quickstart.md).
+
+**Membership is the credential for everything gig-shaped.** There is no public marketplace on
+either stage: `GET /gigs` answers `410`. A worker needs an active mailbox in a gig before they
+can poll it, and — on an order machine — a buyer needs an active mailbox before they can place
+an order at all. The way in is always an invite link from the gig owner
+(`POST /gigs/:id/invites`). A `pending_approval` mailbox is not enough.
+
+## Getting testnet money
+
+Two different tokens, and you need both:
+
+- **MockUSDC** is what gigs and orders are denominated in. It has no faucet route on the API. Ask
+  the platform owner to mint some to your hot wallet address, which you can read from
+  `GET /wallets`.
+- **Base Sepolia ETH** is gas. It matters more than it looks: on an order machine the **buyer**
+  signs their own deposit transaction from their own hot wallet, so a buyer with no gas cannot
+  place an order however much MockUSDC they hold. Any public Base Sepolia faucet works.
+
+Balances: `GET /wallets/:alias_id/balances` returns both.
+
+## Autologin, so a link lands somewhere useful
+
+Append `?api_key=` to **any** staging URL to sign in and land on that exact page in one step:
+
+```
+https://staging.dollarplatoon.com/gigs?api_key=YOUR_API_KEY
+https://staging.dollarplatoon.com/gigs/GIG_01HX...?api_key=YOUR_API_KEY
+```
+
+The key is validated, the session stored, and `api_key` scrubbed from the address bar and
+history. Compose it with `?hide_navbar=true&hide_logo=true` for an embed. See
+[web-pages.md](https://dollarplatoon.com/skill/web-pages.md) for every page and param.
+
+> **A URL containing `api_key` grants full account access to anyone who sees it.** On staging the
+> money is fake and the risk is only your test data; the habit still matters, because the same
+> link shape works in production.
+
+## What staging has that production does not
+
+**`inbound_order` — the order machine mode — runs on staging only.** A full order has been taken
+end to end there on Base Sepolia: deposit, deliver, approve, settle, reveal. Production has none
+of it, and would refuse: its Treasury migration has not run and its deposit-id secret is unset,
+so a publish-with-deposit would `500` by design rather than take money it could not settle.
+
+If you are building against `inbound_order`, staging is not a rehearsal — it is the only place it
+exists. See [orders.md](https://dollarplatoon.com/skill/orders.md).
+
+## What is NOT production-ready — read before you ship
+
+Stated plainly, because the difference between the stages is not only "one has fake money".
+
+- **The wallet encryption key rotation has not run — on either stage.** Hot wallet private keys
+  are encrypted with a key that is the published development default. On production that is 782
+  real wallets. The dual-key read path that makes rotation possible is deployed to staging only.
+  **Do not treat a Dollar Platoon hot wallet as cold storage on either stage.** Withdraw earnings
+  to a wallet you control (`POST /wallets/:alias_id/transfer`).
+- **The production Treasury migration has not happened.** Production still runs the old contract,
+  which has no per-task deposits, no undo, and no reserved-balance guard. Every `inbound_order`
+  feature depends on the new one.
+- **The maintenance flag does not exist.** There is no way to quiesce the money routes on either
+  stage, so a platform migration cannot cleanly stop the world. This is the platform's problem,
+  not yours, but it means a production cutover is not a background event.
+- **`GET /public/read-url` signs any S3 key for any share-token holder.** Unfixed on both stages.
+  Anything offloaded to S3 — a large task body, an uploaded file — should be treated as readable
+  by anyone holding any share token on the platform. Keep secrets in `private_details` and
+  `private_note`, which are not S3-backed.
+- **Staging carries test debris.** Some gigs sit on retired Treasuries with stale MockUSDC and
+  unsettled rollups, and a little unattributed dust exists in old contracts. If a *very* old
+  staging gig behaves oddly around money, check its `contract_address` before assuming a bug.
+
+## Moving an integration from staging to production
+
+Three things change and nothing else does:
+
+1. **The host.** `staging.dollarplatoon.com` → `dollarplatoon.com`. Every path is the same.
+2. **The API key.** Accounts do not cross over. Provision or log in again against production.
+3. **The money is real.** Same code paths, same rounding, same 110% budgeting rule on outbound
+   gigs — and the same total absence of a reversal. There is no dispute resolution and no refund
+   after a payout on either stage. See
+   [platform.md](https://dollarplatoon.com/skill/platform.md).
+
+What does **not** carry over: any `inbound_order` shop, because production has no such mode yet.
+Build the rest of your integration against production if you like; build that half against
+staging and wait.
+
+`GET /health` tells you which stage answered, which is worth asserting once at startup:
+
+```json
+GET /health → { "status": "ok", "stage": "staging", "timestamp": "..." }
+```
+
+## Tell the two apart without trusting a hostname
+
+```bash
+curl -s https://staging.dollarplatoon.com/api/health
+```
+
+```json
+{ "stage": "staging",
+  "chain": { "chain_id": 84532, "chain_name": "Base Sepolia", "is_testnet": true },
+  "treasury_address": "0x932B…D485", "usdc_address": "0xE4E5…c6a8" }
+```
+
+`is_testnet` is the field to branch on. `stage` is a label somebody typed into an env file;
+`chain_id` is asked of the node, and it is the one that decides whether the money is real. Treat an
+unrecognised chain id as a testnet — the safe default is "do not send real funds here".