===============
LIBRARY RULES
===============
From library maintainers:
- `codanna init` at repo root creates `.codanna/` with `settings.toml`. Re-run with `--force` to overwrite. Idempotent otherwise.
- Register code paths: `codanna index src lib tests` indexes multiple dirs in one pass. `codanna add-dir <path>` appends, `codanna remove-dir <path>` drops.
- `codanna list-dirs` shows tracked dirs. `codanna config` prints merged effective settings. `-c <path>` overrides `settings.toml` per invocation.
- Default bootstrap: `codanna init` → `codanna index .` → `codanna serve --watch` (stdio for Claude Code / Cursor) or `serve --http --watch` (multi-client).
- `codanna index` reads dirs from settings plus CLI paths. Re-run after major changes; rely on `serve --watch` for incremental edits during a session.
- `codanna index --force` rebuilds. With CLI paths, `--force` clears the index but only rebuilds those paths — other configured paths go stale.
- To rebuild every configured path, run `codanna index --force` with no path arguments.
- `--dry-run` previews files without writing. `--max-files N` caps for smoke tests. `--threads N` overrides `indexing.parallelism` from config.
- Languages supported (15): C, C++, C#, Clojure, GDScript, Go, Java, JavaScript, Kotlin, Lua, PHP, Python, Rust, Swift, TypeScript.
- 8 languages auto-resolve module paths from build config: Go (go.mod), Python (pyproject.toml), TS (tsconfig.json), Java/Kotlin/PHP/C#/Swift.
- Docs and code symbols live in separate stores. `codanna documents <cmd>` targets markdown/text; `codanna retrieve` and `codanna mcp` target code symbols.
- Register collection: `codanna documents add-collection <name> <path>` (default glob `**/*.md`). Custom glob: `--pattern "**/*.mdx"`.
- Index docs: `codanna documents index --collection <name>` or `--all` to index every collection. `--force` rebuilds; `--no-progress` quiets bars.
- Search docs (CLI): `codanna documents search "<query>" --collection <name> --limit 5 --json --fields id,path`.
- Search docs (MCP): `codanna mcp search_documents query:"<text>" collection:<name> limit:5`.
- List collections: `codanna documents list`. Stats: `documents stats <name>`. Remove: `documents remove-collection <name>`.
- `codanna serve` starts MCP over stdio (default for IDE/agent integration). `--watch` hot-reloads when the index changes externally.
- HTTP+OAuth: `codanna serve --http --watch --bind 127.0.0.1:8080`. HTTPS+TLS: `serve --https --watch`. Override `--bind` for LAN/container exposure.
- Single stdio MCP server per index since v0.9.20. Concurrent stdio servers on the same `.codanna/` are rejected at startup.
- Hot-reload polls `meta.json` and `state.json` every `--watch-interval` seconds (default 5). External rebuilds propagate within that window.
- `codanna mcp <tool>` invokes MCP tools directly without launching a server — use for one-shot CLI scripts and CI.
- Tier 1 (highest context per query): `semantic_search_with_context` for meaning plus relationships; `analyze_impact` for change radius. Start here.
- Tier 2 (target a known symbol): `find_symbol <name>` exact lookup, `get_calls <id>` outbound, `find_callers <id>` inbound.
- Tier 3 (browse / status): `search_symbols query:<text>` fuzzy by name, `semantic_search_docs` meaning without relationships, `get_index_info` stats.
- `analyze_impact <name|symbol_id:N> max_depth:5` returns the transitive impact set. Run before refactors to size blast radius.
- Retrieve grammar: `retrieve symbol <name>` exact, `retrieve search "<query>" --kind function --limit 20`, `retrieve describe <name>` full details.
- Call graph: `retrieve callers <name|symbol_id:N>`, `retrieve calls <name|symbol_id:N>`, `retrieve implementations <Trait>`.
- Symbol IDs accepted wherever `<name>` is. Tool output embeds `[symbol_id:N]`; reuse to disambiguate name collisions across modules.
- Common collisions (`new`, `from`, `parse`, `default`) ⇒ first call returns `error.suggestions[]` with `symbol_id:N` candidates; pick via `error.context[]`.
- `kind:` filter accepts function, struct, trait, class, method, enum, type, module, field, interface. Apply via `--kind` flag or `kind:<value>`.
- All retrieve/mcp/documents commands accept `key:value` args alongside flags: `search query:parse limit:5 kind:function lang:rust` is valid.
- `lang:<rust|python|typescript|...>` narrows to one language. Absent ⇒ best matches across all. Useful in multi-language repos and monorepos.
- Threshold filter: `semantic_search_docs query:"<text>" threshold:0.5` drops weak hits. Bands: ≥0.7 strong, 0.5–0.7 relevant, 0.3–0.5 weak, <0.3 noise.
- Query writing: technical terms beat natural questions. "parse TypeScript import statements" beats "how does parsing work".
- Envelope: `{type, status, code, exit_code, message, hint, data, error?, meta}`. Schema version in `meta.schema_version`. Stable across all commands.
- Envelope: `status` ∈ {success, not_found, partial_success, error}. Exit codes: 0 success, 1 not_found, 2 error. Gate scripts via `jq -e '.status == "success"'`.
- Envelope: `hint` carries next-step guidance. Agents chain on `hint` to drive multi-step exploration without external orchestration.
- Envelope: Errors include `error.suggestions[]` and `error.context[]` for recovery — e.g. ambiguous name returns `symbol_id` candidates with file/line context.
- Envelope: `--fields a,b,c` projects only `data` items; envelope (type, status, code, meta) is always intact. Use to shrink large piped result sets.
- Refactor loop: `semantic_search_with_context query:"<concern>"` → `analyze_impact <symbol>` → `find_callers symbol_id:N` → `get_calls symbol_id:N`.
- Debug loop: pipe error string into `semantic_search_with_context query:"<error>"` → `find_callers` to trace reach → `get_calls` for downstream deps.
- Pre-edit check: `analyze_impact <fn>` before modification. Affected count above threshold ⇒ split the change. Threshold tunable in `[guidance]` templates.
- `mcp <tool> --watch` reindexes changed files before running the tool. Use during live edits to avoid stale results without restarting `serve`.
- Empty result set ⇒ drop one filter at a time (`kind:`, `lang:`, `collection:`) before broadening query text. Filters narrow harder than terms.
- Pair impl with prose: `mcp semantic_search_with_context query:"<topic>"` then `mcp search_documents query:"<topic>"`. Same ranking concept, different stores.
- `.codanna/` is generated state — never edit `.codanna/index/` by hand. Tantivy and memmap binary round-trip; manual edits corrupt the index.
- Default embeddings: 384-dim fastembed, local. Remote OpenAI-compatible: `CODANNA_EMBED_URL`, `CODANNA_EMBED_MODEL`, `CODANNA_EMBED_DIM`, `CODANNA_EMBED_API_KEY`.
- Changing embedding backend changes vector dim ⇒ Codanna reports incompatibility ⇒ rebuild with `codanna index --force`. API key only via env, never `settings.toml`.

### Install Codanna via Homebrew

Source: https://docs.codanna.sh/installation

Standard installation method for macOS and Linux users.

```bash
brew install codanna
```

--------------------------------

### Install Codanna via Cargo

Source: https://docs.codanna.sh/installation

Install from crates.io or use cargo-binstall for faster prebuilt binary installation.

```bash
# From crates.io
cargo install codanna --locked

# Prebuilt binaries (faster)
cargo binstall codanna
```

--------------------------------

### Configure document settings

Source: https://docs.codanna.sh/features/document-search

Example configuration for document collections in .codanna/settings.toml.

```toml
[documents]
enabled = true

[documents.collections.docs]
paths = ["docs/"]
patterns = ["**/*.md"]
```

--------------------------------

### Start HTTP Server

Source: https://docs.codanna.sh/reference/mcp-network

Starts an HTTP server with OAuth authentication enabled. Use this for network access when TLS is not required.

```bash
codanna serve --http --watch
```

--------------------------------

### Common Workflow: Starting a Refactor

Source: https://docs.codanna.sh/workflows/tool-tiers

This workflow demonstrates starting a refactor by first finding relevant code using semantic search, then mapping the change radius with impact analysis, and finally getting specific details using call analysis tools.

```bash
codanna mcp semantic_search_with_context query:"authentication logic" limit:3
```

```bash
codanna mcp analyze_impact AuthService
```

```bash
codanna mcp get_calls symbol_id:567
```

```bash
codanna mcp find_callers symbol_id:567
```

--------------------------------

### Manage Project Profiles

Source: https://docs.codanna.sh/reference/cli

Commands for initializing, installing, syncing, and managing project profiles and providers.

```bash
codanna profile init claude
```

```bash
codanna profile install claude
```

```bash
codanna profile list --verbose
```

```bash
codanna profile status
```

```bash
codanna profile sync
```

```bash
codanna profile update claude
```

```bash
codanna profile remove claude
```

```bash
codanna profile verify claude
```

```bash
codanna profile provider add bartolli/codanna-profiles
```

```bash
codanna profile provider remove codanna-profiles
```

```bash
codanna profile provider list --verbose
```

--------------------------------

### Start HTTPS Server

Source: https://docs.codanna.sh/reference/mcp-network

Starts an HTTPS server with TLS encryption enabled. Recommended for secure network communication.

```bash
codanna serve --https --watch
```

--------------------------------

### Install Codanna via Shell Script

Source: https://docs.codanna.sh/

Use this command to download and install the Codanna CLI tool on your system.

```bash
curl -fsSL --proto '=https' --tlsv1.2 https://install.codanna.sh | sh
```

--------------------------------

### Example Text Output for Agentic Guidance

Source: https://docs.codanna.sh/workflows/agentic-guidance

This is an example of the text-based guidance message provided by Codanna, suggesting a next step based on search results.

```text
💡 Found 3 matches. Consider using 'find_symbol' on the most relevant result...
```

--------------------------------

### MCP Quick CLI Examples

Source: https://docs.codanna.sh/reference/mcp-quick

Demonstrates various use cases for MCP Quick, including finding symbols, semantic search, relationship tracing, and JSON output for piping.

```bash
# Find a symbol
codanna mcp find_symbol main
```

```bash
# Semantic search
codanna mcp semantic_search_docs query:"error handling" limit:5
```

```bash
# Search with context
codanna mcp semantic_search_with_context query:"authentication" limit:3
```

```bash
# Trace relationships
codanna mcp get_calls symbol_id:567
```

```bash
codanna mcp find_callers process_file
```

```bash
codanna mcp analyze_impact Parser
```

```bash
# JSON output for piping
codanna mcp search_symbols query:parse --json | jq '.data[].name'
```

--------------------------------

### Serve with Custom Config Path

Source: https://docs.codanna.sh/reference/mcp-network

Starts an HTTP server and specifies the configuration file path. Useful when running the server outside the project directory.

```bash
codanna --config /path/to/project/.codanna/settings.toml serve --http --watch
```

--------------------------------

### Install Codanna via Nix

Source: https://docs.codanna.sh/installation

Requires Nix with flakes enabled to run or enter a development shell.

```bash
# Run directly
nix run github:bartolli/codanna

# Development shell
nix develop github:bartolli/codanna
```

--------------------------------

### Example JSON Output with System Message

Source: https://docs.codanna.sh/workflows/agentic-guidance

This JSON output includes a 'system_message' field containing actionable guidance for AI assistants.

```json
{
  "system_message": "Found 3 matches. Consider using 'find_symbol'வுகளை...",
  "data": []
}
```

--------------------------------

### Launch Claude Code with Certificate Trust

Source: https://docs.codanna.sh/reference/https-setup

Starts the client while explicitly pointing Node.js to the custom CA certificate.

```bash
NODE_EXTRA_CA_CERTS=~/.ssl/codanna-ca.pem claude
```

--------------------------------

### Codanna Ignore File Example

Source: https://docs.codanna.sh/reference/customization

Specify files and directories to be ignored by Codanna, similar to .gitignore. This example shows common exclusions.

```bash
# Created by codanna init
.codanna/       # Don't index own data
target/         # Skip build artifacts
node_modules/   # Skip dependencies
```

--------------------------------

### Enable Watch Mode for Server

Source: https://docs.codanna.sh/reference/debugging

Starts the Codanna serve command with watch enabled, which monitors file changes and triggers re-indexing automatically.

```bash
codanna serve --watch
```

--------------------------------

### Handle Error Responses

Source: https://docs.codanna.sh/workflows/piping

Example of an error response containing suggestions and context for command recovery.

```bash
codanna retrieve callers parse --json
```

```json
{
  "type": "error",
  "status": "error",
  "code": "INVALID_QUERY",
  "exit_code": 2,
  "message": "Ambiguous: found 100 symbol(s) named 'parse'",
  "hint": "Use: codanna retrieve callers symbol_id:<id>",
  "data": null,
  "error": {
    "suggestions": [
      "symbol_id:587",
      "symbol_id:3702"
    ],
    "context": [
      {
        "file_path": "src/parsing/c/parser.rs",
        "kind": "Method",
        "line": 43,
        "symbol_id": 587
      }
    ]
  },
  "meta": {
    "schema_version": "1.0.0"
  }
}
```

--------------------------------

### Register and Manage Codanna Profile Providers

Source: https://docs.codanna.sh/features/collaboration

Commands to register, list, and remove profile providers. Ensure providers are registered before listing or installing profiles.

```bash
# Register a provider
codanna profile provider add bartolli/codanna-profiles

# List available profiles
codanna profile list --verbose

# Install to current workspace
codanna profile install claude

# Check status
codanna profile status
```

```bash
# Add provider
codanna profile provider add bartolli/codanna-profiles

# List providers
codanna profile provider list --verbose

# Remove provider
codanna profile provider remove codanna-profiles
```

--------------------------------

### Handle Not Found Response

Source: https://docs.codanna.sh/workflows/piping

Example of a CLI command resulting in a not found status and the corresponding JSON output structure.

```bash
codanna mcp find_symbol name:NonExistent --json
```

```json
{
  "type": "result",
  "status": "not_found",
  "code": "NOT_FOUND",
  "exit_code": 1,
  "message": "Symbol 'NonExistent' not found",
  "hint": "Use 'search_symbols' with fuzzy matching or 'semantic_search_docs' for broader search.",
  "data": null,
  "meta": {
    "schema_version": "1.0.0",
    "entity_type": "symbol",
    "query": "NonExistent"
  }
}
```

--------------------------------

### Retrieve Implementations

Source: https://docs.codanna.sh/features/relationships

Use this command to get all structs that implement a specified trait, including their definitions.

```bash
retrieve implementations LanguageParser
```

--------------------------------

### Perform Semantic Search

Source: https://docs.codanna.sh/reference/debugging

Executes a semantic search query. The first example shows a potentially too specific query, while the second demonstrates a broader, more effective query for 'config loading'.

```bash
# Too specific
codanna mcp semantic_search_docs query:"TypeScriptParserConfigLoader" limit:5

# Better
codanna mcp semantic_search_docs query:"config loading" limit:5
```

--------------------------------

### Define AuthService for Semantic Search

Source: https://docs.codanna.sh/features/semantic-search

Examples of how documentation comments on symbols are indexed for semantic search across different languages.

```javascript
class AuthService {
  /**
   * Authenticate user with email and password.
   * Returns JWT token on success.
   */
  static default(config) { ... }
}
```

```python
class AuthService:
    def __call__(self, email: str, password: str) -> str:
        """
        Authenticate user with email and password.
        Returns JWT token on success.
        """
        ...
```

```rust
impl AuthService {
    /// Authenticate user with email and password.
    /// Returns JWT token on success.
    pub fn new(email: &str, password: &str) -> Self { ... }
}
```

--------------------------------

### Manage Codanna Profiles in Workspace

Source: https://docs.codanna.sh/features/collaboration

Commands for installing, updating, removing, and verifying Codanna profiles within the current workspace. Use these to manage your project's profile dependencies.

```bash
# Install
codanna profile install claude

# Update
codanna profile update claude

# Remove
codanna profile remove claude

# Verify integrity
codanna profile verify claude
```

--------------------------------

### Customize Guidance Templates in TOML

Source: https://docs.codanna.sh/workflows/agentic-guidance

Guidance messages can be customized by editing the '.codanna/settings.toml' file. This example shows how to configure templates for 'find_callers' and 'analyze_impact'.

```toml
[guidance]
enabled = true

[guidance.templates.find_callers]
no_results = "No callers found. This might be an entry point or unused code."
single_result = "Found 1 caller. Use 'find_symbol' to explore where this function is used."
multiple_results = "Found {result_count} callers. Consider 'analyze_impact' for complete dependency graph."

# Custom thresholds
[[guidance.templates.analyze_impact.custom]]
min = 20
template = "Significant impact with {result_count} affected symbols. Consider breaking this change into smaller parts."
```

--------------------------------

### Example JSON Output for AI Developers

Source: https://docs.codanna.sh/workflows/agentic-guidance

This JSON structure, particularly the 'system_message' field, provides actionable next-step suggestions for AI agents using Codanna's MCP.

```json
{
  "status": "success",
  "system_message": "Found 12 callers. Consider 'analyze_impact' for complete dependency graph.",
  "data": []
}
```

--------------------------------

### Get Calls for a File

Source: https://docs.codanna.sh/features/relationships

Use this command to find all functions invoked by a specific file. Results include symbol IDs for further investigation.

```bash
codanna mcp get_calls process_file
```

--------------------------------

### Synchronize Codanna Profiles with Team

Source: https://docs.codanna.sh/features/collaboration

Command to synchronize installed profiles based on the `.codanna/profiles.lock.json` file. This ensures all team members use the same set of profiles.

```bash
codanna profile sync
```

--------------------------------

### Tier 1: Semantic Search and Impact Analysis

Source: https://docs.codanna.sh/workflows/tool-tiers

Use `semantic_search_with_context` for finding code by meaning with relationships, and `analyze_impact` for mapping changes when modifying a symbol. These are high-context tools to start with.

```bash
codanna mcp semantic_search_with_context query:"authentication logic" limit:3
```

```bash
codanna mcp analyze_impact UserAuth
```

--------------------------------

### Common Workflow: Before Modifying a Function

Source: https://docs.codanna.sh/workflows/tool-tiers

This workflow guides users on preparing to modify a function by first finding what depends on it using `analyze_impact`, then checking all callers with `find_callers`, and finally understanding the contract with `get_calls`.

```bash
codanna mcp analyze_impact process_payment
```

```bash
codanna mcp find_callers symbol_id:890
```

```bash
codanna mcp get_calls symbol_id:890
```

--------------------------------

### Initialize Codanna Project

Source: https://docs.codanna.sh/installation

Run this command in the root of your project to initialize Codanna.

```bash
codanna init
```

--------------------------------

### Configure Windows Environment

Source: https://docs.codanna.sh/reference/https-setup

Sets the environment variable and launches the client on Windows systems.

```cmd
set NODE_EXTRA_CA_CERTS=C:/Users/username/.ssl/codanna-ca.pem
claude
```

--------------------------------

### Serve Options

Source: https://docs.codanna.sh/reference/cli

Configuration flags for running the Codanna server.

```APIDOC
## Serve Options

### Description
Configuration flags for enabling hot-reload, HTTP/HTTPS servers, and binding addresses.

### Parameters
- **--watch** (flag) - Optional - Enable hot-reload when index changes
- **--watch-interval** (N) - Optional - Seconds between change checks
- **--http** (flag) - Optional - Enable HTTP server with OAuth
- **--https** (flag) - Optional - Enable HTTPS server with TLS
- **--bind** (addr) - Optional - Address to bind HTTP/HTTPS server
```

--------------------------------

### Configure Go and Python Project Resolvers

Source: https://docs.codanna.sh/reference/project-resolvers

Add configuration files for Go and Python to settings.toml to enable project resolvers. Re-index after changes.

```toml
[languages.go]
config_files = ["/path/to/project/go.mod"]

[languages.python]
config_files = ["/path/to/project/pyproject.toml"]
```

--------------------------------

### Configure Swift Package Manager

Source: https://docs.codanna.sh/reference/project-resolvers

Enable Swift support and specify Package.swift to detect source roots using SPM conventions or custom path specifications from target definitions.

```toml
[languages.swift]
enabled = true
config_files = ["Package.swift"]
```

--------------------------------

### Java Language Configuration with Gradle

Source: https://docs.codanna.sh/reference/customization

Enable Java support and configure Codanna to read build.gradle for multi-module projects. Specify the source layout if non-standard.

```toml
[[languages.java.projects]]
config_file = "service/build.gradle"
source_layout = "jvm"  # jvm | standard-kmp | flat-kmp
```

--------------------------------

### Get Calls by Symbol ID

Source: https://docs.codanna.sh/features/relationships

Retrieve functions invoked by a specific symbol using its ID. This is useful for chaining queries.

```bash
codanna mcp get_calls symbol_id:1883
```

--------------------------------

### View Index Incompatibility Error

Source: https://docs.codanna.sh/features/semantic-search

Example of the error message displayed when the current embedding backend dimensions do not match the existing index.

```text
ERROR: semantic search disabled -- index incompatible:
Index was built with 384-dimensional embeddings but current backend produces 768d.
Re-index with: codanna index <path> --force
```

--------------------------------

### Enable Go Project Resolver

Source: https://docs.codanna.sh/reference/project-resolvers

Enable the Go language resolver and specify the go.mod configuration file.

```toml
[languages.go]
enabled = true
config_files = ["go.mod"]
```

--------------------------------

### MCP Quick CLI Usage

Source: https://docs.codanna.sh/reference/mcp-quick

Basic syntax for executing MCP tools directly from the command line. No server process is needed.

```bash
codanna mcp <tool> [arguments]
```

--------------------------------

### View Codanna Configuration

Source: https://docs.codanna.sh/reference/customization

Command to display the current Codanna configuration settings.

```bash
codanna config
```

--------------------------------

### Configure Module Logging

Source: https://docs.codanna.sh/reference/debugging

Sets up per-module logging levels in the '.codanna/settings.toml' file. This allows for granular control over debug output for different Codanna components.

```toml
[logging]
default = "warn"

[logging.modules]
# Internal modules
pipeline = "info"    # Indexing stages and progress
semantic = "info"    # Embedding pool and search
indexing = "debug"   # Detailed indexing info
mcp = "debug"        # MCP server operations
watcher = "debug"    # File watcher events

# External targets
rag = "info"         # Document collections
tantivy = "warn"     # Search engine
```

--------------------------------

### Swift Language Configuration

Source: https://docs.codanna.sh/reference/customization

Enable Swift support and specify Package.swift files. Codanna uses these to detect source roots and generate module paths.

```toml
[languages.swift]
enabled = true
config_files = [
    "Package.swift",
    "modules/networking/Package.swift"
]
```

--------------------------------

### Configure C# .csproj for Namespaces

Source: https://docs.codanna.sh/reference/project-resolvers

Enable C# support and specify .csproj files to extract RootNamespace and AssemblyName for namespace configuration. This is essential for SDK-style projects.

```toml
[languages.csharp]
enabled = true
config_files = ["MyProject.csproj"]
```

```xml
<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <RootNamespace>MyCompany.MyProject</RootNamespace>
    <AssemblyName>MyProject</AssemblyName>
  </PropertyGroup>
</Project>
```

--------------------------------

### Test MCP Server Connectivity and Tool Execution

Source: https://docs.codanna.sh/reference/cli

Execute MCP tools and test server connectivity. Omit the `--tool` flag to list available tools.

```bash
codanna mcp-test
```

```bash
codanna mcp-test --tool find_symbol --args '{"name":"main"}'
```

--------------------------------

### Enable Python Project Resolver

Source: https://docs.codanna.sh/reference/project-resolvers

Enable the Python language resolver and specify the pyproject.toml configuration file. Codanna auto-detects the build backend.

```toml
[languages.python]
enabled = true
config_files = ["pyproject.toml"]
```

--------------------------------

### Get Symbol Details using Codanna CLI

Source: https://docs.codanna.sh/workflows/agentic-guidance

Use the 'codanna mcp find_symbol' command to retrieve details about a specific code symbol. The 'symbol_id' can be used for more precise lookups.

```bash
codanna mcp find_symbol commit_batch
```

--------------------------------

### Create Shell Alias

Source: https://docs.codanna.sh/reference/https-setup

Simplifies launching the secure client by creating a persistent alias in shell configuration files.

```bash
alias claude-secure='NODE_EXTRA_CA_CERTS=~/.ssl/codanna-ca.pem claude'
```

```bash
claude-secure
```

--------------------------------

### Configure PHP PSR-4 Autoloading

Source: https://docs.codanna.sh/reference/project-resolvers

Enable PHP support and specify composer.json to enable PSR-4 autoloading configuration. Codanna sorts namespace mappings by path length for correct resolution.

```toml
[languages.php]
enabled = true
config_files = ["composer.json"]
```

```json
{
  "autoload": {
    "psr-4": {
      "App\\": "src/",
      "App\\Http\\": "src/Http/"
    }
  }
}
```

--------------------------------

### Check .codanna Directory

Source: https://docs.codanna.sh/reference/debugging

Lists the contents of the '.codanna' directory in the current path to ensure configuration files and cache exist.

```bash
ls -la .codanna/
```

--------------------------------

### Configure Java Multi-Project Resolvers

Source: https://docs.codanna.sh/reference/project-resolvers

Configure multiple Java projects, specifying build files and source layouts for accurate path resolution.

```toml
[[languages.java.projects]]
config_file = "api/pom.xml"
source_layout = "jvm"

[[languages.java.projects]]
config_file = "service/build.gradle"
source_layout = "jvm"
```

--------------------------------

### Manage document collections via CLI

Source: https://docs.codanna.sh/features/document-search

Commands to add, list, and remove document collections for indexing.

```bash
# Add a collection
codanna documents add-collection docs docs/

# List collections
codanna documents list

# Remove a collection
codanna documents remove-collection docs
```

--------------------------------

### Configure Java Project Resolver

Source: https://docs.codanna.sh/reference/project-resolvers

Enable the Java language resolver and specify Maven pom.xml or Gradle build.gradle configuration files. For custom layouts, set `source_layout`.

```toml
[languages.java]
enabled = true
config_files = ["pom.xml"]

# For Gradle projects with custom layouts:
[[languages.java.projects]]
config_file = "build.gradle"
source_layout = "jvm"  # jvm | standard-kmp | flat-kmp
```

--------------------------------

### Configure Kotlin Project Resolver

Source: https://docs.codanna.sh/reference/project-resolvers

Enable the Kotlin language resolver and specify the build.gradle.kts configuration file. For non-standard layouts, set `source_layout`.

```toml
[languages.kotlin]
enabled = true
config_files = ["build.gradle.kts"]

# For projects with non-standard layouts:
[[languages.kotlin.projects]]
config_file = "build.gradle.kts"
source_layout = "jvm"  # jvm | standard-kmp | flat-kmp
```

--------------------------------

### Chaining Queries with Symbol ID

Source: https://docs.codanna.sh/features/relationships

Demonstrates how to chain Codanna CLI commands using symbol IDs obtained from previous queries, enabling precise relationship tracing.

```bash
# Find a symbol
codanna mcp semantic_search_with_context query:"config parser" limit:1
# Returns: parse_config [symbol_id:567]

# Trace its relationships
codanna mcp get_calls symbol_id:567
codanna mcp find_callers symbol_id:567
codanna mcp analyze_impact symbol_id:567
```

--------------------------------

### Perform Semantic Search with Context

Source: https://docs.codanna.sh/features/semantic-search

Retrieve detailed symbol information including relationships and documentation.

```bash
codanna mcp semantic_search_with_context query:"error handling" limit:1
```

```text
Found 1 results for query: 'error handling'

1. error - Method at src/io/format.rs:149-163 [symbol_id:5240]
   Similarity Score: 0.642
   Documentation:
     Create a generic error response.
   Signature: pub fn error(code: ExitCode, message: &str, suggestions: Vec<&str>) -> Self

   error calls 2 function(s):
     -> Module collect at src/indexing/pipeline/stages/mod.rs:10 [symbol_id:3222]
     -> Method iter at src/storage/memory.rs:105 [symbol_id:4480]

   error uses 1 type(s):
     -> Enum ExitCode at src/io/exit_code.rs:19-47 [symbol_id:5076]
```

--------------------------------

### Codanna CLI Key:Value Arguments

Source: https://docs.codanna.sh/reference/cli

Use key:value pairs for arguments with retrieve, MCP, and documents commands. This format works alongside flags.

```bash
codanna retrieve search query:parse limit:5 kind:function
```

```bash
codanna mcp semantic_search_docs query:"error handling" limit:3 lang:rust
```

```bash
codanna documents search query:"auth" limit:5 collection:docs
```

--------------------------------

### Codanna CLI Commands

Source: https://docs.codanna.sh/reference/cli

Overview of core CLI commands for managing the Codanna environment and codebase indexing.

```APIDOC
## CLI Commands

### Description
Core commands to initialize, index, and manage the Codanna workspace.

### Commands
- **codanna init** - Set up .codanna directory with configuration
- **codanna index [paths]** - Build searchable index from codebase
- **codanna add-dir <path>** - Add folder to indexed paths
- **codanna remove-dir <path>** - Remove folder from indexed paths
- **codanna list-dirs** - List configured indexed directories
- **codanna retrieve <subcommand>** - Query symbols and relationships
- **codanna mcp <tool>** - Execute MCP tools directly
- **codanna mcp-test** - Test MCP connection and list tools
- **codanna serve** - Start MCP server
- **codanna documents <subcommand>** - Manage document collections
- **codanna profile <subcommand>** - Manage workspace profiles
- **codanna config** - Display active settings
- **codanna parse <file>** - Output AST as JSONL
- **codanna benchmark [language]** - Benchmark parser performance
```

--------------------------------

### Configure MCP Persistent for OpenCode

Source: https://docs.codanna.sh/reference/mcp-persistent

Add this configuration to your `opencode.json` file for OpenCode integration. OpenCode combines the command and arguments into a single array under the `command` key.

```json
{
  "mcp": {
    "codanna": {
      "type": "local",
      "command": ["codanna", "--config", ".codanna/settings.toml", "serve", "--watch"],
      "enabled": true
    }
  }
}
```

--------------------------------

### Configure Kotlin Multi-Project Resolvers

Source: https://docs.codanna.sh/reference/project-resolvers

Configure multiple Kotlin projects with specific build files and source layouts for accurate path resolution.

```toml
[[languages.kotlin.projects]]
config_file = "app/build.gradle.kts"
source_layout = "jvm"

[[languages.kotlin.projects]]
config_file = "shared/build.gradle.kts"
source_layout = "flat-kmp"
```

--------------------------------

### Configure TypeScript tsconfig.json for Paths

Source: https://docs.codanna.sh/reference/project-resolvers

Enable TypeScript support and specify tsconfig.json files to resolve path aliases and baseUrl settings. Supports path aliases, baseUrl resolution, and project references.

```toml
[languages.typescript]
enabled = true
config_files = [
    "tsconfig.json",
    "packages/web/tsconfig.json"
]
```

```json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@app/*": ["src/app/*"],
      "@components/*": ["src/components/*"]
    }
  }
}
```

--------------------------------

### Configure Goose MCP Persistent via CLI

Source: https://docs.codanna.sh/reference/mcp-persistent

Use this command-line interface sequence to configure Goose to use the Codanna MCP persistent server. It prompts for extension details and the command to run.

```bash
goose configure
# Select: Add Extension > Command-line Extension
# Name: codanna
# Command: codanna --config .codanna/settings.toml serve --watch
```

--------------------------------

### Index Project Code

Source: https://docs.codanna.sh/installation

Indexes the current directory for semantic search.

```bash
codanna index .
```

--------------------------------

### Manage Document Collections

Source: https://docs.codanna.sh/reference/cli

Commands for adding, removing, indexing, searching, and listing document collections.

```bash
codanna documents add-collection docs docs/
```

```bash
codanna documents remove-collection docs
```

```bash
codanna documents index
```

```bash
codanna documents search "auth flow"
```

```bash
codanna documents list
```

```bash
codanna documents stats docs
```

--------------------------------

### TypeScript Language Configuration

Source: https://docs.codanna.sh/reference/customization

Enable TypeScript support and specify configuration files like tsconfig.json. This helps Codanna resolve path aliases and module settings.

```toml
[languages.typescript]
enabled = true
config_files = [
    "tsconfig.json",
    "packages/web/tsconfig.json"
]
```

--------------------------------

### Configure MCP Persistent for Goose (YAML)

Source: https://docs.codanna.sh/reference/mcp-persistent

Add this configuration to your `~/.config/goose/config.yaml` file for Goose integration. This specifies the command, arguments, and type for the Codanna extension.

```yaml
extensions:
  codanna:
    name: codanna
    cmd: codanna
    args:
      - "--config"
      - ".codanna/settings.toml"
      - "serve"
      - "--watch"
    type: stdio
    enabled: true
```

--------------------------------

### Indexed Paths Configuration

Source: https://docs.codanna.sh/reference/customization

Specify which directories should be indexed by Codanna. This configuration is managed via the settings.toml file.

```toml
[indexing]
indexed_paths = [
    "/path/to/project1",
    "/path/to/project2"
]
```

--------------------------------

### Common Workflow: Debugging an Issue

Source: https://docs.codanna.sh/workflows/tool-tiers

This workflow outlines debugging an issue by first searching with an error description, then tracing how code is reached using `find_callers`, and finally seeing dependencies with `get_calls`.

```bash
codanna mcp semantic_search_with_context query:"connection timeout error" limit:3
```

```bash
codanna mcp find_callers symbol_id:123
```

```bash
codanna mcp get_calls symbol_id:123
```

--------------------------------

### Profile Subcommands API

Source: https://docs.codanna.sh/reference/cli

Manage project profiles for collaboration and configuration.

```APIDOC
## Profile Subcommands

### Initialize Profile

Initializes a project with a specified profile.

### Method

`POST` (Conceptual - CLI command)

### Endpoint

`/profile/init

### Parameters

#### Path Parameters

- **name** (string) - Required - The name of the profile to initialize with.

### Request Example

```bash
codanna profile init claude
```

### Response

(Not applicable for this CLI command - output is to stdout)

---

## Profile Subcommands

### Install Profile

Installs a profile to the workspace.

### Method

`POST` (Conceptual - CLI command)

### Endpoint

`/profile/install

### Parameters

#### Path Parameters

- **name** (string) - Required - The name of the profile to install.

#### Query Parameters

- **--source <source>** (string) - Optional - Profile source (git URL or local directory).
- **--ref <ref>** (string) - Optional - Git reference (branch, tag, or commit SHA).
- **-f, --force** (boolean) - Optional - Force installation even if profile exists.

### Request Example

```bash
codanna profile install claude
codanna profile install claude --source git@github.com:user/repo.git --ref main -f
```

### Response

(Not applicable for this CLI command - output is to stdout)

---

## Profile Subcommands

### List Profiles

Lists available profiles.

### Method

`GET` (Conceptual - CLI command)

### Endpoint

`/profile/list

### Parameters

#### Query Parameters

- **--verbose** (boolean) - Optional - Show verbose output.

### Request Example

```bash
codanna profile list
codanna profile list --verbose
```

### Response

(Not applicable for this CLI command - output is to stdout)

---

## Profile Subcommands

### Show Profile Status

Shows the status of installed profiles.

### Method

`GET` (Conceptual - CLI command)

### Endpoint

`/profile/status

### Request Example

```bash
codanna profile status
```

### Response

(Not applicable for this CLI command - output is to stdout)

---

## Profile Subcommands

### Sync Profiles

Installs profiles from the team configuration.

### Method

`POST` (Conceptual - CLI command)

### Endpoint

`/profile/sync

### Request Example

```bash
codanna profile sync
```

### Response

(Not applicable for this CLI command - output is to stdout)

---

## Profile Subcommands

### Update Profile

Updates an installed profile.

### Method

`PUT` (Conceptual - CLI command)

### Endpoint

`/profile/update/{name}

### Parameters

#### Path Parameters

- **name** (string) - Required - The name of the profile to update.

### Request Example

```bash
codanna profile update claude
```

### Response

(Not applicable for this CLI command - output is to stdout)

---

## Profile Subcommands

### Remove Profile

Removes a profile.

### Method

`DELETE` (Conceptual - CLI command)

### Endpoint

`/profile/remove/{name}

### Parameters

#### Path Parameters

- **name** (string) - Required - The name of the profile to remove.

### Request Example

```bash
codanna profile remove claude
```

### Response

(Not applicable for this CLI command - output is to stdout)

---

## Profile Subcommands

### Verify Profile

Verifies the integrity of a profile.

### Method

`GET` (Conceptual - CLI command)

### Endpoint

`/profile/verify/{name}

### Parameters

#### Path Parameters

- **name** (string) - Optional - The name of the profile to verify. If not provided, verifies all installed profiles.

### Request Example

```bash
codanna profile verify claude
codanna profile verify
```

### Response

(Not applicable for this CLI command - output is to stdout)

---

## Profile Subcommands

### Add Profile Provider

Registers a profile provider.

### Method

`POST` (Conceptual - CLI command)

### Endpoint

`/profile/provider/add

### Parameters

#### Query Parameters

- **source** (string) - Required - The source of the provider (e.g., git URL).

### Request Example

```bash
codanna profile provider add bartolli/codanna-profiles
```

### Response

(Not applicable for this CLI command - output is to stdout)

---

## Profile Subcommands

### Remove Profile Provider

Removes a registered profile provider.

### Method

`DELETE` (Conceptual - CLI command)

### Endpoint

`/profile/provider/remove/{id}

### Parameters

#### Path Parameters

- **id** (string) - Required - The ID of the provider to remove.

### Request Example

```bash
codanna profile provider remove codanna-profiles
```

### Response

(Not applicable for this CLI command - output is to stdout)

---

## Profile Subcommands

### List Profile Providers

Lists registered profile providers.

### Method

`GET` (Conceptual - CLI command)

### Endpoint

`/profile/provider/list

### Parameters

#### Query Parameters

- **--verbose** (boolean) - Optional - Show verbose output.

### Request Example

```bash
codanna profile provider list
codanna profile provider list --verbose
```

### Response

(Not applicable for this CLI command - output is to stdout)

```

--------------------------------

### Check Codanna in PATH

Source: https://docs.codanna.sh/reference/debugging

Verifies if the 'codanna' executable is available in the system's PATH environment variable.

```bash
which codanna
```

--------------------------------

### Benchmark Parser Performance

Source: https://docs.codanna.sh/reference/cli

Run performance benchmarks for specific languages or custom files.

```bash
codanna benchmark                  # All languages
codanna benchmark rust             # Single language
codanna benchmark --file src/lib.rs  # Custom file
```

--------------------------------

### Configure MCP Persistent for Claude Code

Source: https://docs.codanna.sh/reference/mcp-persistent

Add this configuration to your project's `.mcp.json` file to integrate Codanna's persistent server with Claude Code. Ensure the command and arguments are correctly specified.

```json
{
  "mcpServers": {
    "codanna": {
      "command": "codanna",
      "args": ["--config", ".codanna/settings.toml", "serve", "--watch"]
    }
  }
}
```

--------------------------------

### Find Implementations for a Trait

Source: https://docs.codanna.sh/features/relationships

Discover all types that implement a given trait. This command returns definitions and relationships.

```bash
codanna mcp find_symbol LanguageParser
```

--------------------------------

### Perform Basic Semantic Code Search

Source: https://docs.codanna.sh/features/semantic-search

Execute a semantic search query for symbols and view the resulting matches.

```bash
codanna mcp semantic_search_docs query:"user authentication" limit:3
```

```text
Found 3 semantically similar result(s) for 'user authentication':

1. name (Field) - Similarity: 0.356
   File: src/plugins/marketplace.rs:40
   Doc: Owner name (user or organization)

2. name (Field) - Similarity: 0.356
   File: src/profiles/provider.rs:40
   Doc: Owner name (user or organization)

3. credential_callback (Function) - Similarity: 0.332
   File: src/profiles/git.rs:80
   Doc: Credential callback for git2 authentication
```

--------------------------------

### Configure Codex CLI Client

Source: https://docs.codanna.sh/reference/mcp-network

Adds MCP Network configuration for the Codex CLI client to the ~/.codex/config.toml file. Ensure the server is running before connecting.

```toml
[mcp_servers.codanna]
type = "http"
url = "http://127.0.0.1:8080/mcp"
```

--------------------------------

### Configure MCP Persistent for Codex CLI

Source: https://docs.codanna.sh/reference/mcp-persistent

Add this configuration to your `~/.codex/config.toml` file for Codex CLI integration. Use `mcp_servers` (snake_case) for the key.

```toml
[mcp_servers.codanna]
command = "codanna"
args = ["--config", ".codanna/settings.toml", "serve", "--watch"]
```

--------------------------------

### Tier 3: Symbol Search and Index Information

Source: https://docs.codanna.sh/workflows/tool-tiers

Use `search_symbols` for fuzzy matching by name pattern, `semantic_search_docs` for semantic search without relationship context, and `get_index_info` for checking index statistics. These tools are for exploration and index status.

```bash
codanna mcp search_symbols query:parse kind:function limit:10
```

```bash
codanna mcp semantic_search_docs query:"error handling" limit:5
```

```bash
codanna mcp get_index_info
```

--------------------------------

### Configure MCP Client

Source: https://docs.codanna.sh/reference/https-setup

Defines the HTTPS server connection settings within the .mcp.json configuration file.

```json
{
  "mcpServers": {
    "codanna": {
      "type": "http",
      "url": "https://127.0.0.1:8443/mcp"
    }
  }
}
```

--------------------------------

### Search documents via MCP

Source: https://docs.codanna.sh/features/document-search

Perform semantic searches using the Model Context Protocol.

```bash
codanna mcp search_documents query:"setup guide" limit:5
codanna mcp search_documents query:"configuration" collection:docs
```

--------------------------------

### Add Directory to Index CLI

Source: https://docs.codanna.sh/reference/customization

Command to add a directory to Codanna's index. Use 'list-dirs' to view and 'remove-dir' to remove.

```bash
codanna add-dir src
```

--------------------------------

### Perform Full-Text Search with Fuzzy Matching using MCP

Source: https://docs.codanna.sh/reference/cli

Employ the `search_symbols` MCP tool for full-text search with fuzzy matching capabilities.

```bash
codanna mcp search_symbols query:parse limit:10
```

--------------------------------

### Configure Claude Client

Source: https://docs.codanna.sh/reference/mcp-network

Adds MCP Network configuration for the Claude client to the .mcp.json file. Ensure the server is running before connecting.

```json
{
  "mcpServers": {
    "codanna": {
      "type": "http",
      "url": "http://127.0.0.1:8080/mcp"
    }
  }
}
```

--------------------------------

### Logging Configuration

Source: https://docs.codanna.sh/reference/customization

Configure default logging levels and module-specific levels. This helps in debugging by controlling the verbosity of logs.

```toml
[logging]
default = "warn"

[logging.modules]
cli = "debug"
indexing = "info"
```

--------------------------------

### Search documents via CLI

Source: https://docs.codanna.sh/features/document-search

Perform semantic searches across indexed documents using the CLI.

```bash
codanna documents search "authentication flow"
codanna documents search "error handling" --collection docs --limit 5
```

--------------------------------

### Search for a Concept using Codanna CLI

Source: https://docs.codanna.sh/workflows/agentic-guidance

Use the 'codanna mcp semantic_search_docs' command to search for documentation related to a specific concept. The 'limit' parameter controls the number of results returned.

```bash
codanna mcp semantic_search_docs query:"commit batch write index" limit:3
```

--------------------------------

### Manage and Search Document Collections

Source: https://docs.codanna.sh/features/semantic-search

Index markdown or text files and perform searches across them.

```bash
# Add and index a collection
codanna documents add-collection docs docs/
codanna documents index

# Search
codanna documents search "authentication flow"

# Or via MCP
codanna mcp search_documents query:"setup guide" limit:5
```

--------------------------------

### Configure Gemini CLI Client

Source: https://docs.codanna.sh/reference/mcp-network

Adds MCP Network configuration for the Gemini CLI client to your settings.json. Gemini CLI auto-discovers OAuth endpoints for HTTPS servers.

```json
{
  "mcpServers": {
    "codanna": {
      "url": "https://127.0.0.1:8443/mcp"
    }
  }
}
```

--------------------------------

### Conduct Natural Language Search using MCP

Source: https://docs.codanna.sh/reference/cli

Use the `semantic_search_docs` MCP tool for natural language searches.

```bash
codanna mcp semantic_search_docs query:"error handling" limit:5
```

--------------------------------

### Index document collections

Source: https://docs.codanna.sh/features/document-search

Commands to trigger indexing for all collections or specific ones, with options to disable progress bars.

```bash
codanna documents index
```

```bash
codanna documents index --no-progress
```

```bash
codanna documents index --collection docs
```

--------------------------------

### Search Indexed Documents using MCP

Source: https://docs.codanna.sh/reference/cli

Utilize the `search_documents` MCP tool to search through indexed documents.

```bash
codanna mcp search_documents query:"setup guide" limit:5
```

--------------------------------

### Configure Remote Embedding via Environment Variables

Source: https://docs.codanna.sh/features/semantic-search

Set environment variables to define the remote embedding server connection details.

```bash
export CODANNA_EMBED_URL=http://localhost:11434    # Server base URL
export CODANNA_EMBED_MODEL=nomic-embed-text        # Model name
export CODANNA_EMBED_DIM=768                        # Output dimension
```

--------------------------------

### Local Semantic Search Model Configuration

Source: https://docs.codanna.sh/reference/customization

Configure Codanna to use a local model for semantic search. Ensure the model name is valid.

```toml
[semantic_search]
model = "AllMiniLML6V2"
```

--------------------------------

### MCP Tools

Source: https://docs.codanna.sh/reference/cli

List of available Model Context Protocol (MCP) tools for symbol analysis and search.

```APIDOC
## MCP Tools

### Description
Tools for interacting with the codebase via MCP, including symbol lookup, semantic search, and impact analysis.

### Available Tools
- **find_symbol**: Find symbol by exact name
- **search_symbols**: Full-text search with fuzzy matching
- **semantic_search_docs**: Natural language search
- **semantic_search_with_context**: Natural language search with relationships
- **get_calls**: Functions called by a function
- **find_callers**: Functions that call a function
- **analyze_impact**: Impact radius of symbol changes
- **search_documents**: Search indexed documents
- **get_index_info**: Index statistics

### MCP Flags
- **--json**: Output in JSON format
- **--fields <fields>**: Filter JSON output to specific data fields
- **--watch**: Check for file changes and reindex before running the tool
- **--args <json>**: Pass tool arguments as a JSON string
```

--------------------------------

### Check Index Existence

Source: https://docs.codanna.sh/reference/debugging

Verify if an index exists before proceeding with operations. This command retrieves information about the specified index.

```bash
codanna mcp get_index_info
```

--------------------------------

### Bind Server to Custom Port

Source: https://docs.codanna.sh/reference/mcp-network

Binds the HTTP server to localhost on a custom port (3000). Useful for avoiding port conflicts.

```bash
codanna serve --http --bind 127.0.0.1:3000
```

--------------------------------

### Bind Server to All Interfaces

Source: https://docs.codanna.sh/reference/mcp-network

Binds the HTTP server to all available network interfaces on port 8080. Use with caution as it makes the server accessible from other machines.

```bash
codanna serve --http --bind 0.0.0.0:8080
```

--------------------------------

### Codanna Retrieve Subcommands

Source: https://docs.codanna.sh/reference/cli

Detailed reference for the 'retrieve' subcommand used to query symbols, calls, and relationships within the indexed codebase.

```APIDOC
## codanna retrieve

### Description
Query symbols and relationships within the indexed codebase.

### Subcommands
- **symbol <name>** - Find symbol by name or symbol_id:ID
- **calls <name>** - Functions called by a function
- **callers <name>** - Functions that call a function
- **implementations <name>** - Types that implement a trait
- **describe <name>** - Full details: signature, docs, relationships
- **search <query>** - Full-text search with filters

### Global Options for Retrieve
- **--json** - Output results in JSON format
- **--fields <fields>** - Filter JSON output to specific data fields
- **lang:<language>** - Filter results by language (e.g., lang:rust)
```

--------------------------------

### Remote Semantic Search Backend Configuration

Source: https://docs.codanna.sh/reference/customization

Configure Codanna to use a remote OpenAI-compatible HTTP server for embeddings. This overrides local model settings.

```toml
[semantic_search]
remote_url = "http://localhost:11434"
remote_model = "nomic-embed-text"
remote_dim = 768
```

--------------------------------

### Perform Natural Language Search with Relationships using MCP

Source: https://docs.codanna.sh/reference/cli

Leverage `semantic_search_with_context` MCP tool for natural language searches that consider relationships.

```bash
codanna mcp semantic_search_with_context query:"auth logic" limit:3
```

--------------------------------

### Benchmark API

Source: https://docs.codanna.sh/reference/cli

Benchmark parser performance for various languages.

```APIDOC
## Benchmark

Benchmarks parser performance for one or all languages.

### Method

`GET` (Conceptual - CLI command)

### Endpoint

`/benchmark

### Parameters

#### Query Parameters

- **language** (string) - Optional - The language to benchmark (e.g., `rust`, `python`). If not provided, benchmarks all supported languages.
- **--file <path>** (string) - Optional - Path to a custom file for benchmarking.

### Request Example

```bash
codanna benchmark
codanna benchmark rust
codanna benchmark --file src/lib.rs
```

### Response

(Not applicable for this CLI command - output is to stdout)

```

--------------------------------

### Verify Code Resolution with Codanna CLI

Source: https://docs.codanna.sh/reference/project-resolvers

Use the codanna mcp analyze_impact command to verify that cross-file relationships resolve correctly based on project configuration. Check callers and calls sections to confirm detection.

```bash
codanna mcp analyze_impact symbol_name:"your_function"
```

--------------------------------

### Logging via Environment Variable

Source: https://docs.codanna.sh/reference/customization

Control Codanna's logging verbosity using the RUST_LOG environment variable. This is useful for debugging specific commands like 'codanna index'.

```bash
RUST_LOG=debug codanna index
```

--------------------------------

### Add Codanna MCP Persistent to Gemini CLI

Source: https://docs.codanna.sh/reference/mcp-persistent

Use this command to add the Codanna MCP persistent server configuration to the Gemini CLI. The `--` separates Gemini CLI arguments from Codanna server arguments.

```bash
gemini mcp add codanna codanna -- --config .codanna/settings.toml serve --watch
```

--------------------------------

### MCP Test

Source: https://docs.codanna.sh/reference/cli

Utility for testing MCP server connectivity and tool execution.

```APIDOC
## MCP Test

### Description
Test MCP server connectivity and verify tool execution.

### Parameters
- **--tool** (string) - Optional - Tool to call
- **--args** (json) - Optional - Tool arguments as JSON
- **--server-binary** (path) - Optional - Path to server binary
- **--delay** (seconds) - Optional - Wait before calling the tool

### Request Example
`codanna mcp-test --tool find_symbol --args '{"name":"main"}'`
```

--------------------------------

### Perform Semantic Search

Source: https://docs.codanna.sh/installation

Executes a semantic search query using the MCP interface.

```bash
codanna mcp semantic_search_with_context query:"where do we handle errors" limit:3
```

--------------------------------

### Set Embedding API Key

Source: https://docs.codanna.sh/features/semantic-search

Configure the API key for authenticated remote embedding providers.

```bash
export CODANNA_EMBED_API_KEY=sk-...
```

--------------------------------

### Extract Data with jq

Source: https://docs.codanna.sh/workflows/piping

Use jq to parse JSON output from Codanna commands for specific fields or status checks.

```bash
# Get symbol names from search results
codanna mcp semantic_search_with_context query:"authentication" limit:2 --json | \
  jq -r '.data[].symbol.name'

# Get file paths only
codanna mcp find_symbol name:Parser --json | \
  jq -r '.data[].file_path'

# Check status before processing
codanna mcp find_symbol name:Parser --json | \
  jq -e '.status == "success"' && echo "Found"
```

--------------------------------

### Envelope JSON Structure

Source: https://docs.codanna.sh/reference/json-schema

The base structure for all successful CLI command responses.

```json
{
  "type": "result",
  "status": "success",
  "code": "OK",
  "exit_code": 0,
  "message": "Found 1 symbol(s)",
  "hint": "Symbol found with full context...",
  "data": [...],
  "meta": {
    "schema_version": "1.0.0",
    "entity_type": "symbol",
    "count": 1,
    "query": "Parser"
  }
}
```