vibn-frontend/docs_archive/VIBN_PRD.md

# vibn — Product Requirements Document

**Version:** 1.0  
**Date:** March 2026  
**Author:** Mark Henderson / Atlas AI  
**Status:** Draft

---

## 1. Executive Summary

vibn is a template-first SaaS product builder for non-technical founders. It turns a product idea into a fully deployed, live web application — without writing code. Users describe their idea through a guided 6-phase wizard (Discover → Architect → Design → Market → Build), and vibn's AI agents scaffold, build, and deploy the product onto the user's own self-hosted infrastructure (Gitea + Coolify). vibn is positioned as "Shopify for building software": opinionated, template-driven, and designed to dramatically reduce failure rates compared to blank-page AI coding tools. The target customer is a non-technical or low-technical founder who has a validated idea and wants to get to a live product and first paying user in under 72 hours.

---

## 2. Problem Statement

**The problem:** Non-technical founders cannot build software products without hiring developers or becoming one themselves. Existing AI coding tools (Cursor, Replit, v0) assume technical literacy. General-purpose AI (ChatGPT) produces code snippets that can't be deployed. Developer agencies cost $50–200k and take 6–12 months. The gap between "I have a great idea" and "I have a live product" remains enormous.

**Who experiences it:** Solo founders, domain experts (lawyers, trainers, consultants, operators) who want to productize a service, career changers, and micro-agencies wanting to scale client delivery without headcount.

**What they do today instead:**
- Hire a freelance developer (slow, expensive, dependency risk)
- Use no-code tools like Bubble or Webflow (limited, technical ceiling, hard to customize)
- Try to learn to code (fails 90%+ of the time for non-native coders)
- Sit on the idea indefinitely

**Why current alternatives fall short:**
- Bubble/Webflow: Hit a wall as soon as real backend logic is needed; proprietary and not portable
- AI coding tools: Require knowing what to ask, how to debug, how to deploy — the hard parts remain
- Agencies: Take too long, cost too much, and the founder loses control
- Hiring: Creates single-point-of-failure dependency

---

## 3. Vision & Success Metrics

**Vision:** vibn is the fastest path from idea to live product for anyone who can describe what they want. It removes every technical barrier between a non-technical founder and a running SaaS — planning, building, deploying, and marketing — while keeping the user in control and the infrastructure on their own servers.

**Success metrics (v1, 6-month targets):**

| Metric | Target |
|---|---|
| Time from signup to deployed app | < 72 hours (median) |
| % of builds that deploy successfully on first attempt | > 85% |
| Monthly active builders | 500 |
| Projects reaching "live" status | 200 |
| Net Revenue Retention (NRR) | > 100% |
| Gross margin | > 65% |
| Paying customers at 6 months | 150 |

**Key milestones:**
- Month 1: Private beta with 10 hand-selected founders
- Month 2: 50 projects initiated, first 20 live
- Month 3: Public waitlist open, payment enabled
- Month 6: Self-serve onboarding, 150 paying customers

---

## 4. Target Users & Personas

### Persona A — The Non-Technical Founder ("The Builder")
- **Who:** A domain expert (ex: fitness coach, lawyer, ops manager) who has identified a software problem in their industry. No coding background. Has validated the idea informally with peers.
- **Primary goal:** Go from idea to a working product they can show to real users and start charging for.
- **Pain points:** Doesn't know where to start technically; has been burned by developers before; doesn't trust no-code tools for "real" products; overwhelmed by choices.
- **Happy path:** Describes idea in the Discover phase → reviews and approves architecture → picks a visual style → sets brand voice → hits "Build" → shares a live URL within 48 hours.
- **What they value:** Speed, control, clarity. They want to see something real, not a mock.

### Persona B — The Micro-Agency Operator ("The Producer")
- **Who:** A freelancer or small agency (1–5 people) that builds web products for clients. Currently using developers or outsourcing. Wants to deliver faster and at higher margin.
- **Primary goal:** Build client products in days, not months. Manage multiple projects from one dashboard. Bill clients for AI compute costs with markup.
- **Pain points:** Hiring developers is expensive and slow. Coordinating freelancers is painful. Margins are thin. Can't take on more work without more headcount.
- **Happy path:** Creates a new client project → walks through wizard on behalf of client → client reviews and approves → vibn builds and deploys → operator bills client with AI cost markup shown.
- **What they value:** Speed, multi-project management, billing visibility, client-presentable output.

### Permissions Matrix

| Capability | Builder (own project) | Producer (client project) |
|---|---|---|
| Create project | ✓ | ✓ |
| Run wizard phases | ✓ | ✓ |
| Trigger build | ✓ | ✓ |
| View live app URL | ✓ | ✓ |
| View cost breakdown | Own costs only | Full client cost breakdown |
| Bill client | — | ✓ |
| Manage custom domain | ✓ | ✓ |
| Access Gitea repo | ✓ | ✓ |
| Request changes post-launch | ✓ | ✓ |

---

## 5. User Flows & Journeys

### Primary Flow — New Builder (Non-Technical Founder)

1. Lands on vibn marketing site (`vibn.app`)
2. Clicks "Get started free" → enters email
3. Completes **Welcome phase**: sees 5-step overview of what vibn does, clicks "Let's build it"
4. **Discover phase**: guided 6-question chat conversation — idea, problem, users, value, revenue, features. Sees live PRD panel filling in as they answer. Continues when all 6 answered.
5. **Architect phase**: Reviews AI-generated architecture (frontend, backend, auth, payments, email, hosting). Each block shows the chosen option and why. Can edit any block. Confirms with "Plan looks good — next: Design".
6. **Design phase**: Picks visual feel from 6 presets (Clean, Bold, Warm, Fresh, Electric, Luxury). Sees live mock of their app updating in real time.
7. **Market phase**: Sets brand voice (sliders for tone, style, personality). Reviews and edits 3 AI-generated content topics. Previews their marketing website style.
8. **Build phase**: Reviews full summary (auth, payments, email, style, website, topics, pages). Clicks "Build my MVP". Watches 12-step live build progress. Receives live URL + Gitea repo link.
9. Redirected to **Dashboard** — sees project as "Live" with URL, stats, and action buttons.

### Secondary Flow — Returning User (Dashboard → Change Request)

1. Logs in → lands on Dashboard (projects screen)
2. Selects an existing project → clicks "Build" or "Grow"
3. Enters the relevant phase of the wizard in edit mode
4. Makes changes → re-triggers partial build
5. Returns to Dashboard, sees updated deployment

### Secondary Flow — Agency Producer (Client Project)

1. Logs in → clicks "+ New project"
2. Tags project as "Client" and enters client name
3. Walks through wizard as normal (can be done with client present or on their behalf)
4. After build: sees project card with "Client" tag, cost breakdown, and "Bill →" button
5. Clicks "Bill →" → generates itemized invoice (LLM costs + compute + markup)
6. Views unbilled total across all clients in Billing screen

### Onboarding Flow

1. Email signup → verify email
2. Welcome wizard (Welcome phase of builder)
3. First project created automatically — user is never left on an empty dashboard
4. If user exits mid-wizard, project is saved as draft and resumed on next login

### Error / Recovery Flows

- **Build fails mid-way:** User sees which step failed, error plain-English explanation, and "Retry" button. Failed build does not charge full credits.
- **Payment setup missing:** If user chose Stripe billing in Architect but hasn't connected Stripe, they're prompted before Build is triggered.
- **Custom domain fails DNS:** In-app guide walks through DNS setup; app is still live on vibn subdomain in the meantime.
- **User exits mid-wizard:** Progress is auto-saved per phase. Resumable from Dashboard.

---

## 6. Feature Requirements

### 6.1 Must Have (v1 Launch)

**Builder Wizard — 6-Phase Flow**
- *Description:* The core product experience. A sequential, guided wizard that takes a user from idea to deployed product.
- *User story:* As a non-technical founder, I want to answer plain-English questions and have AI figure out the architecture, code, and deployment — so I never have to think about technical choices.
- *Acceptance criteria:* All 6 phases completable end-to-end. Progress saved between sessions. Each phase produces a visible artifact (PRD, architecture plan, design preview, etc.).

**Discover Phase — Conversational PRD Builder**
- *Description:* 6-question guided chat. Each answer populates a live PRD panel. AI synthesizes answers into a structured product plan.
- *Acceptance criteria:* All 6 questions answered before proceeding. PRD panel shows structured output per question. "Plan looks good" CTA advances to next phase.

**Architect Phase — Architecture Selection**
- *Description:* AI proposes 6 architecture blocks (Frontend, Backend, Auth, Payments, Email, Hosting). Each block is explainable in plain English and editable.
- *Acceptance criteria:* All 6 blocks shown with default selection and rationale. User can change any block via dropdown/modal. Hosting block is locked to self-hosted (Coolify + Gitea). Pages list shown.

**Design Phase — Visual Feel Picker**
- *Description:* 6 visual presets. Selecting a preset updates a live app mock in real time.
- *Acceptance criteria:* 6 presets rendered correctly. Live mock updates within 300ms of selection. Continue CTA available once selection made.

**Market Phase — Voice + Topics + Website**
- *Description:* Brand voice sliders (tone, style, personality). AI-generated content topics (add/edit/remove). Website style picker with live preview.
- *Acceptance criteria:* Voice sliders affect AI content generation downstream. Topics editable with add/remove. Website preview updates with style selection.

**Build Phase — Review + Deploy**
- *Description:* Full summary of all decisions. "Build my MVP" button triggers 12-step build pipeline. Live progress shown. On completion: app URL + Gitea link.
- *Acceptance criteria:* All decisions shown accurately from prior phases. Build progress shows step-by-step status. On success: live URL displayed and functional. On failure: clear error + retry option.

**Dashboard — Projects View**
- *Description:* Home screen after login. Shows all projects with status, basic stats, and actions.
- *Acceptance criteria:* Projects shown as cards with status (Live/Building), URL, and key stats (visitors, signups, MRR). "Continue building" for in-progress builds. "+ New project" creates a new wizard session.

**Dashboard — Billing View (Agency)**
- *Description:* Client billing tab showing unbilled costs by client, LLM/compute/other breakdown, invoice generation.
- *Acceptance criteria:* Unbilled totals accurate. "Bill →" generates invoice. Cost log shows itemized charges.

**Authentication**
- *Description:* Email-based signup/login for the vibn platform itself.
- *Acceptance criteria:* Email + password signup. Email verification required. Forgot password flow. Session persists across browser restarts.

**Deployment Integration (Coolify + Gitea)**
- *Description:* Every built project is pushed to user's Gitea repo and deployed via Coolify automatically.
- *Acceptance criteria:* Gitea repo created on build start. Code committed on completion. Coolify deploy triggered automatically. App live on `[project].vibn.app` subdomain.

**Floating AI Chat (Assist)**
- *Description:* Phase-aware chat assistant available throughout the builder wizard. Persists across phase navigation.
- *Acceptance criteria:* Chat available from Discover through Build phases. Phase-specific starter suggestions. Chat history persists across phase changes. Does not reset on navigation.

---

### 6.2 Should Have (Fast Follow — Months 2–3)

**Custom Domain Support**
- Users can connect their own domain to a deployed project.
- In-app DNS setup guide. SSL auto-provisioned via Coolify.

**Post-Build Change Requests**
- Users can request changes to their live product in plain English.
- AI interprets, diffs the codebase, applies change, redeploys.

**Marketing Autopilot**
- AI generates and schedules blog posts, email newsletters, and social content based on topics defined in Market phase.
- Initial manual approval required; can be set to auto-publish.

**Credit Usage Display**
- Show real-time credit consumption during builds.
- Warn before triggering tasks estimated to cost > X credits.
- User-configurable spending cap per project.

**Template Marketplace Access**
- Starter templates browsable before creating a project.
- Template selection sets pre-configured architecture defaults.

---

### 6.3 Could Have (Future — Months 4–6)

**Client-Facing Project Portal**
- Agency clients can log in to review progress, approve phases, and view their live app — without accessing the vibn dashboard directly.

**Stripe Connect for Invoice Payment**
- Agency operators can receive payment from clients directly via vibn.

**Analytics Dashboard (per project)**
- Built-in lightweight analytics (page views, signups, MRR) sourced from the deployed app's database.

**Invite Team Members**
- Multiple vibn users can collaborate on a single project.

**Mobile App (iOS/Android)**
- Native app for monitoring live projects and approving content scheduled by marketing autopilot.

**Template Marketplace (Sell/Buy)**
- Third-party developers can submit templates; users can purchase premium templates.

---

### 6.4 Explicitly Out of Scope (v1)

| Feature | Reason excluded |
|---|---|
| Mobile app (iOS/Android) builder output | All v1 builds are web apps; native app generation is a later capability |
| Real-time multi-user collaboration on wizard | Single-user flow only in v1; collaboration is v2 |
| Self-hosting vibn itself (white-label) | Not offered in v1; Enterprise tier future consideration |
| AI voice/video generation | Out of scope; vibn generates text and code only |
| Direct Stripe Connect marketplace | Invoice workflow is manual export only in v1 |
| Custom AI model selection by users | Model routing is automatic; users do not choose models |
| Offline/desktop app | Web-only |
| HIPAA / SOC2 compliance | Out of scope for v1; required before any healthcare customers |

---

## 7. Screen-by-Screen Specification

### 7.1 Marketing Website (`vibn.app`)
- **Purpose:** Acquire non-technical founders. Convert to "Get started free" or "Log in".
- **Key elements:** Hero headline ("You have the idea. We handle everything else."), 5-step how-it-works, pull quotes from 3 founders, stats bar (280+ launched, 72h avg, 4.9 rating), empathy section, final CTA.
- **Actions:** Get started free → Welcome wizard. Log in → Dashboard.
- **Notes:** Lora serif + Inter sans, ink/parchment palette. No color accents.

### 7.2 Welcome Phase
- **Purpose:** Orient the user, set expectations, build confidence.
- **Key elements:** 5-step overview of the vibn process. "Let's build it →" CTA. Tagline: "From idea to live product. No code needed."
- **Actions:** "Let's build it" → Discover phase.

### 7.3 Builder Sidebar (phases 2–6)
- **Purpose:** Persistent navigation and progress tracking during the wizard.
- **Key elements:** vibn logo. Progress checklist (Product plan, Architecture, Product design, Marketing). Phase nav (Discover, Architect, Design, Market, Build MVP). User avatar + name + plan at bottom.
- **Notes:** Sidebar is hidden on Welcome and Website screens. Always visible during builder phases.

### 7.4 Discover Phase
- **Purpose:** Capture the product idea as structured data. Output: PRD.
- **Key elements (left panel):** Phase header, progress bar across 6 questions, AI message bubble per question, user input field.
- **Key elements (right panel):** "Your Product Plan" — live-updating sections: Idea, Problem, Users, Value, Revenue, Features. Each fills in as answered.
- **Actions:** User types answers. AI asks follow-up. After 6 questions: "Plan looks good — next: Architect →" CTA.

### 7.5 Architect Phase
- **Purpose:** Let user review and confirm the technical architecture in plain English.
- **Key elements (center):** Phase header. 6 architecture blocks as horizontal-scrollable cards (Frontend, Backend, Auth, Payments, Email, Hosting). Each card shows: icon, chosen option, plain-English explanation, "Change →" button. "Why?" expandable for each block. Infra note (Coolify + Gitea).
- **Key elements (right panel):** "Pages to Build" — grouped by Public, Auth, App, Payments.
- **Actions:** "Change →" opens selection modal with 2–4 alternatives per block. "Confirm — next: Design →" CTA.

### 7.6 Design Phase
- **Purpose:** Choose a visual style for the product.
- **Key elements (left):** 6 feel cards (Clean, Bold, Warm, Fresh, Electric, Luxury) — each with label, reference product, and color/style preview.
- **Key elements (right):** Live app mock that updates to reflect selected feel. Shows a plausible dashboard UI in that style.
- **Actions:** Click a feel card → mock updates. "Next: Market →" CTA.

### 7.7 Market Phase — Voice Tab
- **Purpose:** Set the brand voice for AI-generated content.
- **Key elements:** 3 slider pairs: Tone (Friendly ↔ Professional), Style (Conversational ↔ Precise), Personality (Warm ↔ Direct). "Voice preview" section shows how the brand would introduce itself.
- **Actions:** Sliders adjust in real time. Tab switches to Topics or Website.

### 7.8 Market Phase — Topics Tab
- **Purpose:** Define the content topics AI will generate and publish.
- **Key elements:** 3 pre-generated topic cards (title, angle, channels). Each editable. "Add topic" button. Remove button per card.
- **Actions:** Edit, add, remove topics. "Next: Website →" tab.

### 7.9 Market Phase — Website Tab
- **Purpose:** Choose the marketing website visual style.
- **Key elements:** 4 website style options (Editorial, Startup Energy, Ultra Minimal, Warm & Human). Live website preview panel updates on selection.
- **Actions:** Click style → preview updates. "Plan looks good — next: Build →" CTA.

### 7.10 Build Phase — Review Screen
- **Purpose:** Final review before triggering the build.
- **Key elements:** Summary grid (Auth, Payments, Email, Product Style, Website Style, Campaign Topics). Pages list (by group). Infra deployment note. "▲ Build my MVP" button. Disclaimer: ~15 minutes, refinable after launch.
- **Actions:** "Build my MVP" → transitions to Build Progress screen.

### 7.11 Build Phase — Progress Screen
- **Purpose:** Show real-time build progress.
- **Key elements:** 12-step checklist with: completed steps (green checkmark), active step (animated indicator), pending steps (grey). Step label + detail line. Progress header showing step count.
- **On completion:** "Your MVP is live" screen — app URL ("Open my app ↗"), Gitea link ("View in Gitea ↗"), "Your next 3 actions" card.

### 7.12 Dashboard — Projects Screen
- **Purpose:** Manage all projects from one place.
- **Key elements:** "Your projects" header with count. Unbilled total button (if agency projects exist). "+ New project" button. Project cards (2-column grid): status thumbnail, project identity (name, URL, client if applicable), status pill (Live/Building), cost strip (client projects), stats (visitors, signups, MRR), action buttons (Build, Grow, ↗). New project CTA card (dashed border, "+" icon).
- **Activity feed:** Recent events across all projects (content published, new signups, build events).

### 7.13 Dashboard — Billing Screen (Client Billing tab)
- **Purpose:** Manage invoicing for agency operators.
- **Key elements:** Summary stats (total unbilled, LLM costs, compute, other). Billing table (by client, by month). Each row: project, LLM, compute, other, total, status pill. "Invoice" button per unbilled row. "Generate invoice" button (global).

### 7.14 Dashboard — Billing Screen (Cost Tracker tab)
- **Purpose:** Understand AI and infrastructure cost breakdown.
- **Key elements:** LLM usage breakdown (code gen, content, chat assist) with bar charts. Infrastructure breakdown (hosting, database, email, domain). Recent charges log (time, description, project, cost).

### 7.15 Floating AI Chat (Assist)
- **Purpose:** On-demand AI help throughout the wizard.
- **Key elements:** Dark header with "Assist · [phase]" + live green dot. Message thread (user + assistant bubbles). Phase-specific starter suggestions (3 clickable). Input field + send button.
- **Behavior:** Persists open/closed state and message history across phase changes. Accessible via 💬 bubble button at bottom right.

---

## 8. Business Model & Pricing

### Revenue Model
**Subscription + Credits** (not unlimited AI)

The subscription covers fixed platform value (infrastructure orchestration, templates, UX, dashboard, Gitea/Coolify integration, team ops). Credits cover variable AI compute costs (LLM calls across Tier A/B/C, build pipelines, content generation).

### Pricing Tiers

| Tier | Price | Templates | Projects | Credits included | Target |
|---|---|---|---|---|---|
| **Free** | $0/mo | Starter only | 1 active | 50 credits/mo | Evaluators |
| **Builder** | $49/mo | Starter + Builder | 3 active | 500 credits/mo | Solo founders |
| **Pro** | $149/mo | All templates | Unlimited | 2,000 credits/mo | Active builders + agencies |
| **Enterprise** | Custom | Custom + private | Unlimited | Custom | Teams, compliance needs |

**Credit top-ups:** Available at $0.10/credit (10 credits = $1). Minimum top-up: $10.

### AI Cost Structure (Internal)

Three-tier model routing:
- **Tier A (40% of calls):** Gemini Flash-class — orchestration, summaries, routing, log parsing. ~$0.0001/1k tokens.
- **Tier B (45% of calls):** Mid-tier coding model (GLM-5 or Qwen Coder via Vertex) — code gen, feature building, refactors. ~$0.002/1k tokens.
- **Tier C (15% of calls):** Premium escalation (Claude Sonnet or Gemini Pro) — architecture decisions, high-risk changes, repeated failures. ~$0.015/1k tokens.

**Credit pricing:** Each credit = approximately $0.10 of platform value (AI + margin). Exact credit cost per action surfaced to user before triggering high-cost tasks.

### Cost Estimate Per Build (v1 template-based app)
| Item | Estimated cost |
|---|---|
| Discover/Architect/Design/Market phases (Tier A/B) | ~$0.80 |
| Full code generation (Tier B, ~8,000 LOC) | ~$2.40 |
| Deployment orchestration | ~$0.20 |
| **Total per build** | **~$3.40** |
| **Charged at markup** | **~40 credits ($4.00)** |

At $49/mo (500 credits), a Builder subscriber can complete ~12 full builds per month within plan.

---

## 9. Integrations & External Dependencies

| Integration | Purpose | Notes |
|---|---|---|
| **Gitea (self-hosted)** | Code storage and version control for every built project | Required. All repos pushed here on build completion. |
| **Coolify (self-hosted)** | Build pipeline, deployment, container orchestration | Required. Auto-deploys on Gitea push. |
| **Google Vertex AI** | Tier A/B/C model calls | Primary AI provider. Gemini Flash (A), mid-tier MaaS (B), Claude/Gemini Pro (C). |
| **Stripe** | Subscription billing for vibn platform fees | Customers pay vibn via Stripe. Stripe not required in built apps unless user selects it in Architect. |
| **Resend / Postmark** | Transactional emails (signup, password reset, notifications) | For vibn platform emails. Built apps may use same if email selected in Architect. |
| **PostgreSQL** | Platform database (conversations, project state, tasks, billing) | Self-hosted in hot tier. |
| **Redis** | Job queue, pubsub for build pipeline events | Optional but recommended for build reliability. |

**No external data import requirements in v1.** Built apps start fresh; no migration tooling in scope.

---

## 10. Non-Functional Requirements

### Performance
- Wizard phase transitions: < 200ms
- Live design mock updates: < 300ms after style selection
- Build pipeline: Median < 15 minutes for a template-based app
- Dashboard load: < 1 second (projects list)
- AI chat response: First token within 1 second

### Platform
- **Primary:** Web (desktop browser) — Chrome, Safari, Firefox, Edge
- **Secondary:** Responsive mobile web for dashboard viewing (not wizard)
- **Not in scope v1:** Native iOS/Android apps

### Accessibility
- WCAG 2.1 AA compliance for all interactive elements
- Keyboard navigable wizard phases
- Sufficient color contrast across all design tokens (ink on paper palette passes AA)

### Compliance & Regulatory
- **GDPR:** Data processing agreements available for EU users. User data deletable on request.
- **PCI DSS:** vibn does not store card data; handled entirely by Stripe.
- **HIPAA:** Out of scope for v1. No healthcare data processed.
- **SOC 2:** Target for Enterprise tier; not required at launch.

### Data Privacy & Security
- All user project code stored in user's own Gitea instance (user owns their data)
- vibn platform database stores: conversation history, project metadata, billing records
- AI conversations not used for model training (Vertex API terms)
- Secrets (API keys, Stripe keys) stored encrypted, never logged
- Build logs retained for 30 days, then purged

### Scalability Assumptions (v1)
- Designed for 500 MAU at launch
- Build pipeline: 20 concurrent builds supported
- Horizontal scaling of worker pool via Coolify

---

## 11. Risks & Mitigations

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Build success rate < 85% due to AI code quality | Medium | High | Template-first architecture dramatically reduces open-ended generation. Fallback retry mechanism. Tiered escalation to better model on repeated failure. |
| LLM costs exceed credit pricing margins | Medium | High | 3-tier routing keeps 85% of calls on cheap models. Per-step token limits. Aggressive context summarization. Max retries cap (3). |
| Users don't understand "credits" model | High | Medium | In-app cost estimation before every build. Plain-English explanations. "This build will use ~40 credits." Spending caps user-configurable. |
| Coolify/Gitea self-hosted infra reliability | Low | High | Hot tier always-on. Healthcheck monitoring. Auto-restart policies. Graceful failure messaging in build UI. |
| Non-technical users abandon wizard mid-way | High | Medium | Progress auto-saved per phase. Resume from dashboard. Floating AI chat for unblocking. Encourage "good enough" answers — no wrong answers in Discover. |
| Scope creep in wizard phases | Medium | Medium | Each phase has a strict set of decisions. No free-form architecture input. Locked hosting block prevents deviation. |
| Competition from Replit, Bolt, v0 | High | Medium | Differentiator is self-hosted infra (user owns everything), template-first (higher success rate), and the end-to-end wizard (no coding literacy required). |
| Agency use case underperforms | Low | Low | Agency (Producer persona) is v1 secondary target. Builder persona is primary. Billing screen can be iterated post-launch. |

---

## 12. Open Questions & Assumptions

### Open Questions

1. **Template library scope at launch:** How many starter templates exist at v1 launch? What are they? (Minimum: SaaS CRUD + landing page. What else?)
2. **Subdomain structure:** Are projects deployed to `[project-name].vibn.app` or `[user-slug]-[project].vibn.app`? (Collision risk if single namespace.)
3. **Build pipeline timing:** Is 15-minute median build time achievable for first template? What's the P95?
4. **Gitea/Coolify provisioning:** Is each user getting their own Gitea org? How are Coolify environments namespaced per user?
5. **Free tier limits:** Should free tier require a credit card? (Conversion vs. abuse risk tradeoff.)
6. **Change requests post-launch:** How are iterative changes billed? Per-change credit cost, or separate workflow?
7. **Marketing autopilot publishing:** In v1, does AI content require manual approval before publishing, or is auto-publish available?
8. **Wizard re-entry:** Can a user go back and redo an earlier phase after completing Build? Does this trigger a rebuild?

### Assumptions Made

- vibn's Gitea and Coolify infrastructure are already operational and stable before v1 user onboarding begins.
- Template-based builds (vs. blank-page builds) keep success rates above 85%.
- Non-technical founders are willing to pay $49–$149/month for a solution that reliably delivers a live product.
- The 6-phase wizard is completable in one sitting (~20–30 minutes) for a user with a clear idea.
- Vertex AI API access and model availability (Gemini Flash, mid-tier MaaS) is stable and within budget.
- Users do not need to understand or manage their Gitea/Coolify infrastructure directly — vibn abstracts it entirely.
- The primary acquisition channel for v1 is content marketing and founder communities (not paid ads).

---

## 13. Appendix

### Glossary

| Term | Definition |
|---|---|
| **Build** | The automated process of AI generating code, committing to Gitea, and deploying via Coolify |
| **Wizard** | The 6-phase guided flow: Discover → Architect → Design → Market → Build |
| **Phase** | A single stage of the wizard, each producing a specific artifact |
| **Template** | A pre-built starter codebase that vibn AI builds upon instead of generating from scratch |
| **Credits** | vibn's unit of AI compute consumption; consumed during builds, content generation, and chat |
| **Hot tier** | Always-running shared infrastructure (API gateway, orchestrator, Postgres, Redis, Gitea, Coolify) |
| **Cold tier** | Per-user on-demand containers (agent workspace instances, hibernated when inactive) |
| **Tier A/B/C** | Three levels of AI model quality/cost, automatically routed by the orchestrator based on task complexity |
| **Producer** | A vibn user building products for clients (agency use case) |
| **Builder** | A vibn user building a product for themselves (founder use case) |
| **PRD** | Product Requirements Document — the structured output of the Discover phase |
| **Gitea** | Self-hosted open-source Git service; stores all project codebases |
| **Coolify** | Self-hosted deployment platform; builds and runs all deployed apps |

### Reference Materials
- Product strategy document: `product-idea-a.md`
- Builder wizard UI prototype: `preview-assist-ui/src/App.jsx`
- Marketing website prototype: `preview-assist-ui/src/Website.jsx`
- Dashboard prototype: `preview-assist-ui/src/Dashboard.jsx`
- PRD agent system prompt: `prd-agent-prompt.pdf`

### Competitor Reference
- **Bolt.new / Lovable:** AI coding from scratch; no deployment, no templates, requires iteration by user
- **Replit:** Strong coding environment; technical literacy required; no guided wizard
- **Webflow:** No-code UI builder; no real backend; visual but limited
- **Bubble:** No-code with backend; steep learning curve; proprietary lock-in
- **v0 (Vercel):** UI generation only; no deployment, no product planning
- **Agencies:** Custom development; 6–12 month timelines; $50k–$200k budgets