# KAI-SPACES-AND-USER-SETTINGS-GOAL.md

| | |
|---|---|
| **Status** | **GOAL LOCKED (design)** — implementation phased; not fully built |
| **Author** | Owner (Ryan) + product session 2026-07-16 |
| **Version** | v1.0 · companion to economy, dual-world, guest social, host settings |
| **Code touchpoints (today)** | `oracle.html` (composer, guest rail, Me/Settings modals), `guest-access.mjs`, `plan-tiers.mjs`, `command-center-server.mjs` (channels/DMs/turn), host Config view |
| **Related goals** | `KAI-ECOSYSTEM-ECONOMY-GOAL.md` (tiers/credits/seats), `ORACLE-OS-SETTINGS-GOAL.md` (**host** OS control), `ORACLE-OS-CONTROL-PANEL-SETTINGS-GOAL.md` (**user Settings panel inventory + rebuild phases**), `KAI-DUAL-WORLD-PLATFORM-GOAL.md`, `RELEASE-READINESS.md` |

---

## 0. Why this doc is huge (and must stay one place)

Owner intent (verbatim themes):

1. **More channels than the fixed Discord catalog** — users create **public / private** rooms they **host**, **invite**, or leave **open** so anyone on that server/workspace can join (if they enable open join).
2. These are **Spaces** inside the **ecosystem / group / workspace** — not host industrial channels.
3. **Tiers + credits still apply** to create, invite seats, media, AI participation, storage.
4. **Composer (text + Send)** must only appear when the user is in a **textable** context — not Metrics, not Channel Settings, not Threads list until a thread is open.
5. **Settings must be vastly improved** — **user settings** (Discord-class, cross-channel, cross-platform), **not** server/host ops settings.
6. Build a real **Settings area**: **ecosystem settings** (workspace/Space admin) **and** **user settings** (every member). Contextual, huge, complete.

This goal is the **source of truth** for that product surface.  
`ORACLE-OS-SETTINGS-GOAL.md` remains the **host industrial** control plane (fleet, `.env`, rebuild). **Never mix the two UIs.**

---

## 1. Vocabulary (lock these words)

| Term | Meaning |
|------|---------|
| **Host / platform** | Ryan’s Oracle OS plant: industrial AIs, secrets, fleet, global Discord bridge |
| **Workspace (tenant)** | A paying (or free Explorer) user’s **ecosystem container** — their social + business room on KAI |
| **Space** | A **user-created channel** (or channel set) **inside** a workspace: text, voice, video, or hybrid |
| **Server (product sense)** | The workspace’s public face — people “join a server” = join a workspace/community, then join Spaces |
| **User settings** | Preferences + privacy + notifications + appearance + accessibility for **this person** (follow them everywhere) |
| **Ecosystem / workspace settings** | Admin controls for **this workspace** (roles, invites, default Spaces, moderation, billing seat list) |
| **Space settings** | Per-Space: public/private, join mode, slowmode, AI allowed, credit drain rules |
| **Host OS Settings** | Operator-only (providers, restart, industrial) — `ORACLE-OS-SETTINGS-GOAL.md` |

**Never** show Host OS Settings to public accounts.  
**Never** put workspace billing next to Kai Coder model swaps.

---

## 2. Spaces — product vision

### 2.1 What a Space is

A **Space** is a first-class chat room the **workspace** owns:

- **Text** (default), optional **voice**, optional **video** (callable only when Space allows it — same rule as today’s ai-social-chat ≠ every channel).
- Identity: `spaceId`, display name, topic, icon/emoji, color, createdBy, workspaceId.
- **Visibility**
  - `public` — listed in workspace directory; anyone in workspace can open (and optionally join history).
  - `private` — invite-only or role-gated; not in public directory.
- **Join mode**
  - `open` — any workspace member can join without invite.
  - `request` — join requests / approvals.
  - `invite` — must be invited (link or @user).
  - `locked` — role only (e.g. `@mods`).
- **Discoverability**
  - Workspace directory, “Browse Spaces”, search.
  - Optional **server-wide open** flag: if workspace is public-community mode, open Spaces appear to any logged-in platform user who **joins the workspace** first (still seats/credits).

### 2.2 Hosting model

| Role | Can do |
|------|--------|
| **Space host** (creator or delegated) | Rename, delete, permissions, invite, open/close join, pin, slowmode, AI toggle |
| **Workspace admin** | Create Spaces (tier-gated), transfer host, audit |
| **Member** | Chat if permitted, leave, mute, personal notification overrides |
| **Guest (product role)** | Same as member of **their** workspace; **never** host industrial Discord SYS channels |

Host industrial Discord channels (`sensitive-info`, `kai-training`, …) stay **platform-owned**. Spaces are **tenant-owned** and stored under tenant state, not the host catalog alone.

### 2.3 Relationship to today’s catalog

| Today | Tomorrow |
|-------|----------|
| Fixed `CHANNEL_CATALOG` (Discord-backed) | Still exists as **platform / federation** social rails (`ai-social-chat`, voices) |
| Guest public allowlist | Keep for **platform social**; Spaces are **additional** per-workspace |
| DMs with social AIs | Remain DMs; Spaces are multi-user rooms |
| Left rail: Friends / AI / Public channels / Workspace | **Public channels** expands to: **Platform social** + **My Spaces** + **Workspace directory** |

### 2.4 Invites

- Deep link: `/join/space/{spaceId}?token=…` or invite code.
- Invite consumes **seat** only if target is not already a workspace member (joining a Space inside a workspace you already belong to = free join).
- Inviting a brand-new user to the **workspace** = seat rules from economy goal (Explorer 1 / Creator 1 / Builder 3 / Team 15).
- Invite types: user handle, email (later), link with expiry, max uses.

### 2.5 Credits & tiers (bind to economy goal)

Creating / running Spaces is not free forever:

| Action | Credits / privilege gate (initial proposal — tune later) |
|--------|----------------------------------------------------------|
| Create Space | Explorer: 1 Space free; Creator: more; Builder/Team: many + categories |
| Open join (public Space) | Allowed Creator+; Explorer open Spaces limited / rate-limited |
| AI agent in Space | Per-message tool costs; local mode cheaper |
| Voice / video minutes | Higher credit burn; tier caps |
| Storage (uploads, images) | Kai Cloud GB from plan card |
| Private Spaces | Creator+ |
| Role hierarchies / categories | Builder+ |
| Custom bot persona in Space | Team |

UI must always show **why** a create button is disabled (“Upgrade to Creator to host private Spaces”) — never a silent fail.

### 2.6 Categories (Discord-like)

```
Workspace “Ada’s Lab”
  ├── Category: Lobby
  │     # welcome (public, open)
  │     # rules (public, read-only for non-mods)
  ├── Category: Work
  │     # sprint (private, invite)
  │     🔊 stand-up voice (callable)
  └── Category: Social
        # memes (public, open)
        📹 hangout (video allowed)
```

### 2.7 Message model (Spaces)

- Messages stored per `spaceId` (jsonl or SQLite later), tenant-scoped.
- Optional **bridge** to Discord for platform social only (existing CHANNEL_RELAY).
- User Spaces **default off Discord** (KAI-native) so tenants don’t need a Discord bot for every room.
- Reactions, replies, threads (later phases) mirror feed engagement patterns already shipping on social posts.

### 2.8 Phases for Spaces

| Phase | Deliverable | Done when |
|-------|-------------|-----------|
| **S0** | Goal + composer textable-only | Done (composer textable-only) |
| **S1** | Data model + APIs: create/list/join Space (tenant file) | **Shipped v9.10.293** — create/list/join + rail; message body next |
| **S2** | Left rail “My Spaces” + open directory | UI discoverable |
| **S3** | Private + invite links | Invite flow works |
| **S4** | Voice/video flags per Space | Call icons only when allowed |
| **S5** | Categories, roles, slowmode, audit | Discord-class moderation basics |
| **S6** | Credit meters + plan gates live | Economy goal metering hooks |

---

## 3. Composer rule (ship immediately / keep forever)

**Principle:** The text box + Send exist only when the user is looking at something they can **type into**.

| Context | Composer |
|---------|----------|
| DM open | **Show** |
| Channel · **Chat** tab | **Show** (if not system-only / not voice) |
| Channel · **Threads** · list only | **Hide** |
| Channel · **Threads** · thread open | **Show** (reply in thread) |
| Channel · **Metrics** | **Hide** |
| Channel · **Settings** (channel) | **Hide** |
| Voice room | **Hide** (use Join Voice) |
| Home / Me / KAIVERSE / Web / Topology | **Hide** |

Implementation: `syncCmdBar()` + `activeThreadId` + `activeSubTab` (`oracle.html`).  
Any new pane must register whether it is `textable`.

---

## 4. Settings architecture — three trees, one shell

### 4.1 Shell: “Settings” app surface

One entry for users (Me → Settings, right rail Account → Settings, mobile gear):

```
Settings
├── 👤 My account          ← USER settings (always)
├── 🔔 Notifications
├── 🎨 Appearance
├── 💬 Chat & media
├── 🔐 Privacy & safety
├── ♿ Accessibility
├── 🌐 Language & region
├── 🧩 Connections         (Discord link later, OAuth, devices)
├── 💳 Plan & credits      (economy — self only)
├── 🏠 My workspaces       (list + switch)
└── 🛠 Workspace admin     (only if workspace_admin+)  ← ECOSYSTEM settings
      ├── Overview
      ├── Members & seats
      ├── Roles
      ├── Spaces
      ├── Invites
      ├── Moderation
      ├── Integrations
      └── Billing (payer)
```

**Host never appears here.** Host uses Config / Root Admin.

### 4.2 USER settings (Discord-class, cross-channel)

These follow the **user** across every Space, DM, device, and platform client (web, mobile later, native later).

#### A. My account
- Display name, handle, bio, pronouns, avatar, banner
- Email (verified), password / passkeys (later)
- Sessions: devices list, revoke
- Delete account / export data (GDPR-shaped later)

#### B. Notifications (per-channel overrides like Discord)
- Global: all / mentions / nothing
- Per-Space mute, suppress @everyone, mobile push (later)
- DM notifications
- Quiet hours
- Unread badge behavior (already started on Chats tab)

#### C. Appearance
- Theme: system / dark / light / high-contrast (stub exists — **must** land here, not only a disabled select)
- Density: compact / normal / cozy (exists)
- Font scale
- Message display: compact vs cozy bubbles
- Accent color (optional)
- Reduced motion

#### D. Chat & media
- Desktop chat: dock vs full messenger (exists)
- Enter to send vs Ctrl+Enter
- Media autoplay, link previews
- Spoiler defaults
- Show/hide embeds

#### E. Privacy & safety
- Who can DM me (everyone / friends / nobody)
- Who can add me to Spaces
- Online status visibility
- Read receipts (later)
- Block / ignore list
- 2FA (later)

#### F. Accessibility
- Screen reader labels audit
- Keyboard shortcuts map
- Color blind safe palette
- Captions defaults for voice/video

#### G. Language & region
- UI language
- Timezone (auto from device + override)
- Clock 12/24 (top bar already local)

#### H. Connections
- Linked Discord (optional)
- Kai Cloud devices
- Node federation later (guest node goal)

#### I. Plan & credits
- Current plan card, weekly remaining, upgrade CTA
- Pack purchase (when live)
- Usage breakdown (chat vs tools vs voice)

### 4.3 ECOSYSTEM / workspace settings (admin)

Only for `workspace_owner` / `workspace_admin`:

| Section | Contents |
|---------|----------|
| **Overview** | Name, icon, description, vanity URL, public/private community |
| **Members & seats** | Roster, roles, remove, seat usage vs plan limit |
| **Roles** | Permissions matrix (manage Spaces, invite, kick, pin, manage messages) |
| **Spaces** | Create/archive, default Space, ordering, categories |
| **Invites** | Create invite, revoke, audit |
| **Moderation** | Automod rules (later), report queue, word filters |
| **Integrations** | Webhooks, AI social agents allowed in this workspace |
| **Billing** | Plan change, invoices (Stripe later) — **workspace payer only** |

### 4.4 Per-Space settings (host of that Space)

- Name, topic, icon  
- Visibility + join mode  
- Slowmode  
- Who can post / attach / use AI  
- Callable (voice/video icons)  
- Archive / delete  
- Transfer host  

### 4.5 Channel Settings tab today vs tomorrow

| Today (host) | Tomorrow (user) |
|--------------|-----------------|
| Allowed speakers chips for industrial bots | **Your** mute/notify for this Space |
| Root-ish status | Notification level for this Space |
| Engine config leakage risk | **No** provider/model for public users |

Per-channel **user** overrides live under Settings → Notifications → channel list **and** as a lightweight panel when you open Space Settings as a **member** (not admin).

---

## 5. Cross-platform parity

Same settings schema, different chrome:

| Client | Settings shell |
|--------|----------------|
| **Web desktop** | Full left nav Settings app |
| **Web mobile** | Full-screen Settings stack (no tiny accordion only) |
| **Native later** | Same API: `GET/PATCH /api/me/settings` |
| **KAIVERSE HUD later** | Subset: mute, push, presence mode |

**Single source of truth:** `state/tenants/{tid}/user_settings.json` + server merge with defaults.  
Never only `localStorage` for privacy/notification truth (localStorage ok for pure UI chrome).

---

## 6. API sketch (implementation target)

### Spaces
```
GET    /api/spaces                 # my spaces + directory (scoped)
POST   /api/spaces                 # create { name, visibility, joinMode }
GET    /api/spaces/:id
PATCH  /api/spaces/:id
POST   /api/spaces/:id/join
POST   /api/spaces/:id/leave
POST   /api/spaces/:id/invites
GET    /api/spaces/:id/messages
POST   /api/spaces/:id/messages
```

### User settings
```
GET    /api/me/settings
PATCH  /api/me/settings            # deep-merge partial
GET    /api/me/settings/schema     # for UI generation (optional)
```

### Workspace admin
```
GET/PATCH /api/workspace
GET/POST  /api/workspace/members
GET/POST  /api/workspace/roles
...
```

Guest allowlist: add exact paths as they ship. Deny host prefixes forever.

### Credits hooks
Every `POST /api/spaces` and message-with-AI path checks plan + weekly allowance (economy goal Track 3).

---

## 7. UI inventory — what must exist

### 7.1 Settings home (user)
- Search settings (filter tree)
- Sections as cards or Discord-style left rail
- Dirty state + Save / Reset per section
- “Open full Settings” from Me, Explore rail, profile menu

### 7.2 Create Space wizard
1. Name + icon  
2. Public / private  
3. Open / invite / request  
4. Text only vs voice-capable  
5. Confirm credit/privilege gate  

### 7.3 Composer discipline
- Covered in §3; regression tests: open Metrics → no cmdbar; open thread list → no cmdbar; open thread → cmdbar.

### 7.4 Host Config stays separate
- Rail Config / Antigravity remain **host-only**
- Rename mental model: “Oracle OS Settings” = host; “Settings” = user+ecosystem

---

## 8. Security & isolation

- Tenant isolation: Space messages never leak across `tenantId`.
- Private Spaces: membership check every read/write.
- Invite tokens hashed at rest (same pattern as user tokens).
- Rate limits on create Space / invite spam.
- Guests cannot escalate to host industrial channels via Space API.
- Content moderation hooks (later) before federation.

---

## 9. Relation to dual world / KAIVERSE

- A Space can optionally bind a **placeId** on the home planet (2D god-teleport + 3D landmark).
- “Meeting Space” → KAIVERSE room later.
- Settings → Presence: god vs embodied defaults.

---

## 10. Phased delivery (recommended order)

| Phase | Name | Outcome |
|-------|------|---------|
| **0** | Composer textable-only + this goal | No Send on Metrics/Settings/thread list |
| **1** | User Settings shell (read/write prefs API + UI) | Theme, density, chat mode, notifications globals — **no prompts** |
| **2** | Spaces S1–S2 | Create/list/join + rail |
| **3** | Invites + private Spaces | Real hosting |
| **4** | Workspace admin settings | Seats/roles |
| **5** | Per-Space user notification overrides | Discord parity |
| **6** | Credits enforcement on Spaces | Economy live hooks |
| **7** | Voice/video Space flags + categories | Full product depth |

---

## 11. Explicit non-goals (this goal)

- Replacing host industrial Discord topology.
- Letting public users edit fleet providers / BitNet / rebuild.
- Stripe checkout (still economy Track 4) — Settings shows plan **intent** until then.
- Full native apps (schema must not block them).

---

## 12. Acceptance criteria (owner can tick)

### Spaces
- [ ] User on Creator+ can create a Space in their workspace  
- [ ] Public open Space appears in directory; private does not  
- [ ] Invite link adds member to Space (and workspace if needed, seat-checked)  
- [ ] Credits/privilege denied with clear upgrade copy  
- [ ] Industrial channels never appear as “user Spaces”  

### Composer
- [x] Metrics tab: no text box / Send  
- [x] Channel Settings tab: no text box / Send  
- [x] Threads list: no text box / Send  
- [x] Open thread / Chat / DM: text box shows  

### User settings
- [ ] Single Settings surface reachable without host Config  
- [ ] Preferences persist server-side and apply on second device (when multi-device)  
- [ ] Theme fully implemented (not disabled stub only)  
- [ ] Notification mutes work per Space  
- [ ] No “Guest” branding; account language is first-class user  

### Ecosystem settings
- [ ] Workspace admin can manage members/seats within plan  
- [ ] Non-admins never see billing controls  

---

## 13. Resume / next engineering session

1. Read this doc §10 Phase 0–1.  
2. Keep composer rules when adding panes.  
3. Implement `/api/me/settings` + Settings shell before large Spaces UI.  
4. Spaces S1 only after settings shell exists (create Space from Settings → Spaces or Messages → Create).  
5. Wire plan gates from `plan-tiers.mjs` privilege keys (add `spaces_create`, `spaces_private`, `spaces_open_join` as needed).  
6. Do **not** put Spaces create on host Config view.

---

## 14. Open decisions (owner may flip later)

1. Explorer: **1 free Space** vs **0** (create only on paid)? *Proposal: 1 free public Space.*  
2. Platform-wide “public community Spaces” vs workspace-only directory first? *Proposal: workspace-only first.*  
3. Bridge user Spaces to Discord ever? *Proposal: no by default; opt-in integration later.*  
4. Thread replies from user Spaces credit cost? *Proposal: same as channel message.*  

---

## 15. Changelog of this goal

| Date | Note |
|------|------|
| 2026-07-16 | v1.0 created — Spaces + User/Ecosystem Settings mega-goal; composer textable rule specified; links economy + host settings split |

---

*End of goal. Implementation may take many releases; do not mark “done” because a modal exists. Done = acceptance criteria above.*