fix: harden agent multi-company workflows

Author: longevityboris

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "invoice-cli"
-version = "0.5.9"
+version = "0.5.10"
 edition = "2021"
 description = "Beautiful invoices from the CLI — international, stateful, agent-friendly"
 license = "MIT"

Cargo.toml

@@ -24,7 +24,9 @@ interface built for agents.
 
 - **Multi-issuer first-class.** Run several companies (SG Pte. Ltd., UK Ltd.,
   US LLC, …) from one binary. Each issuer has its own jurisdiction, tax
-  profile, default template, numbering series, and logo.
+  profile, default template, numbering series, and logo. New issuers default
+  to `{issuer}-{year}-{seq:04}` numbering so invoice IDs stay globally
+  addressable for agents even when several companies share one database.
 - **Per-client defaults.** Pin a default issuer and/or template per client —
   then just `invoice invoices new --client meridian --item design` and the
   right entity + branding lights up automatically.
@@ -43,7 +45,8 @@ interface built for agents.
   the header at the appropriate size for its design language.
 - **Credit notes.** Issue against any existing invoice with `credit-note
   --full` (full reversal) or `--item ...` (specific refund lines). Independent
-  `CN-YYYY-NNNN` numbering series so credit notes don't collide with invoices.
+  `CN-{issuer}-YYYY-NNNN` numbering series so credit notes don't collide with
+  invoices.
 - **Draft-only editing.** Amend a draft's metadata with `invoices edit` or
   its line items with `invoices items add|remove|edit`. Once issued, invoices
   are immutable — the correct path for corrections is a credit note, which
@@ -115,15 +118,15 @@ invoice products add design \
 invoice invoices new --client meridian --item design --due 30d
 
 # 5. Render + open
-invoice invoices render 2026-0001 --open
+invoice invoices render acme-2026-0001 --open
 
 # 6. Later: mark paid, clone for next month
-invoice invoices mark 2026-0001 paid
-invoice invoices duplicate 2026-0001
+invoice invoices mark acme-2026-0001 paid
+invoice invoices duplicate acme-2026-0001
 
 # 7. Need a refund? Credit note against the original. Positive refund
 # specs are stored as credits automatically:
-invoice invoices credit-note 2026-0001 --item "Refund:1:500" --notes "Goodwill credit"
+invoice invoices credit-note acme-2026-0001 --item "Refund:1:500" --notes "Goodwill credit"
 
 # 8. Month-end accountant handoff
 invoice invoices export --from 2026-01-01 --to 2026-03-31 --format csv --out q1.csv
@@ -151,7 +154,7 @@ invoice invoices export --from 2026-01-01 --to 2026-03-31 --format csv --out q1.
 | `invoices export --from X --to Y --format csv\|json` | Accountant handoff |
 | `invoices delete <number> [--force]` | Delete an invoice (`--force` for non-draft) |
 | `template list\|preview <name>` | Inspect available templates |
-| `doctor` | Diagnose typst install, DB, templates |
+| `doctor` | Diagnose typst install, DB, templates, default issuer, numbering |
 | `agent-info` | Full JSON capability manifest |
 | `skill install` | Install embedded Claude/Codex/Gemini skill |
 | `update [--check]` | Self-update via brew or cargo |
@@ -199,6 +202,8 @@ contract:
 
 - Every command emits a `{version, status, data|error}` envelope when piped.
 - `invoice agent-info` returns a full capability + exit-code manifest.
+- `invoice doctor --json` reports setup, default issuer validity, and risky
+  multi-company numbering formats.
 - `invoice skill install` drops a ready-to-use skill file into
   `~/.claude/skills/invoice-cli/SKILL.md` (and the Codex/Gemini equivalents).
 
@@ -209,6 +214,11 @@ USER:  "Bill Meridian for last month's design work"
 AGENT: invoice invoices duplicate $(invoice invoices list --json | jq -r '.data[0].number')
 ```
 
+Agents should use invoice numbers returned by JSON responses, not predict the
+next sequence. The CLI keeps numbers globally unique; if legacy issuers share a
+plain `{year}-{seq:04}` format, generation auto-prefixes the issuer slug on
+collision and `doctor` warns so you can clean up the formats.
+
 ## Architecture
 
 - **Rust** binary via `cargo` / single-binary distribution.

README.md

@@ -104,6 +104,10 @@ pub enum IssuerCmd {
         /// etc.
         #[arg(long)]
         notes: Option<String>,
+        /// Invoice number format. Tokens: {issuer}, {year}, {seq}, {seq:04}.
+        /// Default includes {issuer} so multiple companies cannot collide.
+        #[arg(long)]
+        number_format: Option<String>,
     },
     /// Edit an existing issuer — pass only the fields you want to change
     Edit {
@@ -142,6 +146,8 @@ pub enum IssuerCmd {
         currency: Option<String>,
         #[arg(long)]
         symbol: Option<String>,
+        /// Invoice number format. Tokens: {issuer}, {year}, {seq}, {seq:04}.
+        /// Use a unique prefix per issuer for globally addressable invoice ids.
         #[arg(long)]
         number_format: Option<String>,
         #[arg(long)]

src/cli.rs

@@ -26,8 +26,8 @@ pub fn run(_ctx: Ctx) -> Result<()> {
     // Built outside the json! macro to avoid hitting the proc-macro recursion
     // limit as the command surface grows.
     let commands_list: &[(&str, &str)] = &[
-        ("issuer add <slug> --name X --jurisdiction sg|uk|us|eu --address ... [--logo PATH]", "Register an issuer (billing entity). --logo points to a PNG/SVG/JPG rendered in template header"),
-        ("issuer edit <slug> [--name ... --template ... --jurisdiction ... --logo PATH etc]", "Update any subset of an issuer's fields (incl. logo path)"),
+        ("issuer add <slug> --name X --jurisdiction sg|uk|us|eu --address ... [--logo PATH --number-format F]", "Register an issuer (billing entity). New issuers default to {issuer}-{year}-{seq:04} so invoice numbers are globally addressable"),
+        ("issuer edit <slug> [--name ... --template ... --jurisdiction ... --number-format ... --logo PATH etc]", "Update any subset of an issuer's fields (incl. logo path and numbering format)"),
         ("issuer set-template <slug> <template>", "Shorthand: change an issuer's default template"),
         ("issuer list | ls", "List issuers"),
         ("issuer show <slug> | get", "Show issuer details"),
@@ -101,7 +101,50 @@ pub fn run(_ctx: Ctx) -> Result<()> {
         "database": database,
         "templates": ["helvetica-nera", "tiefletter-gold", "monoline", "vienna", "boutique"],
         "tax_profiles": profiles,
-        "item_spec": "product-slug[:qty]  OR  description:qty:price[:rate]"
+        "item_spec": "product-slug[:qty]  OR  description:qty:price[:rate]",
+        "config_keys": {
+            "default_issuer": "Issuer slug used by invoices new when --as is omitted and the client has no default issuer. `invoice config set default_issuer unset` clears it.",
+            "self_update": "Reserved shared setting for updater behavior across the suite."
+        },
+        "first_run": [
+            "invoice doctor --json",
+            "invoice issuer add <slug> --name <display-name> --jurisdiction sg|uk|us|eu|custom --address \"line1\\nline2\"",
+            "invoice config set default_issuer <issuer-slug>",
+            "invoice clients add <slug> --name <client-name> --address \"line1\\nline2\" --default-issuer <issuer-slug>",
+            "invoice invoices new --client <client-slug> --item \"Description:1:100:20\""
+        ],
+        "examples": [
+            {
+                "goal": "Create an invoice using client/default issuer routing",
+                "command": "invoice invoices new --client meridian --item \"Consulting:1:1200:20\" --json"
+            },
+            {
+                "goal": "Create an invoice for a specific company",
+                "command": "invoice invoices new --as paperfoot --client meridian --item design:1 --json"
+            },
+            {
+                "goal": "Render an invoice PDF",
+                "command": "invoice invoices render paperfoot-2026-0001 --json"
+            },
+            {
+                "goal": "Issue a full credit note",
+                "command": "invoice invoices credit-note paperfoot-2026-0001 --full --json"
+            }
+        ],
+        "multi_company_model": {
+            "issuer": "The company/person billing as. Each issuer owns tax profile, logo, bank details, default notes/output dir, and its own sequence counter.",
+            "client": "The customer. A client may pin default_issuer and default_template.",
+            "invoice_numbering": "Invoice numbers are globally addressable by the CLI. New issuers default to {issuer}-{year}-{seq:04}; legacy colliding formats are auto-prefixed with the issuer slug on collision.",
+            "recommended_default": "Set config.default_issuer for single-company workflows; use client.default_issuer or explicit --as for multi-company workflows."
+        },
+        "guardrails": [
+            "Run doctor before first use and after changing config.",
+            "Prefer --json for agents; stdout is data and stderr is diagnostics.",
+            "Use globally unique issuer number formats, ideally {issuer}-{year}-{seq:04}.",
+            "Do not delete issued invoices; mark void or create a credit note.",
+            "Use invoice numbers returned by JSON responses rather than guessing the next sequence.",
+            "Pin client default issuers when the same customer is always billed by the same company."
+        ]
     });
 
     print_raw(&manifest);

src/commands/agent_info.rs

@@ -16,6 +16,12 @@ pub fn run(cmd: ConfigCmd, ctx: Ctx) -> Result<()> {
             Ok(())
         }
         ConfigCmd::Set { key, value } => {
+            let remove_key = matches!(
+                value.to_ascii_lowercase().as_str(),
+                "unset" | "none" | "null" | ""
+            );
+            validate_config_value(&key, &value, remove_key)?;
+
             // Minimal implementation: set-and-save via toml::Value merge.
             let path = config::config_path()?;
             let existing = if path.exists() {
@@ -26,21 +32,43 @@ pub fn run(cmd: ConfigCmd, ctx: Ctx) -> Result<()> {
             let mut doc: toml::Value =
                 toml::from_str(&existing).unwrap_or(toml::Value::Table(Default::default()));
             if let toml::Value::Table(ref mut t) = doc {
-                t.insert(key.clone(), parse_value(&value));
+                if remove_key {
+                    t.remove(&key);
+                } else {
+                    t.insert(key.clone(), parse_value(&value));
+                }
             } else {
                 return Err(AppError::Config("config root is not a table".into()));
             }
             std::fs::write(&path, toml::to_string_pretty(&doc).unwrap())?;
             print_success(
                 ctx,
-                &serde_json::json!({"key": key, "value": value}),
-                |_| println!("set {} = {}", key, value),
+                &serde_json::json!({"key": key, "value": if remove_key { serde_json::Value::Null } else { serde_json::Value::String(value.clone()) }}),
+                |_| {
+                    if remove_key {
+                        println!("unset {key}");
+                    } else {
+                        println!("set {key} = {value}");
+                    }
+                },
             );
             Ok(())
         }
     }
 }
 
+fn validate_config_value(key: &str, value: &str, remove_key: bool) -> Result<()> {
+    if key == "default_issuer" && !remove_key {
+        let conn = crate::db::open()?;
+        crate::db::issuer_by_slug(&conn, value).map_err(|_| {
+            AppError::InvalidInput(format!(
+                "unknown issuer '{value}' for config.default_issuer. Add it first or run `invoice issuer list`."
+            ))
+        })?;
+    }
+    Ok(())
+}
+
 fn parse_value(v: &str) -> toml::Value {
     if v == "true" {
         toml::Value::Boolean(true)

src/commands/config.rs

@@ -70,13 +70,16 @@ pub fn run(ctx: Ctx) -> Result<()> {
         message: format!("{} available: {}", templates.len(), templates.join(", ")),
     });
 
-    // db
+    // db + suite-level invariants
     match crate::db::open() {
-        Ok(_) => checks.push(Check {
-            name: "database".into(),
-            status: "pass",
-            message: format!("{} ok", config::db_path()?.display()),
-        }),
+        Ok(conn) => {
+            checks.push(Check {
+                name: "database".into(),
+                status: "pass",
+                message: format!("{} ok", config::db_path()?.display()),
+            });
+            add_suite_checks(&mut checks, &conn)?;
+        }
         Err(e) => checks.push(Check {
             name: "database".into(),
             status: "fail",
@@ -113,3 +116,82 @@ pub fn run(ctx: Ctx) -> Result<()> {
     }
     Ok(())
 }
+
+fn add_suite_checks(checks: &mut Vec<Check>, conn: &rusqlite::Connection) -> Result<()> {
+    let issuers = crate::db::issuer_list(conn)?;
+    if issuers.is_empty() {
+        checks.push(Check {
+            name: "issuers".into(),
+            status: "warn",
+            message: "no issuers configured. First run: invoice issuer add <slug> --name ... --address ...".into(),
+        });
+    } else {
+        checks.push(Check {
+            name: "issuers".into(),
+            status: "pass",
+            message: format!("{} configured", issuers.len()),
+        });
+    }
+
+    let cfg = config::load()?;
+    match cfg.default_issuer.as_deref() {
+        Some(slug) => match crate::db::issuer_by_slug(conn, slug) {
+            Ok(_) => checks.push(Check {
+                name: "default-issuer".into(),
+                status: "pass",
+                message: format!("config.default_issuer = {slug}"),
+            }),
+            Err(_) => checks.push(Check {
+                name: "default-issuer".into(),
+                status: "fail",
+                message: format!(
+                    "config.default_issuer points to missing issuer '{slug}'. Run: invoice config set default_issuer unset"
+                ),
+            }),
+        },
+        None if issuers.is_empty() => checks.push(Check {
+            name: "default-issuer".into(),
+            status: "warn",
+            message: "not set yet because no issuers exist".into(),
+        }),
+        None => checks.push(Check {
+            name: "default-issuer".into(),
+            status: "warn",
+            message: "not set. Agents must pass --as or use clients with default issuers.".into(),
+        }),
+    }
+
+    if issuers.len() > 1 {
+        use std::collections::BTreeMap;
+        let mut by_format: BTreeMap<&str, Vec<&str>> = BTreeMap::new();
+        for issuer in &issuers {
+            by_format
+                .entry(issuer.number_format.as_str())
+                .or_default()
+                .push(issuer.slug.as_str());
+        }
+        let risky: Vec<String> = by_format
+            .into_iter()
+            .filter(|(format, slugs)| slugs.len() > 1 && !format.contains("{issuer}"))
+            .map(|(format, slugs)| format!("{} share '{}'", slugs.join(", "), format))
+            .collect();
+        if risky.is_empty() {
+            checks.push(Check {
+                name: "numbering".into(),
+                status: "pass",
+                message: "multi-company number formats are distinct or include {issuer}".into(),
+            });
+        } else {
+            checks.push(Check {
+                name: "numbering".into(),
+                status: "warn",
+                message: format!(
+                    "{}. Invoice numbers are globally addressable; use --number-format '{{issuer}}-{{year}}-{{seq:04}}' for each issuer.",
+                    risky.join("; ")
+                ),
+            });
+        }
+    }
+
+    Ok(())
+}

src/commands/doctor.rs

@@ -24,6 +24,7 @@ pub fn run(cmd: IssuerCmd, ctx: Ctx) -> Result<()> {
             logo,
             output_dir,
             notes,
+            number_format,
         } => {
             let jur = Jurisdiction::from_str(&jurisdiction).ok_or_else(|| {
                 AppError::InvalidInput(format!(
@@ -52,7 +53,7 @@ pub fn run(cmd: IssuerCmd, ctx: Ctx) -> Result<()> {
                 default_template: template,
                 currency: Some(profile.currency.to_string()),
                 symbol: Some(profile.symbol.to_string()),
-                number_format: "{year}-{seq:04}".into(),
+                number_format: number_format.unwrap_or_else(|| "{issuer}-{year}-{seq:04}".into()),
                 logo_path: logo,
                 default_output_dir: output_dir,
                 default_notes: notes,

src/commands/issuers.rs

@@ -24,9 +24,9 @@ invoice clients add meridian --name "Meridian & Co." --country US --address "...
     --default-issuer acme --default-template boutique
 invoice products add design --description "Design engagement" --unit project --price 8400 --currency SGD --tax-rate 9
 invoice invoices new --client meridian --item design --due 30d   # no --as needed: uses client default
-invoice invoices render 2026-0001 --open                          # uses client.default_template
-invoice invoices mark 2026-0001 paid                              # auto-stamps paid_at
-invoice invoices duplicate 2026-0001                              # clone for next month's billing
+invoice invoices render acme-2026-0001 --open                     # uses client.default_template
+invoice invoices mark acme-2026-0001 paid                         # auto-stamps paid_at
+invoice invoices duplicate acme-2026-0001                         # clone for next month's billing
 ```
 
 ### Editing existing records
@@ -52,9 +52,9 @@ invoice issuer edit acme --logo ~/Pictures/acme.png
 DRAFT invoices are mutable; once `issued`/`paid`/`void` they're immutable — use a credit note.
 
 ```
-invoice invoices edit 2026-0001 --notes "Net 14 — early-payment 2% discount"
-invoice invoices items add 2026-0001 "Extra fee:1:500"
-invoice invoices credit-note 2026-0001 --item "Refund:1:500" --notes "Goodwill credit"
+invoice invoices edit acme-2026-0001 --notes "Net 14 — early-payment 2% discount"
+invoice invoices items add acme-2026-0001 "Extra fee:1:500"
+invoice invoices credit-note acme-2026-0001 --item "Refund:1:500" --notes "Goodwill credit"
 ```
 
 ### Aging & export
@@ -75,10 +75,12 @@ invoice invoices new --client meridian --item design --discount-rate 10
 ### Tips
 
 - Run `invoice agent-info` for the full JSON capability manifest.
-- Run `invoice doctor` to verify typst is installed & DB is ready.
+- Run `invoice doctor --json` to verify typst, DB, default issuer, and multi-company numbering.
 - Item spec supports `product-slug[:qty]` OR `description:qty:price[:rate]`.
 - Template resolution at render: `--template` flag > client.default_template > issuer.default_template > `vienna`.
 - `--as` picks the issuer; omit it when the client has `default_issuer` pinned or `config.default_issuer` is set.
+- New issuers default to `{issuer}-{year}-{seq:04}` so invoice numbers are globally addressable; use `issuer edit --number-format` for per-company custom prefixes.
+- Use invoice numbers returned by JSON responses instead of predicting the next sequence.
 - `mark issued` / `mark paid` auto-stamp `issued_at` / `paid_at` (first transition only).
 - `invoices list` shows totals per invoice (computed with `rust_decimal`).
 - Every tax value is computed with `rust_decimal` — no float rounding.