From d543f8d3f1c9c8212b97bd32f1b5ea708018ab70 Mon Sep 17 00:00:00 2001
From: Andy <andy.conlon@gmail.com>
Date: Fri, 6 Mar 2026 20:21:30 -0500
Subject: [PATCH] docs: add README and CLAUDE.md

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 CLAUDE.md | 30 ++++++++++++++++++++++++++++++
 README.md | 34 ++++++++++++++++++++++++++++++++++
 2 files changed, 64 insertions(+)
 create mode 100644 CLAUDE.md
 create mode 100644 README.md

diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..bc72577
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,30 @@
+# CLAUDE.md
+
+## Project
+
+Multiplayer NPC simulation game (Dwarf Fortress-inspired). Server-authoritative ECS architecture.
+
+## Structure
+
+- `shared/` -- Types and constants (no runtime code)
+- `server/` -- Node.js + Socket.io game server with ECS
+- `client/` -- Phaser 3 + TypeScript renderer
+- `chars/` -- Character sprite assets (do not modify)
+- `docs/plans/` -- Design and implementation docs
+
+## Commands
+
+- `npm install` -- install all workspace dependencies
+- `npm -w server run dev` -- start server (port 3001)
+- `npm -w server run test` -- run server tests (22 tests)
+- `npm -w client run dev` -- start client dev server (port 3000)
+- `npm -w client run build` -- build client for production
+
+## Key Conventions
+
+- ECS components are plain data objects, systems are pure functions
+- Server owns all game state; clients are renderers
+- Character sprites are 48x48 per frame, 6 cols x 4 rows spritesheet layout
+- Compositing: skins + accessories layered in z-order, cached as single textures
+- Shared types ensure client/server protocol agreement
+- Systems run in order: needsDecay -> npcBrain -> movement -> broadcast
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ba706c8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,34 @@
+# DFlike
+
+A multiplayer browser game inspired by Dwarf Fortress. Watch autonomous NPCs with needs-driven AI wander, eat, and rest in a shared world. Connect as an observer or take control of an avatar.
+
+## Quick Start
+
+```bash
+npm install
+# Terminal 1: Start server
+npm -w server run dev
+# Terminal 2: Start client
+npm -w client run dev
+```
+
+Open http://localhost:3000. Open multiple tabs for multiplayer.
+
+### Asset Setup
+
+Character assets must be present at `client/public/assets/chars/`. If missing:
+
+```bash
+cp -r chars client/public/assets/
+```
+
+## Controls
+
+- **WASD / Arrow Keys** -- pan camera (camera mode) or move avatar (avatar mode)
+- **TAB** -- toggle between camera and avatar mode
+
+## Architecture
+
+- **Server:** Node.js + Socket.io, server-authoritative ECS simulation at 10 ticks/sec
+- **Client:** Phaser 3 + TypeScript, Vite bundler
+- **Shared:** TypeScript types and constants