feat(skills,cli): dolibarr-sandbox-checkpoint — manage the sandbox iso-prod checkpoint

A skill + CLI group to drive the ADR-0003 sandbox lifecycle, instead of the manual
kubectl/deno/.env dance:

  arcodange sandbox checkpoint status       # liveness + is the write agent armed?
  arcodange sandbox checkpoint refresh --yes # re-seed iso-prod (DESTRUCTIVE, gated)
  arcodange sandbox checkpoint provision     # re-create ai_agent_sandbox (Playwright) + relink
  arcodange sandbox checkpoint relink-env    # rewrite write skill .env from the key + verify

- refresh wraps ops/sandbox/sandbox-lifecycle.sh; requires --yes (it wipes the agent
  too, since iso-prod overwrites llx_user). --db-only skips the documents sync.
- provision runs test/provisionSandbox.ts (you do the admin login — PROD creds,
  iso-prod) then auto-relinks; relink-env writes .env mode 600 and verifies via
  GET /users/info.
- scripts resolve the repo root from ARCO_ROOT (set by bin/arcodange) or their own
  path, so they work via the CLI or standalone.

Tested: status reports armed/not-armed correctly; refresh refuses without --yes
(exit 3); relink-env errors with no key (exit 1); help/usage wired.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

.claude/skills/dolibarr-sandbox-checkpoint/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: dolibarr-sandbox-checkpoint
+description: Manage the erp-sandbox iso-prod checkpoint — status, reset (refresh-from-prod), re-provision the write agent, relink the write skill .env. Use after rehearsing writes when you want a clean prod-shaped sandbox again.
+---
+
+# dolibarr-sandbox-checkpoint
+
+Lifecycle management for the **erp-sandbox** iso-prod checkpoint (ADR-0003). The
+sandbox exists so an agent can rehearse Dolibarr writes on prod-shaped data; this
+skill resets it back to a clean iso-prod baseline and re-arms the write path.
+
+All commands are exposed via the CLI:
+
+```sh
+arcodange sandbox checkpoint status
+arcodange sandbox checkpoint refresh --yes
+arcodange sandbox checkpoint provision
+arcodange sandbox checkpoint relink-env
+```
+
+## The reset cycle
+
+```
+  refresh --yes            provision                (auto) relink-env
+  ───────────────►  ──────────────────────►  ─────────────────────────►
+  wipe + re-seed     re-create the write       rewrite the write skill
+  iso-prod from      agent (Playwright;         .env from the new key +
+  prod (~2-3 min)    you log in) + key          verify it authenticates
+```
+
+1. **`status`** — HTTP liveness + whether the write agent (`ai_agent_sandbox`) is
+   *armed* (its key authenticates `GET /users/info`). Read-only, no cluster access.
+2. **`refresh --yes`** — re-seed the sandbox iso-prod from prod, wrapping
+   `ops/sandbox/sandbox-lifecycle.sh` (read-only `pg_dump` of prod → `DROP OWNED` →
+   `pg_restore`, then documents/logo sync). **Destructive**: requires `--yes`, and
+   it wipes the write agent too (iso-prod overwrites `llx_user` with prod's, which
+   has no `ai_agent_sandbox`). `--db-only` skips the documents sync. Needs `kubectl`
+   on the lab cluster.
+3. **`provision`** — re-create the write agent by running the Playwright POC
+   (`test/provisionSandbox.ts`). It opens a browser; **you complete the admin
+   login** — with the **PROD** admin credentials, since the sandbox is iso-prod
+   (they come from `test/.env.sandbox`). The POC re-grants the agent's rights
+   (including `banque lire`) and writes the key to `test/.ai_agent_sandbox.key`,
+   then this command auto-runs `relink-env`. Needs `deno`.
+4. **`relink-env`** — (re)write `dolibarr-sandbox-write/.env` from
+   `test/.ai_agent_sandbox.key` (mode 600) and verify it authenticates. Run it
+   standalone any time the key changed.
+
+## Why a refresh wipes the agent (and the key)
+
+A full refresh is **iso-prod**: it replaces the whole `public` schema (incl.
+`llx_user` and `llx_const`) with prod's. So `ai_agent_sandbox` — created *after* the
+seed, absent from prod — disappears, and `DOLI_INSTANCE_UNIQUE_ID` reverts to prod's,
+which invalidates the instance-encrypted API key. That's why re-provisioning (not
+just re-linking) is required after every refresh. This is by design (ADR-0003): the
+sandbox's prod-write isolation is structural, and the agent is cheap to recreate.
+
+## Gotchas
+
+- **Run from an up-to-date checkout.** The `.env` is written next to the
+  `dolibarr-sandbox-write` skill in *this* checkout — invoke `arcodange` from a
+  worktree synced to `origin/main` (the trunk may lag), or the skill/`.env` won't be
+  where your writes look for them.
+- **PROD admin creds for `provision`.** If the Playwright login fails, fix
+  `DOLI_ADMIN_PASSWORD` in `test/.env.sandbox` to prod's admin password.
+- **`refresh` needs `kubectl`** (lab cluster context); **`provision` needs `deno`**.
+- The lifecycle script pauses ArgoCD self-heal for the re-seed and restores it via
+  an EXIT trap — an interrupted refresh won't strand the sandbox scaled to 0.
+
+See also: `dolibarr-sandbox-write/SKILL.md` (the writes this arms), `ops/sandbox/`
+(the lifecycle script + README), factory `vibe/ADR/0003-sandbox-state-lifecycle.md`.