diff --git a/docs/universe/features/01-platform/README.md b/docs/universe/features/01-platform/README.md
new file mode 100644
index 0000000..22b3545
--- /dev/null
+++ 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/)
\ No newline at end of file
diff --git a/docs/universe/features/01-platform/admin-api/README.md b/docs/universe/features/01-platform/admin-api/README.md
new file mode 100644
index 0000000..3e8a8b0
--- /dev/null
+++ 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`
\ No newline at end of file
diff --git a/docs/universe/features/01-platform/oidc-auth/README.md b/docs/universe/features/01-platform/oidc-auth/README.md
new file mode 100644
index 0000000..fda8b05
--- /dev/null
+++ 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
\ No newline at end of file
diff --git a/docs/universe/features/01-platform/orbit-model/README.md b/docs/universe/features/01-platform/orbit-model/README.md
new file mode 100644
index 0000000..352a886
--- /dev/null
+++ 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
new file mode 100644
index 0000000..5d5cbbf
--- /dev/null
+++ 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
\ No newline at end of file
diff --git a/docs/universe/features/01-platform/self-hosting/README.md b/docs/universe/features/01-platform/self-hosting/README.md
new file mode 100644
index 0000000..e54487a
--- /dev/null
+++ 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
\ No newline at end of file
diff --git a/docs/universe/features/01-platform/workadventure-fork/README.md b/docs/universe/features/01-platform/workadventure-fork/README.md
new file mode 100644
index 0000000..3c982ab
--- /dev/null
+++ 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`)
\ No newline at end of file
diff --git a/docs/universe/features/02-spatial-world/README.md b/docs/universe/features/02-spatial-world/README.md
new file mode 100644
index 0000000..0bb8343
--- /dev/null
+++ 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
new file mode 100644
index 0000000..84a9791
--- /dev/null
+++ 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
new file mode 100644
index 0000000..5956fe0
--- /dev/null
+++ 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
new file mode 100644
index 0000000..6d2baf6
--- /dev/null
+++ 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
\ No newline at end of file
diff --git a/docs/universe/features/02-spatial-world/bot-editor/README.md b/docs/universe/features/02-spatial-world/bot-editor/README.md
new file mode 100644
index 0000000..cfee584
--- /dev/null
+++ 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
diff --git a/docs/universe/features/02-spatial-world/emoji-reactions/README.md b/docs/universe/features/02-spatial-world/emoji-reactions/README.md
new file mode 100644
index 0000000..0101a50
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/emoji-reactions/README.md
@@ -0,0 +1,17 @@
+# Emoji Reactions
+
+**Status:** 🟢 LIVE (inherited from WorkAdventure)
+
+React quickly with emojis that display above your avatar. A lightweight way to acknowledge, react, or communicate without speaking.
+
+## How It Works
+
+- Click the emoji button in the action bar
+- Select an emoji from the sub-menu
+- The emoji appears above your avatar for a few seconds
+- Visible to nearby players
+
+## Related
+
+- [Proximity chat](./proximity-chat/) — voice reactions
+- [Text chat](./text-chat/) — text-based reactions
diff --git a/docs/universe/features/02-spatial-world/entity-editor/README.md b/docs/universe/features/02-spatial-world/entity-editor/README.md
new file mode 100644
index 0000000..f8ebf6e
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/entity-editor/README.md
@@ -0,0 +1,34 @@
+# Entity Editor
+
+**Status:** 🟢 LIVE
+
+Place and configure interactive objects on maps. Part of the in-game Map Editor.
+
+## How It Works
+
+- Open the Map Editor and switch to Entity Editor mode
+- Search and select entities from a catalog (furniture, objects, decorative items)
+- Place entities on the map by clicking a position
+- Each entity can be named, described, and assigned properties
+
+## Entity Properties
+
+Like [Area Zones](./area-zones/), entities can trigger actions:
+
+| Property | What it does |
+|----------|-------------|
+| **Open Website** | Opens a URL when the player interacts with the entity (press SPACE near it) |
+| **Open File** | Opens an uploaded file when the player interacts |
+| **Searchable** | Makes the entity discoverable in Orbit's exploration view |
+
+## Other Capabilities
+
+- **Upload custom assets** — add your own images as new entity types
+- **Edit/Remove** — modify or delete placed entities
+- **Name & Description** — label entities for identification
+
+## Related
+
+- [Area zones](./area-zones/) — area-level actions (same property system)
+- [Maps](./maps/) — the spatial canvas entities sit on
+- [Scripting API](./scripting-api/) — programmatic entity interaction
diff --git a/docs/universe/features/02-spatial-world/follow/README.md b/docs/universe/features/02-spatial-world/follow/README.md
new file mode 100644
index 0000000..2849647
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/follow/README.md
@@ -0,0 +1,25 @@
+# Follow
+
+**Status:** 🟢 LIVE (inherited from WorkAdventure)
+
+Follow another player through the map. Your avatar automatically tracks their movements.
+
+## How It Works
+
+- Walk near another player's avatar
+- Click the "Follow" button on their avatar
+- Your avatar follows them as they move through rooms and maps
+- Player being followed sees a "Stop following" button
+- API: `WA.player.proximityMeeting.followMe()`
+- Events: `WA.player.proximityMeeting.onUnfollowed()`
+
+## Use Cases
+
+- Tour guides leading groups through a space
+- Helping new users navigate
+- Keeping a group together during events
+
+## Related
+
+- [Proximity chat](./proximity-chat/) — talk while following
+- [Scripting API](./scripting-api/) — programmatic follow triggers
diff --git a/docs/universe/features/02-spatial-world/inline-map-editor/README.md b/docs/universe/features/02-spatial-world/inline-map-editor/README.md
new file mode 100644
index 0000000..345449c
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/inline-map-editor/README.md
@@ -0,0 +1,14 @@
+# Inline Map Editor
+
+Edit maps directly in the browser while inside the virtual world. No need for the Tiled desktop app for basic adjustments.
+
+## What You Can Do
+
+- Configure [area zones](./area-zones/) (entry/exit, silent, broadcast, meeting rooms)
+- Set [megaphone](./megaphone/) scope and access tags
+- Adjust room properties
+
+## Related
+
+- [Maps](./maps/) — for full map creation in Tiled
+- `docs/map-building/inline-editor/area-editor/index.md`
\ No newline at end of file
diff --git a/docs/universe/features/02-spatial-world/lock-discussion/README.md b/docs/universe/features/02-spatial-world/lock-discussion/README.md
new file mode 100644
index 0000000..c67c5d1
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/lock-discussion/README.md
@@ -0,0 +1,17 @@
+# Lock Discussion
+
+**Status:** 🟢 LIVE (inherited from WorkAdventure)
+
+Lock your conversation bubble to prevent others from joining. Useful for private conversations in public spaces.
+
+## How It Works
+
+- In an active conversation bubble, click the lock button
+- No new participants can enter the bubble
+- Existing participants remain
+- Unlock to allow others to join again
+
+## Related
+
+- [Proximity chat](./proximity-chat/) — the conversation bubble
+- [Screen sharing](./screen-sharing/) — share screen in locked bubble
diff --git a/docs/universe/features/02-spatial-world/map-templates/README.md b/docs/universe/features/02-spatial-world/map-templates/README.md
new file mode 100644
index 0000000..c9f1620
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/map-templates/README.md
@@ -0,0 +1,8 @@
+# Map Templates
+
+Pre-built room layouts that can be reused across worlds. Speeds up map creation by providing common configurations (office, classroom, event hall, community hub).
+
+## Related
+
+- [Maps](./maps/) — creating custom maps
+- `docs/map-building/index.md`
\ No newline at end of file
diff --git a/docs/universe/features/02-spatial-world/maps/README.md b/docs/universe/features/02-spatial-world/maps/README.md
new file mode 100644
index 0000000..674ec53
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/maps/README.md
@@ -0,0 +1,24 @@
+# Maps
+
+The spatial canvas of Universe. Maps are built with [Tiled](https://www.mapeditor.org/) and use the **WAM** (Web Avatar Map) format — JSON. They define the layout, collision, zones, and interactions of every room.
+
+## How It Works
+
+- **Editor:** Tiled (desktop). Place tiles, objects, zones on layers
+- **Format:** WAM schema at `docs/schema/2.0.0/wam.json`
+- **Publishing:** WA hosted, GitHub Pages, or self-hosted (see [self-hosting](../01-platform/self-hosting/))
+- **Hot-reload:** Maps reload on save — no server restart
+
+## What's on a Map
+
+- [Area zones](./area-zones/) — entry/exit triggers, silent zones, broadcast zones
+- [Meeting rooms](./meeting-rooms/) — Jitsi/BBB zones for scheduled calls
+- Embedded websites as interactive objects
+- Animated tiles, cameras, text displays
+- Collision layers, teleport points
+
+## Related
+
+- [Inline map editor](./inline-map-editor/) — modify maps in-game
+- [Map templates](./map-templates/) — reusable room layouts
+- `docs/map-building/tiled-editor/` — full docs
\ No newline at end of file
diff --git a/docs/universe/features/02-spatial-world/matrix-chat/README.md b/docs/universe/features/02-spatial-world/matrix-chat/README.md
new file mode 100644
index 0000000..0ba3307
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/matrix-chat/README.md
@@ -0,0 +1,17 @@
+# Matrix Chat
+
+Optional persistent chat via Matrix/Synapse. Gives every room a permanent chat history across sessions.
+
+## How It Works
+
+- Synapse container runs alongside the main stack
+- Chat history persists when users leave and re-enter
+- Federates with the broader Matrix network
+
+## When to Use
+
+Skip if you only need per-session [proximity chat](./proximity-chat/) and ephemeral [text chat](./text-chat/). Enable if users need to revisit conversations from previous sessions.
+
+## Docs
+
+`docs/others/self-hosting/matrix.md`
\ No newline at end of file
diff --git a/docs/universe/features/02-spatial-world/meeting-rooms/README.md b/docs/universe/features/02-spatial-world/meeting-rooms/README.md
new file mode 100644
index 0000000..51edb36
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/meeting-rooms/README.md
@@ -0,0 +1,19 @@
+# Meeting Rooms
+
+**Status:** 🟢 LIVE (Jitsi/BBB supported)
+
+Video conference rooms embedded in maps. Walk your avatar into a meeting room zone to join a scheduled call.
+
+## How It Works
+
+- Designate an area zone as a meeting room
+- Zone is linked to a Jitsi or BigBlueButton URL
+- When player walks in, they auto-join the call
+- Supports multiple simultaneous meetings
+
+> **Note:** Jitsi and BBB are supported integrations. Universe's core real-time communication infrastructure is LiveKit WebRTC + Coturn, which powers [proximity chat](./proximity-chat/). Meeting rooms use external providers for scheduled calls.
+
+## Related
+
+- [Area zones](./area-zones/) — meeting room is a zone type with LiveKit room property
+- [Proximity chat](./proximity-chat/) — spontaneous alternative using LiveKit core
diff --git a/docs/universe/features/02-spatial-world/megaphone/README.md b/docs/universe/features/02-spatial-world/megaphone/README.md
new file mode 100644
index 0000000..b1dfe97
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/megaphone/README.md
@@ -0,0 +1,20 @@
+# Megaphone
+
+Broadcast your audio, video, or screen to every player in a room or an entire world. Typically reserved for admins and moderators.
+
+## How It Works
+
+- Click megaphone icon in the action bar to enable
+- Orange icon + yellow camera feedback + megaphone icon on avatar = broadcasting
+- Scope: "room" (current room) or "world" (all rooms sharing the same space name)
+- Access controlled by tags — only tagged users see the megaphone button
+
+## Configuration
+
+Configured in [inline map editor](./inline-map-editor/) under the megaphone tab. Toggle on/off, set scope, set access tags.
+
+## Related
+
+- [Proximity chat](./proximity-chat/) — 1:1 or small group
+- [Area zones](./area-zones/) — broadcast zone (push notifications, different from live audio)
+- `docs/map-building/inline-editor/megaphone.md`
\ No newline at end of file
diff --git a/docs/universe/features/02-spatial-world/play-audio/README.md b/docs/universe/features/02-spatial-world/play-audio/README.md
new file mode 100644
index 0000000..087b2b7
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/play-audio/README.md
@@ -0,0 +1,18 @@
+# Play Audio
+
+**Status:** 🟢 LIVE (inherited from WorkAdventure)
+
+Play audio files when players enter designated area zones. Used for ambient sound, announcements, or interactive experiences.
+
+## How It Works
+
+- Add a "Play Audio" property to any area in the map editor
+- Upload an audio file
+- When a player walks into the area, the audio plays
+- Audio stops when the player leaves the area
+
+## Related
+
+- [Area zones](./area-zones/) — audio plays on zone entry
+- [Maps](./maps/) — create maps with audio zones
+- [Megaphone](./megaphone/) — live audio broadcast (different from triggered audio)
diff --git a/docs/universe/features/02-spatial-world/proximity-chat/README.md b/docs/universe/features/02-spatial-world/proximity-chat/README.md
new file mode 100644
index 0000000..032b208
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/proximity-chat/README.md
@@ -0,0 +1,27 @@
+# Proximity Chat
+
+**Status:** 🟢 LIVE
+
+Audio/video communication triggered by spatial proximity. Uses **direct peer-to-peer WebRTC by default** (via `simple-peer`), with automatic scaling to a LiveKit server when rooms grow beyond the threshold (default: 4 users). Coturn provides TURN/STUN relay for NAT traversal.
+
+The backend decides when to switch. If LiveKit isn't configured (`LIVEKIT_HOST` env var not set), the room stays on P2P regardless of user count.
+
+## How It Works
+
+- Walk your avatar near another player — audio/video bubble activates automatically
+- **≤ 4 users:** Direct P2P WebRTC (`simple-peer`). Zero server load, minimal latency.
+- **> 4 users:** Backend triggers automatic switch to LiveKit server (when configured). Clients get a `SWITCH_MESSAGE` with a LiveKit room token and connect via `livekit-client`.
+- When LiveKit is unavailable or not configured, P2P is used at any scale.
+- **Scaling back:** When users drop back to ≤ 4, a 20-second delayed transition back to P2P is scheduled (prevents thrashing on rapid join/leave).
+- Hear nearby conversations (optional toggle)
+- Private bubbles for small group discussions
+- Muted by default — you choose who you hear
+- No scheduling needed — spontaneous
+
+## Related Features
+
+- **Screen Sharing** — Share your screen with people in the conversation bubble via the screenShareButton
+- **Follow** — Click to follow another person (API: `WA.player.proximityMeeting.followMe()`)
+- [Text chat](./text-chat/) — in-world messaging
+- [Megaphone](./megaphone/) — one-to-many broadcast
+- [Technology stack](../05-about/technology-stack/) — LiveKit + Coturn integration
diff --git a/docs/universe/features/02-spatial-world/screen-sharing/README.md b/docs/universe/features/02-spatial-world/screen-sharing/README.md
new file mode 100644
index 0000000..fbef5e4
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/screen-sharing/README.md
@@ -0,0 +1,17 @@
+# Screen Sharing
+
+**Status:** 🟢 LIVE (inherited from WorkAdventure)
+
+Share your screen with people in your conversation bubble. Accessible via the screenShareButton in the in-world UI.
+
+## How It Works
+
+- Click the screen share button in the conversation bubble
+- Your screen is shared with everyone in your proximity bubble
+- Toggle on/off — works alongside audio/video in the same bubble
+- Multiple users can screen share simultaneously
+
+## Related
+
+- [Proximity chat](./proximity-chat/) — the conversation bubble where screen sharing happens
+- [Megaphone](./megaphone/) — broadcast screen to an entire room or world
diff --git a/docs/universe/features/02-spatial-world/scripting-api/README.md b/docs/universe/features/02-spatial-world/scripting-api/README.md
new file mode 100644
index 0000000..6e7deef
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/scripting-api/README.md
@@ -0,0 +1,31 @@
+# Scripting API
+
+The `WA.*` namespace — programmatic control of the virtual world. Lets map creators add interactive behavior.
+
+## API Reference
+
+| API | Purpose |
+|---|---|
+| `WA.room` | Room state, layers, onEnterLayer, onLeaveLayer |
+| `WA.state` | Persistent key-value store (survives map reloads) |
+| `WA.player` | Player position, tags, UUID, state |
+| `WA.ui` | Popups, custom menus, iframes, modals, action bar buttons |
+| `WA.chat` | Send/receive chat messages programmatically |
+| `WA.mapEditor` | Programmatic map editing |
+| `WA.iframeId` | Self-identification for iframe scripts |
+
+## Capabilities
+
+- Open popups on zone entry ([area-zones](./area-zones/))
+- Register custom menu items in the navbar
+- Display "press space to confirm" action messages
+- Embed interactive iframes (positioned on viewport)
+- Open modals (center, left, right)
+- Add/remove action bar buttons
+- Listen for `onRemotePlayerClicked` for custom interactions
+- Pre-registered menu keys: settings, profile, invite, credit, globalMessages, contact, report
+
+## Related
+
+- [Area zones](./area-zones/) — scripting triggers on zone entry
+- `docs/developer/map-scripting/` — full API docs
\ No newline at end of file
diff --git a/docs/universe/features/02-spatial-world/searchable/README.md b/docs/universe/features/02-spatial-world/searchable/README.md
new file mode 100644
index 0000000..b5a34b0
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/searchable/README.md
@@ -0,0 +1,19 @@
+# Searchable Areas & Entities
+
+**Status:** 🟢 LIVE (inherited from WorkAdventure, enhanced by Universe)
+
+Make areas and entities discoverable in Orbit's exploration view. Searchable items appear when users search for rooms, features, or objects.
+
+## How It Works
+
+- In the Area Editor or Entity Editor, toggle the "Searchable" property
+- The area or entity appears in Orbit search results
+- Users can find rooms and objects by name or description
+- Descriptions help users understand what they'll find
+
+## Related
+
+- [Area zones](./area-zones/) — searchable is an area property
+- [Entity editor](./entity-editor/) — searchable is an entity property
+- [Orbit](../01-platform/orbit/) — discovery via Orbit navigation
+- [Area editor](./entity-editor/) — toggle in the editor
diff --git a/docs/universe/features/02-spatial-world/teleport/README.md b/docs/universe/features/02-spatial-world/teleport/README.md
new file mode 100644
index 0000000..067636b
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/teleport/README.md
@@ -0,0 +1,28 @@
+# Teleport
+
+**Status:** 🟢 LIVE (extension module)
+
+Teleport between universes, worlds, and rooms via a custom area property. Part of the external modules system.
+
+## How It Works
+
+- Add a "Teleport" property to any area in the map editor
+- Specify destination: Universe, World, Room, and optional Start Area
+- When a player walks into the area, they're teleported to the destination
+- URL format: `@/universe/world/room#startArea`
+
+## Configuration
+
+| Field | Required | Description |
+|-------|----------|-------------|
+| Universe | ✅ | e.g., `bawes-univ` |
+| World | ✅ | e.g., `bawes-world` |
+| Room | ✅ | e.g., `headquarters` |
+| Start Area | Optional | e.g., `startSpawnArea` |
+
+The teleport extension is enabled per-room by adding `"teleport"` to the `modules` array in room metadata.
+
+## Related
+
+- [Area zones](./area-zones/) — teleport is an area property
+- [Maps](./maps/) — rooms that can be destinations
diff --git a/docs/universe/features/02-spatial-world/text-chat/README.md b/docs/universe/features/02-spatial-world/text-chat/README.md
new file mode 100644
index 0000000..dcd6a6d
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/text-chat/README.md
@@ -0,0 +1,19 @@
+# Text Chat
+
+In-world text messaging. Every room has its own chat channel. Universe extends this with bot streaming.
+
+## Features
+
+- Per-room message history
+- Chat bubble display in game UI
+- Proximity-based visibility (nearby players see your messages)
+
+## Bot Streaming (Universe Extension)
+
+AI bot responses stream token-by-token into the chat bubble in real time. See [bot-streaming-chat](../03-ai-bots/bot-streaming-chat/) for details.
+
+## Related
+
+- [Proximity chat](./proximity-chat/) — voice alternative
+- [Matrix chat](./matrix-chat/) — persistent history across sessions
+- `docs/user/chat.md`
\ No newline at end of file
diff --git a/docs/universe/features/02-spatial-world/user-directory/README.md b/docs/universe/features/02-spatial-world/user-directory/README.md
new file mode 100644
index 0000000..7473cb6
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/user-directory/README.md
@@ -0,0 +1,19 @@
+# User Directory
+
+**Status:** 🟢 LIVE (inherited from WorkAdventure)
+
+Browse all users in your space, see their status, and locate them on the map.
+
+## How It Works
+
+- Open the user list from the action bar
+- See all connected users, their status (Online, Busy, etc.)
+- Click on a user to locate them on the map
+- Walk toward them or send a message
+
+## Related
+
+- [Availability status](./availability-status/) — status displayed in directory
+- [Proximity chat](./proximity-chat/) — walk to a user from the directory
+- [Text chat](./text-chat/) — message users from directory
+- [Follow](./follow/) — follow a user found via directory
diff --git a/docs/universe/features/02-spatial-world/white-label-rebranding/README.md b/docs/universe/features/02-spatial-world/white-label-rebranding/README.md
new file mode 100644
index 0000000..00c3cc7
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/white-label-rebranding/README.md
@@ -0,0 +1,14 @@
+# White Label / Rebranding
+
+Customize Universe with your own brand — logos, domain, and meta tags. Configured per-world in the map editor.
+
+## What You Can Change
+
+- Replace WorkAdventure logos with your own
+- Use your own domain (e.g. play.yourcompany.com)
+- Customize meta tags for SEO
+
+## Related
+
+- [Self-hosting](../01-platform/self-hosting/) — DNS and domain setup
+- [Inline map editor](./inline-map-editor/) — configure via UI
\ No newline at end of file
diff --git a/docs/universe/features/02-spatial-world/woka-avatars/README.md b/docs/universe/features/02-spatial-world/woka-avatars/README.md
new file mode 100644
index 0000000..9e6c4c3
--- /dev/null
+++ b/docs/universe/features/02-spatial-world/woka-avatars/README.md
@@ -0,0 +1,18 @@
+# Woka Avatars
+
+User avatars — pipoya-style 2D pixel-art sprites. The visual identity for every human in Universe.
+
+## Features
+
+- Pipoya-style pixel art
+- Customizable appearance (clothing, accessories)
+- Walk, sit, emote animations
+- Admin-managed avatar catalog (see [avatar-platform](./avatar-platform/))
+
+## Bot Avatars
+
+Bots have their own visual identity, separate from user Wokas. See [bot-avatars](../03-ai-bots/bot-avatars/).
+
+## Docs
+
+`docs/others/self-hosting/wokas.md`
\ No newline at end of file
diff --git a/docs/universe/features/03-ai-bots/README.md b/docs/universe/features/03-ai-bots/README.md
new file mode 100644
index 0000000..d7b3cda
--- /dev/null
+++ b/docs/universe/features/03-ai-bots/README.md
@@ -0,0 +1,21 @@
+# 03 — AI Bots
+
+The core Universe-built feature. Bots are first-class spatial citizens — they walk around rooms, react to proximity, stream conversations, and call external tools via MCP.
+
+| Feature | Status | What it is |
+|---|---|---|
+| [bot-behaviors](./bot-behaviors/) | 🟢 LIVE | Idle / patrol / social behavior modes |
+| [bot-streaming-chat](./bot-streaming-chat/) | 🟢 LIVE | Token-by-token AI responses |
+| [bot-emotions](./bot-emotions/) | 🟢 LIVE | Emotion blocks parsed from bot output |
+| [bot-tool-calling](./bot-tool-calling/) | 🟢 LIVE | MCP tool execution in conversations |
+| [bot-greetings](./bot-greetings/) | 🟢 LIVE | Proximity-triggered greetings |
+| [bot-memory](./bot-memory/) | 🟢 LIVE | Per-bot persistent memory |
+| [bot-avatars](./bot-avatars/) | 🟢 LIVE | NPC-only avatar sets for bots |
+| [recursive-bots](./recursive-bots/) | 🟢 LIVE | Bots spawning bots |
+| [bot-provider-config](./bot-provider-config/) | 🟢 LIVE | Per-bot AI provider (OpenAI, LMStudio, etc) |
+| [bot-file-parsing](./bot-file-parsing/) | 🟢 LIVE | PDF, Word, Excel, web page analysis |
+| [bot-media-sending](./bot-media-sending/) | 🟢 LIVE | Auto-send tool-generated images to users |
+| [bot-gallery](./bot-gallery/) | 🟢 LIVE | Multi-image gallery messages with lightbox |
+| [bot-pending-media](./bot-pending-media/) | 🟢 LIVE | Queue media for delivery on user re-entry |
+
+See also: [04-mcp](../04-mcp/), [02-spatial-world/proximity-chat](../02-spatial-world/proximity-chat/)
\ No newline at end of file
diff --git a/docs/universe/features/03-ai-bots/bot-avatars/README.md b/docs/universe/features/03-ai-bots/bot-avatars/README.md
new file mode 100644
index 0000000..e1287be
--- /dev/null
+++ b/docs/universe/features/03-ai-bots/bot-avatars/README.md
@@ -0,0 +1,24 @@
+# Bot Avatars
+
+Bots have their own visual identity, separate from user [Wokas](../02-spatial-world/woka-avatars/). This helps users immediately distinguish between people and AI agents.
+
+## NPC-Only Sets
+
+Bot avatars come from **NPC-only** [avatar sets](../02-spatial-world/avatar-platform/). These are hidden from the user avatar picker — players can never accidentally become a bot.
+
+Examples:
+- Museum lion mascot → lion avatar from "Animal Guides" set
+- Store guide → branded uniform avatar
+- Chef bot → chef avatar for food hall
+
+## Features
+
+- Separate catalog from user Wokas
+- Texture picker uses `&context=bot` URL param ([PR #210](https://github.com/BAWES-Universe/workadventure-universe/pull/210))
+- Status indicators (connected, thinking, idle)
+- Avatar assignment via [Orbit](../01-platform/orbit/) admin
+
+## Related
+
+- [Woka avatars](../02-spatial-world/woka-avatars/) — user avatar system
+- [Avatar platform](../02-spatial-world/avatar-platform/) — NPC-only set management
\ No newline at end of file
diff --git a/docs/universe/features/03-ai-bots/bot-behaviors/README.md b/docs/universe/features/03-ai-bots/bot-behaviors/README.md
new file mode 100644
index 0000000..d8d63ea
--- /dev/null
+++ b/docs/universe/features/03-ai-bots/bot-behaviors/README.md
@@ -0,0 +1,29 @@
+# Bot Behaviors
+
+Behavior modes that determine how bots interact with players in the spatial world.
+
+## Behavior Types
+
+| Mode | What it does |
+|---|---|
+| **Idle** | Waits for player interaction. Silent until approached. |
+| **Patrol** | Walks a set of waypoints around the room autonomously. |
+| **Social** | Greets nearby users proactively without waiting. |
+
+## Proximity Triggers
+
+Bots detect when a player enters their zone and react: greeting ([bot-greetings](./bot-greetings/)), offering a tour, starting an onboarding sequence, or flagging a human handoff.
+
+## Conversation Handoff
+
+When a bot hits its limit, it flags the session for human takeover — sending a notification to staff or escalating to a live operator room, preserving conversation context.
+
+## Scripted Sequences
+
+Beyond conversation, bots can execute scripted sequences: move to a position, wait, speak, trigger an animation, open a door, play a sound, start a countdown. Useful for tours, onboarding flows, and narrative experiences.
+
+## Related
+
+- [Bot greetings](./bot-greetings/) — messages triggered by these behaviors
+- [Recursive bots](./recursive-bots/) — manager bots spawning workers
+- [Orbit](../01-platform/orbit/) — configure behavior per bot
\ No newline at end of file
diff --git a/docs/universe/features/03-ai-bots/bot-emotions/README.md b/docs/universe/features/03-ai-bots/bot-emotions/README.md
new file mode 100644
index 0000000..2b5654b
--- /dev/null
+++ b/docs/universe/features/03-ai-bots/bot-emotions/README.md
@@ -0,0 +1,12 @@
+# Bot Emotions
+
+Bots can express moods through `[EMOTION_UPDATE]` blocks in their output. These are parsed before display and routed to the backend for state tracking — not shown in the chat UI.
+
+## Purpose
+
+Lets bots have internal emotional state (happy, confused, thinking, surprised, sad) that affects their avatar animation or behavior without cluttering the conversation.
+
+## Related
+
+- [Bot streaming chat](./bot-streaming-chat/) — emotions parsed from the same stream
+- [Bot avatars](./bot-avatars/) — visual state could reflect emotions
\ No newline at end of file
diff --git a/docs/universe/features/03-ai-bots/bot-file-parsing/README.md b/docs/universe/features/03-ai-bots/bot-file-parsing/README.md
new file mode 100644
index 0000000..917a0a2
--- /dev/null
+++ b/docs/universe/features/03-ai-bots/bot-file-parsing/README.md
@@ -0,0 +1,41 @@
+# Bot File Parsing
+
+**Status:** 🟢 LIVE
+
+Bots analyze PDF, Word (.docx), Excel (.xlsx), and web pages (via Mozilla Readability). Users upload files or paste URLs, the bot extracts text content, and the AI responds with summaries, answers, or analysis.
+
+## How It Works
+
+1. User uploads a file in chat or pastes a URL
+2. FileParser extracts text content (pdf-parse for PDF, mammoth for Word, xlsx for Excel, Readability for web)
+3. Extracted text feeds into the AI for response generation
+4. Bot answers questions, summarizes, or references specific data from the file
+
+## Supported Formats
+
+- **PDF** — Full text extraction via pdf-parse
+- **Word (.docx)** — Document parsing via mammoth
+- **Excel (.xlsx)** — Cell values and multi-sheet data via xlsx
+- **Web Pages** — Content extraction via Mozilla Readability
+
+## Security
+
+- SSRF-protected URL fetching (private IP validation)
+- In-memory parsing — file content not persisted to conversation storage
+- Per-file MIME type inference from extension
+
+## Use Cases
+
+- "Summarize this 50-page contract"
+- "What does this Excel sheet say about Q3 revenue?"
+- "Read this article and tell me the key points" (with Firecrawl MCP for web extraction)
+- "What are the termination conditions in this agreement?"
+
+## Code
+
+`bots/services/FileParser.ts`, `bots/services/WebPageExtractor.ts`
+
+## Related
+
+- [Bot tool calling](./bot-tool-calling/) — FileParser is called as a tool
+- [MCP server management](../04-mcp/mcp-server-management/) — configure which servers a bot connects to
diff --git a/docs/universe/features/03-ai-bots/bot-gallery/README.md b/docs/universe/features/03-ai-bots/bot-gallery/README.md
new file mode 100644
index 0000000..04bcb8f
--- /dev/null
+++ b/docs/universe/features/03-ai-bots/bot-gallery/README.md
@@ -0,0 +1,35 @@
+# Bot Gallery Messages
+
+**Status:** 🟢 LIVE
+
+Gallery messages display multiple images in a responsive grid with a full-screen lightbox. Works for both user-uploaded files and bot-generated images.
+
+## Layout
+
+- **2 images** — Two-column layout, equal space
+- **3 images** — Mosaic layout (one large + two small)
+- **4+ images** — Grid layout with +N overflow overlay on the 6th cell
+
+## Lightbox
+
+- Keyboard navigation (ArrowLeft/Right)
+- Swipe gestures (left/right on mobile)
+- Prev/next buttons
+- Fade transitions on image change
+- Zoom, pan, double-tap, pinch zoom
+- Character movement auto-disabled while lightbox is open
+
+## Sender-Agnostic
+
+- **User uploads** — multiple files batched into a single gallery message
+- **Bot-generated images** — auto-batched when a tool call returns 2+ images
+
+## Code
+
+`play/src/front/Chat/Components/Room/Message/MessageGallery.svelte`, `Lightbox.svelte`
+
+## Related
+
+- [Bot media sending](./bot-media-sending/) — how bot-generated images reach the gallery
+- [Bot file parsing](./bot-file-parsing/) — file analysis that may produce gallery output
+- [Text chat](../02-spatial-world/text-chat/) — the chat UI that renders galleries
diff --git a/docs/universe/features/03-ai-bots/bot-greetings/README.md b/docs/universe/features/03-ai-bots/bot-greetings/README.md
new file mode 100644
index 0000000..0bd84df
--- /dev/null
+++ b/docs/universe/features/03-ai-bots/bot-greetings/README.md
@@ -0,0 +1,14 @@
+# Bot Greetings
+
+When a player walks near a bot, the bot sends a customizable greeting message. The starting point for every bot interaction.
+
+## How It Works
+
+- Triggers on spatial proximity ([bot-behaviors](./bot-behaviors/))
+- Greeting content customizable per bot (set in [Orbit](../01-platform/orbit/))
+- Works with all behavior modes — Social greets proactively, Idle greets when approached
+
+## Related
+
+- [Bot behaviors](./bot-behaviors/) — the trigger system
+- `bots/memory/PersistentMemory.ts` — greeting memory
\ No newline at end of file
diff --git a/docs/universe/features/03-ai-bots/bot-media-sending/README.md b/docs/universe/features/03-ai-bots/bot-media-sending/README.md
new file mode 100644
index 0000000..20629eb
--- /dev/null
+++ b/docs/universe/features/03-ai-bots/bot-media-sending/README.md
@@ -0,0 +1,37 @@
+# Bot Media Sending
+
+**Status:** 🟢 LIVE
+
+When a bot calls an MCP tool that returns media (images, video, files), the result is auto-sent to the user's chat. No extra prompts, no manual steps — the media interceptor detects URLs in tool results and delivers them directly.
+
+## How It Works
+
+1. Bot calls an MCP tool that returns a URL (image, video, file)
+2. Auto-send interceptor detects media URLs in tool results
+3. Media is sent directly to the user's chat
+4. AI continues with confirmation — no duplicate sends
+
+## Smart Delivery
+
+- **Auto-batching** — 2+ images from the same tool call batch into a gallery message
+- **Single images** — direct send via sendImage
+- **Graceful fallback** — if gallery send fails, falls back to individual sends
+- **Deduplication** — originalUrl tracking prevents duplicate sends across turns
+
+## MCP Tool Examples
+
+- **ComfyUI** — "Generate an image of a dragon" → bot sends the image
+- **Higgsfield** — "Create a 5-second video clip" → bot delivers the video
+- **Firecrawl** — "Scrape this webpage and send me a screenshot" → bot scrapes and delivers
+- **Tavily** — "Research this topic and send me the key sources" → bot searches and links
+- **DALL·E / Stable Diffusion MCPs** — any image-generation pipeline
+
+## Code
+
+`bots/ai/AIService.ts` — autoSendMedia, preQueueToolResults
+
+## Related
+
+- [Bot tool calling](./bot-tool-calling/) — the tools that produce media
+- [Bot gallery](./bot-gallery/) — how multi-image results are displayed
+- [Bot pending media](./bot-pending-media/) — what happens when the user walks away
diff --git a/docs/universe/features/03-ai-bots/bot-memory/README.md b/docs/universe/features/03-ai-bots/bot-memory/README.md
new file mode 100644
index 0000000..521b837
--- /dev/null
+++ b/docs/universe/features/03-ai-bots/bot-memory/README.md
@@ -0,0 +1,18 @@
+# Bot Memory
+
+Every bot has persistent memory that survives across sessions. A visitor who asked about something last week is recognized this week.
+
+## How It Works
+
+- Stores conversation history, user interactions, learned facts
+- Loaded on bot spawn, restored when a user re-enters the bot's room
+- Enables coherent long-term conversations
+
+## Code
+
+`bots/memory/PersistentMemory.ts` — stored in PostgreSQL, loaded on demand with caching.
+
+## Related
+
+- [Bot provider config](./bot-provider-config/) — the AI model that uses this memory
+- [Recursive bots](./recursive-bots/) — spawned bots inherit their own memory
\ No newline at end of file
diff --git a/docs/universe/features/03-ai-bots/bot-pending-media/README.md b/docs/universe/features/03-ai-bots/bot-pending-media/README.md
new file mode 100644
index 0000000..d03492d
--- /dev/null
+++ b/docs/universe/features/03-ai-bots/bot-pending-media/README.md
@@ -0,0 +1,32 @@
+# Bot Pending Media
+
+**Status:** 🟢 LIVE
+
+If a user walks away while a bot is generating media, the result is queued and delivered the moment they return. No lost images, no repeated requests.
+
+## How It Works
+
+1. **Pre-queue** — URLs from tool results are saved to `pendingMedia` immediately after the tool finishes, before the AI generates its response
+2. **Re-entry detection** — when the user walks back to the bot, `flushPendingMedia` delivers all queued media
+3. **Deduplication** — `originalUrl` tracking prevents re-sending the same media
+4. **Greeting context** — the bot's greeting on re-entry notes that media was delivered while away, so the AI doesn't try to re-generate
+
+## The Problem This Solves
+
+- Bot calls a tool (e.g. ComfyUI) — generation takes 10-30 seconds
+- User walks away to another part of the room
+- Tool finishes, image is ready — but nobody to send it to
+- Without pending media: image is lost, user has to ask again
+- With pending media: image is queued, delivered on re-entry
+
+## Code
+
+`bots/ai/AIService.ts` — preQueueToolResults, flushPendingMedia
+`bots/memory/ConversationMemory.ts` — pendingMedia lifecycle
+`bots/memory/PersistentMemory.ts` — pendingMedia storage
+
+## Related
+
+- [Bot media sending](./bot-media-sending/) — the auto-send that pre-queues
+- [Bot memory](./bot-memory/) — where pendingMedia is stored
+- [Bot greetings](./bot-greetings/) — re-entry greeting with delivery context
diff --git a/docs/universe/features/03-ai-bots/bot-provider-config/README.md b/docs/universe/features/03-ai-bots/bot-provider-config/README.md
new file mode 100644
index 0000000..f65e77b
--- /dev/null
+++ b/docs/universe/features/03-ai-bots/bot-provider-config/README.md
@@ -0,0 +1,28 @@
+# Bot Provider Configuration
+
+Every bot can use a different AI provider and model. This is configured per-bot via the [admin API](../01-platform/admin-api/) / [Orbit](../01-platform/orbit/).
+
+## Supported Providers
+
+- OpenAI-compatible APIs
+- Anthropic
+- Deepseek
+- LMStudio (self-hosted, local)
+- Qwen 3B (default, runs offline-capable)
+
+## Storage
+
+Provider credentials are encrypted at rest — see [mcp-encryption](../04-mcp/mcp-encryption/). Fetched on demand with 1-hour caching.
+
+## Why Per-Bot
+
+- Support bot → fast, cheap model
+- Creative bot → powerful reasoning model
+- Education bot → safety-guarded model
+- Each tuned independently
+
+## Related
+
+- [MCP encryption](../04-mcp/mcp-encryption/) — credential storage
+- [Recursive bots](./recursive-bots/) — spawned bots get their own provider config
+- [Technology stack](../05-about/technology-stack/) — full list of supported models
\ No newline at end of file
diff --git a/docs/universe/features/03-ai-bots/bot-streaming-chat/README.md b/docs/universe/features/03-ai-bots/bot-streaming-chat/README.md
new file mode 100644
index 0000000..fb50c88
--- /dev/null
+++ b/docs/universe/features/03-ai-bots/bot-streaming-chat/README.md
@@ -0,0 +1,16 @@
+# Bot Streaming Chat
+
+AI responses stream word-by-word into the [text chat](../02-spatial-world/text-chat/) bubble as they're generated. Instead of waiting for a full response, you see the bot "thinking" in real time.
+
+## How It Works
+
+- Token-by-token rendering in the chat bubble
+- 🔍 magnifying-glass indicator appears mid-stream when the bot calls an [MCP tool](./bot-tool-calling/)
+- [Emotion blocks](./bot-emotions/) (`[EMOTION_UPDATE]`) are stripped from display and routed to backend
+- Real-time protocol — not request-response
+
+## Related
+
+- [Bot emotions](./bot-emotions/) — parsed from same stream
+- [Bot tool calling](./bot-tool-calling/) — indicators in stream
+- [Text chat](../02-spatial-world/text-chat/) — the chat UI rendering
\ No newline at end of file
diff --git a/docs/universe/features/03-ai-bots/bot-tool-calling/README.md b/docs/universe/features/03-ai-bots/bot-tool-calling/README.md
new file mode 100644
index 0000000..cae6aa9
--- /dev/null
+++ b/docs/universe/features/03-ai-bots/bot-tool-calling/README.md
@@ -0,0 +1,38 @@
+# Bot Tool Calling
+
+Bots use MCP tools during conversations — querying databases, checking inventory, creating tickets, or interacting with any [MCP-connected](../04-mcp/) service.
+
+## How It Works
+
+1. Bot discovers tools via [MCP tool discovery](../04-mcp/mcp-tool-discovery/) handshake
+2. During conversation, the AI decides when to call a tool based on context
+3. 🔍 indicator appears mid-stream in [streaming chat](./bot-streaming-chat/)
+4. Tool results feed back into the AI for response generation
+5. Timeout: 5s per call, 10s total budget per turn
+
+## Examples
+
+- **ComfyUI** (image generation) — "Generate an image of a dragon" → bot sends the image
+- **Higgsfield** (video generation) — "Create a 5-second video clip" → bot delivers the video
+- **Firecrawl** (web scraping) — "Read this article and tell me the key points" → bot scrapes and summarizes
+- **Tavily** (web search) — "Research this topic" → bot searches, synthesizes, and links sources
+- **Linear / Attio** (CRM/PM) — "Create an issue for this bug" / "What's the status of deal X?"
+- **FileParser** (built-in) — "Summarize this PDF" → bot extracts text and answers questions
+
+## File Analysis
+
+Bots can analyze PDF, Word, Excel, and web pages. See [bot-file-parsing](./bot-file-parsing/) for details.
+
+## Media Output
+
+Tools can return images and video — auto-sent to users as chat messages or galleries. See [bot-media-sending](./bot-media-sending/) for details.
+
+## Graceful Degradation
+
+If a tool call times out or the MCP server is unreachable, the bot responds without crashing. The tool is simply unavailable for that turn.
+
+## Related
+
+- [MCP server management](../04-mcp/mcp-server-management/) — configure which servers a bot connects to
+- [MCP tool discovery](../04-mcp/mcp-tool-discovery/) — how tools are found
+- [Bot provider config](./bot-provider-config/) — the AI model making the decision
\ No newline at end of file
diff --git a/docs/universe/features/03-ai-bots/recursive-bots/README.md b/docs/universe/features/03-ai-bots/recursive-bots/README.md
new file mode 100644
index 0000000..8184c75
--- /dev/null
+++ b/docs/universe/features/03-ai-bots/recursive-bots/README.md
@@ -0,0 +1,20 @@
+# Recursive Bots
+
+Bots spawning bots — autonomous AI agent provisioning. A functional closed loop where AIs provision AIs on real infrastructure.
+
+## How It Works
+
+- A **manager bot** creates a **worker bot** via the [admin API](../01-platform/admin-api/)
+- The spawned bot gets its own [MCP servers](../04-mcp/), [behavior](./bot-behaviors/), personality, room assignment
+- The spawned bot operates fully autonomously from creation
+- When a bot encounters an unsolvable problem, it can request a new MCP server or spawn a sub-agent
+
+## Implications
+
+Human role shifts from builder to curator — set intent, define guardrails, govern outcomes. The orchestra conducts itself.
+
+## Related
+
+- [Bot behaviors](./bot-behaviors/) — behaviors for spawned bots
+- [MCP server management](../04-mcp/mcp-server-management/) — spawned bots get their own servers
+- [Bot provider config](./bot-provider-config/) — each bot can use a different model
\ No newline at end of file
diff --git a/docs/universe/features/04-mcp/README.md b/docs/universe/features/04-mcp/README.md
new file mode 100644
index 0000000..cd9a7f2
--- /dev/null
+++ b/docs/universe/features/04-mcp/README.md
@@ -0,0 +1,16 @@
+# 04 — MCP Integration
+
+The Model Context Protocol layer — how bots connect to external tools and data sources. Every feature here was built on top of the WorkAdventure fork.
+
+| Feature | Status | What it is |
+|---|---|---|
+| [mcp-server-management](./mcp-server-management/) | 🟢 LIVE | CRUD, status, per-bot server config |
+| [mcp-oauth](./mcp-oauth/) | 🟢 LIVE | OAuth 2.0 + PKCE for MCP servers |
+| [mcp-auth-bearer](./mcp-auth-bearer/) | 🟢 LIVE | Bearer token auth |
+| [mcp-auth-api-key](./mcp-auth-api-key/) | 🟢 LIVE | API key header auth |
+| [mcp-tool-discovery](./mcp-tool-discovery/) | 🟢 LIVE | tools/list, caching, graceful degradation |
+| [mcp-admin-ui](./mcp-admin-ui/) | 🟢 LIVE | Orbit admin panel for MCP |
+| [mcp-observability](./mcp-observability/) | 🟢 LIVE | PostHog + Sentry traces |
+| [mcp-encryption](./mcp-encryption/) | 🟢 LIVE | AES-256-GCM credential storage |
+
+See also: [03-ai-bots/bot-tool-calling](../03-ai-bots/bot-tool-calling/)
\ No newline at end of file
diff --git a/docs/universe/features/04-mcp/mcp-admin-ui/README.md b/docs/universe/features/04-mcp/mcp-admin-ui/README.md
new file mode 100644
index 0000000..27dc8c2
--- /dev/null
+++ b/docs/universe/features/04-mcp/mcp-admin-ui/README.md
@@ -0,0 +1,26 @@
+# MCP Admin UI
+
+The MCP management interface inside [Orbit](../01-platform/orbit/). Lets operators manage bot MCP server configurations without touching code.
+
+## States
+
+| State | Shows |
+|---|---|
+| Loading | Spinner |
+| Empty | "No MCP servers" + add button |
+| Connected | ✅ green indicator |
+| Error | ❌ red indicator + message |
+| Testing | 🕑 spinner during connection test |
+| Removing | Progress during deletion |
+
+## Features
+
+- Per-bot server list (name, URL, status, tool count, last-checked)
+- Add/edit/remove servers
+- Test connection with raw tool discovery preview
+- Super-admin bypass — access all bot MCP configs
+
+## Related
+
+- [MCP server management](./mcp-server-management/) — the API layer behind this UI
+- [Orbit](../01-platform/orbit/) — parent admin dashboard
\ No newline at end of file
diff --git a/docs/universe/features/04-mcp/mcp-auth-api-key/README.md b/docs/universe/features/04-mcp/mcp-auth-api-key/README.md
new file mode 100644
index 0000000..26160b6
--- /dev/null
+++ b/docs/universe/features/04-mcp/mcp-auth-api-key/README.md
@@ -0,0 +1,8 @@
+# MCP API Key Auth
+
+API key authentication for MCP servers. Key is sent in `x-api-key` or a custom header. Stored encrypted at rest ([mcp-encryption](./mcp-encryption/)).
+
+## Related
+
+- [MCP OAuth](./mcp-oauth/) — for services that need OAuth
+- [MCP bearer auth](./mcp-auth-bearer/) — simpler bearer token
\ No newline at end of file
diff --git a/docs/universe/features/04-mcp/mcp-auth-bearer/README.md b/docs/universe/features/04-mcp/mcp-auth-bearer/README.md
new file mode 100644
index 0000000..179c4de
--- /dev/null
+++ b/docs/universe/features/04-mcp/mcp-auth-bearer/README.md
@@ -0,0 +1,8 @@
+# MCP Bearer Auth
+
+Simple bearer token authentication for MCP servers. Configure with a token, sent in the `Authorization: Bearer...` header. Token stored encrypted at rest ([mcp-encryption](./mcp-encryption/)).
+
+## Related
+
+- [MCP OAuth](./mcp-oauth/) — full OAuth flow for more complex auth
+- [MCP API key auth](./mcp-auth-api-key/) — alternative using header-based keys
\ No newline at end of file
diff --git a/docs/universe/features/04-mcp/mcp-encryption/README.md b/docs/universe/features/04-mcp/mcp-encryption/README.md
new file mode 100644
index 0000000..35ae960
--- /dev/null
+++ b/docs/universe/features/04-mcp/mcp-encryption/README.md
@@ -0,0 +1,22 @@
+# MCP Encryption
+
+All MCP credentials are encrypted at rest using AES-256-GCM, per row, scoped per creator.
+
+## What's Encrypted
+
+- Bearer tokens ([mcp-auth-bearer](./mcp-auth-bearer/))
+- OAuth access + refresh tokens ([mcp-oauth](./mcp-oauth/))
+- API keys ([mcp-auth-api-key](./mcp-auth-api-key/))
+- AI provider credentials ([bot-provider-config](../03-ai-bots/bot-provider-config/))
+
+## Security Model
+
+- Row-level encryption for multi-tenant isolation
+- Encryption key in environment variables
+- Admin API write path only — no public creation
+- Risks noted: no tool output sanitization, no creator-side server validation
+
+## Related
+
+- All MCP auth feature folders
+- [Bot provider config](../03-ai-bots/bot-provider-config/) — similarly encrypted
\ No newline at end of file
diff --git a/docs/universe/features/04-mcp/mcp-oauth/README.md b/docs/universe/features/04-mcp/mcp-oauth/README.md
new file mode 100644
index 0000000..332e07c
--- /dev/null
+++ b/docs/universe/features/04-mcp/mcp-oauth/README.md
@@ -0,0 +1,25 @@
+# MCP OAuth
+
+Full OAuth 2.0 authorization code flow with PKCE for MCP server authentication. Provider-agnostic — any OAuth-compatible MCP server works with zero hardcoded integrations.
+
+## Flow
+
+1. Bot admin configures OAuth provider (authorize URL, token URL, client ID/secret, scopes) in [Orbit](../01-platform/orbit/) or [admin API](../01-platform/admin-api/)
+2. Bot initiates OAuth via popup window
+3. User authorizes in provider's consent screen
+4. Callback routes token to Universe via `mcp-callback/route.ts`
+5. Token encrypted at rest per-server ([mcp-encryption](./mcp-encryption/))
+6. Automatic refresh on 401 responses
+
+## Features
+
+- PKCE for public clients
+- Auto-discovery via RFC 9728 authorization server metadata
+- Works with Attio, Xero, any OAuth MCP server
+- State token contains redirectUrl for correct callback routing
+
+## Related
+
+- [MCP bearer auth](./mcp-auth-bearer/) — simpler alternative
+- [MCP API key auth](./mcp-auth-api-key/) — simpler alternative
+- [MCP encryption](./mcp-encryption/) — token storage
\ No newline at end of file
diff --git a/docs/universe/features/04-mcp/mcp-observability/README.md b/docs/universe/features/04-mcp/mcp-observability/README.md
new file mode 100644
index 0000000..3d736da
--- /dev/null
+++ b/docs/universe/features/04-mcp/mcp-observability/README.md
@@ -0,0 +1,22 @@
+# MCP Observability
+
+AI trace monitoring and error tracking for MCP tool calls across Universe bots.
+
+## PostHog
+
+Events tagged with:
+- `mcp_tool_count` — how many tools are available per server
+- `mcp_latency` — execution time per tool call
+
+## Sentry
+
+Spans and errors for:
+- Tool discovery success/failure
+- Tool execution success/failure
+- Timeouts
+- Server connectivity issues
+
+## Related
+
+- [MCP tool discovery](./mcp-tool-discovery/) — what gets monitored
+- [Technology stack](../05-about/technology-stack/) — observability infrastructure
\ No newline at end of file
diff --git a/docs/universe/features/04-mcp/mcp-server-management/README.md b/docs/universe/features/04-mcp/mcp-server-management/README.md
new file mode 100644
index 0000000..8716fe5
--- /dev/null
+++ b/docs/universe/features/04-mcp/mcp-server-management/README.md
@@ -0,0 +1,22 @@
+# MCP Server Management
+
+Add, configure, and monitor MCP servers attached to each bot. Every bot can have multiple servers, each exposing a set of tools.
+
+## What You Can Do
+
+- **Add** — name + URL, pick auth type ([OAuth](./mcp-oauth/), [bearer](./mcp-auth-bearer/), [API key](./mcp-auth-api-key/))
+- **Test** — test connection shows raw `tools/list` response
+- **Monitor** — status indicators per server: ✅ connected, ❌ error, 🕑 testing
+- **View** — tool count, last-checked timestamp, connection log
+
+## Limits
+
+- 5 servers per bot (soft cap)
+- Admin API write path only — no public creation
+
+## Related
+
+- [MCP admin UI](./mcp-admin-ui/) — the Orbit interface
+- [MCP tool discovery](./mcp-tool-discovery/) — how tools are listed
+- [Bot tool calling](../03-ai-bots/bot-tool-calling/) — using tools in conversation
+- `BotMcpServersEditor.svelte` in `play/src/front/external-modules/bots/components/`
\ No newline at end of file
diff --git a/docs/universe/features/04-mcp/mcp-tool-discovery/README.md b/docs/universe/features/04-mcp/mcp-tool-discovery/README.md
new file mode 100644
index 0000000..0369c24
--- /dev/null
+++ b/docs/universe/features/04-mcp/mcp-tool-discovery/README.md
@@ -0,0 +1,28 @@
+# MCP Tool Discovery
+
+Auto-discovery of tools exposed by MCP servers via the `tools/list` handshake. The bridge between MCP servers and bot intelligence.
+
+## How It Works
+
+1. Bot calls `tools/list` on each configured [MCP server](./mcp-server-management/)
+2. Server responds with tool definitions (name, description, JSON input schema)
+3. Tool definitions cached per server with 1-hour TTL
+4. When AI decides to use a tool, the system calls `tools/call` with the AI-generated parameters
+
+## Graceful Degradation
+
+- If `tools/list` times out → empty tool list returned (bot still responds, just without tools)
+- If `tools/call` times out (5s per call, 10s total budget) → tool marked unavailable for that turn
+- Bot never crashes due to MCP server issues
+
+## Performance
+
+- 1-2 extra HTTP requests per conversation turn if tools are used
+- Slight increase in token cost (tool definitions in AI context)
+- Near-zero memory/CPU for the bot server
+
+## Related
+
+- [Bot tool calling](../03-ai-bots/bot-tool-calling/) — the conversation layer that uses discovered tools
+- [MCP server management](./mcp-server-management/) — configure which servers to discover from
+- `MCPConnector.ts` in workadventure-universe
\ No newline at end of file
diff --git a/docs/universe/features/05-about/README.md b/docs/universe/features/05-about/README.md
new file mode 100644
index 0000000..bbb3cf2
--- /dev/null
+++ b/docs/universe/features/05-about/README.md
@@ -0,0 +1,10 @@
+# 07 — About BAWES
+
+The organization behind Universe.
+
+| Feature | Status | What it is |
+|---|---|---|
+| [the-team](./the-team/) | 🟢 LIVE | Khalid and BAWES |
+| [technology-stack](./technology-stack/) | 🟢 LIVE | Tools and infrastructure |
+| [contact](./contact/) | 🟢 LIVE | How to reach us |
+| [legal](./legal/) | 🟢 LIVE | Terms of use + privacy policy |
\ No newline at end of file
diff --git a/docs/universe/features/05-about/contact/README.md b/docs/universe/features/05-about/contact/README.md
new file mode 100644
index 0000000..5b9d928
--- /dev/null
+++ b/docs/universe/features/05-about/contact/README.md
@@ -0,0 +1,6 @@
+# Contact
+
+- **Website:** bawes.net
+- **Blog:** blog.bawes.net
+- **GitHub:** github.com/BAWES-Universe
+- **X:** @khalidmnet
\ No newline at end of file
diff --git a/docs/universe/features/05-about/legal/README.md b/docs/universe/features/05-about/legal/README.md
new file mode 100644
index 0000000..e968297
--- /dev/null
+++ b/docs/universe/features/05-about/legal/README.md
@@ -0,0 +1,6 @@
+# Legal
+
+- **Terms of Use** — published on bawes.net
+- **Privacy Policy** — published on bawes.net
+
+Covers use of the Universe platform and bawes.net website.
\ No newline at end of file
diff --git a/docs/universe/features/05-about/technology-stack/README.md b/docs/universe/features/05-about/technology-stack/README.md
new file mode 100644
index 0000000..d195613
--- /dev/null
+++ b/docs/universe/features/05-about/technology-stack/README.md
@@ -0,0 +1,31 @@
+# Technology Stack
+
+## Frontend
+- **Marketing site:** Next.js 14, Tailwind CSS, Framer Motion
+- **Virtual world:** Phaser.js
+- **In-game UI:** Svelte (BotMcpServersEditor, BotDetailView)
+
+## Backend
+- **Runtime:** TypeScript/Node.js
+- **API:** Next.js API routes + WebSocket (Pusher)
+- **Database:** PostgreSQL (Prisma ORM)
+- **Cache:** Redis
+- **Chat:** Matrix / chat.bawes.net (optional)
+
+## AI
+- **Models:** OpenAI, Anthropic, Deepseek, LMStudio, Qwen 3B (default)
+- **Protocol:** MCP (Model Context Protocol) — streamable HTTP
+- **Agent runtime:** Custom-built
+
+## Video/Audio
+- **Engine:** LiveKit (spatial audio/video via WebRTC)
+
+## Infrastructure
+- **Hosting:** Coolify on Hetzner
+- **Containers:** Docker Compose / Helm (Kubernetes)
+- **Proxy:** Traefik
+
+## Observability
+- **Analytics:** PostHog ($ai_trace, $ai_generation)
+- **Error tracking:** Sentry
+- **CI/CD:** GitHub Actions + Release PRs
\ No newline at end of file
diff --git a/docs/universe/features/05-about/the-team/README.md b/docs/universe/features/05-about/the-team/README.md
new file mode 100644
index 0000000..dcecea8
--- /dev/null
+++ b/docs/universe/features/05-about/the-team/README.md
@@ -0,0 +1,6 @@
+# The Team
+
+**Khalid** — Founder and operator. "Operating the Universe. Recruiting talent, shipping weird things, and teaching monkeys how to build empires."
+
+- X: @khalidmnet
+- Medium: @enter-the-universe (31 followers, 45 following)
\ No newline at end of file
diff --git a/docs/universe/features/06-content/README.md b/docs/universe/features/06-content/README.md
new file mode 100644
index 0000000..f067620
--- /dev/null
+++ b/docs/universe/features/06-content/README.md
@@ -0,0 +1,5 @@
+# 08 — Content & Media
+
+| Feature | Status | What it is |
+|---|---|---|
+| [blog](./blog/) | 🟢 LIVE | Medium publication + 7 articles |
\ No newline at end of file
diff --git a/docs/universe/features/06-content/blog/README.md b/docs/universe/features/06-content/blog/README.md
new file mode 100644
index 0000000..5afbd58
--- /dev/null
+++ b/docs/universe/features/06-content/blog/README.md
@@ -0,0 +1,21 @@
+# Blog
+
+Medium publication at blog.bawes.net. Author: Khalid (@enter-the-universe).
+
+## Articles
+
+| # | Title | Date | Length |
+|---|---|---|---|
+| 1 | Beyond the Avatar: Why Spatial Computing and MCP Belong Together | Jul 7, 2026 | 6 min |
+| 2 | Prime Time: How a Monkey Taught Me That Wholeness Is the Real Success | Oct 5, 2025 | 3 min |
+| 3 | The Parable of the Mirror-Builders | Sep 30, 2025 | 2 min |
+| 4 | The Power of Zero | Sep 3, 2025 | 2 min |
+| 5 | The Dawn of a New Archetype | Sep 3, 2025 | 2 min |
+| 6 | Divine Compression Theory | Aug 1, 2025 | 1 min |
+| 7 | Why Monkeys Should Automate | Jul 2, 2025 | 2 min |
+
+## Related
+
+- [Monkey lore](../06-lore/monkey-lore/) — articles 2, 4, 5, 7
+- [Soft singularity](../06-lore/soft-singularity/) — article 1
+- [Power of Zero](../06-lore/power-of-zero/) — articles 4, 5
\ No newline at end of file
diff --git a/docs/universe/features/07-partners/README.md b/docs/universe/features/07-partners/README.md
new file mode 100644
index 0000000..38c7a5d
--- /dev/null
+++ b/docs/universe/features/07-partners/README.md
@@ -0,0 +1,5 @@
+# 09 — Partners
+
+| Feature | Status | What it is |
+|---|---|---|
+| [workadventure](./workadventure/) | 🔵 FORK SOURCE | Upstream project credit |
\ No newline at end of file
diff --git a/docs/universe/features/07-partners/workadventure/README.md b/docs/universe/features/07-partners/workadventure/README.md
new file mode 100644
index 0000000..5a5b16d
--- /dev/null
+++ b/docs/universe/features/07-partners/workadventure/README.md
@@ -0,0 +1,24 @@
+# WorkAdventure
+
+Universe is a fork of WorkAdventure by TheCodingMachine — an open-source (MIT) virtual world platform. We maintain an active relationship with the upstream project.
+
+## Credit
+
+We credit WorkAdventure:
+- On bawes.net — noted as built on WorkAdventure
+- In blog posts — "Universe is an open virtual world platform built on WorkAdventure"
+- This folder documents the inheritance chain
+
+## What We Inherited
+
+- Proximity chat, Tiled maps, WAM format, scripting API, Woka avatars, zones, megaphone, Matrix, OIDC, Docker self-hosting, white label
+
+## What We Built
+
+All of [03-ai-bots](../03-ai-bots/), [04-mcp](../04-mcp/), [Orbit](../01-platform/orbit/), [avatar platform](../02-spatial-world/avatar-platform/)
+
+## Links
+
+- Upstream: github.com/thecodingmachine/workadventure
+- Website: workadventu.re
+- Discord: discord.gg/G6Xh9ZM9aR
\ No newline at end of file
diff --git a/docs/universe/features/README.md b/docs/universe/features/README.md
new file mode 100644
index 0000000..f230e22
--- /dev/null
+++ b/docs/universe/features/README.md
@@ -0,0 +1,33 @@
+# Features
+
+Every feature, project, concept, and component in the Universe ecosystem. Each folder describes one thing — what it is, where the code lives, how it works.
+
+## Sections
+
+```
+features/
+├── 01-platform/         6 — fork, self-hosting, OIDC, admin API, Orbit admin, Orbit Model
+├── 02-spatial-world/   24 — maps, zones, chat, avatars, editors, scripting, comms, status
+├── 03-ai-bots/         13 — behaviors, streaming, tool calling, file parsing, media, gallery, recursive bots
+├── 04-mcp/              8 — servers, auth, tool discovery, admin UI, encryption
+├── 05-about/            4 — team, tech stack, contact, legal
+├── 06-content/          1 — blog (7 Medium articles)
+└── 07-partners/         1 — WorkAdventure (source fork)
+                    ———
+                    57 features
+```
+
+## Cross-References
+
+Features link to related features throughout. `[bot-tool-calling]` → see the feature in `03-ai-bots/bot-tool-calling`.
+
+## Status
+
+| Badge | Meaning |
+|---|---|
+| 🟢 LIVE | Shipped and running |
+| 🟡 PLANNED | Documented but not yet built |
+| ⚫ INACTIVE | Previously operated, currently down |
+| 🟡 COMING SOON | Planned but not built |
+| 🟡 VISION | Conceptual, not implemented |
+| 🔵 INHERITED | From WorkAdventure upstream |
diff --git a/docs/universe/site/00-navigation.md b/docs/universe/site/00-navigation.md
new file mode 100644
index 0000000..dbf60d5
--- /dev/null
+++ b/docs/universe/site/00-navigation.md
@@ -0,0 +1,22 @@
+# Navigation (Current)
+
+## Navbar links (desktop)
+
+| Link | Type |
+|------|------|
+| Home `/` | Internal |
+| How It Works `/how-it-works` | Internal |
+| Blog `https://blog.bawes.net` | External |
+| Market `/market` | Internal |
+| Components `/work` | Internal |
+| Manifesto `/manifesto` | Internal |
+| The Empty Seat `/empty-seat` | Internal |
+| Contact `/contact` | Internal |
+
+**Desktop:** Full link list displayed inline, plus a Discord CTA button ("Join us on Discord" → `https://discord.gg/CXceJWnwNT`)
+
+**Mobile:** Hamburger menu → full-screen overlay with same links. Discord button shown inline next to hamburger.
+
+## Logo
+
+Left side: BAWES logo image + "BAWES" (bold) + "Universe" (gradient)
diff --git a/docs/universe/site/01-hero.md b/docs/universe/site/01-hero.md
new file mode 100644
index 0000000..c5b6d76
--- /dev/null
+++ b/docs/universe/site/01-hero.md
@@ -0,0 +1,25 @@
+# Hero Section (Current)
+
+## Full viewport hero with WebGL canvas space background
+
+**Headline:**
+```
+Turn ideas into action
+together.
+```
+
+**Subheadline:**
+```
+We build and operate shared digital environments where people work, learn, trade, and collaborate in real time.
+```
+
+**Tagline:**
+```
+No friction. No silos. Just momentum.
+```
+
+**CTAs:**
+- "Enter the Universe" — gold gradient button, opens `universe.bawes.net` in new tab with cross-domain PostHog tracking
+- "See how it works" — secondary outline button, links to `/how-it-works`
+
+**Visual:** Canvas-based space background with stars, nebulae (golden, red, orange, deep purple), parallax on mouse movement, shooting stars, scroll-driven fade/scale.
diff --git a/docs/universe/site/02-homepage-sections.md b/docs/universe/site/02-homepage-sections.md
new file mode 100644
index 0000000..c8a7d4b
--- /dev/null
+++ b/docs/universe/site/02-homepage-sections.md
@@ -0,0 +1,106 @@
+# Homepage Sections (Current)
+
+Sections displayed below the hero on the home page (`/`), in order.
+
+---
+
+## 1. What is Universe?
+
+Logo badge + headline.
+
+**Headline:** "What is **Universe**?"
+
+**Body:**
+> Universe is a shared digital environment made of spaces, not apps or pages.
+>
+> People move through rooms and worlds, see who's around, and work together naturally, whether they're collaborating, studying, building, shopping, or just hanging out.
+
+**Highlight block:**
+> You don't switch tools.
+> **The space adapts to what you're doing.**
+
+---
+
+## 2. What people use it for
+
+Four grid cards, each with emoji, title, description. Staggered fade-in animation.
+
+| Card | Emoji | Description |
+|------|-------|-------------|
+| Work | 🤝 | Team spaces, focus rooms, spontaneous collaboration, real execution. |
+| Learning | 📚 | Personal study rooms, group learning, mentorship, digital campuses. |
+| Commerce | 🛍️ | Shops, services, and marketplaces embedded into shared spaces, connected to real-world tools. |
+| Community | 🎮 | Hangouts, gaming groups, events, casual meetups. |
+
+---
+
+## 3. Shared markets & commerce
+
+**Headline:** "Shared markets & **commerce**"
+
+**Body:**
+> Universe supports shared market experiences where people discover products, services, and opportunities together, not in isolation.
+
+**Two feature blocks:**
+1. **Commerce is tool-agnostic.** Shops and marketplaces can connect to whatever stack fits: Shopify, custom systems, booking tools, or existing infrastructure.
+2. **BAWES helps design and integrate** these experiences when needed. We don't just provide tools; we help you build.
+
+**CTA:** "Learn about markets in Universe" → `/market`
+
+---
+
+## 4. Get help when you need it
+
+**Headline:** "Get help when you need it"
+
+**Body:**
+> You can ask the Universe for help (guidance, people, or execution), and your request is routed to the right place.
+
+**Three animated phrases (staggered):**
+- Real humans.
+- Real work.
+- **Real progress.**
+
+**Highlight block:**
+> Universe doesn't promise answers to everything.
+> It promises a **path forward** for anything.
+
+**Bot capability highlight:**
+> Drop a file, get answers. Bots read PDFs, Word documents, Excel spreadsheets, and web pages — then answer your questions, summarize key points, and generate images and video. Not just chat. Real work.
+
+---
+
+## 5. Work with Universe Components
+
+**Headline:** "Work with **Universe Components**"
+
+**Body:**
+> Universe is built from modular components that work together seamlessly.
+> Each component serves a specific purpose while integrating naturally with the broader ecosystem.
+
+**CTA:** "Explore components" → `/work`
+
+---
+
+## 6. Open by default
+
+**Headline:** "Open by **default**"
+
+**Body:** "BAWES operates in the open."
+
+**Three cards:**
+- Open-source projects
+- Public community
+- Transparent systems
+
+---
+
+## 7. Closing CTA
+
+**Headline:** "You don't need to understand everything to start."
+
+**Subheadline:** "You just need a place where things **move forward**."
+
+**Dual CTA:**
+- "Enter the Universe" (gold gradient, opens universe.bawes.net)
+- "Talk to us" → `/contact`
diff --git a/docs/universe/site/03-how-it-works.md b/docs/universe/site/03-how-it-works.md
new file mode 100644
index 0000000..7ae6de5
--- /dev/null
+++ b/docs/universe/site/03-how-it-works.md
@@ -0,0 +1,62 @@
+# How It Works (Current)
+
+**Route:** `/how-it-works`
+**Headline:** "**Universe**, simply explained"
+
+**Subheadline:** "Universe is composed of spaces people can move through, not interfaces people click through."
+
+**Three tag badges:** "Presence matters." / "Context matters." / "Where you are shapes what you can do."
+
+---
+
+## Sections
+
+### 1. Orbit (Navigation)
+
+Orbit is the navigation layer of the Universe.
+
+Features:
+- discover universes, worlds, and rooms
+- understand what exists
+- jump directly to where activity is happening
+
+> Orbit shows you where you are in the universe: your location and position. Use it to discover and navigate what's around you. Think of Orbit as orientation, not hierarchy.
+
+### 2. The Structure: Universes → Worlds → Rooms
+
+Three-tier hierarchy:
+
+| Level | What it is | Examples |
+|-------|-----------|----------|
+| **Universes** | A first-class environment | an organization, a community, a project, a brand, a personal ecosystem |
+| **Worlds** | A functional domain inside a Universe | Work world, Learning world, Market world, Social world, Event world |
+| **Rooms** | Where things actually happen | collaboration, study, events, shops, hangouts, gameplay |
+
+Rooms are **spatial**, **contextual**, and **alive**.
+
+### 3. Maps & Room Templates
+
+Rooms are built using maps. Universe provides room templates (proven layouts designed for specific use cases) so people can start fast and build with confidence.
+
+Templates are **optional** — advanced users can customize or create their own.
+
+### 4. Membership & Access
+
+All spaces are open to explore. Membership exists at the world level and grants capabilities, not exclusivity.
+
+Members may: edit rooms, define areas, manage layouts, access restricted zones.
+
+**Areas & permissions:** Access control is spatial, not global. Using the Area Editor, members define zones inside rooms and control who can enter, who can interact, who can edit. This allows open spaces with protected cores, without private worlds.
+
+### 5. Editors
+
+| Editor | Purpose |
+|--------|---------|
+| **Map Editor** | Decorate rooms, customize layouts, shape the environment visually |
+| **Area Editor** | Define zones, assign permissions, control access and editing |
+
+**Motto:** "Creativity with **guardrails**."
+
+## CTA
+
+"Get Started" → `/contact`
diff --git a/docs/universe/site/04-market.md b/docs/universe/site/04-market.md
new file mode 100644
index 0000000..5026295
--- /dev/null
+++ b/docs/universe/site/04-market.md
@@ -0,0 +1,35 @@
+# Market Page (Current)
+
+**Route:** `/market`
+**Headline:** "Commerce in **shared spaces**"
+
+**Subheadline:** "Universe supports commerce as a spatial experience, not a locked-in platform."
+**Description:** "People explore shops, services, and marketplaces together inside shared environments, while transactions connect to the real world."
+
+---
+
+## What this enables
+
+### Shops & Services
+Brand spaces, community stores, service desks, pop-ups. Create immersive shopping experiences.
+
+### Market & Mall Experiences
+Shared market areas for launches, showcases, and discovery, social by design.
+
+---
+
+## Tool-Agnostic Commerce
+
+Universe does not replace your stack. You can connect:
+- Shopify
+- Custom commerce systems
+- Booking platforms
+- Ticketing tools
+- Payment providers
+- Your existing tools
+
+> **BAWES helps design and integrate** these experiences when needed.
+
+## CTA
+
+"Get help with commerce integration" → `/contact`
diff --git a/docs/universe/site/05-components.md b/docs/universe/site/05-components.md
new file mode 100644
index 0000000..8c0c987
--- /dev/null
+++ b/docs/universe/site/05-components.md
@@ -0,0 +1,37 @@
+# Components Page (Current)
+
+**Route:** `/work`
+**Headline:** "Work with **Universe Components**"
+
+**Description:** "Discover and connect powerful components to enhance your Universe experience. Each component is designed to work seamlessly within the Universe, helping you build, manage, and grow your digital environment."
+
+---
+
+## Available Components
+
+Nine components displayed as animated cards with emoji, title, description, status (Live / Coming Soon), and action buttons.
+
+| Component | Status | Description | Links |
+|-----------|--------|-------------|-------|
+| **BAWES Intelligence** 🧠 | Live v1 | Type a goal. Get a plan. Let AI turn your thoughts into proposals and action steps. | [Website](https://intelligence.bawes.net) |
+| **StudentHub** 🎓 | Live v1 | Hire students like cloud resources, instantly, with full tracking and support. | [Website](https://studenthub.co) · [Discord](https://discord.gg/CXceJWnwNT) |
+| **Plugn** 🛒 | Live v1 | Launch your store in minutes. Connect inventory, payments, and fulfillment without devs needed. | [Website](https://plugn.io) · [Discord](https://discord.gg/amjZaKAZ8X) |
+| **Thought Processor** 易 | Coming Soon | The Native OS for Thinking, Processing, and Action. Capture, organize, prioritize, and delegate. | — |
+| **Tribe** 👥 | Coming Soon | Find Your Tribe. Build Your Network. AI connects you with perfect student clubs based on your interests. | — |
+| **Tamr** 🔄 | Coming Soon | On-demand recruitment that matches the right person to the right place at the right time. | — |
+| **Universe Wallet** 💼 | Coming Soon | Manage your digital assets and connect with the People Directory. | — |
+| **Crypto Ecosystem** 💰 | Coming Soon | Payment infrastructure for seamless transactions within the Universe. | — |
+| **BAWES Sandbox** 🧪 | Coming Soon | Experiment and build in a safe, controlled environment. | — |
+
+---
+
+## How to Connect
+
+Three steps:
+1. **Choose Components** — Select the components you need. Mix and match.
+2. **Connect & Configure** — Each component integrates automatically. Configure to match your workflow.
+3. **Start Building** — Components work together to enhance your Universe experience.
+
+## CTA
+
+"Get Started" → `/contact`
diff --git a/docs/universe/site/06-manifesto.md b/docs/universe/site/06-manifesto.md
new file mode 100644
index 0000000..f836e3f
--- /dev/null
+++ b/docs/universe/site/06-manifesto.md
@@ -0,0 +1,27 @@
+# Manifesto Page (Current)
+
+**Route:** `/manifesto`
+**Headline:** "The BAWES Universe **Manifesto**"
+
+**Core statement:**
+> We are not building an app.
+> **We are building a universe.**
+>
+> A people-first environment designed to help ideas turn into action, faster, smarter, and with less friction.
+
+**Highlight block:**
+> We don't just support execution.
+> **We are execution.**
+
+## Core Principles
+
+| Principle | Description |
+|-----------|-------------|
+| **Open by Default** | Universes are interoperable and accessible. We build in the open, not behind walls. |
+| **Spatial, Not Hierarchical** | Presence and context shape experience. Navigation is orientation, not control. |
+| **Tool-Agnostic** | We don't lock you in. Connect what works. Build what you need. |
+| **Execution Over Promise** | Real work, real systems, real progress. We build, not just plan. |
+
+## CTA
+
+"Join the conversation" → `/contact`
diff --git a/docs/universe/site/07-empty-seat.md b/docs/universe/site/07-empty-seat.md
new file mode 100644
index 0000000..b2a1b44
--- /dev/null
+++ b/docs/universe/site/07-empty-seat.md
@@ -0,0 +1,37 @@
+# The Empty Seat (Current)
+
+**Route:** `/empty-seat`
+**Headline:** "The **Empty Seat**"
+
+**Core statement:**
+> No one owns the throne.
+> No one rules forever.
+> **Power is borrowed, not held.**
+
+**Summary:** The Empty Seat is a structural decision that protects continuity, creativity, and execution without ego. Leadership is functional, **not symbolic**.
+
+---
+
+## What it means
+
+In traditional organizations, leadership positions become permanent fixtures. The person in the seat becomes the seat itself, and the structure ossifies around them. The Empty Seat principle means that leadership roles are temporary, contextual, and transferable. The seat exists, but no one person owns it permanently.
+
+This creates space for:
+- Natural transitions as projects evolve
+- Different expertise leading at different times
+- Reduced ego-driven decision making
+- Continuity that doesn't depend on individuals
+
+---
+
+## Three implications
+
+| Principle | Description |
+|-----------|-------------|
+| **Functional Authority** | Leadership emerges from capability and context, not from titles or tenure. |
+| **Natural Rotation** | As needs change, different people step into leadership roles without friction or power struggles. |
+| **Reduced Friction** | Decisions flow from what needs to happen, not from who has the authority to decide. |
+
+## CTA
+
+"Learn more about our approach" → `/contact`
diff --git a/docs/universe/site/08-contact.md b/docs/universe/site/08-contact.md
new file mode 100644
index 0000000..3972c28
--- /dev/null
+++ b/docs/universe/site/08-contact.md
@@ -0,0 +1,26 @@
+# Contact Page (Current)
+
+**Route:** `/contact`
+**Headline:** "**Talk** to us"
+
+**Subheadline:**
+> Sometimes you don't need a product. You need clarity, structure, or help executing something real. We work with founders, teams, students, and organizations, intentionally and hands-on.
+
+---
+
+## Form
+
+| Field | Label | Type |
+|-------|-------|------|
+| Name | "Your name" | Text input |
+| Email | "your@email.com" | Email input |
+| Message | "Tell us about your project, idea, or challenge..." | Textarea |
+| Context | "Any additional details, timeline, or context..." | Textarea (optional) |
+
+Form submits to a Discord webhook. Shows success/error toast.
+
+## Alternative contact
+
+"Prefer to connect another way? Join our Discord community"
+
+Discord button → `https://discord.gg/CXceJWnwNT`
diff --git a/docs/universe/site/09-footer.md b/docs/universe/site/09-footer.md
new file mode 100644
index 0000000..255e7e5
--- /dev/null
+++ b/docs/universe/site/09-footer.md
@@ -0,0 +1,27 @@
+# Footer (Current)
+
+**Layout:** 4-column grid
+
+**Column 1 (Brand):**
+- BAWES logo + "BAWES Universe"
+- Tagline: "We are not building an app. We are building a universe. A fully integrated, people-first universe designed to help you think, act, build, and grow."
+- Social icons: Discord, GitHub
+
+**Column 2 (Navigate):**
+- How It Works → `/how-it-works`
+- Blog → `https://blog.bawes.net`
+- Market → `/market`
+- Components → `/work`
+
+**Column 3 (Philosophy):**
+- Manifesto → `/manifesto`
+- The Empty Seat → `/empty-seat`
+
+**Column 4 (Connect):**
+- Contact → `/contact`
+- Discord → `https://discord.gg/CXceJWnwNT`
+
+**Footer bottom:**
+- © BAWES Universe. Open by default.
+- Terms of Use → `/terms-of-use`
+- Privacy Policy → `/privacy-policy`
diff --git a/scripts/guardrail-scan.sh b/scripts/guardrail-scan.sh
index 785f6cf..fa4ab85 100755
--- a/scripts/guardrail-scan.sh
+++ b/scripts/guardrail-scan.sh
@@ -3,7 +3,7 @@
 set -e
 
 echo "=== 1. Secret patterns (public repo!) ==="
-if git grep -nE "(BEGIN RSA|BEGIN OPENSSH|ghp_|gho_|ghs_|ntn_[A-Za-z0-9]{20}|sk-[A-Za-z0-9]{20}|AKIA[0-9A-Z]{16}|xox[baprs]-|secret_[A-Za-z0-9]{20}|password[[:space:]]*=[[:space:]]*['\"][^'\"]{6,})" -- . ':!*.md' ':!.gitignore' 2>/dev/null; then
+if git grep -nE "(BEGIN RSA|BEGIN OPENSSH|ghp_|gho_|ghs_|ntn_[A-Za-z0-9]{20}|sk-[A-Za-z0-9]{20}|AKIA[0-9A-Z]{16}|xox[baprs]-|secret_[A-Za-z0-9]{20}|password[[:space:]]*=[[:space:]]*['\"][^'\"]{6,})" -- . ':!*.md' ':!.gitignore' ':!scripts/guardrail-scan.sh' 2>/dev/null; then
   echo "FAIL: secret pattern found. This repo is PUBLIC — remove it."
   exit 1
 fi