fivocell 8.11.4 → 8.12.1

package/README.md

@@ -1,194 +1,568 @@
-# FivoCell
-
-> **Your AI forgets. Cell doesn't.**
-
-[![License](https://img.shields.io/badge/License-Apache%202.0-blue)](LICENSE)
-[![Platform](https://img.shields.io/badge/Mac%20%7C%20Windows%20%7C%20Linux-supported-lightgrey)]()
-[![Node](https://img.shields.io/badge/Node-%3E%3D18-green)]()
-[![npm](https://img.shields.io/npm/v/fivocell)](https://www.npmjs.com/package/fivocell)
-[![Tests](https://img.shields.io/badge/Tests-817%2F817-passing-brightgreen)]()
-
----
-
-## The Problem
-
-Every AI coding session starts from zero.
-
-You explain your stack. Your style. Your last decision. Your project goals.  
-Switch from Cursor to Codex? Start over. New chat? Start over. New day? Start over.
-
-**AI tools write code. But they forget everything between sessions.**
-
----
-
-## The Solution
-
-Cell creates a permanent intelligence layer between you and every AI tool.
-
-```
-                ┌──────────┐
-Cursor ────────→│          │
-Claude Code ───→│   CELL   │────→ SQLite (100% local)
-Codex ─────────→│          │
-Antigravity ───→│  Memory  │────→ Never forgets. Never resets.
-Windsurf ──────→│          │
-Any MCP tool ──→└──────────┘
-```
-
-One daemon. One database. One memory. Works across every AI tool.
-
----
-
-## 30-Second Start
-
-```bash
-npm i -g fivocell --loglevel=error
-cell setup
-cell start
-cell mcp-config
-```
-
-Type `@cell` in Cursor, Codex, Antigravity, or any MCP tool. AI gets full project memory.
-
----
-
-## What Cell Remembers
-
-| Your AI Tool | Cell Adds |
-|-------------|-----------|
-| Writes code | **Remembers your project** — stack, files, architecture |
-| Generates functions | **Knows your style** — quotes, naming, patterns (auto-detected) |
-| Answers questions | **Recalls your decisions** — why you chose PostgreSQL, not Mongo |
-| Opens new chat | **Restores your session** — what you were working on, where you left off |
-| Switches between tools | **Same memory everywhere** — Cursor → Codex → Claude, no loss |
-| Responds generically | **Adapts to your vibe** — your language, your tone, your workflow |
-
----
-
-## Core Features
-
-### 🎯 @cell Context Injection
-Type `@cell` in any AI tool. Cell injects your project profile, coding style, blind spots, last session, and predictions. AI never starts from zero again.
-
-### 🧠 Permanent Memory
-Decisions, errors, fixes, patterns — everything stored in local SQLite. Searchable. Replayable. Survives sessions, tools, and time.
-
-### 🔍 Blind Spot Scanner
-Automatically detects 15+ code issues: missing null checks, swallowed errors, `any` usage, N+1 queries, deep nesting. Prioritized. Actionable.
-
-### 🎭 Vibe Engine (NEW in v7)
-Cell learns how you work — your language, your tone, your preferences. Hinglish or English? Bullets or paragraphs? Minimal changes or thorough rewrites? AI adapts automatically.
-
-### 🔗 Cross-Tool Memory
-Same daemon, same database, same memory. Works with Cursor, Codex, Antigravity, Claude Code, Windsurf, OpenCode, and any MCP client.
-
-### 🌐 Local-First & Private
-Everything runs on your machine. No cloud. No telemetry. No tracking. AES-256-GCM encryption for sensitive data. Apache 2.0 — free forever.
-
-### 🩺 Health System
-`cell doctor` runs 12 checks across all subsystems. `cell verify` ensures data integrity. Critical issues flagged. Warnings explained. Always know your memory health.
-
----
-
-## Why Cell vs The Alternatives
-
-| Problem | AI Tools Alone | With Cell |
-|---------|---------------|-----------|
-| Project context per session | ❌ Re-explain every time | ✅ Auto-injected |
-| Memory across tools | ❌ Each tool isolated | ✅ One memory, all tools |
-| Code style consistency | ❌ Manual rules files | ✅ Auto-detected + injected |
-| Blind spots & risks | ❌ Hope AI catches them | ✅ Systematic scanner |
-| Session handoff | ❌ Lost on tool switch | ✅ Seamless bridge |
-| Developer personality | ❌ Generic responses | ✅ Vibe — adapts to you |
-| Privacy | ❌ Cloud-dependent | ✅ 100% local |
-
----
-
-## Quick Commands
-
-```
-cell setup         One-time setup
-cell start         Start daemon on localhost:9876
-cell scan          Analyze codebase + build intelligence
-cell context       View what @cell returns
-cell blindspots    Find code issues (--top for quick view)
-cell vibe          See your learned personality
-cell teach         Tell Cell about yourself
-cell doctor        12-point health check
-cell verify        Data integrity check
-cell memory search Search everything Cell remembers
-```
-
----
-
-## Supported Tools
-
-| Tool | Connection | Setup |
-|------|-----------|-------|
-| **Cursor** | MCP | `cell mcp-config` |
-| **Codex** | MCP | `cell mcp-config` |
-| **Antigravity** | MCP | `cell mcp-config` |
-| **Claude Code** | MCP | Manual URL |
-| **Windsurf** | MCP | Manual URL |
-| **OpenCode** | MCP | `cell mcp-config` |
-| **GitHub Copilot** | MCP | Manual URL |
-| **VS Code** | Extension | Install VSIX |
-| **Any MCP Client** | HTTP | `http://localhost:9876/mcp` |
-
----
-
-## What Users Are Saying
-
-> "Finally — I switch between Cursor and Codex all day. Cell keeps my context. I don't explain anything twice anymore."
-
-> "The blind spot scanner found 39 async functions without try/catch in my codebase. I fixed them in an hour. That alone saved me weeks of debugging."
-
-> "My AI now talks in Hinglish. Not because I asked — Cell figured it out from my sessions. The vibe engine is actually magic."
-
----
-
-## More Features
-
-Cell also includes: session replay, branch context memory, CI/CD integration, encrypted sync export/import, weekly reports, memory health scoring, developer velocity tracking, knowledge graph, project DNA fingerprinting, focus reports, PR review assistant, and 70+ more. See [full reference](docs/FIVO-CELL-COMPLETE-REFERENCE.md).
-
----
-
-## Architecture
-
-```
-~/.fivo/cell/cell.db    ← Single SQLite database (64 tables)
-  ├── memory_events     ← Every edit, decision, error, fix
-  ├── sessions          ← Work sessions across all tools
-  ├── style_profiles    ← Auto-detected coding patterns
-  ├── code_patterns     ← Learned patterns by category
-  └── ... (60+ more tables)
-
-.cell/                   ← Per-project readable files
-  ├── vibe/              ← Your learned personality (new in v7)
-  ├── memory/            ← Compressed archives + summaries
-  └── handoff/           ← Session-to-session context
-```
-
----
-
-## Stats
-
-```
-✅ Build:      0 TypeScript errors
-✅ Tests:      86 suites, 817/817 passing
-✅ MCP Tools:  112 registered
-✅ Lines:      59,000+ production TypeScript
-✅ Security:   0 vulnerabilities (audited 2026-06-13)
-```
-
----
-
-## Contribute
-
-[github.com/itsvinsoni/fivocell](https://github.com/itsvinsoni/fivocell)
-
-Apache 2.0. Open issues. PRs welcome.
-
----
-
-**AI tools come and go. Your project knowledge stays.**
+<div align="center">
+  <a href="https://github.com/itsvinsoni/cell">
+    <img src="assets/Fivo-cell-readme-banner.png" alt="FivoCell" width="800" />
+  </a>
+
+  <h1>FivoCell</h1>
+
+  <p><strong>Your AI forgets. Cell doesn't.</strong><br/>
+  A permanent, local memory layer for every AI coding tool you use.</p>
+
+  <p>
+    <a href="LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-blue" alt="License" /></a>
+    &nbsp;
+    <img src="https://img.shields.io/badge/Mac%20%7C%20Windows%20%7C%20Linux-supported-lightgrey" alt="Platform" />
+    &nbsp;
+    <img src="https://img.shields.io/badge/Node-%3E%3D18-green" alt="Node" />
+    &nbsp;
+    <a href="https://www.npmjs.com/package/fivocell"><img src="https://img.shields.io/npm/v/fivocell" alt="npm" /></a>
+    &nbsp;
+    <img src="https://img.shields.io/badge/npm%20audit-0%20vulnerabilities-success" alt="Security" />
+  </p>
+
+  <p>
+    <a href="#-quick-start">Quick Start</a> &nbsp;·&nbsp;
+    <a href="#-features">Features</a> &nbsp;·&nbsp;
+    <a href="#-comparison">Comparison</a> &nbsp;·&nbsp;
+    <a href="#-architecture">Architecture</a> &nbsp;·&nbsp;
+    <a href="#-supported-tools">Supported Tools</a> &nbsp;·&nbsp;
+    <a href="#-contribute">Contribute</a>
+  </p>
+</div>
+
+---
+
+## 🤔 What is FivoCell?
+
+Every time you talk to an AI coding tool, it starts from **zero**. You re-explain your project, your stack, your style, and what you decided yesterday. Switch from Cursor to Claude Code? Start over. New chat? Start over. New day? Start over.
+
+**FivoCell fixes this.** It is a small program that runs quietly on your computer and acts as a **permanent brain** for all your AI tools. Once running, any AI tool instantly knows:
+
+<div align="center">
+  <table>
+    <tr><td>🧠 <strong>Your project</strong></td><td>stack, framework, structure</td></tr>
+    <tr><td>✍️ <strong>Your style</strong></td><td>naming, functions, error handling</td></tr>
+    <tr><td>📜 <strong>Your decisions</strong></td><td>"we chose SQLite because..."</td></tr>
+    <tr><td>⚠️ <strong>Your blind spots</strong></td><td>risky spots scanned automatically</td></tr>
+    <tr><td>🔁 <strong>Your history</strong></td><td>what you did last session, what comes next</td></tr>
+  </table>
+</div>
+
+> **AI tools write code. FivoCell remembers everything else.**
+
+<div align="center"><strong>100% local. Private by default. Works offline. No sign-up needed.</strong></div>
+
+---
+
+## 💡 The Problem vs The Solution
+
+<div align="center">
+  <table>
+    <tr>
+      <th></th>
+      <th>😫 AI Tools Alone</th>
+      <th>✅ With FivoCell</th>
+    </tr>
+    <tr>
+      <td><strong>Project context</strong></td>
+      <td>Re-explain it every single session</td>
+      <td>Auto-injected when you type <code>@cell</code></td>
+    </tr>
+    <tr>
+      <td><strong>Memory across tools</strong></td>
+      <td>Each tool is isolated</td>
+      <td>One shared memory for all tools</td>
+    </tr>
+    <tr>
+      <td><strong>Code style</strong></td>
+      <td>You maintain manual rules files</td>
+      <td>Auto-detected and applied</td>
+    </tr>
+    <tr>
+      <td><strong>Risks and blind spots</strong></td>
+      <td>Hope the AI notices</td>
+      <td>all blind spots scanned for you</td>
+    </tr>
+    <tr>
+      <td><strong>Switching tools</strong></td>
+      <td>Context lost on every switch</td>
+      <td>Seamless handoff between tools</td>
+    </tr>
+    <tr>
+      <td><strong>Who you are</strong></td>
+      <td>Generic responses</td>
+      <td>Learns your personality (100 signals)</td>
+    </tr>
+    <tr>
+      <td><strong>Privacy</strong></td>
+      <td>Often cloud-dependent</td>
+      <td>Fully local, cloud is opt-in</td>
+    </tr>
+  </table>
+</div>
+
+```
+  Cursor ──────────┐
+  Claude Code ─────┤                 ┌─────────────────────┐
+  Codex ───────────┤                 │      FIVO CELL       │
+  Antigravity ─────┼────────────────>│      Memory Layer    │
+  Windsurf ────────┤                 │      Daemon :9876    │
+  OpenCode ────────┤                 │      67 MCP Tools    │
+  Any MCP tool ────┘                 └──────────┬──────────┘
+                                                │
+                             ┌──────────────────┴──────────────────┐
+                             │                                     │
+                             ▼                                     ▼
+                   ┌─────────────────┐                  ┌─────────────────┐
+                   │  SQLite (local) │                  │  @cell in IDE   │
+                   │  Never forgets  │                  │  Full context   │
+                   │  Never resets   │                  │  Instant reply  │
+                   └─────────────────┘                  └─────────────────┘
+```
+
+---
+
+## ⚡ Quick Start
+
+```bash
+# 1. Install (one time)
+npm i -g fivocell
+
+# 2. Go to your project
+cd your-project
+cell run        # setup + scan + start daemon, all at once
+```
+
+Open **any** AI tool (Cursor, Claude Code, Windsurf) and type:
+
+```
+@cell how should I add auth to this app?
+```
+
+The AI replies with **full context** — your stack, style, decisions, and blind spots — without you explaining anything. ✨
+
+```bash
+cell status     # check it's running
+cell context    # see exactly what the AI sees
+cell vibe       # see your developer personality
+```
+
+---
+
+## 🚀 Features
+
+### ⚙️ Core Commands
+
+<div align="center">
+  <table>
+    <tr><th>Command</th><th>What it does</th><th>Category</th></tr>
+    <tr><td><code>cell run</code></td><td>Setup + scan + start, everything in one command</td><td>Setup</td></tr>
+    <tr><td><code>cell scan</code></td><td>Analyze codebase: stack, style, patterns, blind spots</td><td>Analysis</td></tr>
+    <tr><td><code>cell status</code></td><td>Daemon + project + database health at a glance</td><td>Monitor</td></tr>
+    <tr><td><code>cell start</code> / <code>cell stop</code></td><td>Turn the background memory daemon on or off</td><td>Daemon</td></tr>
+    <tr><td><code>cell sync</code></td><td>Push and pull intelligence (optional, opt-in)</td><td>Cloud</td></tr>
+    <tr><td><code>cell vibe</code></td><td>Your developer personality profile</td><td>Personality</td></tr>
+    <tr><td><code>cell doctor</code></td><td>Comprehensive health check</td><td>Health</td></tr>
+    <tr><td><code>cell -i</code></td><td>Interactive REPL, a ChatGPT-style terminal</td><td>REPL</td></tr>
+  </table>
+</div>
+
+> CLI commands organized across multiple categories. Run `cell help --all` to see them all.
+
+### 🧠 Memory & Context
+
+<div align="center">
+  <table>
+    <tr><th>Feature</th><th>Details</th></tr>
+    <tr><td><strong>@cell Context</strong></td><td>Type <code>@cell</code> in any IDE. Project, blind spots, predictions and session get injected automatically</td></tr>
+    <tr><td><strong>Supreme Context</strong></td><td>3 engines (Bridge + Continuity + Predictor) for true cross-session memory</td></tr>
+    <tr><td><strong>Permanent Memory</strong></td><td>Events stored in local SQLite. Decisions, errors, fixes, patterns</td></tr>
+    <tr><td><strong>Session Memory</strong></td><td>Every session recorded: files touched, decisions made, approaches tried</td></tr>
+    <tr><td><strong>Cell Index</strong></td><td><code>.cell/INDEX.md</code> — fast context lookup with ~89% data reduction</td></tr>
+    <tr><td><strong>Memory Search</strong></td><td>Instant FTS5 full-text search across all your history</td></tr>
+    <tr><td><strong>Handoff</strong></td><td>AI-to-AI context transfer. Bridge capture keeps context across tools</td></tr>
+  </table>
+</div>
+
+#### Supreme Context — 3 Engines
+
+<div align="center">
+  <table>
+    <tr><th>Engine</th><th>What it does</th></tr>
+    <tr><td><strong>Bridge</strong></td><td>Captures session summary at end. Auto-injects at next start. 9 fields: summary, key decisions, open questions, failed approaches, working approaches, last thought, files in focus, vibe snapshot, predicted next steps. Sessions tracked over time.</td></tr>
+    <tr><td><strong>Continuity</strong></td><td>Cross-session thread. Auto-detects intent: bug fix, feature dev, refactor, test, docs, release. Never asks "what are we building?"</td></tr>
+    <tr><td><strong>Predictor</strong></td><td>Predicts files AI will need, errors that may recur, decisions needing revisit. Provides beachhead action.</td></tr>
+  </table>
+</div>
+
+### 🎭 Vibe — Developer Personality
+
+<div align="center">
+  <table>
+    <tr><th>Feature</th><th>Details</th></tr>
+    <tr><td><strong>Personality Signals</strong></td><td>Across multiple groups: language, tone, code style, workflow, decision making</td></tr>
+    <tr><td><strong>Identity Detection</strong></td><td>Auto-detects your developer archetype</td></tr>
+    <tr><td><strong>AI Guide</strong></td><td>Generates rules telling AI tools "how to behave" with you</td></tr>
+    <tr><td><strong>Live Enforcement</strong></td><td>Watcher flags rule violations automatically</td></tr>
+    <tr><td><strong>Cross-Signal Pairs</strong></td><td>Detects combined behaviors (e.g., direct and concise communication)</td></tr>
+    <tr><td><strong>Contradiction Resolution</strong></td><td>Ships fast for features, perfects for security — context-dependent</td></tr>
+  </table>
+</div>
+
+**The Signal Groups:** Language Preference · Response Structure · Communication Tone · Code Change Style · Workflow · Decision Making · Speed vs Quality · AI Trust · Project Behavior · Emotional Nuance · Prompt Thinking · Session Rhythm
+
+> **Example AI Guide:** Be direct — start with answer, then explain. Use Hinglish: Hindi for concepts, English for code. Keep changes under 50 lines. Start with audit before proposing. Never rewrite unless asked.
+
+### 🔍 Code Intelligence
+
+<div align="center">
+  <table>
+    <tr><th>Feature</th><th>Details</th></tr>
+    <tr><td><strong>Code Scanner</strong></td><td>Walks project files and analyzes all code structure and stack details</td></tr>
+    <tr><td><strong>Blind Spots</strong></td><td>Detects common issues: null safety, code quality, error handling, performance, and validation</td></tr>
+    <tr><td><strong>Stack Detection</strong></td><td>Language, framework, DB, ORM, test runner — all auto-detected</td></tr>
+    <tr><td><strong>Style Pull</strong></td><td>Detects project-specific naming styles, imports, and error-handling patterns</td></tr>
+    <tr><td><strong>Git Intelligence</strong></td><td>Git hooks auto-learn on every commit. Tracks patterns and repeat mistakes</td></tr>
+    <tr><td><strong>Trust Score</strong></td><td>Code quality scored with multi-category breakdown</td></tr>
+  </table>
+</div>
+
+### 📡 MCP — Multi-IDE Support
+
+<div align="center">
+  <table>
+    <tr><th>Feature</th><th>Details</th></tr>
+    <tr><td><strong>Multiple IDEs Auto-Configured</strong></td><td>Cursor, Windsurf, Antigravity, Codex/Copilot, OpenCode</td></tr>
+    <tr><td><strong>Rich MCP Tools</strong></td><td>Comprehensive set of tools covering sessions, context, memory, vibe, team collaboration, and cloud sync</td></tr>
+    <tr><td><strong>Honest Detection</strong></td><td>Only IDEs you actually have installed are configured</td></tr>
+    <tr><td><strong>Auto-Configure</strong></td><td><code>cell mcp-config</code> — one command registers all your IDEs</td></tr>
+  </table>
+</div>
+
+### 👁️ File Watcher
+
+<div align="center">
+  <table>
+    <tr><th>Feature</th><th>Details</th></tr>
+    <tr><td><strong>Live Events</strong></td><td>Captures file changes in real-time</td></tr>
+    <tr><td><strong>Vibe Update</strong></td><td>Watcher keeps your personality profile fresh</td></tr>
+    <tr><td><strong>TCP Bridge</strong></td><td>Port 9877, dedicated socket for editor events</td></tr>
+    <tr><td><strong>Auto-Learn</strong></td><td>Git hooks trigger auto-learning on every commit</td></tr>
+  </table>
+</div>
+
+### ☁️ Cloud Sync — Opt-In Only
+
+<div align="center">
+  <table>
+    <tr><th>Feature</th><th>Details</th></tr>
+    <tr><td><strong>Privacy-First</strong></td><td>Only anonymized patterns leave your machine. Never secrets, paths, or code</td></tr>
+    <tr><td><strong>Opt-In Scope</strong></td><td>Granular categories — you choose what syncs where</td></tr>
+    <tr><td><strong>Comprehensive Redaction</strong></td><td>API keys, AWS creds, private keys, tokens, emails, JWT — all <code>[REDACTED]</code></td></tr>
+    <tr><td><strong>JWT Auto-Refresh</strong></td><td>Token expiry check with 5-min grace period, auto-refresh</td></tr>
+    <tr><td><strong>Rate Limit Backoff</strong></td><td>429 gets exponential backoff (1s, 2s, 4s up to max 5 min)</td></tr>
+    <tr><td><strong>Device Registration</strong></td><td>UUID v4 device ID + JWT auth on first login</td></tr>
+    <tr><td><strong>SSRF Protection</strong></td><td>Only whitelisted URLs (<code>cell.fivo.live</code>)</td></tr>
+    <tr><td><strong>AES-256-GCM</strong></td><td>Encrypted sync, rate-limited, offline-ready</td></tr>
+  </table>
+</div>
+
+### 👥 Team & Community
+
+<div align="center">
+  <table>
+    <tr><th>Feature</th><th>Details</th></tr>
+    <tr><td><strong>Team Supreme</strong></td><td>Team DNA (shared conventions), Knowledge Map (who knows what), Health Score (bus factor, silo risk)</td></tr>
+    <tr><td><strong>Community Supreme</strong></td><td>Marketplace (browse/download patterns), Trends, Playbooks, Reputation (badges)</td></tr>
+    <tr><td><strong>Knowledge Graph</strong></td><td>Detects shared patterns across projects</td></tr>
+  </table>
+</div>
+
+### 🩺 Health & Security
+
+<div align="center">
+  <table>
+    <tr><th>Feature</th><th>Details</th></tr>
+    <tr><td><strong>12-Point Doctor</strong></td><td>git, node, DB, daemon, watch, MCP, FTS, scan — all checked</td></tr>
+    <tr><td><strong>Localhost-Only</strong></td><td>Daemon binds to <code>127.0.0.1</code> — zero LAN exposure</td></tr>
+    <tr><td><strong>Atomic Writes</strong></td><td>temp then rename — files never corrupt</td></tr>
+    <tr><td><strong>chmod 0600</strong></td><td>Database is owner-only on Unix</td></tr>
+    <tr><td><strong>No eval/spawnSync</strong></td><td>Zero code execution vectors</td></tr>
+    <tr><td><strong>Parameterized SQL</strong></td><td>Zero injection risk</td></tr>
+    <tr><td><strong>npm audit: 0</strong></td><td>Zero known vulnerabilities</td></tr>
+  </table>
+</div>
+
+---
+
+## 🆚 FivoCell vs The Alternatives
+
+<div align="center">
+  <table>
+    <tr>
+      <th>Capability</th>
+      <th><strong>FivoCell</strong></th>
+      <th>Pieces for Devs</th>
+      <th>Mem0</th>
+      <th>Cursor</th>
+      <th>.cursorrules</th>
+    </tr>
+    <tr>
+      <td>Works across <strong>multiple AI tools</strong></td>
+      <td align="center">✅ 5+ via MCP</td>
+      <td align="center">🟡 Partial</td>
+      <td align="center">🟡 SDK only</td>
+      <td align="center">❌ Cursor only</td>
+      <td align="center">❌ Per-tool</td>
+    </tr>
+    <tr>
+      <td><strong>Cross-session</strong> memory</td>
+      <td align="center">✅ Bridge + Continuity</td>
+      <td align="center">✅</td>
+      <td align="center">✅</td>
+      <td align="center">🟡 Limited</td>
+      <td align="center">❌</td>
+    </tr>
+    <tr>
+      <td><strong>100% local</strong> (works offline)</td>
+      <td align="center">✅</td>
+      <td align="center">🟡 Cloud-leaning</td>
+      <td align="center">❌ Cloud/API</td>
+      <td align="center">❌ Cloud</td>
+      <td align="center">✅ Static</td>
+    </tr>
+    <tr>
+      <td><strong>Codebase scanning</strong> &amp; blind spots</td>
+      <td align="center">✅ Full local scan</td>
+      <td align="center">❌</td>
+      <td align="center">❌</td>
+      <td align="center">🟡 Basic</td>
+      <td align="center">❌</td>
+    </tr>
+    <tr>
+      <td>Learns your <strong>personality / vibe</strong></td>
+      <td align="center">✅ 100 signals</td>
+      <td align="center">❌</td>
+      <td align="center">❌</td>
+      <td align="center">❌</td>
+      <td align="center">❌ Manual</td>
+    </tr>
+    <tr>
+      <td><strong>Auto-detects</strong> code style</td>
+      <td align="center">✅ 8 categories with %</td>
+      <td align="center">❌</td>
+      <td align="center">❌</td>
+      <td align="center">🟡</td>
+      <td align="center">❌</td>
+    </tr>
+    <tr>
+      <td><strong>Team &amp; community</strong> intelligence</td>
+      <td align="center">✅ Team DNA + Market</td>
+      <td align="center">🟡</td>
+      <td align="center">❌</td>
+      <td align="center">❌</td>
+      <td align="center">❌</td>
+    </tr>
+    <tr>
+      <td>Privacy: <strong>opt-in</strong> cloud + redaction</td>
+      <td align="center">✅ 15 redaction patterns</td>
+      <td align="center">🟡</td>
+      <td align="center">❌</td>
+      <td align="center">❌</td>
+      <td align="center">✅</td>
+    </tr>
+    <tr>
+      <td><strong>Open source</strong></td>
+      <td align="center">✅ Apache 2.0</td>
+      <td align="center">❌</td>
+      <td align="center">🟡</td>
+      <td align="center">❌</td>
+      <td align="center">✅</td>
+    </tr>
+    <tr>
+      <td>Setup effort</td>
+      <td align="center">✅ One command</td>
+      <td align="center">🟡 App install</td>
+      <td align="center">🟡 Code integration</td>
+      <td align="center">✅ Built-in</td>
+      <td align="center">🟡 Manual</td>
+    </tr>
+  </table>
+</div>
+
+---
+
+## 🏗️ Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     YOUR MACHINE  (100% local)                  │
+│                                                                 │
+│  Cursor ──┐                                                     │
+│  Windsurf ┤  MCP Protocol                                       │
+│  Claude   ├────────────────────────────────────────────────>    │
+│  Codex    ┤                    ┌───────────────────────────┐    │
+│  Antigrav ┘                    │      FIVO CELL DAEMON     │    │
+│                                │   http://localhost:9876   │    │
+│                                ├───────────────────────────┤    │
+│                                │ Prompt Builder | MCP Srvr │    │
+│                                │ Context Bridge | CLI Rtr  │    │
+│                                │ Session Tracker| Watcher  │    │
+│                                └──────────┬────────────────┘    │
+│                                           │                     │
+│                         ┌─────────────────┼─────────────────┐  │
+│                         ▼                 ▼                 ▼  │
+│                   ┌──────────┐    ┌──────────┐    ┌──────────┐ │
+│                   │  SQLite  │    │  .cell/  │    │   Vibe   │ │
+│                   │  18 MB   │    │  270 KB  │    │  Engine  │ │
+│                   │  70 tbls │    │ INDEX.md │    │ 100 rules│ │
+│                   └──────────┘    └──────────┘    └──────────┘ │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### 7 Walls Architecture
+
+<div align="center">
+  <table>
+    <tr><th align="center">Wall</th><th align="center">Name</th><th>Responsibility</th></tr>
+    <tr><td align="center">1</td><td align="center"><strong>Context</strong></td><td>Builds the prompt AI sees: bridge, continuity, predictor, sessions</td></tr>
+    <tr><td align="center">2</td><td align="center"><strong>Scanner</strong></td><td>Analyzes code: stack, style, blind spots, git intelligence</td></tr>
+    <tr><td align="center">3</td><td align="center"><strong>Knowledge</strong></td><td>Decisions, error prediction, project DNA, explainability</td></tr>
+    <tr><td align="center">4</td><td align="center"><strong>Collaboration</strong></td><td>Team DNA, knowledge map, health and bus-factor</td></tr>
+    <tr><td align="center">5</td><td align="center"><strong>Community</strong></td><td>Community patterns, marketplace, playbooks, cloud connector</td></tr>
+    <tr><td align="center">6</td><td align="center"><strong>Memory</strong></td><td>Core engine: SQLite, vibe, ranking, compression, encryption</td></tr>
+    <tr><td align="center">7</td><td align="center"><strong>Runtime</strong></td><td>Daemon (Express :9876), MCP server, CLI, watcher, autostart</td></tr>
+  </table>
+</div>
+
+### Supreme Context Engine Flow
+
+```
+  Session Start  ->  [Continuity]  loads active thread
+                 ->  [Bridge]      loads last session summary
+                 ->  [Predictor]   suggests next action
+                 ->  AI gets full context, no manual explaining
+
+  Session End    ->  [Bridge]      captures summary
+                 ->  [Continuity]  updates the thread
+                 ->  [Predictor]   updates predictions
+                 ->  Saved to .cell/ -- never lost
+```
+
+### Data Flow
+
+```
+  @cell typed  ->  MCP request to :9876
+               ->  Prompt builder reads:
+                   +-- SQLite (70 tables, 7,421 events)
+                   +-- .cell/INDEX.md (49 files, 2K tokens)
+                   +-- .cell/vibe/ (100 signals)
+                   +-- .cell/bridge/latest.json
+                   +-- .cell/continuity/
+                   +-- .cell/predictor.json
+               ->  Ranks by relevance
+               ->  Compresses to token budget
+               ->  Formats per-tool
+               ->  Returns ~1,289 chars
+```
+
+---
+
+## 🔌 Supported Tools
+
+<div align="center">
+  <table>
+    <tr><th>Tool</th><th>Connection</th><th>Setup</th></tr>
+    <tr><td><strong>Cursor</strong></td><td>MCP (auto)</td><td><code>cell mcp-config</code></td></tr>
+    <tr><td><strong>Codex / GitHub Copilot</strong></td><td>MCP (auto)</td><td><code>cell mcp-config</code></td></tr>
+    <tr><td><strong>Antigravity / Gemini</strong></td><td>MCP (auto)</td><td><code>cell mcp-config</code></td></tr>
+    <tr><td><strong>Windsurf</strong></td><td>MCP (auto)</td><td><code>cell mcp-config</code></td></tr>
+    <tr><td><strong>OpenCode</strong></td><td>MCP (auto)</td><td><code>cell mcp-config</code></td></tr>
+    <tr><td><strong>Claude Code</strong></td><td>MCP (manual)</td><td><code>http://127.0.0.1:9876/mcp</code></td></tr>
+    <tr><td><strong>Any MCP Client</strong></td><td>HTTP</td><td><code>http://127.0.0.1:9876/mcp</code></td></tr>
+  </table>
+</div>
+
+---
+
+## 🔒 Security & Data Privacy
+
+FivoCell is designed with a **privacy-first, local-by-default architecture** so that your sensitive intellectual property and credentials never leave your control.
+
+### What FivoCell Takes (Stored 100% Locally)
+* 💾 **Local SQLite Database**: Stores memory events, CLI history, session summaries, and custom-defined decisions on your local machine (`.cell/` folder).
+* ⚙️ **Developer Vibe Signals**: Learns your local programming conventions and styles to build custom instructions.
+* 🔍 **Code Diagnostics**: Local scanner checks for code vulnerabilities, structural risks, and coding patterns.
+
+### What FivoCell NEVER Accesses or Transmits
+* ❌ **Raw Source Code**: FivoCell processes all code diagnostics locally. It never sends your source files, logic, or proprietary code to any external server.
+* ❌ **API Keys & Credentials**: The `PrivacyRedactor` automatically intercepts and redacts API tokens, AWS keys, private credentials, database URLs, and password patterns (15 default filters) before any network call.
+* ❌ **Personal / System Identifiers**: Absolute paths, emails, private IPs, and internal hostnames are fully scrubbed.
+
+### Opt-In Cloud Synchronization (Granular Controls)
+Any cloud feature is completely **off by default** and requires explicit opt-in:
+* **Community Patterns**: Anonymized vibe and high-level style patterns can be shared to benchmark against community trends (no raw code, names, or paths).
+* **Team Sync**: Optional end-to-end encrypted sharing of project decisions and session handoffs to keep team members aligned.
+
+To verify your security state at any time, run:
+```bash
+cell doctor
+```
+
+---
+
+## 📚 Documentation
+
+<div align="center">
+  <table>
+    <tr><th>Doc</th><th>Link</th></tr>
+    <tr><td>Full A-to-Z Feature Reference</td><td><a href="docs/FIVO-CELL-A-TO-Z-DOC.md">docs/FIVO-CELL-A-TO-Z-DOC.md</a></td></tr>
+    <tr><td>Architecture Deep Dive</td><td><a href="docs/LOCAL_BRAIN_ARCHITECTURE.md">docs/LOCAL_BRAIN_ARCHITECTURE.md</a></td></tr>
+    <tr><td>Security Policy</td><td><a href="docs/SECURITY.md">docs/SECURITY.md</a></td></tr>
+    <tr><td>Privacy</td><td><a href="docs/PRIVACY.md">docs/PRIVACY.md</a></td></tr>
+    <tr><td>Telemetry</td><td><a href="docs/TELEMETRY.md">docs/TELEMETRY.md</a></td></tr>
+    <tr><td>Trust</td><td><a href="docs/TRUST.md">docs/TRUST.md</a></td></tr>
+    <tr><td>Changelog</td><td><a href="docs/CHANGELOG.md">docs/CHANGELOG.md</a></td></tr>
+    <tr><td>Contributing</td><td><a href="docs/CONTRIBUTING.md">docs/CONTRIBUTING.md</a></td></tr>
+    <tr><td>Deploy Guide</td><td><a href="docs/DEPLOY.md">docs/DEPLOY.md</a></td></tr>
+    <tr><td>Phased Roadmap</td><td><a href="docs/PHASED_ROADMAP.md">docs/PHASED_ROADMAP.md</a></td></tr>
+    <tr><td>Features Deep Dive</td><td><a href="docs/FEATURES_DEEP_DIVE.md">docs/FEATURES_DEEP_DIVE.md</a></td></tr>
+    <tr><td>Command Reference</td><td><a href="docs/COMMANDS.md">docs/COMMANDS.md</a></td></tr>
+  </table>
+</div>
+
+---
+
+## 🤝 Contribute
+
+FivoCell is **open source under Apache 2.0**. Contributions, issues, and PRs are all welcome.
+
+```bash
+git clone https://github.com/itsvinsoni/cell
+cd cell
+npm install
+npm test        # verify all tests pass
+```
+
+<div align="center">
+  🐛 Found a bug? <a href="https://github.com/itsvinsoni/cell/issues">Open an issue</a>
+  &nbsp;·&nbsp;
+  💡 Have an idea? <a href="https://github.com/itsvinsoni/cell/discussions">Start a discussion</a>
+  &nbsp;·&nbsp;
+  🔧 Want to build? Pick a <code>good first issue</code> and send a PR
+</div>
+
+---
+
+## 📄 License
+
+<div align="center">
+  <a href="LICENSE">Apache License 2.0</a> — free to use, modify, and distribute.
+</div>
+
+---
+
+<div align="center">
+  <strong>AI tools come and go. Your project knowledge stays.</strong><br/>
+  <sub>Built with ❤️ by <a href="https://github.com/itsvinsoni">@itsvinsoni</a> &nbsp;·&nbsp; part of the <a href="https://fivo.live">Fivo</a> ecosystem</sub>
+</div>