docs: Refactor README, add CONTRIBUTING.md and LICENSE

CONTRIBUTING.md

@@ -0,0 +1,68 @@
+# Contributing to OpenCode Vibe
+
+We focus on speed, precision, and type safety. We use **Bun** for everything.
+
+## Core Philosophy
+
+1.  **Core Owns Computation**: Logic lives in `packages/core`. React only binds UI.
+2.  **Push-Based State**: We use `createWorldStream()` via Effect/Atoms.
+3.  **Type Safety First**: No `any`. No type assertions unless absolutely necessary.
+
+## Development Setup
+
+**Prerequisites**: [Bun](https://bun.sh) v1.3+
+
+```bash
+# Install dependencies
+bun install
+
+# Start development server
+bun dev
+```
+
+## Workflow
+
+### 1. Make Changes
+- Follow **TDD**: Write failing tests (Red) → Implement (Green) → Clean up (Refactor).
+- Use **Vitest** for testing: `bun test`.
+
+### 2. Verify Quality
+Before committing, you **MUST** pass all checks:
+
+```bash
+bun format         # Fix formatting (Biome)
+bun lint           # Check linting (oxlint)
+bun run typecheck  # Check types (Turbo)
+```
+
+> **Note**: `bun run typecheck` checks the entire monorepo. Do not skip this.
+
+### 3. Commit & PR
+- We use **Changesets** for versioning.
+- If your change affects published packages, run:
+  ```bash
+  bun changeset
+  ```
+- Follow the prompt to add a summary.
+
+## Monorepo Structure
+
+- **`apps/web/`** - Next.js 16 web application (App Router, RSC, Tailwind)
+- **`apps/swarm-cli/`** - CLI for visualizing world state across servers
+- **`packages/core/`** - World stream, atoms, Effect services, types
+- **`packages/react/`** - React bindings (hooks, providers, store)
+
+## Documentation
+
+- **`apps/web/README.md`** - Web app architecture and patterns
+- **`packages/core/README.md`** - Core SDK and world stream documentation
+- **`packages/react/README.md`** - React hooks and providers
+- **`docs/adr/`** - Architecture Decision Records
+  - [ADR-016: Core Layer Responsibility](docs/adr/016-core-layer-responsibility.md) (Core owns computation, React binds UI)
+  - [ADR-018: Reactive World Stream](docs/adr/018-reactive-world-stream.md) (`createWorldStream()` is THE API)
+- **`docs/guides/`** - Implementation guides (SSE sync, mobile, subagents)
+- **`AGENTS.md`** - AI agent conventions and development patterns
+
+## License
+
+By contributing, you agree that your code will be licensed under the MIT License.

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OpenCode VIBE
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,50 +1,31 @@
-# opencode-vibe 🏄‍♂️
-
-```
-                                      _      │       _ _
-  ___  _ __   ___ _ __   ___ ___   __| | ___ │__   _(_) |__   ___
- / _ \| '_ \ / _ \ '_ \ / __/ _ \ / _` |/ _ \│\ \ / / | '_ \ / _ \
-| (_) | |_) |  __/ | | | (_| (_) | (_| |  __/│ \ V /| | |_) |  __/
- \___/| .__/ \___|_| |_|\___\___/ \__,_|\___│  \_/ |_|_.__/ \___|
-      |_|                                   │
-```
+![header](demo/header.png)
 
 Next.js 16 rebuild of the OpenCode web application. Real-time chat UI with streaming message display, SSE sync, and React Server Components.
 
-> **Warning:** This project uses Next.js 16 canary - bleeding edge, expect rough edges. Catppuccin-themed because we're not savages.
+> **Warning:** This project uses Next.js 16 canary - bleeding edge. Catppuccin-themed because we're not savages.
 
 ## Quick Start
 
-**Prerequisites:** [Bun](https://bun.sh) v1.3+ and [OpenCode CLI](https://github.com/sst/opencode) running locally.
-
-```bash
-# 1. Install dependencies
-bun install
-
-# 2. Start OpenCode (any mode - TUI or serve)
-cd /path/to/your/project
-opencode
+**Prerequisites:** [Bun](https://bun.sh) v1.3+ and [OpenCode CLI](https://github.com/sst/opencode).
 
-# 3. Start the web UI
-bun dev
+1. **Start OpenCode in your project:**
+   Navigate to the project you want to work on and keep this running:
+   ```bash
+   cd /path/to/your/project
+   opencode
+   ```
 
-# 4. Open browser
-# Navigate to: http://localhost:8423
-```
+2. **Start the Web UI:**
+   Clone this repo, install, and run:
+   ```bash
+   git clone https://github.com/joelhooks/opencode-vibe.git
+   cd opencode-vibe
+   bun install
+   bun dev
+   ```
 
-The web UI auto-discovers all running OpenCode processes. No configuration needed.
-
----
-
-## What's Here
-
-**Monorepo structure:**
-
-- **`apps/web/`** - Next.js 16 web application (App Router, RSC, Tailwind)
-- **`apps/swarm-cli/`** - CLI for visualizing world state across servers
-- **`packages/core/`** - World stream, atoms, Effect services, types
-- **`packages/react/`** - React bindings (hooks, providers, store)
-- **`docs/`** - Architecture Decision Records and implementation guides
+3. **Open Browser:**
+   Go to `http://localhost:8423`
 
 ---
 
@@ -61,29 +42,6 @@ The web UI auto-discovers all running OpenCode processes. No configuration neede
 
 ---
 
-## Development
-
-**Available scripts:**
-
-```bash
-# Development
-bun dev                 # Start Next.js dev server (port 8423 = VIBE)
-bun build               # Production build
-
-# Code quality
-bun run typecheck       # TypeScript check (via turbo, checks all packages)
-bun lint                # Run oxlint
-bun format              # Format with Biome
-
-# Testing
-bun test                # Run tests (Vitest)
-bun test --watch        # Watch mode
-```
-
-**CRITICAL:** Always run `bun run typecheck` from repo root before committing. Turbo checks the full monorepo.
-
----
-
 ## Tech Stack
 
 | Layer          | Technology            | Why                                 |
@@ -100,28 +58,10 @@ bun test --watch        # Watch mode
 
 ---
 
-## Documentation
-
-- **`apps/web/README.md`** - Web app architecture and patterns
-- **`packages/core/README.md`** - Core SDK and world stream documentation
-- **`packages/react/README.md`** - React hooks and providers
-- **`docs/adr/`** - Architecture Decision Records
-  - ADR-016: Core Layer Responsibility (Core owns computation, React binds UI)
-  - ADR-018: Reactive World Stream (`createWorldStream()` is THE API)
-- **`docs/guides/`** - Implementation guides (SSE sync, mobile, subagents)
-- **`AGENTS.md`** - AI agent conventions and development patterns
-
----
-
 ## Contributing
 
-1. Use Bun (not npm/pnpm)
-2. Follow TDD: RED → GREEN → REFACTOR
-3. Run `bun format` before committing
-4. Check `bun lint` and `bun run typecheck` pass
-
----
+See **[CONTRIBUTING.md](CONTRIBUTING.md)** for development workflow, architecture docs, and project structure.
 
 ## License
 
-MIT
+This project is licensed under the MIT License - see the **[LICENSE](LICENSE)** file for details.