BAWES-Universe · BAWES · Aug 11, 2026
diff --git a/docs/universe/features/01-platform/README.md b/docs/universe/features/01-platform/README.md
@@ -0,0 +1,14 @@
+# 01 — Platform
+
+Core infrastructure — the fork, how it's deployed, auth, management APIs, and admin dashboard.
+
+| Feature | Status | What it is |
+|---|---|---|
+| [workadventure-fork](./workadventure-fork/) | 🔵 INHERITED | What we forked from WorkAdventure, what changed |
+| [self-hosting](./self-hosting/) | 🟢 LIVE | Docker Compose, Coolify, env vars, Helm chart |
+| [oidc-auth](./oidc-auth/) | 🟢 LIVE | Authentication via OpenID Connect |
+| [admin-api](./admin-api/) | 🟢 LIVE | REST API for rooms, maps, bots, MCP servers |
+| [orbit](./orbit/) | 🟢 LIVE | Operator admin dashboard — the UI on top of admin-api |
+| [orbit-model](./orbit-model/) | 🟢 LIVE | Community gravity framework — Love × Reach, adapted for Universe |
+
+See also: [02-spatial-world](../02-spatial-world/), [03-ai-bots](../03-ai-bots/), [04-mcp](../04-mcp/)
diff --git a/docs/universe/features/01-platform/admin-api/README.md b/docs/universe/features/01-platform/admin-api/README.md
@@ -0,0 +1,23 @@
+# Admin API
+
+Next.js REST API for managing rooms, maps, bots, and MCP servers. Separate repo from the main Universe fork.
+
+## Endpoints
+
+- **Room CRUD** — create, read, update, delete rooms
+- **Map CRUD** — manage WAM file assignments per room/world
+- **Bot CRUD** — AI provider, system prompt, behavior ([bot-behaviors](../03-ai-bots/bot-behaviors/)), avatar ([bot-avatars](../03-ai-bots/bot-avatars/))
+- **MCP server management** — per-bot MCP server configs ([mcp-server-management](../04-mcp/mcp-server-management/))
+- **Auth:** API key headers + `CORS_ALLOWED_ORIGINS` env var
+
+## Repo
+
+`github.com/BAWES-Universe/workadventure-universe-admin` — `develop` → `main`
+
+Tech stack: Prisma ORM, PostgreSQL, TypeScript, Next.js API routes.
+
+## Related
+
+- [Orbit](./orbit/) — the admin UI that sits on top of this API
+- **[bot-provider-config](../03-ai-bots/bot-provider-config/)** — AI provider config through this API
+- Docs: `docs/others/self-hosting/adminAPI.md`
diff --git a/docs/universe/features/01-platform/oidc-auth/README.md b/docs/universe/features/01-platform/oidc-auth/README.md
@@ -0,0 +1,15 @@
+# OIDC Auth
+
+Authentication via OpenID Connect. Provides user login, session management, and tag-based access control.
+
+## How It Works
+
+- **Production:** External OIDC provider handles login
+- **Development:** Keycloak mock server (user: "User1" / pass: "pwd"), auto-enabled in `docker compose up`
+- **Anonymous mode:** Use `docker-compose-no-oidc.yaml` to disable OIDC for testing
+
+## Related
+
+- [Self-hosting](./self-hosting/) — OIDC env vars
+- [Area zones](../02-spatial-world/area-zones/) — tag-gated access to rooms
+- [Avatar platform](../02-spatial-world/avatar-platform/) — membership-gated sets
diff --git a/docs/universe/features/01-platform/orbit-model/README.md b/docs/universe/features/01-platform/orbit-model/README.md
@@ -0,0 +1,74 @@
+# Orbit Model
+
+**Status:** 🟢 LIVE
+
+A framework for understanding community member gravity — how people move closer to or farther from the center of the Universe based on their actions, not their titles.
+
+The Orbit Model was originally created by **Josh / Orbit Love** ([orbit-model.joshed.io](https://orbit-model.joshed.io/), [github.com/orbit-love/orbit-model](https://github.com/orbit-love/orbit-model)) as a community management framework. Universe adapts and implements it across the ecosystem.
+
+## Original Framework: Gravity = Love × Reach
+
+The core formula. A member's gravity — their pull toward the center — is the product of their **Love** (involvement, responsibility, commitment) and **Reach** (connectedness, visibility, influence).
+
+| Force | What it measures |
+|-------|-----------------|
+| **Love** | Leadership, responsibility, involvement, commitment |
+| **Reach** | Connectedness, visibility, influence, network size |
+
+## Orbit Levels
+
+Members orbit at distances corresponding to their actions and relationships:
+
+| Level | Love | Reach | Who they are |
+|-------|------|-------|-------------|
+| **Advocates** | High | High | Ambassadors, champions — help mobilize and grow |
+| **Contributors** | High | Lower | Invest time in code, docs, feedback, beta tests |
+| **Participants** | Medium | Medium | Active users, event attendees, regular engagers |
+| **Explorers** | Low | Low | Newcomers, passive observers, learners |
+
+## How Universe Adapts the Model
+
+Universe adds **Momentum** as a fourth force: how often and how consistently you engage. Someone who ships often, supports others, and stays aligned has strong gravity and a close orbit. Someone who floats in and out drifts into outer orbit.
+
+| Force | Universe adaptation |
+|-------|-------------------|
+| **Love** | Value, support, contribution to the ecosystem |
+| **Reach** | How far your work or message spreads |
+| **Gravity** | Alignment and resonance with the Universe mission |
+| **Momentum** | Consistency of engagement over time |
+
+## What Orbit Affects in Universe
+
+Orbit is not a badge or rank — it's a reflection of motion. The system gates access with gravity, not hierarchy:
+
+- What quests and opportunities you see
+- How fast AI agents respond to you
+- What signals and requests reach you
+- Who reaches out and why
+- What the system prioritizes around you
+
+It's the hidden architecture behind:
+
+| Area | How Orbit Affects |
+|------|-------------------|
+| **Monkey Education System** | What doors open |
+| **Banana Bank** | Trust and transaction limits |
+| **AI Agents** | Tone, access, scope of responses |
+| **Discord** | How visible your input is |
+
+## Increasing Your Gravity
+
+This is not a point system. No karma to farm. Gravity increases when you:
+
+1. **Contribute signal, not noise** — ship work, support others, add value
+2. **Stay consistent** — one-time sparks fade; sustained engagement builds momentum
+3. **Align with the mission** — the closer your work resonates with the system, the stronger your pull
+4. **Act, don't just orbit ideas** — doing moves you closer than observing
+
+> *"You don't need permission to move closer. Just momentum. The system will feel it."*
+
+## Related
+
+- [Orbit — Operator Admin](./orbit/) — the admin dashboard (separate from the model; they share the "Orbit" name)
+- [Admin API](./admin-api/) — underlies the admin dashboard
+- Credit: [Orbit Model](https://orbit-model.joshed.io/) by Josh / [Orbit Love](https://github.com/orbit-love/orbit-model) (MIT)
diff --git a/docs/universe/features/01-platform/orbit/README.md b/docs/universe/features/01-platform/orbit/README.md
@@ -0,0 +1,20 @@
+# Orbit — Operator Admin
+
+Orbit is the brand name for the operator admin dashboard. It's the UI that universe operators use to manage everything without touching code — worlds, rooms, bots, avatar sets, members, and access rules.
+
+## Capabilities
+
+- **Per-universe dashboard** — every universe instance gets its own Orbit panel
+- **World & room management** — create, archive; set capacity, maps, bots, access rules
+- **Member & role system** — assign membership tags that gate rooms and avatar sets
+- **Area permission editor** — draw restricted zones on maps via UI (see [area-zones](../02-spatial-world/area-zones/))
+- **Avatar set management** — create and assign avatar sets per world, universe, or role (see [avatar-platform](../02-spatial-world/avatar-platform/))
+- **Bot configuration** — name, persona, model, memory, assigned avatar (see [bot-avatars](../03-ai-bots/bot-avatars/), [bot-provider-config](../03-ai-bots/bot-provider-config/))
+- **MCP server management** — add/edit servers per bot, test connections (see [mcp-admin-ui](../04-mcp/mcp-admin-ui/))
+- **Audit logs** — full action trail for governance
+
+## Related
+
+- [Admin API](./admin-api/) — Orbit is the UI layer on top of this API
+- [Orbit Model](./orbit-model/) — the conceptual community gravity framework (separate from the dashboard; they share the "Orbit" name)
+- All [03-ai-bots](../03-ai-bots/) and [04-mcp](../04-mcp/) features
diff --git a/docs/universe/features/01-platform/self-hosting/README.md b/docs/universe/features/01-platform/self-hosting/README.md
@@ -0,0 +1,28 @@
+# Self-Hosting
+
+How Universe is deployed and how others can run their own instance.
+
+## Production
+
+- **Hosting:** Coolify on Hetzner (bare metal)
+- **Containers:** Docker Compose — admin-api, pusher, front, map-storage, uploader, Redis, Matrix, Traefik
+- **Database:** PostgreSQL (encrypted at rest for MCP credentials — see [mcp-encryption](../04-mcp/mcp-encryption/))
+- **Auth:** [OIDC](./oidc-auth/) provider (production) / Keycloak mock (dev)
+
+## For Others
+
+Two options documented in `docs/others/self-hosting/install.md`:
+- **Docker Compose** — standard setup
+- **Helm chart** — Kubernetes deployment
+
+Environment variables: `docs/others/self-hosting/env-variables.md`
+Matrix (optional): `docs/others/self-hosting/matrix.md`
+
+## Development
+
+`docker compose up` with `.env.template`. Requires ~14 subdomains in `/etc/hosts`. See [workadventure-fork](./workadventure-fork/) for the upstream README setup instructions.
+
+## Related
+
+- [Admin API](./admin-api/) — REST layer
+- [Orbit](./orbit/) — operator UI
diff --git a/docs/universe/features/01-platform/workadventure-fork/README.md b/docs/universe/features/01-platform/workadventure-fork/README.md
@@ -0,0 +1,28 @@
+# WorkAdventure Fork
+
+Universe is a fork of [WorkAdventure](https://workadventu.re) by TheCodingMachine — an open-source (MIT) virtual world platform. We extended it with AI agents, MCP integration, streaming conversations, encrypted storage, and a bot management system.
+
+## What We Inherited
+
+From upstream WorkAdventure (`github.com/thecodingmachine/workadventure`):
+
+- Proximity-based audio/video chat via WebRTC (backed by [LiveKit](../05-about/technology-stack/))
+- Tiled map editor + WAM JSON format. See [maps](../02-spatial-world/maps/)
+- Inline [map editor](../02-spatial-world/inline-map-editor/) in-game
+- [Scripting API](../02-spatial-world/scripting-api/) — WA.ui, WA.room, WA.player, WA.state
+- [Woka avatars](../02-spatial-world/woka-avatars/) (pipoya sprites)
+- [Area zones](../02-spatial-world/area-zones/) — entry/exit, meeting rooms, silent, broadcast
+- [Megaphone](../02-spatial-world/megaphone/) broadcast system
+- [Matrix chat](../02-spatial-world/matrix-chat/) (optional Synapse)
+- [OIDC authentication](./oidc-auth/)
+- Docker Compose + Helm [self-hosting](./self-hosting/)
+- [White label](../02-spatial-world/white-label-rebranding/) — custom domain, logos
+
+## What We Built
+
+Everything in [03-ai-bots](../03-ai-bots/) and [04-mcp](../04-mcp/), plus the [admin API](./admin-api/), [Orbit dashboard](./orbit/), and [avatar platform](../02-spatial-world/avatar-platform/).
+
+## Repos
+
+- **Fork:** `github.com/BAWES-Universe/workadventure-universe` (branch: `universe-develop` → `universe`)
+- **Admin:** `github.com/BAWES-Universe/workadventure-universe-admin` (branch: `develop` → `main`)
diff --git a/docs/universe/features/02-spatial-world/README.md b/docs/universe/features/02-spatial-world/README.md
@@ -0,0 +1,33 @@
+# 02 — Spatial World
+
+Virtual environment features — maps, zones, communication tools, avatars, editors, and the scripting API. Mostly inherited from WorkAdventure, extended by Universe with AI-specific additions.
+
+| Feature | Status | What it is |
+|---|---|---|
+| [maps](./maps/) | 🟢 LIVE | Tiled editor, WAM format, publishing |
+| [inline-map-editor](./inline-map-editor/) | 🟢 LIVE | In-game map editing |
+| [area-zones](./area-zones/) | 🟢 LIVE | Zones with triggerable actions (website, file, LiveKit, megaphone, teleport, etc.) |
+| [entity-editor](./entity-editor/) | 🟢 LIVE | Place and configure interactive objects on maps |
+| [bot-editor](./bot-editor/) | 🟢 LIVE | Place, configure, and manage bots on the map |
+| [teleport](./teleport/) | 🟢 LIVE | Teleport between universes/worlds/rooms via area property |
+| [proximity-chat](./proximity-chat/) | 🟢 LIVE | P2P WebRTC by default, auto-scales to LiveKit at 4+ users. Coturn TURN/STUN |
+| [text-chat](./text-chat/) | 🟢 LIVE | In-world text + bot streaming |
+
+| [screen-sharing](./screen-sharing/) | 🟢 LIVE | Share screen in conversation bubbles |
+| [follow](./follow/) | 🟢 LIVE | Follow another player through the map |
+| [lock-discussion](./lock-discussion/) | 🟢 LIVE | Lock conversation bubble to prevent others joining |
+| [emoji-reactions](./emoji-reactions/) | 🟢 LIVE | Quick emoji reactions above avatar |
+| [megaphone](./megaphone/) | 🔵 INHERITED | Broadcast audio/video to room or world |
+| [play-audio](./play-audio/) | 🟢 LIVE | Play audio files on area zone entry |
+| [availability-status](./availability-status/) | 🟢 LIVE | Set status (Online, Busy, etc.), syncs across platforms |
+| [user-directory](./user-directory/) | 🟢 LIVE | Browse users, see status, locate on map |
+| [woka-avatars](./woka-avatars/) | 🟢 LIVE | Pipoya-style user avatars |
+| [avatar-platform](./avatar-platform/) | 🟢 LIVE | Avatar sets, entitlements, catalog governance |
+| [meeting-rooms](./meeting-rooms/) | ⚠️ SUPPORTED | Jitsi/BBB zones (core infra is LiveKit WebRTC) |
+| [searchable](./searchable/) | 🟢 LIVE | Make areas and entities discoverable in Orbit |
+| [scripting-api](./scripting-api/) | 🔵 INHERITED | WA.ui, WA.room, WA.player, WA.state |
+| [white-label-rebranding](./white-label-rebranding/) | 🔵 INHERITED | Custom domain, logos |
+| [matrix-chat](./matrix-chat/) | 🟡 OPTIONAL | Persistent chat via Synapse |
+| [map-templates](./map-templates/) | 🔵 INHERITED | Reusable room layouts |
+
+See also: [01-platform/workadventure-fork](../01-platform/workadventure-fork/), [03-ai-bots/bot-streaming-chat](../03-ai-bots/bot-streaming-chat/)
diff --git a/docs/universe/features/02-spatial-world/area-zones/README.md b/docs/universe/features/02-spatial-world/area-zones/README.md
@@ -0,0 +1,38 @@
+# Area Zones
+
+**Status:** 🟢 LIVE
+
+Spatial zones on maps that trigger actions when players enter, exit, or stay. Drawn using the Area Editor in the in-game Map Editor. Universe's permission and interaction system for the virtual world.
+
+## Area Properties (Actions)
+
+When drawing an area in the Area Editor, you can assign one or more of these properties:
+
+| Property | What it does |
+|----------|-------------|
+| **Start Area** | Sets where players spawn when entering the map |
+| **Exit Area** | Teleports player to another map and start zone |
+| **Open Website** | Opens a URL (immediately on enter, or as a press-[SPACE] prompt) |
+| **Open File** | Opens an uploaded file (PDF, etc.) |
+| **Google Workspace** | Pre-configured Google Docs, Sheets, Slides, Drive integrations |
+| **Klaxoon** | Embedded Klaxoon board |
+| **LiveKit Room** | Activates spatial audio/video in the zone (with audio/video mute options) |
+| **Megaphone (Speaker)** | Designates area as megaphone broadcast origin |
+| **Megaphone (Listener)** | Designates area as megaphone reception zone |
+| **Highlight** | Visually highlights the area on the map |
+| **Focusable** | Makes the area focusable/interactive |
+| **Play Audio** | Plays an audio file on zone entry |
+| **Restricted Rights** | Gates access by read/write membership tags |
+| **Searchable** | Makes the area discoverable in Orbit's exploration view |
+| **Matrix Chat Room** | Creates an optional persistent chat room for the area |
+
+## Access Control
+
+Area permissions are managed in [Orbit](../01-platform/orbit/). Draw a zone on the map, assign read/write tags, and only users with the matching tags can enter or interact. Tags come from [OIDC roles](../01-platform/oidc-auth/) or direct membership assignment.
+
+## Related
+
+- [Entity Editor](#) — objects placed on maps can also trigger actions
+- [Scripting API](./scripting-api/) — programmatic zone triggers via WA.room.onEnterLayer
+- [Avatar platform](./avatar-platform/) — membership-gated sets use same tag system
+- `docs/map-building/inline-editor/area-editor/`
diff --git a/docs/universe/features/02-spatial-world/availability-status/README.md b/docs/universe/features/02-spatial-world/availability-status/README.md
@@ -0,0 +1,27 @@
+# Availability Status
+
+**Status:** 🟢 LIVE (inherited from WorkAdventure)
+
+Set your availability status to let others know your current state. Status syncs across connected platforms (Microsoft Teams, Discord, Slack).
+
+## Status Options
+
+| Status | Meaning |
+|--------|---------|
+| **Online** | Available for conversations |
+| **Busy** | Do not disturb — notifications suppressed |
+| **Do Not Disturb** | Deep focus mode |
+| (others configurable via admin) | |
+
+## Features
+
+- Set status from the profile menu in the action bar
+- Status displays as colored indicator on your avatar
+- Changes appear on connected platforms (Teams, Discord, Slack)
+- "Busy" status suppresses conversation bubble joins
+- Configurable via admin
+
+## Related
+
+- [User directory](./user-directory/) — see other users' statuses
+- [Proximity chat](./proximity-chat/) — availability affects bubble joining
diff --git a/docs/universe/features/02-spatial-world/avatar-platform/README.md b/docs/universe/features/02-spatial-world/avatar-platform/README.md
@@ -0,0 +1,35 @@
+# Avatar Platform
+
+Full avatar identity system — not just a character picker. Avatars are grouped into **Sets**: managed collections with scope, entitlement type, and lifecycle.
+
+## Set Types
+
+| Type | Who can use it |
+|---|---|
+| **Public** | Every visitor, any world |
+| **Universe-scoped** | Only inside a specific universe |
+| **World-scoped** | Only inside a single world |
+| **Membership-gated** | Requires a tag, subscription, or email domain |
+| **User-granted** | Admin-assigned to a specific user |
+| **NPC / Bot-only** | Hidden from all players — assigned to AI bots only |
+
+## Entitlement Types
+
+- **Tag-gated** — requires a membership tag ("staff", "vip", "student")
+- **Subscription-gated** — behind a recurring subscription; auto-expires
+- **Email-domain scoped** — only @company.com can see the set
+- **Direct grant** — admin assigns to a specific user
+- **Time-limited** — start and end dates; seasonal drops auto-unlock
+
+## Governance
+
+- **Safe archive** — warns if anyone/bot is wearing a set before archiving
+- **Audit log** — every action tracked with timestamp and actor
+- **Versioned collections** — publish new season without touching live
+
+## Related
+
+- [Woka avatars](./woka-avatars/) — user avatar rendering
+- [Bot avatars](../03-ai-bots/bot-avatars/) — NPC-only sets
+- [Orbit](../01-platform/orbit/) — manage avatar sets via admin dashboard
+- [OIDC auth](../01-platform/oidc-auth/) — tags and roles for membership gating
diff --git a/docs/universe/features/02-spatial-world/bot-editor/README.md b/docs/universe/features/02-spatial-world/bot-editor/README.md
@@ -0,0 +1,40 @@
+# Bot Editor
+
+**Status:** 🟢 LIVE
+
+Place, configure, and manage AI bots directly on the map. Part of the in-game Map Editor with bindings to the Admin API.
+
+## Modes
+
+The Bot Editor has four modes:
+
+| Mode | What it does |
+|------|-------------|
+| **List** | View all bots on the current map, their status, and behavior type |
+| **Detail** | Edit a single bot's configuration — name, behavior, radius, avatar |
+| **Placing** | Click on the map to set a bot's spawn position |
+| **Waypoint Edit** | Draw patrol waypoints for bots in Patrol mode |
+
+## Configuration
+
+Per-bot settings available in the editor:
+
+- **Name** — display name in the world
+- **Behavior Type** — idle (stationary), patrol (follows waypoints), social (proactive greeting)
+- **Radius** — proximity detection range
+- **Conversation Radius** (social bots) — how far the bot reaches out to greet people
+- **Patrol Waypoints** — click on the map to add waypoints the bot walks between
+- **Assigned Space** — bot's current position on the map
+
+## Live Updates
+
+Changes made in the Bot Editor are sent to running bots in real-time via the Admin API:
+- Move a bot → it teleports instantly
+- Change behavior type → bot switches mode immediately
+- Add waypoints → patrol path updates live
+
+## Related
+
+- [Bot behaviors](../03-ai-bots/bot-behaviors/) — idle, patrol, social behavior documentation
+- [Admin API](../01-platform/admin-api/) — the REST API behind the bot editor
+- [Orbit](../01-platform/orbit/) — operator dashboard for bot management