axm-echo 0.0.1.dev0__tar.gz → 0.1.0__tar.gz

axm_echo-0.1.0/.gitignore

@@ -0,0 +1,48 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+# Generated version file
+_version.py
+.Python
+build/
+dist/
+*.egg-info/
+*.egg
+
+# Virtual environments
+.venv/
+.uv/
+venv/
+ENV/
+
+# Testing & Coverage
+.pytest_cache/
+.coverage
+coverage.xml
+coverage.json
+htmlcov/
+coverage_html/
+.tox/
+
+# Type checking & Linting
+.mypy_cache/
+.ruff_cache/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Environment
+.env
+.envrc
+
+# Documentation
+site/
+
+# OS
+.DS_Store
+Thumbs.db

axm_echo-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,16 @@
+# Contributing to axm-echo
+
+Thanks for your interest in contributing!
+
+## Development setup
+
+```bash
+uv sync --all-groups
+uv run pytest
+```
+
+## Pull requests
+
+- Follow Conventional Commits for commit messages.
+- Run `make lint` and `make test` before opening a PR.
+- Add tests for new features and bug fixes.

axm_echo-0.1.0/PKG-INFO

@@ -0,0 +1,84 @@
+Metadata-Version: 2.4
+Name: axm-echo
+Version: 0.1.0
+Summary: Neural similarity & echo detection over code corpora (MiniLM + scikit-learn).
+Project-URL: Homepage, https://github.com/axm-protocols/axm-forge-workspace
+Project-URL: Documentation, https://axm-protocols.github.io/axm-forge-workspace/
+Project-URL: Repository, https://github.com/axm-protocols/axm-forge-workspace.git
+Project-URL: Issues, https://github.com/axm-protocols/axm-forge-workspace/issues
+Author-email: Gabriel Jarry <gabriel@axm-protocols.io>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: axm
+Requires-Dist: axm-ast
+Requires-Dist: numpy>=2.5.0
+Requires-Dist: scikit-learn>=1.9.0
+Requires-Dist: sentence-transformers>=5.6.0
+Requires-Dist: torch>=2.12.1
+Description-Content-Type: text/markdown
+
+# axm-echo
+
+Neural similarity & echo detection over code corpora (MiniLM + scikit-learn).
+
+<p align="center">
+  <a href="https://forge.axm-protocols.io/audit/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge-workspace/gh-pages/badges/axm-echo/axm-audit.json" alt="axm-audit"></a>
+  <a href="https://forge.axm-protocols.io/init/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge-workspace/gh-pages/badges/axm-echo/axm-init.json" alt="axm-init"></a>
+  <a href="https://github.com/axm-protocols/axm-forge-workspace/actions/workflows/axm-quality.yml"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge-workspace/gh-pages/badges/axm-echo/coverage.json" alt="Coverage"></a>
+  <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+">
+</p>
+
+---
+
+## Overview
+
+Neural similarity & echo detection over code corpora (MiniLM + scikit-learn).
+
+## Features
+
+- **Neural by default** — the `st` (MiniLM) backend ships in the base install
+  (`torch` + `sentence-transformers`) and runs in-process; no extra to enable.
+- **`tfidf` opt-out** — the pure-CPU `numpy` + `scikit-learn` backend stays
+  available (`--backend tfidf`) for callers that want to avoid loading torch.
+- Built on `axm-ast` for code-corpus extraction — the corpus feeding both
+  `echo_code` (cross-package dedup) and `echo_check` (reuse retrieval).
+
+## Installation
+
+```bash
+# echo is neural by default — the install ships torch + sentence-transformers.
+uv add axm-echo
+```
+
+Or as a workspace dependency in `pyproject.toml`:
+
+```toml
+[project]
+dependencies = ["axm-echo"]
+
+[tool.uv.sources]
+axm-echo = { workspace = true }
+```
+
+## Development
+
+This package is part of the **axm-forge-workspace** uv workspace.
+
+```bash
+# Run tests for this package
+uv run pytest --package axm-echo
+
+# From workspace root
+make test-axm-echo
+```
+
+## License
+
+MIT — © 2026 Gabriel Jarry

axm_echo-0.1.0/README.md

@@ -0,0 +1,58 @@
+# axm-echo
+
+Neural similarity & echo detection over code corpora (MiniLM + scikit-learn).
+
+<p align="center">
+  <a href="https://forge.axm-protocols.io/audit/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge-workspace/gh-pages/badges/axm-echo/axm-audit.json" alt="axm-audit"></a>
+  <a href="https://forge.axm-protocols.io/init/"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge-workspace/gh-pages/badges/axm-echo/axm-init.json" alt="axm-init"></a>
+  <a href="https://github.com/axm-protocols/axm-forge-workspace/actions/workflows/axm-quality.yml"><img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge-workspace/gh-pages/badges/axm-echo/coverage.json" alt="Coverage"></a>
+  <img src="https://img.shields.io/badge/python-3.12%2B-blue" alt="Python 3.12+">
+</p>
+
+---
+
+## Overview
+
+Neural similarity & echo detection over code corpora (MiniLM + scikit-learn).
+
+## Features
+
+- **Neural by default** — the `st` (MiniLM) backend ships in the base install
+  (`torch` + `sentence-transformers`) and runs in-process; no extra to enable.
+- **`tfidf` opt-out** — the pure-CPU `numpy` + `scikit-learn` backend stays
+  available (`--backend tfidf`) for callers that want to avoid loading torch.
+- Built on `axm-ast` for code-corpus extraction — the corpus feeding both
+  `echo_code` (cross-package dedup) and `echo_check` (reuse retrieval).
+
+## Installation
+
+```bash
+# echo is neural by default — the install ships torch + sentence-transformers.
+uv add axm-echo
+```
+
+Or as a workspace dependency in `pyproject.toml`:
+
+```toml
+[project]
+dependencies = ["axm-echo"]
+
+[tool.uv.sources]
+axm-echo = { workspace = true }
+```
+
+## Development
+
+This package is part of the **axm-forge-workspace** uv workspace.
+
+```bash
+# Run tests for this package
+uv run pytest --package axm-echo
+
+# From workspace root
+make test-axm-echo
+```
+
+## License
+
+MIT — © 2026 Gabriel Jarry

axm_echo-0.1.0/docs/explanation/architecture.md

@@ -0,0 +1,58 @@
+# Architecture
+
+`axm-echo` is a flat set of single-responsibility modules — no `core/` /
+`adapters/` split, no hexagonal layering. The two `axm.tools` entry points
+(`echo_code`, `echo_check`) orchestrate a shared
+**corpus → embed → compare** pipeline; everything else is a leaf the tools
+compose.
+
+```mermaid
+graph TD
+    subgraph "Tools (axm.tools entry points)"
+        EchoCode["EchoCodeTool · echo_code"]
+        EchoCheck["EchoCheckTool · echo_check"]
+    end
+
+    subgraph "Pipeline"
+        Corpus["corpus · extract_package / extract_monorepo"]
+        Embedding["embedding · embed / neighbors (tfidf | st)"]
+        Cluster["cluster · cross_pairs / split_pairs / cluster_pairs"]
+        Waiver["waiver · cluster_hash / acknowledged"]
+    end
+
+    subgraph "Leaves"
+        Scope["scope · load_scope (~/axm/echo.toml)"]
+        Structural["structural · jaccard_similarity (stdlib, no torch)"]
+    end
+
+    EchoCode --> Corpus
+    EchoCode --> Embedding
+    EchoCode --> Cluster
+    EchoCode --> Waiver
+    EchoCheck --> Corpus
+    EchoCheck --> Embedding
+    Corpus --> Scope
+    Corpus -->|axm-ast| Embedding
+```
+
+## Modules
+
+| Module | Role |
+|---|---|
+| `tools` | The `echo_code` / `echo_check` `AXMTool`s (MCP + CLI + DAG node). They run the pipeline and shape the `ToolResult`. |
+| `corpus` | Extract public symbols from a package (`extract_package`) or the whole scope (`extract_monorepo`) via `axm-ast`; each `Symbol` carries an `embed_text`. |
+| `embedding` | The two backends behind `embed()` — `tfidf` (scikit-learn, pure CPU) and `st` (MiniLM, neural). `neighbors()` does exact cosine top-k. |
+| `cluster` | Cross-package candidate pairs (`cross_pairs`), the v7 anti-signal split (`split_pairs`: dupes / parallel-API / boilerplate), and union-find clustering. |
+| `waiver` | The acknowledged-cluster mechanism: a stable `cluster_hash` and the `[[tool.axm-echo.acknowledged]]` waiver lifecycle (mark / stale). |
+| `scope` | Resolve the workspace roots to scan from `~/axm/echo.toml`, degrading to the current directory when absent. |
+| `structural` | 100%-structural similarity over `ast.FunctionDef` bodies (`statement_set` + `jaccard_similarity`); pure stdlib, never loads torch. The primitive `duplicate_tests` reuses. |
+
+## Design decisions
+
+| Decision | Rationale |
+|---|---|
+| Neural by default (`st`/MiniLM) | Docstring similarity wants semantics; `torch` + `sentence-transformers` ship in the base install. |
+| `tfidf` backend kept | A pure-CPU opt-out for callers that must avoid loading torch — `embed(texts, backend="tfidf")` and `--backend tfidf`. |
+| Lazy torch import | `torch` is imported only inside the `st` backend, so the `tfidf` path stays light at runtime even though torch is installed. |
+| Flat modules, no hexagonal split | Each module is one concern with a small public surface; the tools compose them. No abstract ports to swap. |
+| Exact cosine (no ANN) | Corpora are monorepo-sized; brute-force matmul is exact and fast enough, with no index to maintain. |

axm_echo-0.1.0/docs/howto/index.md

@@ -0,0 +1,9 @@
+# How-To Guides
+
+Task-oriented guides for common workflows.
+
+## Available Guides
+
+- [Reuse check during planning with `echo_check`](reuse-check-in-planning.md) —
+  retrieve existing monorepo symbols for a ticket's intention and decide
+  reuse / extend / develop before drafting it.

axm_echo-0.1.0/docs/howto/reuse-check-in-planning.md

@@ -0,0 +1,78 @@
+# Reuse check during planning with `echo_check`
+
+When a plan is decomposed into tickets (the `/plan-tickets` workflow), every
+ticket whose scope is *"develop a helper / function / class that does X"*
+risks minting a duplicate of something the monorepo already provides — a
+fifth retry helper, a third CSV reader, another `slugify`. `echo_check`
+turns that risk into a deliberate decision.
+
+This guide shows how to wire `echo_check` into the planning step that
+gathers codebase intelligence, and how to act on its result.
+
+## When to run it
+
+Run the reuse check **only** for tickets that introduce *reusable
+behaviour* — a new unit worth deduplicating. Skip it for pure glue, config
+edits, dependency bumps, or scopes that are already "wire / refactor
+existing code": there is no new helper to deduplicate there.
+
+## 1. Retrieve the closest existing symbols
+
+Call `echo_check` on the **intention** — a free-form description of the
+behaviour the ticket would build:
+
+```python
+from axm_echo.tools import EchoCheckTool
+
+result = EchoCheckTool().execute(
+    intention="resilient HTTP call with retry on transient 5xx errors",
+)
+candidates = result.data["candidates"]
+```
+
+Via MCP / CLI the same call is `axm echo_check` or
+`axm_call(name="echo_check", arguments={"intention": "..."})`.
+
+Each candidate carries its `qualname`, `package`, `score`, full docstring
+(`doc_full`), a location `verdict`, and a `promotable` flag:
+
+| Field | Meaning |
+|---|---|
+| `verdict = "reuse_canonical"` | The hit lives in the canonical commons (`axm-ingot`) — reuse the canonical symbol directly. |
+| `verdict = "reuse_in_place"` | A real helper exists in some package but has not been canonicalised — reuse it **in place** from `<package>`; do not mint a duplicate just because it is not in the ingot yet. |
+| `promotable = True` | A well-documented non-ingot candidate worth canonicalising later. |
+
+An **empty** candidate list means nothing scored above the retrieval
+threshold — the intention is genuinely novel.
+
+## 2. Decide reuse / extend / develop — read the docstrings, not the score
+
+`echo_check` *retrieves and ranks*; it deliberately does **not** decide.
+A `PARTIAL` match (similar docstring, different contract) can outrank a
+perfect one, so never branch on the score or the verdict tag alone. Read
+each candidate's `doc_full` and signature, compare its real contract
+against the intention, and pick one branch:
+
+| Decision | When | Ticket effect |
+|---|---|---|
+| **reuse** | A candidate already does *exactly* what the intention needs. | Rewrite the ticket to *"import / reuse `<qualname>` from `<package>` + wire it in"*; drop the implementation tasks, keep only wiring + tests. |
+| **extend** | A candidate is the right *canonical* home but misses a parameter / mode / edge case. | Emit an **extension ticket** on `<qualname>` in `<package>`, and make the consumer ticket `blocks`-depend on it (extension lands first). |
+| **develop** | No candidate covers the intention (empty list, or all near-misses with a different contract). | Write the "develop a helper" ticket as normal. |
+
+## 3. Worked example
+
+Spec line: *"the screener needs a resilient HTTP call (retry on 5xx)."*
+
+```python
+EchoCheckTool().execute(
+    intention="resilient HTTP call with retry on transient errors",
+)
+```
+
+If a candidate like `request_with_retry [axm-commons]` comes back with a
+docstring matching the contract, **do not** emit "develop a retry helper".
+Emit a **reuse** ticket — *"reuse `request_with_retry` from `axm-commons`
+in the screener fetch path"* — with its implementation tasks dropped.
+
+If nothing matches (empty candidate list), the helper genuinely does not
+exist yet: emit the develop ticket.

axm_echo-0.1.0/docs/index.md

@@ -0,0 +1,98 @@
+---
+hide:
+  - navigation
+  - toc
+---
+
+# axm-echo
+
+<p align="center">
+  <strong>Neural similarity & echo detection over code corpora (MiniLM + scikit-learn).</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/axm-protocols/axm-forge-workspace/actions/workflows/ci.yml">
+    <img src="https://github.com/axm-protocols/axm-forge-workspace/actions/workflows/ci.yml/badge.svg" alt="CI" />
+  </a>
+  <a href="https://github.com/axm-protocols/axm-forge-workspace/actions/workflows/axm-quality.yml">
+    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge-workspace/gh-pages/badges/axm-echo/axm-init.json" alt="axm-init" />
+  </a>
+  <a href="https://github.com/axm-protocols/axm-forge-workspace/actions/workflows/axm-quality.yml">
+    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge-workspace/gh-pages/badges/axm-echo/axm-audit.json" alt="axm-audit" />
+  </a>
+  <a href="https://github.com/axm-protocols/axm-forge-workspace/actions/workflows/axm-quality.yml">
+    <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/axm-protocols/axm-forge-workspace/gh-pages/badges/axm-echo/coverage.json" alt="Coverage" />
+  </a>
+  <img src="https://img.shields.io/badge/python-3.12+-blue.svg" alt="Python 3.12+" />
+</p>
+
+---
+
+## Installation
+
+```bash
+# echo is neural by default — the install ships torch + sentence-transformers
+# (MiniLM) alongside numpy + scikit-learn.
+uv add axm-echo
+```
+
+The neural `st` backend is the in-process default. The `tfidf` backend stays
+pure-CPU and never loads torch, for callers that want to skip the model.
+
+## Quick Start
+
+```python
+from axm_echo import embed, extract_monorepo, neighbors
+
+# 1. Build a corpus of public symbols across the configured workspaces
+#    (driven by ~/axm/echo.toml, falling back to the current dir).
+symbols = extract_monorepo()
+texts = [s["embed_text"] for s in symbols]
+
+# 2. Embed it. "st" (MiniLM) is the neural default; "tfidf" stays pure-CPU.
+matrix = embed(texts, backend="tfidf")
+
+# 3. Find the nearest neighbours of a symbol (exact cosine top-k).
+for idx, score in neighbors(matrix[0], matrix, k=5):
+    print(f"{score:.3f}  {symbols[idx]['qualname']}")
+```
+
+## Features
+
+- ✅ **`echo_code` cross-package echo detection** — the `axm echo_code` tool
+  (MCP + CLI + DAG node) clusters intent-equivalent duplicate symbols across
+  packages, with the v7 anti-signals (trivial-accessor filter, parallel-API
+  demotion, boilerplate-frequency demotion) applied
+- ✅ **Liveable `echo_code` report** — bounded `--top-n` display (the neural
+  pass still finds them all, only the output is capped; the total stays
+  visible), `--max-cluster-size` rejection of union-find over-merges, and an
+  acknowledged-cluster **waiver** workflow (`[[tool.axm-echo.acknowledged]]`
+  in the scan-root `pyproject.toml`) that excludes intended echoes and reports
+  stale waivers to retire
+- ✅ **`echo_check` intent retrieval** — the `axm echo_check` tool
+  (MCP + CLI + DAG node) embeds a free-form intention and returns the top-k
+  nearest monorepo symbols with their docstrings, each tagged with a location
+  verdict (reuse canonical / reuse in place / promotable); it does the
+  retrieval, leaving the use / extend / nothing decision to the caller
+- ✅ **Structural similarity** — `statement_set` / `jaccard_similarity`
+  (with `flatten_body` / `normalize_dump`) compare two `ast.FunctionDef`
+  bodies by Jaccard over constant/identifier-normalized statement-sets;
+  100% structural, pure stdlib, never loads torch
+- ✅ **Two embedding backends** — `st` (MiniLM `all-MiniLM-L6-v2`, the neural
+  default) and `tfidf` (code, scikit-learn), selected by a registry
+- ✅ **Exact neighbour search** — brute-force cosine matmul, no ANN
+- ✅ **Lazy torch import** — `torch` + `sentence-transformers` ship in the
+  base install (neural-by-default), but torch is imported only inside the
+  `st` backend, so the `tfidf` path never loads it at runtime
+- ✅ **axm-ast corpus extractor** — public symbols with signature +
+  docstring, `embed_text` falling back to code when undocumented
+- ✅ **Scope loader** — `~/axm/echo.toml`, graceful degradation to the
+  current workspace
+- ✅ **Modern Python** — 3.12+ with strict typing
+
+---
+
+<div style="text-align: center; margin: 2rem 0;">
+  <a href="tutorials/getting-started/" class="md-button md-button--primary">Get Started →</a>
+  <a href="reference/cli/" class="md-button">Reference</a>
+</div>

axm_echo-0.1.0/docs/reference/cli.md

@@ -0,0 +1,136 @@
+# CLI Reference
+
+## Commands
+
+### `axm echo_code`
+
+Detect cross-package code **echoes** — intent-equivalent duplicate symbols
+across the configured monorepo. The tool walks the scope, embeds every public
+documented symbol, finds cross-package pairs whose docstrings are semantically
+close, applies the v7 anti-signals, and prints the surviving **clusters** plus
+the demoted parallel-API / boilerplate buckets.
+
+The command is auto-registered from the `axm.tools` entry point, so the same
+implementation is reachable as an MCP tool and a DAG `tool_node` too.
+
+```bash
+# Cluster echoes across the corpus (~/axm/echo.toml scope, or the cwd).
+axm echo_code
+
+# The default backend is neural "st" (MiniLM, in-process). Opt into the
+# pure-CPU tfidf backend to avoid loading torch.
+axm echo_code --backend tfidf
+
+# Raise the cosine floor for a candidate pair (default 0.55).
+axm echo_code --threshold 0.7
+
+# Show only the 10 nearest actionable clusters (the total stays in the header).
+axm echo_code --top-n 10
+
+# Tighten the over-merge guard (default 50): drop any component above 20.
+axm echo_code --max-cluster-size 20
+```
+
+| Option | Default | Description |
+| -- | -- | -- |
+| `--backend` | `st` | Embedding backend: `st` (neural MiniLM, the in-process default) or `tfidf` (pure CPU, no torch). |
+| `--threshold` | `0.55` | Minimum cosine similarity for a candidate pair. |
+| `--top-n` | `30` | Bound the report to the N nearest *non-acknowledged* clusters. The neural pass still finds them all — only the display is bounded; the total count stays in the header. |
+| `--max-cluster-size` | `50` | Reject any connected component larger than this as a union-find over-merge (a structural-conformity signal, not a duplicate echo — a genuine duplicate is 2-5 members). |
+
+Output names the tool, the live/shown/actionable cluster counts, the corpus
+size, and the demoted buckets, then lists each shown cluster's members with
+their package and docstring first line:
+
+```text
+echo_code | 8 clusters, 3 shown (8 actionable) | corpus 16 symbols | 0 parallel-API · 0 boilerplate (demoted)
+
+cluster 1  sim=1.000  (2 symbols)
+  axm_commons.errors.RateLimitError  [axm-commons]  “Raised when the upstream API rate limit has been exceeded.”
+  axm_bib.errors.RateLimitError  [axm-bib]  “Raised when the upstream API rate limit has been exceeded.”
+```
+
+#### Acknowledging a cluster (waiver)
+
+A genuine cross-package echo that is *intended* (a parallel API, a deliberate
+wrapper) is noise on every run. Acknowledge it in the **scan-root** `pyproject.toml`
+(the first workspace root in `~/axm/echo.toml`) so it drops out of the
+actionable top-N. Each entry is a 12-hex `cluster_hash` (printed in the tool's
+`data.clusters[*].cluster_hash`) plus a non-empty `reason`:
+
+```toml
+[[tool.axm-echo.acknowledged]]
+hash = "ca29d81fb73c"
+reason = "parallel API, intended cross-package duplication"
+```
+
+An acknowledged *live* cluster is marked `acknowledged` and excluded from the
+top-N and the `actionable_count`. The mechanism is self-cleaning: a waiver whose
+hash no longer matches any live cluster is reported under
+`data.stale_acknowledged` ("this waiver no longer serves a purpose, retire it")
+— informative, never blocking. A malformed entry (bad hash, empty reason) is
+rejected gracefully into `data.acknowledged_errors`; the run never crashes.
+
+### `axm echo_check`
+
+Retrieve the public symbols closest to a free-form **intention**, ranked by
+semantic similarity across the whole monorepo. Before writing a new helper,
+ask `echo_check` what already exists: it embeds the intention, returns the
+top-k nearest documented symbols with their docstrings, and tags each with a
+location **verdict** so you know whether to reuse the canonical symbol, reuse
+one in place, or promote it.
+
+The verdict is a *location* tag, not a decision: a high score means "this is
+the closest existing promise", never "use this". The use / extend / nothing
+call is left to the calling agent — a partial match may legitimately score
+above an exact one.
+
+Like `echo_code`, the command is auto-registered from the `axm.tools` entry
+point, so the same implementation is reachable as an MCP tool and a DAG
+`tool_node` too.
+
+```bash
+# Retrieve the closest existing symbols for an intention.
+axm echo_check --intention "HTTP request with retry and backoff"
+
+# The default backend is neural "st" (MiniLM, in-process). Opt into the
+# pure-CPU tfidf backend to avoid loading torch.
+axm echo_check --intention "slugify a string" --backend tfidf
+
+# Raise the retrieval floor / cap the number of candidates.
+axm echo_check --intention "parse a CSV file" --threshold 0.5 --k 3
+```
+
+| Option | Default | Description |
+| -- | -- | -- |
+| `--intention` | `""` | Free-form description of the behaviour to implement. |
+| `--backend` | `st` | Embedding backend: `st` (neural MiniLM, the in-process default) or `tfidf` (pure CPU, no torch). |
+| `--k` | `10` | Maximum number of candidates to return. |
+| `--threshold` | `0.30` | Minimum cosine similarity for a candidate to be retrieved. Below it the candidate is dropped, so a novel intention returns an empty list rather than a spurious match. |
+
+The verdict is set by the candidate's package: a hit in `axm-ingot` is
+`reuse_canonical`; anything else is `reuse_in_place` (with a `promotable→ingot`
+hint when the symbol is documented well enough to be worth canonicalising).
+
+Output names the tool, the intention, the candidate count, and the corpus
+size, then lists each ranked candidate with its package, similarity, verdict
+and docstring first line:
+
+```text
+echo_check | “HTTP request with retry and backoff” | 1 candidates | corpus 2 symbols
+
+1. axm_ingot.net.fetch_url  [axm-ingot]  sim=0.762  reuse_canonical
+   "Perform an HTTP request, retrying with backoff on transient errors."
+```
+
+When nothing crosses the threshold the report says so explicitly, rather than
+surfacing a weak false match:
+
+```text
+echo_check | “render a mermaid sequence diagram” | 0 candidates | corpus 2 symbols
+(no candidate above threshold — likely novel)
+```
+
+## Python API
+
+Auto-generated API reference is available under [Python API](api/).