vibn-agent-runner/VIBN_PRODUCT_BLUEPRINT.md

# Vibn — Product Blueprint & Go-to-Market Architecture

> Status: Draft v3 · Owner: Mark · Last updated: 2026-06-04
> v3 sharpens the wedge to **custom tools** for local businesses (not
> websites/marketing), makes onboarding **expertise-first → dashboard** (no pitch
> generator), and moves the targeting/"gold rush" recommendation into the
> dashboard. v2 (services+margins+pitch onboarding) is superseded; v1 (founder/
> build-first) before it.
>
> Implemented so far (FE, against mocks + typed contracts): the contractor
> onboarding flow — `app/(onboarding)/onboarding/onboarding-agency*.{tsx,ts}` +
> the front-door fork in `page.tsx`. Backend + dashboard pending (handoff doc).

---

## 1. Positioning

**Vibn is the operating system for a new breed of local-business consultant — it
helps them find local SMBs, build them the *custom tools* they actually need
(without writing code), and bill for it profitably — so those businesses stop
paying for a stack of expensive SaaS apps that don't talk to each other.**

The wedge is **custom tools, not websites/marketing.** Every local business is
overpaying for generic SaaS that half-fits; the consultant builds one tool that
fits their workflow exactly.

Think **Harvest for AI vibe coding**: the place a consultant runs the whole
client business — find, build, host, invoice.

Two audiences, one engine — but a clear hero:
- **PRIMARY · The new consultant / freelancer / small studio.** Often not a deep
  engineer (a marketer, designer, or hustler starting a "websites + marketing for
  local business" practice). Vibn is their unfair advantage. **They are the buyer.**
- **SECONDARY · The SMB owner doing it themselves.** Same engine, no markup. Served
  by self-serve, not chased.
- **De-emphasized:** startup founders. That lane (Lovable, v0, Bolt, Replit) is a
  bloodbath and is *not* where our infrastructure points.

### Why this wedge (the infra already leans here)
- `market_categories_suggest` returns **Google Business Profile** categories — a
  *local business* construct.
- `market_research_run` pulls local **business leads, TAM, competitors** (DataForSEO).
- Missinglettr lists **Google Business** among its 12 platforms — local social + GBP.
- The "owner" persona pitch is *"replace the stack of tools you rent"* — SMB ops.
- The Cadence CRM template = contacts + scheduling; domains + Stripe = every SMB.

None of this was built for startups. It was built for **local SMBs and the people
who serve them.** This is a focus, not a pivot.

---

## 2. The two front doors

Opposite motivations require opposite openings:

| Door | Who | First question they're asking | Opening |
|---|---|---|---|
| **"Personal"** | SMB owner / self-builder | *"Can I see my thing built?"* | **Build-first** — straight to a live themed preview (§6) |
| **"Agency"** (HERO) | New consultant | *"Can I do this? What do I build? Who needs it? How do I get a client?"* | **Contractor-first** — set up the agency, state your expertise, land in a dashboard of local targets (§4) |

The homepage leads with the consultant promise and routes self-builders to the
simpler path — it does **not** treat them as equals.

> Reversal from v1: "get to a live preview ASAP" is right for a self-builder and
> *wrong* for a consultant. A consultant is evaluating a **business**, not a build
> tool. Lead with the contractor parts; building happens later, per client.

---

## 3. The lifecycle = one client engagement

For the consultant, the product lifecycle is the shape of **a single client
engagement**, run once per SMB client:

```
DISCOVER  →  BUILD  →  REFINE  →  GROW
the pitch    deliver    iterate    the retainer
(win it)     the site   with client (recurring $)
```

It's driven by two orthogonal axes (kept distinct in code — today they're conflated):

| Axis | Controls | Decided |
|---|---|---|
| **Engagement stage** | The *path* (research/pitch vs build vs grow) | Per client, by where the deal is |
| **SMB domain** (trades, salon, dental, food, fitness…) | The *look* — template family + theme | Inferred from the business type |

A consultant runs many clients at different stages simultaneously.

---

## 4. Contractor-first onboarding — "Set up your AI agency"

Onboarding is short and has one job: learn **who the consultant is** and **what
they love building**. The moment we know their sweet spot, we drop them into
their **dashboard** — where the local-business recommendations live as an
ongoing feature (not a one-shot screen). No pitch generator, no terminal
targeting screen in onboarding. *(Implemented: `app/(onboarding)/onboarding/onboarding-agency.tsx`.)*

```mermaid
flowchart TD
    A["1 · Your agency<br/>name · city (Places lookup)"] --> B["2 · Your presence<br/>what does your agency have today? (checklist)"]
    B --> C["3 · Your ideal customer (free text)<br/>'who / what problem do you want to solve?'"]
    C --> D["Open my dashboard →"]
    D --> E["DASHBOARD<br/>AI reads description → recommends local businesses to target"]
```

- **Agency** option details: "I want to do billable AI work for others" (VIBN helps you find local businesses that you can build custom solutions for).
- **Personal** option details: "I want to build my own ideas" (Go from idea to market, and beyond).

### Step contents
1. **Your agency** — name, **city** (global Places-API lookup, §6.x).
2. **Your presence** — "What does your agency have today?" Checklist of assets
   (Website, social media accounts, blog, custom domain, existing billing).
   Light profiling to customize their dashboard experience.
3. **Your ideal customer** *(the heart of it)* — a **free-text** box: *"Is there a
   certain type of business or business problem you are passionate about?"*
   (e.g. "I want to help dentists automate patient booking"). If they are undecided,
   clicking **"I'm not sure right now"** bypasses the step with a neutral default
   ("help any local business automate workflows"). This replaces the old examples list.
   Vibn will help them match with potential customers in their area, and drive awareness of their brand.
4. **→ Dashboard.** CTA "Open my dashboard →" finishes onboarding with
   `{ profile, expertise, tools }` (AI-extracted tool categories, where `expertise`
   holds the ideal-customer string).

### The Local Business Category Lookup & Mapping Pipeline (onboarding)
This is the core "Business Identity & Needs" pipeline run on Step 1 of the self-builder flow, designed to bypass Google's messy administrative category labels:
1.  **Step 1: City Geocoding & Radius Setup:**
    - The user selects their city in Step 1. The frontend retrieves their structured `CityRef` (holding `lat`/`lng` coordinates from Google Places) and sets a default radial search geofence of **50km**.
2.  **Step 2: Geofenced DataForSEO Business Search:**
    - The backend takes the business name (or URL) and queries the **DataForSEO Business Listings Search API** (`/v3/business_data/business_listings/search/live`) using geofenced `"location_coordinate"` radial search:
      `"location_coordinate": "{{lat}},{{lng}},50"`
    - This bypasses Google's strict SAB restrictions, pulling down the full business records (including mobile businesses with hidden addresses like "Wheely Clean Mobile Dental").
    - The server extracts GMB's main `"category"` and `"additional_categories"` arrays.
    - It joins them to our `smb_to_software_mapping_final.json` dataset (the 4,006-item database) to fetch their exact, customized software tool requirements.
3.  **Step 3: Unpacked Category Card Selection ("Which best describes your business?"):**
    - The frontend receives the matched business, and automatically unpacks **both its primary category and all discovered GMB alternative categories** into individual clickable cards.
    - The screen displays: **"Which best describes your business?"**
    - Selecting any card (e.g. *Dental hygienist* or *Teeth whitening service*) instantly loads that specific subcategory's custom presets and advances to Step 2!
    - *Fallback:* If DataForSEO or geocoding fails (e.g. offline dev), it gracefully triggers Google Places Text Search (New) + Gemini 2.5 Flash as an automated fallback reasoning bridge.

### The targeting engine (lives in the dashboard)

### The dashboard (the home screen they land on)
- **Recommended targets** — the AI's local-business recommendations (above),
  refreshable; claim one to start a client/prospect.
- **Clients / prospects** — each SMB; status (prospect → won → live → retainer).
- **Projects** — per client (a custom tool build + hosting/support retainer).
- **Revenue & margin** — what each client costs me vs. what I bill; retainer MRR
  (illustrative until metering lands, then live).
- Building a client's tool is entered **from a client**, not the dashboard root.
- *(To build next — reuses `extractTools` + `mockTargets`; light paper/ink theme.)*

---

## 5. Modes — capability surfaces with enforced tool gating

Three modes (capability surfaces, not vibes). **Refine is not a mode** — it's Build
against an already-live project.

| Mode | Engagement role | Stop condition |
|---|---|---|
| **Collab** | Discover — research + pitch + spec | PRD + decisions + backlog (the spine) |
| **Build** | Deliver the site + refine | A clickable preview / shipped `fqdn` |
| **Grow** | The retainer — distribute + monitor | Scheduled content + live analytics |

### 5.1 Tool gating is enforced, not described
Today "DO NOT WRITE CODE" is a prompt *request* while `fs_write`/`ship`/`shell_exec`
stay in the tool list → the constraint is soft and the prompt re-teaches the
forbidden workflow. Fix: one `MODE_TOOLS: Record<Mode, ToolName[]>` map, read by:
1. **Prompt builder** — filters exposed tool schemas per mode (model can't see what
   it can't call; also cuts ~88 schemas → ~20–30 = token/latency win).
2. **Dispatcher** — rejects out-of-mode calls (guards hallucinated names).
Applied in **both** `vibn-frontend/app/api/chat/route.ts` and the agent-runner.

### 5.2 Allowlist sketch
| Capability | Collab | Build | Grow |
|---|---|---|---|
| Reads (`projects_get`, `apps_*` reads, `get_design_template`) | ✅ | ✅ | ✅ |
| Research (`market_*` 💲, `github_*`, `http_fetch`) | ✅ | ❌ | ✅ (seo/insights) |
| Spine docs — `fs_*` **scoped to `.vibncode/specs/`** | ✅ | ✅ (+ repo) | ✅ (blog/SEO) |
| Design kit / `apps_templates_scaffold` | propose | ✅ full | theme marketing |
| Engineering (`shell_exec`, `dev_server_*`, `apps_create`, `ship`, `databases_*`) | ❌ | ✅ | `apps_create { repo }` only |
| Distribution (`missinglettr_*`, `generate_media`) | ❌ | ❌ | ✅ |
| Destructive (`*_delete`, `apps_volumes_wipe`) | ❌ | ⚠️ confirm | ❌ |

Gating gives each guardrail a home: **money gate** in Collab, **destructive-confirm**
in Build, **untrusted-content rule** in BASE (Collab + Grow read the open web).

### 5.3 Prompt composition
```
BASE   identity · voice · spine/task-ledger contract · infra model · hard rules ·
       untrusted-content rule · project + client/agency state
  +
MODE   { Collab | Build | Grow } — behavior + stop condition + protocols
  +
CONTEXT design kit · decisions/backlog · stage seed · SMB-domain template guidance
```
BASE + MODE must be **shared modules imported by both** the chat route and the
agent-runner (today there are three drifted copies — root of the "loops on task 1"
bug).

### 5.4 Visibility
Modes **auto-select** by stage + project state. The toggle remains a power-user
override. Nobody picks a mode manually.

---

## 6. Build-first door & design-first delivery

The build flow is no longer the front door — but it's still how work gets
*delivered* (and how a self-builder enters). It must be **design-first, not
code-first.**

- **Stop** scaffolding from `create-next-app` + hand-building UI (slow, generic,
  the source of visual-QA loops).
- **Start** from a polished, CSS-variable-themed template family, reskin to the
  SMB's brand via the design-kit token system, then populate content.

### 6.1 Template families (assets in `design-templates/VIBN (2)/`)
| Family | Use | SMB domain |
|---|---|---|
| `vibn-ai-templates` | Shared base library (components + 4 themes) | foundation |
| `vibn-app` | Marketing / landing / lead capture + payments | most local SMB sites |
| `vibn-crm` (Cadence) | Ops: contacts, scheduling, dashboard | trades, salons, clinics |
| `vibn-marketplace` (Atlas) | Listings / booking / two-sided | directories, multi-vendor |

Themes (`minimal` / `dark` / `glass` / `editorial`) + accent come from the SMB's
brand. **Demos must look visibly local-SMB** (a plumber, a salon, a dental office),
never a generic SaaS dashboard.

### 6.2 Wired vs. to-build
- ✅ Design-kit registry, Design tab, token injection, `apps_templates_scaffold`, `get_design_template`.
- ❌ The four families ingested as registered kits (`DESIGN.md` + `tokens.css` + `SKILL.md`).
- ❌ Build recipe rewritten to "scaffold-from-kit first."
- ❌ Build entered per client from the console; SMB brand → kit selection.
- ❌ Real session streamed to a real themed preview (today: `setTimeout` animation + fake URL, answers discarded).

### 6.3 Fork, don't depend
Fork the kit into the client's repo (the READMEs say "fork it") — self-contained,
fully editable.

---

## 7. Grow — the retainer (Missinglettr)

Grow is the consultant's **recurring revenue.** Once a client's site is live, the
consultant runs their marketing as a monthly retainer.

- **Missinglettr API** = one API to post/schedule across 12 platforms (incl. Google
  Business) with shortening, analytics, webhooks. The engine of Grow.
- **My Business Business Information API (GMB)** = used specifically via OAuth 2.0 to manage verified locations, publish Google Local Business posts, and retrieve and reply to reviews (reputation management). Combined with Missinglettr, it forms the core Grow suite.
- **DataForSEO OnPage API Website Auditor** = crawlers that fetch a client's website and return full on-page diagnostics: `cms` auto-detection (Wix, WordPress, Squarespace), SSL status, mobile responsiveness, and broken link counts.
- Capabilities: AI-generated social + blog + **local SEO pages**, styled to match
  the client's design kit, scheduled via Missinglettr; reviews; analytics reporting.
- Existing blocks: `market_seo_analyze`, `generate_media`, `project_recent_errors`
  (monitoring), and `vibn-attribution-package` (UTM → first-touch attribution).
- To build: `missinglettr_*` tool wrapper, content/SEO generation, analytics loop,
  and a **client-facing monthly report** (the retainer's visible value).

---

## 8. Agency / billing layer — "Harvest for AI vibe coding" (CORE, not a fast-follow)

For the consultant ICP, **getting paid is half the value prop.** It cannot be an
afterthought. The most important primitive is the **monthly retainer** (the Grow
fee = the consultant's MRR), not just the one-off project invoice.

### 8.1 Cost sources (all metered, tagged by client/project)
| Cost type | Source |
|---|---|
| AI usage (tokens) | `lib/ai/llm-client.ts` |
| Compute / infra (apps, dev containers, DBs) | Coolify / `lib/dev-container.ts` |
| Domains | `domains_register` / `lib/opensrs.ts` |
| Market research 💲 | `market_research_run` (DataForSEO) |
| Distribution | Missinglettr (usage / subscription) |
| Media | `generate_media` |

### 8.2 Components
1. **Metering ledger** — `{ workspaceId, clientId, projectId, costType, quantity,
   rawCost, ts }`. Seeded by `lib/quotas.ts` + telemetry. Every cost-incurring tool
   emits an event.
2. **Client ↔ project mapping** — agency workspace holds many client projects.
3. **Pricing engine** — per client: **retainer** (recurring), cost-plus markup %,
   or fixed project price. Roll up raw cost → apply pricing → billable.
4. **Invoicing & retainers** — Stripe (in stack): one-off invoices **and recurring
   subscriptions** for retainers; optional client statement/portal.
5. **In-agent cost transparency** — AI surfaces estimated cost *before* spending
   (the money-gate guardrail as a platform concept); every spend is attributable.

### 8.3 Consequence
Accurate per-client cost accounting is needed regardless of when invoicing UI ships,
so **the metering ledger is launch-foundation work** — retrofitting attribution is
painful. Onboarding's "your margins" can be *illustrative* until metering is live,
provided the numbers are honestly labeled.

---

## 9. The spine — single source of truth

**`.vibncode/specs/*.md` (markdown) is the law.** Retire DB `plan_*` tools (or make
them thin markdown writers). The desktop Interactive Backlog already reads markdown;
the session runner already toggles checkboxes; it's git-tracked; it's the artifact
the user sees and edits.
- Task state = `- [ ]` / `- [x]`; all brains obey this.
- `.vibncode/` **must be committed and never removable by `git clean -fd`** (the
  earlier unattended-loop bug).
- The **design kit travels in the spine** — styling source of truth from Build → Grow.
- The spine carries the engagement: Discover writes the spec/pitch, Build consumes
  it + adds the kit, Grow reads product + kit to generate matching marketing.

---

## 10. Hardening (from the prompt/tool audit)

- **Phantom tools:** `apps_envs_set`→`apps_envs_upsert`; `apps_containers_list`→
  `apps_containers_ps`; `plan_decision_log` (Architect; doesn't exist) → remove.
- **Template-literal leak:** `route.ts` ~L306 escaped `\${activeProject.slug}` →
  un-escape so it interpolates.
- **Task-tracking civil war:** route vs shared-body vs runner disagree → markdown
  checkboxes everywhere (§9).
- **Hardcoded project specs:** route ships one project's private spec list
  (COPPA / Missinglettr / Dracula) to every user → generalize/derive.
- **Architect contradiction:** solved by mode gating (§5) + composition (§5.3).
- **Sentry snippet path** unreachable from dev container → inline / ship in scaffold.
- **`request_visual_qa` "Always"** → "for UI work."
- **Infra clarity:** add infra model + first-deploy recipe (resolve `ship` "if
  linked" + `ship` vs `apps_create { repo }`).

---

## 11. Go-to-market sequencing

| Milestone | Scope | Why |
|---|---|---|
| **0 · Foundation** | Spine = markdown everywhere; BASE+MODE shared modules; `MODE_TOOLS` gating; phantom/leak fixes; de-contaminate specs; **metering ledger** | Nothing safe until brains agree on the ledger; metering before any spend |
| **1 · Contractor onboarding (launch front door)** | "Start an AI agency" flow: opportunity → identity (Places city lookup) → presence → **free-text expertise** → dashboard. ✅ FE built against mocks | What the hero ICP evaluates first; short and contained |
| **2 · The dashboard + targeting** | Land them in the dashboard; AI extracts tools from expertise (`analyze-expertise`) → recommends local businesses to target (`targets` via Places Aggregate); claim → prospect | The "gold rush" payoff + ongoing home |
| **3 · Deliver (design-first build)** | Ingest 4 kits → kit-first build recipe → build the client's **custom tool** per client → real preview | Turns a claimed target into a delivered tool |
| **4 · Grow retainer + Missinglettr** | `missinglettr_*`, content/local-SEO, analytics loop, client monthly report | Recurring-revenue hook |
| **5 · Full billing** | Retainers + one-off invoicing (Stripe) + client statements on the metering ledger | Completes "bill for it" |

**Launch line:** Milestones 0 + 1 + 2 (onboarding → dashboard with real
recommendations) + a slice of 3 (one custom tool built end-to-end). Grow/billing
shown as the model, delivered next.

**Build status:** onboarding FE (steps 1–4) is built and compiles clean against
mock data + typed contracts. Backend endpoints + the dashboard are next (see
`VIBN_HANDOFF_TICKETS.md`).

---

## 12. The journeys (consultant serving a local SMB)

### Sofia — the new consultant (the hero path)
Sofia wants to start a side-business building custom tools for local businesses.
She signs up, selects the "Agency" option, names it, sets her city (a global Places lookup),
and declares what assets she has today. Then the
one question that matters: *"Is there a certain type of business or business problem you are passionate about?"* She types
"I want to help local dentists automate patient booking" and clicks **Open my dashboard**. She's
in. Her dashboard already shows local businesses that fit — salons, gyms, auto
shops, dentists — each flagged as stuck on disconnected SaaS and ripe for one
custom tool. She hasn't done any work and already has a target list.

### Joe's Plumbing — the client gets a custom tool (Build)
Sofia claims "plumbers," picks Joe as a client, and builds him a custom
scheduling + invoicing + reporting tool — one app around his workflow, replacing
the three half-fitting SaaS subscriptions he was paying for. Design-first from a
kit, in his colors, live in a day instead of weeks.

### The SMB owner — self-serve (secondary door)
An owner who finds Vibn directly selects the "Personal" option, enters their business name, city, and optional website, gets their business type auto-analyzed by the AI, and goes straight to building:
### The retainer — recurring revenue (Grow)
With Joe live, Sofia adds a marketing retainer. Vibn generates his Google Business
posts, a couple of local-SEO pages, and social content in his brand voice, schedules
it across platforms via Missinglettr, and produces a monthly report Sofia forwards to
Joe. Joe sees leads; Sofia bills a recurring fee.

### Getting paid (Billing)
Every cost on Joe's projects — AI, hosting, his domain, the market research, the
social scheduling — is metered and attributed. Sofia applies her markup, and Vibn
turns the build into a one-off invoice and the marketing into a recurring Stripe
subscription. She's not just delivering work; she's running a business with real margin.

### The SMB owner — self-serve (secondary door)
An owner who finds Vibn directly skips the agency setup and goes build-first:
"a booking tool for my salon" → a quick look confirm → watches it build → lands
in the chat refining it. Same engine, no markup, no dashboard.

---

## 13. Open decisions
1. ~~**Front-door fork**~~ — **DECIDED:** explicit "Agency" vs "Personal" (neutral presentation, no pre-selection bias).
2. **Targeting spend** — the dashboard's recommendations need per-city counts
   (Places Aggregate API) and may touch paid `market_research_run`. Use a
   free/cached read for the first dashboard view; gate any paid run on consent.
3. **`MODE_TOOLS`** as the single source of truth for prompt + dispatcher. (Lean: yes.)
4. **Collab write scope** path-scoped to `.vibncode/`. (Lean: yes.)
5. **Kit ingestion** — one kit per family, themes as overrides. (Lean: yes.)
6. **Pricing model first** — retainer vs cost-plus vs fixed: which to ship first.
   (Lean: retainer + simple markup.)
7. **Launch SMB vertical** — which single domain to polish end-to-end first
   (trades? salon? dental?).
8. ~~**Core brand color**~~ — **DECIDED** (see §14).

---

## 14. Design system (aligned — build everything to this)

The canonical visual spec. All net-new frontend is built to it; the cheaper model
inherits it too.

- **Foundation: warm paper-and-ink** (the differentiator). Product is light
  (`--vibn-paper` bg, `--vibn-ink` text, the warm-neutral ramp); marketing may be
  dramatically dark.
- **One brand color: matured clay-coral**, threaded through *both* marketing and
  product, used **sparingly** (primary action, active state, brand mark, progress,
  the single "next thing"). No second chromatic color.
  - Tokens in `app/globals.css`: `--vibn-coral` `oklch(0.68 0.16 35)` (actions),
    `--vibn-coral-hover`, `--vibn-coral-glow` (the brighter `0.74 0.175 35` for
    glow/focus), `--vibn-coral-soft`, `--vibn-coral-fg`.
  - Added **additively** — existing `--primary`/`--accent` not rewired blind;
    new surfaces use the coral tokens directly and get visual QA.
- **Hard rule:** Vibn chrome accent (coral) ≠ a client app's accent. The product
  chrome is coral; each *built client site* uses its own design-kit accent.
- **Two contexts:** onboarding wizard = dark + coral (existing primitives in
  `app/(onboarding)/onboarding/onboarding-primitives.tsx`); product/console =
  light paper/ink + coral.
- **Client builds** come from the 4 design-kit families (base + app/crm/
  marketplace), CSS-var themed (minimal/dark/glass/editorial), forked into the
  client repo. Demos must look visibly local-SMB.
- **Type:** product = Inter (`--font-inter`); editorial moments may use a serif
  display per the kit.