# BizBuilder agent integration spec

This file describes what an autonomous agent (Cursor, Claude Code, Lovable, Bolt, v0, Replit, OpenClaw, Hermes, or any MCP-compatible client) can do with BizBuilder on behalf of a vibecoder.

## Status

V1.5 — MCP server scaffolding in development. Initial 4 tools defined below; production endpoint forthcoming.

## Identity

- **Product:** BizBuilder
- **Tagline:** The AI Copilot for vibecoders. Builders should stay builders — we do the labor of being found.
- **Role:** AI growth copilot for solo founders — runs the customer-acquisition loop for founders who shipped on AI coding tools (Lovable, Bolt, Cursor, v0, Replit, Claude Code, etc.).
- **Owner:** BizBuilder, Inc.
- **Web:** https://bizbuilderai.com
- **API base (planned):** https://bizbuilderai.com/api/mcp/v1

## What an agent can do

### `bizbuilder.scout(url)` — read-only

Returns 10-15 conjunction proposals for a given product URL. Free. No spend, no commit. Scout reads the page (Firecrawl), matches against the seed library + vector library, and proposes shapes with predicted CPA bands.

Inputs:
- `url` (string, required) — full https URL of the product landing page.

Outputs:
- `proposals` (array of ConjunctionProposal) — see schema in src/lib/actions/scout-conjunctions.ts.
- Each proposal carries `seed_library_ref` (SP-001..SP-030) and `vector_ref` (V001..V025) when matched.

### `bizbuilder.test_pmf(url)` — free Probe

Runs a free Probe: BizBuilder reads the page, proposes 2-3 audience-archetype districts, and runs a real, hard-capped (~$10-15) ad/seed micro-test across them. Within hours the founder watches real strangers arrive in their city. No card asked — the Probe is free.

Requires:
- Authenticated user (OAuth or API token).

Inputs:
- `url` (string, required).

Outputs:
- `venture_id` (string) — track via `bizbuilder.observe`.

### `bizbuilder.observe(venture_id)` — read-only

Returns the current state machine state, latest outcomes, and conjunction-by-conjunction performance.

Inputs:
- `venture_id` (string, required).

Outputs:
- `state` (string) — submitted | reviewing | scout_ready | flagged_for_payment | approved | launching | running | measuring | deciding | scaling | killed | killed_by_admin | pivoting.
- `cycle_number_for_user` (integer).
- `conjunctions` (array) — latest outcomes per conjunction.
- `verdict` (object, when present) — Scale / Fix / Kill recommendation + diagnostic.

### `bizbuilder.decide(venture_id, decision)` — write

Commits a K/P/DD decision (kill, pivot, double_down/scale).

Inputs:
- `venture_id` (string, required).
- `decision` (enum, required) — `scale` | `pivot` | `kill`.

Outputs:
- `ok` (boolean).
- `next_state` (string) — the state machine target after the transition.

## Authentication

OAuth-style flow modelled on Humblytics' agent onboarding:

1. Agent calls `POST /api/mcp/v1/auth/init` with `{ client_name }` → receives `{ token, verifyUrl }`.
2. User opens `verifyUrl` in a browser, signs into BizBuilder, approves the agent.
3. Agent polls `GET /api/mcp/v1/auth/status?token=...` until status returns `approved` and yields a long-lived bearer token.
4. Subsequent calls use `Authorization: Bearer <token>`.

For MCP clients (Cursor, Claude Code), the token lives in the client's MCP settings.

## Source-attribution header

Agents calling BizBuilder should set `x-bb-mcp-client` to one of:

- `cursor` → `mcp_cursor` source
- `lovable` → `mcp_lovable`
- `bolt` → `mcp_bolt`
- `claude_code` → `mcp_claude_code`

This validates Critical Condition #4 (MCP conversion ≥3x web).

## Rate limits

V1.5 limits (subject to revision):
- Scout: 10 calls/hour/IP unauthenticated; unlimited authenticated.
- test_pmf: one free Probe per URL/domain; rate-limited per account and per IP.
- observe / decide: 60 calls/min/venture.

## Versioning

This document carries a `Last-Updated` semantic version implicitly via `https://bizbuilderai.com/llms-full.txt` — read both for the current contract.

Last-Updated: 2026-05-05 (V1.5)