erp/.claude/skills/dolibarr-data-snapshot/SKILL.md

name: dolibarr-data-snapshot description: Snapshot the read-only state of the Arcodange Dolibarr instance into a single content-addressable JSON file — status, thirdparties (list + per-id detail), invoices (list + per-id detail + per-id payments), recurring templates, products, bank accounts. Each snapshot includes a content_hash (sha256 of the data, EXCLUDING the captured-at timestamp) so two snapshots of identical state hash identically — drift detection is one comparison. Use cases: cohort-review evidence packs, archival before a known-risky change, time-series drift detection between two dates, point-in-time forensics. Use when the user asks "snapshot Dolibarr", "dump the state", "archiver l'ERP", "preuve cohort", "diff entre deux dates". Depends on the dolibarr skill. SKIP for one-shot reads (use the other workflow skills directly), for PDF / binary attachments (intentionally excluded — would bloat the snapshot), for write-side changes (this is read-only forensics), and for snapshotting NON-Dolibarr state (bank statements, k8s, etc. — those would be sibling skills). requires: bins: ["curl", "jq", "python3"] auth: true

dolibarr-data-snapshot — point-in-time JSON dump of Dolibarr read state

One script: snapshot.sh. Pulls every read-only endpoint the dolibarr-* family uses and bundles into a single JSON file with a content hash. Read-only, no side effects.

Depends on the dolibarr base skill.

What's in the snapshot

{
  "schema_version": "1",
  "captured_at": "2026-05-28T21:58:50Z",
  "instance": "erp.arcodange.lab",
  "content_hash": "sha256:6b94cd312d55a693d3c533ae6c9a5abef2734dd5bca8d4b1bdd5ca6ea6fc1f9a",
  "data": {
    "status":         { ... GET /status ... },
    "thirdparties":   { "list": [ ... GET /thirdparties ... ], "detail": { "1": { ... GET /thirdparties/1 ... }, ... } },
    "invoices":       { "list": [ ... ], "detail": { "12": { ... }, ... }, "payments": { "12": [ ... ], ... } },
    "recurring_templates": { "1": { ... GET /invoices/templates/1 ... }, ... },
    "products":       [ ... GET /products ... ],
    "bank_accounts":  [ ... GET /bankaccounts ... ]
  }
}

content_hash is the sha256 of data only — it deliberately excludes captured_at, schema_version, instance, and the hash field itself. So two snapshots taken at different moments but reflecting identical Dolibarr state have the same content_hash. That's what makes drift detection trivial:

jq -r .content_hash snap-2026-05.json snap-2026-06.json
# Same hash → no data changed between the two captures.
# Different hash → use `jq` / `diff` to find what moved.

Usage

./scripts/snapshot.sh                          # writes ./snapshot-YYYY-MM-DDTHHMMSSZ.json
./scripts/snapshot.sh --out /tmp/baseline.json
./scripts/snapshot.sh --print-only             # stdout, no file (pipe-friendly)
./scripts/snapshot.sh --max-template-id 100    # raise the template-probe upper bound

Live output of the current Dolibarr (captured at examples/snapshot-summary.txt — the actual JSON is too big to commit verbatim, ~246 KB):

wrote ./snapshot-2026-05-28T215850Z.json (246186 bytes)
  sha256:6b94cd312d55a693d3c533ae6c9a5abef2734dd5bca8d4b1bdd5ca6ea6fc1f9a

Contents (V1 baseline):

• 10 thirdparties (KissMetrics + 9 others — prospects / suppliers / etc.)
• 5 invoices, all KM (1 avoir + 4 regular)
• 5 per-invoice payment arrays
• 1 recurring template (Kiss Metrics Invoice — frequency=0, see dolibarr-recurring-templates)
• 2 products (KM-audit, KM-cloud-devops)
• 3 bank accounts (QONTO, WISE EURO, G.RADUREAU CCA)

What's intentionally excluded

• PDF attachments. /documents/download returns base64 bodies up to ~MB each. Including them would 10×–100× the snapshot size. Workflow skills (dolibarr-invoice-audit) fetch PDFs on-demand.
• users/info — leaks the ai_agent account internals. Out of scope for a read-only state dump.
• /setup/modules — admin-only, not available to ai_agent.
• Anything that requires writing (cron triggers, etc.).
• /payments list-all — returns 501 (see base skill catalogue); we get payment data via per-invoice fetches.

Use cases

1. Cohort-review evidence pack

./scripts/snapshot.sh --out evidence/dolibarr-2026-05-28.json
# Send the file as proof of the billing state at that moment.
# The content_hash signs the data.

2. Drift detection between two dates

./scripts/snapshot.sh --out snap-may.json
# ... a month passes ...
./scripts/snapshot.sh --out snap-jun.json
jq -r .content_hash snap-may.json snap-jun.json
# Different → something moved. Find what:
diff <(jq -S .data snap-may.json) <(jq -S .data snap-jun.json) | head -50

3. Archive before a known-risky change

Before manually firing the next M-N invoice, regenerating the PDF template, or any UI change with billing consequences:

./scripts/snapshot.sh --out before-change-$(date -u +%Y%m%d).json
# Make the change ...
./scripts/snapshot.sh --out after-change-$(date -u +%Y%m%d).json
# Diff to confirm only the intended state moved.

Performance

On the current Arcodange instance (5 invoices, 10 thirdparties, 1 template), the snapshot completes in ~2 seconds with one HTTP call per top-level resource + N calls for per-id fetches. At ~30 thirdparties + ~100 invoices + ~10 templates, expect ~150 calls and ~10 s.

Out of scope

• Snapshotting bank statements (Qonto / Wise CSV exports). Different data source — would be a sibling skill (arcodange-bank-snapshot or similar).
• Snapshotting Kubernetes state of the ERP deployment. Sibling skill candidate (arcodange-k8s-snapshot).
• Schema migrations / drift in the Dolibarr DB itself. That requires dolibarr-postgres-readonly or similar; out of scope here.