feat(skills): dolibarr-sandbox-write — host-guarded write skill (V9)

The write-capable companion to the read-only dolibarr* skills, scoped to the
erp-sandbox. Lets an AI agent rehearse bookkeeping writes against a copy of prod
(ADR-0003) before a human promotes the reviewed change to prod.

- scripts/dol-write.sh: write wrapper that REFUSES any host that is not
  erp-sandbox.arcodange.lab (the structural prod-safety guarantee) using the
  ai_agent_sandbox key from a gitignored .env.
- scripts/thirdparty-create.sh: create client/supplier fiches; codes auto-assign
  via the elephant mask (code="-1").
- scripts/invoice-create.sh: customer (/invoices) or supplier (/supplierinvoices)
  invoices with product/service lines + ref_supplier, optional validate.
- scripts/payment-record.sh: record a règlement (VIR/CB/CHQ/LIQ); customer pays
  full + marks paid, supplier needs an amount.
- SKILL.md (safety model + workflows + the human-gated promote flow), .env.example,
  example input.

Proven end-to-end live against the sandbox: client -> invoice (service+product
lines, HT 1100 / TTC 1320) -> validate -> payment (paid); supplier -> supplier
invoice (ref_supplier carried) -> validate. Host guard verified to refuse a prod
URL before sending.

Avoirs (credit notes) and bin/arcodange CLI wiring are planned follow-ups.

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

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

@@ -0,0 +1,117 @@
+---
+name: dolibarr-sandbox-write
+description: >-
+  WRITE operations against the Arcodange Dolibarr SANDBOX (erp-sandbox.arcodange.lab)
+  — the rehearsal environment where an AI agent records thirdparties, invoices and
+  payments before any change is promoted to prod. Create client/supplier fiches
+  (auto-coded), customer + supplier invoices with product/service lines and the
+  supplier's own reference, validate them, and record règlements (payments). Every
+  write goes through dol-write.sh, which REFUSES any host that is not the sandbox —
+  the structural guarantee (ADR-0003) that this skill can never mutate production.
+  Use when the user asks to "create a thirdparty / supplier / client fiche", "saisir
+  une facture", "record an invoice with lines", "enregistrer un règlement / paiement",
+  or to rehearse a write before promoting it to prod. SKIP for production writes
+  (prod stays read-only via the `dolibarr` skill's `ai_agent` key; promotion is a
+  separate, human-gated replay), and for credit notes/avoirs (a planned follow-up).
+  Depends on the write-scoped `ai_agent_sandbox` Dolibarr user + its API key.
+requires:
+  bins: [bash, curl, python3]
+  auth: ".env with DOLIBARR_SANDBOX_URL + DOLIBARR_SANDBOX_API_KEY (mode 600, gitignored)"
+---
+
+# dolibarr-sandbox-write
+
+Write-capable companion to the read-only `dolibarr*` skills, scoped to the
+**sandbox**. It exists so an AI agent can *rehearse* bookkeeping writes against a
+faithful copy of prod (see ADR-0003 + the `ops/sandbox/` seed tooling), then a
+human promotes the reviewed change to prod.
+
+## The safety model (read this first)
+
+- **Host guard.** `scripts/dol-write.sh` reads `DOLIBARR_SANDBOX_URL` from `.env`
+  and refuses to send any request unless it matches `erp-sandbox.arcodange.lab`.
+  Point it at `erp.arcodange.lab` (prod) and it exits non-zero *before* the
+  request. This is the structural reason the skill cannot write prod.
+- **Credential scope.** The key is `ai_agent_sandbox`'s — valid only on the
+  sandbox host, with create+read rights on thirdparties / invoices / supplier
+  invoices / products / contacts (+ `societe client voir`). Prod's `ai_agent`
+  key is read-only and lives in a different skill's `.env`.
+- **Resettable.** Anything written here is wiped by `ops/sandbox/sandbox-lifecycle.sh
+  refresh-from-prod`, so mistakes cost a reset, not data.
+- **Promotion to prod is NOT in this skill.** Rehearse here → capture a reviewable
+  diff with the read-only `dolibarr-data-snapshot` skill (before/after) → a human
+  approves → the same operations are replayed against prod under a separate,
+  human-held prod-write credential. Never wire a prod-write key into this skill.
+
+## Setup
+
+Create `.env` (mode 600, gitignored) next to `scripts/`:
+
+```sh
+cd .claude/skills/dolibarr-sandbox-write
+umask 077
+{ echo "DOLIBARR_SANDBOX_URL=https://erp-sandbox.arcodange.lab"
+  printf 'DOLIBARR_SANDBOX_API_KEY=%s\n' "$(cat /path/to/.ai_agent_sandbox.key)"; } > .env
+```
+
+The key is produced by the Playwright provisioner in the repo's `test/`
+(`provisionSandbox.ts` → `.ai_agent_sandbox.key`). Verify: `scripts/dol-write.sh
+GET /status` should return HTTP 200 with `"environment":"non-production"`.
+
+## Workflows
+
+All three read a JSON object on **stdin** (or a file path as `$1`) and emit ids.
+
+### 1 · Thirdparty (fiche client/fournisseur) — `scripts/thirdparty-create.sh`
+
+```sh
+echo '{"name":"KissMetrics","role":"client","tva_intra":"US.."}' | scripts/thirdparty-create.sh
+echo '{"name":"OVH","role":"supplier","siret":"..."}'            | scripts/thirdparty-create.sh
+```
+`role`: `client` | `supplier` | `both`. Codes auto-assign from the mask
+(`CL{0000}` / `FO{0000}`) via the `-1` sentinel; pass `client_code`/`supplier_code`
+to override. Optional: `country_id` (default 1=FR), `siret`, `tva_intra`,
+`address`, `zip`, `town`, `email`, `phone`, `idprof1`. Emits the new id.
+
+### 2 · Invoice (facture) — `scripts/invoice-create.sh`
+
+```sh
+echo '{"socid":42,"kind":"customer","validate":true,
+       "lines":[{"desc":"Conseil","qty":2,"price_ht":500,"tva":20,"type":"service"},
+                {"desc":"Licence","qty":1,"price_ht":100,"tva":20,"type":"product"}]}' \
+  | scripts/invoice-create.sh
+# supplier invoice carrying the supplier's own reference:
+echo '{"socid":7,"kind":"supplier","ref_supplier":"INV-2026-042","validate":true,
+       "lines":[{"desc":"Hosting","qty":1,"price_ht":80,"tva":20,"type":"service"}]}' \
+  | scripts/invoice-create.sh
+```
+`kind`: `customer` (`/invoices`) | `supplier` (`/supplierinvoices`). Lines carry
+`desc, qty, price_ht, tva, type` (product|service) and optional `product_id`
+(`fk_product`) to link a catalogue product. Totals + TVA are computed by Dolibarr.
+`validate:true` turns the draft (`PROV…`) into a final numbered invoice; omit it
+to leave a draft. Emits `{id, ref, ref_supplier, total_ht, total_ttc, statut}`.
+
+### 3 · Payment (règlement) — `scripts/payment-record.sh`
+
+```sh
+echo '{"invoice_id":19,"mode":"VIR","account_id":1}'                  | scripts/payment-record.sh
+echo '{"invoice_id":13,"kind":"supplier","mode":"VIR","account_id":1,"amount":96}' \
+  | scripts/payment-record.sh
+```
+The invoice must be **validated** first. `mode`: `VIR|CB|CHQ|LIQ`. Customer
+payments settle the full remaining amount and mark the invoice paid; **supplier**
+payments require an explicit `amount`. `account_id` is the bank account id (the
+read-only `dolibarr-payments-state` skill lists them; `ai_agent_sandbox` does not
+yet have `banque lire`, so pass the id). Emits the new payment id.
+
+## Gotchas
+
+- **Validate before paying.** A draft (`statut=0`, ref `PROV…`) cannot be paid.
+- **Codes.** The thirdparty code module is `mod_codeclient_elephant` (auto). The
+  REST create needs `code_client`/`code_fournisseur = "-1"` to trigger it — the
+  script does this; without it the API errors `ErrorCustomerCodeRequired`.
+- **Dates** are sent as Unix epochs; pass `date:"YYYY-MM-DD"` or omit for today.
+- **`banque lire`** isn't granted yet → `GET /bankaccounts` returns empty. Add it
+  to the provisioner's rights set if account discovery from this skill is needed.
+- **Avoirs (credit notes)** are a planned follow-up (a customer invoice with
+  `type=2` referencing the original).