ALAI Client Invoice Cycle — Runbook

ALAI Client Invoice Cycle — Runbook

Purpose:Version: Actionable1.0 commandCreated: sequence2026-07-28 forOwner: creating,John sending,(AI tracking,Director) and/ collectingAlem aBasic client(CEO) invoice.Source Fullprocess: skillSkill workflow:invoice (~/.claude/skills/invoice/SKILL.md.), Skill financial-overview Audience:Tooling: John (primary)invoice-generator.js, Finverge (accounting/Fiken sync)fiken.js, Alemcontacts.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: Last14 updated:days 2026-07-28.

---

3. The Cycle — Step by Step

Step 1 — Validate the Client

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 them.the client. Never fabricate.invent.
• No email on file →-> ask Alem,Alem. doNever not guess.invent.
• Confirm org number +and address are present (required on the invoice).

Step 2 — Collect Invoiceinvoice Data

data

InteractivelyGather (from Alem or existingcontract context):

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

Step 3 — Create the Invoice

invoice

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

Verify the tool output:

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

Step 4 — CEO Review (mandatory, no exceptions)

Showwith Alem (MANDATORY GATE)

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

Client:

{name}
Client, Amount:Amount, {amount} {currency}
MVAVAT (25%):, {mva}Total, Total: {total} {currency}
Description: {description}Description, Due date: {date}date, Payment terms:terms
{days} days

Wait for explicit "OK" / "SEND". Invoicing is classified NeverHIGH send an invoice without approvalrisk — invoiceno =auto-send.

HIGH-risk draft classification.

Step 5 — Draft,Create Approve,email Send

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 email if no draft was auto-created:MCP:

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

Step 67 — Fiken Syncsync (Norwegian entity accounting)

NODE_PATH=~/system/node_modules node ~/system/tools/fiken.js invoices sync

Run after every new invoice if the client has a Fiken contactcommands configured.available: status, companies, invoices list|show|sync, contacts list|show|sync, balances, transactions list [--days N], reconcile [--dry-run], dashboard [--json].

Step 78 — 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-Remindremind Schedule

/ overdue escalation

TheHandled by the pipeline-watcher daemon runs(auto-remind), thethrottled reminderto cadencesync automatically:with Fiken at most every 6h before evaluating overdue status (MC #106151 — prevents nagging on invoices already paid):

7:Norwegian) 14:notify) :

Day	Action
Day 7	Friendly reminder — (auto-sent, Norwegian
Day 14	Firm reminder — (auto-sent + Slack notify
Day 30+	EscalationEscalated —to an MC task created for Alem

Check status / send manually if needed: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 remind <invoice-id>check-overdue

Step

Manual 8reminder: — Ongoing Tracking

NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js listremind all<invoice-id>

NODE_PATH=~/system/node_modules

node
4. ~/system/tools/Full invoice-generator.js listCommand unpaidReference
NODE_PATH=~/system/node_modules
create node<client> ~/system/tools/invoice-generator.js<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                                         NODE_PATH=~/system/node_modulesFind nodeoverdue ~/system/tools/invoice-generator.jsinvoices, generate reminders
auto-remind [--dry-run]                               Auto-escalation reminder system
dashboard                                             Invoice dashboard
stats                                                 NODE_PATH=~/system/node_modules node ~/system/tools/fiken.js dashboard

For a full financial position (bank balances + outstanding + pipeline forecast), use /financial-overview:

NODE_PATH=~/system/node_modules node ~/system/tools/fiken.js balancesStatistics


5. Hard Rules

VAT 25% MVA on allfor NOK invoices — applied automatically by invoice-generator.js. addsAlways it automatically. Verifyverify the total before sending.total.
CEOAlem approves every invoice — invoice = HIGH risk. Never send without Alem'san explicit "OK".
Client must exist in contacts.db —before noany invoice foris an unregistered contact.created.
Reference is mandatory — every invoice tiesmust link to a contract or PO number.PO.
ALAI branding — PDF always uses the standard ALAI invoice template.
Currency matchesmust match the contract — never mix NOK/EUREUR/other onfor the same client relationship.engagement.
Anti-hallucination — never invent an amount. If Alem hasn't stated a figure, ask.
Due date is realistic — default 14 days; check the contract for custom terms.
Fiken sync — run after every new invoice whereif Fiken is configured for thethat client.entity.


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


7. Related Documents

Skill: invoice (~/.claude/skills/invoice/SKILL.md)
FinancialSkill: financial-overview skill: (~/.claude/skills/financial-overview/SKILL.md)
InvoiceALAI-CLIENT-ONBOARDING.md DB:— contract terms originate here (Phase 4/5)

ALAI-CLIENT-INCIDENT-RESPONSE.md



Document Location: ~/system/databases/invoices.dbALAI/processes/runbooks/ALAI-CLIENT-INVOICE-CYCLE.md
Templates:Access ~/system/templates/invoices/standard-invoice.html
Control: INTERNAL