Client Operations Runbooks

Operational runbooks for client onboarding, invoicing, and incident response

ALAI Client Onboarding — Runbook

ALAI Client Onboarding — Runbook

Version: 1.0 Created: 2026-07-28 Owner: John (AI Director) / Alem Basic (CEO) Source process: processes/client-onboarding.md, processes/quick-ref/client-onboarding-quickref.md Tooling: node ~/system/tools/onboard-client.js, Skill onboard-client

1. Purpose

Every new ALAI client goes through 7 mandatory phases before development starts. No phase is skipped. Each phase has an owner, a required output, and a gate condition that must be true before moving to the next phase.

2. The 7 Phases

Phase 1: First Contact       -> gate: qualified lead
Phase 2: Discovery           -> gate: brief approved by client
Phase 3: NDA                 -> gate: NDA signed
Phase 4: Proposal            -> gate: proposal accepted
Phase 5: Contract            -> gate: contract signed + first payment
Phase 6: Project Setup       -> gate: project scaffolded + kick-off done
Phase 7: Development Start   -> SDLC pipeline takes over (processes/sdlc/)
# Phase Owner Timeline Gate
1 First Contact BizDev Respond within 24h Lead qualified, discovery call booked
2 Discovery BA + PO 1-3 days Project Brief written and approved by client
3 NDA John 1 day NDA signed by both sides
4 Proposal PO + Tech Lead 3-5 days Client accepts proposal in writing
5 Contract John 2-3 days Contract signed both sides + first payment received (if milestone-based)
6 Project Setup John + SM 1 day Project scaffolded, kick-off held, backlog created, all access granted
7 Development Start SM + Tech Lead Ongoing N/A — SDLC and sprint cadence take over

3. Phase Detail

Phase 1 — First Contact

Phase 2 — Discovery

Phase 3 — NDA

Phase 4 — Proposal

Phase 5 — Contract

Phase 6 — Project Setup

Phase 7 — Development Start

4. Client Directory Structure

Full standard: processes/client-document-structure.md

clients/<CLIENT>/
├── intake/
│   ├── first-contact.md
│   ├── discovery-notes.md
│   ├── project-brief.md
│   ├── proposal.md
│   ├── client-materials/        <- everything client provides, with README index
│   └── correspondence/
├── legal/
│   ├── drafts/
│   └── signed/
├── docs/{specs,research}/
├── designs/
├── src/
├── tests/
├── comms/{channels/standups,meetings,decisions}/
├── deployments/
└── project.json

5. RACI

Activity BizDev BA PO Tech Lead SM John Alem
First Contact R I I - - A I
Discovery C R R C - A I
NDA - - - - - R/A I
Proposal - C R R - A A
Contract - - - - - R A
Project Setup - - I C R R/A I
Kick-off - C R R R A I

R = Responsible, A = Accountable, C = Consulted, I = Informed

6. Automation Hooks

  1. Novi lead -> creates clients/<CLIENT>/intake/ + notifies BizDev
  2. Brief approved -> triggers NDA template fill
  3. NDA signed -> triggers Proposal creation
  4. Proposal accepted -> triggers Contract fill
  5. Contract signed -> triggers Project Setup scaffold
  6. Kick-off done -> project-workflow.js init

Guided end-to-end execution: node ~/system/tools/onboard-client.js or Skill onboard-client (7-phase interactive workflow).

7. Hard Rules

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

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>

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:

Step 4 — Review with Alem (MANDATORY GATE)

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

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

NODE_PATH=~/system/node_modules node ~/system/tools/drafts.js list pending

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):

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, anel@wizard.no
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

ALAI Client Incident Response — Runbook

ALAI Client Incident Response — Runbook

Version: 1.0 Created: 2026-07-28 Owner: John (AI Director) / Alem Basic (CEO) Source process: processes/incident-management.md (full spec), processes/quick-ref/incident-response-quickref.md Related: processes/templates/incident-report.md, processes/communication-protocol.md

1. Purpose

Client-facing runbook for handling any incident that affects a client's service: production outages, bugs, security incidents, SLA breaches. This is the condensed operational version — the full governance document (classification rationale, GDPR appendix, KPIs, audit trail) lives in processes/incident-management.md.

2. Severity Matrix

Severity Definition Response Time Resolution Target Notify
P1 CRITICAL Service completely down, active data breach, revenue impact, legal/regulatory violation 15 min 4 hours Alem + Client + Datatilsynet (if GDPR)
P2 HIGH Major feature broken, client blocked, no workaround, security vulnerability 1 hour 8 hours John + Tech Lead + Client
P3 MEDIUM Minor feature broken, workaround exists 4 hours 24 hours John + relevant agent
P4 LOW Cosmetic, no business impact 24 hours 5 days Assigned agent

When in doubt, escalate up. Better to downgrade a P1 to P2 than to underestimate a critical incident.

3. Response Flow

Detection -> Triage & Classify -> Investigation -> Resolution -> Verification -> Communication -> Post-Mortem -> Closure

Step 1 — Detection

Source Action
Automated monitoring (Mission Control, health checks) Auto-alert to John
Client report (email, ticket) Logged via support-ticket.js, escalated by John
Internal discovery (agent/dev) Report to John immediately (Slack #ai-ops)
Third-party/vendor Forward to John + Alem

Step 2 — Triage & Classify (John, within SLA response time above)

  1. Acknowledge receipt to the reporter
  2. Classify severity using the matrix in Section 2
  3. Assign owner (agent/role per incident type)
  4. Create incident record: comms/incidents/INC-YYYY-MM-DD-NNN.md from processes/templates/incident-report.md
  5. Notify stakeholders per Escalation Matrix (Section 4)
  6. Open Slack thread in #incidents

Step 3 — Investigation

Step 4 — Resolution

Step 5 — Verification

Step 6 — Communication cadence

Severity Initial Update Progress Updates Resolution Notice
P1 Within 15 min Every 30 min Immediately + 24h follow-up
P2 Within 1 hour Every 2 hours Within 1h of resolution
P3 Within 4 hours Daily if >24h Next business day OK
P4 N/A unless client-reported N/A Next sprint review

Step 7 — Post-Mortem (mandatory P1/P2, optional P3)

Step 8 — Closure

4. Escalation Matrix

P4: Developer -> Tech Lead (review) -> Archive
P3: Developer -> Tech Lead (notified) -> Archive
P2: Tech Lead (owns) -> John (notified) -> Client notified -> Archive
                                          -> if SLA breach: Alem involved
P1: John coordinates -> Alem notified IMMEDIATELY -> Client notified IMMEDIATELY
                                                    -> Datatilsynet if GDPR breach (72h)

Escalate to Alem when: any P1; P2 affecting a major client or revenue; client relationship risk; legal/regulatory implication (GDPR, lawsuit threat); media/PR risk; financial impact >50,000 NOK; requires external assistance.

Authority When Deadline Contact
Datatilsynet Personal data breach (GDPR Art. 33) 72h from detection postkasse@datatilsynet.no
Client Breach of data processing agreement 24h per DPA Client contact per contract
Politiet (Kripos) Criminal activity Immediately 02800, tips@politiet.no
NSM Critical infrastructure attack Immediately nsm@nsm.no

5. Client Communication Templates

Initial notification (email, within SLA)

Use values from the incident record and the client contract/contact record before sending.

Subject: Action Required or Informational — Service Incident Notification — {{client_name}}

We are writing to inform you of a service incident affecting {{affected_service_or_feature}}.

Incident Summary:
- What: {{impact_what_users_experience}}
- When Detected: {{detected_date_time_with_timezone}}
- Current Status: {{investigating_mitigating_or_resolved}}
- Impact to Your Users: {{specific_user_impact}}

What We Are Doing: {{response_actions_underway}}
Next Steps: {{client_expectation_workaround_next_update_time}}
Estimated Resolution: {{estimated_resolution_or_investigating}}

We will provide updates every {{update_cadence}} until resolved.

Resolution confirmation

Use values from the incident record and production verification evidence before sending.

Subject: RESOLVED: Service Incident — {{client_name}}

Incident Summary:
- Issue: {{issue_summary}}
- Root Cause: {{brief_non_technical_root_cause}}
- Resolution: {{what_was_fixed}}
- Resolved At / Total Duration: {{resolved_timestamp_and_duration}}

Preventive Actions: {{prevention_actions}}
Impact to Your Data: {{data_impact_statement}}

Full template set (internal declared/update/resolved, GDPR Art. 33/34 regulatory notices): processes/incident-management.md §6.

6. On-Call

7. Tools

Tool Purpose Command
support-ticket.js Create incident record from client report node ~/system/tools/support-ticket.js create --title "<incident title>" --severity <P1-P4>
Mission Control Track incident as task node ~/system/tools/mc.js add "<INC-ID> <incident title>" --priority high
Slack Real-time incident channel node ~/system/tools/slack.js send incidents "<incident update>"
HiveMind Log lessons learned node ~/system/agents/hivemind/hivemind.js post john incident "<lesson learned>"
health-check.js System health monitoring node ~/system/tools/health-check.js --quick
auto-fix.js Automated recovery for known issues node ~/system/tools/auto-fix.js <service> <issue>

Mission Control Dashboard: http://localhost:3030

8. Hard Rules

Document Location: ~/ALAI/processes/runbooks/ALAI-CLIENT-INCIDENT-RESPONSE.md Access Control: INTERNAL