Initialize project structure with core files, environment settings, and basic configurations

Co-authored-by: Copilot <copilot@github.com>

project.md

@@ -0,0 +1,367 @@
+# CharacterGarden – AI-Oriented Design Spec (Copilot-Ready)
+
+## 0. Purpose
+
+This document defines **hard contracts and system boundaries** for CharacterGarden.
+
+Goal: enable an AI coding assistant (e.g. Copilot) to implement the system step-by-step without ambiguity.
+
+Core principle:
+
+> The application owns truth. The LLM only translates and narrates.
+
+---
+
+## 1. System Overview
+
+### Pipeline
+
+```
+Prose Input
+→ Intent Extraction
+→ Canonical Actions
+→ Truth Engine Validation
+→ State Changes + Events
+→ Memory Storage
+→ Narration Output
+```
+
+---
+
+## 2. Core Contracts (STRICT)
+
+### 2.1 Entity
+
+```
+Entity {
+  id: string
+  type: string
+  name: string
+  attributes: object
+}
+```
+
+### 2.2 Action (Canonical)
+
+```
+Action {
+  actor: string (entity id)
+  verb: string (enum)
+  target?: string (entity id)
+  params?: object
+}
+```
+
+Allowed verbs (MVP):
+
+```
+move, open, close, take, drop, use, inspect, speak
+```
+
+### 2.3 Validation Result
+
+```
+ValidationResult {
+  accepted: Action[]
+  rejected: { action: Action, reason: string }[]
+  state_changes: StateChange[]
+}
+```
+
+### 2.4 State Change
+
+```
+StateChange {
+  entity_id: string
+  field: string
+  old_value: any
+  new_value: any
+}
+```
+
+### 2.5 Event
+
+```
+Event {
+  id: string
+  turn: number
+  action: Action
+  result: "success" | "fail"
+  timestamp: number
+}
+```
+
+---
+
+## 3. Truth Rules
+
+1. Only the **Truth Engine** can modify world state
+2. LLM output is NEVER directly trusted
+3. Every state change must be traceable to an Event
+4. Invalid actions must return explicit failure reasons
+
+---
+
+## 4. Memory Model
+
+Memory is NOT a single blob.
+
+### Types
+
+#### 4.1 Turn
+
+Raw input/output
+
+#### 4.2 Event
+
+Accepted or rejected actions
+
+#### 4.3 Fact
+
+Current world state (derived, not duplicated)
+
+#### 4.4 Belief
+
+```
+Belief {
+  entity_id: string
+  claim: string
+  confidence: number
+}
+```
+
+#### 4.5 Summary
+
+Compressed narrative context
+
+---
+
+## 5. Services
+
+### 5.1 App (Core Service)
+
+Responsibilities:
+
+* orchestrate turns
+* call LLM (optional)
+* run truth engine
+* manage memory
+
+Tech: Node.js (Express or Fastify)
+
+---
+
+### 5.2 Truth Engine (Module inside App)
+
+Responsibilities:
+
+* validate actions
+* enforce rules
+* apply state changes
+* emit events
+
+NO LLM USAGE
+
+---
+
+### 5.3 LLM Adapter (Optional)
+
+Responsibilities:
+
+* extract actions from prose
+* resolve references
+* generate narration
+* summarize memory
+
+Backend: Ollama
+
+---
+
+### 5.4 Frontend
+
+Responsibilities:
+
+* send input
+* display output
+* optionally inspect state/events
+
+Minimal React or Vue app
+
+---
+
+## 6. Turn Flow (IMPLEMENT EXACTLY)
+
+```
+1. Receive user input (string)
+2. Store raw turn
+3. Extract actions (LLM or fallback parser)
+4. Validate actions (truth engine)
+5. Apply accepted changes
+6. Store events
+7. Generate narration
+8. Return response
+```
+
+---
+
+## 7. Storage
+
+### SQLite (MVP)
+
+Tables:
+
+* entities
+* events
+* turns
+* beliefs
+* summaries
+
+File location:
+
+```
+/data/sqlite/app.db
+```
+
+---
+
+## 8. Docker Design
+
+### Services
+
+```
+services:
+  app
+  frontend
+  ollama (optional)
+```
+
+### Principles
+
+* No host dependencies beyond Docker
+* Persist only `/data`
+* Use `.env` for config
+* No hidden setup scripts
+
+---
+
+## 9. Folder Structure
+
+```
+charactergarden/
+  docker-compose.yml
+  .env
+  app/
+  frontend/
+  data/
+    sqlite/
+```
+
+---
+
+## 10. MVP Scope
+
+STRICT LIMITS:
+
+* 1–2 rooms
+* ≤3 characters
+* ≤10 actions
+* no complex AI autonomy
+* no multi-agent loops yet
+
+---
+
+## 11. Non-Goals (DO NOT BUILD YET)
+
+* microservices
+* distributed systems
+* plugin frameworks
+* advanced agent loops
+* cloud dependencies
+
+---
+
+## 12. Development Workflow Rule
+
+A root-level file named `thoughts.md` must exist and be maintained throughout development.
+
+Purpose of `thoughts.md`:
+
+* record current implementation status
+* record the next planned steps
+* record blockers, assumptions, and unresolved questions
+* summarize architectural decisions already made
+* preserve continuity across editor sessions or context loss
+
+Rules for `thoughts.md`:
+
+* update it after each meaningful implementation step
+* keep entries concise and factual
+* do not use it for chain-of-thought dumping or vague brainstorming
+* use it as a project progress log and working memory
+* when resuming work, review `thoughts.md` first before making changes
+* when changing architecture, record what changed and why
+* when a task is incomplete, note exactly what remains
+
+Recommended structure:
+
+```md
+# thoughts.md
+
+## Current Status
+- what is implemented
+- what is partially implemented
+- what is broken or unverified
+
+## Current Architecture Decisions
+- key decisions and constraints
+
+## Next Steps
+- ordered checklist of immediate tasks
+
+## Open Questions
+- unresolved design or implementation questions
+
+## Session Notes
+- short dated notes describing recent progress
+```
+
+Copilot instruction:
+
+> Before starting work, read `thoughts.md`. After completing any meaningful change, update `thoughts.md` to reflect current status, next steps, and any unresolved issues.
+
+## 13. Development Order
+
+1. Define entities + actions
+2. Implement truth engine
+3. Add SQLite persistence
+4. Build API endpoints
+5. Add minimal UI
+6. Add LLM integration
+
+---
+
+## 14. Key Rule
+
+> If the system works without an LLM, the architecture is correct.
+
+---
+
+## 15. Expected Behavior
+
+* deterministic state
+* explainable failures
+* replayable sessions
+* inspectable memory
+
+---
+
+## 16. Future Extensions (NOT NOW)
+
+* branching timelines
+* advanced belief systems
+* multi-agent arbitration
+* long-term memory compression
+
+---
+
+## END SPEC