docs: rewrite README for cross-language code intelligence positioning

sunilp · sunilp · commit 85395d8bb412 · 2026-05-12T10:11:52.000+05:30
diff --git a/README.md b/README.md
@@ -11,10 +11,10 @@
 
 # jam
 
-**The developer-first AI CLI.** Cross-language code intelligence from your terminal.
+**Cross-language code intelligence for polyglot codebases.**
 
-Trace call graphs across Java, SQL, Python, and TypeScript. Impact analysis.
-AI-powered agentic execution. Works with Copilot & Gemini. Windows, macOS, Linux.
+Trace call graphs and column-level impact across Java, SQL, Python, and TypeScript.
+From your terminal — or as an MCP server for any AI agent.
 
 [![CI](https://github.com/sunilp/jam-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/sunilp/jam-cli/actions/workflows/ci.yml)
 [![npm](https://img.shields.io/npm/v/@sunilp-org/jam-cli.svg)](https://www.npmjs.com/package/@sunilp-org/jam-cli)
@@ -24,206 +24,83 @@ AI-powered agentic execution. Works with Copilot & Gemini. Windows, macOS, Linux
 
 </div>
 
-<div align="center">
-  <img src="docs/assets/demo.svg" alt="jam CLI — trace, git wtf, agent" width="720">
-</div>
-
 ---
 
-## What Jam Does
+## The pain jam solves
 
-Jam isn't a generic AI assistant. It's the senior dev who's seen everything — direct, opinionated, and warm. Every message, error, and prompt speaks with the same voice: concise, specific, developer-aligned.
-
-- 🔍 **Call graph tracing** — trace any symbol's callers, callees, and upstream chain across languages
-- 💥 **Impact analysis** — "if I change this, what breaks?" with column-level SQL dependency tracking
-- 🤖 **Agentic execution** — `jam go` (interactive) and `jam run` (one-shot) decompose tasks into parallel subtasks
-- 💬 **AI chat & ask** — streaming responses, multi-turn sessions, stdin/pipe support
-- 🩹 **Patch workflow** — generate diffs, validate, preview, apply with confirmation
-- 📊 **Code intelligence** — explain files, search code, review diffs, generate Mermaid diagrams
-- 🔧 **Git toolkit** — `wtf` explains state, `undo` reverses mistakes, `standup` shows your work
-- ✅ **Verification** — scan for secrets, lint, type-check before you commit
-- 🧰 **19 zero-LLM utilities** — `ports`, `stats`, `deps`, `todo`, `hash`, `json`, `env`, and more
-- 🔌 **Any provider** — Copilot, Gemini, Ollama, OpenAI, Anthropic, Groq — or bring your own
-- 🏠 **Local-first** — your code never leaves your machine unless you choose a remote provider
-- 🖥️ **Cross-platform** — Windows (PowerShell, cmd), macOS, Linux
-- 🔗 **MCP + plugins** — connect to Model Context Protocol servers, drop in custom commands
-
----
-
-## Install
+You're about to drop the `legacy_id` column from `customer`. Your codebase has Java services, Python ETL jobs, raw SQL stored procs, and a TypeScript frontend. Your AI agent searches for the column name and finds 3 references. Are there really only 3? Or did the agent miss the JPA `@Column(name="legacy_id")` mapping, the MyBatis XML alias, the SQLAlchemy column class, and the stored procedure that joins on it?
 
 ```bash
-# npm
-npm install -g @sunilp-org/jam-cli
-
-# Homebrew
-brew tap sunilp/tap && brew install jam-cli
-
-# Try without installing
-npx @sunilp-org/jam-cli doctor
+jam impact customer.legacy_id
 ```
 
-Jam auto-detects the best available AI provider — **no API keys needed** if you have Copilot or Gemini:
-
-| Priority | Provider | Setup |
-|----------|----------|-------|
-| 1 | **GitHub Copilot** | VSCode extension — zero config |
-| 2 | **Gemini Code Assist** | VSCode extension — zero config |
-| 3 | **Anthropic** | `export ANTHROPIC_API_KEY=sk-ant-...` |
-| 4 | **OpenAI** | `export OPENAI_API_KEY=sk-...` |
-| 5 | **Ollama** (default) | `ollama serve` + `ollama pull llama3.2` |
-
-```bash
-jam doctor           # verify everything works
-jam models list      # see available models
-jam models set gpt-4o  # set your preferred model
-```
-
----
-
-## Cookbook
-
-### Ask & Chat
-
-```bash
-jam ask "explain the builder pattern in Go"
-
-# pipe anything
-cat schema.sql | jam ask "what tables have no foreign keys?"
-git log --since="1 week" -p | jam ask "summarize this week's changes"
-
-# interactive chat with history
-jam chat
 ```
-
-### Agent Engine
-
-```bash
-# interactive agent console — reads, writes, runs commands
-jam go
-jam> add retry logic to the HTTP client with exponential backoff
-
-# one-shot autonomous task
-jam run "add input validation to all API endpoints" --yes
-
-# fully autonomous with parallel workers
-jam run "refactor auth module into separate files" --auto --workers 4
+customer.legacy_id
+├─ Java (5 callers)
+│  ├─ CustomerRepository.findByLegacyId       src/main/java/.../CustomerRepository.java:42
+│  ├─ CustomerService.migrate (uses #1)       src/main/java/.../CustomerService.java:118
+│  └─ ... 3 more
+├─ Python (2 callers)
+│  ├─ etl.transform_customers                 etl/transforms.py:67
+│  └─ migrations/0042_drop_column.py          (drops the column ← intended)
+├─ SQL (3 callers)
+│  ├─ sp_reconcile_customers (stored proc)    db/procs/sp_reconcile_customers.sql:12
+│  ├─ vw_customer_audit (view)                db/views/vw_customer_audit.sql:8
+│  └─ trigger_customer_audit                  db/triggers/trigger_customer_audit.sql:5
+└─ TypeScript (1 caller)
+   └─ getCustomerLegacy                       web/src/api/customer.ts:23
+
+⚠ Risk: HIGH — 11 sites across 4 languages depend on this column.
 ```
 
-### Code Intelligence
+That's the value. Run it before the change, not after CI breaks.
 
-```bash
-# trace a function's call graph
-jam trace createProvider
-jam trace updateBalance --impact       # what breaks if this changes?
-jam trace handleRequest --mermaid      # output as Mermaid diagram
-jam trace PROC_PAYMENT --depth 8       # deeper upstream chain
-
-# explain any file
-jam explain src/auth/middleware.ts
+## What jam does
 
-# search with AI understanding
-jam search "where is the rate limiter configured?"
+- **`jam trace <symbol>`** — call graph in any direction (callers, callees, both) across languages
+- **`jam impact <symbol>`** — what breaks if this symbol or column changes
+- **`jam diagram`** — Mermaid diagrams for architecture or call flow
+- **`jam search`** / **`jam deps`** — symbol search and dependency analysis
+- **`jam mcp serve`** *(Phase 2, coming)* — expose all of the above as an MCP server, so Claude Code, Cursor, Aider, and Goose can call into jam's polyglot intelligence
+- Plus a handful of zero-LLM developer utilities: `ports`, `stats`, `hash`, `json`, `env`, `dup`, `http`, `todo`, `git wtf`, `git undo`, `git standup`, and more
 
-# generate architecture diagram from code
-jam diagram
-```
+## What jam is **not**
 
-### Git Toolkit
+- Not an AI coding agent. Use Claude Code, Cursor, or Aider for "write this feature."
+- Not a chat tool. Use the official Anthropic, OpenAI, or Google CLIs for that.
+- Not a generic terminal AI. jam answers one question well: *"if I change this, what breaks across my stack?"*
 
-```bash
-jam git wtf          # "3 files staged, 2 conflicts, 1 stash. Here's what happened..."
-jam git undo         # undo last commit, last stash, or last merge
-jam git standup      # your commits from the last 3 days
-jam git cleanup      # preview and delete merged branches
-jam git oops         # fix common mistakes (wrong branch, bad commit message)
-```
-
-### Dev Utilities (zero LLM)
-
-```bash
-jam stats            # LOC, languages, complexity hotspots
-jam deps             # import dependency graph
-jam todo             # find all TODO/FIXME/HACK comments
-jam verify           # pre-commit checks: secrets, lint, types
-jam ports            # what's listening on which port
-jam env              # environment variable diff between shells
-jam hash <file>      # MD5/SHA1/SHA256 of any file
-jam json <file>      # validate, format, query JSON
-jam recent           # recently modified files
-jam convert 5kg lb   # unit conversions
-jam http GET /users  # quick HTTP requests
-jam pack             # analyze npm/pip/cargo package size
-```
-
-### Patch & Review
+## Install
 
 ```bash
-# AI-powered diff summary
-jam diff
-
-# code review with risk assessment
-jam review
-
-# generate and apply a patch
-jam patch "add error handling to the database module"
-
-# auto-generate commit message matching your project's convention
-jam commit
-```
-
----
-
-## VSCode Extension
-
-[Install from Marketplace](https://marketplace.visualstudio.com/items?itemName=sunilp.jam-cli-vscode)
-
-- All commands in the Command Palette
-- `@jam` chat participant in GitHub Copilot Chat
-- TODO tree in the sidebar with click-to-navigate
-- **Copilot or Gemini** auto-detected — zero configuration, no API keys
-- Status bar indicator shows connection state
-- Keeps jam-cli updated automatically
-
----
+# npm
+npm install -g @sunilp-org/jam-cli
 
-## Configuration
+# Homebrew
+brew tap sunilp/tap && brew install jam-cli
 
-```bash
-jam init              # interactive setup wizard
-jam config show       # show resolved config
+# Try without installing
+npx @sunilp-org/jam-cli doctor
 ```
 
-```json
-// .jamrc (per-project)
-{
-  "defaultProfile": "work",
-  "profiles": {
-    "work": { "provider": "anthropic", "model": "claude-sonnet-4-20250514" },
-    "local": { "provider": "ollama", "model": "llama3.2" }
-  }
-}
-```
+## Quickstart
 
 ```bash
-jam ask "hello" --profile work     # use Anthropic
-jam ask "hello" --profile local    # use Ollama
+jam doctor                       # check your environment
+jam trace getUserById            # who calls / what does it call
+jam impact users.email           # cross-language column impact
+jam diagram --type architecture  # Mermaid architecture diagram
 ```
 
-Supports HTTP proxy (`HTTP_PROXY`), custom CA certificates (`tlsCaPath`), configurable timeouts, MCP servers, and plugin loading. [Full configuration docs →](https://jam.sunilprakash.com)
-
----
-
-## Links
+## Status
 
-- 📖 [Documentation](https://jam.sunilprakash.com)
-- 🧩 [VSCode Extension](https://marketplace.visualstudio.com/items?itemName=sunilp.jam-cli-vscode)
-- 🍺 [Homebrew Tap](https://github.com/sunilp/homebrew-tap)
-- 🐛 [Issues](https://github.com/sunilp/jam-cli/issues)
+- **v0.12.0** (current) — Sharp pivot from generic AI CLI to cross-language code intelligence. AI-assistant features (ask/chat/run/go and friends) archived to [`archive/ai-suite`](https://github.com/sunilp/jam-cli/tree/archive/ai-suite).
+- **v0.13** (next) — `jam mcp serve` stdio MCP server. Plug jam into Claude Code / Cursor / Aider / Goose.
+- **v0.14** (after that) — Deep Java (Spring Data, JPA, MyBatis), Python (SQLAlchemy, Django, Alembic), SQL (multi-dialect, views, triggers, stored procs), and Kotlin support.
 
-## Contributing
+## Looking for ask / chat / run / go?
 
-See [CONTRIBUTING.md](CONTRIBUTING.md). PRs welcome.
+Those commands were removed in v0.12 — they competed with Claude Code without doing anything Claude Code doesn't already do better. The code lives on the [`archive/ai-suite`](https://github.com/sunilp/jam-cli/tree/archive/ai-suite) branch. A future release may revive AI features, but only ones that ride on top of the cross-language graph (impact-aware migration plans, PR-tailored impact summaries, etc.) — not generic chat.
 
 ## License
 
