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), update an existing fiche's dossier (allowlisted non-ledger fields
  with a before/after read-back diff), add contacts idempotently (dedupe by email
  then name), customer + supplier invoices with product/service lines and the
  supplier's own reference, validate them, and record règlements (payments). Every
  create is IDEMPOTENT (erp#44): before any POST it dedupes against the target
  (thirdparty by exact name, supplier invoice by socid+ref_supplier, customer
  invoice by socid+date+total+line fingerprint, payment by invoice+amount+
  normalized transaction id; credit notes excepted, a follow-up), so replaying
  a manifest — even one that failed mid-run — is a no-op, never a duplicate.
  Also attaches source documents (the supplier's PDF) onto an invoice's GED
  (erp#43): upload via the Documents API, idempotent by (object, filename,
  sha256) — re-attach is a no-op, same name + different content aborts. 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",
  "compléter / mettre à jour la fiche client", "add a contact to a thirdparty",
  "saisir une facture", "record an invoice with lines", "enregistrer un règlement /
  paiement", "attacher la pièce / le justificatif / le PDF à la facture",
  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). 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

Each script reads a JSON object on **stdin** (or a file path — or inline JSON —
as `$1`; `thirdparty-update.sh` also takes `<socid>` first) and emits ids as JSON.

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

**Idempotent (erp#44): dedupe by exact name.** Before any POST the name is looked
up on the target with the same semantics as promote's `#thirdparty:name=` lookup:
one match whose roles cover the requested `role` → `{"id": <existing>,
"deduped": true}`, no write; **2+ matches abort** (ambiguous — never guess); a
match **missing the requested role aborts** too (refuse-never-repair: reusing a
client fiche as a supplier would skip the code mask and hide a data problem).
Otherwise it creates and emits `{"id": <new>, "deduped": false}`.

### 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,
deduped}`.

**Idempotent (erp#44).** Before any POST the thirdparty's invoices of the same
kind are listed and deduped:

- **supplier with `ref_supplier`** → by **(socid, ref_supplier)** — the
  supplier's own ref is the natural key. Same key with a *different* total
  **aborts** (a conflict to resolve, never a dedupe).
- **customer** (or supplier without `ref_supplier`) → by **(socid, date,
  total_ttc ±0.02, line fingerprint)** — the multiset of (desc, qty, subprice,
  tva_tx), desc HTML-unescaped/whitespace-collapsed since Dolibarr returns
  stored text HTML-encoded. Credit notes (`type=2`) are never candidates;
  2+ matches abort.

A hit emits the **existing** invoice with `"deduped": true` — and if
`validate:true` was asked while the match is still a draft (run 1 died between
create and validate), it is **validated now**, so a replayed manifest converges
instead of stalling on a half-done op. A listing failure other than 404 aborts
(POSTing blind would mint duplicates — the exact erp#44 failure mode).

### 3 · Payment (règlement) — `scripts/payment-record.sh`

```sh
echo '{"invoice_id":19,"mode":"VIR","account_id":1,"transaction_id":"2159468139"}' | scripts/payment-record.sh
echo '{"invoice_id":13,"kind":"supplier","mode":"VIR","account_id":1,"amount":96,
       "transaction_id":"arcodange-1246-1-transaction-019f14c5-e254-7ac9-9e9f-307ed9-d55f44"}' \
  | scripts/payment-record.sh   # stores num 019f14c5-e254-7ac9-9e9f-307ed9-d55f44
```
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 — list
them with `scripts/bank-accounts.sh` (`ai_agent_sandbox` now holds `banque lire`).

**Always pass `transaction_id`** — the originating bank transaction id (the
Qonto/Wise tx id from the feed). It is the first-class way to tie a règlement to
the real bank movement: stored on the payment's bank line (`llx_bank.num_chq`), so
reconciliation matches **by id** rather than by fuzzy amount/date. (`num` is a
back-compat alias for the same field.) Recording without it prints a warning — the
payment still posts, but it won't auto-reconcile.

**Canonical short form — the varchar(50) constraint.** Dolibarr stores
`num_payment` in **varchar(50)** columns (`llx_paiement.num_paiement`,
`llx_paiementfourn.num_paiement`) while Qonto transaction ids run ~67 chars
(`<org>-<n>-<n>-transaction-<uuid>`) — POSTing one raw fails with HTTP 400
"value too long for type character varying(50)". The script therefore normalizes
before POST: everything through `transaction-` is stripped and the **UUID suffix**
(globally unique, ~37 chars) is what gets stored. Wise ids (short numerics) pass
through unchanged. An id still >50 chars after normalization is **refused** with
an explicit error — never truncated silently. `arcodange-bank-reco`'s bank-match
normalizes feed ids the same way, so short-form nums keep reconciling by id
(historical long-form nums too). Pass the raw feed id; the script does the rest.

**Idempotent (erp#44), composing with the normalization above.** Before any POST
the invoice's payment list is fetched and deduped by **(invoice, amount,
normalized transaction_id)**: a row whose stored num — normalized the same way,
so historical long-form Qonto nums still match — equals the normalized
`transaction_id` is a replay. Supplier payments also require the amounts to
agree (±0.005; same tx with a *different* amount **aborts** as a conflict);
customer payments settle the full remaining, so the tx id alone is the key. A
hit emits `{"id": null, "bank_transaction_id": <existing line>,
"transaction_id": <normalized>, "deduped": true}` without posting (`id` is null
by honesty — Dolibarr's payment list does not expose the paiement rowid; the
bank line is the stable handle). **Without a `transaction_id` there is no dedupe
key — a replay WILL double-pay**, one more reason it is always passed.

Emits **`{id, bank_transaction_id, transaction_id, deduped}`**.
`bank_transaction_id` is the Dolibarr bank line (`llx_bank.fk_bank_line`) the
payment created — the id the reconciliation (`arcodange-bank-reco`) keys on.
`transaction_id` echoes the **normalized** num actually stored. Both ends are
captured at write time.

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

```sh
# customer avoir
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
# supplier avoir (avoir fournisseur)
echo '{"socid":12,"kind":"supplier","source_invoice":17,"ref_supplier":"AV-2026-77","validate":true,
       "lines":[{"desc":"Avoir hosting","qty":1,"price_ht":120,"tva":20,"type":"service"}]}' \
  | scripts/creditnote-create.sh
```
An invoice of `type=2` referencing `source_invoice` (`fk_facture_source`); amounts
come out negative. `kind:"supplier"` targets `/supplierinvoices` (carry
`ref_supplier`); default `customer` targets `/invoices`. `validate:true` numbers it
(`AVC…` for customer, `AVF…` for supplier). Emits `{id, ref, ref_supplier, total_ht,
total_ttc, fk_facture_source, statut}`.

### 5 · Thirdparty dossier update — `scripts/thirdparty-update.sh`

```sh
scripts/thirdparty-update.sh 1 '{"email":"[email protected]","note_public":"…"}'
scripts/thirdparty-update.sh 1 fiche.json      # or a file; or "-" for stdin
echo '{"socid":1,"fields":{"zip":"33713"}}' | scripts/thirdparty-update.sh   # promote form
```
Updates an **existing** fiche's dossier — **allowlisted fields only**: `name`,
`name_alias`, `address`, `zip`, `town`, `state_id`, `region_id`, `country_id`,
`country_code`, `email`, `url`, `phone`, `typent_id`, `effectif_id`, `note_public`,
`note_private`, `idprof1`…`idprof6`, `tva_intra`. That is the ledger grammar's
"thirdparty complete" — identity / address / typology / notes / national ids.
Anything else (`code_client`, `client`/`fournisseur` roles, remises, payment
conditions…) is **refused before any request**, exit non-zero, offender named.
Read-back contract: GET before → PUT → GET after; emits
`{"id":N,"changed":{field:{"before":…,"after":…}}}` restricted to the requested
fields that actually changed, and exits non-zero if a requested field did not
take. Re-applying the same update yields `"changed": {}` — idempotency you can see.

### 6 · Contact — `scripts/contact-create.sh`

```sh
echo '{"socid":1,"lastname":"Rootering","firstname":"Hendrik","poste":"COO",
       "email":"[email protected]"}' | scripts/contact-create.sh
```
**Idempotent from day one** (the erp#44 pattern): before any POST it lists the
thirdparty's contacts and dedupes **by case-insensitive email, then by
(lastname, firstname)**; a match emits `{"id": <existing>, "deduped": true}` and
exits 0 without writing. Otherwise POST `/contacts` → `{"id": <new>,
"deduped": false}`. Required: `socid`, `lastname`. Optional: `firstname`, `poste`
(job title), `email`, `phone` (stored as `phone_pro`), `phone_mobile`,
`phone_perso`, `address`, `zip`, `town`, `country_id`, `note_public`,
`note_private`. Unknown fields are refused, never dropped.

### 7 · Attach a source document (GED) — `scripts/document-attach.sh`

```sh
echo '{"modulepart":"facture_fournisseur","ref":"FAF2026013",
       "file":"pdfs/F1045_ARCODANGE_2026-06-30.pdf"}' | scripts/document-attach.sh
echo '{"modulepart":"facture","object_id":19,"file":"/abs/path/piece.pdf",
       "filename":"stored-name.pdf"}' | scripts/document-attach.sh
```
Uploads the **source piece** (the supplier's own PDF, a contract…) onto an
invoice's GED directory via `POST /documents/upload` (base64 content,
`overwriteifexists` always 0). `modulepart`: `facture`/`invoice` (customer) or
`facture_fournisseur`/`invoice_supplier`/`supplier_invoice` (supplier). Address
the invoice by `object_id` or by Dolibarr `ref` (both = cross-checked; a
ref-only lookup matching 0 or 2+ aborts). `filename` defaults to the file's
basename. Emits `{object_id, ref, modulepart, filename, sha256, size, deduped}`.

**Idempotent by (object, filename, sha256) — our own check, never Dolibarr's
overwrite flag.** Before any POST the object's GED is listed
(`GET /documents?modulepart=…&id=…`, where 404 on a proven-existing object means
"no documents yet") and a same-named entry is **downloaded back and
sha256-compared**: identical → `{"deduped": true}`, no upload; **different
content ABORTS** — silently replacing a stored piece would rewrite evidence
(refuse-never-repair). After an upload the file is re-listed, downloaded back
and sha256-verified (read-back proof the GED holds exactly the bytes sent).

## 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`. Op kinds: `thirdparty`,
`thirdparty_update` (input: `socid` + `fields`), `contact`, `invoice`, `creditnote`,
`payment`, `attach` — each mapping to its workflow script above. An `attach` op's
relative `file` path resolves against the **manifest's directory** (the manifest
is the portable unit: a replay pack carries its `pdfs/` beside it), and
`promote-plan` prints the file's sha256 — or a loud MISSING warning — at review
time so the content is pinned before any apply.

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

**Replay is safe (erp#44).** Every op script dedupes before POSTing, so a
manifest that failed mid-run — the 2026-07-11 rehearsal's manifest B, whose op 1
had already created the DARNIS invoice — can simply be re-applied: already-done
ops answer `deduped=true`, the rest execute. `promote-apply` marks each op
`created` or `deduped=true` inline and totals them in the summary line
(`OK — promote complete (1 created, 2 deduped)`), so an all-`deduped` second run
is visible proof of a no-op. Live acceptance: `tests/replay-idempotency.sh`
double-applies a self-contained manifest (thirdparty + supplier invoice +
payment + GED attach) on the sandbox and asserts run 2 dedupes all ops with
zero new rows and zero new GED files.

A manifest value can reference another entity two ways, both resolved against the
**target** so the same file is portable sandbox↔prod:

- **`@ref`** — an entity **created earlier in this manifest** (resolves to the id
  just created on the target). For new records.
- **`#entity:field=value`** — a **pre-existing** entity, looked up on the target by
  business key, e.g. `#thirdparty:name=KissMetrics` or `#thirdparty:code=CL0007`.
  Supports `thirdparty` (name/code/supplier_code) and `invoice`/`supplierinvoice`
  (ref/ref_supplier). A lookup matching **nothing or more than one** record **aborts
  the run** — it never guesses, so it can't write to the wrong entity.

So a real change like "invoice the existing client KissMetrics and record its
payment" is `{"socid":"#thirdparty:name=KissMetrics", ...}` — it resolves to the
sandbox KissMetrics on `--target sandbox` and the prod one on `--target prod`.

## 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.
- **Qonto tx ids don't fit varchar(50).** `payment-record.sh` strips the
  `<org>-<n>-<n>-transaction-` prefix and stores the UUID suffix (see workflow 3);
  ids still >50 chars after that are refused. Offline proof: `tests/run-tests.sh`
  (stubbed `dol-write.sh` via the `DOL_WRITE` hook — writes nothing anywhere).
- **`banque lire`** (rights id 111) is granted → `scripts/bank-accounts.sh` lists
  accounts (id/label/bank) so a payment can pick its `account_id`. It's in the
  provisioner's `WRITE_IDS`, so a fresh `provisionSandbox.ts` run includes it.
- **`user lire`** (rights id 251) is granted → the checkpoint *armed* probe
  (`GET /users/info` in `status`/`relink-env`) answers 200 instead of 403. Also in
  the provisioner's `WRITE_IDS`.
- **Avoirs (credit notes)** → `creditnote-create.sh` (customer invoice `type=2`
  referencing `source_invoice`; amounts negative, ref `AVC…`). Supplier avoirs
  are a follow-up.
- **Dossier updates are allowlisted by design.** The ledger grammar's "thirdparty
  complete" completes a fiche with identity/address/typology/notes/idprof1-6/
  tva_intra — never with ledger-side state. `thirdparty-update.sh` refuses
  anything else (`code_client`, roles, payment conditions…) *before* any request:
  a typo'd field must fail loudly, not silently mutate the ledger. Offline proof
  in `tests/run-tests.sh`.
- **Every create dedupes before POSTing (erp#44)** — thirdparty by exact name
  (ambiguous or role-mismatch aborts), supplier invoice by (socid, ref_supplier)
  (total mismatch aborts), customer invoice by (socid, date, total, line
  fingerprint), payment by (invoice, amount, normalized tx id), contact by
  (socid, email) then (socid, lastname+firstname), GED attach by (object,
  filename, sha256) — each answering
  `{"deduped": true}` instead of minting a duplicate, so replaying a manifest is
  always safe. Two holes: a **payment without a `transaction_id`** has no
  dedupe key and WILL double-pay on a replay, and **`creditnote-create.sh` does
  not dedupe yet** (supplier-avoir parity follow-up) — do not replay a manifest
  containing a creditnote op past a mid-run failure. Offline proof:
  `tests/run-tests.sh`; live double-apply proof: `tests/replay-idempotency.sh`.
- **GED attach paths carry a get_exdir prefix for supplier invoices.** A
  supplier-invoice document lives at `fournisseur/facture/<x>/<y>/<REF>/<file>`
  (the `<x>/<y>` split derives from the object id), so `/documents/download`
  needs `0/3/FAF2026014/file.pdf`, not `FAF2026014/file.pdf`. `document-attach.sh`
  derives the module-relative path from the listing's `fullname` (substring
  after the last `/facture/`) — never reconstructs it. Customer invoices have
  no prefix (`facture/<REF>/<file>`). Upload answers the bare filename as a
  JSON string; the script verifies it and then read-back-verifies the sha256.
- **A dedupe lookup that fails (non-404) aborts the op** — the scripts refuse to
  POST blind, because assuming "no match" on a 403/timeout is precisely how
  duplicates get minted (cf. the `voir_tous` ACL trap in the `dolibarr` skill:
  missing permissions masquerade as empty lists).
- **`poste`, not `soc2`.** The job-title field on a Dolibarr contact is `poste`;
  `soc2` (seen in WIP operator payloads) is not a Dolibarr field and the API
  would drop it silently — `contact-create.sh` refuses it with a pointer to
  `poste`.
- **CLI:** all of these are also `arcodange sandbox {thirdparty|invoice|payment|creditnote|attach|write}`
  (JSON on stdin) — `arcodange sandbox help` for the list.