Create VISION.md

VISION.md

@@ -0,0 +1,154 @@
+# Claw3D Vision
+
+Claw3D is an open-source 3D environment for visualizing and interacting with AI agents powered by OpenClaw.
+
+The long-term goal of Claw3D is to build a living 3D world where AI agents and humans collaborate: a kind of digital city where agents operate, communicate, and perform tasks in a shared visual space.
+
+OpenClaw acts as the intelligence and orchestration engine, while Claw3D provides the visual layer and interactive environment that makes agent activity understandable, inspectable, and collaborative.
+
+This document explains the direction of the project and the guardrails guiding its development.
+
+Project overview and developer documentation can be found in:
+
+- [`README.md`](README.md)
+- [`ROADMAP.md`](ROADMAP.md)
+- [`CONTRIBUTING.md`](CONTRIBUTING.md)
+
+## Why Claw3D Exists
+
+AI systems are becoming increasingly capable, but their behavior is often invisible or difficult to understand.
+
+Claw3D aims to solve this by providing a visual interface for AI systems, allowing people to:
+
+- observe AI agents operating in real time
+- understand system behavior visually
+- collaborate with AI in shared environments
+- debug and inspect complex agent interactions
+
+The ultimate vision is a 3D city of AI agents, where:
+
+- agents represent services, tasks, and workflows
+- humans can explore, monitor, and interact with them
+- systems become understandable through spatial interaction
+
+## Relationship to OpenClaw
+
+Claw3D is designed to work with OpenClaw, not replace it.
+
+OpenClaw provides:
+
+- agent orchestration
+- tools and integrations
+- communication channels
+- task execution
+- model provider integrations
+
+Claw3D provides:
+
+- visualization
+- interaction
+- spatial representation of agents and systems
+- collaborative environments for humans and AI
+
+In simple terms:
+
+```text
+OpenClaw -> intelligence and task execution
+Claw3D   -> visualization and interaction layer
+```
+
+Maintaining compatibility with OpenClaw is an important design goal.
+
+Features that require breaking OpenClaw integration will generally not be accepted unless there is a strong architectural reason.
+
+## Current Priorities
+
+Claw3D is still in an early stage of development.
+
+Current priorities include:
+
+### Stability and Reliability
+
+- bug fixes
+- predictable rendering behavior
+- improving the developer experience
+
+### Core Architecture
+
+- defining how agents map to visual entities
+- building a scalable world model
+- establishing a clean integration path with OpenClaw
+
+### Developer Ergonomics
+
+- clear APIs for extending the environment
+- easy local setup
+- straightforward contribution paths
+
+### Visualization Primitives
+
+- representing agents
+- representing workflows
+- representing system activity in spatial form
+
+## Contribution Rules
+
+To keep the project maintainable:
+
+- One PR = one topic. Avoid bundling unrelated changes.
+- Very large PRs may be declined or split into smaller pieces.
+- Architectural changes should be discussed in issues before implementation.
+- Contributors should respect the project's direction and scope.
+
+Claw3D is still evolving quickly, so iteration is expected.
+
+## Architecture Direction
+
+Claw3D is designed as a visual layer on top of agent systems.
+
+The system should remain:
+
+- modular
+- extensible
+- easy to experiment with
+
+The current stack focuses on:
+
+- Three.js
+- WebGL
+- browser-based rendering
+- integration with OpenClaw runtime systems
+
+The goal is to keep the environment accessible to developers and contributors.
+
+## What We Will Not Merge (For Now)
+
+To maintain focus, the following types of contributions are generally avoided:
+
+- features that break compatibility with OpenClaw
+- major architectural rewrites without prior discussion
+- replacing the rendering stack without strong technical justification
+- heavy framework layers that reduce hackability
+- extremely large PRs without prior coordination
+- unrelated product experiments that do not advance the Claw3D vision
+
+This list is a directional guardrail, not a permanent restriction.
+
+Strong technical arguments or user demand may change these decisions.
+
+## Long-Term Direction
+
+The long-term vision for Claw3D is ambitious:
+
+**A 3D city of AI agents.**
+
+In this environment:
+
+- AI agents operate as visible entities
+- systems become spatially understandable
+- humans can interact with agent systems in real time
+- collaboration between humans and AI becomes natural
+
+Instead of interacting with invisible systems through logs and dashboards, users will be able to walk through and interact with the systems themselves.
+
+Claw3D is an early step toward that future.