fivocell 8.12.23 → 8.12.24

package/README.md

@@ -22,8 +22,8 @@
 
   <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="#-what-happens-over-time">What Happens Over Time</a> &nbsp;·&nbsp;
+    <a href="#-features--benefits">Features</a> &nbsp;·&nbsp;
     <a href="#-architecture">Architecture</a> &nbsp;·&nbsp;
     <a href="#-supported-tools">Supported Tools</a> &nbsp;·&nbsp;
     <a href="#-contribute">Contribute</a>
@@ -36,18 +36,29 @@
 
 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:
+**FivoCell fixes this.** It runs quietly on your machine as a local daemon and acts as a **permanent brain** for all your AI tools. The moment it's installed, any AI tool 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 project</strong></td><td>stack, framework, structure, architecture</td></tr>
+    <tr><td>✍️ <strong>Your style</strong></td><td>naming, functions, error handling patterns</td></tr>
+    <tr><td>📜 <strong>Your decisions</strong></td><td>"we chose SQLite because...", "we rejected X"</td></tr>
+    <tr><td>⚠️ <strong>Your blind spots</strong></td><td>risky spots scanned automatically across your codebase</td></tr>
     <tr><td>🔁 <strong>Your history</strong></td><td>what you did last session, what comes next</td></tr>
   </table>
 </div>
 
+**Real output example — what Cell tells you on first scan:**
+
+```
+✅ Scanned your project
+⚠️  98 files have try/catch missing on async functions
+⚠️  43 files have console.log left behind
+⚠️  null safety issues detected in core modules
+🧠  Your vibe: "Bilingual communicator, strategic auditor, ships fast"
+🔮  Predicted next session: auth module needs error handling pass
+```
+
 > **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>
@@ -81,7 +92,7 @@ Every time you talk to an AI coding tool, it starts from **zero**. You re-explai
     <tr>
       <td><strong>Risks and blind spots</strong></td>
       <td>Hope the AI notices</td>
-      <td>all blind spots scanned for you</td>
+      <td>Scanned automatically, category-wise</td>
     </tr>
     <tr>
       <td><strong>Switching tools</strong></td>
@@ -90,8 +101,8 @@ Every time you talk to an AI coding tool, it starts from **zero**. You re-explai
     </tr>
     <tr>
       <td><strong>Who you are</strong></td>
-      <td>Generic responses</td>
-      <td>Learns your personality (100 signals)</td>
+      <td>Generic responses every time</td>
+      <td>Learns your personality across sessions</td>
     </tr>
     <tr>
       <td><strong>Privacy</strong></td>
@@ -107,7 +118,7 @@ Every time you talk to an AI coding tool, it starts from **zero**. You re-explai
   Codex ───────────┤                 │      FIVO CELL       │
   Antigravity ─────┼────────────────>│      Memory Layer    │
   Windsurf ────────┤                 │      Daemon :9876    │
-  OpenCode ────────┤                 │      67 MCP Tools    │
+  OpenCode ────────┤                 │      MCP Tools       │
   Any MCP tool ────┘                 └──────────┬──────────┘
                                                 │
                              ┌──────────────────┴──────────────────┐
@@ -125,15 +136,27 @@ Every time you talk to an AI coding tool, it starts from **zero**. You re-explai
 ## ⚡ Quick Start
 
 ```bash
-# 1. Install (one time)
-npm i -g fivocell
+# Step 1 — Install (one time)
+npm install -g fivocell
 
-# 2. Go to your project
+# Step 2 — Go to your project and run
 cd your-project
-cell run        # setup + scan + start daemon, all at once
+cell run
+```
+
+`cell run` is a single command that does everything:
+
+```
+[1/7] ✅ Setup complete — .cell/ folder created
+[2/7] 🔍 Scanning codebase — files, stack, style, blind spots
+[3/7] ⚠️  Blind spots found — null safety, error handling, console.log
+[4/7] 🧠 Vibe engine started — learning your patterns
+[5/7] 📄 AGENTS.md created — AI tools now know who you are
+[6/7] 🚀 Daemon started on :9876 — MCP tools ready
+[7/7] 👁️  Watcher started — file saves will be tracked
 ```
 
-Open **any** AI tool (Cursor, Claude Code, Windsurf) and type:
+Then open **any** AI tool (Cursor, Claude Code, Windsurf) and type:
 
 ```
 @cell how should I add auth to this app?
@@ -142,45 +165,100 @@ Open **any** AI tool (Cursor, Claude Code, Windsurf) and type:
 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 status     # check daemon + project health
 cell context    # see exactly what the AI sees
 cell vibe       # see your developer personality
 ```
 
 ---
 
-## 🚀 Features
+## 📅 What Happens Over Time
+
+### Day 1 — After `cell run`
+
+| Step | What Happens |
+|:----:|--------------|
+| 1 | `npm install -g fivocell` — installed globally |
+| 2 | `cell run` — setup + scan + daemon start in one command |
+| 3 | Code scan runs — files analyzed, blind spots found (null safety, error handling, console.log etc.) |
+| 4 | `.cell/` folder created — vibe, context, INDEX, bridge files |
+| 5 | `AGENTS.md` created at project root — tells every AI tool what `@cell` is |
+| 6 | Daemon starts on `:9876` — all MCP tools are ready |
+| 7 | File watcher starts — every save will be tracked from now on |
+
+**You'll see something like:**
+```
+⚠️  98 files: try/catch missing on async functions
+⚠️  43 files: console.log not removed
+   null_safety: high priority
+   error_handling: high priority
+```
+
+---
+
+### First 7 Days — Cell Learns You
+
+| Event | What Happens |
+|:-----:|--------------|
+| 8 | Type `@cell` in any editor → instant context injected, no explaining |
+| 9 | Vibe signals detected — "Bilingual communicator, strategic auditor, pragmatic shipper" |
+| 10 | Watcher records events — every file save, every git commit tracked |
+| 11 | Smart triggers: 5 saves in 60 sec → predictions automatically refreshed |
+| 12 | Run `cell scan` → code analysis updated with new blind spots |
+| 13 | Cross-editor memory — end session in Cursor → open Claude Code → bridge is already there |
+| 14 | Session bridge captured — files touched, decisions made, what failed, what worked |
+
+---
+
+### First 30 Days — Cell Knows You
+
+| Event | What Happens |
+|:-----:|--------------|
+| 15 | Vibe stabilizes — high-confidence personality profile solidified |
+| 16 | Cross-project profile — `~/.fivo/cell/projects/` tracks data across all your repos |
+| 17 | Global vibe merged — one identity across all your projects |
+| 18 | Predictions get accurate — "this file will be opened", "this error will recur" |
+| 19 | Model intelligence — tracks which AI tool has highest code acceptance rate for you |
+| 20 | Memory compaction — events older than 90 days auto-archived |
+| 21 | User-profile.md generated — your skills, blind spots, journey documented |
+| 22 | Neural handoff — every session end saves bridge + continuity for seamless next start |
+
+---
+
+## 🚀 Features & Benefits
 
 ### ⚙️ 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 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 doctor</code></td><td>Full health check across all layers</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.
+> Multiple CLI commands organized across 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>@cell Context</strong></td><td>Type <code>@cell</code> in any IDE — project, blind spots, predictions, session — all 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>Permanent Memory</strong></td><td>All events stored in local SQLite — decisions, errors, fixes, patterns — never lost</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>
+    <tr><td><strong>Cross-Editor Handoff</strong></td><td>End in Cursor, continue in Claude Code — session bridge already waiting</td></tr>
   </table>
 </div>
 
@@ -189,68 +267,79 @@ cell vibe       # see your developer personality
 <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>Bridge</strong></td><td>Captures session summary at end. Auto-injects at next start. Tracks: summary, key decisions, open questions, failed approaches, working approaches, last thought, files in focus, vibe snapshot, predicted next steps.</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>
+    <tr><td><strong>Predictor</strong></td><td>Predicts files you'll need, errors that may recur, decisions needing revisit. Accuracy improves over 30 days.</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>
+    <tr><td><strong>Personality Signals</strong></td><td>Learned across multiple groups: language, tone, code style, workflow, decision making</td></tr>
+    <tr><td><strong>Identity Detection</strong></td><td>Auto-detects your archetype: e.g. "Bilingual communicator — Strategic auditor — Pragmatic shipper"</td></tr>
+    <tr><td><strong>AI Guide</strong></td><td>Generates rules injected into every AI session — "how to talk to this developer"</td></tr>
+    <tr><td><strong>Live Enforcement</strong></td><td>Watcher flags vibe rule violations automatically on file save</td></tr>
+    <tr><td><strong>Cross-Signal Pairs</strong></td><td>Detects combined behaviors: direct + concise = no-nonsense communicator</td></tr>
+    <tr><td><strong>Contradiction Resolution</strong></td><td>Ships fast for features, perfects for security — context-dependent vibe</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.
+> **Example AI Guide generated by Cell:** "Be direct — start with answer, then explain. Use Hinglish where helpful. Keep changes minimal. 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>Code Scanner</strong></td><td>Walks all project files, analyzes structure, stack, style, and risk patterns</td></tr>
+    <tr><td><strong>Blind Spots</strong></td><td>Detects: null safety, missing try/catch, console.log, code quality, performance, validation</td></tr>
+    <tr><td><strong>Deep Analysis</strong></td><td>Complexity analysis, duplicate detection, nesting depth, long functions</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>Rich MCP Tools</strong></td><td>Sessions, context, memory, vibe, team, community, watch, sync, graph, scan, CI — all covered</td></tr>
+    <tr><td><strong>Honest Detection</strong></td><td>Only IDEs you actually have installed are configured — no fake counts</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>Live Events</strong></td><td>Captures file changes in real-time — every save tracked</td></tr>
+    <tr><td><strong>Smart Triggers</strong></td><td>5 saves in 60 seconds → predictions auto-refreshed</td></tr>
+    <tr><td><strong>Vibe Update</strong></td><td>Watcher keeps your personality profile fresh automatically</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">
@@ -260,41 +349,44 @@ cell vibe       # see your developer personality
     <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>Multi-Point Doctor</strong></td><td>git, node, DB, daemon, watch, MCP, FTS, scan — all checked with <code>cell doctor</code></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>
+    <tr><td><strong>Atomic Writes</strong></td><td>temp then rename — files never corrupt on crash</td></tr>
+    <tr><td><strong>No eval/spawnSync</strong></td><td>Zero dynamic code execution vectors</td></tr>
+    <tr><td><strong>Parameterized SQL</strong></td><td>Zero injection risk across all queries</td></tr>
+    <tr><td><strong>npm audit: 0</strong></td><td>Zero known vulnerabilities in dependencies</td></tr>
   </table>
 </div>
 
 ---
 
+## 🚫 What FivoCell Does NOT Do
+
+Honest list. Know this before you use it.
+
+| # | Missing | Why |
+|:-:|---------|-----|
+| 1 | **Semantic code understanding** — "explain why this function is wrong logically" | Needs an LLM. Cell is fully rule-based and deterministic. |
+| 2 | **Live cloud sync** (`cell.fivo.live`) | Cloud server is a separate deployment. Cell itself works 100% offline. |
+| 3 | **Multi-language deep parsing** (Python, Rust, Go) | Tree-sitter is installed but not fully wired into all analyzers yet. |
+
+**What Cell IS:** A rule-based, deterministic, offline-first memory layer.
+**What Cell is NOT:** An LLM, a code explainer, or a cloud service.
+
+---
+
 ## 🆚 FivoCell vs The Alternatives
 
 <div align="center">
@@ -341,7 +433,7 @@ cell vibe       # see your developer personality
     </tr>
     <tr>
       <td>Learns your <strong>personality / vibe</strong></td>
-      <td align="center">✅ 100 signals</td>
+      <td align="center">✅ Multi-signal</td>
       <td align="center">❌</td>
       <td align="center">❌</td>
       <td align="center">❌</td>
@@ -349,20 +441,12 @@ cell vibe       # see your developer personality
     </tr>
     <tr>
       <td><strong>Auto-detects</strong> code style</td>
-      <td align="center">✅ 8 categories with %</td>
+      <td align="center">✅ Multi-category</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>
@@ -414,8 +498,8 @@ cell vibe       # see your developer personality
 │                         ▼                 ▼                 ▼  │
 │                   ┌──────────┐    ┌──────────┐    ┌──────────┐ │
 │                   │  SQLite  │    │  .cell/  │    │   Vibe   │ │
-│                   │  18 MB   │    │  270 KB  │    │  Engine  │ │
-│                   │  70 tbls │    │ INDEX.md │    │ 100 rules│ │
+│                   │  local   │    │  INDEX   │    │  Engine  │ │
+│                   │  DB      │    │  bridge  │    │  signals │ │
 │                   └──────────┘    └──────────┘    └──────────┘ │
 └─────────────────────────────────────────────────────────────────┘
 ```
@@ -454,16 +538,16 @@ cell vibe       # see your developer personality
 ```
   @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
+                   +-- SQLite local DB (all events, decisions, errors)
+                   +-- .cell/INDEX.md (fast context lookup)
+                   +-- .cell/vibe/ (personality signals)
+                   +-- .cell/bridge/latest.json (last session)
+                   +-- .cell/continuity/ (active thread)
+                   +-- .cell/predictor.json (next actions)
                ->  Ranks by relevance
                ->  Compresses to token budget
                ->  Formats per-tool
-               ->  Returns ~1,289 chars
+               ->  Returns context block to AI
 ```
 
 ---
@@ -490,21 +574,21 @@ cell vibe       # see your developer personality
 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.
+* 💾 **Local SQLite Database**: Stores memory events, CLI history, session summaries, and decisions on your local machine (`.cell/` folder).
+* ⚙️ **Developer Vibe Signals**: Learns your local programming conventions and styles to build custom AI 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.
+* ❌ **Raw Source Code**: All code diagnostics run locally. Your source files never leave your machine.
+* ❌ **API Keys & Credentials**: The `PrivacyRedactor` intercepts and redacts API tokens, AWS keys, 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.
+* **Community Patterns**: Anonymized vibe and high-level style patterns only — no raw code, names, or paths.
+* **Team Sync**: Optional encrypted sharing of project decisions and session handoffs.
 
-To verify your security state at any time, run:
+To verify your security state at any time:
 ```bash
 cell doctor
 ```
@@ -516,8 +600,6 @@ cell doctor
 <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>
@@ -525,9 +607,9 @@ cell doctor
     <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>
+    <tr><td>Bug Reports</td><td><a href="docs/BUG_REPORT.md">docs/BUG_REPORT.md</a></td></tr>
+    <tr><td>Cloud Sync Guide</td><td><a href="docs/CLOUD-SYNC-GUIDE.md">docs/CLOUD-SYNC-GUIDE.md</a></td></tr>
   </table>
 </div>