docs: add README for open source launch

README.md

···
+# Phoenix VCS
+
+**Regenerative version control that compiles intent to working software.**
+
+Phoenix takes a specification written in plain language, extracts structured requirements, and generates a working application — database, API, validation, and UI — with full traceability from every line of spec to every line of generated code.
+
+```
+spec/todos.md (40 lines)  →  phoenix bootstrap  →  working app
+```
+
+## What it does
+
+Write what you want in a markdown spec:
+
+```markdown
+## Tasks
+
+- A task has a title, a priority (urgent, high, normal, low), and an optional due date
+- Users can create tasks by providing at least a title
+- Users can mark a task as complete or reopen a completed task
+- Users can filter tasks by status, project, or priority
+- Overdue tasks must be visually highlighted
+```
+
+Phoenix compiles this through a pipeline:
+
+```
+Spec → Clauses → Canonical Requirements → Implementation Units → Generated Code
+```
+
+Each transformation is tracked. Change one line in the spec and Phoenix knows exactly which code needs to regenerate — and which doesn't.
+
+## Quick start
+
+```bash
+# Install
+git clone https://github.com/chad/phoenix.git
+cd phoenix
+npm install
+npm run build
+
+# Create a project with the sqlite-web-api architecture
+mkdir my-app && cd my-app
+mkdir spec
+
+# Write your spec
+cat > spec/app.md << 'EOF'
+# My App
+
+## Items
+
+- An item has a name and a quantity
+- Users can create, view, update, and delete items
+- Name must not be empty
+EOF
+
+# Generate
+npx phoenix init --arch=sqlite-web-api
+npx phoenix bootstrap
+
+# Run
+npm install
+npm run dev
+# → http://localhost:3000
+```
+
+## Architecture targets
+
+Phoenix doesn't just generate code — it compiles to an **architecture**. The architecture target defines the runtime, frameworks, patterns, and conventions. The spec defines *what*, the architecture defines *how*.
+
+The first built-in target is `sqlite-web-api`:
+- **HTTP**: [Hono](https://hono.dev)
+- **Database**: [better-sqlite3](https://github.com/WiseLibs/better-sqlite3)
+- **Validation**: [Zod](https://zod.dev)
+- **Pattern**: Route modules with shared DB, migration system, Zod schemas
+
+New architectures can be added by creating a single file in `src/architectures/`. The pipeline doesn't change — only the compilation target.
+
+## The pipeline
+
+```
+┌──────────┐    ┌──────────┐    ┌──────────────┐    ┌──────┐    ┌───────────┐
+│ Spec     │ →  │ Clauses  │ →  │ Canonical    │ →  │ IUs  │ →  │ Generated │
+│ (markdown)│    │ (parsed) │    │ Requirements │    │      │    │ Code      │
+└──────────┘    └──────────┘    └──────────────┘    └──────┘    └───────────┘
+                                                                      │
+     ◄──────────── Provenance edges track every transformation ───────┘
+```
+
+- **Spec ingestion**: Parses markdown into content-addressed clauses with semantic hashes
+- **Canonicalization**: Extracts typed requirements (REQUIREMENT, CONSTRAINT, INVARIANT, DEFINITION, CONTEXT) with confidence scores and relationship edges
+- **IU planning**: Groups requirements into Implementation Units with risk tiers, contracts, and boundary policies
+- **Code generation**: LLM generates real implementations guided by architecture-specific prompts and few-shot examples, with typecheck-and-retry
+- **Selective invalidation**: Change one spec line → only the dependent subtree regenerates
+
+## Visualization
+
+```bash
+npx phoenix inspect
+```
+
+Opens an interactive pipeline visualizer in your browser. Click the **Spec** tab to see your spec text with hover highlighting — click any line to trace its path through clauses → canonical nodes → IUs → generated files.
+
+## CLI
+
+```bash
+phoenix init [--arch=NAME]    # Initialize a project
+phoenix bootstrap             # Full pipeline: ingest → canonicalize → plan → generate
+phoenix ingest [--verbose]    # Ingest spec changes (shows diff before applying)
+phoenix diff                  # Show clause-level diffs
+phoenix canonicalize          # Extract canonical requirements
+phoenix regen [--iu=ID]       # Regenerate code (all or specific IU)
+phoenix status                # Trust dashboard
+phoenix inspect               # Interactive pipeline visualization
+```
+
+## Examples
+
+### [todo-app](examples/todo-app/)
+
+A Todoist-style task manager generated from a [user-centric spec](examples/todo-app/spec/todos.md). Features:
+- Tasks with priorities, due dates, projects, completion tracking
+- Projects with colors and active task counts
+- Filtering by status, priority, and project
+- Stats summary with completion percentage
+- Full web UI with sidebar, forms, filters
+- REST API for integration with external tools
+
+All generated from ~40 lines of behavioral requirements.
+
+### [phoenix-self](examples/phoenix-self/)
+
+Phoenix specifying itself. The [PRD](PRD.md) decomposed into 6 specs covering ingestion, canonicalization, implementation, integrity, operations, and platform. Used to stress-test the canonicalization pipeline on real-world complexity.
+
+### Other examples
+
+- [settle-up](examples/settle-up/) — Expense splitting with debt simplification
+- [pixel-wars](examples/pixel-wars/) — Real-time multiplayer territory game
+- [tictactoe](examples/tictactoe/) — Multiplayer game with matchmaking
+- [taskflow](examples/taskflow/) — Task management with analytics
+
+## How it works under the hood
+
+### Canonicalization
+
+Every spec sentence is scored against 5 canonical types using a keyword rubric with configurable weights. The resolution engine deduplicates nodes via token Jaccard similarity, infers typed edges (constrains, refines, defines, invariant_of), and builds a hierarchical graph. The pipeline was optimized through 32 automated experiments (autoresearch-style) across 18 gold-standard specs.
+
+### Code generation
+
+The LLM receives a structured prompt with:
+1. Canonical requirements, constraints, invariants, and definitions for the IU
+2. Architecture-specific system prompt (import rules, patterns, conventions)
+3. Few-shot code examples showing the exact patterns to follow
+4. Related context from other spec sections
+5. Sibling module mount paths (so the web UI knows where the API lives)
+
+If generation fails or doesn't typecheck, the system retries with error feedback. If that fails, it falls back to architecture-aware stubs that still produce valid, mountable modules.
+
+### Drift detection
+
+Phoenix tracks a manifest of every generated file's content hash. `phoenix status` compares the working tree against the manifest and flags any unlabeled manual edits. This is how Phoenix knows if you've modified generated code and need to either promote the change to a spec requirement or add a waiver.
+
+## Status
+
+Alpha. The core pipeline works end-to-end — spec to working app with full traceability. The `sqlite-web-api` architecture target generates functional CRUD APIs with web UIs from behavioral specs.
+
+What's next:
+- More architecture targets (Express + Postgres, Cloudflare Workers + D1, CLI apps)
+- Smarter IU planner (merge cross-cutting concerns into parent resources)
+- Selective regeneration from spec edits (the pipeline supports it, the UX needs work)
+- Test generation and evidence collection
+- Multi-file spec projects with cross-references
+
+## License
+
+MIT