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

---
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 gated, not automatic.** Rehearse here → review the
  change-set (`promote-plan.sh`) → replay it on prod (`promote-apply.sh --target
  prod`). The prod write key is supplied via the **environment at apply time**
  (`DOLIBARR_PROD_WRITE_KEY`), never stored in any `.env`, and `dol-prod-write.sh`
  refuses every prod write unless `ARCO_PROMOTE_CONFIRM=I-UNDERSTAND-THIS-WRITES-PROD`.
  See "Promote to prod" below.

## 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.

### 4 · Credit note (avoir) — `scripts/creditnote-create.sh`

```sh
echo '{"socid":42,"source_invoice":19,"validate":true,
       "lines":[{"desc":"Avoir partiel conseil","qty":1,"price_ht":100,"tva":20,"type":"service"}]}' \
  | scripts/creditnote-create.sh
```
A customer invoice of `type=2` referencing `source_invoice` (`fk_facture_source`);
amounts come out negative (a credit). `validate:true` turns the draft into a
numbered `AVC…` avoir. Emits `{id, ref, total_ht, total_ttc, fk_facture_source, statut}`.

## Promote to prod (rehearse → review → replay)

The ADR-0003 capstone: take a change rehearsed in the sandbox and apply the **same
operations** to prod, with a human in the loop. The unit is a **manifest** — a JSON
array of write ops using **symbolic refs** (`@name`) instead of ids, so it is
portable from sandbox to prod (an invoice references `@tp1`, the thirdparty created
earlier in the run). See `examples/promote-manifest.json`.

```sh
scripts/promote-plan.sh  change.json                      # 1. human-readable review
scripts/promote-apply.sh change.json --target sandbox     # 2. rehearse the replay (safe)
# 3. promote — writes PROD; the key is env-only and the confirm flag is mandatory:
DOLIBARR_PROD_WRITE_KEY="<prod write key>" \
ARCO_PROMOTE_CONFIRM=I-UNDERSTAND-THIS-WRITES-PROD \
  scripts/promote-apply.sh change.json --target prod
```

`promote-apply` resolves each `@ref` to the id actually created during the run, so
dependent ops wire up on the target. `--target sandbox` writes via `dol-write.sh`;
`--target prod` writes via `dol-prod-write.sh`, which reads `DOLIBARR_PROD_WRITE_KEY`
**from the environment only** (never a stored `.env`) and refuses any write unless
`ARCO_PROMOTE_CONFIRM` is set exactly. Pair it with `dolibarr-data-snapshot` (prod
before/after) to confirm only the intended records changed.

Limitation: a manifest references entities it **creates** (via `@ref`). Referencing
a *pre-existing* prod entity by a sandbox id won't match — resolve those by business
key (name/code/ref) first. Self-contained change-sets (new thirdparty + its invoice
+ payment) replay cleanly today.

## 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)** → `creditnote-create.sh` (customer invoice `type=2`
  referencing `source_invoice`; amounts negative, ref `AVC…`). Supplier avoirs
  are a follow-up.
- **CLI:** all of these are also `arcodange sandbox {thirdparty|invoice|payment|creditnote|write}`
  (JSON on stdin) — `arcodange sandbox help` for the list.