# Handoff: Business & Strategy Context (beyond the foundation docs)

**Written:** 2026-07-12, by Claude Fable 5, at James's request, anticipating loss of Fable access.
**Audience:** James + future AI sessions (Opus 4.8 / Sonnet).
**Relationship to other docs:** `docs/foundation/00|01|02` remain the source of truth for the original thesis and kernel design. This file records everything decided, learned, or strategized **after** those docs were written — do not repeat their content back to James; build on it.

---

## 1. The 2026-07-12 pivot (supersedes the roadmap sequencing in thesis §5)

The end goal is unchanged: a private factory that mints AI-enabled SMB products per industry, operated solo + domain partner, bootstrapped cash-flow business.

What changed: James's access to the frontier model (Fable) is ending; Opus 4.8/Sonnet remain. He is therefore **deliberately re-accepting the "factory-first" risk** his own thesis warned about (§5, §8), because the scarce resource shifted from *market validation* to *frontier design capability*. The operating principle for all remaining frontier-model time, and the standing prioritization rule after it:

> **Spend the strongest available model on decisions that are expensive to reverse and designs that are hard to originate. Everything stampable from a pattern is deferred to cheaper models with a written work order.**

Concrete implications, agreed with James:

- **Mechanical work is deferred**, explicitly including: rate limiting, Docker/Coolify deployment, LINE/WhatsApp adapters, widget embedding, i18n passes, pgvector activation, and modules beyond the exemplars. These are Opus/Sonnet work orders, not frontier work.
- **"Horizontal" progress means decided + specified + de-risked** — NOT half-implemented. Breadth lives in specs and playbooks; code depth is reserved for contracts whose mistakes poison everything downstream (module composition, factory codegen).
- **Don't wait for the first cash-cow vertical (D13)** to make horizontal progress — but implementation of polish still waits for a real customer to pull it (see §5 below).

## 2. Decision: the factory is a CODEGEN console, not a GUI/runtime platform (major, settled)

James originally floated an ideal outcome of a "powerful and pretty GUI-based factory" — pick modules from a menu, instantly get software for any business type. **He withdrew the GUI request on 2026-07-12 and settled on codegen.** Record this as the ruling interpretation of the factory vision:

- The factory's compose step **generates typed code**: an `apps/<client>` package assembled from the module catalog + a vertical manifest + a theme. Products remain ordinary vibe-codeable codebases. This preserves D8 (no runtime metadata engine) — the trap to permanently avoid is drifting toward Odoo/low-code, which would destroy the vibe-coding edge that justifies the whole business.
- A GUI *console* may exist someday, but it is a **front-end to the code generator**, never a runtime configuration engine. Runtime configurability stays thin: labels, prompts, grounding, custom fields — exactly what `VerticalManifest` already does.
- First implementation form: a **CLI composer** (`create-app` style script) — a GUI adds nothing until there are many modules to pick from.

## 3. The module catalog ontology (the "menu" of the factory)

The long-term vision "any business I want should have modules ready" translates to roughly **15 capability modules** that cover ~90% of SMB software (excluding extreme specialties like SCADA/core banking, which are out of scope by James's own statement). The kernel already covers identity/tenancy, AI substrate, channels, jobs/events, audit. The catalog, with dependency edges:

| # | Module | Scope (one line) | Depends on |
|---|--------|------------------|-----------|
| 1 | **contacts-crm** | Party enrichment: pipeline/lead states, notes, segments, tags | kernel only |
| 2 | **scheduling** | Bookings/appointments lifecycle (EXISTS as v0: `scheduled-interactions`) | contacts (soft) |
| 3 | **catalog** | Products/services/price lists (the thing quotes & bookings reference) | kernel only |
| 4 | **sales-documents** | Quote → order → invoice lifecycle, approval workflow, PDF/send | catalog, contacts |
| 5 | **payments** | Receipts/payment records; provider seam (PromptPay, Stripe, cash log) | sales-documents |
| 6 | **inventory-lite** | Stock levels, adjustments, low-stock alerts | catalog |
| 7 | **messaging-campaigns** | Broadcasts, follow-up sequences, drip over channel adapters | contacts |
| 8 | **tasks-workflow** | Internal assignments, checklists, due dates | kernel only |
| 9 | **staff-rota** | Shifts, working hours, assignment eligibility, commissions | kernel only |
| 10 | **forms-intake** | Custom data capture forms feeding Records | kernel only |
| 11 | **documents-files** | File/attachment management; e-sign later | kernel only |
| 12 | **reporting-copilot** | Cross-module dashboards + AI natural-language Q&A over tenant data (reference Flow B step 3) | reads all |
| 13 | **loyalty-membership** | Punch cards, packages/credits, membership tiers | contacts, payments |
| 14 | **expenses-lite** | Simple expense/purchase logging | kernel only |
| 15 | **reviews-feedback** | Post-service review requests, NPS, testimonial collection | messaging, scheduling |

Rules of thumb for the catalog: each module = one coherent capability an SMB owner would name; dependencies must stay a DAG; the kernel's `Party` primitive is the single shared "customer" — modules extend it, never fork it. A vertical (spa, tutoring, HVAC…) = a subset of modules + one manifest.

**Chosen exemplar for module #2 (recommended, pending James's final confirmation): `sales-documents` (quotes → invoices).** Rationale: it is reference Flow B from the spec (the half of the kernel Flow A didn't validate), exercises Money/approvals/attachments, and composes naturally with scheduling ("invoice this booking") — the best single test of cross-module composition.

## 4. Unit economics (measured live, 2026-07-11)

- A real customer chat exchange costs ~**1.3¢ per customer message** on `claude-opus-4-8` ($5/$25 per MTok; measured: 4 messages = 7,362 in / 573 out tokens ≈ $0.05). Haiku 4.5 would be ~5× cheaper via one env var (`KERNEL_MODEL_DEFAULT`).
- At ~500 customer messages/month per business, AI COGS ≈ **$3–7/month per tenant**. Any plausible subscription (thesis leaning: setup fee + monthly retainer, likely $30–150/mo range for SEA SMB) has enormous gross margin headroom. Per-tenant metering already exists (`ai_usage` table, `purpose`-labeled), so COGS per customer is queryable at any time — use it when pricing.
- Many tenants share one VPS + one Postgres with RLS isolation → infra COGS per tenant is near zero at early scale.

## 5. Gap analysis: current build → first paying B2C operator (from the 2026-07-11 assessment)

What exists is genuinely sellable in demo form: *"An AI receptionist that answers only from your business info, takes booking requests 24/7, gives you a back office, and reminds your customers automatically — re-brandable to a new industry in an afternoon."* The proven demo arc (wellness ↔ tutoring skins, the bot refusing a Sunday booking because grounding says closed) is the wow moment for domain partners.

Gaps, in recommended order (all are Opus-executable work orders):

1. ~~**Chat endpoint hardening**~~ — ✅ DONE 2026-07-14 (spec §9.27, built by an Opus pilot session): rate limit per conversation AND per IP + per-tenant daily AI token budget + per-call clamps. A public URL is no longer blocked on this.
2. **VPS deploy** (Docker + Coolify + worker process) — ~1 day. Blocks everything customer-facing.
3. **Conversations inbox + human takeover** (operator sees chats, pauses bot per conversation, replies manually) — ~2 days. Table stakes for a real operator; biggest missing feature.
4. **Operator notifications** (event-bus subscriber → email/LINE ping on new booking) — ~0.5 day.
5. **Embeddable chat widget** (script tag → floating bubble on the client's own site, themed from manifest) — 2–3 days.
6. **LINE adapter** — 1–2 days (LINE developer account is easy; SEA customers live on LINE). WhatsApp is later (Meta verification takes weeks; or Twilio).
7. **Availability/calendar** — deliberately NOT urgent: the current "request → operator confirms" model matches how SEA SMBs already operate over LINE. Build only when a customer demands it.
8. **Self-serve grounding/content editing in admin** — optional under the partner-led model (James is the integrator); reduces his support load later.

**Sequencing philosophy (James agreed):** do the two hygiene items whenever convenient; let the **first real customer pull items 3–8** in whatever order sells. Do not polish speculatively.

## 6. The "three frontends" framing (for any pretty-UI work)

1. **Customer chat widget** — highest visibility; where design effort earns money (end customers of paying operators see it).
2. **Operator back office** — functional scaffold exists; the single highest-value polish for SEA SMB owners is **mobile-first** (they run their business from a phone) + a "today" dashboard.
3. **Mini public page per business** (services + prices + chat/book button) — NOT in the original plan but cheap on this kernel and very sellable: "you get a web presence *and* an AI receptionist" beats a widget-only pitch.

All three are UI-only work — the kernel needs no changes for any of them.

## 7. Open decisions — ANSWERED 2026-07-12 (James chose all three recommendations)

1. **Frontier-time allocation → depth + breadth split.** Composition contracts + one exemplar in code; the rest of the catalog as spec sheets (`docs/handoff/modules/`). DONE.
2. **Exemplar module → `sales-documents`.** Built, composed with scheduling via the `bookingInvoicingBridge`, proven live (spec §9.18–9.20). DONE.
3. **Design-system investment → tokens + one surface.** Manifest `branding.theme` → CSS vars → Tailwind utilities; customer chat rebuilt as the reference surface (welcome card + manifest-driven suggestion chips); both vertical skins verified visually. DONE.

## 8. Standing strategic cautions (Fable's judgment, recorded)

- The single most dangerous drift is **runtime-configurability creep** (custom fields growing relations, manifests growing behavior, a "settings engine"). Every time it appears, re-read D8. The factory's moat is codegen speed, not configurability.
- The second danger is **building modules nobody pulls**. The catalog (§3) is a map, not a to-do list. Specs for all; code only when a demo or customer needs it.
- Competing on features against big platforms is losing; the moat remains segment + locale + partner distribution (D3/D4). Nothing in the pivot changed that.
- The **demo is the sales asset**: keep `apps/demo` always working end-to-end. Any refactor that breaks the demo arc costs real sales capability.
- Economics leaning remains setup-fee + monthly recurring (thesis §7); per-tenant `ai_usage` data should inform the floor price.

## 9. Internet-business expansion (DECIDED 2026-07-17, James)

The factory's scope explicitly widens: it serves **internet businesses** (marketplaces, SaaS, content platforms) alongside the offline-SMB products, from the same kernel and codegen. The fence was never in the kernel — it was in the module catalog and the frontends. Established with James:

- **The socket-and-plug principle** (his approval, recorded verbatim in spec §9.28): user authentication providers and payment gateways are permanently **per-business manual work** — every builder has their own auth preference (e.g. Clerk) and every region its own gateway (Omise vs Stripe). The kernel therefore owns the *internal identity model* and the *money facts* as thin contracts (sockets); each generated business writes small provider adapters (plugs). We touch these concerns exactly once, at the contract, never at the provider.
- **Validation exemplar: a Cameo-style marketplace MVP** (James's long-backburnered SEA Cameo-clone idea, used here as the test) — mock payments with real 75/25 fee facts, seeded talent accounts, tokenized guest links for buyers, S3-compatible video upload/playback. Scope + phases in spec §9.28; the phase structure guarantees stopping early still retains the full enhanced factory.
- **What this adds to the catalog:** identity socket + public-surface contract (kernel, spec §9.29/§9.30), amended `payments` + `documents-files` (spec §9.31/§9.32), new modules `marketplace-listings` + `marketplace-orders` (sheets 16/17) — all reusable for any service marketplace, not just Cameo.
- **Strategic caution (Fable's judgment):** capability ≠ mandate. Running a B2C marketplace is a different business (liquidity chicken-and-egg, consumer support, fraud) from the partner-led B2B factory; the expansion is about what the factory CAN mint. Whether James operates a Cameo clone is a separate, undecided business call.