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

name, description, requires

name	description	requires
dolibarr-sandbox-write	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.	bins auth bash curl python3 .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/:

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

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

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

echo '{"invoice_id":19,"mode":"VIR","account_id":1,"transaction_id":"QONTO-TX-1234"}' | scripts/payment-record.sh
echo '{"invoice_id":13,"kind":"supplier","mode":"VIR","account_id":1,"amount":96,"transaction_id":"WISE-TX-5678"}' \
  | 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 — 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.

Emits {id, bank_transaction_id, transaction_id}. 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. Both ends are captured at write time.

4 · Credit note (avoir) — scripts/creditnote-create.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}.

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.

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.

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