fivocell 2.0.0 → 3.0.0

package/README.md

@@ -1,697 +1,104 @@
-<div align="center">
-
-# 🧠 FIVO Cell
-
-<img src="https://img.shields.io/badge/License-Apache%202.0-blue?style=for-the-badge&logo=apache" alt="License">
-<img src="https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-lightgrey?style=for-the-badge&logo=linux" alt="Platform">
-<img src="https://img.shields.io/badge/Version-2.0.0-purple?style=for-the-badge" alt="Version">
-<img src="https://img.shields.io/badge/Tests-391%20Passing-brightgreen?style=for-the-badge" alt="Tests">
-
-<br><br>
-
-```
-╔══════════════════════════════════════════════════════════════╗
-║                                                              ║
-║   🧬  Your Coding DNA. Learned Once. Applied Everywhere.     ║
-║                                                              ║
-║   🌍 Local-First  •  🆓 Free Forever  •  🔗 5+ AI Surfaces  ║
-║   🛡️ Zero Code Leaves Machine  •  🔓 Apache 2.0            ║
-║                                                              ║
-╚══════════════════════════════════════════════════════════════╝
-```
-
-</div>
-
----
-
-<div align="center">
-
-## 🤔 The Problem
-
-</div>
-
-<div align="center">
-
-```
-╔════════════════════════════════════════════════════════════╗
-║                                                            ║
-║   💬 "Use arrow functions"          💬 "I prefer TypeScript"║
-║   💬 "Add error handling"           💬 "Don't use any"     ║
-║   💬 "Use Zod for validation"       💬 "Named exports please"║
-║                                                            ║
-║   You repeat yourself. Every. Single. Day.                ║
-║                  To every. Single. AI tool.               ║
-║                                                            ║
-╚════════════════════════════════════════════════════════════╝
-```
-
-</div>
-
-**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. Gemini starts from zero every session. You waste **hours** context-switching between tools that share absolutely nothing.
-
-> **This is the last time you'll explain yourself to a machine.**
-
----
-
-<div align="center">
-
-## 🎯 The Solution
-
-</div>
-
-<div align="center">
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│                       🧠 CELL DAEMON                         │
-│                    Your Persistent Brain                     │
-│                                                              │
-│   ┌─────────┐   ┌─────────┐   ┌─────────┐   ┌─────────┐    │
-│   │ VS Code │   │ Cursor  │   │ Gemini  │   │ Claude  │    │
-│   └────┬────┘   └────┬────┘   └────┬────┘   └────┬────┘    │
-│        │             │             │             │          │
-│        └─────────────┴──────┬──────┴─────────────┘          │
-│                             │                               │
-│                   ┌─────────▼─────────┐                     │
-│                   │   🧠 CELL DAEMON  │                     │
-│                   │    localhost:9876 │                     │
-│                   └─────────┬─────────┘                     │
-│                             │                               │
-│       ┌─────────────────────┼───────────────────────┐       │
-│       │                     │                       │       │
-│   ┌───▼───┐             ┌───▼───┐             ┌───▼───┐   │
-│   │ 👤 You│             │ 👥Team│             │ 🌐 All│   │
-│   │Style  │    ───►     │Shared │    ───►     │ Best  │   │
-│   │Blind  │             │Pattern│             │Practi-│   │
-│   │Spots  │             │  Bus  │             │ ces   │   │
-│   │ DNA   │             │Factor │             │Trends │   │
-│   └───────┘             └───────┘             └───────┘   │
-│                                                              │
-│        Personal Layer         Team Layer     Community Layer│
-│                                                              │
-│              🎯 One profile. Every AI tool. Zero config.    │
-└──────────────────────────────────────────────────────────────┘
-```
-
-</div>
-
-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 coding taste. Then it injects that taste back into every AI you use.
-
-**It's not another AI tool. It's the cognitive layer that makes every AI tool actually understand you.**
-
----
-
-<div align="center">
-
-## ⚡ One Command. Everything.
-
-</div>
-
-<div align="center">
-
-```bash
-npm i -g fivocell       # 📦 Install
-cell start              # 🚀 Start daemon + watcher + MCP server
-cell connect            # 🔌 Auto-configure ALL your AI tools
-```
-
-</div>
-
-<div align="center">
-
-```
-╔════════════════════════════════════════════════════════════╗
-║                                                            ║
-║  cell start brings up:                                    ║
-║                                                            ║
-║  ⚙️  Daemon (port 9876)    — 125+ API endpoints            ║
-║  👁️  File Watcher           — Auto-learns from every edit   ║
-║  🔌 MCP Server (port 9877) — 25 tools, 8 resources         ║
-║                                                            ║
-║  One command. Thirty seconds. Done.                        ║
-║                                                            ║
-╚════════════════════════════════════════════════════════════╝
-```
-
-</div>
-
-<div align="center">
-
-`cell connect` — Auto-creates config files for every AI tool detected
-
-</div>
-
-<div align="center">
-
-| 🛠️ Tool | 📁 Config Created | 🔗 Method |
-|:-------:|:-----------------:|:---------:|
-| 🖱️ **Cursor** | `.cursor/mcp.json` | Auto-detected |
-| 🤖 **Claude Code** | `.mcp.json` | Project-level |
-| 🌌 **Gemini CLI** | `~/.gemini/settings.json` | Global config |
-| ⚡ **Codex CLI** | `~/.codex/config.json` | Global config |
-
-💡 **Zero manual config. Works on Windows, Mac, and Linux identically.**
-
-</div>
-
----
-
-<div align="center">
-
-## 🧬 The Three-Layer Brain
-
-</div>
-
-<div align="center">
-
-```
-╔═══════════════════════════════════════════════════════════════════╗
-║                  🧠 CELL INTELLIGENCE LAYERS                      ║
-╠═══════════════════╦═══════════════════╦═══════════════════════════╣
-║                   ║                   ║                           ║
-║   👤 PERSONAL     ║   👥 TEAM         ║   🌐 COMMUNITY            ║
-║   ─────────      ║   ─────           ║   ─────────               ║
-║                   ║                   ║                           ║
-║  "Tum kaise      ║  "Team kaisi      ║ "Duniya ke best          ║
-║   code karte     ║   hai —           ║   developers kya         ║
-║   ho — exactly"  ║   collectively"   ║   karte hain —           ║
-║                  ║                   ║   evidence ke saath"     ║
-║                   ║                   ║                           ║
-║  🔐 PRIVATE      ║  🔒 ANONYMIZED    ║  📊 AGGREGATED          ║
-║  Sirf tumhara    ║  SHA-256 hashed   ║  No code. No names.     ║
-║                  ║                   ║                           ║
-╚═══════════════════╩═══════════════════╩═══════════════════════════╝
-```
-
-</div>
-
-<div align="center">
-
-### 👤 PERSONAL LAYER
-
-*"Cell knows you better than you know yourself"*
-
-</div>
-
-| 🧩 Engine | 🔍 What It Learns |
-|:----------|:------------------|
-| 📝 **Syntax** | Arrow vs named? Async/await? Semicolons? Quotes? Destructuring? |
-| 🏷️ **Naming** | camelCase? Boolean prefixes? Abbreviations? Generic name avoidance? |
-| 📐 **Structure** | File size? Function length? Nesting depth? Early returns? Guard clauses? |
-| 🏗️ **Architecture** | Frontend/backend patterns? Folder style? Config placement? |
-| 👁️ **Blind Spots** | **31 rules** — Error handling missed? Tests skipped? Security gaps? N+1 queries? |
-| ⚡ **Productivity** | Speed patterns? Decision history? Revert frequency? Over/under engineering? |
-| 🧠 **Knowledge Graph** | Tech proficiency? Project DNA? Session context? Context chain? |
-| 🔬 **Proof Engine** | Evidence for every claim — memory, prediction, impact, DNA, identity |
-
-<div align="center">
-
-> 💡 *"Tumhara #1 issue: async error handling 73% cases mein missing hai. Ye tumhara sabse bada bug source hai last 3 months mein."*
-
-</div>
-
-<div align="center">
-
-### 👥 TEAM LAYER
-
-*"Collective intelligence no wiki can capture"*
-
-</div>
-
-| 🧩 Feature | 🔍 What It Provides |
-|:----------|:-------------------|
-| 📚 **Shared Patterns** | Team-approved patterns + rationale |
-| 🗺️ **Knowledge Map** | Kaun kya jaanta hai — expertise distribution |
-| 🚌 **Bus Factor** | "Is module ko sirf Rahul jaanta hai — risk alert!" |
-| 🏥 **Team DNA** | Quality bar, risk profile, testing culture, refactoring appetite |
-| 🔄 **Workflows** | PR bottlenecks, deploy patterns, common failures |
-| 👁️ **Collective Blind Spots** | Patterns team consistently misses across sprints |
-
-<div align="center">
-
-> 🔒 **Privacy guarantee:** Team filenames use SHA-256 hashes, not usernames. File system browsers can't identify individual developers.
-
-</div>
-
-<div align="center">
-
-### 🌐 COMMUNITY LAYER
-
-*"Evidence, not opinions"*
-
-</div>
-
-| 🧩 Feature | 🔍 What It Aggregates |
-|:----------|:---------------------|
-| 📈 **Pattern Success** | "Next.js + Prisma + Zod — 89% success across 48K projects" |
-| 💀 **Failure Library** | Most common bugs, security vulnerabilities, performance bottlenecks |
-| 🔮 **Tech Evolution** | Adoption curves, migration patterns, abandonment signals |
-| 📊 **Benchmarks** | Feature delivery by team size, bug rate by testing culture |
-
-<div align="center">
-
-> 🛡️ **46 fields blocked.** Only abstract, anonymized statistics. Zero code. Zero identities.
-
-</div>
-
----
-
-<div align="center">
-
-## 🏆 Why Developers Choose Cell
-
-</div>
-
-<div align="center">
-
-| 🎯 Feature | 🧠 Cell | 🤖 Copilot | 🖱️ Cursor Rules | ⚡ Codex | 🌊 Windsurf |
-|:----------|:-------:|:----------:|:---------------:|:--------:|:-----------:|
-| **Works across tools** | ✅ All | ❌ GitHub only | ❌ Cursor only | ❌ OpenAI only | ❌ Windsurf only |
-| **Learns from behavior** | ✅ Edits, rejects | ❌ Prompt-only | ⚠️ Manual rules | ❌ Prompt-only | ⚠️ Basic |
-| **👁️ Blind spot detection** | ✅ 31 rules | ❌ | ❌ | ❌ | ❌ |
-| **👥 Team intelligence** | ✅ Bus factor, silos | ❌ | ❌ | ❌ | ❌ |
-| **🌐 Community data** | ✅ Evidence-backed | ❌ | ❌ | ❌ | ❌ |
-| **🏠 Local-first** | ✅ Zero cloud deps | ❌ Cloud required | ✅ Local only | ❌ Cloud required | ⚠️ Hybrid |
-| **🔓 Open source** | ✅ Apache 2.0 | ❌ Proprietary | ❌ Proprietary | ❌ Proprietary | ❌ Proprietary |
-| **🛡️ Privacy** | ✅ 46 fields blocked | ⚠️ Code to cloud | ✅ Local | ⚠️ Code to cloud | ⚠️ Code to cloud |
-| **🔌 MCP support** | ✅ 25 tools | ❌ | ⚠️ Limited | ⚠️ Limited | ❌ |
-| **💰 Free forever** | ✅ Yes | ❌ $10+/mo | ✅ Free tier | ❌ Pay-per-use | ❌ $15+/mo |
-
-</div>
-
-<div align="center">
-
-> 🎯 **Bottom line:** Every other tool is locked to one editor, sends code to the cloud, or costs money. Cell works everywhere, keeps everything local, and is permanently free.
-
-</div>
-
----
-
-<div align="center">
-
-## 🔌 MCP Server — 25 Tools, 8 Resources
-
-</div>
-
-<div align="center">
-
-```
-┌──────────────────────────────────────────────────────────────┐
-│                    🔌 CELL MCP SERVER                         │
-│                    localhost:9877/mcp                         │
-│                                                              │
-│   ┌─────────────────────┐    ┌───────────────────────┐      │
-│   │  👤 Personal (6)     │    │  🌐 Community (6)     │      │
-│   │                     │    │                       │      │
-│   │ 🎯 get_taste_context │    │ 📊 community_stats   │      │
-│   │ 📤 send_signal      │    │ 🏆 community_rankings │      │
-│   │ 📋 get_profile      │    │ 📈 community_trends   │      │
-│   │ 🔮 predict_next     │    │ 💡 community_insights │      │
-│   │ 🏗️ check_build      │    │ 📖 community_playbooks │      │
-│   │ 🎯 get_recommend... │    │ ⭐ community_reputation │      │
-│   └─────────────────────┘    └───────────────────────┘      │
-│                                                              │
-│   ┌─────────────────────┐    ┌───────────────────────┐      │
-│   │  🏢 Org Intel (6)    │    │  🔄 Cross-Layer (5)    │      │
-│   │                     │    │                       │      │
-│   │ 📊 org_benchmarks   │    │ 🧮 intelligence_score │      │
-│   │ 🔍 org_silos        │    │ ⚠️ analyze_risks      │      │
-│   │ 🚌 org_bus_factor   │    │ 🎯 find_opportunities │      │
-│   │ ⚠️ org_risks        │    │ 📋 generate_decisions │      │
-│   │ 💡 org_insights     │    │ 📄 intelligence_report │      │
-│   │ 📖 org_playbooks    │    │                       │      │
-│   └─────────────────────┘    └───────────────────────┘      │
-│                                                              │
-│         📦 Resources: 8 URIs — taste, community, team       │
-└──────────────────────────────────────────────────────────────┘
-```
-
-</div>
-
----
-
-<div align="center">
-
-## 🛡️ Security & Privacy — The Deep Dive
-
-</div>
-
-<div align="center">
-
-```
-╔══════════════════════════════════════════════════════════╗
-║                                                          ║
-║   🔒 Your code is yours. Period.                         ║
-║                                                          ║
-║   No account. No cloud dependency. No telemetry.         ║
-║   No analytics. No tracking. No phone-home.              ║
-║                                                          ║
-╚══════════════════════════════════════════════════════════╝
-```
-
-</div>
-
-<div align="center">
-
-### 🚫 46 Fields BLOCKED From Leaving Your Machine
-
-</div>
-
-<div align="center">
-
-```
-❌ source_code       ❌ file_path        ❌ file_content     ❌ file_name
-❌ prompt            ❌ response         ❌ ai_response      ❌ repo_name
-❌ company_name      ❌ project_name     ❌ customer_name    ❌ username
-❌ secret            ❌ api_key          ❌ password         ❌ token
-❌ auth_token        ❌ private_key      ❌ pii              ❌ email
-❌ phone             ❌ address          ❌ ssn              ❌ environment_vars
-❌ stack_trace       ❌ variable_name    ❌ function_name    ❌ api_name
-❌ endpoint_name     ❌ class_name       ❌ interface_name   ❌ type_name
-❌ business_logic    ❌ domain_terms     ❌ comment_text     ❌ error_message
-❌ log_message       ❌ db_schema        ❌ display_name     ❌ handle
-```
-
-</div>
-
-<div align="center">
-
-### 🔐 Team Layer — Anonymized by Default
-
-</div>
-
-<div align="center">
-
-```
-╔════════════════════════════════════════════════════════════╗
-║                                                            ║
-║   BEFORE:  team/alice.json     👀 Aah, Alice ka data!     ║
-║   AFTER:   team/a7f3b9c1.json  🤷 Kaun hai ye? Koi nahi.  ║
-║                                                            ║
-╚════════════════════════════════════════════════════════════╝
-```
-
-</div>
-
-<div align="center">
-
-> 🔑 Team member filenames use **SHA-256 hashing** with a fixed salt. Same user → same hash (deterministic). But impossible to reverse into a username.
-
-</div>
-
-<div align="center">
-
-### 📊 Community Layer — Only Abstract, Aggregated Stats
-
-</div>
-
-<div align="center">
-
-```
-╔════════════════════════════════════════════════════════════╗
-║   ✅ ALLOWED:                                              ║
-║                                                            ║
-║   "TypeScript + tests developers produce 37% fewer bugs"  ║
-║   "68% of developers miss async error handling"           ║
-║   "Server Components adoption: 34% → 71% in one year"    ║
-║                                                            ║
-║   ❌ NEVER:                                                ║
-║                                                            ║
-║   "Vinayak's payment-service has an auth bug on line 47"  ║
-║   "acme-corp/backend uses this exact folder structure"     ║
-║                                                            ║
-╚════════════════════════════════════════════════════════════╝
-```
-
-</div>
-
-<div align="center">
-
-### 🎚️ Three Privacy Modes
-
-</div>
-
-<div align="center">
-
-| 🔒 Mode | 📤 What's Shared |
-|:-------:|:-----------------|
-| 🏠 `private` | **Nothing.** Fully offline. |
-| 🌐 `community` | Anonymized pattern stats only (default) |
-| 🏢 `organization` | Within your company's org boundary |
-
-</div>
-
-```bash
-cell privacy        # Check current mode
-cell cloud off      # 🔒 Full privacy
-cell cloud on       # 🌐 Community (default)
-```
-
-<div align="center">
-
-> 💨 **Clean uninstall:** `npm uninstall -g fivocell` + `rm -rf ~/.fivo/cell/`. Gone. No traces. No leftovers.
-
-</div>
-
----
-
-<div align="center">
-
-## 🏗️ Architecture
-
-</div>
-
-<div align="center">
-
-```
-╔═══════════════════════════════════════════════════════════════════╗
-║                      🏗️ CELL ARCHITECTURE                         ║
-╠═══════════════════════════════════════════════════════════════════╣
-║                                                                   ║
-║   📟 CLI                                  🔌 MCP                  ║
-║   42 commands + shortcuts  ◄────►  25 tools + 8 URIs              ║
-║        │                                   │                      ║
-║        └─────────────────┬─────────────────┘                      ║
-║                          │                                        ║
-║               ┌──────────▼──────────┐                             ║
-║               │   ⚙️  DAEMON        │                             ║
-║               │   localhost:9876    │                             ║
-║               │   125+ endpoints    │                             ║
-║               └──────────┬──────────┘                             ║
-║                          │                                        ║
-║        ┌─────────────────┼─────────────────┐                      ║
-║        │                 │                 │                      ║
-║    ┌───▼───┐         ┌───▼───┐         ┌───▼───┐                ║
-║    │ 👤 You │         │ 👥 We │         │ 🌐 All │                ║
-║    │ 11 eng │ ───►    │ 3 eng │ ───►    │ 4 eng │                ║
-║    └───────┘         └───────┘         └───────┘                ║
-║                                                                   ║
-║   ────────────────────────────────────────────────────────       ║
-║   💾 Storage: ~/.fivo/cell/  (all JSON, no database needed)      ║
-╚═══════════════════════════════════════════════════════════════════╝
-```
-
-</div>
-
----
-
-<div align="center">
-
-## 🤝 Contributing
-
-</div>
-
-<div align="center">
-
-```
-╔══════════════════════════════════════════════════════╗
-║   We ❤️ contributors. Here's how to jump in.          ║
-╚══════════════════════════════════════════════════════╝
-```
-
-</div>
-
-<div align="center">
-
-### 🚀 First Time Setup
-
-</div>
-
-```bash
-git clone https://github.com/thevinsoni/cell.git
-cd cell
-npm install
-npm run build          # TypeScript → dist/
-npm test               # Verify all 772 assertions pass
-```
-
-<div align="center">
-
-### 📁 Project Map
-
-</div>
-
-```
-src/
-├── 📟 cli.ts                    # CLI (42 commands + shortcuts)
-├── 🔌 mcp-server.ts             # MCP JSON-RPC server (25 tools)
-├── 🧠 core/                     # All 19 intelligence engines
-│   ├── syntax-engine.ts         # 13 syntax analyzers
-│   ├── naming-engine.ts         # Variable/function/boolean naming
-│   ├── structure-engine.ts      # File size, nesting, guards
-│   ├── architecture-engine.ts   # Frontend/backend patterns
-│   ├── 👁️ blind-spot-engine.ts  # 31 blind spot rules
-│   ├── ⚡ productivity-engine.ts # Speed, decisions, reverts
-│   ├── 🧬 knowledge-graph-engine.ts # Tech map, session context
-│   ├── 📦 cell-store.ts         # .cell/ directory manager
-│   ├── 🔬 proof-engine.ts       # Evidence-based claims
-│   ├── 👥 team-engine.ts        # Team patterns + knowledge map
-│   ├── 👥 team-advanced-engine.ts # Sprint tracking, blind spots
-│   ├── 👥 team-composer.ts      # Weighted taste aggregation
-│   ├── 🌐 community-engine.ts   # Pattern success + benchmarks
-│   ├── 🌐 community-advanced.ts # Stack decisions
-│   ├── 🌐 community-prior.ts    # Synthetic → live transition
-│   ├── 🌐 community-live.ts     # Real signal ingestion
-│   ├── 🛡️ privacy-manager.ts    # 46 forbidden fields
-│   └── 🧪 __tests__/            # 772 hostile assertions
-├── ⚙️ daemon/                   # Daemon server
-│   ├── server.ts                # 125+ route Express server
-│   ├── lifecycle.ts             # Start/stop/restart
-│   └── websocket.ts             # Real-time streaming
-
-📦 extensions/
-├── 🖥️ vscode/                   # VSCode extension (.vsix)
-├── 🖥️ jetbrains/                # JetBrains plugin config
-└── ⌨️ shell/                    # Shell + Copilot sync scripts
-```
-
-<div align="center">
-
-### 🎯 What to Build
-
-</div>
-
-| 🏷️ Type | 💡 Examples |
-|:--------|:------------|
-| 👁️ **New blind spot rule** | Add `detectMissing()` to `blind-spot-engine.ts` |
-| 🧠 **New engine** | Create `src/core/your-engine.ts` with `CellStore` |
-| 📟 **CLI command** | Add to `cli.ts` following existing patterns |
-| 🔌 **MCP tool** | Add to `mcp-server.ts` TOOLS + `handleToolCall()` |
-| 🧪 **Tests** | Add hostile assertions proving edge cases |
-| 📖 **Docs** | Improve README, FOUNDATION.md, MCP-SETUP.md |
-
-<div align="center">
-
-### 📋 Guidelines
-
-</div>
-
-1. 🚫 **Zero AI/ML dependencies.** Evidence-based math only.
-2. 🏠 **Local-first.** Every feature must work fully offline.
-3. 🛡️ **Privacy-first.** Check `privacy-manager.ts` before sharing data.
-4. 💾 **Memory-only file content.** Abstract patterns only — never raw code.
-5. 🌍 **Cross-platform.** Node.js only. Works on Windows, Mac, Linux.
-6. 🧪 **Tests required.** Every engine needs hostile assertions.
-
-<div align="center">
-
-### 🔄 PR Process
-
-</div>
-
-```
-1️⃣  Fork → Branch → Implement → Add tests
-2️⃣  npm test          → 772 assertions must pass
-3️⃣  npx tsc --noEmit  → Zero TypeScript errors
-4️⃣  Open PR → main    → Describe what + why
-5️⃣  ✅ All checks green → Merged! 🎉
-```
-
----
-
-<div align="center">
-
-## 🧪 Tests
-
-</div>
-
-```bash
-npm test              # All 772 assertions
-
-# Specific test:
-npx vitest run src/core/__tests__/team-composer.test.ts
-```
-
-<div align="center">
-
-```
-✅ 772/772 hostile assertions passing
-✅ Zero TypeScript errors
-✅ Cross-platform verified
-```
-
-</div>
-
----
-
-<div align="center">
-
-## ⭐ Why Trust Cell
-
-</div>
-
-<div align="center">
-
-```
-╔════════════════════════════════════════════════════════════╗
-║                                                            ║
-║  🔓 Apache 2.0     — Every line is public. Audit it.      ║
-║  🏠 Local-First    — Zero cloud dependency.               ║
-║  💰 Free Forever   — No pricing page. No billing code.    ║
-║  🛡️ 46 Blocked     — Code literally cannot leave.         ║
-║  📊 Zero Telemetry — No usage tracking. No analytics.     ║
-║  🧪 772 Assertions — Edge cases proven to work.           ║
-║  💨 Clean Uninstall — One command. No traces.             ║
-║                                                            ║
-╚════════════════════════════════════════════════════════════╝
-```
-
-</div>
-
----
-
-<div align="center">
-
-## 🔗 Links
-
-</div>
-
-<div align="center">
-
-| 🔗 | Resource |
-|:---:|:---------|
-| 🌐 | [cell.fivo.live](https://cell.fivo.live) |
-| 📦 | `npm i -g fivocell` |
-| 💻 | [github.com/thevinsoni/cell](https://github.com/thevinsoni/cell) |
-| 📖 | [MCP Setup Guide](docs/MCP-SETUP.md) |
-
-</div>
-
----
-
-<div align="center">
-
-```
-╔══════════════════════════════════════════════════════════╗
-║                                                          ║
-║   🧬 Your taste. Every tool. Forever free.               ║
-║                                                          ║
-║   Cell is the last time you explain yourself             ║
-║   to a machine.                                          ║
-║                                                          ║
-╚══════════════════════════════════════════════════════════╝
-```
-
-**Made with ❤️ by developers, for developers. [Contribute →](#-contributing)**
-
-</div>
+# 🧠 FIVO Cell v3.0
+
+**Personal Developer Intelligence Layer. You write code. Cell learns.**
+
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue)](LICENSE)
+[![Version](https://img.shields.io/badge/Version-3.0.0-purple)](https://www.npmjs.com/package/fivocell)
+[![Platform](https://img.shields.io/badge/Mac%20%7C%20Windows%20%7C%20Linux-supported-lightgrey)]()
+
+---
+
+## What Cell Does
+
+```
+$ cell scan
+$ cell status
+
+🔮 Predictions:
+  ⚠ "15 async functions missing try/catch — 2x repeated"
+
+🧠 Git Intelligence:
+  Best hours: 10:00-11:00  |  Most productive: Monday
+  Mastered: TypeScript  |  Learning: JavaScript
+
+📂 Personal:
+  ! 15 async functions missing try/catch
+  ! 15 empty catch blocks — errors silently swallowed
+  ! 127 console.log statements — use structured logger
+  ! 34 'any' type usages — use specific types
+
+👥 Team: Git-based sharing. No servers. No ports.
+🌐 Community: Anonymous patterns + benchmarks.
+```
+
+## Install
+
+```bash
+npm i -g fivocell
+cell start
+cell scan
+cell status
+```
+
+## 7 Commands
+
+| Command | Does |
+|---------|------|
+| `cell start` | Start daemon + MCP (port 9876) |
+| `cell stop` | Stop daemon cleanly |
+| `cell scan` | Deep scan codebase — AST + Git intelligence |
+| `cell status` | Full dashboard: personal, predictions, team, community |
+| `cell team` | Git-based team sharing & knowledge map |
+| `cell community` | Anonymous patterns, benchmarks, trends |
+| `cell help` | Show commands |
+
+## Cell Knows
+
+- **Code Style**: quotes, semicolons, naming, indentation, function style, async patterns
+- **Blind Spots**: exact counts — "15 async without try/catch", "15 empty catch blocks"
+- **Git Intelligence**: best work hours, most productive day, skill levels, bug history
+- **Predictions**: repeat mistakes, decision regret, complexity traps, energy warnings
+- **Team**: knowledge map, bus factor, shared patterns via git
+- **Community**: anonymous pattern sharing, aggregate benchmarks
+- **$> cell status** shows everything
+
+## MCP Server
+
+Cell runs an MCP server on `localhost:9876/mcp` with 15 tools:
+
+```
+cell_get_dev_profile    cell_get_code_patterns    cell_deep_scan
+cell_scan_report        cell_send_signal           cell_get_context
+cell_scan_full_pc       cell_behavior_summary      cell_log_error
+cell_log_fix            cell_log_decision          cell_log_context
+cell_log_stuck          cell_session_bridge        cell_predict
+```
+
+Connect from Cursor, Claude Code, Windsurf or any MCP-compatible tool.
+
+## Architecture
+
+```
+.cell/
+├── personal/    — profile, style, errors, decisions
+├── team/        — members, shared patterns, blind spots, knowledge map
+├── community/   — aggregate patterns, benchmarks, shares
+└── cell.db      — SQLite database (all persistent data)
+
+.cell/team/ in git repo — push/pull for team sharing
+```
+
+## Privacy
+
+- **100% local** — code never leaves your machine
+- **Apache 2.0** — free forever
+- Community sharing sends only **abstract pattern types** (zero code, zero filenames)
+- Maximum 300 bytes per community payload
+
+## License
+
+Apache 2.0 — Free forever. No restrictions for individual use.
+
+---
+
+**Cell watches your coding. Learns your habits. Finds your blind spots. Remembers what works.**