Skip to main content

ALAI Client Invoice Cycle — Runbook

ALAI Client Invoice Cycle — Runbook

Version: 1.0 Created: 2026-07-28 Owner: John (AI Director) / Alem Basic (CEO) Source process: Skill invoice (~/.claude/skills/invoice/SKILL.md), Skill financial-overview Tooling: invoice-generator.js, fiken.js, contacts.js, drafts.js, MCP mcp__email__email_send

1. Purpose

Defines how ALAI creates, sends, tracks, and reconciles client invoices — from client validation through payment reconciliation and overdue escalation. This is the ONLY approved path to send an invoice; invoices are never emailed ad hoc.

2. Tooling Map

Purpose Tool
Create/list/show/pay invoices NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js
Client/contact lookup NODE_PATH=~/system/node_modules node ~/system/tools/contacts.js
Email draft queue (approval gate) NODE_PATH=~/system/node_modules node ~/system/tools/drafts.js
Accounting sync (Norway entity) node ~/system/tools/fiken.js
Send invoice email MCP mcp__email__email_send (account: "john")
PDF template ~/system/templates/invoices/standard-invoice.html
Local invoice DB ~/system/databases/invoices.db

Invoice DB fields include: client, amount, currency (NOK/EUR/USD/BAM/RSD), vat_pct, vat_amount, total_amount, description, line_items, status (draft/sent/paid/overdue/cancelled), project_id, company, due_date, paid_at, payment_reference. Default payment terms: 14 days.

3. The Cycle — Step by Step

Step 1 — Validate the client

NODE_PATH=~/system/node_modules node ~/system/tools/contacts.js search "<client>"
NODE_PATH=~/system/node_modules node ~/system/tools/contacts.js show <id>
  • Client not in contacts.db -> ask Alem for details, add the client. Never invent.
  • No email on file -> ask Alem. Never invent.
  • Confirm org number and address are present (required on the invoice).

Step 2 — Collect invoice data

Gather (from Alem or contract context):

  1. Client (name/company)
  2. Amount (excl. VAT)
  3. Currency (NOK, EUR, USD, BAM, RSD — must match the contract currency, never mixed)
  4. Description of what is being billed
  5. Line items (optional, for itemized invoices)
  6. Payment terms (default 14 days, check contract for custom terms)
  7. Reference (project, contract, PO number — mandatory)

Step 3 — Create the invoice

NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js create "<client>" <amount> <currency> "<description>"

Verify the output:

  • Invoice ID assigned
  • VAT (25%) auto-applied for NOK invoices
  • Total = amount + VAT
  • Due date = today + payment terms
  • PDF generated in ~/system/deliverables/invoices/

Step 4 — Review with Alem (MANDATORY GATE)

Present before sending — never sent without explicit sign-off:

  • Client, Amount, VAT (25%), Total, Description, Due date, Payment terms
  • Wait for explicit "OK" / "SEND". Invoicing is classified HIGH risk — no auto-send.

Step 5 — Create email draft (not a direct send)

NODE_PATH=~/system/node_modules node ~/system/tools/drafts.js list pending
  • Invoice email = HIGH risk -> requires manual approval
  • Reminder email = MEDIUM risk -> auto-approve + Slack notify

Step 6 — Send (after Alem approval)

NODE_PATH=~/system/node_modules node ~/system/tools/drafts.js approve <draft-id>
NODE_PATH=~/system/node_modules node ~/system/tools/drafts.js send <draft-id>

Or directly via MCP:

mcp__email__email_send(account: "john", to: "<client-email>",
  subject: "Invoice #<id> — ALAI Holding AS",
  body: "...", attachments: ["~/system/deliverables/invoices/INV-<id>.pdf"])

Step 7 — Fiken sync (Norwegian entity accounting)

node ~/system/tools/fiken.js invoices sync

Fiken commands available: status, companies, invoices list|show|sync, contacts list|show|sync, balances, transactions list [--days N], reconcile [--dry-run], dashboard [--json].

Step 8 — Payment reconciliation

NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js reconcile <invoice-id> <payment-ref> [date]
# alias:
NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js mark-paid <invoice-id> <payment-ref>
NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js reconciliation-report

Automated bank-transaction matching: node ~/system/tools/fiken.js reconcile [--dry-run].

Step 9 — Auto-remind / overdue escalation

Handled by the pipeline-watcher daemon (auto-remind), throttled to sync with Fiken at most every 6h before evaluating overdue status (MC #106151 — prevents nagging on invoices already paid):

  • Day 7: Friendly reminder (auto-sent, Norwegian)
  • Day 14: Firm reminder (auto-sent + Slack notify)
  • Day 30+: Escalated to an MC task for Alem

Check status:

NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js list overdue
NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js check-overdue

Manual reminder: NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js remind <invoice-id>

4. Full invoice-generator.js Command Reference

create <client> <amount> [currency] [description]   Create invoice
list [unpaid|paid|overdue|all]                       List invoices
show <invoice-id>                                    Show details
pay <invoice-id> [date]                              Mark as paid (simple)
reconcile <invoice-id> <payment-ref> [date]           Mark paid with payment reference
mark-paid <invoice-id> <payment-ref>                  Alias for reconcile (current date)
reconciliation-report                                 Payment reconciliation report
pdf <invoice-id>                                      Generate PDF
send <invoice-id> [--to email]                        Generate email draft (MCP ready)
remind <invoice-id>                                   Generate reminder draft (MCP ready)
check-overdue                                         Find overdue invoices, generate reminders
auto-remind [--dry-run]                               Auto-escalation reminder system
dashboard                                             Invoice dashboard
stats                                                 Statistics

5. Hard Rules

  1. VAT 25% for NOK — applied automatically by invoice-generator.js. Always verify the total.
  2. Alem approves every invoice — HIGH risk. Never send without an explicit "OK".
  3. Client must exist in contacts.db before any invoice is created.
  4. Reference is mandatory — every invoice must link to a contract or PO.
  5. ALAI branding — PDF always uses the standard ALAI template.
  6. Currency must match the contract — never mix NOK/EUR/other for the same client engagement.
  7. Anti-hallucination — never invent an amount. If Alem hasn't stated a figure, ask.
  8. Due date — default 14 days; check the contract for custom terms.
  9. Fiken sync — run after every new invoice if Fiken is configured for that entity.

6. Worked Example

Alem: "Fakturiši Wizard 25000 NOK za februar maintenance"

1. contacts.js search "Wizard" -> Wizard NUF, [email protected]
2. invoice-generator.js create "Wizard NUF" 25000 NOK "February 2026 maintenance and support"
3. Output: INV-0005, 25000 + 6250 VAT = 31250 NOK, due date = today+14
4. Present to Alem for review
5. Alem: "OK"
6. drafts.js approve + send
7. fiken.js invoices sync

Document Location: ~/ALAI/processes/runbooks/ALAI-CLIENT-INVOICE-CYCLE.md Access Control: INTERNAL

No comments to display

Back to top