bukio-cli: Instructions file for Codex

AGENTS.md — bukio-cli Agent Manual

This file is the agent's manual for bukio-cli. Read it before driving the tool. It assumes you have shell access to the machine where bukio-cli is installed and that bukio is on PATH.

Install (no toolchain)

curl -fsSL https://raw.githubusercontent.com/erikvankempen/bukio-cli/main/install.sh | sh
bukio --version

The installer is non-interactive and idempotent: it detects the platform, verifies the download against the release's SHA256SUMS and installs into ~/.local/bin. Use --version v0.18.2 to pin a release, --system for /usr/local/bin. If this machine already has Rust, cargo binstall bukio-cli does the same thing. Update with bukio update (see §3) — never by compiling.

1. House rules (non-negotiable)

1. Dry-run before you mutate. Every mutating command accepts --dry-run. Run it, read the plan, then run without --dry-run.
2. Identify yourself. Every command requires a named actor: --actor '<role>:<name>' or env BUKIO_ACTOR — agent:bartholomeus for the agent, human:erik for the owner. A bare human/agent is rejected (ACTOR_REQUIRED/INVALID_ACTOR); anonymous actors would pollute the audit trail.
3. Parse --json, never scrape text. Every command prints one JSON document with --json. Exit code 0 = success, 1 = failure.
4. Never touch the SQLite file directly. No sqlite3 CLI, no raw SQL. The engine + triggers exist to protect the books. If you need a capability that doesn't exist, say so instead of hacking the DB.
5. Never delete posted entries. Correct mistakes with entry reverse (which posts a contra-entry) and re-book.
6. Verify after every mutation. At minimum: bukio report trial-balance --json → data.balanced must be true (when you've posted anything).
7. Money is integer cents. amount_cents in JSON is the truth. amount strings are for humans. No floats, ever.
8. Archive every source document. When booking an invoice (or any posted document — purchase invoice, credit note, bank proof), copy the original PDF/image/XML to ~/.bukio/invoices/ next to the live DB before finishing, named YYYY-MM-DD_<vendor-slug>_<invoice-number>.<ext> (see 6.17). The books then carry their paper trail.
9. Signing is required once a company enforces it. bukio actor enforce --on makes a valid actor signature mandatory: unsigned or unverifiable commands are refused before anything is written. Never work around an enforced company — not with --dry-run (also refused), not with a different --actor (must be enrolled), not by disabling the gate. Only an enrolled actor can disable enforcement (actor enforce --off is refused for unenrolled/keyless actors) — and it is an audited act: ask first. Consequence accepted by design: if all enrolled keys are lost, the CLI is locked out on that company (recovery = restore a backup, or the owner edits the DB directly).
10. Enrol per company — and enrol before enforcing. An actor's key is enrolled per company DB (bukio actor register runs against the current --db). Register in every company the actor works in; a key valid in one company is not valid in another. First enrolment is operator-gated: under actor enforce on, registering a brand-new actor is refused (ACTOR_KEY_UNKNOWN) — an already-enrolled actor (the operator) must flip enforce --off (itself refused for unenrolled actors) → actor register → enforce --on, each an audited act. Rotation re-enrolment stays possible under enforce (the revoked actor's actor register is exempt — it is the only way back in). If a command is refused with ACTOR_KEY_UNKNOWN/ACTOR_KEY_REVOKED, run bukio actor verify and fix enrolment or rotate (actor keygen --force + actor register).
11. Human keys are passphrase-protected; use sessions. human: keys are encrypted — run bukio actor unlock once per session (default 12 h, --ttl-hours to change) or set BUKIO_SIGNING_PASSPHRASE; actor lock clears the session. Never store a passphrase in a script next to the key; prefer the session for interactive work.
12. Cron/system actors sign from their key file. system:/agent: keys are plain files — a cron job or agent that has the key file signs automatically. Give unattended jobs their own actor (system:backup, system:cron) with its own enrolled key, so the audit trail shows which system acted. --sign-key <path> overrides the key file; the resolution order is --sign-key → session → BUKIO_SIGNING_PASSPHRASE → <config>/keys/<role>-<name>.key.