fivocell 1.0.0 → 1.0.2

package/README.md

@@ -1,65 +1,54 @@
-# 🧠 Cell
+# FIVO Cell
 
-> **Your coding taste. Learned once. Applied everywhere. Forever free.**
+<div align="center">
 
-`Apache 2.0` &nbsp; `Local-First` &nbsp; `Free Forever` &nbsp; `5+ Surfaces` &nbsp; `203 Tests Passing`
+**Your coding taste. Learned once. Applied everywhere. Forever free.**
 
----
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
+[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey.svg)](#)
+[![Version](https://img.shields.io/badge/Version-1.0.0-purple.svg)](#)
 
-<p align="center">
-  <strong>🌍 The AI world is closing fast. Walled gardens everywhere.</strong><br>
-  Let's build something open. Together. Like Linux did.<br>
-  <em>I had limited tokens. You have the rest. ❤️</em><br>
-  Fork it. Ship it. Own it. This is <strong>ours</strong> — not mine.<br>
-  <strong>You show up → we all win. 🫂</strong>
-</p>
+`🌍 Local-First` • `🆓 Free Forever` • `🔗 5+ AI Surfaces`
 
 ---
 
-## 🤔 The Problem Nobody Talks About
-
-You use 4 different AI coding tools. Claude Code for architecture. Cursor for quick edits. Windsurf for deep refactors. Copilot for autocomplete.
+</div>
 
-**Every single one of them is a walled garden.**
+Every AI tool you use has amnesia. Claude doesn't remember what you taught Cursor. Copilot never learned from the fix you made in Windsurf. You repeat yourself. You reject the same patterns. You waste hours context-switching between tools that share nothing.
 
-Claude doesn't know what you taught Cursor. Copilot doesn't remember what you fixed in Windsurf. You repeat the same edits. You reject the same patterns. You waste the same 40% of your time context-switching between tools.
+**This is the last time you'll explain yourself to a machine.**
 
-The AI industry sold you "personalization" — but locked it inside their own tool. Your taste isn't portable. Your preferences aren't yours.
+Cell is a daemon that lives on your machine. It watches how you edit AI-generated code — across every tool — and builds a mathematical model of your taste. Then it injects that taste back into every AI you use.
 
-**That ends today.**
-
----
-
-## ✨ What Cell Does
-
-Cell is a tiny daemon that runs on your machine. It watches how you edit AI-generated code — across **every** tool — and learns your taste. Then it quietly injects that taste back into every AI you use.
+**One profile. Every surface. Zero config.**
 
 ```
           ┌──────────┐
-          │  VS Code │──┐
+          │  VS Code  │──┐
+          └──────────┘  │
+          ┌──────────┐  │     ┌──────────────────┐
+          │  Cursor   │──┤     │                  │
+          └──────────┘  │     │   CELL DAEMON    │   Your taste,
+          ┌──────────┐  ├────►│   (localhost)    │──► everywhere.
+          │ Windsurf │──┤     │                  │
+          └──────────┘  │     │  0 cloud deps    │
+          ┌──────────┐  │     └──────────────────┘
+          │  Claude   │──┤
           └──────────┘  │
-          ┌──────────┐  │     ┌─────────────────┐
-          │  Cursor  │──┤     │                 │
-          └──────────┘  │     │   CELL DAEMON   │    Your taste,
-          ┌──────────┐  ├────►│   (localhost)   │───► everywhere.
-          │ Windsurf │──┤     │                 │
-          └──────────┘  │     │  40 modules     │
-          ┌──────────┐  │     │  203 tests      │
-          │  Claude  │──┤     │  0 cloud deps   │
-          └──────────┘  │     └─────────────────┘
           ┌──────────┐  │
-          │  Codex   │──┤
+          │  Codex    │──┤
           └──────────┘  │
           ┌──────────┐  │
-          │ Terminal │──┘
+          │ Terminal  │──┤
+          └──────────┘  │
+          ┌──────────┐  │
+          │  Copilot  │──┘
           └──────────┘
 ```
 
-**Learn once. Apply everywhere. Zero config. Zero cost.**
-
 ---
 
-## ⚡ Quick Install
+## Quick Install
 
 ```bash
 npm i -g fivocell
@@ -67,201 +56,450 @@ cell init
 cell daemon start
 ```
 
-Extensions (manual for now — auto-installer coming in v1.1):
-- VS Code / Cursor / Windsurf: Install `.vsix` from [releases](https://github.com/thevinsoni/cell/releases)
-- Claude Code / Codex CLI: Add MCP config to `~/.claude/claude_desktop_config.json` or `~/.codex/mcp.json`
-- Terminal: Source the shell hook from `extensions/shell/install.sh`
-
-That's it. Three commands. 30 seconds. 5+ surfaces.
+**Three commands. Thirty seconds. Done.**
 
+```bash
+cell status    # Verify it's working
 ```
-✅ Daemon started (localhost:9876)
-✅ VS Code extension linked
-✅ Cursor extension linked
-✅ Windsurf extension linked
-✅ Claude Code MCP configured
-✅ Codex CLI MCP configured
-✅ Shell hook added
-✅ Copilot instructions created
 
-Done. Just code. 🧠
-```
+---
 
-Verify anytime:
+## 5-Minute Quickstart
 
 ```bash
+# 1. Initialize Cell in any project
+cd my-project
+cell init
+
+# 2. Start the daemon (background service)
+cell daemon start
+
+# 3. Learn from a code edit
+cell learn --file src/app.ts --diff "const x=1 → const x = 1"
+
+# 4. See your taste profile
 cell status
+
+# 5. Get recommendations
+cell community
+
+# 6. Predict your next action
+cell next
+
+# 7. Check privacy settings
+cell privacy
 ```
 
+---
+
+## The 9 Intelligence Chapters
+
+Cell's brain is organized into 9 intelligence layers. Each layer runs independently and persists to its own JSON file in `~/.fivo/cell/`.
+
+### Chapter 2 — Learning Layer
+
+The foundation. Watches 4 signals from every AI tool:
+
+| Signal | Trigger | Weight |
+|--------|---------|--------|
+| **Edit Diff** | You changed what AI wrote | High |
+| **Reject** | You deleted AI output entirely | High |
+| **Retry** | You asked AI to regenerate | Medium |
+| **Accept** | You kept it as-is | Low |
+
+Includes: Validator, Classifier, ConfidenceEngine, QualityEngine, LifecycleTracker, RelationshipEngine, PatternSearch, RankingEngine.
+
 ```
-🧠 FIVO Cell Status
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-Daemon:        ✅ Running (localhost:9876)
-VS Code:       ✅ Installed
-Cursor:        ✅ Installed
-Windsurf:      ✅ Installed
-Claude Code:   ✅ MCP configured (5 tools)
-Codex CLI:     ✅ MCP configured
-Shell Hook:    ✅ Active
-Copilot Sync:  ✅ Active
-Modules:       40 loaded
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Commands: cell init, cell status, cell taste show, cell taste reset, cell learn
 ```
 
----
+### Chapter 3 — Outcome Engine
+
+Tracks what happens AFTER your code ships. 7 event types (deploy, review, test, bug, perf, security, rollback) with 3-factor confidence scoring, 4-value trend analysis, 5-factor health assessment, and 6-category leaderboard.
+
+```
+No CLI commands — accessed via daemon API at /api/outcomes
+```
+
+### Chapter 4 — Recommendation Engine V2
+
+5-factor scoring (pattern strength, recency, contextual relevance, team consensus, outcome validation) with diversity enforcement, evidence-based reasons, and cold-start handling.
+
+```
+Commands: cell community (community priors feed into recommendations)
+```
+
+### Chapter 5 — Project DNA
+
+Filesystem scanner that profiles any repository in 40-200ms. 10 profiling systems: stack detection, framework detection, style detection, test patterns, dependency patterns, architecture patterns, config patterns, language stats, file tree, git patterns. Fingerprint comparison for similarity scoring.
+
+```
+No CLI commands — accessed via daemon API at /api/project-dna
+```
+
+### Chapter 6 — Knowledge Graph V2
+
+11 edge types (imports, calls, extends, implements, defines, uses, configures, tests, documents, deploys, monitors) across 10 subsystems. Path discovery with weighted traversal and influence scoring.
+
+```
+No CLI commands — accessed via daemon API at /api/knowledge-graph
+```
+
+### Chapter 7 — Community Intelligence
 
-## 🏆 Cell vs The World
+10 systems: privacy guard (14 allowed fields only), rankings, trends (hour/day/week), clusters, playbooks, benchmarks, reputation, insights. Aggregates patterns from 5000+ simulated developers.
 
-Nobody else does what Cell does. Here's the raw truth:
+```
+Commands: cell community, cell community-live, cell community-full
+```
+
+### Chapter 8 — Organization Intelligence
+
+10 systems: org isolation, team profiles, knowledge silos, bus factor, risk assessment, playbooks, executive insights, benchmarks. Team collaboration tools with voting and conflict resolution.
+
+```
+Commands: cell push, cell pull, cell vote, cell silos, cell review, cell standup, cell handoff
+```
 
-| Capability | Cell | Copilot | Cursor | ChatGPT | Continue |
-|---|---|---|---|---|---|
-| **Learns YOUR taste** | ✅ | ❌ | ❌ | ⚠️ | ❌ |
-| **Cross-tool (5+ surfaces)** | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **Session snapshots** | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **Community wisdom** | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **100% Free forever** | ✅ | ⚠️ | ❌ | ⚠️ | ✅ |
-| **Privacy (local-first)** | ✅ | ❌ | ❌ | ❌ | ✅ |
-| **Model intelligence** | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **Error prediction** | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **Security guardian** | ✅ | ⚠️ | ❌ | ❌ | ❌ |
-| **Build failure prediction** | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **Team taste sync (beta)** | ✅ | ❌ | ❌ | ❌ | ❌ |
-| **Dead code detection** | ✅ | ❌ | ❌ | ❌ | ❌ |
+### Chapter 9 — Cross-Layer Intelligence
+
+10 systems: unified context builder, 7-dimension intelligence score, evidence fusion engine, knowledge gap detector, opportunity finder, risk analyzer, lifecycle classifier, decision generator, multi-level benchmarker, report generator.
+
+```
+No CLI commands — accessed via daemon API at /api/cross-layer
+```
+
+---
 
-**Cell is not an AI coding tool.** It's the taste layer that makes every AI coding tool smarter.
+## CLI Commands Reference (42 Commands)
+
+### Learning & Profile
+
+| Command | Description |
+|---------|-------------|
+| `cell init` | Initialize Cell in current project |
+| `cell status` | Show taste profile summary |
+| `cell taste show` | Display cell.md taste profile |
+| `cell taste reset` | Reset all learned patterns |
+| `cell learn --file --diff` | Feed a code edit for learning |
+
+### Team Collaboration
+
+| Command | Description |
+|---------|-------------|
+| `cell push` | Push taste to team directory |
+| `cell pull` | Pull team or member taste |
+| `cell vote` | Vote on pattern conflict |
+| `cell handoff` | Generate teammate handoff summary |
+| `cell silos` | Detect knowledge silos |
+| `cell review` | Generate PR review summary |
+| `cell standup` | Generate daily standup |
+
+### Predictions
+
+| Command | Description |
+|---------|-------------|
+| `cell next` | Predict next coding action |
+| `cell branch` | Pre-generate files from branch name |
+| `cell gentests` | Generate test cases for a function |
+| `cell errors` | Predict potential errors in code |
+| `cell buildcheck` | Predict build failures |
+| `cell mergecheck` | Predict merge conflicts |
+| `cell scan` | Scan code for security vulnerabilities |
+| `cell perf` | Analyze code for performance issues |
+
+### Community
+
+| Command | Description |
+|---------|-------------|
+| `cell community` | Show community prior patterns |
+| `cell community-live` | Show live community stats |
+| `cell community-full` | Show full community dashboard |
+
+### Code Health
+
+| Command | Description |
+|---------|-------------|
+| `cell deadcode` | Detect dead code in a file |
+| `cell cycles` | Detect circular dependencies |
+| `cell dupes` | Detect code duplication |
+| `cell complexity` | Analyze code complexity |
+| `cell deps` | Check dependency health |
+
+### Utilities
+
+| Command | Description |
+|---------|-------------|
+| `cell snapshot` | Capture or restore project context |
+| `cell sync` | Sync patterns across projects |
+| `cell solutions` | Search solution index |
+| `cell langswitch` | Get language switch guide |
+| `cell resume` | Check for interruption and resume |
+| `cell offline` | Check offline queue status |
+| `cell abtest` | Run A/B test |
+| `cell xdomain` | Cross-domain projections (research) |
+
+### Infrastructure
+
+| Command | Description |
+|---------|-------------|
+| `cell daemon start` | Start background daemon |
+| `cell daemon stop` | Stop background daemon |
+| `cell daemon restart` | Restart daemon |
+| `cell daemon status` | Check daemon status |
+| `cell cloud on` | Enable cloud sync |
+| `cell cloud off` | Disable cloud sync |
+| `cell cloud status` | Show cloud sync status |
+| `cell privacy` | Show privacy settings |
 
 ---
 
-## 🎯 Every Feature, Explained
-
-### 🧠 Taste Learning (The Core)
-Cell watches 4 types of signals as you work:
-- **Edit Diff** — you changed what the AI wrote
-- **Reject** — you deleted the AI's output entirely
-- **Retry** — you asked the AI to regenerate
-- **Accept** — you kept it as-is
-
-Over time, Cell builds a mathematical model of your taste using **Beta distributions** with 95% credible intervals. You can see exactly what it learned — and how confident it is — in `cell.md`.
-
-### 🔗 Cross-Tool Continuity
-Your taste follows you. VS Code → Cursor → Windsurf → Claude Code → Codex → Terminal. Same profile. Same patterns. Zero repetition.
-
-### 🔮 Predictive Intelligence
-Cell doesn't just learn — it anticipates:
-- **Next-Action Prediction** — knows you'll write tests after routes
-- **Build Failure Prevention** — warns before you commit broken code
-- **Error Detection** — catches null refs, missing awaits, type mismatches
-- **Security Guardian** — blocks SQL injection, hardcoded secrets, XSS in real-time
-- **Performance Analysis** — spots N+1 queries, suggests eager loading
-- **Merge Conflict Resolution** — predicts conflicts before they happen
-- **Test Anticipation** — generates test cases from function signatures
-- **Git Branch Pre-generation** — reads branch name, scaffolds boilerplate
-
-### 👥 Team Intelligence
-- **Auto-computed team taste** — no meetings, no style guides, no arguments
-- **Conflict resolution** — data-driven voting, 48-hour window, audit trail
-- **PR Review Assistant** — summarizes changes, flags pattern deviations
-- **Standup Auto-generation** — daily summary: done, in-progress, blocked
-- **Onboarding Accelerator** — new devs inherit team taste, 40-60% faster first PR
-
-### 🏥 Code Health
-- **Dead Code Detection** — unused functions, imports, dependencies
-- **Circular Dependency Analysis** — DFS cycle detection with break-point suggestions
-- **Duplication Scanning** — AST-based clone detection, unified helper generation
-- **Complexity Hotspots** — cyclomatic complexity ranking with refactor suggestions
-- **Dependency Health** — version freshness, non-breaking update plans
-
-### 🧠 Model Intelligence
-Cell tracks which AI model performs best for which task — from real signals, not marketing claims. "Should I use Claude or GPT for this refactor?" Cell knows.
+## MCP Server
+
+Cell includes a Model Context Protocol (MCP) server that exposes the full intelligence engine to any MCP-compatible client (Claude Code, Codex CLI, Cursor, etc.).
+
+### 25 Tools
+
+| Tool | Description |
+|------|-------------|
+| `cell_learn` | Learn from a code edit |
+| `cell_predict_next` | Predict next coding action |
+| `cell_predict_errors` | Predict errors in code |
+| `cell_predict_build` | Predict build failures |
+| `cell_predict_merge` | Predict merge conflicts |
+| `cell_scan_security` | Scan for security issues |
+| `cell_analyze_perf` | Analyze performance issues |
+| `cell_generate_tests` | Generate test cases |
+| `cell_generate_branch` | Pre-generate branch files |
+| `cell_community_stats` | Get community pattern stats |
+| `cell_community_trends` | Get community trends |
+| `cell_community_playbooks` | Get community playbooks |
+| `cell_outcome_events` | Record outcome events |
+| `cell_outcome_health` | Get outcome health score |
+| `cell_outcome_leaderboard` | Get outcome leaderboard |
+| `cell_project_dna` | Build project DNA profile |
+| `cell_knowledge_graph` | Query knowledge graph |
+| `cell_knowledge_paths` | Discover knowledge paths |
+| `cell_org_profile` | Get organization profile |
+| `cell_org_silos` | Detect knowledge silos |
+| `cell_org_busfactor` | Compute bus factor |
+| `cell_cross_layer_report` | Generate intelligence report |
+| `cell_cross_layer_gaps` | Detect knowledge gaps |
+| `cell_cross_layer_opportunities` | Find opportunities |
+| `cell_cross_layer_risks` | Analyze risks |
+
+### 8 Resources
+
+- `cell://patterns` — All learned patterns
+- `cell://profile` — Developer taste profile
+- `cell://outcomes` — Outcome event history
+- `cell://community/trends` — Community trends
+- `cell://community/rankings` — Community rankings
+- `cell://org/teams` — Team profiles
+- `cell://org/benchmarks` — Organization benchmarks
+- `cell://cross-layer/report` — Full intelligence report
+
+### Setup
+
+```json
+{
+  "mcpServers": {
+    "cell": {
+      "command": "node",
+      "args": ["path/to/packages/mcp-server/dist/server.js"]
+    }
+  }
+}
+```
+
+Or via Claude Code:
+
+```bash
+claude mcp add cell -- node path/to/packages/mcp-server/dist/server.js
+```
 
 ---
 
-## 🔒 Privacy: What We Store, What We DON'T
+## Daemon
 
-This is the most important section. Read it.
+The daemon is a REST API server on port 9876 with WebSocket streaming on port 9878.
 
-### ❌ What Cell NEVER Stores or Sends
+```bash
+# Start
+cell daemon start
 
-| Data | Status | Why |
-|---|---|---|
-| Your source code | **NEVER leaves machine** | Code stays in your editor. Cell only sees diffs. |
-| File paths | **NEVER stored** | Only extension (.ts, .py) is extracted for language context. |
-| Git history | **NEVER accessed** | Cell doesn't touch your git repo. |
-| API keys / secrets | **NEVER captured** | Guardian detects them to warn you, never stores them. |
-| Personal identity | **NEVER required** | No email. No signup. No account. |
-| Project names | **NEVER sent to cloud** | Obfuscated before any opt-in sync. |
+# Check status
+cell daemon status
 
-### ✅ What Cell DOES Store (Locally Only)
+# Stop
+cell daemon stop
+```
 
-| Data | Location | Purpose |
-|---|---|---|
-| Pattern stats | `~/.fivo/cell/` (JSON file store) | "You prefer const over let (92% confidence)" |
-| Signal counts | Local DB | How many times you accepted/rejected a pattern |
-| Session snapshots | `~/.fivo/cell/snapshots/` | Crash recovery — last 10 snapshots, 5 min history |
-| Config inferences | Local DB | "This project uses TypeScript strict mode" |
+125+ API endpoints across all 9 intelligence layers.
 
-### ☁️ What Goes to Cloud (ON by Default — Off Anytime)
+---
 
-Cloud sync is **ON by default** to give you better suggestions from day one. One command to turn off:
+## Extensions
 
-| Data | How It's Protected |
-|---|---|
-| Pattern stats (examples) | `"prefers const over let (92%)"`, `"uses named exports (88%)"`, `"vitest over jest (95%)"` |
-| Your fingerprint | `sha256(machine_id + git_email)` — irreversible hash |
-| Community contribution | Aggregated with 10K+ others. Your patterns become one drop in an ocean. |
-| ❌ What's NOT shared | File paths. Project names. Source code. API keys. Git history. |
+| Tool | Type | Setup |
+|------|------|-------|
+| **VS Code** | Extension | `code --install-extension extensions/vscode/fivo-cell-0.2.0.vsix` |
+| **Cursor** | Extension | Same .vsix file |
+| **Windsurf** | Extension | Same .vsix file |
+| **Claude Code** | MCP | `claude mcp add cell -- node packages/mcp-server/dist/server.js` |
+| **Codex CLI** | MCP | `codex mcp add cell -- node packages/mcp-server/dist/server.js` |
+| **Copilot** | Sync Script | `node extensions/shell/copilot-sync.js` |
+| **Terminal** | Shell Hook | `source extensions/shell/install.sh` |
 
-```bash
-cell cloud off     # Fully offline. Nothing leaves your machine.
-cell cloud on      # Re-enable anytime.
+---
+
+## Team Mode
+
+Cell supports local-network team collaboration without any cloud dependency.
+
+```
+Developer A ──┐
+              ├── Cell Daemon (port 9876)
+Developer B ──┘     │
+                    │ LAN
+Developer C ──┐     │
+              ├─────┘
+Developer D ──┘
 ```
 
-**Your code is the product you sell. Cell protects it like it's our own.**
+- `cell push` — Share your taste with the team
+- `cell pull` — Pull team taste profile
+- `cell vote` — Resolve pattern conflicts democratically
+- `cell handoff` — Generate context summaries for teammates
+- `cell standup` — Auto-generated daily standups
+
+Up to 10-20 developers can collaborate on a single local network.
 
 ---
 
-## 🤝 Why Trust Cell?
+## Cloud Sync
 
-### 1. Open Source (Apache 2.0)
-Every line of the daemon is public. You can read it. Audit it. Fork it. The code that runs on your machine has zero secrets.
+Cloud sync is **ON by default** and shares only anonymous pattern statistics:
 
-### 2. Local-First Architecture
-Cell works 100% offline. Cloud is a bonus, not a requirement. Turn it off with `cell cloud off` — enforced at daemon level. If `cell.fivo.live` disappears tomorrow, your taste still works.
+```
+"prefers const over let (87%)"
+"uses named exports, not default (83%)"
+"vitest over jest (91%)"
+```
 
-### 3. No VC Money. No Data Business Model.
-FIVO (the company behind Cell) makes money from enterprise AI infrastructure — not from selling developer data. Cell is free because it's cross-subsidized by FIVO Enterprise, not because you're the product.
+**Your source code never leaves your machine.** No file paths. No project names. No secrets.
 
-### 4. You Can Uninstall in 5 Seconds
 ```bash
-npm uninstall -g fivocell
-rm -rf ~/.fivo/cell
+cell cloud off    # Fully offline mode
+cell cloud on     # Re-enable sync
+cell cloud status # Check current status
 ```
-Everything is gone. No lingering processes. No cloud accounts to delete. No "export your data" forms. Just gone.
 
-### 5. Built for Developers, by Developers
-We use Cell ourselves. Every day. Across multiple tools. We built it because we needed it. The privacy guarantees aren't marketing — they're what we demanded for our own code.
+---
+
+## Privacy
+
+### Never stored or transmitted
+
+| Data | Guarantee |
+|------|-----------|
+| Your source code | Never leaves your machine. Cell only sees diffs. |
+| File paths | Never persisted or transmitted. Only file extensions. |
+| Git history | Never accessed. |
+| API keys / secrets | Detected and warned. Never captured. |
+| Identity | No email. No signup. No account. |
+| Project names | Obfuscated before any transmission. |
+
+### Stored locally only
+
+| Data | Location |
+|------|----------|
+| Pattern preferences | `~/.fivo/cell/pattern-store.json` |
+| Outcomes | `~/.fivo/cell/outcomes.json` |
+| Developer profiles | `~/.fivo/cell/profiles/` |
+| Project DNA | `~/.fivo/cell/project-dna.json` |
+| Knowledge graph | `~/.fivo/cell/knowledge-graph.json` |
+| Community intelligence | `~/.fivo/cell/community-intelligence.json` |
+| Organization intelligence | `~/.fivo/cell/org-intelligence.json` |
+| Cross-layer intelligence | `~/.fivo/cell/cross-layer-intelligence.json` |
+| Session snapshots | `~/.fivo/cell/snapshots/` |
 
 ---
 
-##  Get Started
+## Architecture
+
+```
+CLI (42 commands)
+  │
+  ├──► Daemon (port 9876) ──► REST API (125+ endpoints)
+  │       │                      │
+  │       ├──► WebSocket (port 9878) ──► Real-time streaming
+  │       │
+  │       └──► MCP Server (port 9877) ──► 25 tools, 8 resources
+  │
+  ├──► Intelligence Engine
+  │       ├── Learning Layer (Ch2)
+  │       ├── Outcome Engine (Ch3)
+  │       ├── Recommendation Engine (Ch4)
+  │       ├── Project DNA (Ch5)
+  │       ├── Knowledge Graph (Ch6)
+  │       ├── Community Intelligence (Ch7)
+  │       ├── Organization Intelligence (Ch8)
+  │       └── Cross-Layer Intelligence (Ch9)
+  │
+  └──► Storage (~/.fivo/cell/)
+          ├── 30+ JSON stores
+          ├── Each layer has its own file
+          └── No database required
+```
+
+Each intelligence layer:
+- Runs independently
+- Persists to its own JSON file
+- Can be reset without affecting others
+- Has 80+ hostile assertions in tests
+
+---
+
+## Running Tests
 
 ```bash
-npm i -g fivocell
-cell init
-cell daemon start
+# All tests
+npx jest --passWithNoTests --no-coverage
+
+# Specific chapter
+npx jest --passWithNoTests --no-coverage src/core/__tests__/chapter9-hostile.test.ts
+
+# Real-world validation
+npx ts-node src/validation/quick-run.ts
 ```
 
-Then just code. Cell learns in the background. No tutorials. No config files. No YAML.
+**772 hostile assertions across 9 chapters — all passing.**
 
 ---
 
-## 🌐 Links
+## Why Trust Cell
 
-- **Website**: [cell.fivo.live](https://cell.fivo.live)
-- **FIVO Enterprise**: [fivo.live](https://fivo.live) — 25x cheaper AI for teams
-- **Discord**: [discord.gg/fivo](https://discord.gg/fivo)
+- **Open Source. Apache 2.0.** Every line is public. Audit it. Fork it. Own it.
+- **Local-First. Always.** Zero cloud dependency. If cell.fivo.live disappears tomorrow, your taste doesn't.
+- **Free. Permanently.** Cell is supported by our community. You're not the product.
+- **Clean uninstall.** `npm uninstall -g fivocell` + `rm -rf ~/.fivo/cell`. Done.
 
 ---
 
-**Cell — Your taste. Every tool. Forever free.** 🧠
+## Links
+
+| Resource | URL |
+|----------|-----|
+| Website | [cell.fivo.live](https://cell.fivo.live) |
+| Enterprise | [fivo.live](https://fivo.live) |
+| Community | [discord.gg/fivo](https://discord.gg/fivo) |
+| NPM | `npm i -g fivocell` |
+
+---
+
+<div align="center">
+
+**Your taste. Every tool. Forever free.**
+
+</div>