@precisionutilityguild/liquid-shadow 1.0.10 → 1.0.11

package/README.md

@@ -1,119 +1,336 @@
-# 🌑 Liquid Shadow
+<p align="center">
+  <img src="https://img.shields.io/badge/%F0%9F%8C%91_Liquid_Shadow-MCP_Intelligence_Layer-6D28D9?style=for-the-badge" alt="Liquid Shadow">
+</p>
+
+<h1 align="center">Liquid Shadow</h1>
 
 <p align="center">
-  <b>Tactical Repository Intelligence Operative - The AI-First Intelligence Layer</b><br>
-  <i>Transform your codebase into a high-signal knowledge graph built for reasoning.</i>
+  <strong>The AI-First Code Intelligence Layer for MCP Agents</strong><br>
+  Stop making your agents grep. Give them a brain.
 </p>
 
 <p align="center">
-  <img src="https://img.shields.io/badge/version-1.0.10-blue.svg" alt="Version">
-  <img src="https://img.shields.io/badge/License-Apache--2.0-blue.svg" alt="License">
-  <img src="https://img.shields.io/badge/build-passing-brightgreen.svg" alt="Build">
-  <img src="https://img.shields.io/badge/MCP-First-6D28D9.svg" alt="MCP First">
+  <a href="https://www.npmjs.com/package/@precisionutilityguild/liquid-shadow"><img src="https://img.shields.io/npm/v/@precisionutilityguild/liquid-shadow?color=6D28D9&label=npm" alt="npm version"></a>
+  <img src="https://img.shields.io/badge/MCP-Compatible-10B981.svg" alt="MCP Compatible">
+  <img src="https://img.shields.io/badge/Tools-52_Atomic-F59E0B.svg" alt="52 Tools">
+  <img src="https://img.shields.io/badge/Languages-TS%20%7C%20JS%20%7C%20Python%20%7C%20PHP%20%7C%20Go-3B82F6.svg" alt="Languages">
+  <img src="https://img.shields.io/badge/License-Apache--2.0-gray.svg" alt="License">
 </p>
 
 ---
 
-## The AI-Native Intelligence OS
+## The Problem With How Agents Work Today
+
+Every time your AI agent needs to understand a codebase, it does this:
+
+```
+read file → grep → read another file → grep → read another file...
+```
 
-**Liquid Shadow** is the primary bridge between your reasoning engine and the raw filesystem. It doesn't just "index" code; it builds a **Relational Intelligence Graph** that allows AI agents to navigate, reason about, and modify large-scale repositories with surgical precision and extreme token efficiency.
+That's hundreds of tokens, dozens of tool calls, and a reasoning chain that collapses under its own weight for anything larger than a toy project. The agent never builds a real mental model — it just stumbles through the dark.
 
-Stop forcing your agents to grep through files. Give them the ability to "feel" the architecture through topological maps and execution flows.
+**Liquid Shadow fixes this at the architecture level.**
 
 ---
 
-## Product Pillars
+## What It Is
 
-### Semantic Sieve & Token Efficiency
+Liquid Shadow is a **Model Context Protocol (MCP) server** that builds a persistent **Relational Intelligence Graph** of your codebase — symbols, dependencies, types, execution flows, git history — and exposes it as 52 high-signal atomic tools your agents can use instead of file reads and grep.
 
-Context is the most expensive resource. Our **Semantic Sieve** intelligently folds implementation details, revealing only the signatures and intent your agent needs. With **Briefing Zoom Levels** (`Orbit`, `Atmosphere`, `Ground`), you control exactly how many tokens are consumed based on the task's altitude.
+One `shadow_analyze_flow` call returns the entire execution graph from an entrypoint.  
+One `shadow_analyze_impact` call shows the full blast radius before a change.  
+One `shadow_ops_briefing` call resumes mission context across sessions.
 
-### Nano-Repair & Structural Stability
+This isn't a smarter `grep`. It's a different paradigm entirely.
 
-Repositories are liquid. Code moves, files are renamed, and dependencies shift. **Nano-Repair** auto-heals your intelligence index in real-time, ensuring that "intent links" and architectural context survive even the most aggressive refactors.
+---
 
-### Mission-Driven Development
+## What It Actually Does
 
-We treat development as a series of tactical **Missions**. Liquid Shadow records every architectural decision (ADR), discovery, and blocker as it happens, creating a persistent "Chronome" of project narrative that persists across sessions.
+### 🔍 Semantic Code Discovery
+Natural language search across your entire codebase. Find "authentication logic" — not just files with `auth` in the name. Powered by hybrid **vector + BM25 FTS** search with Reciprocal Rank Fusion scoring.
 
-### Relational Impact Analysis
+### 📊 Relational Graph Analysis
+Trace full execution flows. Compute blast radius of any change. Resolve type inheritance chains. Map every HTTP route, socket event, and pubsub topic — producers and consumers split.
 
-Change one function, see the ripple. Trace execution flows and predict the **Blast Radius** of any modification across repository boundaries using our cross-repo fusion engine.
+### 🧠 Token-Optimized Inspection
+The **Semantic Sieve** folds implementation details and surfaces only signatures and intent. Control depth with `Orbit → Atmosphere → Ground` zoom levels. A file summary costs ~20 tokens instead of 2,000.
 
----
+### 🎯 Mission-Driven Development
+Persistent context that **survives across sessions**. Create missions with outcome contracts, log decisions and discoveries, synthesize Architectural Decision Records, and resume exactly where you left off — even weeks later.
 
-## The Tactical Suite (45 Atomic Tools)
+### 🤝 Multi-Agent Coordination
+File-level **claim/release locking** prevents parallel agents from stomping on each other's work. Dispatch plans across agent roles. Submit findings to a peer-review Tribunal. Hand off typed artifacts between RECON → OVERSEER → ENGINEER pipelines.
 
-Organized into specialized intelligence suites for the modern agent:
+### 🔧 Zero-Maintenance Indexing
+Git hooks auto-reindex on every commit and branch switch. The **Ember Daemon** builds semantic embeddings in the background at lowest OS priority — your `git commit` is never blocked.
 
-| Suite            | Tactical Purpose                | Key Tools                                          |
-| :--------------- | :------------------------------ | :------------------------------------------------- |
-| **Ops Control**  | Mission & context management    | `shadow_ops_context`, `shadow_ops_briefing`        |
-| **Intelligence** | Deep architectural reasoning    | `shadow_analyze_impact`, `shadow_analyze_flow`     |
-| **Discovery**    | Semantic & config retrieval     | `shadow_search_concept`, `shadow_search_config`    |
-| **Recon**        | Structural layer classification | `shadow_recon_topography`, `shadow_recon_hologram` |
-| **Inspection**   | Token-optimized code folding    | `shadow_inspect_symbol`, `shadow_inspect_file`     |
-| **Maintenance**  | Intelligence synchronization    | `shadow_sync_trace`, `shadow_sync_repair`          |
+### 🌐 Cross-Repo Intelligence
+The **Fused Index** unifies multiple repositories at query time via SQLite `ATTACH DATABASE`. Zero data duplication. Trace a frontend API call all the way through to the backend handler across repo boundaries.
 
 ---
 
-## The Intelligence Lifecycle
+## Tool Suite (52 Atomic Tools)
+
+| Suite | Tools | Purpose |
+|:------|:------|:--------|
+| **`shadow_recon_*`** | `onboard` `topography` `scout` `tree` `hologram` | Bootstrap index, structural classification, arc maps |
+| **`shadow_search_*`** | `concept` `symbol` `config` `path` | Semantic, symbol, env var, and path searches |
+| **`shadow_analyze_*`** | `impact` `flow` `deps` `mesh` `type_graph` `debt` `explain_diff` | Blast radius, execution flows, API surfaces, dead code, diff narratives |
+| **`shadow_inspect_*`** | `symbol` `file` | Token-folded symbol inspection and file summaries |
+| **`shadow_ops_*`** | `plan` `track` `log` `briefing` `context` `synthesize` `chronicle` `health` `graph` `crystallize` `crystallize_theme` `claim` `release` `dispatch_plan` `tribunal_submit` `tribunal_status` `handoff` `handoff_read` | Full mission lifecycle + multi-agent coordination |
+| **`shadow_sync_*`** | `trace` `index` `repair` | Incremental sync, Nano-Repair auto-healing |
+| **`shadow_env_*`** | `hooks` `diagnose` | Git hook management, system health |
+| **`shadow_workspace_*`** | `list` `link` `fuse` `status` `ensure` `repair` `gc` | Multi-repo Federation |
+
+---
 
-Liquid Shadow is designed to be the first point of contact for any agent entering a workspace.
+## Zero-Config Setup (2 Minutes)
 
-### 1. Installation (Safe Init)
+Stop configuring things manually. Liquid Shadow auto-discovers your IDE and injects both the MCP server and the Tactical Skills so your agent is instantly operational.
 
 ```bash
-npm install -g @precisionutilityguild/liquid-shadow
-liquid-shadow init # Interactive security confirmation
+# 1. Install globally
+npm i -g @precisionutilityguild/liquid-shadow
+
+# 2. Run the tactical onboarding
+liquid-shadow init
 ```
 
-### 2. Operational Dashboard (TUI)
+The `init` script automatically configures MCP connections for:
+- ✅ **Claude Code** (`~/.claude.json`)
+- ✅ **Claude Desktop** (`claude_desktop_config.json`)
+- ✅ **Gemini CLI** (`~/.gemini/settings.json`)
+- ✅ **Antigravity IDE** (`mcp_config.json`)
+- ✅ **Cursor** (via `.cursor/mcp.json` context)
+- ✅ **Codex** (`~/.codex/config.toml`)
 
-Keep a finger on the pulse of your repository's intelligence. Liquid Shadow provides a high-signal Terminal UI for a bird's-eye view of your mapping density and performance.
+*(If you are using an unsupported client, simply point it to `liquid-shadow-mcp` with no arguments).*
 
-```bash
-liquid-shadow dashboard
+---
+
+## First Run: Onboard Your Repository
+
+Once connected, tell your agent:
+
+```
+Use shadow_recon_onboard on /absolute/path/to/your/repo
+```
+
+Liquid Shadow scans all source files, extracts symbols, builds dependency graphs, and fires up the Ember Daemon for background embedding generation. Most mid-size projects are ready in under 30 seconds.
+
+---
+
+## The Skills System
+
+Liquid Shadow ships **14 pre-built agent workflows** (called Skills) that are automatically injected into your agent's context on `init`. Instead of calling raw tools and guessing at the right sequence, agents follow optimized tactical playbooks.
+
+| Skill | What It Does |
+|:------|:-------------|
+| `/onboard` | Bootstrap index, hooks, and first mission |
+| `/understand` | Concept-to-code mapping and execution tracing |
+| `/mission` | Strategic planning with outcome contracts |
+| `/continue` | Resume the highest-priority active mission |
+| `/trace-impact` | Blast radius and cross-repo dependency maps |
+| `/audit` | Dead code, circular deps, layer drift detection |
+| `/chronicle` | Git-native narrative history of the project |
+| `/synthesize` | Distill mission logs into Architectural Decision Records |
+| `/research` | External dependency research with local + web context |
+| `/workspace` | Multi-repo federation and mission linking |
+| `/crystallize` | Compress mission logs for token-efficient briefings |
+| `/coordinate` | Multi-agent dispatch and Tribunal reviews |
+| `/sync` | Incremental index repair after external changes |
+
+Skills reduce "what tools do I call in what order?" from a guessing game to a single directive.
+
+---
+
+## Real Usage Patterns
+
+### "What breaks if I change this function?"
+
+```
+Use shadow_analyze_impact on the authenticateUser function in src/auth/service.ts
+```
+
+Returns: every downstream consumer, call depth by default = 3, with file paths and symbol names. Blast radius computed in one call.
+
+### "Where is the auth logic?"
+
+```
+Use shadow_search_concept to find all authentication and session handling code
+```
+
+Returns: semantically ranked results. Finds code that *handles auth* even if it doesn't have `auth` in the filename.
+
+### "Explain what changed in this diff"
+
+```
+Use shadow_analyze_explain_diff with staged:true
+```
+
+Returns: a semantic narrative of what your current staged changes actually do — not just a list of lines changed.
+
+### "Resume where I left off"
+
+```
+Use shadow_ops_briefing on /path/to/repo at Ground altitude
+```
+
+Returns: active missions, next candidates, recent decisions, health stats — full context reconstruction from persistent storage.
+
+### "Find all API endpoints in this service"
+
+```
+Use shadow_analyze_mesh on /path/to/repo with topic "/api/"
 ```
 
-> **Scouting Report**: Need a quick status instead? Run `liquid-shadow status`.
+Returns: every HTTP route, socket event handler, and pubsub topic — producers and consumers mapped separately.
+
+---
 
-### 3. The Skills-First Loop
+## Performance
 
-Liquid Shadow is designed for **Autonomy**. While it provides 45 atomic tools, the primary interface for an agent is the **Skills** system. Running `liquid-shadow init` automatically injects these high-level workflows into the agent's environment.
+Indexing is CPU-parallel via SWC worker pools. Semantic embeddings are off-thread via the Ember Daemon.
 
-#### High-Signal Workflows
+| Repository | Files | Symbols | Time |
+|:-----------|:------|:--------|:-----|
+| VS Code core | 6,100 | 109,000+ | 110.6s |
+| Next.js | 9,700 | — | 24.2s (~400 files/sec) |
+| Django | 2,893 | — | validated |
+| Laravel Framework | 2,854 | — | validated |
+| FastAPI | 1,118 | — | validated |
 
-Instead of guessing which tools to call, agents follow optimized **Tactical Skills**:
+After the first index, incremental syncs typically complete in 1–3 seconds.
 
-- **/onboard**: Build the baseline index and topography.
-- **/understand**: Concept-to-code mapping and execution tracing.
-- **/mission**: Strategic planning and automated ADR synthesis.
-- **/trace-impact**: Predict blast radius and dependency ripple effects.
-- **/audit**: Detect technical debt, circular deps, and dead code.
+---
 
-#### Example: Agent Strategy Flow
+## CLI Reference
 
-```markdown
-// 1. RECON: The agent reads the Skill definition
-view_file({ path: '.agent/skills/onboard/SKILL.md' });
+For direct terminal use without an agent:
 
-// 2. ACT: Following the Skill, the agent orchestrates the tools
-shadow_recon_onboard({ repoPath: '/abs/path' });
-shadow_ops_context({ repoPath: '/abs/path' });
-shadow_env_hooks({ action: 'install', repoPath: '/abs/path' });
+```bash
+# Initialize the intelligence index
+npx @precisionutilityguild/liquid-shadow index /path/to/repo
+
+# Real-time dashboard
+npx @precisionutilityguild/liquid-shadow dashboard
+
+# Quick status
+npx @precisionutilityguild/liquid-shadow status /path/to/repo
+
+# Symbol inspection
+npx @precisionutilityguild/liquid-shadow inspect symbol /path/to/repo MyClass
+
+# Mission management
+npx @precisionutilityguild/liquid-shadow mission plan /path/to/repo "Migrate Auth" "Replace JWT with OAuth2"
+npx @precisionutilityguild/liquid-shadow mission briefing /path/to/repo
+npx @precisionutilityguild/liquid-shadow mission synthesize /path/to/repo <mission-id>
+
+# Semantic search
+npx @precisionutilityguild/liquid-shadow search-concept "authentication middleware"
+
+# Deploy/update skills to all detected agents
+npx @precisionutilityguild/liquid-shadow skills update
+
+# Git hooks (auto-reindex on commit + branch switch)
+npx @precisionutilityguild/liquid-shadow hooks install
 ```
 
 ---
 
-## Enterprise-Grade Performance
+## Supported Languages
 
-Optimized for speed. Scalable for large codebases.
+| Language | Parser | Status |
+|:---------|:-------|:-------|
+| TypeScript | SWC | ✅ Full |
+| JavaScript | SWC | ✅ Full |
+| Python | Tree-sitter | ✅ Full |
+| PHP | Tree-sitter | ✅ Full |
+| Go | Tree-sitter | ✅ Full |
 
-- **VS Code Core (6.1k files)**: Indexed in **110.6s** (109k+ symbols)
-- **Next.js (9.7k files)**: Indexed in **24.2s** (~404 files/sec)
+More languages are added via Tree-sitter grammars. The parser is auto-selected from file extension.
+
+---
+
+## Architecture at a Glance
+
+```
+Your Agent (Claude / Cursor / Gemini / etc.)
+         │
+         │  MCP stdio transport
+         ▼
+┌─────────────────────────────────────────┐
+│           Liquid Shadow MCP Server      │
+│  52 atomic tools across 8 suites        │
+│                                         │
+│  ┌──────────┐  ┌──────────────────────┐ │
+│  │  Recon   │  │  Intelligence Engine │ │
+│  │  Layer   │  │  (Impact/Flow/Mesh)  │ │
+│  └────┬─────┘  └──────────┬───────────┘ │
+│       │                   │             │
+│  ┌────▼───────────────────▼───────────┐ │
+│  │   SQLite FTS5 + Vector Index       │ │
+│  │   (Symbols · Deps · Embeddings)    │ │
+│  └────────────────────────────────────┘ │
+│                                         │
+│  ┌──────────────┐  ┌────────────────┐   │
+│  │ Mission Store│  │  Ember Daemon  │   │
+│  │ (Git Notes)  │  │ (bg embeddings)│   │
+│  └──────────────┘  └────────────────┘   │
+└─────────────────────────────────────────┘
+         │
+         ▼
+  Your Repository (read-only — never modifies source)
+```
+
+Liquid Shadow is **fully read-only** on your source code. It maintains its own SQLite index alongside your repository.
+
+---
+
+## Multi-Agent & Parallel Safety
+
+Running multiple agents on the same codebase simultaneously? Liquid Shadow handles it:
+
+- **`shadow_ops_claim`** — agent claims a file before editing
+- **`shadow_ops_release`** — releases the claim after
+- **`shadow_working_set_check`** — query active claims before spawning parallel workers
+- **`shadow_ops_dispatch_plan`** — assign sub-missions to specialized agent roles
+- **`shadow_ops_tribunal_submit/status`** — peer-review findings before merging conclusions
+
+Claim entries are TTL-based and auto-expire, so a crashed agent never permanently blocks a file.
+
+---
+
+## Frequently Asked Questions
+
+**Does Liquid Shadow modify my source code?**  
+Never. It is strictly read-only on your codebase. The only files it writes are its own SQLite index and Git Notes for mission logs.
+
+**How do I keep the index fresh?**  
+You don't have to. Every tool automatically runs a JIT (Just-In-Time) git-tree differential check before executing. If you've modified files since the last index, it incrementally syncs only the changed files in milliseconds before answering your query. (You can also install Git hooks via `shadow_env_hooks` for background syncing).
+
+**What if I rename files or move symbols?**  
+Run `shadow_sync_repair`. Nano-Repair re-links anchors and heals broken intent references without a full re-index.
+
+**Can I use this as a library (not MCP)?**  
+Yes. The programmatic API (`query.ts`) exposes `searchSymbol`, `analyzeImpact`, and `getBriefing` as direct TypeScript entry-points.
+
+**Does it work offline / on private code?**  
+Yes. Everything runs locally. No source code is sent anywhere. Embeddings are generated locally via `@xenova/transformers`.
+
+---
+
+## Links
+
+- **Homepage**: [liquidshadow.pugcorp.online](https://liquidshadow.pugcorp.online/)
+- **npm**: [@precisionutilityguild/liquid-shadow](https://www.npmjs.com/package/@precisionutilityguild/liquid-shadow)
+- **GitHub**: [PrecisionUtilityGuild/liquid-shadow](https://github.com/PrecisionUtilityGuild/liquid-shadow)
+- **Changelog**: [CHANGELOG.md](./CHANGELOG.md)
 
 ---
 
 <p align="center">
-  <i>Powered by <b>SQLite FTS5</b>, <b>SWC</b>, and <b>Precision Intelligence</b>.</i><br>
+  Built on <b>SQLite FTS5</b> · <b>SWC</b> · <b>Tree-sitter</b> · <b>@xenova/transformers</b><br>
+  <i>Precision Utility Guild — making agents smarter, not louder.</i>
+</p>