leedab 0.5.3 → 0.6.1

package/wiki/README.md

@@ -0,0 +1,27 @@
+# LeedAB OS — wiki
+
+Cross-customer accumulated wisdom that ships with the OS. Read by agents at runtime via the `read_use_case_wiki` tool family.
+
+## Layout
+
+- `customer-use-cases/<industry>.md` — per-industry briefing read by Champion + Solutions when grounding work in a customer's vertical.
+- `agent-design-patterns/` *(reserved)* — when an agent design pattern stabilises, mirror it from the LeedAB Brain so the OS can ship without the Brain at hand.
+
+## Where the canonical content lives
+
+The `LeedAB Brain/Wiki/` vault is the **working canonical source**. Mina + Muiez accumulate it there as a regular doc surface (with frontmatter, with backlinks, with weekly review). The OS-shipped fallback in this folder is a SHIPPABLE SNAPSHOT — what runtime code reads when the Brain isn't accessible (e.g. on Vercel deploys, in customer appliances).
+
+To override at runtime and read directly from the Brain in dev:
+
+```
+LEEDAB_WIKI_ROOT=/path/to/LeedAB\ Brain/Wiki npm run dev
+```
+
+When the Brain content drifts ahead of the OS-shipped snapshot, sync it down via the periodic snapshot job *(planned — not built yet)*. For now, treat divergence as expected and refresh manually before a release.
+
+## Editing rules
+
+- **Joint authority** — Mina + Muiez both edit. Substantive changes warrant a Telegram heads-up so the other isn't surprised.
+- **No customer names** in the public-facing OS-shipped snapshot. Customer specifics belong in `01_Customers/<Co>/` in the Brain or in the per-customer brain. Keep these files industry-shaped.
+- **Slugs are kebab-case** (`professional-services`, not `Professional Services` or `prof_services`). Filenames must match `^[a-z0-9](?:[a-z0-9-]{0,40}[a-z0-9])?$` — the runtime reader rejects anything outside that.
+- **Body shape** — see `customer-use-cases/_template.md` for the convention agents expect to find.

package/wiki/customer-use-cases/README.md

@@ -0,0 +1,26 @@
+# Customer use-case wiki
+
+One file per industry. Read by Champion (when grounding the Champion's coaching in their customer's vertical) and Solutions (when the prospect-build agent is generating a manifest for a new prospect in this vertical).
+
+## Filename rule
+
+`<industry-slug>.md` where the slug is lowercase alphanumeric + hyphens, 1-42 chars. Runtime regex: `^[a-z0-9](?:[a-z0-9-]{0,40}[a-z0-9])?$`. Filenames that don't match are silently invisible — the reader rejects them.
+
+## Body shape
+
+Every entry should have at least these sections, in order:
+
+1. **Vertical fingerprint** — one paragraph: who works in this vertical, what their day looks like, what they're stressed about.
+2. **Common workflows** — 5–10 bullet workflows agents should expect to be asked to handle. Each in customer's vocabulary, not LeedAB's.
+3. **Tone notes** — how the customer speaks: terse / formal / warm / blue-collar / brand-driven / etc. Affects every reply the COO orchestrator sends.
+4. **Default agent subset** — which 5–7 of the 31 LeedAB agents map to this vertical's pain. Used by Solutions when defaulting a manifest.
+5. **Known failure modes** — patterns that have burned us before (a workflow that looks easy but is sensitive, an integration that misbehaves, a tone choice that backfired).
+6. **LeedAB customers in this vertical** *(internal-only — strip before shipping public)* — for Mina + Muiez context. Not loaded into agent context.
+
+See `_template.md` for the boilerplate.
+
+## Editing
+
+Adding a new industry: copy `_template.md`, rename, fill in. Bump the matching default subset in Solutions if the agent set should change (`apps/console/lib/solutions/parse-brief.ts` may carry hard-coded defaults — check before assuming the agent reads from here).
+
+Removing an industry that has live customers: don't. Mark it `## Status: deprecated` at the top and keep the page.

package/wiki/customer-use-cases/_template.md

@@ -0,0 +1,42 @@
+# {{Industry name}}
+
+## Vertical fingerprint
+
+Who works in this vertical. A typical day. What they're stressed about. One paragraph, 4-6 sentences.
+
+## Common workflows
+
+5-10 workflows agents should expect to be asked to run. Use the customer's vocabulary, not LeedAB internal terms.
+
+- Workflow 1
+- Workflow 2
+- ...
+
+## Tone notes
+
+How customers in this vertical speak. Affects every reply the COO sends.
+
+- Default register: formal / casual / blue-collar / warm-brand / terse-direct
+- Common words to mirror: ...
+- Words to avoid: ...
+- Sign-off convention: ...
+
+## Default agent subset
+
+Which 5-7 of the 31 LeedAB agents map to this vertical's pain. Used by Solutions when defaulting a manifest for a new prospect.
+
+- agent-id-1
+- agent-id-2
+- ...
+
+## Known failure modes
+
+Patterns that have burned us before. Be specific — name the workflow + what broke.
+
+- ...
+
+## LeedAB customers in this vertical *(internal-only)*
+
+Names + slugs of LeedAB customers in this vertical. Not loaded into agent context.
+
+- Customer name (`slug`)

package/wiki/customer-use-cases/agencies.md

@@ -0,0 +1,47 @@
+# Agencies
+
+## Vertical fingerprint
+
+Agencies sell their team's time and expertise — creative agencies, marketing agencies, dev shops, design studios, PR firms. The decision-maker is usually a founder-principal or operations lead balancing this week's deliverables against next quarter's pipeline against the team's utilisation rate. They think in billable hours, utilisation %, gross margin per project, scope creep, retainer renewal, and the difference between a good client and a profitable one (often not the same). The stack is project-management (Notion / Asana / Monday / ClickUp) + time-tracking (Harvest / Toggl) + invoicing (Xero / QuickBooks / Stripe) + storage (Google Drive / Dropbox).
+
+## Common workflows
+
+- Pipeline review — what's in / next month / probability-weighted; flag drop-offs and follow up before they go cold
+- Project profitability check — actual hours vs. quoted hours, in-progress and post-mortem; flag scope-creep risks early
+- Client-status digest — weekly update per client: what shipped, what's next, what blocks; sent to the client + saved in vault
+- Retainer renewal coordination — 60 days out, draft renewal terms, surface usage trends, offer contract adjustments
+- Pitch / proposal drafting — RFP response, scope + timeline + pricing — drafted with margin model behind it
+- Resource allocation — who's on which project this week, surface over-utilisation (>100%) and under-utilisation (<70%)
+- Subcontractor management — when work goes to freelancers, track scope + deadlines + invoice reconciliation
+- Case-study / portfolio update — when a project ships, capture metrics + permission to publish + draft case study
+- Receivables chase — overdue invoices, escalation cadence, surface frozen accounts before they become legal
+- Internal training / knowledge transfer — when a senior leaves a project, ensure the playbook is documented before they roll off
+
+## Tone notes
+
+- Default register: professional-warm. Agencies sell trust; the tone is closer to a strategic adviser than a vendor.
+- Common words to mirror: scope, retainer, deliverable, milestone, turnaround, brief, kickoff, pitch, RFP, billable, utilisation
+- Words to avoid: corporate boilerplate ("at your earliest convenience"), generic SaaS-isms, casual tone with new clients (earn it first)
+- Sign-off convention: first name + role + agency (Mina, Strategy Lead — [Agency]). Senior-on-senior is common.
+
+## Default agent subset
+
+- sales
+- cx
+- finance
+- marketing
+- people *(utilisation + freelancer coordination)*
+- legal *(MSAs, IP, NDAs)*
+
+## Known failure modes
+
+- **Quoting fixed-price work without a margin model.** Agencies that price by gut and not by hours-cost get eroded over time.
+- **Letting scope creep land silently.** "While you're at it..." adds 30% to the project for free unless documented + change-ordered.
+- **Confusing client-friendliness with client-overcommitment.** Saying yes to every request kills team morale and project margins.
+- **Auto-sending status updates that paper over delays.** Clients appreciate a candid "we hit a snag, here's the recovery plan" more than a glossy "all on track" until the deadline misses.
+- **Receivables chases that read aggressive too early.** First nudge: gentle reminder. Second: with copy of invoice + new due date. Third: pause new work + escalation. Don't skip steps.
+- **Subcontractor invoices reconciled separately from project P&L.** Means project profitability is never truly known until the freelancer invoices land.
+
+## LeedAB customers in this vertical *(internal-only)*
+
+- (none yet — first prospect should populate this section)

package/wiki/customer-use-cases/ecommerce.md

@@ -0,0 +1,47 @@
+# E-commerce
+
+## Vertical fingerprint
+
+E-commerce operators run direct-to-consumer or B2B online stores where every aspect of the customer relationship — discovery, decision, purchase, support, retention — happens digitally. The decision-maker is often a founder-operator or a small ops team running multiple channels: their own Shopify / WooCommerce / Magento store, plus marketplaces (Amazon, eBay, Etsy, Catch), plus social commerce (Instagram, TikTok). They think in conversion rate, average order value (AOV), customer acquisition cost (CAC), lifetime value (LTV), return rate, ROAS (return on ad spend), and cart-abandonment rate. The stack is heavy: Shopify + Klaviyo + ShipStation + Gorgias + Meta Ads + Google Ads + ReCharge + ParcelPanel and a dozen apps wired to each.
+
+## Common workflows
+
+- Order issue triage — late delivery, damaged, wrong item, fraud-flag — decide refund / replace / dispute, draft customer reply
+- Cart-abandonment recovery — sequence triggered, A/B testable, declines with each subsequent send to avoid spam reports
+- Inventory reorder — sales velocity vs. stock + lead time = reorder trigger per SKU; alert on stockout-imminent SKUs
+- Negative-review response — public reply that makes the customer feel heard while protecting the brand from look-bad-on-camera attacks
+- Returns processing — RMA generated, return label, refund or store-credit decision, restocking fee policy enforced
+- Marketing-campaign coordination — promo codes synced across Shopify + ad platforms + email; promo landing page tested
+- Compliance updates — privacy policy, T&Cs, refund policy — version-controlled, customer-comms when material changes
+- Cohort + LTV reporting — by acquisition channel, by first-product, by AOV band; surface declining segments early
+- Influencer / affiliate seeding — outreach + product-send + tracking + commission reconciliation
+- Supplier-side issues — drop-shipper out of stock, price hike, replacement supplier qualification
+
+## Tone notes
+
+- Default register: brand-led — match what the customer's website + Instagram already say. E-commerce is brand-heavy; the COO can't sound generic.
+- Common words to mirror: AOV, CAC, LTV, ROAS, CR (conversion rate), checkout, cart, restock, dropship, fulfillment, SKU, variant
+- Words to avoid: "patron" (too formal), generic SaaS-speak ("solution", "platform"), corporate-apology template-isms
+- Sign-off convention: brand-first then person ("The [Brand] Team — Mia"). Solo-founder brands often sign off as the founder ("Mia, founder of [Brand]"); preserve that voice.
+
+## Default agent subset
+
+- cx
+- marketing
+- email
+- campaigns
+- ops
+- finance
+
+## Known failure modes
+
+- **Auto-issuing refunds for fraud-flagged orders.** Chargeback-vs-refund is a strategic decision; agents draft the path, humans authorise.
+- **Sending generic cart-abandonment emails to high-value customers.** The 4th repeat customer isn't a stranger; their flow should differ.
+- **Reorder triggers ignoring promo cycles.** A flash sale triples sales velocity for 48h; reorder triggers based on raw velocity over-commit.
+- **Public review replies that argue with the customer.** Even when the customer is wrong, a defensive public reply hurts the brand more than the original complaint.
+- **Cross-channel inventory drift.** Showing "in stock" on Shopify while Amazon already sold the last unit = oversold. Inventory truth-source must be one system.
+- **Forgetting to update tax / shipping rates by region.** Especially when expanding to a new state or country.
+
+## LeedAB customers in this vertical *(internal-only)*
+
+- (none yet — first prospect should populate this section)

package/wiki/customer-use-cases/food-service.md

@@ -0,0 +1,45 @@
+# Food service
+
+## Vertical fingerprint
+
+Food-service operators run cafés, restaurants, ghost kitchens, food trucks, and catering businesses where the daily rhythm is dictated by service times, perishable inventory, and hourly staff availability. The decision-maker is usually an owner-operator or hospitality manager balancing tonight's service against this week's roster and next month's food-cost percentage. They think in covers (customers served), turn time, COGS%, mise en place, prep lists, par stock, 86 (out-of-stock items), gross profit margin per dish, and labour percentage. Many run on a POS (Square / Lightspeed / Toast) plus a roster app (Deputy / Tanda) plus WhatsApp groups for shift comms.
+
+## Common workflows
+
+- Daily prep-list generation — count covers booked, prior-week shape, current par stock; produce a prep list for the kitchen
+- Roster published vs. demand mismatch — too few staff for booked covers, or too many on a quiet day, surface for adjustment
+- 86 management — when a dish runs out mid-service, customer notification + POS update + supplier reorder if recurring
+- Supplier ordering — perishable goods reordered on rolling cycles per supplier (greengrocer daily, butcher 2x/week, dry goods weekly)
+- Customer-review handler — Google / TripAdvisor / Yelp review comes in, draft tone-matched response within 24h
+- Roster cover request — staff calls in sick, find replacement from approved-roster list, escalate to manager if no cover within 30min
+- Promo / event push — Friday-night promo, ticketed event, set-menu — coordinate marketing + ops + supplier orders
+- Food-cost percentage drift — weekly check, surface dishes whose ingredient cost has crept up enough to hurt margin
+- Compliance log — food-safety temperature checks, allergen registers, cleaning rosters; daily attestations
+
+## Tone notes
+
+- Default register: warm-but-direct. Hospitality is a relationship business; the tone of customer comms is closer to "thank you for the heads up, we'll fix it" than to a corporate apology template.
+- Common words to mirror: covers, service, turn, prep, mise, 86, par, COGS, FOH (front-of-house), BOH (back-of-house), brigade, runner, bartender
+- Words to avoid: "patron" (too formal for most casual venues), "experience" (overused), "curated" (overused), "concept"
+- Sign-off convention: first name + role ("Lina, Manager — Surry Hills"). Owner sign-offs feel personal and disarm complaints; use them for any 3-star-and-below review.
+
+## Default agent subset
+
+- ops
+- cx
+- marketing
+- procurement
+- people
+- finance
+
+## Known failure modes
+
+- **Auto-replying to negative reviews without context.** A 1-star review for a 90-minute wait might be Friday-night reality, or might be a kitchen meltdown. Surface to a human; never auto-publish a review reply.
+- **Reordering perishables without checking near-end-of-life stock.** Perishable inventory turnover is the #1 driver of food cost. Always check what's ageing in the walk-in before suggesting a reorder.
+- **Generic promo broadcasts.** Loyalty customers get different messaging than first-timers. Segment basics matter even for a small operator.
+- **Auto-acting on compliance incidents.** Allergen mistakes, food-safety breaches, suspected food-poisoning — never auto-action; route to the manager + the operator's compliance procedure.
+- **Roster decisions made without checking award terms.** Australian hospitality has hard rules around penalty rates, breaks, casual loading. Don't let an automation cross legal lines on labour.
+
+## LeedAB customers in this vertical *(internal-only)*
+
+- (none yet — first prospect should populate this section)

package/wiki/customer-use-cases/healthcare.md

@@ -0,0 +1,49 @@
+# Healthcare
+
+## Vertical fingerprint
+
+Healthcare operators in the SMB segment run clinics — GP practices, allied health (physio, psych, dental, optometry), specialist private practices, telehealth services. The decision-maker is usually a practice manager, owner-clinician, or operations lead balancing today's appointment book against this month's revenue against the quarter's compliance + accreditation cycle. They think in appointment fill rate, no-show rate, time-of-billing (Medicare item codes / private health rebates), recall lists, MBS (Medicare Benefits Schedule) item interpretation, and the rhythm of the practice's clinical specialties. The stack is practice-management software (Best Practice / Medical Director / Cliniko / HotDoc) + accounting (Xero) + telephony.
+
+> ⚠️ **Strict guardrails apply.** Patient information is high-sensitivity by law (Privacy Act, My Health Records, state-level health-records legislation). Cross-customer + cross-patient isolation is non-negotiable. Agents NEVER store PHI in shared infra; never include identifiable information in cross-system messages; never auto-act on clinical content.
+
+## Common workflows
+
+- Appointment confirmation + reminders — multi-channel cadence (SMS / email), reschedule path, no-show follow-up
+- New-patient intake — forms collected pre-visit, flagged red-pin items reviewed by clinician before consult
+- Recall-list management — patients due for review (e.g. annual diabetic check, dental hygiene, vaccination booster) — outreach sequence
+- Billing + claims — Medicare item codes confirmed, private health rebates calculated, gap-payment communicated, claim submitted same-day
+- Telehealth coordination — consent, technology check, fallback to phone, post-consult notes filed
+- Clinician roster — leave coordination, clinical-supervision sign-offs, locum bookings
+- Complaints + feedback handling — every complaint logged in incident register; serious adverse events escalated per practice policy
+- Compliance + accreditation — RACGP / AGPAL / specialty-college standards tracked, evidence collected, gap-fill plans actioned
+- Supplier ordering — clinical consumables, scrip pads, vaccines (cold chain), PPE — reorder cycles per supplier
+- After-hours triage — practice closed, urgent-care line vs. ED routing per protocol, message taken for clinician callback
+
+## Tone notes
+
+- Default register: professional, calm, plain-language. Healthcare communication is held to a higher standard than retail or hospitality. Avoid medical jargon when speaking to patients; preserve precision when speaking to clinicians.
+- Common words to mirror: practice, consult, recall, rebate, gap-fee, MBS, telehealth, clinician (umbrella term covering doctor / physio / psych / etc), referral, item number
+- Words to avoid: marketing fluff ("personalised", "world-class"), informal slang to patients, anything that could read as a clinical recommendation when written by a non-clinician
+- Sign-off convention: practice name + role + first name ("Eastside Clinic — Reception, Sarah"). Clinicians are signed off by full name + qualifications when external-facing.
+
+## Default agent subset
+
+- cx
+- ops
+- compliance *(critical — accreditation + privacy + clinical governance)*
+- finance *(billing complexity is high)*
+- people
+- legal
+
+## Known failure modes
+
+- **Treating patient comms like a marketing channel.** Reminders ≠ promo. The line is bright; one promotional message in a clinical reminder sequence triggers privacy complaints.
+- **Auto-replying to clinical questions.** Anything that could be construed as medical advice must come from (or be reviewed by) a clinician. The agent's role is logistical: reschedule, intake, billing — not clinical.
+- **PHI in audit logs / shared analytics.** Patient data isolation has to extend through every observability surface. No identifiable PHI in audit logs even for debugging.
+- **Cross-patient leakage in family-billing scenarios.** Family members on the same account ≠ same patient. Reminders + clinical follow-ups must be addressed to the correct patient.
+- **Auto-acting on consent-revocation.** When a patient withdraws consent (data, recalls, marketing, telehealth), the cancellation propagates manually — never auto-flow to the next system without a human verifying the chain completed.
+- **Failed-attempt outbound calls treated as "delivered".** A reminder call hitting voicemail is not a successful reminder. Track outcome explicitly.
+
+## LeedAB customers in this vertical *(internal-only)*
+
+- (none yet — privacy + compliance gating means we onboard this vertical only after the customer-vault provisioning + audit-log hardening land. First prospect should populate this section.)

package/wiki/customer-use-cases/hospitality.md

@@ -0,0 +1,47 @@
+# Hospitality
+
+## Vertical fingerprint
+
+Hospitality (cafes, restaurants, fitness studios, salons, small venues) runs on bookings, repeat customers, and tight margins. The decision-maker is the owner-operator or venue manager juggling a roster, a supplier list, customer-facing comms across multiple channels, and the constant pressure of front-of-house being the experience. Their stress: a no-show on a 12-top, a supplier delivering the wrong order on a Monday morning, an Instagram review that needs a response within an hour. Many run on a POS (Square, Lightspeed, Mindbody) + a booking system + WhatsApp groups for the team.
+
+## Common workflows
+
+- Booking confirmation + reminder — booking made online, confirmation sent, day-before reminder sent, no-show flagged
+- Booking change / cancel — customer changes party size or time, table reassignment, waitlist update
+- Supplier order check — confirm tomorrow's delivery is locked in, surface mismatches before opening
+- Customer enquiry triage — questions across IG DM, Google, email, booking platform messages: "do you do gluten-free", "can we bring a cake", "is the room air-conditioned"
+- Review response — Google + IG reviews, especially negatives, drafted in venue voice for owner approval
+- Roster management — staff sick, last-minute swap needed, shift broadcast to team WhatsApp
+- New menu / class launch — comms across IG, email, website, on-table card
+- Loyalty / repeat outreach — birthdays, anniversaries (for restaurants), milestone classes (for studios)
+- Wedding / event enquiry — qualifier questions, package send, viewing scheduled, follow-up cadence
+- Inventory + waste check — end-of-week count, slow-mover surface, ordering adjustment
+
+## Tone notes
+
+- Default register: warm, brand-driven, hospitable. Each venue has a voice that's part of the experience — read existing posts + emails before drafting anything.
+- Common words to mirror: guests (not "customers"), cover (table seat), service (lunch service / dinner service), spot (booking), arvo (Australian afternoon)
+- Words to avoid: transactional words ("inventory turn", "throughput"). Customer-facing comms shouldn't sound operational.
+- Sign-off convention: first name + venue, often warm. Sometimes a signature line that's part of the brand (e.g. "see you Tuesday — Sunset team").
+
+## Default agent subset
+
+- cx
+- marketing
+- sales *(events / functions enquiries)*
+- ops
+- content *(IG / email copy)*
+- finance *(payroll + supplier invoice — usually outsourced to a bookkeeper anyway)*
+
+## Known failure modes
+
+- **Auto-replying to negative reviews.** Owner needs to see + approve every negative-review response. Auto-sent generic replies make a bad situation worse.
+- **Confirming bookings that conflict.** A booking system sync gap that lets the agent confirm a 7pm 6-top when the room is already booked = a guest-facing humiliation. Always check live availability before confirming.
+- **Generic event/wedding replies.** This is a high-stakes enquiry. AI-default replies feel like the venue doesn't care. Always surface to the owner with a 30-second priming brief.
+- **Tone drift across channels.** IG DM voice ≠ email voice ≠ Google review voice. Don't average; match each channel.
+- **Promising menu / availability info that isn't accurate.** "Yes we do gluten-free pasta" when the kitchen ran out yesterday = customer arrives angry. Surface menu enquiries to the kitchen check, don't auto-confirm from a stale FAQ.
+
+## LeedAB customers in this vertical *(internal-only)*
+
+- Sunset Cafe (`sunset-cafe`)
+- Element Pilates (`element-pilates`)

package/wiki/customer-use-cases/logistics.md

@@ -0,0 +1,58 @@
+# Logistics
+
+## Vertical fingerprint
+
+Logistics operators run dispatch desks: drivers in the field, freight moving across multiple touch points, customer expectations measured in minutes. The decision-maker is usually an ops manager or owner-operator who is balancing today's exceptions against this week's profitability. They think in routes, manifests, PUDs (pickups), PODs (proof of delivery), exception types (refused / damaged / weather), and customer SLAs. Many are running on a thin layer of spreadsheets + a TMS + WhatsApp groups.
+
+## Common workflows
+
+- Dispatch exception triage — driver reports a refused delivery, ops needs the customer notified + the freight rerouted within 30 min
+- POD chase-up — freight delivered but POD not received from the driver, ops needs an automated nudge before the customer calls
+- Late-job customer notification — customer expects a window, the window is going to slip, get a tone-matched message out before they ask
+- Manifest reconciliation — end-of-day check that all jobs have a status, exceptions have a paper trail, billable accessorials are captured
+- Driver onboarding paperwork — license check, induction, vehicle assignment, first-week cadence
+- Customer onboarding — credit check, account setup, first-job walkthrough
+- Subbie management — subcontractor invoice reconciliation, on-time-delivery tracking, retention
+- Weekly profitability review — by-customer / by-route margin, surface the loss-making lanes
+- Compliance log — chain-of-responsibility, fatigue, vehicle inspections, audit-ready
+
+## Tone notes
+
+- Default register: terse, action-oriented, blue-collar. Skip pleasantries; lead with the action.
+- Common words to mirror: dispatch, run, leg, lane, drop, PUD, POD, manifest, exception, accessorial, SLA, reefer, B-double, semi
+- Words to avoid: corporate-speak ("synergise", "leverage", "circle back"). Owner-operators have a low tolerance for it.
+- Sign-off convention: name + role on the truck (e.g. "Jase, dispatch"). Customers expect to know who they're talking to.
+
+## Default agent subset
+
+- ops
+- cx
+- finance
+- sales
+- compliance
+- marketing *(growth — typically smaller pull than the others)*
+
+## Known failure modes
+
+- **Driver names leaking to the wrong customer.** A dispatch reply that mentions another customer's driver by name is a contract-violation in most ops shops. Cross-customer isolation matters here more than usual.
+- **Tone too polished.** Customer-side comms that read like a SaaS marketing email get ignored. Match the WhatsApp/text register the ops team already uses.
+- **Auto-acting on exceptions.** Refused deliveries, damaged freight, customer disputes — never auto-action. Surface to the human; let them choose.
+- **Compliance-adjacent automation.** Fatigue declarations, chain-of-responsibility logs, vehicle inspection records — these are legally load-bearing. Agents read; humans write.
+
+## LeedAB customers in this vertical *(internal-only)*
+
+- Tarheel Logistics (`tarheel`) — first paying, ~200 deliveries/day, NSW+interstate, SAP+Cario stack
+- Acme Logistics (`acme-logistics`) — demo only
+
+## Tarheel-shaped logistics (specific to first paying customer)
+
+When grounding for Tarheel specifically, layer these on top of the generic logistics pattern above. (Per-agent system-prompt overrides for `ops` and `procurement` carry the same content into every Tarheel model call via `clients/tarheel/manifest.json`.)
+
+- **Stack:** SAP order management + Cario TMS. Dispatch ID = SAP order ID — always confirm match before acting on an exception. Never login to a third system, even if asked.
+- **Volume:** ~200 deliveries/day average, scaling into Q3 2026. Plan for 2-3x throughput in scaffolds + smoke fixtures.
+- **5am Sydney handoff to NZ team.** Cross-shift dispatch decisions get flagged before delegation. Operationally load-bearing.
+- **Coles is a high-friction account.** Deductions go through legal as formal disputes — never reply via informal email. Dispute drafting is procurement + cx pair work.
+- **Suppliers:** SAP-driven; never bypass the PO system.
+- **Primary contact:** Operations Manager. Telegram window 06:00-12:00 Sydney. Voice only if urgent.
+- **Escalation threshold:** anything > $5k impact, anything customer-visible, anything touching a contractual SLA — escalate to Mina before action.
+- **Tone:** terse, blue-collar, action-first. Sign-offs include name + role ("Jase, dispatch"). Skip corporate-speak; the ops team has a low tolerance for it.

package/wiki/customer-use-cases/manufacturing.md

@@ -0,0 +1,45 @@
+# Manufacturing
+
+## Vertical fingerprint
+
+Manufacturing operators run shop floors that turn raw material into shipped product against contractually-binding SLAs. The decision-maker is usually a plant manager, owner-operator, or operations director balancing today's production schedule against this week's input costs and next month's order book. They think in BOMs (bills of materials), takt time, OEE (overall equipment effectiveness), WIP, scrap rates, lead times, and reorder points. Many run on ERP (SAP / NetSuite / Microsoft Dynamics) plus a thin layer of spreadsheets and shop-floor whiteboards. Compliance overhead is heavy — ISO 9001, food-safety, electrical certifications, depending on what they make.
+
+## Common workflows
+
+- Production schedule rebalancing — a machine goes down or a key input is delayed, the schedule needs to be re-shuffled and customers notified
+- Raw-material reorder triggers — stock hits reorder point, PO drafted to approved supplier, lead time and price re-confirmed
+- Quality-incident triage — a batch fails QC, contain it, root-cause it, decide rework vs. scrap, notify affected customers
+- Supplier scorecard updates — on-time delivery, defect rate, price drift tracked per supplier across quarters
+- Customer-order acknowledgement — RFQ in, capacity check, lead time quote, contract terms confirmed
+- Maintenance scheduling — preventive vs. reactive, critical-path equipment first, planned during low-utilisation windows
+- Compliance audit prep — pull batch records, calibration logs, training records on demand for ISO / food-safety / electrical audits
+- Safety-incident reporting — near-miss, lost-time injury, plant-side investigation + regulatory notification
+- Cost-of-goods-sold drift — material price changes flow through to product margin; flag products dropping below target margin
+
+## Tone notes
+
+- Default register: terse, technical, no-nonsense. Manufacturing operators have low tolerance for marketing fluff or generic SaaS-speak.
+- Common words to mirror: takt, WIP, scrap, rework, OEE, lot, batch, BOM, RFQ, PO, MRO (maintenance/repair/operations), changeover, downtime, throughput
+- Words to avoid: "synergise", "leverage", "optimise" (without specifics), "world-class", "industry-leading"
+- Sign-off convention: name + role + plant ("Sarah Chen, Production Manager — Plant 2"). When ambiguous, name the shift.
+
+## Default agent subset
+
+- ops
+- procurement
+- finance
+- compliance
+- cx
+- people *(shift-cover and safety-related)*
+
+## Known failure modes
+
+- **Treating QC failures as a customer-service problem.** A failed batch is a quality + supply-chain problem first, customer comms second. Get the root cause + containment plan before drafting customer notifications.
+- **Auto-reordering raw materials based on stale data.** Reorder triggers should always re-confirm current price + lead time before generating the PO. Supplier prices drift; lead times stretch.
+- **Auto-acting on compliance-related incidents.** Anything touching safety, environmental, or regulatory reporting requires a human signoff path — agents draft, humans submit.
+- **Customer notifications that read like marketing copy.** Manufacturing buyers want delivery dates and root causes, not apologies and value props.
+- **Cross-customer leakage of lead-time data.** A competitor with insider lead-time visibility can underbid; lead times are commercially sensitive.
+
+## LeedAB customers in this vertical *(internal-only)*
+
+- (none yet — first prospect should populate this section)

package/wiki/customer-use-cases/professional.md

@@ -0,0 +1,48 @@
+# Professional services
+
+## Vertical fingerprint
+
+Professional services firms (advisory, legal, accounting, consulting boutiques, financial planning) run on relationships, billable hours / project fees, and the trust that comes from precision. The decision-maker is usually a partner or principal who is balancing client work, business development, and team management — rarely with a dedicated ops person until headcount passes ~10. Their stress: client matters that need attention now while the partner is in another meeting, a compliance / conflict-check that has to be flawless, an invoice that has to read right because the client will scrutinise every line.
+
+## Common workflows
+
+- Client matter intake — prospect calls, conflict check, engagement letter, retainer / scope clarification
+- Conflict check — across the firm's existing client list before opening a new matter
+- Engagement letter generation — populated from intake, sent for client signature
+- Status update to client — weekly / fortnightly digest of work in progress, no surprises
+- Document version control — drafts circulated, comments returned, version history maintained
+- Compliance + AML / KYC checks — particularly for legal + financial advisory
+- Invoice generation — line-item time + disbursements, partner review, send + payment-link
+- New-client onboarding — welcome pack, portal access, expectation setting
+- Partner referral handling — inbound referral, qualification, response within 24h to maintain the network
+- Quarterly business review with key clients — agenda set, materials prepared, partner brief
+- Monthly / quarterly newsletter or thought-leadership piece — drafted from partner's POV, not generic
+
+## Tone notes
+
+- Default register: precise, formal, low-flourish. Every word in a client-facing reply may be referenced later in a meeting or audit; nothing decorative.
+- Common words to mirror: matter (legal), engagement (advisory), retainer, statement of work, scope, disbursement, in-scope / out-of-scope, billable, conflict-check, privilege
+- Words to avoid: casual / breezy phrasing, exclamation marks, emojis. Even with warm clients, the written register stays formal — that's the brand.
+- Sign-off convention: full name + title (Partner / Principal / Director). Often a formatted signature block.
+
+## Default agent subset
+
+- cx
+- legal *(when the firm is legal-adjacent — otherwise compliance)*
+- compliance
+- finance
+- sales *(BD-driven)*
+- content *(thought-leadership + newsletters)*
+
+## Known failure modes
+
+- **Auto-acting on a privileged matter.** Anything related to client privilege / advice / conflict — agent reads, surfaces, never auto-acts. The cost of an inadvertent waiver is catastrophic.
+- **Generic newsletters under a partner's name.** Partners' personal brand IS the BD pipeline. AI-default thought leadership in a partner's voice erodes their brand within a few editions. Always surface a draft + treat as a first cut.
+- **Conflict-check shortcuts.** Even when the prospect's name doesn't obviously match an existing client, run the check against parent / subsidiary relationships. Missed conflicts are a regulatory issue.
+- **Invoice line items without context.** A line that says "Research, 3.2h" gets queried. Same line as "Research re section 17 amendment, 3.2h" gets paid. Push for descriptive narration even when the time-entry was terse.
+- **Confidentiality drift in summary docs.** Status digests that name specific other clients or matters by name = breach of confidentiality. Always pseudonymise + double-check before sending.
+
+## LeedAB customers in this vertical *(internal-only)*
+
+- Howard Partners (`howard-partners`)
+- Ledbetter Advisory (`ledbetter-advisory`)

package/wiki/customer-use-cases/retail.md

@@ -0,0 +1,44 @@
+# Retail
+
+## Vertical fingerprint
+
+SMB retailers run on inventory turn, customer touchpoints, and seasonal cycles. The decision-maker is the owner or store manager juggling stock, staff rosters, supplier follow-ups, and customer service replies — usually in fragments between serving the floor. Their stress is not knowing the margin on a SKU until the end-of-month count, and customer enquiries piling up on Instagram + email + the website form simultaneously. Many run a POS (Square, Lightspeed, Shopify) + Xero + a Google Sheet that nobody else understands.
+
+## Common workflows
+
+- Stock-out alert — a fast-moving SKU dips below reorder threshold, supplier needs a PO before the next sales day
+- Supplier follow-up — chase a backordered shipment, log the delay, communicate to customers waiting on it
+- Customer enquiry triage — questions arrive across Instagram DM, Facebook, email, website form. Categorise (sales / returns / wholesale / press), draft response, surface for owner approval
+- Returns + refund processing — eligibility check against policy, restocking decision, customer comms
+- Wholesale enquiry — qualify the buyer, send linesheet + terms, log to the pipeline
+- New-product launch comms — Instagram caption, email blast, website blurb, all from one product brief
+- Seasonal stock planning — pre-order quantities for next season based on this season's sell-through
+- End-of-month reconciliation — POS vs accounting, slow-mover write-down decision, margin by category
+- Loyalty / repeat-customer outreach — birthdays, post-purchase thank-yous, lapsed-customer winback
+
+## Tone notes
+
+- Default register: brand-driven, warm. Each retailer has a voice — read the existing IG captions and emails before drafting anything.
+- Common words to mirror: pieces (not "units"), arrived / dropped / restocked, made-to-order, limited run
+- Words to avoid: "synergy", "pipeline", "vertical" — corporate-speak feels off in retail. Also avoid generic AI-flavoured phrases ("we're thrilled", "we'd love to") that pattern-match as automated.
+- Sign-off convention: first-name only, owner or named team member. Often warm (e.g. "Bondi Bloom team x").
+
+## Default agent subset
+
+- cx
+- marketing
+- sales
+- ops
+- finance
+- content *(captions / email copy)*
+
+## Known failure modes
+
+- **Auto-replying without owner approval on returns / refunds.** Even when policy is clear, "can I get a refund?" is a relationship moment for SMB retail. Surface, don't auto-send.
+- **Generic captions.** Brand voice in retail is the moat. AI-default captions get noticed within 2-3 posts and erode trust. Either match the voice precisely or surface for human edit.
+- **Pricing changes via auto-flow.** Even seasonal markdowns should pass through the owner — the moment something gets discounted erroneously is a customer-anger moment.
+- **Cross-channel duplicate replies.** Customer asks the same question on IG + email; agent replies on both with slightly different wording. Looks chaotic. De-dupe by customer identity, not by channel.
+
+## LeedAB customers in this vertical *(internal-only)*
+
+- Bondi Bloom (`bondi-bloom`)

package/wiki/customer-use-cases/trades.md

@@ -0,0 +1,47 @@
+# Trades
+
+## Vertical fingerprint
+
+Trades businesses (roofing, building, plumbing, electrical, carpentry) run on jobs, quotes, and weather. The decision-maker is usually the owner-operator who is also on the tools two days a week, with a junior office person handling phones + invoicing + scheduling. Their stress: the difference between a quoted price and the actual cost on a job, the chase-up cycle for unpaid invoices, supplier price changes that surprise them mid-job, and customer expectations that drift after the quote is signed.
+
+## Common workflows
+
+- Quote-to-invoice flow — quote sent, accepted, scheduled, materials ordered, job done, invoice issued, payment chased
+- Variation orders — customer changes scope mid-job, owner needs a tone-matched written variation in their inbox before they hear "but I thought it was included" later
+- Weather rescheduling — rain forecast, three jobs need to slide, customers need notification before they're left waiting
+- Materials follow-up — supplier hasn't confirmed the order, the trades team is heading to site tomorrow morning
+- Subcontractor coordination — get the sparkie / plumber on site at the right time without too much idle
+- Invoice chase-up — overdue invoices, escalating template (gentle / firm / final), pre-collections
+- Site safety induction — new worker on a commercial site, paperwork, SWMS, induction sign-off
+- Photo / progress update to customer — owners want photos at milestones; trades team takes them on phone but never sends
+- Pre-defects walkthrough — final inspection before handover, defect list captured, owner signed off
+- Lead qualification — phone enquiry, address + scope + timeframe + budget capture, surface to owner for callback decision
+
+## Tone notes
+
+- Default register: practical, no-frills, slightly informal. Australian trades + suburban customers — the customer doesn't want a long email, they want "sorted, here's what's next."
+- Common words to mirror: sparkie, chippy, brickie, ute, site, quote, var (variation), invoice, defect, snag list, RCD, SWMS, induct
+- Words to avoid: corporate jargon, customer-service-y framing ("we appreciate your patience"). Lead with the action, not the politeness.
+- Sign-off convention: first name + business name. Brief.
+
+## Default agent subset
+
+- ops
+- cx
+- finance
+- sales
+- compliance *(SWMS + induction + defect tracking)*
+- marketing *(usually word-of-mouth-driven, not heavy)*
+
+## Known failure modes
+
+- **Variation orders sent without numbers.** A customer-facing message that talks about "additional work" without the dollar figure is a fight waiting to happen. Always include the price + the line item.
+- **Tone too polished.** Trades customers (residential + commercial) read polished AI-flavoured replies as evasive. Be direct.
+- **Promising weather-dependent dates.** Schedules slip when it rains. Always frame as "weather permitting" + auto-shift if rain forecast >60% probability.
+- **Sending invoices without a payment link.** Trades invoices that say "please remit to BSB ..." get paid 5-10 days later than ones with a one-tap link.
+- **Compliance-adjacent automation.** SWMS forms, defect lists, induction sign-offs — these are legally load-bearing on commercial sites. Agents read + remind; humans sign.
+
+## LeedAB customers in this vertical *(internal-only)*
+
+- Coastal Built (`coastal-built`)
+- Hawkesbury Roofing (`hawkesbury-roofing`)