Merge pull request 'feat(skills): dolibarr-sandbox-write — host-guarded write skill (V9)' (#21) from claude/dolibarr-sandbox-write into main

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/arcodange-bank-reco/SKILL.md

@@ -124,6 +124,90 @@ Current state (V1 baseline):
 - Wise **STANDARD EUR**     : 5 308,25 € live
 - **Total bank-side**       : 9 499,79 €
 
+## Known-patterns catalog ([known-patterns.json](known-patterns.json))
+
+Bank movements that have no Dolibarr counterpart fall into two groups:
+
+1. **Intentional gaps** — operational expenses or one-off events the operator knows about (URSSAF mensuel, AI subs, capital deposit, Wise plan fees). These keep recurring but their accounting treatment is well-understood.
+2. **Real action items** — incoming payments not yet entered, expenses missing a supplier invoice, anomalies.
+
+Without a catalog, both look identical in the BANK-ONLY bucket — noise drowns the signal. The catalog is an operator-curated list of patterns; `bank-match.sh` reads it and splits BANK-ONLY into two sub-buckets:
+
+- **BANK-ONLY — known patterns** : annotated with `[classification]` + a one-line note (which Dolibarr account to use, etc.). Don't action; just verify.
+- **BANK-ONLY — unknown** : the real signal. Each entry is either a missing supplier invoice, an unrecorded payment, or a new pattern to add to the catalog.
+
+**Schema** (JSON, see [known-patterns.json](known-patterns.json) for current entries):
+
+```json
+{
+  "patterns": [
+    {
+      "pattern": "regex (case-insensitive, matched against bank label + operation type)",
+      "classification": "capital_deposit | social_charges | ai_subscription | bank_fee | internal_topup | personal_apport | needs_classification",
+      "bank":   "qonto | wise   (optional, default both)",
+      "side":   "credit | debit (optional, default both)",
+      "amount_min": 0.0,    "amount_max": 99999.0,   // optional numeric bounds
+      "note": "human-readable context — what this is, which Dolibarr account, recurring schedule, etc."
+    }
+  ]
+}
+```
+
+**Editing workflow:**
+1. Run `bin/arcodange bank match` → look at BANK-ONLY unknown.
+2. For each recurring entry that's "expected", add a pattern to `known-patterns.json`.
+3. Re-run match → the entry should now appear in the known sub-bucket.
+4. For one-off action items (e.g. "+2147 € KM May 29 not in Dolibarr"), don't add a pattern — enter it in Dolibarr instead.
+
+**V6.1 catalog** ships with these patterns for the current Arcodange baseline:
+- `FOUREZ Quentin` → capital_deposit (initial 1000 € apport via notaire, 2026-01-21)
+- `URSSAF` → social_charges
+- `MISTRAL.AI` / `CLAUDE.AI` → ai_subscription
+- `Wise *Plan` → bank_fee (Wise account plan billed via Qonto card)
+- `qonto_fee` → bank_fee
+- `BALANCE_DEPOSIT|For your account plan` → internal_topup (the Wise +50/-50 self-funding pair)
+
+After applying the catalog to the V6 baseline, the **only remaining BANK-UNKNOWN** is the **+2147 € KissMetrics payment on 2026-05-29** that hasn't been entered in Dolibarr — the actual signal.
+
+## V7 bucket structure
+
+V7 adds three improvements that reshape the output buckets:
+
+| Bucket | Meaning | Counts toward exit-1? |
+|---|---|---|
+| **MATCHED** | Bank ↔ Dolibarr paired. Annotated with match kind: `[wire-ref]` (strong, via `--enrich`) or `[amt+date]` (loose). | No |
+| **INTERNAL** | Wise↔Qonto consolidations (5000€ moved between Arcodange's own accounts). | No |
+| **AVOIR-NETTED** | Dolibarr AVC + FAC cancellation cycles paired and excluded (the bank only saw the net). | No |
+| **BANK-ONLY — known patterns** | Bank movement with a `known-patterns.json` annotation. Intentional gap. | No |
+| **BANK-ONLY — unknown** | Bank movement with no Dolibarr counterpart AND no catalog pattern. **Real action item**. | Yes |
+| **DOLIBARR-ONLY — on API-tracked accounts** (QON*/WIS*) | Dolibarr payment that the bank should have shown. **Real gap**. | Yes |
+| **DOLIBARR-ONLY — not in API scope** (CCA1 perso etc.) | Expected gap — we have no API on those accounts. | No |
+
+Exit code 0 iff the two "real gap" buckets are empty.
+
+### `--enrich` — wire-reference strong matching
+
+`bank-match.sh --enrich` fetches `/v1/transfers/{id}` for each Wise TRANSFER and reads the `reference` field (the wire memo from the sender, e.g. `FROM KISSMETRICS HOLDINGS INC FOR INVOICE FAC002CL0001002/ VENDOR:DEV`). When the reference contains a `FAC\d+(CL\d+)?` pattern matching a Dolibarr customer invoice, that pairing takes precedence over the loose date+amount match. Only the strong-matched ones get `[wire-ref]`; the rest fall through to `[amt+date]`. Cost: 1 extra HTTP call per Wise transfer.
+
+### Avoir cycle netting
+
+When Arcodange cancels and reissues an invoice (FAC001 → AVC001 + FAC001-NEW), the bank sees one net credit but Dolibarr stores 3 payment entries. V7 pairs AVC entries of -X with FAC entries of +X for the same socid within ±5d, surfaces them in **AVOIR-NETTED**, and excludes them from `dolibarr-only`. Removes the V6.1 noise where AVC001 + FAC001-CL00001 appeared as fake gaps.
+
+### fk_account context
+
+`bank-match.sh` now fetches `/bankaccounts` and tags `dolibarr-only` entries with their account ref + label. Splits into API-tracked (QON*/WIS* — real gaps) vs not-in-scope (everything else — expected). The 7 CCA1 personal-account entries that used to look like failures are now correctly classified as expected gaps.
+
+### Effect on the baseline
+
+| | V6 | V6.1 | V7 |
+|---|---|---|---|
+| MATCHED | 6 (all amt+date) | 6 | 6 (1 wire-ref strong + 5 amt+date when --enrich) |
+| BANK-ONLY total | 8 mixed | 7 known + 1 UNKNOWN | 7 known + 1 UNKNOWN |
+| AVOIR-NETTED | — | — | 2 (silently absorbed) |
+| DOL-only TRUE GAP | 9 (noisy) | 9 (noisy) | **0** |
+| DOL-only EXPECTED | — | — | 7 (CCA1 personal) |
+| Exit-1 signal count | 17 (noise) | 10 (less noise) | **1** (just the +2147€ KM) |
+
 ## Matching heuristic — what's in v1 and what's V7
 
 Today's match logic:

.claude/skills/arcodange-bank-reco/examples/bank-match-2026-01-to-05.txt

@@ -1,36 +1,50 @@
-# Bank reconciliation: 2026-01-01 → 2026-05-31  (window ±7d, fees: off)
+# Bank reconciliation: 2026-01-01 → 2026-05-31  (window ±7d, fees: off, enrich: on)
 
 === MATCHED  (6 bank ↔ Dolibarr) ===
-  Qonto 2026-01-27  -     50.00  card                Wise *Plan   ↔   supplier FAF2026001               (2026-01-26, Δ-1d)
+  Qonto 2026-01-27  -     50.00  card                Wise *Plan   ↔[amt+date]   supplier FAF2026001               (2026-01-26, Δ-1d)
-  Wise  2026-02-05  +    510.00  TRANSFER            Kissmetrics Holdings Inc   ↔   customer FAC001-CL0001001         (2026-02-05, Δ+0d)
+  Wise  2026-02-05  +    510.00  TRANSFER            Kissmetrics Holdings Inc   ↔[amt+date]   customer FAC001-CL0001001         (2026-02-05, Δ+0d)
-  Wise  2026-03-06  +   5100.00  TRANSFER            Kissmetrics Holdings Inc   ↔   customer FAC002-CL0001002         (2026-03-12, Δ+6d)
+  Wise  2026-03-06  +   5100.00  TRANSFER            Kissmetrics Holdings Inc   ↔[wire-ref]   customer FAC002-CL0001002         (2026-03-12, Δ+6d)
-  Qonto 2026-03-13  -    612.00  transfer            DARNIS OPERATIONS   ↔   supplier FAF2026008               (2026-03-13, Δ+0d)
+  Qonto 2026-03-13  -    612.00  transfer            DARNIS OPERATIONS   ↔[amt+date]   supplier FAF2026008               (2026-03-13, Δ+0d)
-  Wise  2026-04-20  +   2550.00  TRANSFER            Kissmetrics Holdings Inc   ↔   customer FAC003-CL0001003         (2026-04-20, Δ+0d)
+  Wise  2026-04-20  +   2550.00  TRANSFER            Kissmetrics Holdings Inc   ↔[amt+date]   customer FAC003-CL0001003         (2026-04-20, Δ+0d)
-  Qonto 2026-05-10  -    306.00  transfer            DARNIS OPERATIONS   ↔   supplier FAF2026009               (2026-05-10, Δ+0d)
+  Qonto 2026-05-10  -    306.00  transfer            DARNIS OPERATIONS   ↔[amt+date]   supplier FAF2026009               (2026-05-10, Δ+0d)
 
 === INTERNAL (Wise↔Qonto consolidations, 1) ===
   Wise  2026-03-13  -   5000.00  TRANSFER            ARCODANGE   ↔   Qonto 2026-03-13 +5000.00
 
-=== BANK-ONLY  (8 bank movements without Dolibarr counterpart) ===
+=== AVOIR-NETTED (2 Dolibarr entries pairing AVC↔FAC cancellation cycles) ===
-  Qonto 2026-01-16  +      5.22  qonto_fee           Qonto
+  customer 2026-02-05    -510.00  AVC001-CL0001001          ↔ netted against FAC001-CL00001
-  Qonto 2026-01-21  +   1000.00  income              FOUREZ Quentin
+  customer 2026-02-05     510.00  FAC001-CL00001            ↔ netted against AVC001-CL0001001
-  Wise  2026-01-26  -     50.00  FEATURE_CHARGE      For your account plan
+
-  Wise  2026-01-26  +     50.00  BALANCE_DEPOSIT     To EUR
+=== BANK-ONLY — known patterns (7, intentional gaps documented in known-patterns.json) ===
-  Qonto 2026-04-03  -    172.68  card                MISTRAL.AI
+  Qonto 2026-01-16  +      5.22  qonto_fee           Qonto   [bank_fee]
-  Qonto 2026-04-13  -    180.00  card                CLAUDE.AI SUBSCRIPTION
+      └─ Qonto fees ou refunds. Petites valeurs. Dolibarr: account 627.
-  Qonto 2026-05-22  -    493.00  direct_debit        URSSAF D ILE DE FRANCE
+  Qonto 2026-01-21  +   1000.00  income              FOUREZ Quentin   [capital_deposit]
+      └─ Apport en capital social initial 1000 €. Maître FOUREZ Quentin, notaire centralisateur du dépôt. Date typique : 2026-01-21. Dolibarr: account 1013.
+  Wise  2026-01-26  -     50.00  FEATURE_CHARGE      For your account plan   [internal_topup]
+      └─ Solde Wise rechargé pour couvrir un frais immédiat (souvent net zéro avec le FEATURE_CHARGE du même jour).
+  Wise  2026-01-26  +     50.00  BALANCE_DEPOSIT     To EUR   [internal_topup]
+      └─ Solde Wise rechargé pour couvrir un frais immédiat (souvent net zéro avec le FEATURE_CHARGE du même jour).
+  Qonto 2026-04-03  -    172.68  card                MISTRAL.AI   [ai_subscription]
+      └─ Mistral AI API subscription. Récurrent mensuel. Dolibarr: account 6262 + supplier 'Mistral AI'.
+  Qonto 2026-04-13  -    180.00  card                CLAUDE.AI SUBSCRIPTION   [ai_subscription]
+      └─ Claude AI subscription (Anthropic). Récurrent mensuel. Dolibarr: account 6262 + supplier 'Anthropic'.
+  Qonto 2026-05-22  -    493.00  direct_debit        URSSAF D ILE DE FRANCE   [social_charges]
+      └─ Cotisations sociales URSSAF (régime mensuel/trimestriel). Dolibarr: account 645100 (charges de sécurité sociale).
+
+=== BANK-ONLY — unknown (1, NEEDS attention: missing supplier invoice / unrecorded payment / new pattern) ===
   Wise  2026-05-29  +   2147.00  TRANSFER            Kissmetrics Holdings Inc
 
-=== DOLIBARR-ONLY  (9 Dolibarr payments without bank movement) ===
+=== DOLIBARR-ONLY — on API-tracked accounts (0, REAL GAP: bank should have shown this) ===
-  supplier 2026-01-04       1.99  FAF2026003  (fk_account=3)
-  supplier 2026-01-06     202.80  FAF2026005  (fk_account=3)
-  supplier 2026-01-09      55.93  FAF2026002  (fk_account=3)
-  supplier 2026-01-09     148.80  FAF2026004  (fk_account=3)
-  supplier 2026-01-12       8.43  FAF2026006  (fk_account=3)
-  supplier 2026-01-15       1.30  FAF2026002  (fk_account=3)
-  supplier 2026-01-17       3.20  FAF2026007  (fk_account=3)
-  customer 2026-02-05    -510.00  AVC001-CL0001001  (fk_account=2)
-  customer 2026-02-05     510.00  FAC001-CL00001  (fk_account=2)
 
---------------------------------------------------------------------------------
+=== DOLIBARR-ONLY — on accounts NOT in API scope (7, expected gap: CCA1 perso etc.) ===
-# 6 matched, 1 internal, 8 bank-only, 9 dolibarr-only
+  supplier 2026-01-04       1.99  FAF2026003                (CCA1 (G.RADUREAU Compte Courant Asso))
+  supplier 2026-01-06     202.80  FAF2026005                (CCA1 (G.RADUREAU Compte Courant Asso))
+  supplier 2026-01-09      55.93  FAF2026002                (CCA1 (G.RADUREAU Compte Courant Asso))
+  supplier 2026-01-09     148.80  FAF2026004                (CCA1 (G.RADUREAU Compte Courant Asso))
+  supplier 2026-01-12       8.43  FAF2026006                (CCA1 (G.RADUREAU Compte Courant Asso))
+  supplier 2026-01-15       1.30  FAF2026002                (CCA1 (G.RADUREAU Compte Courant Asso))
+  supplier 2026-01-17       3.20  FAF2026007                (CCA1 (G.RADUREAU Compte Courant Asso))
+
+----------------------------------------------------------------------------------------------------
+# 6 matched, 1 internal, 2 avoir-netted, 7 bank-known, 1 bank-UNKNOWN, 0 dol-only-API, 7 dol-only-personal
+# patterns loaded from /Users/gabrielradureau/Work/Arcodange/erp/.claude/worktrees/happy-wilson-ee5645/.claude/skills/arcodange-bank-reco/scripts/../known-patterns.json: 7 pattern(s)

.claude/skills/arcodange-bank-reco/known-patterns.json

@@ -0,0 +1,60 @@
+{
+  "_schema": "v1",
+  "_description": "Operator-curated catalogue of known recurring/intentional bank movements. Used by bank-match.sh to annotate the BANK-ONLY bucket so the operator can immediately tell 'needs Dolibarr entry' from 'documented intentional gap'. Edit this file as new recurring patterns emerge.",
+  "_match_rules": "Pattern matched case-insensitively as a regex against the bank label. Optional filters: bank (qonto|wise), side (credit|debit), amount_min, amount_max, type (Wise activity type). All present filters must match.",
+  "_classifications": {
+    "capital_deposit":    "Apport en capital social. Dolibarr account 1013 (capital souscrit appelé versé).",
+    "social_charges":     "URSSAF, retraite complémentaire, etc. Dolibarr account 645x.",
+    "ai_subscription":    "Claude / Mistral / OpenAI / similar. Dolibarr account 6262 (frais télécom / abonnements logiciels).",
+    "bank_fee":           "Plan bancaire, frais d'opération, refunds. Dolibarr account 627 (services bancaires).",
+    "internal_topup":     "Solde Wise/Qonto rechargé pour couvrir un frais immédiat. Often nets out.",
+    "personal_apport":    "Apport en compte courant d'associé (Gabriel finançant Arcodange depuis son perso). Dolibarr account 4551.",
+    "needs_classification": "Pattern catched but no Dolibarr account assignment defined yet; surface for review."
+  },
+  "patterns": [
+    {
+      "pattern": "FOUREZ.*Quentin",
+      "classification": "capital_deposit",
+      "bank": "qonto",
+      "side": "credit",
+      "note": "Apport en capital social initial 1000 €. Maître FOUREZ Quentin, notaire centralisateur du dépôt. Date typique : 2026-01-21. Dolibarr: account 1013."
+    },
+    {
+      "pattern": "URSSAF",
+      "classification": "social_charges",
+      "bank": "qonto",
+      "side": "debit",
+      "note": "Cotisations sociales URSSAF (régime mensuel/trimestriel). Dolibarr: account 645100 (charges de sécurité sociale)."
+    },
+    {
+      "pattern": "MISTRAL\\.AI",
+      "classification": "ai_subscription",
+      "side": "debit",
+      "note": "Mistral AI API subscription. Récurrent mensuel. Dolibarr: account 6262 + supplier 'Mistral AI'."
+    },
+    {
+      "pattern": "CLAUDE\\.AI",
+      "classification": "ai_subscription",
+      "side": "debit",
+      "note": "Claude AI subscription (Anthropic). Récurrent mensuel. Dolibarr: account 6262 + supplier 'Anthropic'."
+    },
+    {
+      "pattern": "Wise.*Plan",
+      "classification": "bank_fee",
+      "side": "debit",
+      "note": "Wise account plan billed via card. Wise's internal fee for keeping the BUSINESS profile active."
+    },
+    {
+      "pattern": "qonto_fee",
+      "classification": "bank_fee",
+      "bank": "qonto",
+      "note": "Qonto fees ou refunds. Petites valeurs. Dolibarr: account 627."
+    },
+    {
+      "pattern": "BALANCE_DEPOSIT|For your account plan",
+      "classification": "internal_topup",
+      "bank": "wise",
+      "note": "Solde Wise rechargé pour couvrir un frais immédiat (souvent net zéro avec le FEATURE_CHARGE du même jour)."
+    }
+  ]
+}

.claude/skills/arcodange-bank-reco/scripts/bank-match.sh

@@ -24,7 +24,7 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 BANK_CURL="${SCRIPT_DIR}/bank-curl.sh"
 DOL_CURL="${SCRIPT_DIR}/../../dolibarr/scripts/dol-curl.sh"
 
-SINCE=""; UNTIL=""; MONTH=""; WINDOW=7; INCLUDE_FEES=0
+SINCE=""; UNTIL=""; MONTH=""; WINDOW=7; INCLUDE_FEES=0; ENRICH=0
 while [[ $# -gt 0 ]]; do
   case "$1" in
     --since) SINCE="$2"; shift 2 ;;
@@ -32,6 +32,7 @@ while [[ $# -gt 0 ]]; do
     --month) MONTH="$2"; shift 2 ;;
     --window-days) WINDOW="$2"; shift 2 ;;
     --include-fees) INCLUDE_FEES=1; shift ;;
+    --enrich) ENRICH=1; shift ;;
     -h|--help) sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
     *) echo "bank-match.sh: unknown arg: $1" >&2; exit 2 ;;
   esac
@@ -66,9 +67,10 @@ QURL="/v2/transactions?bank_account_id=${QONTO_ACCT}&settled_at_from=${SINCE}T00
 # --- 2. Pull Wise activities ---
 "${BANK_CURL}" wise "/v1/profiles/${WISE_PROFILE_ID}/activities?size=100&since=${SINCE}T00:00:00.000Z&until=${UNTIL}T23:59:59.999Z" > "${WORK}/wise.json"
 
-# --- 3. Pull Dolibarr customer + supplier invoices and their payments ---
+# --- 3. Pull Dolibarr customer + supplier invoices, payments, and bank accounts ---
 "${DOL_CURL}" '/invoices?limit=500&sortfield=t.datef&sortorder=ASC'         > "${WORK}/dol_inv.json"
 "${DOL_CURL}" '/supplierinvoices?limit=500'                                  > "${WORK}/dol_sup.json"
+"${DOL_CURL}" '/bankaccounts'                                                > "${WORK}/dol_acct.json"
 
 mkdir -p "${WORK}/dol_pay" "${WORK}/dol_supay"
 for id in $(python3 -c "import json,sys; print(' '.join(str(r['id']) for r in json.load(open(sys.argv[1])) if r.get('id')))" "${WORK}/dol_inv.json"); do
@@ -78,11 +80,26 @@ for id in $(python3 -c "import json,sys; print(' '.join(str(r['id']) for r in js
   "${DOL_CURL}" "/supplierinvoices/${id}/payments" > "${WORK}/dol_supay/${id}.json" 2>/dev/null || echo "[]" > "${WORK}/dol_supay/${id}.json"
 done
 
+# --- 3b. Optional: enrich Wise TRANSFER activities with wire references ---
+if [[ "${ENRICH}" == "1" ]]; then
+  mkdir -p "${WORK}/wise_refs"
+  for tid in $(python3 -c "
+import json, sys
+acts = json.load(open(sys.argv[1])).get('activities') or []
+for a in acts:
+    r = a.get('resource') or {}
+    if r.get('type')=='TRANSFER' and r.get('id'): print(r['id'])
+" "${WORK}/wise.json"); do
+    "${BANK_CURL}" wise "/v1/transfers/${tid}" > "${WORK}/wise_refs/${tid}.json" 2>/dev/null || true
+  done
+fi
+
 # --- 4. Match in python ---
-python3 - "${WORK}" "${SINCE}" "${UNTIL}" "${WINDOW}" "${INCLUDE_FEES}" <<'PY'
+PATTERNS_FILE="${SCRIPT_DIR}/../known-patterns.json"
+python3 - "${WORK}" "${SINCE}" "${UNTIL}" "${WINDOW}" "${INCLUDE_FEES}" "${PATTERNS_FILE}" "${ENRICH}" <<'PY'
 import json, sys, os, re, datetime, collections
-work, since, until, window_days, include_fees = sys.argv[1:6]
+work, since, until, window_days, include_fees, patterns_file, enrich = sys.argv[1:8]
-window = int(window_days); include_fees = include_fees == "1"
+window = int(window_days); include_fees = include_fees == "1"; enrich = enrich == "1"
 since_d = datetime.date.fromisoformat(since); until_d = datetime.date.fromisoformat(until)
 
 def strip(s): return re.sub(r'<[^>]+>', '', s or '').strip()
@@ -110,7 +127,22 @@ for a in (json.load(open(os.path.join(work,"wise.json"))).get("activities") or [
     m = re.search(r'([\d,.]+)\s*([A-Z]{3})', pa)
     amt = float(m.group(1).replace(",", "")) if m else 0.0
     title = strip(a.get("title") or "")[:40]
-    wise_movs.append({"bank":"Wise", "date":dt, "sign":sign, "amount":amt, "label":title, "op":typ, "matched_dol":None, "matched_internal":False})
+    res = a.get("resource") or {}
+    resource_id = str(res.get("id")) if res.get("type") == "TRANSFER" else None
+    wise_movs.append({"bank":"Wise", "date":dt, "sign":sign, "amount":amt, "label":title, "op":typ, "matched_dol":None, "matched_internal":False, "wise_resource_id":resource_id, "wire_ref":""})
+
+# 4b'. If --enrich, load per-transfer wire references and attach to Wise movs
+if enrich:
+    ref_dir = os.path.join(work, "wise_refs")
+    if os.path.isdir(ref_dir):
+        for m in wise_movs:
+            if not m["wise_resource_id"]: continue
+            p = os.path.join(ref_dir, f"{m['wise_resource_id']}.json")
+            if not os.path.isfile(p): continue
+            try:
+                t = json.load(open(p))
+                m["wire_ref"] = (t.get("reference") or "")
+            except Exception: pass
 
 bank_movs = qonto_movs + wise_movs
 
@@ -121,7 +153,7 @@ for w in [m for m in bank_movs if m["bank"]=="Wise" and m["sign"]=="-"]:
             w["matched_internal"] = q; q["matched_internal"] = w
             break
 
-# 4d. Normalize Dolibarr payments
+# 4d. Normalize Dolibarr payments — carry socid too for avoir netting
 dol_pays = []
 inv_by_id = {str(r["id"]): r for r in json.load(open(os.path.join(work,"dol_inv.json")))}
 for fn in os.listdir(os.path.join(work,"dol_pay")):
@@ -131,7 +163,9 @@ for fn in os.listdir(os.path.join(work,"dol_pay")):
         d = datetime.datetime.strptime(p["date"], "%Y-%m-%d %H:%M:%S").date()
         if d < since_d or d > until_d: continue
         amt = float(p.get("amount") or 0)
-        dol_pays.append({"side":"customer", "ref":inv["ref"], "date":d, "amount":amt, "fk_account":inv.get("fk_account"), "matched_bank":None})
+        dol_pays.append({"side":"customer", "ref":inv["ref"], "date":d, "amount":amt,
+                         "fk_account":inv.get("fk_account"), "socid":inv.get("socid"),
+                         "matched_bank":None, "netted_against":None})
 
 sup_by_id = {str(r["id"]): r for r in json.load(open(os.path.join(work,"dol_sup.json")))}
 for fn in os.listdir(os.path.join(work,"dol_supay")):
@@ -141,37 +175,136 @@ for fn in os.listdir(os.path.join(work,"dol_supay")):
         d = datetime.datetime.strptime(p["date"], "%Y-%m-%d %H:%M:%S").date()
         if d < since_d or d > until_d: continue
         amt = float(p.get("amount") or 0)
-        dol_pays.append({"side":"supplier", "ref":sup["ref"], "date":d, "amount":amt, "fk_account":sup.get("fk_account"), "matched_bank":None})
+        dol_pays.append({"side":"supplier", "ref":sup["ref"], "date":d, "amount":amt,
+                         "fk_account":sup.get("fk_account"), "socid":sup.get("socid"),
+                         "matched_bank":None, "netted_against":None})
 
-# 4e. Match: each bank movement (non-internal) tries to find a Dolibarr counterpart
+# 4d.1. AVOIR cycle netting: an AVC (credit note) for -X on socid S cancels out
-for m in [x for x in bank_movs if not x["matched_internal"]]:
+# a FAC for +X on the same socid, within a small date window. Bank sees the NET
-    bank_signed = m["amount"] if m["sign"]=="+" else -m["amount"]
+# of the cycle (typically +X for the reissued FAC with the new ref scheme).
-    # For customer payments (Dol records them as positive amounts): +bank credit matches +dol customer payment
+# Pair an AVC with a FAC of opposite sign + equal abs(amount) + same socid +
-    # For supplier payments: -bank debit matches +dol supplier payment (positive in Dol since it's the amount paid out)
+# within ±5d. Mark both as "netted" so they're excluded from matching and
-    # Heuristic: match abs(amount) within 0.01 and date within window.
+# excluded from the dolibarr-only failure count.
-    candidates = [p for p in dol_pays if p["matched_bank"] is None and abs(p["amount"] - m["amount"]) < 0.01 and abs((p["date"] - m["date"]).days) <= window]
+avcs = [p for p in dol_pays if p["side"]=="customer" and p["ref"].startswith("AVC") and p["amount"] < 0]
+for avc in avcs:
+    candidates = [p for p in dol_pays
+                  if p is not avc
+                  and p["side"]=="customer"
+                  and p["socid"] == avc["socid"]
+                  and abs(p["amount"] + avc["amount"]) < 0.01  # opposite signs equal magnitude
+                  and abs((p["date"] - avc["date"]).days) <= 5
+                  and p["netted_against"] is None
+                  and p["matched_bank"] is None]
+    if candidates:
+        # Prefer the OLDEST (the original cancelled FAC), not the reissue.
+        # Heuristic: refs with shorter / older numbering scheme. If multiple,
+        # pick smallest date delta.
+        candidates.sort(key=lambda p: (abs((p["date"] - avc["date"]).days), p["ref"]))
+        partner = candidates[0]
+        avc["netted_against"] = partner["ref"]
+        partner["netted_against"] = avc["ref"]
+
+# 4e. Match — two-pass:
+#   PASS 1 (strong) : Wise transfers with an --enrich'd wire reference containing
+#                     a "FAC***" pattern try to match the Dolibarr invoice with
+#                     that exact ref. This is the highest-confidence match.
+#   PASS 2 (loose)  : remaining bank movements use the date+amount heuristic.
+# Netted Dolibarr entries (avoir cycle) are excluded from both passes.
+
+# Build customer ref -> dol payment index (only un-netted, un-matched entries)
+ref_index = collections.defaultdict(list)
+for p in dol_pays:
+    if p["matched_bank"] is None and p["netted_against"] is None:
+        # Strip trailing dash/suffix variants — FAC002CL0001002 vs FAC002-CL0001002 are equivalent
+        normalized = re.sub(r'[^A-Z0-9]', '', p["ref"].upper())
+        ref_index[normalized].append(p)
+
+# Pass 1: strong match on wire references
+for m in [x for x in bank_movs if not x["matched_internal"] and x.get("wire_ref")]:
+    refs_in_wire = re.findall(r'FAC\d+(?:CL\d+)?', (m["wire_ref"] or "").upper().replace("-",""))
+    for r in refs_in_wire:
+        if r in ref_index and ref_index[r]:
+            p = ref_index[r].pop(0)
+            m["matched_dol"] = p; m["match_kind"] = "wire-ref"
+            p["matched_bank"] = m
+            break
+
+# Pass 2: loose date+amount match for remaining bank movements
+for m in [x for x in bank_movs if not x["matched_internal"] and not x["matched_dol"]]:
+    candidates = [p for p in dol_pays
+                  if p["matched_bank"] is None and p["netted_against"] is None
+                  and abs(p["amount"] - m["amount"]) < 0.01
+                  and abs((p["date"] - m["date"]).days) <= window]
     if candidates:
-        # Pick smallest date delta
         candidates.sort(key=lambda p: abs((p["date"] - m["date"]).days))
         p = candidates[0]
-        m["matched_dol"] = p; p["matched_bank"] = m
+        m["matched_dol"] = p; m["match_kind"] = "amt+date"
+        p["matched_bank"] = m
+
+# 4f. Annotate non-matched movements with known-patterns catalog
+patterns = []
+if os.path.isfile(patterns_file):
+    try: patterns = json.load(open(patterns_file)).get("patterns", [])
+    except Exception as e: print(f"  /!\\ failed to load {patterns_file}: {e}", file=sys.stderr)
+
+def match_pattern(mov):
+    # Match against both the bank label AND the operation type — different
+    # banks surface useful info in different fields (Qonto puts the operation
+    # type in `op`, e.g. "qonto_fee"; Wise puts the activity type in `op`,
+    # e.g. "BALANCE_DEPOSIT", and the human title in `label`).
+    haystack = (mov.get("label") or "") + " | " + (mov.get("op") or "")
+    for pat in patterns:
+        if pat.get("bank") and pat["bank"] != mov["bank"].lower(): continue
+        if pat.get("side") and pat["side"] != ("credit" if mov["sign"]=="+" else "debit"): continue
+        amin = pat.get("amount_min"); amax = pat.get("amount_max")
+        if amin is not None and mov["amount"] < amin: continue
+        if amax is not None and mov["amount"] > amax: continue
+        if re.search(pat["pattern"], haystack, re.IGNORECASE):
+            return pat
+    return None
+
+for m in bank_movs:
+    if m["matched_dol"] or m["matched_internal"]: continue
+    m["known"] = match_pattern(m)
 
 # --- 5. Render ---
+
+# Load Dolibarr bank accounts (for fk_account context on dolibarr-only)
+dol_accts = {}
+try:
+    for a in json.load(open(os.path.join(work, "dol_acct.json"))):
+        dol_accts[str(a["id"])] = {"ref": a.get("ref","-"), "label": a.get("label","-"), "country": a.get("country_code","")}
+except Exception: pass
+
+# Heuristic: which Dolibarr accounts are NOT covered by Qonto/Wise API today?
+# Convention: CCA = Compte Courant d'Associé (personal). Anything not QON*/WIS*
+# is treated as "API-invisible" and tagged as such.
+def account_kind(fk_account):
+    if not fk_account: return ("unknown", "fk_account=None")
+    a = dol_accts.get(str(fk_account))
+    if not a: return ("unknown", f"fk_account={fk_account} (not in /bankaccounts)")
+    ref = (a["ref"] or "").upper()
+    if ref.startswith(("QON", "WIS")):
+        return ("api_tracked", f"{a['ref']} ({a['label']})")
+    return ("personal_or_other", f"{a['ref']} ({a['label']})")
+
 def fmt_bank(m):
     return f"  {m['bank']:<5} {m['date']}  {m['sign']:<2}{m['amount']:>9.2f}  {m['op'][:18]:<18}  {m['label']}"
 
-print(f"# Bank reconciliation: {since} → {until}  (window ±{window}d, fees: {'on' if include_fees else 'off'})")
+print(f"# Bank reconciliation: {since} → {until}  (window ±{window}d, fees: {'on' if include_fees else 'off'}, enrich: {'on' if enrich else 'off'})")
 print()
 matched   = [m for m in bank_movs if m["matched_dol"]]
 internal  = [m for m in bank_movs if m["matched_internal"] and m["sign"]=="-"]
 bank_only = [m for m in bank_movs if not m["matched_dol"] and not m["matched_internal"]]
-dol_only  = [p for p in dol_pays if p["matched_bank"] is None]
+netted_dol_pairs = [p for p in dol_pays if p["netted_against"]]
+dol_only  = [p for p in dol_pays if p["matched_bank"] is None and p["netted_against"] is None]
 
 print(f"=== MATCHED  ({len(matched)} bank ↔ Dolibarr) ===")
 for m in sorted(matched, key=lambda m: m["date"]):
     p = m["matched_dol"]
     delta = (p["date"] - m["date"]).days
-    print(fmt_bank(m) + f"   ↔   {p['side']:<8} {p['ref']:<24} ({p['date']}, Δ{delta:+d}d)")
+    kind = m.get("match_kind", "?")
+    print(fmt_bank(m) + f"   ↔[{kind}]   {p['side']:<8} {p['ref']:<24} ({p['date']}, Δ{delta:+d}d)")
 print()
 
 print(f"=== INTERNAL (Wise↔Qonto consolidations, {len(internal)}) ===")
@@ -180,19 +313,51 @@ for m in sorted(internal, key=lambda m: m["date"]):
     print(fmt_bank(m) + f"   ↔   {other['bank']} {other['date']} {other['sign']}{other['amount']:.2f}")
 print()
 
-print(f"=== BANK-ONLY  ({len(bank_only)} bank movements without Dolibarr counterpart) ===")
+# Avoir cycles netted out (informational; bank correctly sees only the net)
-for m in sorted(bank_only, key=lambda m: m["date"]):
+if netted_dol_pairs:
+    print(f"=== AVOIR-NETTED ({len(netted_dol_pairs)} Dolibarr entries pairing AVC↔FAC cancellation cycles) ===")
+    for p in sorted(netted_dol_pairs, key=lambda p: (p["date"], p["ref"])):
+        print(f"  {p['side']:<8} {p['date']}  {p['amount']:>9.2f}  {p['ref']:<24}  ↔ netted against {p['netted_against']}")
+    print()
+
+bank_known   = [m for m in bank_only if m.get("known")]
+bank_unknown = [m for m in bank_only if not m.get("known")]
+
+print(f"=== BANK-ONLY — known patterns ({len(bank_known)}, intentional gaps documented in known-patterns.json) ===")
+for m in sorted(bank_known, key=lambda m: m["date"]):
+    k = m["known"]
+    cls = k.get("classification","?")
+    print(fmt_bank(m) + f"   [{cls}]")
+    print(f"      └─ {k.get('note','')}")
+print()
+
+print(f"=== BANK-ONLY — unknown ({len(bank_unknown)}, NEEDS attention: missing supplier invoice / unrecorded payment / new pattern) ===")
+for m in sorted(bank_unknown, key=lambda m: m["date"]):
     print(fmt_bank(m))
 print()
 
-print(f"=== DOLIBARR-ONLY  ({len(dol_only)} Dolibarr payments without bank movement) ===")
+# Split dolibarr-only by whether the fk_account is API-tracked (real gap)
-for p in sorted(dol_only, key=lambda p: p["date"]):
+# or personal_or_other (expected gap — we have no API on those accounts)
-    print(f"  {p['side']:<8} {p['date']}  {p['amount']:>9.2f}  {p['ref']}  (fk_account={p['fk_account']})")
+dol_only_api      = [p for p in dol_only if account_kind(p["fk_account"])[0] == "api_tracked"]
+dol_only_personal = [p for p in dol_only if account_kind(p["fk_account"])[0] != "api_tracked"]
+
+print(f"=== DOLIBARR-ONLY — on API-tracked accounts ({len(dol_only_api)}, REAL GAP: bank should have shown this) ===")
+for p in sorted(dol_only_api, key=lambda p: p["date"]):
+    _, ctx = account_kind(p["fk_account"])
+    print(f"  {p['side']:<8} {p['date']}  {p['amount']:>9.2f}  {p['ref']:<24}  ({ctx})")
 print()
 
-# Verdict
+print(f"=== DOLIBARR-ONLY — on accounts NOT in API scope ({len(dol_only_personal)}, expected gap: CCA1 perso etc.) ===")
-fails = len(bank_only) + len(dol_only)
+for p in sorted(dol_only_personal, key=lambda p: p["date"]):
-print("-" * 80)
+    _, ctx = account_kind(p["fk_account"])
-print(f"# {len(matched)} matched, {len(internal)} internal, {len(bank_only)} bank-only, {len(dol_only)} dolibarr-only")
+    print(f"  {p['side']:<8} {p['date']}  {p['amount']:>9.2f}  {p['ref']:<24}  ({ctx})")
+print()
+
+# Verdict: only UNKNOWN bank-only AND dol-only-on-API-tracked count as failures.
+# Avoir-netted pairs and personal-account dolibarr entries are intentional/expected.
+fails = len(bank_unknown) + len(dol_only_api)
+print("-" * 100)
+print(f"# {len(matched)} matched, {len(internal)} internal, {len(netted_dol_pairs)} avoir-netted, {len(bank_known)} bank-known, {len(bank_unknown)} bank-UNKNOWN, {len(dol_only_api)} dol-only-API, {len(dol_only_personal)} dol-only-personal")
+print(f"# patterns loaded from {patterns_file}: {len(patterns)} pattern(s)")
 sys.exit(0 if fails == 0 else 1)
 PY

.claude/skills/arcodange-email-ingest/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: arcodange-email-ingest
+description: Scrape supplier-invoice emails from the Arcodange Zoho mailbox (`gabrielradureau@arcodange.fr` + its `books@arcodange.fr` alias + forwarded Gmail) via the Zoho Mail OAuth API, list candidates matching supplier patterns, download PDF attachments, run pdftotext + heuristic extract, and emit Dolibarr-ready supplier-invoice draft JSON for the operator to paste into the Dolibarr UI. Two workflows — (1) list candidates in a folder (default `/Inbox/books` where the alias auto-routes mail); (2) inspect one message by id, download + parse PDFs, propose draft entries. Surfaces concrete data: supplier name guess (first PDF line), invoice ref, invoice date, total HT/TVA/TTC, VAT rate. Read-only at every layer (Zoho scopes are READ-only; no write to Dolibarr). Use when the user asks "list pending supplier invoices in mail", "ingest invoices from email", "draft Dolibarr entry from this email", "audit cohort supplier docs from mail". Depends on `dolibarr` for the shared `.env`. SKIP for write-side Dolibarr operations (V9 candidate), for non-Zoho mailboxes (use IMAP fallback in a future skill if needed), and for attachments that aren't PDFs (only PDF text extraction is wired today).
+requires:
+  bins: ["curl", "jq", "python3", "pdftotext"]
+  auth: true
+---
+
+# arcodange-email-ingest — supplier-invoice emails → Dolibarr draft
+
+Close the inbound side of the accounting loop: bills land in `books@arcodange.fr`, this skill turns them into Dolibarr-ready draft entries for the operator to validate + create.
+
+Depends on the [dolibarr](../dolibarr/SKILL.md) base skill (shared `.env`).
+
+**CLI shortcuts:** `bin/arcodange email list | inspect | curl`
+
+## Architecture choice — Zoho API, not IMAP
+
+We chose the Zoho Mail OAuth API over IMAP because:
+- **Richer metadata** — folder paths, attachment IDs, search operators, threads.
+- **One account covers everything** — `books@arcodange.fr` is an alias of `gabrielradureau@arcodange.fr`. One refresh_token + the `/accounts` endpoint exposes both, plus all the other aliases (`contact@`, `bonjour@`, etc.).
+- **Gmail folded in via forwarding** — `arcodange@gmail.com` forwards incoming to `books@` (configured in Gmail UI). No Google API setup, no app-passwords, no second OAuth flow.
+- **Token-only auth** — no app-password fragility, no SCA dance (unlike Wise).
+
+The single canonical inbox path: **`/Inbox/books`** — Zoho's auto-filter routes incoming mail to the `books@` alias into this sub-folder. Scan it first; widen with `--all-folders` only if needed.
+
+## Prerequisites
+
+1. Base skill set up ([dolibarr/README.md](../dolibarr/README.md)).
+2. Zoho OAuth Self-Client created and a refresh_token generated. The `.env` extension:
+   ```
+   ZOHO_CLIENT_ID=<from api-console.zoho.com self-client>
+   ZOHO_CLIENT_SECRET=<same>
+   ZOHO_REFRESH_TOKEN=<exchanged from one-time code>
+   ZOHO_DC=eu                # eu | com | in | au
+   ```
+   Setup walkthrough is in the V8 prep section of the cohort review notes.
+3. Gmail forwarding to `books@arcodange.fr` enabled (Gmail Settings → Forwarding and POP/IMAP).
+4. `pdftotext` (`brew install poppler` on macOS).
+
+## Workflows
+
+### 1. List candidates
+
+```bash
+bin/arcodange email list                      # default: /Inbox/books, last 30 msgs, no filter
+bin/arcodange email list --candidates-only    # filter to subjects/attachments matching supplier patterns
+bin/arcodange email list --folder /Inbox/contact --limit 50
+bin/arcodange email list --all-folders --candidates-only   # scan everything (slower, more API calls)
+```
+
+Captured at [examples/email-list.txt](examples/email-list.txt). The candidate filter matches subjects against `facture|invoice|receipt|reçu|payment|paiement|abonnement|subscription|order|commande|bill` OR any message with an attachment.
+
+**Hard exclusions** (V8.1) — applied before the candidate test, regardless of attachments:
+- Subjects starting with `Invitation:` / `Updated invitation:` / `Canceled event:` / `Accepted:` / `Declined:` / `Tentative:` / `Maybe:` (after stripping `Re:` / `Fwd:` / `Tr:` prefixes) → filters calendar events that always carry an `.ics` attachment.
+- Senders matching newsletter/marketing patterns (`updates.<domain>`, `noreply@*calendar*`, `news@`, `newsletter@`, etc.).
+
+The `[*]` column marks candidates, `[Y]` marks emails with attachments. Compared to V8.0, V8.1 cuts the `--all-folders --candidates-only` baseline from ~27 noisy entries down to ~12 actionable ones.
+
+### 2. Inspect one email + draft Dolibarr entry
+
+```bash
+bin/arcodange email inspect 1775141901205014300
+bin/arcodange email inspect 1775141901205014300 --folder /Inbox/books   # default
+bin/arcodange email inspect 1775141901205014300 --save-pdf ~/Documents/factures-2026-Q2/
+bin/arcodange email inspect 1775141901205014300 --json    # machine-readable
+```
+
+The script:
+1. Fetches the email metadata (subject / from / date) via `/messages/view`.
+2. Lists attachments via `/messages/{mid}/attachmentinfo`.
+3. Downloads each attachment via `/messages/{mid}/attachments/{aid}`.
+4. For each `.pdf`, runs `pdftotext -layout`, applies regex heuristics to extract:
+   - Supplier name guess (first non-empty PDF line — often the supplier letterhead).
+   - Invoice reference (`facture/invoice n° XXX`).
+   - Invoice date.
+   - Total HT / TVA / TTC + VAT rate %.
+5. Emits a draft JSON record per attachment — paste into the Dolibarr UI manually.
+
+Heuristics are intentionally conservative (regex-based, no LLM dependency). For PDF templates where the heuristic fails, the raw `pdftotext` output is on disk in the work dir; rerun with `--save-pdf` to grab the PDF for manual entry.
+
+Captured at [examples/email-inspect.txt](examples/email-inspect.txt) for the V8 baseline (Mistral AI receipt).
+
+## What it doesn't do (V8.0 scope)
+
+- **Does not write to Dolibarr.** The supplier invoice is still created manually in the Dolibarr UI from the draft JSON. V9 candidate: automate via `/supplierinvoices` POST.
+- **Does not mark emails as ingested.** Each run re-emits the same candidates. Implementing this requires extending the OAuth scope: the current refresh_token only has READ scopes (`ZohoMail.messages.READ` etc.). The flag-set endpoint (`PUT /api/accounts/{aid}/updatemessage`) requires `ZohoMail.messages.UPDATE`, which would force the user to regenerate the refresh_token. **V8.2 candidate** — once the user opts in to the wider scope, `--mark-ingested` becomes a one-line flag on `email-inspect.sh` and `is_candidate()` in `email-list.sh` learns to skip messages with `flagid == flag_info`.
+- **No body extraction yet.** We only parse PDF attachments. Inline-HTML invoices (rare — most suppliers send PDFs) would need body fetch via `/content`.
+- **Heuristic extraction is best-effort.** Different supplier PDF templates yield different field-extraction reliability. The draft JSON is a starting point, not ground truth.
+
+## Token cache
+
+`zoho-curl.sh` caches the OAuth access_token in `$TMPDIR/zoho-access-$USER` (mode 600, TTL 50 min). Avoids hitting Zoho's OAuth refresh rate-limit on every invocation. On 401, the wrapper auto-refreshes once and retries.
+
+## API endpoints used (Zoho Mail)
+
+| Endpoint | Purpose |
+|---|---|
+| `POST /oauth/v2/token` (accounts.zoho.{dc}) | Refresh access_token from refresh_token |
+| `GET /accounts` | Discover accountId + aliases on the account |
+| `GET /accounts/{aid}/folders` | List folders (with paths like `/Inbox/books`) |
+| `GET /accounts/{aid}/messages/view?folderId=&limit=&start=` | List messages in a folder |
+| `GET /accounts/{aid}/folders/{fid}/messages/{mid}/attachmentinfo` | List attachments metadata |
+| `GET /accounts/{aid}/folders/{fid}/messages/{mid}/attachments/{aid}` | Download attachment bytes |
+
+## Out of scope
+
+- **Writing to Dolibarr** (V9 candidate — would lift the read-only constraint on the API key, or use a separate write-scoped key).
+- **Marking ingested emails** (V8.1 trivial follow-up).
+- **Non-PDF attachments** (heuristics are PDF-specific).
+- **Body-text extraction** (would need `/content` endpoint, deferred).
+- **IMAP fallback** for non-Zoho mailboxes (deferred — Gmail forwarding to books@ covers the only known external mailbox today).
+- **LLM-based extraction** (deferred — regex covers the current set of supplier templates well enough).

.claude/skills/arcodange-email-ingest/examples/email-inspect.txt

@@ -0,0 +1,31 @@
+================================================================================
+ Email 1775141901205014300
+================================================================================
+  subject   : Votre facture nº MSTRL-API-814045-001 de Mistral AI SAS
+  from      : no-reply@mistral.ai
+  date      : 2026-04-02
+  attached  : True
+
+  -- Attachment 1: invoice-MSTRL-API-814045-001.pdf (74377 bytes, 1771 chars extracted) --
+    pdf_top_line     = 'Facture'
+    invoice_ref      = 'API-814045-001'
+    invoice_date_raw = None
+    total_ht         = None
+    total_tva        = None
+    total_ttc        = None
+    vat_rate_pct     = '20.0'
+
+  Suggested Dolibarr supplier-invoice draft entries:
+[
+    {
+        "supplier_hint": "Facture",
+        "invoice_ref": "API-814045-001",
+        "invoice_date": null,
+        "total_ht": null,
+        "total_tva": null,
+        "total_ttc": null,
+        "vat_rate_pct": "20.0",
+        "source_email": "1775141901205014300",
+        "source_attachment": "invoice-MSTRL-API-814045-001.pdf"
+    }
+]

.claude/skills/arcodange-email-ingest/examples/email-list-all-folders.txt

@@ -0,0 +1,16 @@
+date        cand att messageId               folder                  from                                  subject
+----------------------------------------------------------------------------------------------------------------------------------
+2026-05-20  [*]  [Y]  1779312401677014300     /clients/KissMetrics    rsirvent@digitalocean.com             Re: VM not running despite status=active, after volume 
+2026-05-20  [*]  [Y]  1779298419301014300     /clients/KissMetrics    tdziuba@kissmetrics.io                Re: VM not running despite status=active, after volume 
+2026-05-20  [*]  [Y]  1779285954272004400     /clients/KissMetrics    tdziuba@kissmetrics.io                Re: VM not running despite status=active, after volume 
+2026-05-05  [*]  [ ]  1777970798248014300     /Inbox/abonnements      freemobile@free-mobile.fr             Votre facture mobile Free est disponible
+2026-04-21  [*]  [Y]  1776785469477004300     /Notification           noreply@hiway.fr                      Darnis Operations - Facture F1042
+2026-04-12  [*]  [Y]  1776017238960014300     /Inbox/books            arcodange@gmail.com                   Fwd: Your receipt from Anthropic Ireland, Limited #2109
+2026-04-04  [*]  [ ]  1775264759983014300     /Inbox/abonnements      freemobile@free-mobile.fr             Votre facture mobile Free est disponible
+2026-04-02  [*]  [Y]  1775141901205014300     /Inbox/books            no-reply@mistral.ai                   Votre facture nº MSTRL-API-814045-001 de Mistral AI SAS
+2026-03-05  [*]  [ ]  1772689535069004400     /Inbox/helloworld       freemobile@free-mobile.fr             Votre facture mobile Free est disponible
+2026-02-08  [*]  [Y]  1770582421208004400     /Inbox/bureaux          ne-pas-repondre@portailpro.gouv.fr    Valider votre espace personnel sur Portailpro.gouv
+2026-01-09  [*]  [ ]  1767989744791004400     /Inbox/books            gabrielradureau@gmail.com             Fwd: INPI - Votre paiement pour la commande Réf. 181876
+2026-01-06  [*]  [Y]  1767710535894005600     /Inbox                  gabrielradureau@gmail.com             Statuts
+----------------------------------------------------------------------------------------------------------------------------------
+# 12 message(s) (candidates only)

.claude/skills/arcodange-email-ingest/examples/email-list.txt

@@ -0,0 +1,7 @@
+date        cand att messageId               folder                  from                                  subject
+----------------------------------------------------------------------------------------------------------------------------------
+2026-04-12  [*]  [Y]  1776017238960014300     /Inbox/books            arcodange@gmail.com                   Fwd: Your receipt from Anthropic Ireland, Limited #2109
+2026-04-02  [*]  [Y]  1775141901205014300     /Inbox/books            no-reply@mistral.ai                   Votre facture nº MSTRL-API-814045-001 de Mistral AI SAS
+2026-01-09  [*]  [ ]  1767989744791004400     /Inbox/books            gabrielradureau@gmail.com             Fwd: INPI - Votre paiement pour la commande Réf. 181876
+----------------------------------------------------------------------------------------------------------------------------------
+# 3 message(s) (candidates only)

.claude/skills/arcodange-email-ingest/scripts/email-inspect.sh

@@ -0,0 +1,256 @@
+#!/usr/bin/env bash
+# Inspect one email by id and propose a Dolibarr supplier-invoice draft.
+#
+# Usage:
+#   email-inspect.sh <messageId> [--folder PATH]    # default folder: /Inbox/books
+#                                [--save-pdf DIR]   # save PDF attachments under DIR/
+#                                [--json]           # emit a single JSON object on stdout
+#
+# Pipeline (read-only):
+#   1. Find the message (in the given folder, default /Inbox/books).
+#   2. List attachments via /attachmentinfo.
+#   3. For each PDF attachment: download, run pdftotext, extract supplier-side
+#      heuristics (name, totals, dates, ref).
+#   4. Emit a draft "Dolibarr-ready" record per attachment so the operator can
+#      hand-create the supplier invoice in the Dolibarr UI.
+#
+# This skill DOES NOT write to Dolibarr. Auto-creation of supplier invoices is
+# V9 candidate.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ZOHO_CURL="${SCRIPT_DIR}/zoho-curl.sh"
+
+if [[ $# -lt 1 ]]; then
+  echo "email-inspect.sh: missing <messageId>" >&2
+  echo "  Hint: bin/arcodange email list  to see candidate ids." >&2
+  exit 2
+fi
+MID="$1"; shift || true
+FOLDER="/Inbox/books"; SAVE_PDF_DIR=""; FMT="text"
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --folder)   FOLDER="$2"; shift 2 ;;
+    --save-pdf) SAVE_PDF_DIR="$2"; shift 2 ;;
+    --json)     FMT="json"; shift ;;
+    -h|--help)  sed -n '2,18p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "email-inspect.sh: unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+command -v pdftotext >/dev/null || { echo "email-inspect.sh: pdftotext not found (brew install poppler)" >&2; exit 2; }
+
+WORK="$(mktemp -d -t emailinspect.XXXXXX)"
+trap 'rm -rf "${WORK}"' EXIT
+
+# 1. accountId + folderId
+"${ZOHO_CURL}" /accounts > "${WORK}/accounts.json"
+AID=$(python3 -c "import json,sys; d=json.load(open(sys.argv[1])); print((d.get('data') or [{}])[0].get('accountId',''))" "${WORK}/accounts.json")
+"${ZOHO_CURL}" "/accounts/${AID}/folders" > "${WORK}/folders.json"
+FID=$(python3 -c "
+import json, sys
+d = json.load(open(sys.argv[1]))
+target = sys.argv[2]
+for f in (d.get('data') or []):
+    if f.get('path') == target:
+        print(f.get('folderId')); break" "${WORK}/folders.json" "${FOLDER}")
+[[ -z "${FID}" ]] && { echo "email-inspect.sh: folder '${FOLDER}' not found" >&2; exit 2; }
+
+# 2. Find the message in the folder listing (to grab metadata: subject, from, date)
+"${ZOHO_CURL}" "/accounts/${AID}/messages/view?folderId=${FID}&limit=100&sortorder=false&start=1" > "${WORK}/folder_msgs.json"
+python3 - "${WORK}/folder_msgs.json" "${MID}" > "${WORK}/meta.json" <<'PY'
+import json, sys
+d = json.load(open(sys.argv[1]))
+mid = sys.argv[2]
+for m in (d.get("data") or []):
+    if str(m.get("messageId")) == mid:
+        json.dump(m, sys.stdout); sys.exit(0)
+sys.exit(f"messageId {mid} not found in this folder")
+PY
+
+# 3. Attachment metadata
+"${ZOHO_CURL}" "/accounts/${AID}/folders/${FID}/messages/${MID}/attachmentinfo" > "${WORK}/attachinfo.json"
+
+# 4. Download each attachment — needs raw bytes (Accept: */*), not the JSON
+# wrapper's default. We bypass zoho-curl.sh for the attachment download but
+# reuse the cached access_token it wrote.
+set -a; source "${SCRIPT_DIR}/../../dolibarr/.env"; set +a
+: "${ZOHO_DC:=eu}"
+TOKEN_CACHE="${TMPDIR:-/tmp}/zoho-access-$(whoami)"
+if [[ ! -s "${TOKEN_CACHE}" ]]; then
+  echo "email-inspect.sh: missing access token cache — run any zoho-curl call first to populate it" >&2
+  exit 2
+fi
+ACCESS_TOKEN=$(cat "${TOKEN_CACHE}")
+MAIL_BASE="https://mail.zoho.${ZOHO_DC}/api"
+
+mkdir -p "${WORK}/atts" "${WORK}/text"
+ATT_IDS=$(python3 -c "
+import json, sys
+d = json.load(open(sys.argv[1]))
+data = d.get('data') or {}
+for a in (data.get('attachments') or []):
+    print(f\"{a.get('attachmentId')}|{a.get('attachmentName','-')}\")" "${WORK}/attachinfo.json")
+while IFS='|' read -r aid aname; do
+  [[ -z "${aid}" ]] && continue
+  outpath="${WORK}/atts/${aname}"
+  curl -sS \
+    -H "Authorization: Zoho-oauthtoken ${ACCESS_TOKEN}" \
+    -H "Accept: */*" \
+    --max-time 60 \
+    -o "${outpath}" \
+    "${MAIL_BASE}/accounts/${AID}/folders/${FID}/messages/${MID}/attachments/${aid}" || true
+  # If pdf, extract text (bash 3.2 compatible — no ${var,,})
+  aname_lc=$(echo "${aname}" | tr '[:upper:]' '[:lower:]')
+  if [[ "${aname_lc}" == *.pdf ]]; then
+    pdftotext -layout "${outpath}" "${WORK}/text/${aname%.pdf}.txt" 2>/dev/null || true
+  fi
+done <<< "${ATT_IDS}"
+
+# Optional save
+if [[ -n "${SAVE_PDF_DIR}" ]]; then
+  mkdir -p "${SAVE_PDF_DIR}"
+  cp "${WORK}/atts/"*.pdf "${SAVE_PDF_DIR}/" 2>/dev/null || true
+fi
+
+# 5. Heuristic extract + render
+python3 - "${WORK}" "${FMT}" <<'PY'
+import json, sys, os, re, datetime, glob
+work, fmt = sys.argv[1:3]
+
+meta = json.load(open(os.path.join(work,"meta.json")))
+ts = int(meta.get("sentDateInGMT") or meta.get("receivedTime") or 0) // 1000
+mail_date = datetime.datetime.fromtimestamp(ts).strftime("%Y-%m-%d") if ts else None
+mail_from = (meta.get("fromAddress") or meta.get("sender") or "-").replace("&lt;","<").replace("&gt;",">").replace("<","").replace(">","")
+mail_subject = meta.get("subject") or "-"
+
+# Heuristics on PDF text
+def extract(text):
+    out = {}
+    # First non-empty line is often the supplier name (or the address block first line)
+    lines = [l.strip() for l in text.splitlines() if l.strip()]
+    out["pdf_top_line"] = lines[0] if lines else None
+
+    # Total TTC / HT / TVA — try multiple French/English patterns
+    def first_match(*patterns):
+        for p in patterns:
+            for line in lines:
+                m = re.search(p, line, re.IGNORECASE)
+                if m: return m.group(1).replace(",", ".").replace(" ", "")
+        return None
+
+    def parse_amount(s):
+        if not s: return None
+        clean = s.replace(",", ".").replace(" ", "")
+        try:
+            v = float(clean)
+            # Money amounts < 1M EUR; filters out VAT-number false positives (FR12345678901)
+            return v if 0 <= v < 1_000_000 else None
+        except: return None
+
+    def first_amount(*patterns):
+        for p in patterns:
+            for line in lines:
+                m = re.search(p, line, re.IGNORECASE)
+                if m:
+                    v = parse_amount(m.group(1))
+                    if v is not None: return f"{v:.2f}"
+        return None
+
+    out["total_ht"]  = first_amount(r'(?:total\s*ht|montant\s*ht|net\s*amount|subtotal)[^\d-]*([\d \.,]+)')
+    # TVA: require currency suffix to avoid matching VAT-number digits
+    out["total_tva"] = first_amount(r'(?:tva|vat)[^\d-]*([\d \.,]+)\s*(?:€|eur)\b')
+    out["total_ttc"] = first_amount(r'(?:total\s*ttc|amount\s*due|total\s*due|grand\s*total|montant\s*total|amount\s*paid)[^\d-]*([\d \.,]+)')
+
+    # Invoice ref — must contain a digit (filters "umber", "Invoice", etc.)
+    m = re.search(r'(?:facture|invoice|receipt|reçu)\s*(?:n[°o]?|number|#|:)\s*([A-Za-z0-9][\w\d/-]{2,})', text, re.IGNORECASE)
+    if m and any(c.isdigit() for c in m.group(1)):
+        out["invoice_ref"] = m.group(1)
+    else:
+        # Fallback: any reasonable ref-shaped token after "Invoice" / "Facture" header
+        m = re.search(r'\b([A-Z]{2,}[-/]?\d[\w\d/-]{2,})\b', text)
+        out["invoice_ref"] = m.group(1) if m else None
+
+    # Invoice date — try ISO, French DD/MM/YYYY, English MM/DD/YYYY, French long form
+    out["invoice_date_raw"] = None
+    for p in (
+        r'\b(\d{4}-\d{2}-\d{2})\b',
+        r'(?:date|émise\s*le|invoice\s*date|date\s*de\s*facturation)[:\s]*(\d{1,2}[\s/.-]\d{1,2}[\s/.-]\d{2,4})',
+        r'(?:date|émise\s*le|invoice\s*date)[:\s]*(\d{1,2}\s+\w{3,9}\.?\s+\d{4})',
+    ):
+        m = re.search(p, text, re.IGNORECASE)
+        if m: out["invoice_date_raw"] = m.group(1).strip(); break
+
+    # VAT rate (e.g. "20%") — restrict to 0-25% so "100%" / page footers don't match.
+    vrate = None
+    for line in lines:
+        m = re.search(r'\b(\d{1,2}([.,]\d+)?)\s*%', line)
+        if m:
+            v = float(m.group(1).replace(",", "."))
+            if 0 <= v <= 25:
+                vrate = m.group(1).replace(",", "."); break
+    out["vat_rate_pct"] = vrate
+
+    return out
+
+pdfs = []
+for pdf in sorted(glob.glob(os.path.join(work,"atts","*.pdf")) +
+                  glob.glob(os.path.join(work,"atts","*.PDF"))):
+    name = os.path.basename(pdf)
+    txt_path = os.path.join(work,"text", os.path.splitext(name)[0] + ".txt")
+    text = open(txt_path).read() if os.path.isfile(txt_path) else ""
+    h = extract(text)
+    h["attachment_name"] = name
+    h["pdf_size_bytes"] = os.path.getsize(pdf)
+    h["pdf_text_len"] = len(text)
+    pdfs.append(h)
+
+result = {
+    "email": {
+        "messageId": meta.get("messageId"),
+        "subject":   mail_subject,
+        "from":      mail_from,
+        "date":      mail_date,
+        "hasAttachment": str(meta.get("hasAttachment","")) == "1",
+    },
+    "attachments": pdfs,
+    "dolibarr_draft_suggestions": [
+        {
+            "supplier_hint":  p.get("pdf_top_line"),
+            "invoice_ref":    p.get("invoice_ref"),
+            "invoice_date":   p.get("invoice_date_raw"),
+            "total_ht":       p.get("total_ht"),
+            "total_tva":      p.get("total_tva"),
+            "total_ttc":      p.get("total_ttc"),
+            "vat_rate_pct":   p.get("vat_rate_pct"),
+            "source_email":   meta.get("messageId"),
+            "source_attachment": p.get("attachment_name"),
+        } for p in pdfs
+    ]
+}
+
+if fmt == "json":
+    print(json.dumps(result, indent=2, ensure_ascii=False))
+    sys.exit(0)
+
+print("=" * 80)
+print(f" Email {meta.get('messageId')}")
+print("=" * 80)
+print(f"  subject   : {mail_subject}")
+print(f"  from      : {mail_from}")
+print(f"  date      : {mail_date}")
+print(f"  attached  : {result['email']['hasAttachment']}")
+print()
+if not pdfs:
+    print("  (no PDF attachments — try inspecting body or other types)")
+for i, p in enumerate(pdfs, 1):
+    print(f"  -- Attachment {i}: {p['attachment_name']} ({p['pdf_size_bytes']} bytes, {p['pdf_text_len']} chars extracted) --")
+    for k in ("pdf_top_line","invoice_ref","invoice_date_raw","total_ht","total_tva","total_ttc","vat_rate_pct"):
+        v = p.get(k)
+        print(f"    {k:<16} = {v!r}")
+    print()
+
+print("  Suggested Dolibarr supplier-invoice draft entries:")
+print(json.dumps(result["dolibarr_draft_suggestions"], indent=4, ensure_ascii=False))
+PY

.claude/skills/arcodange-email-ingest/scripts/email-list.sh

@@ -0,0 +1,141 @@
+#!/usr/bin/env bash
+# List candidate supplier-invoice emails from the books@ Zoho mailbox.
+#
+# Usage:
+#   email-list.sh [--folder PATH]      # default: /Inbox/books (the books@ alias-filtered folder)
+#                 [--limit N]          # default: 30
+#                 [--candidates-only]  # filter by subject pattern OR attachment
+#                 [--all-folders]      # scan every folder (slow, lots of API calls)
+#
+# Output: table with mid, date, from, subject, hasAttachment.
+# A "candidate" is a message whose subject matches a supplier-like pattern
+# (facture/invoice/receipt/reçu/payment/paiement/abonnement/order/commande)
+# OR which has an attachment.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ZOHO_CURL="${SCRIPT_DIR}/zoho-curl.sh"
+
+FOLDER="/Inbox/books"
+LIMIT=30
+CANDIDATES_ONLY=0
+ALL_FOLDERS=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --folder)           FOLDER="$2"; shift 2 ;;
+    --limit)            LIMIT="$2"; shift 2 ;;
+    --candidates-only)  CANDIDATES_ONLY=1; shift ;;
+    --all-folders)      ALL_FOLDERS=1; shift ;;
+    -h|--help)          sed -n '2,12p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;;
+    *) echo "email-list.sh: unknown arg: $1" >&2; exit 2 ;;
+  esac
+done
+
+WORK="$(mktemp -d -t emailist.XXXXXX)"
+trap 'rm -rf "${WORK}"' EXIT
+
+# 1. Discover accountId
+"${ZOHO_CURL}" /accounts > "${WORK}/accounts.json"
+AID=$(python3 -c "import json,sys; d=json.load(open(sys.argv[1])); print((d.get('data') or [{}])[0].get('accountId',''))" "${WORK}/accounts.json")
+[[ -z "${AID}" ]] && { echo "email-list.sh: no accountId in /accounts response" >&2; exit 1; }
+
+# 2. Resolve folder path → folderId
+"${ZOHO_CURL}" "/accounts/${AID}/folders" > "${WORK}/folders.json"
+
+# Build list of (folderId, path) tuples to scan
+if [[ "${ALL_FOLDERS}" == "1" ]]; then
+  FOLDER_IDS=$(python3 -c "
+import json, sys
+d = json.load(open(sys.argv[1]))
+for f in (d.get('data') or []):
+    fid = f.get('folderId'); path = f.get('path') or f.get('folderName','-')
+    # Skip noisy system folders
+    if path in ('/Drafts','/Templates','/Snoozed','/Sent','/Spam','/Trash','/Outbox'): continue
+    print(f\"{fid}|{path}\")" "${WORK}/folders.json")
+else
+  FOLDER_IDS=$(python3 -c "
+import json, sys
+d = json.load(open(sys.argv[1]))
+target = sys.argv[2]
+for f in (d.get('data') or []):
+    if f.get('path') == target:
+        print(f\"{f.get('folderId')}|{f.get('path')}\")
+        break" "${WORK}/folders.json" "${FOLDER}")
+  if [[ -z "${FOLDER_IDS}" ]]; then
+    echo "email-list.sh: folder '${FOLDER}' not found. Available:" >&2
+    python3 -c "import json,sys; [print(f'  {f.get(\"path\",\"-\")}') for f in json.load(open(sys.argv[1])).get('data',[])]" "${WORK}/folders.json" >&2
+    exit 2
+  fi
+fi
+
+# 3. Fetch messages per folder
+mkdir -p "${WORK}/msgs"
+COUNT=0
+while IFS='|' read -r fid fpath; do
+  [[ -z "${fid}" ]] && continue
+  COUNT=$((COUNT+1))
+  out="${WORK}/msgs/$(printf '%03d' "${COUNT}").json"
+  "${ZOHO_CURL}" "/accounts/${AID}/messages/view?folderId=${fid}&limit=${LIMIT}&sortorder=false&start=1" > "${out}" 2>/dev/null || echo '{"data":[]}' > "${out}"
+  echo "${fpath}" > "${out}.path"
+done <<< "${FOLDER_IDS}"
+
+# 4. Render
+python3 - "${WORK}/msgs" "${CANDIDATES_ONLY}" <<'PY'
+import json, sys, os, re, datetime, glob
+msgs_dir, candidates_only_str = sys.argv[1:3]
+candidates_only = candidates_only_str == "1"
+
+CANDIDATE_PATTERN = re.compile(
+    r'facture|invoice|receipt|re[cç]u|payment|paiement|abonnement|subscription|order|commande|invoice|bill',
+    re.IGNORECASE,
+)
+
+# Subjects that look like calendar invites / event updates / generic notifications
+# get filtered out of --candidates-only — they always have a .ics attachment so
+# the "has-attachment" heuristic alone catches them as false positives.
+EXCLUDE_PATTERN = re.compile(
+    r'^(?:re:\s*|fwd:\s*|tr:\s*)*'                       # strip Re:/Fwd:/Tr: prefixes
+    r'(?:invitation|updated\s+invitation|canceled\s+event|accepted|declined|tentative|maybe)\s*:',
+    re.IGNORECASE,
+)
+
+# Senders that are pure noise — newsletter/marketing patterns.
+EXCLUDE_SENDER = re.compile(
+    r'(updates\.|noreply@.*calendar|@calendar\.|news@|newsletter@|@updates\.)',
+    re.IGNORECASE,
+)
+
+def is_candidate(m):
+    subj   = m.get("subject","") or ""
+    sender = m.get("fromAddress","") or m.get("sender","") or ""
+    # Hard exclusions take precedence over inclusions
+    if EXCLUDE_PATTERN.match(subj.strip()): return False
+    if EXCLUDE_SENDER.search(sender): return False
+    if str(m.get("hasAttachment","")) == "1": return True
+    if CANDIDATE_PATTERN.search(subj): return True
+    return False
+
+rows = []
+for f in sorted(glob.glob(os.path.join(msgs_dir, "*.json"))):
+    fpath = open(f + ".path").read().strip()
+    try: data = json.load(open(f)).get("data") or []
+    except: continue
+    for m in data:
+        if candidates_only and not is_candidate(m): continue
+        ts = int(m.get("sentDateInGMT") or m.get("receivedTime") or 0) // 1000
+        dt = datetime.datetime.fromtimestamp(ts).strftime("%Y-%m-%d") if ts else "-"
+        frm = (m.get("fromAddress") or m.get("sender") or "-").replace("&lt;","<").replace("&gt;",">").replace("<","").replace(">","")[:36]
+        subj = (m.get("subject") or "-")[:55]
+        has = "Y" if str(m.get("hasAttachment","")) == "1" else " "
+        cand = "*" if is_candidate(m) else " "
+        rows.append((dt, fpath, cand, has, m.get("messageId","-"), frm, subj))
+
+rows.sort(key=lambda r: r[0], reverse=True)
+print(f"{'date':<10}  {'cand':<4} {'att':<3} {'messageId':<22}  {'folder':<22}  {'from':<36}  subject")
+print("-" * 130)
+for dt, fpath, cand, has, mid, frm, subj in rows:
+    print(f"{dt:<10}  [{cand}]  [{has}]  {mid:<22}  {fpath[:22]:<22}  {frm:<36}  {subj}")
+print("-" * 130)
+print(f"# {len(rows)} message(s)" + (" (candidates only)" if candidates_only else ""))
+PY

.claude/skills/arcodange-email-ingest/scripts/zoho-curl.sh

@@ -0,0 +1,126 @@
+#!/usr/bin/env bash
+# Read-only curl wrapper for the Zoho Mail API.
+#
+# Usage:
+#   zoho-curl.sh <path>                  # e.g. zoho-curl.sh /accounts
+#   zoho-curl.sh -i <path>               # include curl's -i (response headers)
+#   zoho-curl.sh -o file.json <path>     # write body to file
+#
+# Reads credentials from ../../dolibarr/.env (the shared canonical file).
+# Required vars:
+#   ZOHO_CLIENT_ID, ZOHO_CLIENT_SECRET, ZOHO_REFRESH_TOKEN, ZOHO_DC
+#
+# Token strategy: each invocation refreshes a short-lived access_token from
+# the refresh_token (Zoho access_tokens live 1h; the cost of refreshing on
+# every call is ~150 ms and avoids state on disk). On 401 from the mail API
+# we re-refresh once and retry (covers refresh-token rotation cases).
+#
+# Exits non-zero on HTTP >= 400 and writes body to stdout + a short message
+# to stderr — same shape as dol-curl.sh / bank-curl.sh.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ENV_FILE="${SCRIPT_DIR}/../../dolibarr/.env"
+
+if [[ ! -f "${ENV_FILE}" ]]; then
+  echo "zoho-curl.sh: missing ${ENV_FILE}" >&2
+  echo "  Required vars: ZOHO_CLIENT_ID, ZOHO_CLIENT_SECRET, ZOHO_REFRESH_TOKEN, ZOHO_DC." >&2
+  echo "  See arcodange-email-ingest/SKILL.md for the OAuth setup." >&2
+  exit 2
+fi
+set -a; source "${ENV_FILE}"; set +a
+
+: "${ZOHO_CLIENT_ID:?zoho-curl.sh: ZOHO_CLIENT_ID not set in .env}"
+: "${ZOHO_CLIENT_SECRET:?zoho-curl.sh: ZOHO_CLIENT_SECRET not set in .env}"
+: "${ZOHO_REFRESH_TOKEN:?zoho-curl.sh: ZOHO_REFRESH_TOKEN not set in .env}"
+: "${ZOHO_DC:=eu}"
+
+ACCOUNTS_BASE="https://accounts.zoho.${ZOHO_DC}"
+MAIL_BASE="https://mail.zoho.${ZOHO_DC}/api"
+
+# Parse pass-through curl args (everything before the last positional)
+PASSTHRU=()
+while [[ $# -gt 1 ]]; do
+  PASSTHRU+=("$1"); shift
+done
+if [[ $# -lt 1 ]]; then
+  echo "zoho-curl.sh: missing API path. Example: zoho-curl.sh /accounts" >&2
+  exit 2
+fi
+API_PATH="$1"
+
+# Cache access_token in tmpfs to avoid hitting OAuth rate limits on every
+# zoho-curl invocation. Zoho access_tokens live 1h; we refresh after 50 min.
+CACHE_FILE="${TMPDIR:-/tmp}/zoho-access-$(whoami)"
+CACHE_TTL_SECONDS=$((50 * 60))
+
+get_access_token() {
+  if [[ -f "${CACHE_FILE}" ]]; then
+    local age
+    age=$(( $(date +%s) - $(stat -f %m "${CACHE_FILE}" 2>/dev/null || stat -c %Y "${CACHE_FILE}") ))
+    if [[ ${age} -lt ${CACHE_TTL_SECONDS} ]]; then
+      cat "${CACHE_FILE}"
+      return 0
+    fi
+  fi
+  local token
+  if ! token=$(curl -sS -X POST "${ACCOUNTS_BASE}/oauth/v2/token" \
+    --max-time 15 \
+    -d "grant_type=refresh_token" \
+    -d "client_id=${ZOHO_CLIENT_ID}" \
+    -d "client_secret=${ZOHO_CLIENT_SECRET}" \
+    -d "refresh_token=${ZOHO_REFRESH_TOKEN}" \
+    | python3 -c "
+import json, sys
+try: d = json.load(sys.stdin)
+except: sys.exit('failed to parse OAuth response')
+if 'access_token' not in d:
+    sys.exit(f'OAuth refresh failed: {d}')
+print(d['access_token'])"); then
+    return 1
+  fi
+  if [[ -z "${token}" ]]; then
+    return 1
+  fi
+  # Store cache (mode 600) only on success
+  printf '%s' "${token}" > "${CACHE_FILE}"
+  chmod 600 "${CACHE_FILE}"
+  printf '%s' "${token}"
+}
+
+do_call() {
+  local token="$1"
+  local body_file="$2"
+  local headers_file="$3"
+  curl -sS \
+    -H "Authorization: Zoho-oauthtoken ${token}" \
+    -H "Accept: application/json" \
+    --max-time 30 \
+    -o "${body_file}" \
+    -D "${headers_file}" \
+    -w "%{http_code}" \
+    ${PASSTHRU[@]+"${PASSTHRU[@]}"} \
+    "${MAIL_BASE}${API_PATH}"
+}
+
+ACCESS_TOKEN=$(get_access_token)
+[[ -z "${ACCESS_TOKEN}" ]] && { echo "zoho-curl.sh: empty access_token" >&2; exit 1; }
+
+BODY_FILE="$(mktemp -t zohocurl.XXXXXX)"
+HEADERS_FILE="$(mktemp -t zohohdr.XXXXXX)"
+trap 'rm -f "${BODY_FILE}" "${HEADERS_FILE}"' EXIT
+
+HTTP_CODE=$(do_call "${ACCESS_TOKEN}" "${BODY_FILE}" "${HEADERS_FILE}")
+
+# Retry once on 401 with a fresh token (handles edge cases of refresh-token rotation)
+if [[ "${HTTP_CODE}" == "401" ]]; then
+  ACCESS_TOKEN=$(get_access_token)
+  HTTP_CODE=$(do_call "${ACCESS_TOKEN}" "${BODY_FILE}" "${HEADERS_FILE}")
+fi
+
+cat "${BODY_FILE}"
+if [[ "${HTTP_CODE}" -ge 400 ]]; then
+  echo "zoho-curl.sh: HTTP ${HTTP_CODE} on ${API_PATH}" >&2
+  exit 1
+fi

.claude/skills/dolibarr-sandbox-write/.env.example

@@ -0,0 +1,10 @@
+# Copy to .env (mode 600 — gitignored). Never commit a real key.
+DOLIBARR_SANDBOX_URL=https://erp-sandbox.arcodange.lab
+DOLIBARR_SANDBOX_API_KEY=
+
+# Populate the key from the Playwright provisioner output (repo test/):
+#   printf 'DOLIBARR_SANDBOX_API_KEY=%s\n' "$(cat ../../../test/.ai_agent_sandbox.key)" >> .env
+#
+# The host guard only allows the sandbox FQDN. Override the pattern ONLY if the
+# sandbox host changes — never widen it to a prod host.
+# DOLIBARR_SANDBOX_HOST_RE=^https://erp-sandbox\.arcodange\.lab(/|$)

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

.claude/skills/dolibarr-sandbox-write/examples/customer-invoice.json

@@ -0,0 +1,9 @@
+{
+  "socid": 42,
+  "kind": "customer",
+  "validate": true,
+  "lines": [
+    { "desc": "Conseil (jours)", "qty": 2, "price_ht": 500, "tva": 20, "type": "service" },
+    { "desc": "Licence annuelle", "qty": 1, "price_ht": 100, "tva": 20, "type": "product" }
+  ]
+}

.claude/skills/dolibarr-sandbox-write/scripts/dol-write.sh

@@ -0,0 +1,82 @@
+#!/usr/bin/env bash
+# Host-guarded WRITE wrapper for the Arcodange Dolibarr SANDBOX API.
+#
+# THE GUARANTEE (ADR-0003): this wrapper REFUSES to run against anything that is
+# not the erp-sandbox host. It is the structural reason an AI agent driving this
+# skill can never mutate production — prod is a different host, and the guard
+# below rejects it before any request is sent.
+#
+# Usage:
+#   dol-write.sh <METHOD> <path> [json-body|@file]
+#     dol-write.sh POST /thirdparties '{"name":"Acme","client":"1"}'
+#     dol-write.sh POST /invoices @invoice.json
+#     dol-write.sh PUT  /thirdparties/42 '{"phone":"+33..."}'
+#     dol-write.sh GET  /thirdparties?limit=5            # reads are allowed too
+#
+# Reads DOLIBARR_SANDBOX_URL + DOLIBARR_SANDBOX_API_KEY from the sibling .env
+# (.claude/skills/dolibarr-sandbox-write/.env), mode 600, gitignored.
+# Prints the response body to stdout; exits non-zero on HTTP >= 400.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+ENV_FILE="${SCRIPT_DIR}/../.env"
+
+if [[ ! -f "${ENV_FILE}" ]]; then
+  echo "dol-write.sh: missing ${ENV_FILE}" >&2
+  echo "  Create it with DOLIBARR_SANDBOX_URL + DOLIBARR_SANDBOX_API_KEY. See README.md." >&2
+  exit 2
+fi
+# shellcheck disable=SC1090
+set -a; source "${ENV_FILE}"; set +a
+
+: "${DOLIBARR_SANDBOX_URL:?dol-write.sh: DOLIBARR_SANDBOX_URL not set in .env}"
+: "${DOLIBARR_SANDBOX_API_KEY:?dol-write.sh: DOLIBARR_SANDBOX_API_KEY not set in .env}"
+
+# ---------------------------------------------------------------------------
+# HOST GUARD — the structural safety invariant. Only the sandbox host passes.
+# Override the allowed pattern only via DOLIBARR_SANDBOX_HOST_RE in .env if the
+# sandbox FQDN ever changes; never widen it to include a prod host.
+# ---------------------------------------------------------------------------
+ALLOWED_RE="${DOLIBARR_SANDBOX_HOST_RE:-^https://erp-sandbox\.arcodange\.lab(/|$)}"
+if [[ ! "${DOLIBARR_SANDBOX_URL}" =~ ${ALLOWED_RE} ]]; then
+  echo "dol-write.sh: REFUSING to write — DOLIBARR_SANDBOX_URL='${DOLIBARR_SANDBOX_URL}'" >&2
+  echo "  is not the erp-sandbox host (allowed: ${ALLOWED_RE})." >&2
+  echo "  This skill only writes the sandbox. Promotion to prod is a separate, human-gated step." >&2
+  exit 3
+fi
+
+if [[ $# -lt 2 ]]; then
+  echo "dol-write.sh: usage: dol-write.sh <METHOD> <path> [json-body|@file]" >&2
+  exit 2
+fi
+METHOD="$1"; API_PATH="$2"; BODY="${3-}"
+case "${METHOD}" in
+  GET|POST|PUT|DELETE|PATCH) ;;
+  *) echo "dol-write.sh: unsupported method '${METHOD}'" >&2; exit 2 ;;
+esac
+
+CURL_ARGS=(
+  -sS -X "${METHOD}"
+  -H "DOLAPIKEY: ${DOLIBARR_SANDBOX_API_KEY}"
+  -H "Accept: application/json"
+  --max-time 30
+)
+if [[ -n "${BODY}" ]]; then
+  # curl --data supports '@file' to read a JSON body from a file.
+  CURL_ARGS+=( -H "Content-Type: application/json" --data "${BODY}" )
+fi
+
+BODY_FILE="$(mktemp -t dolwrite.XXXXXX)"
+trap 'rm -f "${BODY_FILE}"' EXIT
+
+HTTP_CODE=$(curl "${CURL_ARGS[@]}" \
+  -o "${BODY_FILE}" -w "%{http_code}" \
+  "${DOLIBARR_SANDBOX_URL}/api/index.php${API_PATH}")
+
+cat "${BODY_FILE}"
+if [[ "${HTTP_CODE}" -ge 400 ]]; then
+  echo "" >&2
+  echo "dol-write.sh: HTTP ${HTTP_CODE} on ${METHOD} ${API_PATH}" >&2
+  exit 1
+fi

.claude/skills/dolibarr-sandbox-write/scripts/invoice-create.sh

@@ -0,0 +1,68 @@
+#!/usr/bin/env bash
+# Create a customer or supplier invoice (facture) with product/service lines in
+# the SANDBOX, optionally validating it.
+#
+# Input: a JSON object on stdin (or a file path in $1):
+#   socid        (required) thirdparty id
+#   kind         "customer" | "supplier"        (default "customer")
+#   date         "YYYY-MM-DD"                    (default today)
+#   ref_supplier supplier's own invoice ref      (supplier invoices)
+#   validate     true|false                       (default false = leave draft)
+#   lines: [ { desc, qty, price_ht, tva, type: "product"|"service", product_id? } ]
+#
+# Emits {id, ref, ref_supplier, total_ht, total_ttc, statut} on stdout.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+W="${SCRIPT_DIR}/dol-write.sh"
+
+SRC="${1:-}"
+if [[ -n "${SRC}" && "${SRC}" != "-" ]]; then INPUT="$(cat "${SRC}")"; else INPUT="$(cat)"; fi
+
+PYF="$(mktemp -t dolpy.XXXXXX)"; trap 'rm -f "${PYF}"' EXIT
+cat > "${PYF}" <<'PY'
+import json, sys, datetime
+d = json.loads(sys.stdin.read())
+if not d.get("socid"):
+    sys.exit("invoice-create.sh: 'socid' is required")
+supplier = d.get("kind", "customer").lower() in ("supplier", "fournisseur")
+endpoint = "/supplierinvoices" if supplier else "/invoices"
+ds = d.get("date")
+epoch = int((datetime.datetime.strptime(ds, "%Y-%m-%d") if ds
+             else datetime.datetime.now()).timestamp())
+lines = []
+for ln in d.get("lines", []):
+    is_product = ln.get("type", "service").lower() in ("product", "produit")
+    L = {
+        "desc": ln.get("desc", ""),
+        "subprice": str(ln.get("price_ht", ln.get("subprice", 0))),
+        "qty": str(ln.get("qty", 1)),
+        "tva_tx": str(ln.get("tva", ln.get("tva_tx", 20))),
+        "product_type": "0" if is_product else "1",
+    }
+    if ln.get("product_id"):
+        L["fk_product"] = str(ln["product_id"])
+    lines.append(L)
+body = {"socid": d["socid"], "date": epoch, "type": 0, "lines": lines}
+if supplier and d.get("ref_supplier"):
+    body["ref_supplier"] = d["ref_supplier"]
+print(endpoint)
+print(json.dumps(body))
+print("1" if d.get("validate") else "0")
+PY
+
+MAPPED="$(printf '%s' "${INPUT}" | python3 "${PYF}")"
+ENDPOINT="$(sed -n 1p <<<"${MAPPED}")"
+BODY="$(sed -n 2p <<<"${MAPPED}")"
+VALIDATE="$(sed -n 3p <<<"${MAPPED}")"
+
+ID="$("${W}" POST "${ENDPOINT}" "${BODY}")"
+if [[ ! "${ID}" =~ ^[0-9]+$ ]]; then
+  echo "invoice-create.sh: create did not return an id: ${ID}" >&2
+  exit 1
+fi
+if [[ "${VALIDATE}" == "1" ]]; then
+  "${W}" POST "${ENDPOINT}/${ID}/validate" '{}' >/dev/null
+fi
+"${W}" GET "${ENDPOINT}/${ID}" | python3 -c "import json,sys
+d=json.load(sys.stdin)
+print(json.dumps({k:d.get(k) for k in ('id','ref','ref_supplier','total_ht','total_ttc','statut')}))"

.claude/skills/dolibarr-sandbox-write/scripts/payment-record.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# Record a payment (règlement) on a validated invoice in the SANDBOX.
+#
+# Input: a JSON object on stdin (or a file path in $1):
+#   invoice_id   (required) the invoice to pay
+#   kind         "customer" | "supplier"      (default "customer")
+#   mode         "VIR" | "CB" | "CHQ" | "LIQ" (default "VIR")
+#   account_id   (required) the bank account id receiving/paying
+#   date         "YYYY-MM-DD"                  (default today)
+#   amount       (REQUIRED for supplier; customer pays the full remaining)
+#   num, comment (optional)
+#
+# The invoice must be VALIDATED first (invoice-create.sh ... "validate":true).
+# Emits the new payment id on stdout.
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+W="${SCRIPT_DIR}/dol-write.sh"
+
+SRC="${1:-}"
+if [[ -n "${SRC}" && "${SRC}" != "-" ]]; then INPUT="$(cat "${SRC}")"; else INPUT="$(cat)"; fi
+
+PYF="$(mktemp -t dolpy.XXXXXX)"; trap 'rm -f "${PYF}"' EXIT
+cat > "${PYF}" <<'PY'
+import json, sys, datetime
+d = json.loads(sys.stdin.read())
+if not d.get("invoice_id"):
+    sys.exit("payment-record.sh: 'invoice_id' is required")
+if not d.get("account_id"):
+    sys.exit("payment-record.sh: 'account_id' is required")
+# Stable Dolibarr c_paiement ids (sandbox seeded from prod / standard defaults).
+MODE = {"VIR": 2, "CB": 6, "CHQ": 7, "LIQ": 4}
+mode = MODE.get(str(d.get("mode", "VIR")).upper())
+if mode is None:
+    sys.exit("payment-record.sh: unknown mode (use VIR|CB|CHQ|LIQ)")
+supplier = d.get("kind", "customer").lower() in ("supplier", "fournisseur")
+ds = d.get("date")
+epoch = int((datetime.datetime.strptime(ds, "%Y-%m-%d") if ds
+             else datetime.datetime.now()).timestamp())
+inv = d["invoice_id"]
+if supplier:
+    if d.get("amount") is None:
+        sys.exit("payment-record.sh: supplier payments require an 'amount'")
+    endpoint = "/supplierinvoices/%s/payments" % inv
+    body = {"datepaye": epoch, "paymentid": mode, "accountid": d["account_id"],
+            "amount": str(d["amount"]), "num_payment": d.get("num", ""),
+            "comment": d.get("comment", "")}
+else:
+    endpoint = "/invoices/%s/payments" % inv
+    body = {"datepaye": epoch, "paymentid": mode, "closepaidinvoices": "yes",
+            "accountid": d["account_id"], "num_payment": d.get("num", ""),
+            "comment": d.get("comment", "")}
+print(endpoint)
+print(json.dumps(body))
+PY
+
+MAPPED="$(printf '%s' "${INPUT}" | python3 "${PYF}")"
+ENDPOINT="$(sed -n 1p <<<"${MAPPED}")"
+BODY="$(sed -n 2p <<<"${MAPPED}")"
+"${W}" POST "${ENDPOINT}" "${BODY}"

.claude/skills/dolibarr-sandbox-write/scripts/thirdparty-create.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+# Create a client and/or supplier thirdparty (fiche tiers) in the SANDBOX.
+#
+# Input: a JSON object on stdin (or a file path in $1). Fields:
+#   name         (required)
+#   role         "client" | "supplier" | "both"   (default "client")
+#   country_id   numeric, default 1 (France)
+#   client_code / supplier_code   default "-1" = auto-generate via the code mask
+#   siret, tva_intra, address, zip, town, email, phone, idprof1  (optional)
+#
+# Emits the new thirdparty id on stdout. All writes go through dol-write.sh,
+# which refuses any host that is not the sandbox.
+#
+# Examples:
+#   echo '{"name":"KissMetrics","role":"client","tva_intra":"US.."}' | thirdparty-create.sh
+#   thirdparty-create.sh fournisseur.json
+set -euo pipefail
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+W="${SCRIPT_DIR}/dol-write.sh"
+
+SRC="${1:-}"
+if [[ -n "${SRC}" && "${SRC}" != "-" ]]; then INPUT="$(cat "${SRC}")"; else INPUT="$(cat)"; fi
+
+PYF="$(mktemp -t dolpy.XXXXXX)"; trap 'rm -f "${PYF}"' EXIT
+cat > "${PYF}" <<'PY'
+import json, sys
+d = json.loads(sys.stdin.read())
+if not d.get("name"):
+    sys.exit("thirdparty-create.sh: 'name' is required")
+role = d.get("role", "client").lower()
+is_client = role in ("client", "both")
+is_supp = role in ("supplier", "fournisseur", "both")
+body = {
+    "name": d["name"],
+    "client": "1" if is_client else "0",
+    "fournisseur": "1" if is_supp else "0",
+    "country_id": str(d.get("country_id", 1)),
+    # "-1" => Dolibarr auto-assigns the next code from the mask
+    # (COMPANY_ELEPHANT_MASK_CUSTOMER / _SUPPLIER); "0" when that role is off.
+    "code_client": (d.get("client_code", "-1") if is_client else "0"),
+    "code_fournisseur": (d.get("supplier_code", "-1") if is_supp else "0"),
+}
+for k in ("siret", "tva_intra", "address", "zip", "town", "email", "phone", "idprof1"):
+    if d.get(k):
+        body[k] = d[k]
+print(json.dumps(body))
+PY
+
+BODY="$(printf '%s' "${INPUT}" | python3 "${PYF}")"
+"${W}" POST /thirdparties "${BODY}"

.claude/skills/dolibarr/README.md

@@ -19,6 +19,12 @@ WISE_API_TOKEN=<from wise.com/settings/api-tokens>
 WISE_PROFILE_ID=<numeric id of the BUSINESS profile — bank probe prints it>
 # Optional: only needed if Wise ever opens the EU statement endpoint
 WISE_SCA_KEY_PATH=~/.config/arcodange-erp/wise-sca-private.pem
+
+# Required by arcodange-email-ingest only
+ZOHO_CLIENT_ID=<from api-console.zoho.com self-client>
+ZOHO_CLIENT_SECRET=<same>
+ZOHO_REFRESH_TOKEN=<exchanged from one-time code via /oauth/v2/token>
+ZOHO_DC=eu                                     # eu | com | in | au
 EOF
 chmod 600 .claude/skills/dolibarr/.env
 ```

.claude/skills/dolibarr/SKILL.md

@@ -151,7 +151,8 @@ Not available on this account (intentionally): `/setup/modules` (admin-only), `/
 - Workflow skill for supplier-side TVA déductible (CA3 lignes 19 / 20 / 17+24): [dolibarr-tva-deductible](../dolibarr-tva-deductible/SKILL.md).
 - Workflow skill for composite CA3-ready TVA summary (collectée + déductible + net): [dolibarr-tva-summary](../dolibarr-tva-summary/SKILL.md).
 - **Bank-side reconciliation** (Qonto + Wise ↔ Dolibarr matching): [arcodange-bank-reco](../arcodange-bank-reco/SKILL.md).
-- Future workflow skills follow the `dolibarr-<topic>` convention (ERP-internal) or `arcodange-<topic>` (cross-system, like bank reconciliation). Each one depends on this skill for connection + permissions + endpoint reference; each one keeps its triggers focused on its specific business workflow.
+- **Email ingestion** (Zoho Mail → supplier-invoice draft for Dolibarr): [arcodange-email-ingest](../arcodange-email-ingest/SKILL.md).
+- Future workflow skills follow the `dolibarr-<topic>` convention (ERP-internal) or `arcodange-<topic>` (cross-system). Each one depends on this skill for connection + permissions + endpoint reference; each one keeps its triggers focused on its specific business workflow.
 
 ## Out of scope
 

.gitea/workflows/vault.yaml

@@ -22,7 +22,7 @@ concurrency:
     url: https://vault.arcodange.lab
     caCertificate: ${{ secrets.HOMELAB_CA_CERT }}
     jwtGiteaOIDC: ${{ needs.gitea_vault_auth.outputs.gitea_vault_jwt }}
-    role: gitea_cicd_webapp
+    role: gitea_cicd_erp
     method: jwt
     path: gitea_jwt
     secrets: |

bin/arcodange

@@ -72,10 +72,15 @@ COMMANDS
     probe                                          Auth + discovery (org slug, profile id, balance ids)
     qonto-transactions   [--month|--since|--until] Qonto transactions table (incoming + outgoing)
     wise-transactions    [--month|--since|--until|--type|--enrich]  Wise activities (incoming + outgoing)
-    match                [--month|--since|--until|--window-days N]  Match bank ↔ Dolibarr (3 buckets)
+    match                [--month|--since|--until|--window-days N|--enrich]  Match bank ↔ Dolibarr (split buckets)
     balance                                        Live balances + Dolibarr cross-check per fk_account
     curl                 <qonto|wise> <path>       Raw read-only curl through bank-curl.sh
 
+  email                              Supplier-invoice emails from the Zoho mailbox
+    list                 [--folder|--limit|--candidates-only|--all-folders]   List candidates
+    inspect              <messageId> [--folder|--save-pdf|--json]   Parse PDFs + draft Dolibarr entry
+    curl                 <path>                    Raw read-only curl through zoho-curl.sh
+
   whoami                                          GET /users/info — confirm auth
   ping                                            GET /status     — liveness + Dolibarr version
   curl                   <path>                   Raw read-only curl through dol-curl.sh
@@ -236,6 +241,30 @@ EOF
     esac
     ;;
 
+  email)
+    sub="${1:-help}"; shift || true
+    case "${sub}" in
+      list)    exec "${SKILLS}/arcodange-email-ingest/scripts/email-list.sh"    "$@" ;;
+      inspect) exec "${SKILLS}/arcodange-email-ingest/scripts/email-inspect.sh" "$@" ;;
+      curl)    exec "${SKILLS}/arcodange-email-ingest/scripts/zoho-curl.sh"     "$@" ;;
+      help|-h|--help)
+        cat <<'EOF'
+arcodange email — supplier-invoice ingestion from the Zoho mailbox.
+
+  list                 [--folder PATH|--limit N|--candidates-only|--all-folders]
+                       List messages (default: /Inbox/books)
+  inspect              <messageId> [--folder PATH|--save-pdf DIR|--json]
+                       Parse PDF attachments, propose Dolibarr supplier-invoice draft
+  curl                 <path>     Raw read-only call through zoho-curl.sh
+
+Requires ZOHO_CLIENT_ID, ZOHO_CLIENT_SECRET, ZOHO_REFRESH_TOKEN, ZOHO_DC in .env.
+See arcodange-email-ingest/SKILL.md for OAuth setup.
+EOF
+        ;;
+      *) echo "arcodange email: unknown subcommand '${sub}' (try 'arcodange email help')" >&2; exit 2 ;;
+    esac
+    ;;
+
   whoami)
     exec "${DOLC}" /users/info
     ;;

chart/scripts/update_ownership.sql

@@ -10,12 +10,12 @@ BEGIN
     WHERE schemaname = 'public'
     LIMIT 1;
 
-    -- Si le propriétaire actuel est différent de erp_role
+    -- Si le propriétaire actuel est différent de {{ .Values.db.ownerRole }}
-    IF current_schema_owner <> 'erp_role' THEN
+    IF current_schema_owner <> '{{ .Values.db.ownerRole }}' THEN
         -- Construire et exécuter la requête REASSIGN OWNED BY
-        EXECUTE format('REASSIGN OWNED BY %I TO %I', current_schema_owner, 'erp_role');
+        EXECUTE format('REASSIGN OWNED BY %I TO %I', current_schema_owner, '{{ .Values.db.ownerRole }}');
-        RAISE NOTICE 'Ownership of all objects in schema "public" has been reassigned from % to %', current_schema_owner, 'erp_role';
+        RAISE NOTICE 'Ownership of all objects in schema "public" has been reassigned from % to %', current_schema_owner, '{{ .Values.db.ownerRole }}';
     ELSE
-        RAISE NOTICE 'No change needed; the owner of schema "public" is already %', 'erp_role';
+        RAISE NOTICE 'No change needed; the owner of schema "public" is already %', '{{ .Values.db.ownerRole }}';
     END IF;
 END $$;

chart/templates/config.yaml

@@ -10,8 +10,8 @@ data:
   DOLI_DB_HOST_PORT: !!str 5432
   # DOLI_DB_USER: root
   # DOLI_DB_PASSWORD: root
-  DOLI_DB_NAME: erp
+  DOLI_DB_NAME: {{ .Values.db.name }}
-  DOLI_URL_ROOT: 'https://erp.arcodange.lab'
+  DOLI_URL_ROOT: 'https://{{ .Values.host }}'
   # DOLI_ADMIN_LOGIN: 'admin'
   # DOLI_ADMIN_PASSWORD: 'admininitialpassword'
   DOLI_ENABLE_MODULES: Societe,Facture
@@ -20,4 +20,9 @@ data:
   PHP_INI_DATE_TIMEZONE: Europe/Paris
   DOLI_AUTH: dolibarr
   DOLI_CRON: !!str 0
+  {{- if ne .Values.env "prod" }}
+  # Non-prod (sandbox): dev mode — render real errors inline instead of the generic
+  # prod "technical error" banner. Prod keeps the image default (DOLI_PROD=1).
+  DOLI_PROD: !!str 0
+  {{- end }}
   # DOLI_INSTANCE_UNIQUE_ID: <random salt for encryption>

chart/templates/scripts-config.yaml

@@ -7,4 +7,4 @@ data:
     {{- .Files.Get "scripts/update_conf_db_credentials.sh" | nindent 4 }}
   
   update_table_ownership.sql: |
-    {{- .Files.Get "scripts/update_ownership.sql" | nindent 4 }}
+    {{- tpl (.Files.Get "scripts/update_ownership.sql") . | nindent 4 }}

chart/templates/vaultauth.yaml

@@ -7,7 +7,7 @@ spec:
   method: kubernetes
   mount: kubernetes
   kubernetes:
-    role: erp
+    role: {{ .Values.vault.k8sRole }}
     serviceAccount: {{ include "erp.serviceAccountName" . }}
     audiences:
       - vault

chart/templates/vaultdynamicsecret.yaml

@@ -9,7 +9,7 @@ spec:
   mount: postgres
 
   # Path to the secret
-  path: creds/erp
+  path: {{ .Values.vault.dynamicPath }}
 
   # Where to store the secrets, VSO will create the secret
   destination:

chart/templates/vaultsecret.yaml

@@ -10,7 +10,7 @@ spec:
   mount: kvv2
 
   # path of the secret
-  path: erp/config
+  path: {{ .Values.vault.staticPath }}
 
   # dest k8s secret
   destination:

chart/values-sandbox.yaml

@@ -0,0 +1,40 @@
+# Sandbox overlay — to be combined with values.yaml:
+#   helm install erp-sandbox chart/ -f chart/values.yaml -f chart/values-sandbox.yaml \
+#                                   --namespace erp-sandbox --create-namespace
+#
+# Activates Phase D of the multi-env evolution (cf. PR thread). Prerequisites:
+#   - factory/postgres/iac/terraform.tfvars: erp has envs = ["prod", "sandbox"]
+#   - tools/hashicorp-vault/iac/modules/app_roles: env parameter applied
+#   - arcodange-org/erp/iac/main.tf: for_each over local.envs (Phase D commit)
+#   - ArgoCD: Application "erp-sandbox" registered (Phase E)
+#
+# Derived names follow the elision rule: env=sandbox → suffix "-sandbox".
+
+env:      sandbox
+instance: erp-sandbox
+host:     erp-sandbox.arcodange.lab
+
+db:
+  name: erp-sandbox
+  ownerRole: erp_sandbox_role
+
+vault:
+  k8sRole:     erp-sandbox
+  dynamicPath: creds/erp-sandbox
+  staticPath:  erp-sandbox/config
+
+# Ingress annotations + hosts — override to point at the sandbox FQDN
+ingress:
+  enabled: true
+  annotations:
+    traefik.ingress.kubernetes.io/router.entrypoints: websecure
+    traefik.ingress.kubernetes.io/router.tls: "true"
+    traefik.ingress.kubernetes.io/router.tls.certresolver: letsencrypt
+    traefik.ingress.kubernetes.io/router.tls.domains.0.main: arcodange.lab
+    traefik.ingress.kubernetes.io/router.tls.domains.0.sans: erp-sandbox.arcodange.lab
+    traefik.ingress.kubernetes.io/router.middlewares: localIp@file
+  hosts:
+    - host: erp-sandbox.arcodange.lab
+      paths:
+        - path: /
+          pathType: Prefix

chart/values.yaml

@@ -2,6 +2,27 @@
 # This is a YAML-formatted file.
 # Declare variables to be passed into your templates.
 
+# ----------------------------------------------------------------------------
+# Multi-environment coordinates (default = prod, elision rule applies).
+# Override in values-<env>.yaml for any non-prod instance — see SKILL.md
+# of the factory runbook (doc/runbooks/new-web-app/conventions.md).
+# By the elision rule, env=prod produces names identical to single-env apps;
+# env=sandbox produces "<app>-sandbox" everywhere except the Postgres owner
+# role which uses snake-case "<app>_sandbox_role".
+# ----------------------------------------------------------------------------
+env:      prod
+instance: erp                          # derived id: env=prod → erp, else <app>-<env>
+host:     erp.arcodange.lab            # internal hostname for this instance
+
+db:
+  name: erp                            # PostgreSQL database name (matches factory tfvars)
+  ownerRole: erp_role                  # Postgres owner role; snake-case <app>_role for prod / <app>_<env>_role for non-prod (matches factory/postgres/iac)
+
+vault:
+  k8sRole:     erp                     # VaultAuth role (postgres/iac issues this per instance)
+  dynamicPath: creds/erp               # path under postgres/ mount for short-lived DB creds
+  staticPath:  erp/config              # path under kvv2/ mount for the static admin config
+
 replicaCount: 1
 
 image:

iac/main.tf

@@ -1,32 +1,66 @@
 locals {
   app = {
-    name = "erp"
+    name         = "erp"
     product_name = "dolibarr" # unused
   }
+
+  # Environments this app is deployed to. By the elision rule (factory runbook
+  # conventions.md / ADR-0002) env=prod renders identical to the single-env
+  # baseline; non-prod envs get a "<name>-<env>" instance id from the module.
+  envs = toset(["prod", "sandbox"])
 }
 
 module "app_roles" {
-  source = "git::ssh://git@192.168.1.202:2222/arcodange-org/tools.git//hashicorp-vault/iac/modules/app_roles?depth=1&ref=main"
+  source   = "git::ssh://git@192.168.1.202:2222/arcodange-org/tools.git//hashicorp-vault/iac/modules/app_roles?depth=1&ref=main"
-  name = local.app.name
+  for_each = local.envs
+  name     = local.app.name
+  env      = each.key
 }
 
 resource "random_password" "admin_initial_password" {
-  length           = 32
+  for_each = local.envs
+  length   = 32
 }
 resource "random_uuid" "dolibarr_id" { # used for encryption as well as when buying modules
+  for_each = local.envs
   lifecycle {
     prevent_destroy = true
   }
 }
 
 resource "vault_kv_secret_v2" "dolibarr_admin_setup" {
-  mount                      = module.app_roles.mount_paths.kvv2
+  for_each = local.envs
-  name                       = format("%sconfig", module.app_roles.kvv2_path_prefix)
+  mount    = module.app_roles[each.key].mount_paths.kvv2
-  data_json                  = jsonencode(
+  name     = format("%sconfig", module.app_roles[each.key].kvv2_path_prefix)
-  {
+  data_json = jsonencode(
-    DOLI_ADMIN_LOGIN        = "admin",
+    {
-    DOLI_ADMIN_PASSWORD     = random_password.admin_initial_password.result
+      DOLI_ADMIN_LOGIN        = "admin",
-    DOLI_INSTANCE_UNIQUE_ID = random_uuid.dolibarr_id.result
+      DOLI_ADMIN_PASSWORD     = random_password.admin_initial_password[each.key].result
-  }
+      DOLI_INSTANCE_UNIQUE_ID = random_uuid.dolibarr_id[each.key].result
+    }
   )
 }
+
+# State migration (ADR-0002 Phase D): re-key the pre-existing single-env resources
+# into the for_each map under the "prod" key so that introducing for_each does NOT
+# plan a destroy+create. This is critical for random_uuid.dolibarr_id — it carries
+# prevent_destroy = true (it is the prod Dolibarr encryption id + paid-module
+# binding), so a missing moved block would HARD-FAIL the apply rather than silently
+# losing it. The module's own internal moved (role -> role[0]) chains with the
+# module re-key here.
+moved {
+  from = module.app_roles
+  to   = module.app_roles["prod"]
+}
+moved {
+  from = random_password.admin_initial_password
+  to   = random_password.admin_initial_password["prod"]
+}
+moved {
+  from = random_uuid.dolibarr_id
+  to   = random_uuid.dolibarr_id["prod"]
+}
+moved {
+  from = vault_kv_secret_v2.dolibarr_admin_setup
+  to   = vault_kv_secret_v2.dolibarr_admin_setup["prod"]
+}

ops/sandbox/README.md

@@ -0,0 +1,60 @@
+# erp-sandbox lifecycle ops
+
+Tooling to make `erp-sandbox` **iso-prod** and to reset it, implementing
+[ADR-0003](https://gitea.arcodange.lab/arcodange-org/factory/src/branch/main/vibe/ADR/0003-sandbox-state-lifecycle.md)
+(sandbox state lifecycle). The sandbox exists so AI agents can rehearse Dolibarr
+**write** operations against a faithful copy of prod, with a structural guarantee
+that the rehearsal path can never mutate prod.
+
+## The prod-integrity guarantee (why this is safe)
+
+| Layer | Enforcement |
+| --- | --- |
+| prod is **read-only** during a refresh | `pg_dump` runs with `default_transaction_read_only=on` |
+| the restore can only write the sandbox | it uses the sandbox's own dynamic creds — a member of `erp_sandbox_role`, which **owns only `erp-sandbox`** |
+| no database is dropped/created | wipe is `DROP OWNED BY erp_sandbox_role CASCADE`; reload is `pg_restore` (no `CREATEDB`, no superuser) |
+| prod is structurally undroppable | `DROP DATABASE` needs ownership; `erp_sandbox_role` does not own prod `erp` (owned by `erp_role`) |
+
+The only prod-capable credential on the platform is the `superuser=true` provider
+in `factory postgres/iac/providers.tf`, used **only** in the human-gated
+`postgres.yaml` CI. This tooling never touches it.
+
+## Usage
+
+```sh
+./sandbox-lifecycle.sh refresh-from-prod   # clone prod DB (data + config) into erp-sandbox
+./sandbox-lifecycle.sh sync-documents      # copy mycompany/ uploads (company logo, PDFs)
+./sandbox-lifecycle.sh refresh             # both, in order
+```
+
+`refresh-from-prod` scales the sandbox pod to 0, dumps the full prod `public`
+schema (read-only), wipes the sandbox's app objects, restores, and scales back
+up. It dumps the **whole** schema (not just `llx_*`) so app helper functions and
+their triggers (e.g. `update_modified_column_tms()`) come over; it filters out
+the provisioner-owned `user_lookup` pgbouncer function from the restore TOC
+because that object already exists per-environment and is not app data.
+
+## Two fidelity caveats (by design — see ADR-0003)
+
+1. **Encryption.** Dolibarr ties some encrypted fields (notably API keys) to
+   `DOLI_INSTANCE_UNIQUE_ID`. The sandbox has its **own** uuid, so prod-encrypted
+   values won't decrypt there. This is why the write-scoped `ai_agent_sandbox`
+   API key must be **generated inside the sandbox** (see `../../test/` POC),
+   not copied from prod. Most data is plaintext and unaffected.
+2. **Uploaded files live on the PVC, not the DB.** A DB refresh copies the logo
+   *const* (`MAIN_INFO_SOCIETE_LOGO`) but not the image; `sync-documents` copies
+   the `documents/mycompany` tree so the logo + attachments actually render.
+
+## BDD reset loop (E4)
+
+For repeated rehearsals, `refresh-from-prod` is the "reset to prod state". A
+faster checkpoint/reset that avoids re-reading prod each time (cache a golden
+dump on a small PVC, then `DROP OWNED + pg_restore` from it) is the documented
+next optimization — see ADR-0003 §Decision/Consequences.
+
+## Hardening backlog
+
+- Replace the transient copy of prod's read+write creds with a **dedicated
+  read-only Postgres role** (issued via a Vault dynamic role) so the dump path is
+  least-privilege by construction, not just by `default_transaction_read_only`.
+- Provision a golden-cache PVC for fast BDD resets.

ops/sandbox/sandbox-lifecycle.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+#
+# sandbox-lifecycle.sh — seed / refresh the erp-sandbox Dolibarr from prod, and
+# sync its uploaded documents, with prod integrity guaranteed structurally.
+#
+# Implements ADR-0003 (factory vibe/ADR/0003-sandbox-state-lifecycle.md):
+#   - prod is read ONLY (pg_dump runs in a default_transaction_read_only session);
+#   - the restore writes ONLY to erp-sandbox, using the sandbox's own dynamic
+#     credentials (a member of erp_sandbox_role, which owns only the sandbox DB),
+#     so it is structurally incapable of touching prod 'erp' (owned by erp_role);
+#   - no DROP/CREATE DATABASE, no CREATEDB, no superuser — wipe is
+#     `DROP OWNED BY erp_sandbox_role CASCADE`, reload is `pg_restore`.
+#
+# The only prod-capable credential on the platform is the superuser provider in
+# factory postgres/iac, exercised solely in the human-gated postgres.yaml CI —
+# this script never uses it.
+#
+# Requires: kubectl (context on the lab cluster), and a postgres:16 image
+# reachable by the cluster. Run from anywhere.
+#
+# Usage:
+#   ./sandbox-lifecycle.sh refresh-from-prod   # iso-prod seed: prod DB -> erp-sandbox
+#   ./sandbox-lifecycle.sh sync-documents      # copy mycompany/ uploads (logo, PDFs)
+#   ./sandbox-lifecycle.sh refresh             # refresh-from-prod + sync-documents
+#
+set -euo pipefail
+
+PROD_NS="erp"
+SB_NS="erp-sandbox"
+PROD_DB="erp"
+SB_DB="erp-sandbox"
+SB_ROLE="erp_sandbox_role"          # snake-case owner role (ADR-0002 elision rule)
+PGHOST="192.168.1.202"              # direct Postgres (NOT pgbouncer — pooler breaks pg_dump)
+PG_IMAGE="postgres:16-alpine"
+DOC_ROOT="/var/www/documents"       # dolibarr_main_data_root
+TMP_PROD_SECRET="prod-db-ro-temp"   # transient copy of prod creds, deleted on exit
+
+log() { printf '\033[1;36m==>\033[0m %s\n' "$*"; }
+die() { printf '\033[1;31mABORT:\033[0m %s\n' "$*" >&2; exit 1; }
+
+sb_pod() { kubectl get pod -n "$SB_NS" -l app.kubernetes.io/instance=erp-sandbox -o name 2>/dev/null | head -1; }
+prod_pod() { kubectl get pod -n "$PROD_NS" -l app.kubernetes.io/instance=erp -o name 2>/dev/null | head -1; }
+
+cleanup_secret() { kubectl delete secret "$TMP_PROD_SECRET" -n "$SB_NS" --ignore-not-found >/dev/null 2>&1 || true; }
+
+refresh_from_prod() {
+  command -v python3 >/dev/null || die "python3 required to copy the prod secret without exposing it"
+  trap cleanup_secret EXIT
+
+  log "Copying prod DB creds into a transient, read-only-intent secret in $SB_NS (values stay base64)"
+  kubectl get secret vso-db-credentials -n "$PROD_NS" -o json \
+    | python3 -c "import json,sys; d=json.load(sys.stdin); d['metadata']={'name':'$TMP_PROD_SECRET','namespace':'$SB_NS'}; d.pop('status',None); d['data']={k:d['data'][k] for k in ('username','password')}; print(json.dumps(d))" \
+    | kubectl apply -f - >/dev/null
+
+  log "Scaling erp-sandbox to 0 (exclusive DB access for the restore)"
+  kubectl scale deploy erp-sandbox -n "$SB_NS" --replicas=0 >/dev/null
+  kubectl wait --for=delete pod -l app.kubernetes.io/instance=erp-sandbox -n "$SB_NS" --timeout=120s >/dev/null 2>&1 || true
+
+  log "Running the seed Job (pg_dump prod read-only -> DROP OWNED -> pg_restore into sandbox)"
+  kubectl delete job sandbox-seed -n "$SB_NS" --ignore-not-found >/dev/null 2>&1 || true
+  kubectl apply -f - >/dev/null <<EOF
+apiVersion: batch/v1
+kind: Job
+metadata: { name: sandbox-seed, namespace: $SB_NS }
+spec:
+  backoffLimit: 0
+  ttlSecondsAfterFinished: 900
+  template:
+    spec:
+      restartPolicy: Never
+      containers:
+        - name: seed
+          image: $PG_IMAGE
+          env:
+            - { name: PROD_PGUSER,    valueFrom: { secretKeyRef: { name: $TMP_PROD_SECRET,   key: username } } }
+            - { name: PROD_PGPASSWORD, valueFrom: { secretKeyRef: { name: $TMP_PROD_SECRET,  key: password } } }
+            - { name: SB_PGUSER,      valueFrom: { secretKeyRef: { name: vso-db-credentials, key: username } } }
+            - { name: SB_PGPASSWORD,  valueFrom: { secretKeyRef: { name: vso-db-credentials, key: password } } }
+            - { name: PGHOST,   value: "$PGHOST" }
+            - { name: PGSSLMODE, value: "disable" }
+          command: ["/bin/sh","-c"]
+          args:
+            - |
+              set -eu
+              SBDB=\$(PGPASSWORD=\$SB_PGPASSWORD psql -h "\$PGHOST" -U "\$SB_PGUSER" -d $SB_DB -tAc 'select current_database()')
+              [ "\$SBDB" = "$SB_DB" ] || { echo "ABORT: target is '\$SBDB' not $SB_DB"; exit 1; }
+              echo "source=$PROD_DB (read-only)  target=$SB_DB  ok"
+              # 1. dump prod — full public schema (incl. helper functions + triggers), read-only session
+              PGPASSWORD=\$PROD_PGPASSWORD PGOPTIONS='-c default_transaction_read_only=on' \\
+                pg_dump -h "\$PGHOST" -U "\$PROD_PGUSER" -d $PROD_DB -n public -Fc -f /tmp/golden.dump
+              # drop provisioner-owned infra (pgbouncer user_lookup) from the TOC: it already
+              # exists in the sandbox and is not app data, so restoring it conflicts.
+              pg_restore -l /tmp/golden.dump | grep -vi 'user_lookup' > /tmp/golden.toc
+              echo "dump: \$(ls -l /tmp/golden.dump | awk '{print \$5}') bytes, tables=\$(grep -c 'TABLE DATA ' /tmp/golden.toc)"
+              # 2. wipe sandbox app objects (everything owned by the app role; infra untouched)
+              PGPASSWORD=\$SB_PGPASSWORD psql -h "\$PGHOST" -U "\$SB_PGUSER" -d $SB_DB -v ON_ERROR_STOP=1 \\
+                -c "DROP OWNED BY $SB_ROLE CASCADE;"
+              # 3. restore golden, owned by the sandbox role
+              PGPASSWORD=\$SB_PGPASSWORD \\
+                pg_restore -L /tmp/golden.toc --no-owner --role=$SB_ROLE -d $SB_DB /tmp/golden.dump \\
+                && echo "restore: clean" || echo "restore: completed with ignorable warnings"
+              # 4. verify
+              Q() { PGPASSWORD=\$SB_PGPASSWORD psql -h "\$PGHOST" -U "\$SB_PGUSER" -d $SB_DB -tAc "\$1"; }
+              echo "llx tables=\$(Q "select count(*) from pg_tables where schemaname='public' and tablename like 'llx_%'")  company=\$(Q "select value from llx_const where name='MAIN_INFO_SOCIETE_NOM'")  lang=\$(Q "select value from llx_const where name='MAIN_LANG_DEFAULT'")  owner=\$(Q "select tableowner from pg_tables where tablename='llx_societe'")"
+              echo "DONE."
+EOF
+  kubectl wait --for=condition=complete job/sandbox-seed -n "$SB_NS" --timeout=300s >/dev/null 2>&1 \
+    || die "seed Job did not complete — see: kubectl logs -n $SB_NS job/sandbox-seed"
+  kubectl logs -n "$SB_NS" job/sandbox-seed | sed 's/^/    /'
+  kubectl delete job sandbox-seed -n "$SB_NS" --ignore-not-found >/dev/null 2>&1 || true
+
+  log "Scaling erp-sandbox back to 1"
+  kubectl scale deploy erp-sandbox -n "$SB_NS" --replicas=1 >/dev/null
+  cleanup_secret; trap - EXIT
+  log "Refresh complete. Run 'sync-documents' to also copy the company logo + uploads."
+}
+
+sync_documents() {
+  local pp sp
+  pp=$(prod_pod); sp=$(sb_pod)
+  [ -n "$pp" ] || die "no prod erp pod found"
+  [ -n "$sp" ] || die "no erp-sandbox pod found"
+  log "Syncing $DOC_ROOT/mycompany (logo + uploads) ${pp##*/} -> ${sp##*/} via tar pipe"
+  kubectl exec -n "$PROD_NS" "${pp#pod/}" -- tar -C "$DOC_ROOT" -cf - mycompany 2>/dev/null \
+    | kubectl exec -i -n "$SB_NS" "${sp#pod/}" -- tar -C "$DOC_ROOT" -xf -
+  log "Documents synced. (For a one-shot logo only, scope the tar to mycompany/logos.)"
+}
+
+case "${1:-}" in
+  refresh-from-prod) refresh_from_prod ;;
+  sync-documents)    sync_documents ;;
+  refresh)           refresh_from_prod; sync_documents ;;
+  *) echo "usage: $0 {refresh-from-prod|sync-documents|refresh}" >&2; exit 2 ;;
+esac

test/.env.example

@@ -1,5 +1,27 @@
+# Copy this template to one of:
+#   .env           — production target, loaded by main.ts
+#   .env.sandbox   — sandbox target,    loaded by provisionSandbox.ts
+# Both are gitignored. Never commit real secret values.
+
+# --- Target ---
+# prod:    https://erp.arcodange.lab          (.env)
+# sandbox: https://erp-sandbox.arcodange.lab  (.env.sandbox)
 DOLIBARR_ADDRESS=https://erp.arcodange.lab
-DOLI_DB_PASSWORD=
+
 DOLI_ADMIN_LOGIN=admin
 DOLI_ADMIN_PASSWORD=""
+DOLI_DB_PASSWORD=""
 ROOT_FOLDER=$HOME/erp
+
+# Populate the passwords from the cluster secrets, e.g. (prod shown):
+#   DOLI_ADMIN_PASSWORD  <- kubectl get secret secretkv -n erp -o jsonpath='{.data.DOLI_ADMIN_PASSWORD}' | base64 -d
+#   DOLI_DB_PASSWORD     <- kubectl get secret vso-db-credentials -n erp -o jsonpath='{.data.password}' | base64 -d
+#
+# NOTE for a sandbox SEEDED from prod (ops/sandbox/sandbox-lifecycle.sh): the seed
+# clones prod's admin password into the sandbox, so .env.sandbox's
+# DOLI_ADMIN_PASSWORD must be PROD's admin password (-n erp), not the sandbox
+# secretkv. The DB password is the sandbox's own (-n erp-sandbox).
+
+# Optional: fix the provisioned user's password (else one is generated and only
+# the API key is emitted to .ai_agent_sandbox.key).
+# AI_AGENT_SANDBOX_PASSWORD=""

test/.gitignore

@@ -0,0 +1,6 @@
+# Secrets — never commit. Covers .env (prod, main.ts) and .env.sandbox
+# (sandbox, provisionSandbox.ts), plus any generated *.key.
+.env*
+!.env.example
+.ai_agent_sandbox.key
+*.key

test/README.md

@@ -0,0 +1,106 @@
+# test — Dolibarr UI automation (Deno + Playwright)
+
+A small Deno + Playwright POC that drives the Dolibarr admin UI in the `fr-FR`
+locale. Playwright fills the same forms a human admin would, so the automation
+works even where the REST API can't (e.g. generating an API key, which is
+encrypted with the instance's own `DOLI_INSTANCE_UNIQUE_ID`).
+
+## Layout
+
+- `main.ts` — original entrypoint (first install, company/display/module setup).
+- `provisionSandbox.ts` — entrypoint that provisions the `erp-sandbox` instance
+  for the AI agent (enable REST API, create a write-scoped user, generate its
+  API key).
+- `scripts/login.ts` — admin login / logout / whoami helpers.
+- `scripts/forms.ts` — `fillForm`, `toggleOnOff`, CKEditor/ACE helpers.
+- `scripts/admin/moduleSetup.ts` — `configureModule`, `enableApiModule`.
+- `scripts/admin/userSetup.ts` — `createUser`, `assignRights`, `generateApiKey`.
+
+## Configure
+
+Copy `.env.example` to `.env` and fill it in. `.env`, `*.key`, and
+`.ai_agent_sandbox.key` are gitignored — never commit secrets.
+
+```sh
+cp .env.example .env
+```
+
+## Lock the installer (after a fresh install via `main.ts`)
+
+Dolibarr keeps its web installer reachable until an `install.lock` file exists.
+After a fresh install (the `main.ts` flow), create it in the target pod — for the
+sandbox:
+
+```sh
+kubectl -n erp-sandbox exec \
+  "$(kubectl get pod -n erp-sandbox -l app.kubernetes.io/instance=erp-sandbox -o name)" -- \
+  /bin/sh -c 'touch /var/www/documents/install.lock && chown www-data:www-data /var/www/documents/install.lock'
+```
+
+The path is the Dolibarr **data root** (`/var/www/documents`, a PVC) — that's where
+Dolibarr checks, and being on the PVC the lock persists across pod restarts. For
+prod, swap to `-n erp -l app.kubernetes.io/instance=erp`. A sandbox **seeded** from
+prod still needs this: the seed (see `../ops/sandbox/`) copies the DB +
+`documents/mycompany`, not `install.lock`.
+
+## Provision the sandbox
+
+Provisions `erp-sandbox.arcodange.lab`: enables the REST API module, creates the
+write-scoped `ai_agent_sandbox` user, grants it its write rights, and has
+Dolibarr generate the user's API key. The key is written to
+`test/.ai_agent_sandbox.key` (gitignored) — it is never printed.
+
+```sh
+cd test
+deno run --allow-all provisionSandbox.ts
+```
+
+Populate `.env` from the `erp-sandbox` namespace secrets first. `secretkv`
+carries the app env (including `DOLI_ADMIN_PASSWORD`); `vso-db-credentials`
+carries the database password:
+
+```sh
+# Admin password (key DOLI_ADMIN_PASSWORD inside the secretkv secret)
+kubectl get secret secretkv -n erp-sandbox \
+  -o jsonpath='{.data.DOLI_ADMIN_PASSWORD}' | base64 -d
+
+# Database password (key `password` inside vso-db-credentials)
+kubectl get secret vso-db-credentials -n erp-sandbox \
+  -o jsonpath='{.data.password}' | base64 -d
+```
+
+Set in `.env`:
+
+```sh
+DOLIBARR_ADDRESS=https://erp-sandbox.arcodange.lab
+DOLI_ADMIN_LOGIN=admin
+DOLI_ADMIN_PASSWORD="<from secretkv above>"
+DOLI_DB_PASSWORD="<from vso-db-credentials above>"
+# Optional — otherwise a random password is generated and only the API key emitted:
+# AI_AGENT_SANDBOX_PASSWORD="<choose one>"
+```
+
+### After it runs
+
+The generated API key lands in `test/.ai_agent_sandbox.key`. Next step (not
+automated by this POC): load it into the `dolibarr` skill's sandbox config /
+Vault at `kvv2/erp-sandbox/ai_agent`.
+
+> [!IMPORTANT]
+> The sandbox Dolibarr is not installed/provisioned yet (empty DB, fresh install
+> wizard). Until the install wizard has been completed against the sandbox,
+> `provisionSandbox.ts` will not have a UI to drive, and the selectors in
+> `moduleSetup.ts` / `userSetup.ts` are best-effort (Dolibarr 22 conventions,
+> not verified live). Confirm them on the first real run.
+
+### Write rights granted
+
+The `ai_agent_sandbox` user is created non-admin and granted read + create on:
+
+| Module           | rights ids                         |
+| ---------------- | ---------------------------------- |
+| facture          | lire=11, creer=12                  |
+| societe          | lire=121, creer=122                |
+| societe contact  | lire=281, creer=282                |
+| fournisseur      | lire=1181, facture lire=1231, facture creer=1232 |
+| produit          | lire=31, creer=32                  |

test/deno.lock

@@ -1,7 +1,8 @@
 {
-  "version": "4",
+  "version": "5",
   "specifiers": {
     "jsr:@std/dotenv@*": "0.225.2",
+    "npm:@types/node@*": "24.2.0",
     "npm:playwright@^1.48.2": "1.48.2"
   },
   "jsr": {
@@ -10,18 +11,33 @@
     }
   },
   "npm": {
+    "@types/node@24.2.0": {
+      "integrity": "sha512-3xyG3pMCq3oYCNg7/ZP+E1ooTaGB4cG8JWRsqqOYQdbWNY4zbaV0Ennrd7stjiJEFZCaybcIgpTjJWHRfBSIDw==",
+      "dependencies": [
+        "undici-types"
+      ]
+    },
     "fsevents@2.3.2": {
-      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA=="
+      "integrity": "sha512-xiqMQR4xAeHTuB9uWm+fFRcIOgKBMiOBP+eXiyT7jsgVCq1bkVygt00oASowB7EdtpOHaaPgKt812P9ab+DDKA==",
+      "os": ["darwin"],
+      "scripts": true
     },
     "playwright-core@1.48.2": {
-      "integrity": "sha512-sjjw+qrLFlriJo64du+EK0kJgZzoQPsabGF4lBvsid+3CNIZIYLgnMj9V6JY5VhM2Peh20DJWIVpVljLLnlawA=="
+      "integrity": "sha512-sjjw+qrLFlriJo64du+EK0kJgZzoQPsabGF4lBvsid+3CNIZIYLgnMj9V6JY5VhM2Peh20DJWIVpVljLLnlawA==",
+      "bin": true
     },
     "playwright@1.48.2": {
       "integrity": "sha512-NjYvYgp4BPmiwfe31j4gHLa3J7bD2WiBz8Lk2RoSsmX38SVIARZ18VYjxLjAcDsAhA+F4iSEXTSGgjua0rrlgQ==",
       "dependencies": [
-        "fsevents",
         "playwright-core"
-      ]
+      ],
+      "optionalDependencies": [
+        "fsevents"
+      ],
+      "bin": true
+    },
+    "undici-types@7.10.0": {
+      "integrity": "sha512-t5Fy/nfn+14LuOc2KNYg75vZqClpAiqscVvMygNnlsHBFpSXdJaYtXMcdNLpl/Qvc3P2cB3s6lOV51nqsFq4ag=="
     }
   },
   "workspace": {

test/provisionSandbox.ts

@@ -0,0 +1,152 @@
+import { loadSync } from "jsr:@std/dotenv";
+// Sandbox provisioning loads its OWN .env.sandbox; prod config stays in .env (main.ts).
+loadSync({ envPath: ".env.sandbox", export: true });
+import { chromium } from "playwright";
+import path from "node:path";
+import login from "./scripts/login.ts";
+import moduleSetup from "./scripts/admin/moduleSetup.ts";
+import userSetup from "./scripts/admin/userSetup.ts";
+
+/*
+  provisionSandbox.ts — separate entrypoint (does NOT touch main.ts).
+
+  Provisions the erp-sandbox Dolibarr so the AI agent can write to it:
+    1. enable the REST API / Web services module,
+    2. create a write-scoped `ai_agent_sandbox` user (non-admin),
+    3. grant it the write rights it needs,
+    4. have Dolibarr generate its API key and emit it safely to
+       test/.ai_agent_sandbox.key (gitignored).
+
+  Run:
+    cd test && deno run --allow-all provisionSandbox.ts
+
+  CANNOT be run end-to-end yet: the sandbox Dolibarr is not installed/provisioned
+  (empty DB, fresh install wizard). Selector correctness in moduleSetup.ts /
+  userSetup.ts is therefore best-effort and must be verified on the first real
+  run, AFTER the install wizard has been completed against the sandbox.
+
+  NEXT STEP (not implemented here): load the generated key into the dolibarr
+  skill's sandbox config / Vault at kvv2/erp-sandbox/ai_agent. We intentionally
+  do NOT write to Vault from this POC.
+*/
+
+/*
+  Write rights to grant `ai_agent_sandbox` (stable Dolibarr rights ids, verified
+  against prod Dolibarr 22.0.4). Each module's read (lire) + create (creer):
+    facture:           lire=11,   creer=12
+    societe:           lire=121,  creer=122, client voir (see-all)=262
+    societe contact:   lire=281,  creer=282
+    fournisseur:       lire=1181, facture lire=1231, facture creer=1232
+    produit:           lire=31,   creer=32
+*/
+const WRITE_IDS = [
+  11, // facture lire
+  12, // facture creer
+  121, // societe lire
+  122, // societe creer
+  262, // societe client "voir" (see-all) — REQUIRED for the /thirdparties LIST
+  //      endpoint; without it the list 404s (the voir_tous ACL trap, cf. the
+  //      dolibarr skill SKILL.md). Other modules' lists work with plain `lire`.
+  281, // societe contact lire
+  282, // societe contact creer
+  1181, // fournisseur lire
+  1231, // fournisseur facture lire
+  1232, // fournisseur facture creer
+  31, // produit lire
+  32, // produit creer
+];
+
+const KEY_FILE = ".ai_agent_sandbox.key";
+
+/*
+  Initialisation — mirrors main.ts but targeted at the sandbox. The default
+  address points at the sandbox; admin creds come from env (the same
+  DOLI_ADMIN_LOGIN / DOLI_ADMIN_PASSWORD vars main.ts uses, populated from the
+  erp-sandbox namespace secrets — see test/README.md "Provision the sandbox").
+*/
+const dolibarrAddress = Deno.env.get("DOLIBARR_ADDRESS") ||
+  "https://erp-sandbox.arcodange.lab";
+const debug = true;
+const DBpassword = Deno.env.get("DOLI_DB_PASSWORD") || "undefined";
+const adminCredentials = {
+  username: Deno.env.get("DOLI_ADMIN_LOGIN") || "admin",
+  password: Deno.env.get("DOLI_ADMIN_PASSWORD") || "undefined",
+};
+
+// The new user's login is fixed; its password comes from env or is generated.
+const AI_AGENT_LOGIN = "ai_agent_sandbox";
+const aiAgentPassword = Deno.env.get("AI_AGENT_SANDBOX_PASSWORD") ||
+  generatePassword();
+
+const rootFolderPath = Deno.env.get("ROOT_FOLDER") ||
+  path.join(Deno.cwd(), "..");
+const imgFolderPath = Deno.env.get("IMG_FOLDER") ||
+  path.join(rootFolderPath, "static/img");
+const configFolderPath = Deno.env.get("CONFIG_FOLDER") ||
+  path.join(rootFolderPath, "static/config");
+
+/* Generate a reasonably strong random password (used only if none provided). */
+function generatePassword(): string {
+  const bytes = new Uint8Array(18);
+  crypto.getRandomValues(bytes);
+  // URL-safe base64 → no shell-hostile characters.
+  return btoa(String.fromCharCode(...bytes))
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+const browser = await chromium.launch({
+  headless: false,
+  logger: {
+    isEnabled: (_name, _severity) => debug,
+    log: (name, severity, message, args) =>
+      console.warn(`${severity}| ${name} :: ${message} __ ${args}`),
+  },
+});
+const context = await browser.newContext({ locale: "fr-FR" });
+const page = await context.newPage();
+
+const globalCtx = {
+  dolibarrAddress,
+  DBpassword,
+  adminCredentials,
+
+  debug,
+  rootFolderPath,
+  imgFolderPath,
+  configFolderPath,
+
+  browser,
+  page,
+  context,
+};
+
+try {
+  await login.doAdminLogin(globalCtx);
+  console.log(`connected as ${await login.whoAmI(globalCtx)}`);
+
+  await moduleSetup.enableApiModule(globalCtx);
+  console.log("REST API module enabled");
+
+  const userId = await userSetup.createUser(globalCtx, {
+    login: AI_AGENT_LOGIN,
+    password: aiAgentPassword,
+    lastname: "AI Agent (sandbox)",
+    admin: false,
+  });
+  console.log(`created user '${AI_AGENT_LOGIN}' (id=${userId})`);
+
+  await userSetup.assignRights(globalCtx, userId, WRITE_IDS);
+  console.log(`granted ${WRITE_IDS.length} write rights to id=${userId}`);
+
+  const apiKey = await userSetup.generateApiKey(globalCtx, userId);
+
+  // Emit the key safely: write it to a gitignored file rather than printing it.
+  await Deno.writeTextFile(KEY_FILE, apiKey + "\n");
+  console.log(`AI_AGENT_SANDBOX API KEY WRITTEN TO test/${KEY_FILE}`);
+} catch (error) {
+  console.error(error);
+} finally {
+  await browser.close();
+}

test/scripts/admin/moduleSetup.ts

@@ -1,19 +1,20 @@
-
 // info-box
 
-import { Page } from "playwright";
+import { Locator, Page } from "playwright";
 import forms from "../forms.ts";
 import login from "../login.ts";
 
 // span.info-box-title has-text /moduleName/
 // span.fa-cog[title="Configuration"]
 
+type ModuleCtx = {
+  page: Page;
+  dolibarrAddress: string;
+  adminCredentials: { username: string; password: string };
+};
+
 async function configureModule(
-    globalCtx: {
+    globalCtx: ModuleCtx,
-      page: Page;
-      dolibarrAddress: string;
-      adminCredentials: { username: string; password: string };
-    },
     {
         moduleName,
         enabled,
@@ -42,6 +43,61 @@ async function configureModule(
     }
 }
 
+/*
+  Enable Dolibarr's REST API / Web services module.
+
+  Activation maps to llx_const.MAIN_MODULE_API=1; in the UI this is the module
+  card on /admin/modules.php (kanban mode). In fr_FR the card title is
+  "API/Web services REST (serveur)" (family "Interfaces").
+
+  NOTE: confirm the exact card title on the first real run against an installed
+  sandbox — the label has not been verified live here. To stay resilient we try
+  the known fr_FR label first (anchored exact match, same as configureModule),
+  and if that card is not present we fall back to matching ANY module card whose
+  title contains "API ... REST" / "REST ... API" in either order.
+*/
+async function enableApiModule(globalCtx: ModuleCtx): Promise<void> {
+    const {page, dolibarrAddress}= globalCtx;
+
+    // fr_FR label as observed in the module catalogue. Confirm on first real run.
+    const knownLabel = "API/Web services REST (serveur)";
+
+    await login.doAdminLogin(globalCtx);
+    await page.goto(`${dolibarrAddress}/admin/modules.php?mode=commonkanban`);
+
+    const exactCard = page.locator('.info-box', {
+        has: page.locator('.info-box-title',{
+            hasText: new RegExp('^'+knownLabel+'\n?$','i')
+        })
+    });
+
+    if(await exactCard.count() > 0) {
+        await forms.toggleOnOff(exactCard, true);
+        return;
+    }
+
+    // Fallback: the exact fr_FR label was not found (different Dolibarr version,
+    // locale, or wording). Match any card whose title looks like the REST API
+    // module regardless of word order.
+    const fuzzyCard = page.locator('.info-box', {
+        has: page.locator('.info-box-title',{
+            hasText: /API.*REST|REST.*API/i
+        })
+    });
+
+    if(await fuzzyCard.count() === 0) {
+        throw new Error(
+            `REST API module card not found on ${dolibarrAddress}/admin/modules.php `+
+            `(tried exact label "${knownLabel}" and /API.*REST|REST.*API/i). `+
+            `Confirm the card title in the running sandbox.`,
+        );
+    }
+
+    // If several cards match the fuzzy pattern, toggle the first one only.
+    await forms.toggleOnOff(fuzzyCard.first() as Locator, true);
+}
+
 export default {
     configureModule,
+    enableApiModule,
 }

test/scripts/admin/userSetup.ts

@@ -0,0 +1,297 @@
+/*
+  User provisioning for the Dolibarr admin UI, driven by Playwright.
+
+  Why the UI and not raw SQL:
+    - Passwords use MAIN_SECURITY_HASH_ALGO=password_hash (bcrypt), so we let
+      Dolibarr hash them by submitting the create form.
+    - API keys are stored ENCRYPTED with the instance key DOLI_INSTANCE_UNIQUE_ID.
+      Each instance (incl. the sandbox) has its own uuid, so a key can only be
+      produced correctly by that instance — we MUST generate it via the UI and
+      read back the resulting value, never INSERT a raw key.
+
+  IMPORTANT — selectors below are best-effort and have NOT been verified against
+  a live, installed sandbox (the sandbox Dolibarr is not provisioned yet). Field
+  names / icon controls are taken from Dolibarr 22 conventions and must be
+  confirmed on the first real run. Spots that are guessed are marked GUESS:.
+*/
+import type { Page } from "playwright";
+import forms from "../forms.ts";
+import login from "../login.ts";
+
+type UserCtx = {
+  page: Page;
+  dolibarrAddress: string;
+  adminCredentials: { username: string; password: string };
+  // imgFolderPath is required by forms.fillForm's signature even though no
+  // file input is used here; provisionSandbox.ts supplies it from globalCtx.
+  imgFolderPath: string;
+};
+
+type NewUser = {
+  login: string;
+  password: string;
+  lastname?: string;
+  admin?: boolean;
+};
+
+// The text fields filled via forms.fillForm (the admin flag is a checkbox we
+// handle separately, so it is intentionally not part of this type).
+type UserFormFields = {
+  login: string;
+  password: string;
+  lastname?: string;
+};
+
+// fr_FR Dolibarr user create form (/user/card.php?action=create&mode=create).
+// GUESS: confirm these input names on first real run. `login` and `lastname`
+// are stable across Dolibarr versions; the password field has been `password`
+// for the manual-entry case (the "generate automatically" option is a separate
+// radio/checkbox we leave untouched so our explicit value is used).
+const newUserInputNames = new Map<keyof UserFormFields, string>([
+  ["login", "login"],
+  ["lastname", "lastname"],
+  ["password", "password"],
+]);
+
+/*
+  Create a user via /user/card.php?action=create and return its numeric id.
+
+  The admin flag is a checkbox (name="admin"); fillForm has no checkbox handler
+  so we toggle it explicitly. After submit Dolibarr redirects to the user card
+  whose URL carries ?id=<n> — we parse the id from there (falling back to a
+  hidden input on the page).
+*/
+async function createUser(
+  globalCtx: UserCtx,
+  { login: userLogin, password, lastname, admin = false }: NewUser,
+): Promise<number> {
+  const { page, dolibarrAddress, imgFolderPath } = globalCtx;
+  await login.doAdminLogin(globalCtx);
+
+  // Idempotent: if the login already exists (e.g. a re-run), return its id rather
+  // than submitting a duplicate create (which Dolibarr rejects).
+  const existingId = await findUserId(globalCtx, userLogin);
+  if (existingId !== undefined) return existingId;
+
+  await page.goto(`${dolibarrAddress}/user/card.php?action=create&mode=create`);
+
+  // Fill text inputs (login, lastname, password) without submitting yet.
+  const formFields: UserFormFields = {
+    login: userLogin,
+    password,
+    lastname,
+  };
+  await forms.fillForm(
+    { page, imgFolderPath },
+    formFields,
+    newUserInputNames,
+    0,
+  );
+
+  // Admin checkbox — only present when the logged-in user is themselves admin.
+  // GUESS: input[name="admin"]; on some setups it's a <select> instead.
+  const adminCheckbox = page.locator('input[name="admin"]');
+  if (await adminCheckbox.count() > 0) {
+    if (admin) {
+      await adminCheckbox.check();
+    } else {
+      // Leave unchecked (default), but be explicit/defensive.
+      if (await adminCheckbox.isChecked()) await adminCheckbox.uncheck();
+    }
+  }
+
+  // Submit the create form. The create page has a single primary submit button
+  // ("Créer utilisateur"); :nth-match index 1 mirrors the fillForm convention.
+  await page.click(':nth-match(input[type="submit"], 1)');
+
+  // After creation Dolibarr lands on the user card. Parse the id.
+  await page.waitForLoadState("domcontentloaded");
+  const id = await readUserIdFromPage(page);
+  if (id === undefined) {
+    throw new Error(
+      `Could not determine the new user id for login "${userLogin}" after ` +
+        `submitting the create form (current URL: ${page.url()}).`,
+    );
+  }
+  return id;
+}
+
+/*
+  Read the numeric user id from the current user card: first from the URL
+  (?id=<n>), then from a hidden input[name="id"] as a fallback.
+*/
+async function readUserIdFromPage(page: Page): Promise<number | undefined> {
+  const fromUrl = new URL(page.url()).searchParams.get("id");
+  if (fromUrl && /^\d+$/.test(fromUrl)) return Number(fromUrl);
+
+  // GUESS: a hidden input carrying the id (common on Dolibarr card pages).
+  const hidden = page.locator('input[name="id"]');
+  if (await hidden.count() > 0) {
+    const val = await hidden.first().getAttribute("value");
+    if (val && /^\d+$/.test(val)) return Number(val);
+  }
+  return undefined;
+}
+
+/*
+  Find an existing user's numeric id by login via the user list, so createUser is
+  idempotent across re-runs. Matches the table row containing the login, then reads
+  the id from that row's user-card link.
+*/
+async function findUserId(
+  globalCtx: UserCtx,
+  userLogin: string,
+): Promise<number | undefined> {
+  const { page, dolibarrAddress } = globalCtx;
+  await page.goto(
+    `${dolibarrAddress}/user/list.php?search_login=${encodeURIComponent(userLogin)}`,
+  );
+  await page.waitForLoadState("domcontentloaded");
+  const cardLink = page
+    .locator("tr", { hasText: userLogin })
+    .locator('a[href*="/user/card.php?id="]')
+    .first();
+  if (await cardLink.count() === 0) return undefined;
+  const href = (await cardLink.getAttribute("href")) ?? "";
+  const m = href.match(/[?&]id=(\d+)/);
+  return m ? Number(m[1]) : undefined;
+}
+
+/*
+  Grant a set of rights to a user on /user/perms.php?id=<userId>.
+
+  Dolibarr renders each grantable permission as a link whose href carries
+  action=addrights&rights=<id> (and a matching action=delrights to revoke).
+  A right that is already granted shows the delrights link instead, so we treat
+  the presence of an addrights link as "not yet granted" and click it; if it's
+  absent we assume the right is already on and skip it (defensive/idempotent).
+*/
+async function assignRights(
+  globalCtx: UserCtx,
+  userId: number,
+  rightIds: number[],
+): Promise<void> {
+  const { page, dolibarrAddress } = globalCtx;
+  await login.doAdminLogin(globalCtx);
+
+  for (const rightId of rightIds) {
+    // Re-navigate per right: Dolibarr reloads the perms table after each grant,
+    // which would otherwise stale the locators.
+    await page.goto(`${dolibarrAddress}/user/perms.php?id=${userId}`);
+
+    // The grant control is an <a> linking to action=addrights&rights=<id>. The
+    // trailing "&" anchors the id so rights=12 does NOT substring-match rights=121
+    // / rights=1232 etc. (Dolibarr hrefs are ...&rights=<id>&confirm=yes...).
+    const addLink = page.locator(
+      `a[href*="action=addrights"][href*="rights=${rightId}&"]`,
+    );
+
+    if (await addLink.count() === 0) {
+      // Either already granted (only a delrights link is shown) or the row is
+      // not visible for this user. Skip rather than fail the whole run.
+      continue;
+    }
+    await addLink.first().click();
+    await page.waitForLoadState("domcontentloaded");
+  }
+}
+
+/*
+  Generate (or read) the user's API key on /user/card.php?id=<userId> in edit
+  mode and RETURN it as a string.
+
+  With the API module enabled the user card edit form shows an api_key text
+  input plus a "generate" control (a dice/refresh icon-link, typically
+  id="generate_api_key" or an <a> with action=...generate...apikey). We trigger
+  generation, then read the value back out of the api_key input. If a key is
+  already present we read and return it without regenerating (idempotent).
+
+  The caller is responsible for handling the returned secret safely — DO NOT log
+  it at debug verbosity.
+*/
+async function generateApiKey(
+  globalCtx: UserCtx,
+  userId: number,
+): Promise<string> {
+  const { page, dolibarrAddress } = globalCtx;
+  await login.doAdminLogin(globalCtx);
+
+  await page.goto(`${dolibarrAddress}/user/card.php?id=${userId}&action=edit`);
+
+  // GUESS: the API key field is input[name="api_key"].
+  const apiKeyInput = page.locator('input[name="api_key"]');
+  if (await apiKeyInput.count() === 0) {
+    throw new Error(
+      `API key input (input[name="api_key"]) not found on the user card for ` +
+        `id=${userId}. Is the REST API module enabled? Confirm the field name ` +
+        `on the running sandbox.`,
+    );
+  }
+
+  // If a key is already set, reuse it.
+  const existing = (await apiKeyInput.first().inputValue()).trim();
+  if (existing.length > 0) return existing;
+
+  // Trigger generation. GUESS: a generate control next to the field. We try a
+  // few likely selectors in order and click the first that exists.
+  const generateSelectors = [
+    "#generate_api_key",
+    'a[href*="action=generateapikey"]',
+    'a[href*="generate"][href*="apikey"]',
+    // Icon-only fallbacks commonly used by Dolibarr "generate" buttons.
+    "span.fa-dice",
+    "a.fa-refresh",
+  ];
+
+  let clicked = false;
+  for (const sel of generateSelectors) {
+    const ctrl = page.locator(sel);
+    if (await ctrl.count() > 0) {
+      await ctrl.first().click();
+      clicked = true;
+      break;
+    }
+  }
+  if (!clicked) {
+    throw new Error(
+      `No API-key generate control found near input[name="api_key"] for ` +
+        `id=${userId} (tried ${generateSelectors.join(", ")}). Confirm the ` +
+        `generate control on the running sandbox.`,
+    );
+  }
+
+  // The generate control fills the input client-side; poll the input value
+  // (via the locator, no browser globals) until it is non-empty or we time out.
+  let key = "";
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    key = (await apiKeyInput.first().inputValue()).trim();
+    if (key.length > 0) break;
+    await page.waitForTimeout(200);
+  }
+  if (key.length === 0) {
+    throw new Error(
+      `API key field was still empty after triggering generation for ` +
+        `id=${userId}.`,
+    );
+  }
+
+  // Persist: the generate control only fills the field client-side. Submit the
+  // edit form so Dolibarr saves api_key to the DB — otherwise it stays NULL and
+  // the generated key never authenticates.
+  const saveBtn = page.locator('input[name="save"], button[name="save"]');
+  if (await saveBtn.count() > 0) {
+    await saveBtn.first().click();
+  } else {
+    await page.click(':nth-match(input[type="submit"], 1)');
+  }
+  await page.waitForLoadState("domcontentloaded");
+
+  return key;
+}
+
+export default {
+  createUser,
+  assignRights,
+  generateApiKey,
+};