KAI-SPACES-AND-USER-SETTINGS-GOAL.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)

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

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

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:

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

---

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.

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:

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

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:

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)

---

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

---

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