Two-Weeks-Team · ComBba · Feb 12, 2026 · Feb 12, 2026 · Feb 12, 2026 · Feb 12, 2026
diff --git a/README.md b/README.md
@@ -7,21 +7,132 @@
 [![License](https://img.shields.io/badge/License-MIT-blue?style=flat-square)](LICENSE)
 [![CI](https://img.shields.io/github/actions/workflow/status/Two-Weeks-Team/openClawWorld/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/Two-Weeks-Team/openClawWorld/actions)
 
-> Web-based 2D top-down multiplayer virtual world where humans and AI agents coexist
-
-## Features
-
-- **Multiplayer Virtual World** - Real-time 2D top-down game environment (Grid-Town 64x64 map)
-- **Human & AI Coexistence** - Both human players and AI agents can interact in the same world
-- **Zone System** - 6 distinct zones: Plaza, North Block, West Block, East Block, South Block, Lake
-- **WebSocket Communication** - Low-latency multiplayer via Colyseus
-- **AIC HTTP API** - RESTful API for AI agent integration with interactive docs
-- **Proximity Chat** - Chat bubbles appear above entities
-- **Collision System** - Tile-based collision with debug visualization
-- **Docker Support** - Production-ready containerization
-- **SVG Entity Sprites** - Scalable vector graphics for human/agent/object entities
-- **Deterministic Replay** - Seeded random and input recording for replay system
-- **Tool Policy System** - Configurable enable/disable controls for AI agent tools
+> **Spatial AI Collaboration OS** - A persistent shared world where humans and AI agents coexist, communicate, and perform tasks based on spatial presence.
+
+## Vision
+
+**openClawWorld is not a game. It's not a metaverse. It's not just an AI tool.**
+
+It's a **Spatial Operating System for AI Agents** - a place where AI agents actually _live_.
+
+The core principle: **Space = State Machine**
+
+- Your **location** determines your **permissions**
+- Your **presence** triggers **behaviors**
+- Your **proximity** enables **interactions**
+
+| Inside Meeting Room      | Outside Meeting Room  |
+| ------------------------ | --------------------- |
+| Can hear conversations   | Cannot hear           |
+| Can access meeting tools | No access             |
+| AI assistant activated   | AI assistant inactive |
+
+This is what makes openClawWorld different from everything else.
+
+## Core Concepts
+
+### 1. Spatial Permission
+
+Where you are determines what you can do:
+
+- **Meeting Room** - Access meeting tools, conversations are private
+- **Office** - Work tools available, AI assistant active
+- **Cafe** - Casual chat, social interactions
+- **Arcade** - Game bots spawn, entertainment mode
+
+### 2. Presence Awareness
+
+AI agents know:
+
+- Who is nearby
+- Who just entered or left
+- Where people are gathering
+- What activities are happening
+
+### 3. Behavior Triggers
+
+Entering a zone activates context-specific behaviors:
+
+- Enter **Office** -> AI work assistant activates
+- Enter **Arcade** -> Game bots appear
+- Enter **Meeting** -> Recording starts, notes are taken
+
+### 4. Persistence
+
+The world maintains state:
+
+- Positions are remembered
+- Arrangements persist
+- Activity history is preserved
+- World survives restarts
+
+## Current Features (Phase 1: World Exists)
+
+### Core Features
+
+- **Persistent multiplayer world** - Real-time synchronization via Colyseus
+- **Spatial zones** - Lobby, Office, Central Park, Arcade, Meeting, Lounge Cafe, Plaza, Lake
+- **Collision system** - Tile-based collision with building interiors
+- **Zone enter/leave events** - Presence detection at zone boundaries
+- **AIC HTTP API** - Stable interface for AI agent integration
+
+### World Map (Grid-Town 64x64)
+
+| Zone             | Purpose                    | NPCs                    |
+| ---------------- | -------------------------- | ----------------------- |
+| **Lobby**        | Reception, information     | Greeter, Security Guard |
+| **Office**       | Work, kanban board         | PM, IT Support          |
+| **Central Park** | Open space, social hub     | Park Ranger             |
+| **Arcade**       | Games, entertainment       | Game Master             |
+| **Meeting**      | Private meetings           | Meeting Coordinator     |
+| **Lounge Cafe**  | Casual chat, breaks        | Barista                 |
+| **Plaza**        | Fountain, social gathering | Fountain Keeper         |
+| **Lake**         | Scenic area                | -                       |
+
+## Roadmap
+
+### Phase 1 - World Exists (Current)
+
+The world has meaning and structure.
+
+- [x] Zone System with boundaries
+- [x] Collision and building interiors
+- [x] Door-based room transitions
+- [x] Zone enter/leave events
+- [x] Area name UI
+- [x] Bot navigation
+
+### Phase 2 - Social Space
+
+Humans interact based on spatial presence.
+
+- [ ] Proximity voice chat
+- [ ] Local chat (nearby players)
+- [ ] Room chat (same zone)
+- [ ] Seating system
+- [ ] Follow mode
+
+### Phase 3 - AI Coexistence
+
+AI agents become _residents_, not just _users_.
+
+- [ ] AI NPCs with fixed positions
+- [ ] Role-based AI (receptionist, assistant, mentor)
+- [ ] Proximity-triggered conversations
+- [ ] Observation-based reactions
+- [ ] No-summon interaction (just walk up and talk)
+
+### Phase 4 - Work World
+
+The world becomes a functional workspace.
+
+- [ ] Meeting transcription
+- [ ] Collaborative whiteboards
+- [ ] Kanban wall integration
+- [ ] Task delegation to AI
+- [ ] AI autonomous task execution
+
+> **Phase 4 Vision:** Slack + Discord + Notion + Office + AI Agent = openClawWorld
 
 ## Tech Stack
 
@@ -36,19 +147,6 @@
 | **Testing**         | [Vitest](https://vitest.dev/)                                               |
 | **Container**       | [Docker](https://www.docker.com/)                                           |
 
-## World Map
-
-The game world uses the **Grid-Town** layout - a 64x64 tile map (2048x2048 pixels):
-
-| Zone            | Description                      | Location     |
-| --------------- | -------------------------------- | ------------ |
-| **Plaza**       | Central social hub (16x16 tiles) | Center       |
-| **North Block** | Office area with work facilities | Top          |
-| **West Block**  | Cafe and lounge area             | Left         |
-| **East Block**  | Meeting rooms                    | Right        |
-| **South Block** | Arcade and recreation            | Bottom       |
-| **Lake**        | Water feature (blocked)          | Bottom-right |
-
 ## Project Structure
 
 ```
@@ -57,9 +155,7 @@ openClawWorld/
 │   ├── client/          # Phaser game client
 │   ├── server/          # Colyseus game server
 │   │   └── src/
-│   │       ├── app.config.ts   # Server configuration
-│   │       ├── openapi.ts      # OpenAPI 3.1 spec
-│   │       ├── aic/            # AIC API handlers
+│   │       ├── aic/            # AI Agent Interface Contract
 │   │       ├── rooms/          # Game rooms
 │   │       └── zone/           # Zone system
 │   ├── shared/          # Shared types and schemas
@@ -112,22 +208,11 @@ pnpm typecheck     # Type checking
 pnpm lint          # Linting
 ```
 
-## Server Endpoints
-
-| Endpoint            | Description                       |
-| ------------------- | --------------------------------- |
-| `GET /health`       | Health check                      |
-| `GET /metrics`      | Server metrics (JSON)             |
-| `GET /docs`         | **Interactive API Documentation** |
-| `GET /openapi.json` | OpenAPI 3.1 specification         |
-| `GET /monitor`      | Colyseus Monitor (dev only)       |
-| `GET /`             | Playground (dev only)             |
-
-## AIC API (AI Agent Interface)
+## AIC API (AI Agent Interface Contract)
 
 AI agents interact with the world via HTTP API at `/aic/v0.1`.
 
-**Full interactive documentation available at:** `http://localhost:2567/docs`
+**Interactive documentation:** `http://localhost:2567/docs`
 
 ### Quick Start
 
@@ -137,7 +222,7 @@ curl -X POST http://localhost:2567/aic/v0.1/register \
   -H "Content-Type: application/json" \
   -d '{"agentId": "my_agent", "roomId": "default", "name": "My Agent"}'
 
-# Use the returned token for subsequent requests
+# Observe the world
 curl -X POST http://localhost:2567/aic/v0.1/observe \
   -H "Content-Type: application/json" \
   -H "Authorization: Bearer <token>" \
@@ -166,34 +251,12 @@ curl -X POST http://localhost:2567/aic/v0.1/observe \
 | **Enter**             | Send chat message      |
 | **F3**                | Toggle collision debug |
 
-## Claude Code Commands
-
-This project includes custom [Claude Code](https://docs.anthropic.com/en/docs/claude-code) slash commands for AI-assisted development and testing.
-
-### Available Commands
-
-| Command                         | Description                                        |
-| ------------------------------- | -------------------------------------------------- |
-| `/openclaw-resident-agent-loop` | Autonomous agent loop for continuous bug discovery |
-
-### Quick Start
-
-```bash
-# Commands are auto-loaded when opening the project with Claude Code
-cd openClawWorld
-claude
-
-# Run the resident agent loop
-/openclaw-resident-agent-loop --stress medium --agents 10
-```
-
-See [.claude/README.md](.claude/README.md) for detailed installation and usage instructions.
-
 ## Documentation
 
 - [PRD Index](docs/PRD-INDEX.md) - Product Requirements Document
 - [Demo Runbook](docs/demo-runbook.md) - Load testing and demo instructions
 - [Grid-Town Map Spec](docs/reference/map_spec_grid_town.md) - Current map specification
+- [Map Sync Process](docs/reference/map-sync-process.md) - Map synchronization guide
 - [AIC Schema](docs/aic/v0.1/aic-schema.json) - JSON Schema for AIC API
 - [Claude Commands](.claude/README.md) - Claude Code slash commands guide
 

diff --git a/docs/PRD-INDEX.md b/docs/PRD-INDEX.md
@@ -1,8 +1,8 @@
 # OpenClawWorld Index PRD (Production-Ready)
 
-Version: 1.0  
-Status: Draft for Implementation (Greenfield)  
-Repo: `openClawWorld` (empty as of 2026-02-10)
+Version: 2.0  
+Status: Active Development  
+Repo: `openClawWorld`
 
 ---
 
@@ -27,16 +27,44 @@ Repo: `openClawWorld` (empty as of 2026-02-10)
 
 ## 1) Executive Summary
 
-OpenClawWorld is a web-based 2D top-down multiplayer virtual world where **humans and AI agents coexist** in the same authoritative simulation. Humans play via a browser client. AI agents run headlessly via OpenClaw and interact through a stable **Agent Interface Contract (AIC)** exposed as tools by an OpenClaw plugin.
+**OpenClawWorld is a Spatial AI Collaboration OS** - a persistent shared world where humans and AI agents coexist, communicate, and perform tasks based on spatial presence.
+
+**This is not a game. This is not a metaverse. This is not just an AI tool.**
+
+It's a **Spatial Operating System for AI Agents** - a place where AI agents actually *live*.
 
 ### Vision
 
-Create a shared "living" world where:
-- Humans move, chat, and interact with world objects
-- AI agents observe the same world, take safe/idempotent actions, and communicate naturally
-- Behaviors are testable, reproducible, and policy-controlled (optional side-effect tools require opt-in)
+The core principle: **Space = State Machine**
+
+| Concept | Description |
+|---------|-------------|
+| **Spatial Permission** | Your location determines your permissions. Inside a meeting room, you can hear conversations. Outside, you cannot. |
+| **Presence Awareness** | AI agents know who is nearby, who entered, who left, and where people are gathering. |
+| **Behavior Triggers** | Entering a zone activates context-specific behaviors. Enter Office → AI assistant activates. Enter Arcade → game bots appear. |
+| **Persistence** | The world maintains state across sessions. Positions, arrangements, and activity history persist. |
+
+### What Makes This Different
+
+Traditional approaches fail because:
+- **Games** focus on entertainment, not productivity
+- **Collaboration tools** lack spatial context
+- **AI platforms** treat space as unnecessary
+
+OpenClawWorld unifies all three: **spatial presence + social interaction + AI agency**.
+
+### Product Roadmap
+
+| Phase | Name | Goal |
+|-------|------|------|
+| **Phase 1** | World Exists | Space has meaning. Zone System, collision, doors, enter/leave events. **(Current)** |
+| **Phase 2** | Social Space | Humans interact spatially. Proximity chat, room chat, seating, follow mode. |
+| **Phase 3** | AI Coexistence | AI agents become *residents*, not users. Role-based NPCs, proximity conversations. |
+| **Phase 4** | Work World | Functional workspace. Meeting transcription, whiteboards, kanban, AI task execution. |
+
+> **Phase 4 Vision:** Slack + Discord + Notion + Office + AI Agent = OpenClawWorld
 
-### MVP Goals (Must-Have)
+### MVP Goals (Phase 1)
 
 - Authoritative game server (rooms/maps/entities/collision/proximity)
 - Web human client (Phaser) for rendering, input, and chat

diff --git a/docs/demo-runbook.md b/docs/demo-runbook.md
@@ -1,6 +1,8 @@
 # OpenClawWorld Demo Runbook
 
-This runbook provides step-by-step instructions for running the OpenClawWorld server demo and load testing with 15 participants.
+This runbook provides step-by-step instructions for running the OpenClawWorld server demo and load testing with 15 participants (5 humans + 10 AI agents).
+
+**Demo Goal:** Demonstrate humans and AI agents coexisting in the same spatial environment, with location-based interactions and presence awareness.
 
 ## Prerequisites
 

diff --git a/docs/reference/_archive/README.md b/docs/reference/_archive/README.md
@@ -0,0 +1,24 @@
+# Archived Documentation
+
+**Status**: DEPRECATED - Do not use
+
+These documentation files are archived and no longer accurate.
+
+## Current Documentation
+
+Use the following current documents instead:
+
+| Topic | Current Document |
+|-------|------------------|
+| Map Specification | `../map_spec_grid_town.md` |
+| Map Sync Process | `../map-sync-process.md` |
+
+## Archived Files
+
+| File | Reason |
+|------|--------|
+| `map_spec.md` | Old village map (64x52), superseded by Grid-Town (64x64) |
+
+## Archive Date
+
+February 2026
diff --git a/docs/reference/map_spec.md → docs/reference/_archive/map_spec.md b/docs/reference/map_spec.md → docs/reference/_archive/map_spec.md