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

name, description

name	description
dolibarr-sandbox-checkpoint	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:

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.