# KAI-ECOSYSTEM-ECONOMY-GOAL.md

| | |
|---|---|
| **Status** | **RELOCKED 2026-07-16** — Free / Explorer $10 / Creator $19 / Builder $29 / Team $75 / Enterprise $499 + thinking modes; payments still shadow |
| **Author** | Owner (Ryan) + pricing session 2026-07-16 (relock) |
| **Scope** | How the public KAI platform prices access: freemium tiers, thinking modes, Kai Credits, packs, Spaces gates. Metering + Stripe later. |
| **Code** | `tools/oracle-discord/shared/plan-tiers.mjs`, user `plan` field, `GET /api/plans`, `/api/me.plan`, `/api/feature-gate` |
| **Depends on** | Guest accounts (Track 2). Metering (Track 3). Payments (Track 4). Spaces/settings goal. |

---

## Design intent (owner)

You are **not** powering an industrial plant. Ops = you + whoever you pay to manage KAI. Hybrid local+cloud keeps variable cost low → **cheap accessible tiers**, volume over gouging, still healthy margin.

---

## Two clocks (important)

| Clock | What it is | Why |
|-------|------------|-----|
| **Billing** | **Monthly** (or annual −20%) | You subscribe / renew once a month. Not a weekly fee. |
| **Usage pace** | **Weekly allowance** (Claude-style) | Heavy use only burns *this week’s* credits. Next week refills. Stops binge-emptying the whole month by day 7, so people don’t *have* to buy packs mid-month. |

Upgrading the plan does two things at once:
1. **More weekly credits** (and usually better rollover).
2. **More privileges** — ecosystem features only that tier (and above) unlock. Lower tiers never get the “good stuff.”

Packs ($4–$35) are **overflow only**. Dashboard should hint: often a few dollars more for an **upgrade** beats a pack (more credits *and* privileges).

---

## Locked tiers (canonical — 2026-07-16 relock)

| Tier | Monthly bill | Annual (~20% off) | Credits / **week** | Thinking modes | Best for |
|------|--------------|-------------------|--------------------|----------------|----------|
| **Free** | **$0** | — | 0 (social only) | low only | Social feed/chat + KAIVERSE/topology **explore** — **no Full Fleet** |
| **Explorer** | **$10** | $96/yr | 200k | **low + mid** | First paid tools + light AI |
| **Creator** | **$19** | $182/yr | 400k | low + mid + **limited high** (taste) | Daily creators, more usage |
| **Builder** | **$29** | $278/yr | 1.2M | low…**high + extra** | Serious projects, 3 seats |
| **Team** | **$75** | $720/yr | 4.7M | … + **max** (fleet at Extra) | Small teams, Roundtable |
| **Enterprise** | **Configure** (from ~$150, always **> Team $75**) | Custom quote | Scales | **max** + isolate stack | Company/research — pay for seats/storage/compute/modules |

**Hard rules:**
- Free = social media + explore KAIVERSE/topology only. **No Full Fleet.**  
- **3D cannot bypass 2D** — `canAccessFeature` / `assertNoFreeFleetBypass` is the same gate for both surfaces.  
- Team is heavy shared; **Enterprise** is `pricingModel: 'configurable'` + `separateServerStack` — monthly = `estimateEnterpriseMonthly(config)` (seats, storage, network, compute, fleet/Roundtable/CAD modules). Always **above Team $75**; large configs can be **hundreds–thousands**/mo.  
- Thinking: low/mid on Explorer; Creator adds limited **high** as taste of Builder; Builder **extra**; Team/Enterprise **max**.

**Privilege ladder (summary):** Free social/explore → Explorer tools/Spaces public → Creator private Spaces + high taste → Builder extra + collab → Team max fleet/Roundtable → Enterprise max + stack isolation.

**Kai Credits** = unified unit (chat + tools). Tools cost **more**. Local mode saves credits.

### BYOK linked AIs (locked 2026-07-21 — `WORKSPACE-SYNCED-AI-RSHL-GOAL.md`)

When the user **syncs their own paid AI** (Claude / ChatGPT / Gemini key / OpenRouter / custom):

| We charge | We do **not** charge |
|---|---|
| Plan subscription (the glass) | Their provider’s **model tokens** |
| Heavy tools (image, shorts, AI web-search, job compute) | Re-sending bloated full-chat history (we never do this) |
| Host-sponsored models (our Antigravity / fleet keys) | — |

**RSHL 1-turn:** each API call is a new single-turn chat; ecosystem holds session memory so cost stays ~flat per turn. Credits action: `byok_chat` = **0**.

**Owned custom AIs:** Builder+ (`custom_agents`); Team/Enterprise scale multi-agent citizens (profile, feed, Kaiverse).

**Seat limits:** Free/Explorer/Creator 1 · Builder 3 · Team 15 · Enterprise 100

---

## Host admin vs workspace admin (do not confuse)

| | **Host / platform** | **Workspace (product)** |
|--|---------------------|-------------------------|
| Who | Ryan (owner), Taz-style host ops | Paying user who bought Creator/Builder/Team |
| What they run | Industrial Oracle OS, fleet, secrets, all tenants | **Their** business + social workspace only |
| Role names | `owner` / `admin` (server ROLES) | `workspace_owner` / `workspace_admin` / `workspace_member` / `workspace_viewer` |
| Invites | N/A (ops mint host users) | Workspace admin invites people **into that paid workspace** on the platform |
| Sees host telemetry / industrial AIs? | Yes | **Never** |

Think: “I’m the admin of *my* company workspace on KAI” — like a creator-admin — not “I run the whole KAI plant.”

Platform is **business + social + tools in one**: the workspace is the container; invites bring coworkers/friends into *that* container; plan tier decides credits, privilege surface, and seat count.

**Seat limits (canonical):** Free 1 · Explorer 1 · Creator 1 · Builder 3 · Team 15 · Enterprise 100  

Invite API / seat enforcement = Track 3–4 (not live yet). Shape lives in `plan-tiers.mjs` (`WORKSPACE_ROLES`, `WORKSPACE_SEAT_LIMITS`).

**Default plan for new accounts:** `free` (`DEFAULT_PLAN_ID`).

---

## Simple money answers (from owner Q&A)

### 10k paying users, 2 months, **no packs**
Balanced mix (~60% Creator / 30% Builder / 10% Team) at list midpoints:

| Segment | Users | Price | MRR |
|---------|-------|-------|-----|
| Creator | 6,000 | $10 | $60k |
| Builder | 3,000 | $29 | $87k |
| Team | 1,000 | $75 | $75k |
| **Total** | **10k** | | **≈ $222k / mo** |

**Two months ≈ $440k–$460k** subscription only (staggered first month slightly less).

Code helper: `estimateMrr({ payingUsers: 10000 })` in `plan-tiers.mjs`.

### ~1M total users (free + paid), 8–12% conversion
- Paid ≈ 80k–120k  
- MRR ballpark **$1.6M–$2.8M+** depending on mix  
- Plus packs/marketplace later  

### AI / data flywheel (not static LLM)
At scale, consented interaction data feeds lattice growth + ternary train cycles (today ~100M on A100 multi-day). Hybrid + continuous learning is the moat; pricing stays cheap because local offload + lean ops.

---

## What's free vs what costs (metering classes)

| Activity | Charged? |
|----------|----------|
| AI ↔ AI internal | **Free** to user |
| User ↔ AI chat | Credits |
| Tasks / tools / skills | Credits (higher multiplier) |
| Ongoing sessions | Credits over time |
| KAIVERSE enter | Free; actions may cost small credits |

Bill **outcome**, not idle fleet capacity.

---

## Build order

1. **Track 1** — product worth paying for (conversation quality).  
2. **Track 2** — accounts / guest isolation *(largely done)*.  
3. **Track 3** — metering + wallet (shadow first: measure, don't charge).  
4. **Track 4** — real payments (Stripe etc.), legal/ToS/tax.

### Scaffold shipped (this update)
- `shared/plan-tiers.mjs` — tier + pack catalog + MRR estimate  
- New guests get `plan: 'explorer'`  
- `GET /api/plans` — public catalog (`billing.status: 'shadow'`)  
- `/api/me` includes `plan` + `planCard`  
- Owner/admin UI plan shown as `team` (host, not billed)

### Not done yet
- Stripe / checkout / webhooks  
- Credit debit on chat/tools  
- Enforce limits when balance hits 0  
- Dashboard upgrade UI / pricing page chrome  

---

## Rules

- **Meter first, charge later** during Alpha.  
- **Never** put payment secrets in the client.  
- Guests never see industrial host cost internals.  
- Annual = 15–20% off list (catalog uses 20%).  
- Numbers above are **list policy** — change only in `plan-tiers.mjs` + this doc together.