skannr 0.2.3 → 0.2.4

package/ARCHITECTURE.md

@@ -0,0 +1,229 @@
+Skannr: Architecture and Design Decisions
+
+Overview
+
+Skannr is a CLI tool, MCP server, and library that helps developers and AI assistants understand codebases without reading every file. It scans a project, generates compressed structural skeletons of the most relevant files, and returns them ranked by relevance to a natural language question. The output is 96.5% smaller than raw source while retaining all architectural information.
+
+The tool also includes risk analysis (quantifying the downstream impact of a code change) and guard (AI code review against team rules with auto-fix capability).
+
+Core Problem
+
+AI coding assistants are limited by context windows. A typical repo has thousands of files. You cannot paste them all. The assistant sees only what you show it, and guesses the rest.
+
+Existing approaches either dump full files (expensive, noisy) or do keyword search (misses architecturally central files that do not mention the search term directly). Neither approach understands the structural relationships between files.
+
+Skannr solves this by combining three ranking signals with structural compression, so the AI gets the right files in the right format at minimal token cost.
+
+System Architecture
+
+The pipeline is linear and stateless. Each stage takes input from the previous stage and produces output for the next. There is no shared mutable state.
+
+Input (question + root path)
+  > File Scanner (discovers all source files)
+  > Ranker (scores files by relevance using hybrid retrieval)
+  > Skeletonizer (strips function bodies, keeps signatures and types)
+  > Formatter (outputs human text, markdown, or JSON)
+
+Each stage is a separate module. They communicate through typed interfaces, not through side effects.
+
+File Layout
+
+src/
+  cli.ts              Command registration (Commander.js, subcommands)
+  index.ts            Library entry point, orchestrates the pipeline
+  scanner.ts          File discovery with gitignore awareness
+  ranker.ts           Basic keyword relevance scoring
+  ranker-enhanced.ts  Hybrid ranking with dependency graph analysis
+  skeletonizer.ts     Routes files to the correct language adapter
+  formatter.ts        Output formatting (human, markdown, JSON)
+  blast-radius.ts     Risk analysis (diff parsing, graph traversal, scoring)
+  guard/              AI code review module (schema, provider, fix applier)
+  languages/          Language adapters (TypeScript via ts-morph, others via WASM)
+  mcp-server.ts       MCP tool registration for AI assistant integration
+  types.ts            Shared type definitions
+
+Design Decisions
+
+1. Hybrid Retrieval over Pure Keyword Search
+
+Decision: Score files using three signals combined, not just keyword matching.
+
+The three signals:
+  Lexical: keyword frequency in file path and content, with synonym expansion
+  Structural: export density, import relevance, symbol count
+  Dependency graph: how many other files import this file (centrality)
+
+Why: A file named utils.ts might contain the most architecturally important auth logic but never mention the word "auth" in its filename. Pure keyword search misses it. Dependency centrality catches it because everything imports it.
+
+The weights are: lexical 50%, structural 20%, enhanced score 30%, with a dependency boost of 15% blended in. These were tuned empirically against large TypeScript monorepos.
+
+2. AST Skeleton Generation over Summarization
+
+Decision: Generate skeletons by stripping function bodies from the AST, not by asking an LLM to summarize.
+
+Why:
+  Deterministic (same input always produces same output)
+  Fast (milliseconds, not seconds)
+  Free (no API call)
+  Lossless for architecture (all types, signatures, imports, class hierarchies preserved)
+  Only lossy for implementation details (function bodies replaced with a placeholder)
+
+The TypeScript adapter uses ts-morph (a TypeScript compiler API wrapper) which gives perfect AST access. For Python, Go, Rust, and Java, the tool uses web-tree-sitter (WASM compiled grammars) which gives equivalent structural parsing without requiring native C++ compilation.
+
+3. WASM over Native Tree-sitter
+
+Decision: Ship tree-sitter grammars as WASM files instead of native bindings.
+
+Why: Native tree-sitter requires a C++ compiler (Visual Studio on Windows, Xcode on Mac). Most JavaScript developers do not have these installed. The npm install would fail for the majority of users.
+
+WASM grammars are platform-independent. They run everywhere Node.js runs. The tradeoff is slightly slower parsing (roughly 2x), but since we only parse files the ranker already selected as relevant (typically 5-10 files), the total time remains under 2 seconds.
+
+The WASM files add 2MB to the package. This is acceptable because it eliminates a class of installation failures entirely.
+
+4. File-level Dependency Graph (not Symbol-level)
+
+Decision: Track dependencies at file granularity (file A imports file B) not at symbol granularity (function X calls function Y).
+
+Why: Symbol-level call graphs require type resolution, which in turn requires a full project compilation context. TypeScript's type checker can do this but only for TS/JS. Python, Go, Rust, and Java would each need their own type resolver. The engineering cost is disproportionate to the accuracy gain for the primary use case (ranking files by relevance).
+
+File-level import graphs are trivially extractable from any language via regex or AST import node detection. They provide sufficient signal for ranking and risk analysis.
+
+This is documented as a stated limitation. Symbol-level resolution is planned for a future version.
+
+5. Deterministic Risk Scoring over LLM-based Assessment
+
+Decision: Compute risk as a weighted formula with named constants, not by asking an LLM "how risky is this."
+
+The formula:
+  risk = 2.5 * (affected files / total files)
+       + 2.5 * (average centrality of affected files)
+       + 3.5 * (fraction of affected files with no test coverage)
+       + 1.5 * (max hop depth reached / max hops configured)
+
+Why:
+  Deterministic: same diff always produces same score
+  Fast: runs in under 2 seconds with zero API calls
+  CI-gateable: you can block merges on a number, not on an LLM's mood
+  Transparent: the formula is visible, the weights are named constants, the inputs are shown
+  Reproducible: another developer running the same command gets the same result
+
+The untested ratio has the highest weight (3.5 out of 10) because untested downstream code is the strongest signal that a merge is risky. This weighting was a deliberate choice: the number that should most influence whether someone trusts a merge is whether the things it might break have tests.
+
+6. Guard: Structured JSON Contract over Text Parsing
+
+Decision: Enforce schema-validated JSON responses from the LLM. Never parse free text looking for status keywords.
+
+Why: This is a direct response to a known failure mode. Other tools in this space parse LLM responses as raw text, looking for a specific line (like "STATUS: PASSED") at a fixed position. This breaks when providers prepend acknowledgment text ("Sure! Here's my analysis:") before the actual response.
+
+Skannr Guard uses:
+  Gemini API's responseMimeType: 'application/json' (forces JSON output)
+  OpenAI's response_format: { type: 'json_object' } (same)
+  Zod schema validation on every response before using it
+  A JSON extraction fallback that finds the first { to last } regardless of surrounding text
+  One retry with an explicit correction prompt on validation failure
+
+The violation object has a fixed schema. The fixable field is set by the rule definition, not by the LLM. This prevents the LLM from deciding on its own what it can auto-fix.
+
+7. Guard: CLI Auto-detection over Mandatory API Keys
+
+Decision: If the user has Claude Code, Gemini CLI, Kiro, or Ollama installed, use it directly. Do not require a separate API key.
+
+Detection priority:
+  1. claude CLI (uses existing Claude Code authenticated session)
+  2. gemini CLI (uses existing Gemini authenticated session)
+  3. kiro-cli (uses existing Kiro session)
+  4. ollama (local, no auth needed)
+  5. Gemini API (needs GEMINI_API_KEY)
+  6. OpenAI API (needs OPENAI_API_KEY)
+
+Why: The biggest friction in AI-powered dev tools is API key setup. If someone already has a coding agent installed and authenticated, they should not need to configure anything else. The tool should use what is already there.
+
+This mirrors how GGA (gentleman-guardian-angel) works: it shells out to existing CLI tools rather than making its own API calls. The difference is that Skannr Guard also supports direct API calls as a fallback for users who do not have any CLI tool installed.
+
+8. Subcommands over Flags
+
+Decision: Structure the CLI as subcommands (skannr risk, skannr guard, skannr agent) rather than a single command with 20+ flags.
+
+Why: The original CLI had --question, --root, --report, --cache-clear, --cache-stats, --diff, --watch, --mcp, --telemetry-on, --telemetry-off all on one command. Users had to read --help every time to find which flags go together.
+
+Subcommands group related functionality. Each subcommand has only the flags relevant to it. The most common operation (asking a question) takes a bare positional argument:
+
+  skannr "how does auth work?"
+
+No flag needed. The tool should be typeable from memory after seeing it once.
+
+Backward compatibility: all old flags still work. The new commands are aliases, not replacements.
+
+9. Built-in Default Rules over Mandatory Configuration
+
+Decision: Guard works without any rules file. Built-in defaults cover universal best practices.
+
+Default rules: no-any-type, no-console-log, error-handling, no-hardcoded-secrets, function-complexity, unused-imports.
+
+Why: Every extra file a tool requires before it works is friction that prevents adoption. If the user has to create .skannr/rules.json before they can try the tool, most will not try it.
+
+The custom rules file is optional. When present, it overrides defaults. Teams that need domain-specific rules can add them. Everyone else gets reasonable defaults out of the box.
+
+10. MCP as the Integration Layer
+
+Decision: Expose all features as MCP tools (scan_codebase, blast_radius, guard_review) over stdio.
+
+Why: MCP (Model Context Protocol) is the emerging standard for giving AI assistants access to external tools. One protocol works with Cursor, Claude Code, Gemini CLI, VS Code Copilot, and any future MCP-compatible tool.
+
+The alternative would be building separate plugins for each editor. MCP avoids that entirely. One implementation, every tool.
+
+The MCP server and CLI share the same internal functions. There is no code duplication between the two surfaces.
+
+Technology Choices
+
+TypeScript: The project itself is written in TypeScript. This aligns with the primary audience (JavaScript/TypeScript developers) and allows dogfooding the TypeScript adapter on the project itself.
+
+Commander.js: CLI framework. Mature, well-typed, supports subcommands and positional arguments. Already a standard choice in the Node.js ecosystem.
+
+ts-morph: TypeScript/JavaScript AST access. Wraps the TypeScript compiler API with a cleaner interface. Gives perfect type information, symbol extraction, and skeleton generation for TS/JS files.
+
+web-tree-sitter: Multi-language parsing via WASM. No native compilation. Supports 40+ languages via grammar files. We bundle Python, Go, Rust, Java (2MB total).
+
+parse-diff: Unified diff parsing. Small focused library, well-maintained, has types. Used by blast-radius to extract changed files and line ranges from git diffs.
+
+zod: Schema validation for Guard's rules file and LLM response contract. Runtime type checking that integrates with TypeScript's type system.
+
+@modelcontextprotocol/sdk: Official MCP SDK. Handles the stdio transport protocol so we only implement tool logic.
+
+@google/generative-ai: Gemini SDK for Guard's direct API calls and the interactive agent mode.
+
+What is Not Included (and Why)
+
+No vector embeddings: Skannr does not use embeddings or a vector store. The hybrid ranking (lexical + structural + graph centrality) is sufficient for finding relevant files. Embeddings would add a model dependency, increase latency, and require a build step to generate the index.
+
+No persistent index: Each run scans fresh. The cache is keyed by file hash (MD5) and invalidates automatically when files change. A persistent index would be faster for repeated queries on unchanged codebases, but adds complexity around invalidation and stale results.
+
+No UI: Skannr is a CLI tool and MCP server. There is no web dashboard or VS Code extension. The landing page is marketing only. The tool's value is in the terminal and in the AI assistant context window.
+
+No custom language grammars: Adding a new language means adding one config entry (which AST node types represent functions, classes, imports) and one WASM grammar file. We do not write custom parsers per language.
+
+Testing Approach
+
+Jest with ts-jest. Tests are in a flat tests/ directory, named *.test.ts.
+
+Test patterns:
+  Temp directories with real files (not mocks of the filesystem)
+  beforeEach creates fixtures, afterEach cleans up
+  WASM dependencies mocked in tests to avoid loading .wasm files in CI
+  Integration tests run git commands in real temp repos
+
+Coverage areas:
+  Schema validation (valid input accepted, invalid input rejected)
+  Graph traversal (correct hop distances, cycle handling, max-hop limits)
+  Risk scoring (known input/output pairs)
+  Fix scoping (never touches non-fixable violations)
+  Hook installation (append-safe, idempotent, clean uninstall)
+
+Performance Characteristics
+
+Typical query: 1-2 seconds end to end on a 2000-file TypeScript repo
+Risk analysis: under 2 seconds (no API call)
+Guard review: 5-15 seconds (LLM round-trip)
+Package size: 450KB compressed, 2.8MB unpacked
+Memory: under 100MB for typical repos
+No background processes: runs, outputs, exits

package/README.md

@@ -1,260 +1,209 @@
-# Skannr
-
-A CLI tool and MCP server that helps AI agents understand **any codebase**.
-It scans files, generates compressed structural "skeletons", and ranks results
-using hybrid retrieval — reducing token usage by ~96% vs full file scans.
-
-## How It Works
-
-1. You point it at any repo with `--root /path/to/repo`
-2. It auto-detects the language (TypeScript, JavaScript, Python, or generic fallback)
-3. It auto-discovers your project's modules from the folder structure
-4. For your question, it ranks the most relevant files using lexical + structural + dependency-graph analysis
-5. It strips function bodies from files (keeping types, signatures, imports)
-6. Returns compact skeletons an AI can reason over without blowing the context window
-
-## Install
-
-```bash
-npm install -g skannr
-```
-
-## Usage
-
-### CLI
-
-```bash
-# Basic
-skannr --question "how does authentication work?" --root /path/to/any/repo
-
-# Limit results
-skannr --question "database connection setup" --root . --limit 5
-
-# Focus on specific modules (auto-discovered if not specified)
-skannr --question "permission checks" --root . --modules auth,middleware
-
-# Force language
-skannr --question "class structure" --root /path/to/python/project --lang python
-
-# Interactive agent mode
-skannr-agent --root /path/to/repo
-
-# Cache management
-skannr --cache-stats
-skannr --cache-clear
-skannr --question "..." --skip-cache
-
-# Output: human (default), markdown, or json
-skannr --question "..." --root . --format markdown
-skannr --question "..." --root . --format json
-
-# Repository health report (JSON on stdout)
-skannr --report --root .
-
-# Re-run analysis when files change (debounced; uses fresh analysis each pass)
-skannr --question "..." --root . --watch
-```
-
-### Watch mode (`--watch`)
-
-Use `--watch` when you want Skannr to stay running and **re-analyze after relevant file changes** (large repos you edit often). Changes under common build/vendor dirs are ignored (`node_modules`, `.git`, `dist`, etc.). Press **Ctrl+C** to stop.
-
-Each run bypasses the analysis cache so results reflect the tree as it is now.
-
-### Anonymous telemetry (opt-in)
-
-Telemetry is **off unless you enable it** (or accept deferred opt-in — see below). It sends **only which CLI flags were used** — never your question text, file paths, or code.
-
-- Enable: `skannr --telemetry-on`
-- Disable: `skannr --telemetry-off`
-
-Settings are stored under `~/.skannr/config.json`. The first time you run an analyze command with no config yet, Skannr may show a short notice; you can opt in or out anytime with the flags above.
-
-If you take no action, telemetry may turn on automatically **after 7 days** from that notice unless you explicitly disabled it with `--telemetry-off`.
-
-## MCP Server
-
-`skannr` ships with a built-in MCP server. One-time setup per AI tool:
-
-### Cursor
-
-`~/.cursor/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "skannr": {
-      "command": "npx",
-      "args": ["-y", "skannr", "--mcp"]
-    }
-  }
-}
-```
-
-### Claude Desktop / Claude Code
-
-`~/Library/Application Support/Claude/claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "skannr": {
-      "command": "npx",
-      "args": ["-y", "skannr", "--mcp"]
-    }
-  }
-}
-```
-
-### Gemini CLI
-
-`~/.gemini/config.json`:
-
-```json
-{
-  "mcpServers": {
-    "skannr": {
-      "command": "npx",
-      "args": ["-y", "skannr", "--mcp"]
-    }
-  }
-}
-```
-
-Alternatively run the dedicated binary: `skannr-mcp` (same stdio server).
-
-## Config File (optional)
-
-Drop a `code-analyzer.config.json` in your repo root:
-
-```json
-{
-  "modules": {
-    "auth": ["src/auth", "lib/auth"],
-    "api": ["src/api", "src/routes"]
-  },
-  "exclude": ["**/generated/**", "**/migrations/**"],
-  "extensions": [".ts", ".js"],
-  "defaultLimit": 10
-}
-```
-
-## Supported Languages
-
-| Language | Skeleton Support |
-|---|---|
-| TypeScript / TSX | Full AST (ts-morph) |
-| JavaScript / JSX | Full AST (ts-morph) |
-| Python | Regex-based (signatures + types) |
-| Others | First 50 lines (generic fallback) |
-
-## Performance
-
-Benchmarked on large TypeScript monorepo:
-
-| Metric | Result |
-|---|---|
-| Token Reduction vs Full Scan | ~96.5% |
-| Token Reduction vs Top-N | ~78.2% |
-| Avg keyword coverage | ~75% |
-| Directory diversity (top-5) | ~80% |
-| Average execution time | ~1.2s |
-
-## Interactive Agent Commands
-
-```
-/help              Show all commands
-/files             List retrieved files
-/symbols <query>   Search for symbols
-/symbol <id>       Get full implementation
-/deps <file>       Show imports for a file
-/refresh           Re-analyze with new context
-/stats             Show mapping statistics
-/exit              Quit
-```
-
-## Blast Radius
-
-Analyze the downstream impact and risk of a code change. Given a git diff,
-blast-radius identifies which files are affected, how central they are in the
-dependency graph, and whether they have test coverage.
-
-**Limitation (v1):** Traversal is computed at file granularity — "file A
-imports file B" — not at function-call level. Function-level resolution is
-planned for a future version.
-
-### CLI
-
-```bash
-# Analyze working tree changes vs HEAD (default)
-skannr blast-radius --root .
-
-# Analyze a specific diff file, 3 hops deep
-skannr blast-radius --root . --diff changes.patch --hops 3
-
-# JSON output for CI pipelines
-skannr blast-radius --root . --json
-```
-
-Sample terminal output:
-
-```
-  Blast Radius Analysis (2-hop traversal)
-  ──────────────────────────────────────────────────
-
-  Risk Score: 5.8/10
-  Risk 5.8/10 (moderate): 1 file(s) changed, 4 downstream affected, 3 untested.
-
-  Changed files:
-    src/auth/session.ts
-
-  Changed symbols:
-    function validateToken (src/auth/session.ts)
-
-  Hop 1 (2 files):
-    src/middleware/auth-guard.ts  centrality=0.85 [NO TEST]
-    src/api/login.ts              centrality=0.60
-
-  Hop 2 (2 files):
-    src/routes/index.ts           centrality=0.45 [NO TEST]
-    src/api/admin.ts              centrality=0.30 [NO TEST]
-
-  Formula inputs:
-    affected_count (normalized): 0.080
-    avg_centrality:              0.550
-    untested_ratio:              0.750
-    hop_spread (normalized):     1.000
-```
-
-### MCP
-
-The `blast_radius` tool is exposed via the same MCP server (`skannr --mcp`).
-
-Input schema:
-
-```json
-{
-  "root": "/path/to/repo",
-  "diff": "<optional unified diff content>",
-  "hops": 2
-}
-```
-
-If `diff` is omitted, the tool runs `git diff HEAD` in the given root.
-The output is the same JSON structure as `skannr blast-radius --json`.
-
-### Risk Score Formula
-
-```
-risk = 2.5 × normalizedAffectedCount
-     + 2.5 × avgCentrality
-     + 3.5 × untestedRatio
-     + 1.5 × normalizedMaxHopSpread
-```
-
-| Input | Range | Meaning |
-|-------|-------|---------|
-| normalizedAffectedCount | 0–1 | Affected files / total project files |
-| avgCentrality | 0–1 | Mean in-degree centrality of affected files |
-| untestedRatio | 0–1 | Fraction of affected files with no test file |
-| normalizedMaxHopSpread | 0–1 | Deepest hop reached / max configured hops |
+# Skannr
+
+A CLI tool and MCP server that helps developers and AI assistants understand any codebase. Scans files, generates compressed structural skeletons, and ranks results using hybrid retrieval. Reduces token usage by 96.5% vs full file reads.
+
+## Install
+
+```bash
+npm install -g skannr
+```
+
+Or use without installing:
+
+```bash
+npx skannr "how does auth work?"
+```
+
+## Usage
+
+### Ask about any codebase
+
+```bash
+skannr "how does authentication work?"
+skannr "database queries" -n 5
+skannr "API endpoints" --json
+skannr "class structure" --lang python
+```
+
+No config needed. Auto-detects language and module structure.
+
+### Risk analysis
+
+Check the downstream impact of your changes before pushing:
+
+```bash
+skannr risk
+skannr risk --json
+skannr risk -n 3
+skannr risk --diff feature.patch
+```
+
+Walks the dependency graph, finds affected files, flags untested code, gives you a 0-10 score. No LLM, no API key, runs in under 2 seconds.
+
+### Guard (AI code review)
+
+Reviews staged changes against coding rules at the symbol level:
+
+```bash
+git add .
+skannr guard
+skannr guard --fix
+skannr guard --fix --dry-run
+skannr guard --pr-mode
+skannr guard --json
+```
+
+Auto-detects your coding agent (Claude, Gemini, Kiro, Ollama). No API key needed if you already have one installed. Works out of the box with built-in rules.
+
+Install as a pre-commit hook:
+
+```bash
+skannr guard install
+skannr guard uninstall
+```
+
+Custom rules (optional):
+
+```json
+// .skannr/rules.json
+{
+  "rules": [
+    {
+      "id": "no-mutations",
+      "description": "Do not mutate function arguments",
+      "severity": "high",
+      "fixable": false,
+      "category": "functional"
+    }
+  ]
+}
+```
+
+### Other commands
+
+```bash
+skannr report          # repo health summary (JSON)
+skannr agent           # interactive exploration mode
+skannr cache stats     # cache hit rate
+skannr cache clear     # wipe cache
+```
+
+## Supported Languages
+
+| Language | Support | Method |
+|---|---|---|
+| TypeScript / TSX | Full AST | ts-morph |
+| JavaScript / JSX | Full AST | ts-morph |
+| Python | Full AST | tree-sitter WASM |
+| Go | Full AST | tree-sitter WASM |
+| Rust | Full AST | tree-sitter WASM |
+| Java | Full AST | tree-sitter WASM |
+| Others | Basic | First 50 lines fallback |
+
+No native build tools required. WASM grammars run everywhere npm runs.
+
+## MCP Server
+
+Exposes three tools: `scan_codebase`, `blast_radius`, `guard_review`.
+
+One-time setup for your AI tool:
+
+```json
+{
+  "mcpServers": {
+    "skannr": {
+      "command": "npx",
+      "args": ["-y", "skannr", "--mcp"]
+    }
+  }
+}
+```
+
+Works with Cursor, Claude Code, Gemini CLI, Kiro, VS Code Copilot, and any MCP-compatible tool.
+
+After setup, just ask your assistant:
+- "How does auth work in this repo?"
+- "Review my staged changes"
+- "What's the risk of my current diff?"
+
+## Risk Score Formula
+
+```
+risk = 2.5 x (affected files / total files)
+     + 2.5 x (avg centrality of affected files)
+     + 3.5 x (% of affected files with no tests)
+     + 1.5 x (max hop reached / max hops configured)
+```
+
+Deterministic. Same diff always produces the same score. CI-gateable:
+
+```bash
+RISK=$(skannr risk --json | jq '.riskScore')
+if [ $(echo "$RISK > 7" | bc -l) -eq 1 ]; then exit 1; fi
+```
+
+## Guard Providers
+
+Guard auto-detects in this order (no config needed):
+
+1. `claude` CLI (uses your existing session)
+2. `gemini` CLI (uses your existing session)
+3. `kiro-cli` (uses your existing session)
+4. `ollama` (local, no auth)
+5. Gemini API (set `GEMINI_API_KEY`)
+6. OpenAI API (set `OPENAI_API_KEY`)
+
+Override with `SKANNR_GUARD_PROVIDER` env var or `.skannr/guard.json`.
+
+## Config File (optional)
+
+```json
+// code-analyzer.config.json (project root)
+{
+  "modules": {
+    "auth": ["src/auth", "lib/auth"],
+    "api": ["src/api", "src/routes"]
+  },
+  "exclude": ["**/generated/**", "**/migrations/**"],
+  "extensions": [".ts", ".js"],
+  "defaultLimit": 10
+}
+```
+
+## Performance
+
+| Metric | Result |
+|---|---|
+| Token reduction vs full scan | 96.5% |
+| Typical query time | 1-2 seconds |
+| Risk analysis | under 2 seconds (no API call) |
+| Guard review | 5-15 seconds (LLM round-trip) |
+| Package size | 450KB compressed |
+
+## Interactive Agent
+
+```bash
+skannr agent
+```
+
+Commands inside the agent:
+
+```
+/files             List retrieved files
+/symbols <query>   Search for symbols
+/symbol <id>       Get full implementation
+/deps <file>       Show imports for a file
+/refresh           Re-analyze with new context
+/stats             Show mapping statistics
+/exit              Quit
+```
+
+Requires `GEMINI_API_KEY` for the interactive agent mode.
+
+## Architecture
+
+See [ARCHITECTURE.md](./ARCHITECTURE.md) for design decisions, technology choices, and the reasoning behind each one.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skannr",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "A universal tool to analyze any codebase and generate semantic skeletons for AI agents",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",