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 Client reaches out (email, referral, direct) Record: name, company, contact, how they found us Quick qualification check: is budget/scope/timeline realistic? Qualified -> schedule Discovery Call. Not qualified -> polite decline with referral if possible. Output: clients//intake/first-contact.md , lead status set qualified/not qualified Phase 2 — Discovery Discovery call/meeting with client Understand: problem, goals, users, budget, timeline Define project type (web app, mobile app, API, landing page, etc.) and candidate tech stack Write the Project Brief (client info, problem, proposed solution, users, platforms, top 5-10 features, integrations, budget range, timeline, success metrics) Output: clients//intake/discovery-notes.md , clients//intake/project-brief.md Phase 3 — NDA Fill NDA template ( legal/nda-template.md ) with client details Send to client for signature via Documenso (skill: send-for-signing ) Store signed copy Output: clients//legal/nda-signed.md + signed PDF Hard rule: technical details and access credentials are NOT shared before NDA is signed. Phase 4 — Proposal Based on Project Brief, define: scope of work, tech stack decision (with rationale), phases/milestones, timeline, pricing (fixed/hourly/milestone), explicit in-scope vs out-of-scope, assumptions, validity period Review by John, then present to client Output: clients//intake/proposal.md Phase 5 — Contract Fill Contract template ( legal/contract-template.md ): scope from proposal, payment terms, IP ownership, warranties IP ownership must be explicitly decided (client owns all / ALAI retains framework+tooling / license) Send for review and signature Receive first payment if milestone-based Output: clients//legal/contract-signed.md + signed PDF Phase 6 — Project Setup Scaffold client directory: mkdir -p clients//{intake,legal,docs,src,designs,tests,comms/channels/standups,comms/meetings,comms/decisions,deployments} Create project.json (name, type, description, tech_stack, platforms, team, phases, budget, timeline) Kick-off meeting: client + PO + Tech Lead + John — cover scope/milestones, communication channels, access & credentials, sprint cadence, escalation path. Notes -> clients//comms/meetings/kick-off.md PO creates initial backlog from scope, prioritized (MoSCoW or numeric) Output: scaffolded directory, project.json , kick-off notes, initial backlog Phase 7 — Development Start Sprint Planning (first sprint) Tasks assigned to agents per RACI SDLC pipeline ( processes/sdlc/ ) takes over Daily standups logged in comms/channels/standups/ 4. Client Directory Structure Full standard: processes/client-document-structure.md clients// ├── 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 Novi lead -> creates clients//intake/ + notifies BizDev Brief approved -> triggers NDA template fill NDA signed -> triggers Proposal creation Proposal accepted -> triggers Contract fill Contract signed -> triggers Project Setup scaffold 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 Mandatory for every client, no exceptions. NDA before any technical detail is shared. Alem approves every contract and every proposal (Accountable). Pricing decided by Alem — team prepares options, does not set the number. Cloud/tenant resources for this client go in the client's own tenant tree ( ~/clients-external// ), never mixed with another tenant. 8. Related Documents processes/client-onboarding.md — full source process processes/quick-ref/client-onboarding-quickref.md — 1-page version processes/client-document-structure.md processes/sdlc/ — what happens after Phase 7 ALAI-CLIENT-INVOICE-CYCLE.md — billing once client is active ALAI-CLIENT-INCIDENT-RESPONSE.md — support once client is live 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 "" NODE_PATH=~/system/node_modules node ~/system/tools/contacts.js show 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): Client (name/company) Amount (excl. VAT) Currency (NOK, EUR, USD, BAM, RSD — must match the contract currency, never mixed) Description of what is being billed Line items (optional, for itemized invoices) Payment terms (default 14 days, check contract for custom terms) Reference (project, contract, PO number — mandatory) Step 3 — Create the invoice NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js create "" "" 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 NODE_PATH=~/system/node_modules node ~/system/tools/drafts.js send Or directly via MCP: mcp__email__email_send(account: "john", to: "", subject: "Invoice # — ALAI Holding AS", body: "...", attachments: ["~/system/deliverables/invoices/INV-.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 [date] # alias: NODE_PATH=~/system/node_modules node ~/system/tools/invoice-generator.js mark-paid 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 4. Full invoice-generator.js Command Reference create [currency] [description] Create invoice list [unpaid|paid|overdue|all] List invoices show Show details pay [date] Mark as paid (simple) reconcile [date] Mark paid with payment reference mark-paid Alias for reconcile (current date) reconciliation-report Payment reconciliation report pdf Generate PDF send [--to email] Generate email draft (MCP ready) remind 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 VAT 25% for NOK — applied automatically by invoice-generator.js . Always verify the total. Alem approves every invoice — HIGH risk. Never send without an explicit "OK". Client must exist in contacts.db before any invoice is created. Reference is mandatory — every invoice must link to a contract or PO. ALAI branding — PDF always uses the standard ALAI template. Currency must match the contract — never mix NOK/EUR/other for the same client engagement. Anti-hallucination — never invent an amount. If Alem hasn't stated a figure, ask. Due date — default 14 days; check the contract for custom terms. 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 7. Related Documents Skill: invoice ( ~/.claude/skills/invoice/SKILL.md ) Skill: financial-overview ( ~/.claude/skills/financial-overview/SKILL.md ) ALAI-CLIENT-ONBOARDING.md — contract terms originate here (Phase 4/5) ALAI-CLIENT-INCIDENT-RESPONSE.md 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) Acknowledge receipt to the reporter Classify severity using the matrix in Section 2 Assign owner (agent/role per incident type) Create incident record: comms/incidents/INC-YYYY-MM-DD-NNN.md from processes/templates/incident-report.md Notify stakeholders per Escalation Matrix (Section 4) Open Slack thread in #incidents Step 3 — Investigation Reproduce the issue in the affected environment Gather evidence: logs, metrics, screenshots Root cause analysis (5 Whys / Fishbone / Timeline) — mandatory for P1/P2 Assess impact: users, data, services affected Fix plan: immediate mitigation vs. long-term fix Step 4 — Resolution Implement fix (code, config, infra, or process change) Validate: staging for P2-P4, production hotfix + 1h monitoring for P1 Deploy per deployment protocol Monitor metrics/logs/error rates for 1 hour post-deploy Step 5 — Verification Fix deployed to production Smoke tests passing No related errors in the last hour Monitoring shows normal metrics Client confirms resolution (if client-reported) Incident record updated to "Resolved" 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) Scheduled within 2 business days of resolution, conducted within 5 Blameless, fact-based, action-oriented Every post-mortem produces at least one action item, tracked in Mission Control Template and full 10-section structure: see processes/incident-management.md §7.3 Step 8 — Closure Incident resolved and verified Post-mortem completed (P1/P2) Action items created and assigned Documentation/runbooks updated Client notified (final resolution email) Incident record archived to comms/incidents/archive/YYYY/ 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 Primary: John (AI Director) — 24/7 via automated monitoring Human backup: Alem (CEO) — for P1 decisions requiring a human Business hours: Mon-Fri 08:00-18:00 CET; after-hours P1 = John responds immediately + alerts Alem by phone, P2 = John within 1h + email to Alem (reviewed within 4h) Contact priority: Slack #ai-ops -> email alem@alai.no -> phone (P1 only) 7. Tools Tool Purpose Command support-ticket.js Create incident record from client report node ~/system/tools/support-ticket.js create --title "" --severity Mission Control Track incident as task node ~/system/tools/mc.js add " " --priority high Slack Real-time incident channel node ~/system/tools/slack.js send incidents "" HiveMind Log lessons learned node ~/system/agents/hivemind/hivemind.js post john incident "" 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 Mission Control Dashboard: http://localhost:3030 8. Hard Rules Blameless post-mortems — focus on systems/process, never individuals. Every P1/P2 gets a post-mortem within 5 business days, no exceptions. GDPR 72h clock starts at detection , not at confirmation — when in doubt, start the clock. Client communication is never skipped for P1/P2, even if resolution is fast. No incident closes without an incident record in comms/incidents/ . 9. Related Documents processes/incident-management.md — full 13-section governance document (severity rationale, KPIs, RCA appendix, GDPR breach assessment tree, quarterly review process) processes/quick-ref/incident-response-quickref.md — 1-page field version processes/templates/incident-report.md ALAI-CLIENT-ONBOARDING.md ALAI-CLIENT-INVOICE-CYCLE.md Document Location: ~/ALAI/processes/runbooks/ALAI-CLIENT-INCIDENT-RESPONSE.md Access Control: INTERNAL