feat: v1.0.4 - uninstall command, stale binary cleanup, viz UI overhaul, embedded migrations

Author: 1337Xcode

.github/workflows/ci.yml

@@ -33,11 +33,11 @@ jobs:
       - name: Check compilation
         run: cargo check --all-targets
 
-      - name: Run clippy
-        run: cargo clippy --all-targets -- -D warnings
+      - name: Format
+        run: cargo fmt --all
 
-      - name: Check formatting
-        run: cargo fmt --all -- --check
+      - name: Clippy
+        run: cargo clippy --all-targets --fix --allow-dirty --allow-staged -- -D warnings
 
   test:
     runs-on: ubuntu-latest

CHANGELOG.md

@@ -2,6 +2,34 @@
 
 All notable changes to Cortex are documented here.
 
+## [1.0.4] - 2026-05-25
+
+### Added
+- `cortex uninstall` command: removes all Cortex traces (binary, graph DB, config, PATH entries, steering files)
+- Installer automatically removes stale cortex binaries from `~/.local/bin`, npm global, and other known locations before installing
+- Installer prepends `~/.cortex/bin` to the current session PATH so reindex uses the new binary immediately
+- Installer checks `.profile` in addition to `.bashrc`/`.zshrc` for Unix PATH configuration
+- Live visualizer (`cortex serve` at `http://127.0.0.1:9749`) now serves the clean viz.rs-style 3D graph UI
+- Dashboard page at `/dashboard` with token savings, symbol search, and tool usage table
+- Navigation between graph view and dashboard via header links
+- `Method` node kind added to SQLite CHECK constraint (fixes indexing of Python `__init__`, class methods, TS constructors)
+- CI auto-fixes formatting and clippy before checking (no more spurious failures)
+
+### Fixed
+- Old cortex binaries in `~/.local/bin` or npm global shadowing the new install (caused `cortex -V` showing wrong version after update)
+- IDE auto-detection no longer falsely detects agents from generic directories (`.github/`, `.vscode/`, `.idea/`, `.kiro/`)
+- Embedded migrations 0007 and 0008 were missing from the binary (Method kind, token savings tables)
+- Windows `setx` PATH note tells user to open a new terminal
+
+### Changed
+- HTML templates moved from `src/cli/commands/` to `src/cli/templates/` (proper structure)
+- Visualizer root (`/`) serves the viz.rs-style graph; dashboard at `/dashboard`
+- Dashboard rewritten: clean dark UI matching viz.rs aesthetic, no more janky tabbed interface
+- Removed dead `dashboard_html.html` file
+
+### Removed
+- Old tabbed unified UI (replaced by separate graph + dashboard pages)
+
 ## [1.0.3] - 2026-05-25
 
 ### Added
@@ -14,6 +42,7 @@ All notable changes to Cortex are documented here.
 - Windows x86 (`win32-ia32`) binary support in release workflow and npm installer
 
 ### Changed
+- Visualizer serves dynamic graph template (fetches `/api/nodes` and `/api/edges` at runtime) with loading state, reset button, and additional node kind badges (Method, Interface, Type)
 - Unified UI fully dark-themed (`#1e1e2e` background) with corner-positioned icon navigation replacing the nav bar
 - Hotspots table uses `overflow-x: auto` to prevent horizontal overflow
 - Statistics overlay uses CSS Grid with `tabular-nums` for numeric alignment

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "cortex"
-version = "1.0.3"
+version = "1.0.4"
 edition = "2024"
 license = "MIT"
 

Cargo.toml

@@ -73,7 +73,7 @@ Cortex indexes your repository into a SQLite call graph and exposes it over the
 ## Install
 
 ```sh
-npx @1337xcode/cortex install
+npx @1337xcode/cortex@latest install
 ```
 
 <details>
@@ -112,7 +112,6 @@ cortex impact UserService.getUser       # blast radius: what breaks if I change
 cortex explain DatabasePool.acquire     # offline function explanation, zero LLM calls
 cortex security report                  # taint flows, OWASP patterns, dependency vulns
 cortex diff main feature-branch         # call graph diff between branches
-cortex viz --port 9749                  # unified tabbed UI (Graph, Dashboard, Explorer)
 cortex viz --export graph.html          # interactive 3D graph in a standalone HTML file
 cortex ci --fail-on-taint               # CI quality gate with exit codes
 cortex hotspots --months 6              # high-churn risky code ranked by risk score
@@ -128,7 +127,7 @@ cortex federate add ../auth-service     # query across repos with unified graph
 - **Sub-second incremental re-indexing** via native OS file watcher (inotify, FSEvents, ReadDirectoryChangesW)
 - **Configurable model pricing** via `~/.cortex/pricing.toml` with longest-prefix matching
 - **Ego-graph capping** at 500 nodes with priority ordering (depth first, then caller count)
-- **Unified tabbed UI** with Graph, Dashboard, and Explorer views served at a single endpoint
+- **Unified tabbed UI** with Graph and Dashboard views served at `cortex serve` (localhost:9749)
 - **Coverage field on graph nodes** populated from LCOV data, surfaced in MCP tool responses
 - **Method vs Function classification** verified across Python, TypeScript, Rust, Go, and Java
 - **Agent steering generation** with module boundaries, complexity hotspots, and active ADRs
@@ -201,7 +200,7 @@ graph TD
 | Coverage gap analysis | Yes (LCOV cross-ref) | No | No | No | No |
 | Configurable pricing | Yes (TOML) | No | No | No | No |
 | Ego-graph capping | Yes (500 nodes) | No | No | No | No |
-| Unified tabbed UI | Yes (Graph/Dashboard/Explorer) | No | No | No | No |
+| Unified tabbed UI | Yes (Graph/Dashboard) | No | No | No | No |
 | Agent steering generation | Yes (boundaries, hotspots, ADRs) | No | No | No | No |
 | CI quality gates | Yes (exit codes) | No | No | No | No |
 | Single binary, zero deps | Yes | Yes | No (Python) | No (Python+LSP) | No (Python) |

README.md

@@ -4,7 +4,8 @@
 
 | Version | Supported          |
 | ------- | ------------------ |
-| 0.0.x   | :white_check_mark: |
+| 1.0.x   | :white_check_mark: |
+| 0.0.x   | :x:                |
 
 ## Reporting a Vulnerability
 
@@ -54,4 +55,6 @@ Cortex is designed with the following security principles:
 3. **No code execution**: Cortex never executes code from indexed repositories
 4. **No secrets in logs**: Tracing never logs file contents, observation text, or source code
 5. **Input sanitization**: All FTS5 queries are sanitized to prevent injection
-6. **Air-gap compatible**: All features work without network access (except OSV.dev checks)
+6. **Air-gap compatible**: All features work without network access (except OSV.dev checks and `cortex update`)
+7. **SHA-256 verified updates**: `cortex update` and the npm installer verify checksums before replacing binaries
+8. **Stale binary cleanup**: Installer removes old binaries from other PATH locations to prevent version confusion

SECURITY.md

@@ -18,13 +18,19 @@ graph TD
         Indexer[Indexer<br/>Rayon + tree-sitter]
         Watcher[File Watcher<br/>notify crate]
         MCP[MCP Server<br/>Tokio + JSON-RPC 2.0]
+        Viz[Visualizer<br/>3D Graph + Dashboard]
     end
 
     DB[(SQLite<br/>WAL mode)]
 
     Watcher -->|FileEvent| Indexer
     Indexer -->|Write| DB
     MCP -->|Read| DB
+    Viz -->|Read| DB
+
+    Update[cortex update] -->|GitHub Releases| Replace[Replace Binary]
+    Replace --> Reindex[cortex reindex]
+    Reindex -->|Delete + Rebuild| DB
 ```
 
 ```mermaid

docs/architecture.md

@@ -38,6 +38,23 @@ Removes `graph.db`, `graph.db-wal`, and `graph.db-shm` from `.cortex-data/`, rec
 
 Use this after a schema change, a corrupted database, or when switching branches with significantly different code.
 
+## cortex uninstall
+
+Remove all Cortex traces from the system.
+
+```sh
+cortex uninstall
+```
+
+Removes:
+- Graph database (`.cortex-data/`)
+- Config directory (`.cortex/`)
+- Binary (`~/.cortex/bin/cortex`)
+- Shell PATH entries added by the installer
+- Agent steering files written by `cortex install`
+
+After uninstalling, restart your terminal for PATH changes to take effect.
+
 ## cortex status
 
 Print graph statistics for the current repository.

docs/cli-reference.md

@@ -3,7 +3,7 @@ title: "Getting Started"
 description: "Install Cortex and index your first repository in under a minute."
 order: 1
 category: "guides"
-lastModified: "2025-07-14"
+lastModified: "2026-05-25"
 ---
 
 # Getting started
@@ -13,10 +13,10 @@ lastModified: "2025-07-14"
 The fastest way to install Cortex:
 
 ```sh
-npx @1337xcode/cortex install
+npx @1337xcode/cortex@latest install
 ```
 
-This downloads the binary for your platform, detects your AI coding agents, and writes the MCP config for each one. No manual configuration needed.
+This downloads the binary for your platform, verifies the SHA-256 checksum, removes any stale old versions, configures your PATH, and runs a full index. Zero-touch.
 
 Alternatives:
 
@@ -30,17 +30,33 @@ cargo build --release
 cp target/release/cortex ~/.local/bin/
 ```
 
+## Update
+
+Cortex checks for updates on every launch and notifies you if a newer version exists. To update:
+
+```sh
+cortex update
+```
+
+This downloads the latest release, verifies the checksum, replaces the binary, and re-indexes.
+
 ## Index your repository
 
 ```sh
 cd /path/to/your/project
 cortex index
 ```
 
-This parses every source file with tree-sitter, extracts functions, classes, call edges, and import relationships, then stores them in a local SQLite database at `.cortex/graph.db`.
+This parses every source file with tree-sitter (29 languages), extracts functions, classes, call edges, and import relationships, then stores them in a local SQLite database.
 
 Indexing is fast. A 3500-file Python project (CPython) indexes in under 60 seconds. A typical 100-file project takes about 500ms.
 
+To force a clean rebuild:
+
+```sh
+cortex reindex
+```
+
 ## Start the MCP server
 
 ```sh
@@ -61,7 +77,7 @@ You don't usually run this manually. The `cortex install` command configures you
 
 ## Configure your agent
 
-If you didn't use `npx @1337xcode/cortex install`, configure manually:
+If you didn't use `npx @1337xcode/cortex@latest install`, configure manually:
 
 ```sh
 cortex install
@@ -72,57 +88,51 @@ This detects installed agents and writes the correct config for each:
 | Agent | Config location |
 |-------|----------------|
 | Claude Code | ~/.claude/settings.json |
-| Claude Desktop (macOS) | ~/Library/Application Support/Claude/claude_desktop_config.json |
-| Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json |
-| Cursor | ~/.cursor/mcp.json |
-| Windsurf | ~/.codeium/windsurf/mcp_config.json |
-| VS Code | .vscode/mcp.json (workspace) |
-| Zed | ~/.config/zed/settings.json |
-| JetBrains | ~/.config/github-copilot/mcp.json |
-| Kiro | ~/.kiro/settings/mcp.json |
-| Cline | .cline/mcp.json |
+| Cursor | .cursor/mcp.json |
+| Windsurf | .windsurf/mcp.json |
+| VS Code | .vscode/mcp.json |
+| Kiro | .kiro/settings/mcp.json |
+| Zed | .zed/settings.json |
+| JetBrains | .idea/mcp.json |
+| GitHub Copilot | .github/copilot-mcp.json |
+| Cline/Roo | .vscode/mcp.json |
+
+Use `--platform <name>` to configure a specific agent without auto-detection.
 
 ## Verify it works
 
 Ask your agent: "What are the most-called functions in this codebase?"
 
 The agent should use the `get_architecture` or `search_symbols` tool and return structural results from the graph rather than reading files.
 
-## What happens next
-
-Once indexed, Cortex keeps the graph up to date automatically:
-
-- The file watcher detects changes and re-indexes modified files in sub-second time
-- Observations you write persist across sessions
-- The bundle (cortex.json) can be committed to git for team sharing
-
-## Common next steps
+## Visualize
 
 ```sh
-# Generate a security report
-cortex security report
-
-# See what breaks if you change a function
-cortex impact MyClass.my_method
+# Interactive 3D graph in browser (live server)
+cortex serve
+# Then open http://127.0.0.1:9749
 
-# Export an interactive graph visualization
+# Export standalone HTML file
 cortex viz --export graph.html
+```
 
-# Set up auto re-indexing on commit
-cortex hook install
-
-# Add another repo to the federation
-cortex federate add ../shared-lib
+## Uninstall
 
-# Ingest documentation into the graph
-cortex ingest ./docs
+To completely remove Cortex (binary, database, config, PATH entries):
 
-# Show build system workspace members
-cortex modules --build-system
+```sh
+cortex uninstall
+```
 
-# Find high-churn risky code
-cortex hotspots
+## Common next steps
 
-# Cross-reference test coverage with call graph
-cortex coverage --lcov coverage.lcov
+```sh
+cortex security report     # Security scan
+cortex impact MyClass.foo  # Blast radius analysis
+cortex viz --export g.html # Export 3D graph
+cortex hook install        # Auto re-index on commit
+cortex federate add ../lib # Multi-repo federation
+cortex ingest ./docs       # Ingest documentation
+cortex hotspots            # Find risky code
+cortex coverage --lcov c.lcov  # Coverage gaps
 ```

docs/getting-started.md

@@ -8,10 +8,10 @@ Code intelligence for AI agents. Indexes your repo into a call graph, exposes it
 ## Install
 
 ```sh
-npx @1337xcode/cortex install
+npx @1337xcode/cortex@latest install
 ```
 
-Downloads the binary for your platform, verifies the SHA256 checksum, drops it in your PATH. Works on Linux, macOS (Intel + Apple Silicon), and Windows.
+Downloads the binary for your platform, verifies the SHA256 checksum, removes any stale cortex binaries from other locations, and drops it in your PATH. Works on Linux, macOS (Intel + Apple Silicon), and Windows. Zero-touch: one command, no manual cleanup needed.
 
 ## What it does