# KAI Dual-World Platform Goal

| | |
|---|---|
| **Status** | VISION LOCK + Phase 0/1 slice |
| **Owner intent** | Account → Avatar (you) with public/private data; 2D Oracle dashboard + 3D KAIVERSE are the **same world** at different speeds/dimensions (PS Home / No Man's Sky feel). |
| **Related** | Guest feed/shorts/subscribe, plan-tiers, KAIVERSE quest design, social-agents |

---

## Core idea (owner words, cleaned)

### 1. Avatar = you (not an autonomous AI)

On create account / Me:

- User creates an **Avatar** (today's "Create Agent" product surface — rename in UX to Avatar).
- Avatar has **bio + identity** (DiceBear / generated look you liked).
- **Public** fields: visible to others (name, handle, public bio, avatar art, home planet label).
- **Private** fields: only that user (email, private notes, private interests, settings) — privacy rights.

This is **not** an autonomous fleet bot. It is **their body/persona** in the platform.

### 2. Two dimensions, one world

| Dimension | What it is | Movement feel |
|-----------|------------|---------------|
| **2D — Oracle dashboard** | Menus, Feed, Shorts, Chat, Me, Subscribe | **God / teleport** — tab jumps = instant travel across the map of your home planet / network |
| **3D — KAIVERSE** | Fly/walk cosmos, realtime presence | **Embodied** — fly, walk, land; slower, spatial, "really there" |

Same places exist in both forms (easter eggs can link 2D spot ↔ 3D coordinates).

### 3. What you do in 2D shows in 3D

- Avatar is **not autonomous**, but **presence mirrors activity**:
  - On Home Feed → avatar "at home planet / social district"
  - In Chat → near social hub / radio
  - In KAIVERSE tab → realtime body in 3D
- 2D = high-speed navigation of the same graph; 3D = real-time traversal.

### 4. Content pillars (both dimensions over time)

Missions, quests, adventures, Battle Royale (cosmos), shops, houses, places (area of sight), easter eggs 2D+3D, multiplayer social.

Quest spine already designed: `KAIVERSE-QUEST-SYSTEM-DESIGN.md` (errors→quests; public = explorer tier).

### 5. Home planet metaphor

- Each user/AI has a **home planet** (or district).
- Dashboard **tabs/pages** = locations on that planet (or linked places).
- KAIVERSE = the spatial realization of those places.

---

## Mapping to current code

| Concept | Today | Gap |
|---------|--------|-----|
| Avatar identity | `/api/social-agents` + DiceBear | Still labeled "agent"; needs **isAvatar / primary** + public/private split |
| Profile public | `/api/me/profile` bio/etc. | Needs explicit public vs private schema |
| Private notes | tenant notes | Keep private-only |
| KAIVERSE body | Fleet planets / hard-part places | User avatar mesh/presence not wired as "you" |
| 2D teleport | View switches | Not yet mapped to place ids |
| 3D realtime | kaiverse.js flight | Must not break first-person feel; avatar additive |
| Quests | Design doc only | Not fully playable loop |

---

## Phased build

### Phase 0 — Language + privacy model (now)
- UX: **Your Avatar** (primary social persona), not "mystery agent".
- Public vs private field lists server-side.
- One primary avatar per user (or first agent = avatar).

### Phase 1 — Presence bridge
- `presence: { view, placeId, mode: 'god'|'embodied', updatedAt }`
- Dashboard view changes update presence (god teleport).
- KAIVERSE polls presence for other users (and self marker).

### Phase 2 — 3D avatar body
- Additive full-body / ship avatar from avatar seed (no nsUpdateCamera rewrite).
- Mirror position when in 3D; ghost/teleport trail when 2D-only.

### Phase 3 — Place graph
- Map Home / Chat / Shorts / Subscribe / KAIVERSE → place nodes on home planet.
- Easter egg links 2D UI coords ↔ 3D positions.

### Phase 4 — Play systems
- Quests/missions (explorer-safe), shops, houses, BR later — gated by plan tier.

---

## Non-goals (immediate)

- Autonomous agent that acts without the user.
- Breaking first-person KAIVERSE controls.
- Full BR / economy in one shot.
- Cross-tenant private data leaks.

---

## Success (Phase 0–1)

1. User understands Avatar = me (public/private).
2. Create/list shows primary avatar clearly.
3. Presence API records current 2D "place" (view).
4. Doc + API ready for 3D body attach later.

## Phase 2–3 shipped (2026-07-16)

- `shared/dual-world-places.mjs` — place graph + easter eggs + lat/lon
- `GET /api/social/world-map` — guest-readable map
- Presence enriched with planetHint/lat/lon for 3D anchors
- `kaiverse.js`: `nsUpdateUserAvatars` additive body/ghost markers from presence (no flight control edits)
- Guest Me tab: home-planet map buttons (2D god-teleport) + dual-world copy
- Flag `window.KAIVERSE_USER_AVATARS=false` to disable 3D avatars