docs: document new commands and refresh skill file

.claude/skills/codesearch/SKILL.md

@@ -3,7 +3,7 @@ name: codesearch
 description: Semantic code search using ML embeddings and AST analysis. Replaces built-in search tools for intent-based code exploration. Use when the user asks to find code by describing what it does, understand code relationships, or explore a codebase semantically.
 metadata:
   author: ArtemisMucaj
-  version: "0.6.0"
+  version: "0.7.0"
 compatibility: Requires the codesearch binary installed and a repository indexed with `codesearch index`.
 ---
 
@@ -21,6 +21,9 @@ Invoke this skill **immediately** when:
 - You need to discover code related to a **concept** rather than an exact string
 - User asks about **blast radius** or **impact** of changing a function/symbol
 - User asks **who calls** a function or **what does a function call** (symbol context)
+- User asks for an **explanation** of a symbol's full call flow or business purpose (`explain`)
+- User asks about the **architectural structure** of a repo — modules, clusters, entry-point features
+- User asks **which files one repository uses** from another (cross-repo dependencies)
 
 ## When to Use Built-in Tools Instead
 
@@ -117,32 +120,105 @@ Codesearch uses Tree-sitter to extract and index these code constructs:
 
 ## Call Graph Analysis
 
-Once a repository is indexed, the call graph is available for two complementary commands.
+Once a repository is indexed, the call graph powers several complementary commands.
 
 ### Impact Analysis — blast radius of a change
 
 ```shell
-# Who breaks if `authenticate` changes? (default depth: 5 hops)
+# Who breaks if `authenticate` changes? (BFS over the call graph)
 codesearch impact authenticate
 
-# Limit to 2 hops
-codesearch impact authenticate --depth 2
-
 # Restrict to one repository; JSON output for scripts
 codesearch impact authenticate --repository my-api --format json
 ```
 
-### Symbol Context — 360-degree callers + callees
+### Symbol Context — full caller/callee call-chain tree
 
 ```shell
 # Who calls `authenticate`, and what does it call?
 codesearch context authenticate
 
-# Limit results per direction
-codesearch context authenticate --limit 10
+# Restrict to one repository; JSON output
+codesearch context authenticate --repository my-api --format json
+```
+
+### Matching symbols by regex
+
+`impact`, `context`, and `explain` resolve the symbol name with a substring match
+by default (`load` matches any fully-qualified name containing `load`). Pass
+`--regex` to supply your own POSIX pattern with explicit anchoring:
+
+```shell
+codesearch impact "^MyNs/.*Service#get$" --regex
+codesearch context ".*Repository.*" --regex
+```
+
+### Explain — LLM-generated call-flow explanation
+
+Produces a structured natural-language description of a symbol's purpose, data/control
+flow, business feature, and key dependencies. Requires `ANTHROPIC_API_KEY` (default
+backend) or an OpenAI-compatible endpoint.
+
+```shell
+# Explain a symbol using the default Anthropic backend
+codesearch explain authenticate
+
+# Use an OpenAI-compatible backend (e.g. LM Studio)
+codesearch explain authenticate --llm open-ai
+
+# Also dump every analyzed symbol's source chunk
+codesearch explain authenticate --dump-symbols
+```
+
+## Architecture & Dependency Analysis
+
+These commands operate on the file- and repository-level dependency graph built during
+indexing. They help answer "how is this codebase structured?" rather than "where is X?".
+
+### Execution Features — entry-point flows ranked by criticality
+
+```shell
+# List the most critical entry-point features in a repository
+codesearch features list my-repo
+
+# Limit the number of features and emit JSON
+codesearch features list my-repo --limit 10 --format json
+
+# Inspect a single feature by its entry-point symbol
+codesearch features get handle_request
+
+# Which features are impacted by changing one or more symbols?
+codesearch features impacted authenticate hash_password
+```
+
+### Clusters — architectural modules (Leiden community detection)
+
+```shell
+# List tightly-coupled file clusters (architectural modules)
+codesearch clusters list my-repo
+
+# Which cluster does a given file belong to?
+codesearch clusters get src/api/auth.rs my-repo
 
-# JSON output
-codesearch context authenticate --format json
+# Print a high-level Markdown architecture overview table
+codesearch clusters overview my-repo
+```
+
+### Uses — cross-repository file dependencies
+
+```shell
+# List the files in repo `web` that use files from repo `core`
+codesearch uses web core
+```
+
+## Interactive TUI
+
+For exploratory sessions a full-screen terminal UI bundles search, impact, and context:
+
+```shell
+codesearch tui                       # open in search mode
+codesearch tui --mode impact         # open in impact mode
+codesearch tui --query "auth flow"   # pre-populate and dispatch a query
 ```
 
 ## Repository Management
@@ -200,4 +276,4 @@ codesearch --no-rerank search "query"
 
 ## Keywords
 
-semantic search, hybrid search, code search, natural language search, find code, explore codebase, code understanding, intent search, AST analysis, embeddings, code discovery, code exploration, BM25, keyword search, RRF, reciprocal rank fusion, call graph, impact analysis, blast radius, symbol context, callers, callees, dependency analysis
+semantic search, hybrid search, code search, natural language search, find code, explore codebase, code understanding, intent search, AST analysis, embeddings, code discovery, code exploration, BM25, keyword search, RRF, reciprocal rank fusion, call graph, impact analysis, blast radius, symbol context, callers, callees, dependency analysis, explain, call flow, execution features, criticality, clusters, architecture overview, Leiden, module detection, cross-repository dependencies, uses, regex symbol match

AGENTS.md

@@ -76,7 +76,12 @@ The codebase follows **Domain-Driven Design (DDD)** with a strict **Ports & Adap
 | RRF result fusion | `src/application/use_cases/rrf_fuse.rs` |
 | Impact (blast radius) analysis | `src/application/use_cases/impact_analysis.rs` |
 | Symbol context (callers/callees) | `src/application/use_cases/symbol_context.rs` |
-| Call graph extraction | `src/application/use_cases/call_graph.rs` |
+| Call graph extraction & relationship queries | `src/application/use_cases/call_graph.rs` |
+| LLM explanation of a symbol's call flow | `src/application/use_cases/explain.rs` |
+| Execution features + criticality scoring | `src/application/use_cases/execution_features.rs` |
+| Architectural cluster detection (Leiden) | `src/application/use_cases/cluster_detection.rs` |
+| File / cross-repo relationship graph (`uses`) | `src/application/use_cases/file_relationship.rs` |
+| Source snippet lookup | `src/application/use_cases/snippet_lookup.rs` |
 | List / delete repositories | `src/application/use_cases/{list,delete}_repository.rs` |
 
 ### Dependency Injection

README.md

@@ -62,19 +62,31 @@ codesearch search "function that handles authentication"
 # Show indexed repositories
 codesearch list
 
+# Show indexing statistics
+codesearch stats
+
 # Delete a repository by name or path
 codesearch delete my-repo
 codesearch delete /path/to/repo
 
 # Show the blast radius of a symbol change (BFS over call graph)
 codesearch impact authenticate
 
-# Show 360-degree caller/callee context for a symbol
+# Show full caller/callee call-chain context for a symbol
 codesearch context authenticate
 
 # LLM-powered explanation of a symbol's full call flow and business purpose
 codesearch explain authenticate
 
+# Rank entry-point execution features by criticality
+codesearch features list my-repo
+
+# Detect architectural clusters in the file dependency graph
+codesearch clusters list my-repo
+
+# List the files one repository uses from another
+codesearch uses web core
+
 # Launch the interactive TUI (search, impact, and context in one terminal UI)
 codesearch tui
 
@@ -149,7 +161,7 @@ CodeSearch builds a call graph during indexing and exposes two commands to query
 
 ### Impact Analysis
 
-Shows every symbol that would be affected (transitively) if a given symbol changes. Uses BFS over the call graph up to a configurable depth.
+Shows every symbol that would be affected (transitively) if a given symbol changes. Uses BFS over the call graph, grouping affected symbols by hop depth.
 
 ```bash
 # Show what breaks if `authenticate` changes
@@ -213,6 +225,11 @@ process_request [call]  src/router.rs:10
 |------|---------|---------|-------------|
 | `-r, --repository` | both | (none) | Restrict to a specific repository |
 | `-F, --format` | both | `text` | Output format: `text`, `json`, or `vimgrep` |
+| `--regex` | both | off | Treat the symbol as an explicit POSIX regex (no auto-wrapping) |
+
+> **Symbol matching:** By default the symbol argument is matched as a substring
+> (`load` matches any fully-qualified name containing `load`). Pass `--regex` to
+> supply your own anchored pattern, e.g. `codesearch impact "^MyNs/.*Service#get$" --regex`.
 
 > **Note:** Call graph data is populated during `codesearch index`. Re-index after code changes to keep the graph up to date.
 
@@ -239,6 +256,57 @@ codesearch tui --query "authentication"
 
 See [Getting Started — Launch the Interactive TUI](docs/features/getting-started.md#launch-the-interactive-tui) for all options.
 
+## Architecture & Dependency Analysis
+
+Beyond per-symbol call graphs, CodeSearch analyses the file- and repository-level
+dependency graph built during indexing.
+
+### Execution Features (`features`)
+
+Discovers entry-point execution flows (forward call chains rooted at entry-point
+symbols) and ranks them by a criticality score.
+
+```bash
+# List the most critical features in a repository
+codesearch features list my-repo --limit 20
+
+# Show a single feature by its entry-point symbol
+codesearch features get handle_request
+
+# Show which features are impacted by changing one or more symbols
+codesearch features impacted authenticate hash_password
+```
+
+### Clusters (`clusters`)
+
+Runs the [Leiden](https://en.wikipedia.org/wiki/Leiden_algorithm) community-detection
+algorithm over the file-level call graph to surface tightly-coupled groups of files
+(architectural modules).
+
+```bash
+# List detected clusters
+codesearch clusters list my-repo
+
+# Find which cluster a file belongs to
+codesearch clusters get src/api/auth.rs my-repo
+
+# Print a high-level Markdown architecture overview table
+codesearch clusters overview my-repo
+```
+
+### Cross-repository Usage (`uses`)
+
+Lists every file in one repository that references symbols defined in another,
+grouped by the target file they depend on.
+
+```bash
+# Files in the `web` repo that use files from the `core` repo
+codesearch uses web core
+```
+
+See [Architecture & Dependency Analysis](docs/features/architecture-analysis.md) for
+output examples, flags, and JSON schemas.
+
 ## Editor Integrations
 
 ### Neovim / Telescope
@@ -312,7 +380,20 @@ codesearch mcp --http 8080 --public
 
 The HTTP server exposes the MCP endpoint at `/mcp`.
 
-**Exposed tool**: `search_code` — accepts `query`, `limit`, `min_score`, `languages`, and `repositories` parameters.
+**Exposed tools:**
+
+| Tool | Description |
+|------|-------------|
+| `search_code` | Hybrid/semantic search. Accepts `query`, `limit`, `min_score`, `languages`, `repositories`, and `text_search`. |
+| `analyze_impact` | Blast-radius analysis for a symbol. Accepts `symbol`, `repository_id`, and `regex`. |
+| `get_symbol_context` | 360° caller/callee context for a symbol. Accepts `symbol`, `repository_id`, and `regex`. |
+| `query_graph` | Precise relationship queries over the call graph. Accepts `pattern`, `target`, `repository_id`, and `limit`. |
+
+The `query_graph` tool supports eight intention-named relationship `pattern`s, returning
+only the requested edge type instead of every relationship at once:
+
+`callers_of`, `callees_of`, `imports_of`, `importers_of`, `inheritors_of`,
+`children_of`, `tests_for`, and `file_summary`.
 
 ### Storage Backends
 

docs/README.md

@@ -14,4 +14,6 @@ This directory contains documentation for the CodeSearch project.
 - [Indexing Pipeline](./features/indexing.md)
 - [Search Features](./features/search.md)
 - [Call Graph Analysis](./features/call-graph.md)
+- [Architecture & Dependency Analysis](./features/architecture-analysis.md)
+- [Embedding Backends](./features/embedding-backends.md)
 - [Editor Integrations](./features/editor-integrations.md)