@oxis-dev/tessra 2.14.1 → 2.17.0

package/README.md

@@ -1,9 +1,197 @@
-## License
+# Tessra
+
+Semantic code intelligence engine for AI agents. Tessra indexes your codebase and exposes it to Claude Code (and any MCP-compatible AI) through a local MCP server — giving agents full call graphs, symbol lookup, smart context, and multi-repo awareness without reading raw files.
+
+## Install
+
+```bash
+npm install -g @oxis-dev/tessra
+```
+
+Requires a valid Tessra license. Get one at [oxis.dev/tessra](https://oxis.dev/tessra).
+
+---
+
+## Quick start
+
+```bash
+# 1. Activate your license
+tessra auth <your-license-key>
+
+# 2. Register your project and start the daemon
+tessra repo add . --name myapp
+tessra repo use myapp
+tessra mcp             # starts the MCP server (used by Claude Code)
+```
+
+Add Tessra to your Claude Code MCP config (`~/.claude/claude_desktop_config.json` or `.claude/settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "tessra": {
+      "command": "tessra",
+      "args": ["mcp"]
+    }
+  }
+}
+```
+
+---
+
+## Multi-repo & workspaces
+
+Tessra maintains a **persistent catalog** (`~/.tessra/repos.json`) so you can switch projects without restarting the MCP server.
+
+### Register repos
+
+```bash
+tessra repo add .                        # register CWD (uses directory name)
+tessra repo add /projects/api --name api # register with explicit name
+tessra here                              # auto-detect git root, register + activate
+```
+
+### Switch active repo
+
+```bash
+tessra repo use api                      # activate; triggers live indexing if daemon is running
+tessra repo current                      # print active: "api" or "workspace:stack" or "(none)"
+tessra repo list                         # list all registered repos with status
+tessra repo remove old-svc               # remove from catalog
+```
+
+### Workspaces (multi-repo)
+
+Group repos into a named workspace and activate them all at once:
+
+```bash
+tessra workspace create cbb-stack --repos cbb_express,cbb_admin
+tessra workspace use cbb-stack           # activates both repos; deactivates any single repo
+tessra workspace list
+tessra workspace remove cbb-stack
+```
+
+When a workspace is active, all repos in it are indexed and available to the agent simultaneously.
+
+**XOR rule:** `active_repo` and `active_workspace` are mutually exclusive. Activating one clears the other.
+
+---
+
+## Session scope (multi-repo)
+
+When multiple repos are indexed, each MCP connection automatically resolves a **session scope** so the agent only sees symbols of the active repo — avoiding silent wrong-repo context.
+
+### Scope resolution order
+
+On every `initialize` handshake Tessra resolves the scope in this priority:
 
-Tessra is proprietary software developed by Oxis.
+1. `workspaceRoot` sent by the client (Claude Code / VS Code sends this automatically)
+2. `--workspace <name|path>` flag on `tessra mcp`
+3. `TESSRA_WORKSPACE` environment variable
+4. CWD git root at daemon startup matched against the catalog
+5. No match → error with actionable instructions
 
-Access and use require a valid subscription or license issued by Oxis. Unauthorized use, reproduction, modification, or distribution of this software is strictly prohibited.
+### Cross-repo queries
 
-This repository is not open source.
+All search tools accept an optional `repo` parameter to query a specific repo regardless of session scope:
+
+```
+find("processPayment", repo="payments-api")
+```
+
+For intentional cross-repo lookups use the dedicated tool:
+
+```
+get_cross(symbol="processPayment", from_repo="payments-api")
+```
+
+### Scope info in `tessra doctor`
+
+`tessra doctor` now shows the resolved MCP scope so you can verify what the agent will see before starting a session.
+
+### Startup order (no `--roots` flag)
+
+When `tessra mcp` starts without `--roots`, it resolves context in this order:
+
+1. Active workspace → loads all workspace repos
+2. Active repo → loads that repo
+3. CWD is a git repo → loads it with a warning ("run `tessra here` to register")
+4. None of the above → error with instructions
+
+---
+
+## CLI reference
+
+### Repo management
+
+| Command | Description |
+|---------|-------------|
+| `tessra repo add [path] [--name N]` | Register a repo in the catalog (does not activate) |
+| `tessra repo use <name>` | Activate repo; triggers live indexing if daemon is running |
+| `tessra repo current` | Print active repo or workspace (one line) |
+| `tessra repo list` | List all registered repos with states |
+| `tessra repo remove <name>` | Remove from catalog |
+| `tessra here` | Detect git root from CWD, register if needed, activate |
+
+### Workspace management
+
+| Command | Description |
+|---------|-------------|
+| `tessra workspace create <name> --repos a,b` | Create a named workspace |
+| `tessra workspace use <name>` | Activate workspace (validates all repos first) |
+| `tessra workspace list` | List registered workspaces |
+| `tessra workspace remove <name>` | Remove a workspace |
+
+### Diagnostics
+
+| Command | Description |
+|---------|-------------|
+| `tessra status` | Active repo/workspace with origin + per-repo states |
+| `tessra doctor` | Health check: repos.json, daemon, individual repos (✔ / ⚠ / ✖) |
+
+### Other
+
+| Command | Description |
+|---------|-------------|
+| `tessra auth <key>` | Activate license |
+| `tessra login` | Browser-based login (no key needed) |
+| `tessra mcp [--roots dir1 dir2] [--workspace name\|path]` | Start MCP server (reads catalog if no `--roots`); `--workspace` fuerza el scope de sesión |
+| `tessra stats` | Show indexing stats and token savings |
+| `tessra prompt` | Print the recommended system prompt for agents |
+| `tessra telemetry status\|enable\|disable` | Manage telemetry consent |
+
+---
+
+## MCP tools exposed to the agent
+
+| Tool | Description |
+|------|-------------|
+| `find` | Locate a symbol by name (exact / prefix / partial); acepta `repo?` para override de scope |
+| `get_context` | Working context for a symbol; acepta `repo?` para override de scope |
+| `get_extended` | Extended context including framework extras (Angular template, Flutter binding) |
+| `get_related` | Related symbols up / down / both; acepta `repo?` para override de scope |
+| `trace_origin` | Trace from a symbol to its application root; acepta `repo?` para override de scope |
+| `get_impact` | Symbols affected by changing a target; acepta `repo?` para override de scope |
+| `get_outline` | File structure (signatures + imports only) |
+| `read_lines` | Raw lines by path + line range |
+| `repo_info` | Stats for all active repos |
+| `get_dependencies` | External deps from active repositories |
+| `get_metrics` | Token savings summary |
+| `repo_add` | Register a repo from inside Claude Code |
+| `repo_use` | Switch active repo from inside Claude Code |
+| `repo_list` | List registered repos from inside Claude Code |
+| `repo_current` | Current active repo/workspace |
+| `get_cross` | Lookup a symbol in a specific repo regardless of session scope |
+
+---
+
+## Supported languages
+
+Angular · Django · Flutter/GetX · TypeScript · JavaScript · Python · Rust · Go · Java · Kotlin · C# · PHP · Ruby · SQL · Svelte · Vue · Astro
+
+---
+
+## License
 
-For licensing inquiries, visit https://oxis.dev
+Tessra is proprietary software by [Oxis](https://oxis.dev).
+A valid subscription is required. Visit [oxis.dev/tessra](https://oxis.dev/tessra) for pricing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxis-dev/tessra",
-  "version": "2.14.1",
+  "version": "2.17.0",
   "description": "MCP server for AI coding tools and agents. Provides semantic codebase context for Cursor, Claude Code, Codex, Copilot, Antigravity, and CLI workflows without requiring full file uploads.",
   "license": "UNLICENSED",
   "author": {