rag-your-code 0.4.2__tar.gz → 0.5.0__tar.gz

{rag_your_code-0.4.2/src/rag_your_code.egg-info → rag_your_code-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rag-your-code
-Version: 0.4.2
+Version: 0.5.0
 Summary: A local, explainable RAG index for codebases and coding agents
 Author: rag-your-code contributors
 License-Expression: MIT
@@ -153,7 +153,15 @@ callees listed, the docstring appended. It introduces no vocabulary the source
 did not already have — which is exactly why retrieval cannot reach a concept
 nobody wrote down.
 
-The agent already reading the index can supply those words:
+**First, the documentation you already wrote is indexed.** Fourteen of the
+fifteen supported languages put documentation immediately above a declaration
+— JSDoc, Javadoc, KDoc, rustdoc, Go doc comments, XML doc comments, PHPDoc —
+and a unit's span begins at the declaration, so all of it used to sit outside
+the index. The same sentence reached thirteen searchable words as a Python
+docstring and two as a JavaScript comment. Now both reach thirteen. Commented-
+out code, separator rules and licence headers are deliberately left out.
+
+**Where there is none, the agent can write it:**
 
 ```bash
 rag-your-code describe status              # coverage, and what is pending
@@ -165,23 +173,43 @@ rag-your-code index .                      # apply it
 or, in the protocol, `describe_pending` and `describe_put` — which take effect
 in the same session, with no refresh.
 
+**And you can move it into the code**, where it needs no bookkeeping at all:
+
+```bash
+rag-your-code describe promote | git apply    # review it first
+```
+
+That emits a unified diff adding a doc comment in each language's own
+convention, for declarations that have none. The tool still never writes your
+source. Only the half meant for a reader is promoted, so a bilingual
+description leaves its second language in the store where retrieval still uses
+it — measured, promoting all 68 on this repository discarded no description
+and left Chinese retrieval unchanged.
+
 ### Measured on this repository
 
-This project describes its own implementation: all 120 units under `src/`
-carry an agent-written bilingual description, committed to the repo. Ten
-natural-language questions about the codebase, before and after:
+This project describes its own implementation: every unit under `src/` carries
+an agent-written bilingual description, committed to the repo, and 68 of them
+have been promoted into the source as doc comments.
 
-| | before | after |
+Seventy natural-language questions about this codebase, in English and
+Chinese, each listing every unit that genuinely answers it
+([`benchmarks/repo_queries.json`](benchmarks/repo_queries.json)):
+
+| | generated descriptions | agent-written |
 |---|---|---|
-| top result in the expected file | 2 / 8 | **6 / 8** |
-| Chinese-language queries | 0 / 4 | **3 / 4** |
-| queries with **no shared word at all** (pure fallback) | 4 | **0** |
+| hit@1 | 0.171 | **0.500** |
+| hit@3 | 0.314 | **0.729** |
+| MRR | 0.240 | **0.605** |
+| answered with no shared word at all | 15.7% | **0%** |
+
+Roughly a threefold improvement in first-place accuracy. Nineteen questions
+still fail, which is what makes the set usable for measuring the next change;
+`tests/test_repo_queries.py` asserts that some question always does.
 
-Two still miss, and both are worth stating. One query says `catastrophic
-backtracking` where the description says `backtracks catastrophically`: there
-is no stemming, so those share no word — exactly the limit documented above.
-The other returned a unit that answers the question from a different file than
-predicted, so the expectation was wrong rather than the retrieval.
+One failure is worth naming: a query saying `catastrophic backtracking` does
+not reach a description saying `backtracks catastrophically`. There is no
+stemming — exactly the limit documented above.
 
 **What this is:** it moves the semantic work from query time to index time.
 Matching stays lexical. It is LLM-authored keyword expansion, and its reach is
@@ -230,7 +258,7 @@ Directional local measurements, not service levels; the archived run is
 **Suite:** Python 3.10 – 3.13 on Linux and Windows, plus a job that installs
 the built wheel into a clean environment and runs every command the
 documentation prescribes, and another that runs the skill's own install line
-verbatim. 208 tests as of 0.4.2 — the count is version-stamped rather than
+verbatim. 248 tests as of 0.5.0 — the count is version-stamped rather than
 maintained, because a bare figure in a living document is a claim that rots;
 per-release counts are in [CHANGELOG.md](CHANGELOG.md).
 

{rag_your_code-0.4.2 → rag_your_code-0.5.0}/README.md

@@ -126,7 +126,15 @@ callees listed, the docstring appended. It introduces no vocabulary the source
 did not already have — which is exactly why retrieval cannot reach a concept
 nobody wrote down.
 
-The agent already reading the index can supply those words:
+**First, the documentation you already wrote is indexed.** Fourteen of the
+fifteen supported languages put documentation immediately above a declaration
+— JSDoc, Javadoc, KDoc, rustdoc, Go doc comments, XML doc comments, PHPDoc —
+and a unit's span begins at the declaration, so all of it used to sit outside
+the index. The same sentence reached thirteen searchable words as a Python
+docstring and two as a JavaScript comment. Now both reach thirteen. Commented-
+out code, separator rules and licence headers are deliberately left out.
+
+**Where there is none, the agent can write it:**
 
 ```bash
 rag-your-code describe status              # coverage, and what is pending
@@ -138,23 +146,43 @@ rag-your-code index .                      # apply it
 or, in the protocol, `describe_pending` and `describe_put` — which take effect
 in the same session, with no refresh.
 
+**And you can move it into the code**, where it needs no bookkeeping at all:
+
+```bash
+rag-your-code describe promote | git apply    # review it first
+```
+
+That emits a unified diff adding a doc comment in each language's own
+convention, for declarations that have none. The tool still never writes your
+source. Only the half meant for a reader is promoted, so a bilingual
+description leaves its second language in the store where retrieval still uses
+it — measured, promoting all 68 on this repository discarded no description
+and left Chinese retrieval unchanged.
+
 ### Measured on this repository
 
-This project describes its own implementation: all 120 units under `src/`
-carry an agent-written bilingual description, committed to the repo. Ten
-natural-language questions about the codebase, before and after:
+This project describes its own implementation: every unit under `src/` carries
+an agent-written bilingual description, committed to the repo, and 68 of them
+have been promoted into the source as doc comments.
 
-| | before | after |
+Seventy natural-language questions about this codebase, in English and
+Chinese, each listing every unit that genuinely answers it
+([`benchmarks/repo_queries.json`](benchmarks/repo_queries.json)):
+
+| | generated descriptions | agent-written |
 |---|---|---|
-| top result in the expected file | 2 / 8 | **6 / 8** |
-| Chinese-language queries | 0 / 4 | **3 / 4** |
-| queries with **no shared word at all** (pure fallback) | 4 | **0** |
+| hit@1 | 0.171 | **0.500** |
+| hit@3 | 0.314 | **0.729** |
+| MRR | 0.240 | **0.605** |
+| answered with no shared word at all | 15.7% | **0%** |
+
+Roughly a threefold improvement in first-place accuracy. Nineteen questions
+still fail, which is what makes the set usable for measuring the next change;
+`tests/test_repo_queries.py` asserts that some question always does.
 
-Two still miss, and both are worth stating. One query says `catastrophic
-backtracking` where the description says `backtracks catastrophically`: there
-is no stemming, so those share no word — exactly the limit documented above.
-The other returned a unit that answers the question from a different file than
-predicted, so the expectation was wrong rather than the retrieval.
+One failure is worth naming: a query saying `catastrophic backtracking` does
+not reach a description saying `backtracks catastrophically`. There is no
+stemming — exactly the limit documented above.
 
 **What this is:** it moves the semantic work from query time to index time.
 Matching stays lexical. It is LLM-authored keyword expansion, and its reach is
@@ -203,7 +231,7 @@ Directional local measurements, not service levels; the archived run is
 **Suite:** Python 3.10 – 3.13 on Linux and Windows, plus a job that installs
 the built wheel into a clean environment and runs every command the
 documentation prescribes, and another that runs the skill's own install line
-verbatim. 208 tests as of 0.4.2 — the count is version-stamped rather than
+verbatim. 248 tests as of 0.5.0 — the count is version-stamped rather than
 maintained, because a bare figure in a living document is a claim that rots;
 per-release counts are in [CHANGELOG.md](CHANGELOG.md).
 

{rag_your_code-0.4.2 → rag_your_code-0.5.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "rag-your-code"
-version = "0.4.2"
+version = "0.5.0"
 description = "A local, explainable RAG index for codebases and coding agents"
 readme = "README.md"
 requires-python = ">=3.10"

{rag_your_code-0.4.2 → rag_your_code-0.5.0/src/rag_your_code.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rag-your-code
-Version: 0.4.2
+Version: 0.5.0
 Summary: A local, explainable RAG index for codebases and coding agents
 Author: rag-your-code contributors
 License-Expression: MIT
@@ -153,7 +153,15 @@ callees listed, the docstring appended. It introduces no vocabulary the source
 did not already have — which is exactly why retrieval cannot reach a concept
 nobody wrote down.
 
-The agent already reading the index can supply those words:
+**First, the documentation you already wrote is indexed.** Fourteen of the
+fifteen supported languages put documentation immediately above a declaration
+— JSDoc, Javadoc, KDoc, rustdoc, Go doc comments, XML doc comments, PHPDoc —
+and a unit's span begins at the declaration, so all of it used to sit outside
+the index. The same sentence reached thirteen searchable words as a Python
+docstring and two as a JavaScript comment. Now both reach thirteen. Commented-
+out code, separator rules and licence headers are deliberately left out.
+
+**Where there is none, the agent can write it:**
 
 ```bash
 rag-your-code describe status              # coverage, and what is pending
@@ -165,23 +173,43 @@ rag-your-code index .                      # apply it
 or, in the protocol, `describe_pending` and `describe_put` — which take effect
 in the same session, with no refresh.
 
+**And you can move it into the code**, where it needs no bookkeeping at all:
+
+```bash
+rag-your-code describe promote | git apply    # review it first
+```
+
+That emits a unified diff adding a doc comment in each language's own
+convention, for declarations that have none. The tool still never writes your
+source. Only the half meant for a reader is promoted, so a bilingual
+description leaves its second language in the store where retrieval still uses
+it — measured, promoting all 68 on this repository discarded no description
+and left Chinese retrieval unchanged.
+
 ### Measured on this repository
 
-This project describes its own implementation: all 120 units under `src/`
-carry an agent-written bilingual description, committed to the repo. Ten
-natural-language questions about the codebase, before and after:
+This project describes its own implementation: every unit under `src/` carries
+an agent-written bilingual description, committed to the repo, and 68 of them
+have been promoted into the source as doc comments.
 
-| | before | after |
+Seventy natural-language questions about this codebase, in English and
+Chinese, each listing every unit that genuinely answers it
+([`benchmarks/repo_queries.json`](benchmarks/repo_queries.json)):
+
+| | generated descriptions | agent-written |
 |---|---|---|
-| top result in the expected file | 2 / 8 | **6 / 8** |
-| Chinese-language queries | 0 / 4 | **3 / 4** |
-| queries with **no shared word at all** (pure fallback) | 4 | **0** |
+| hit@1 | 0.171 | **0.500** |
+| hit@3 | 0.314 | **0.729** |
+| MRR | 0.240 | **0.605** |
+| answered with no shared word at all | 15.7% | **0%** |
+
+Roughly a threefold improvement in first-place accuracy. Nineteen questions
+still fail, which is what makes the set usable for measuring the next change;
+`tests/test_repo_queries.py` asserts that some question always does.
 
-Two still miss, and both are worth stating. One query says `catastrophic
-backtracking` where the description says `backtracks catastrophically`: there
-is no stemming, so those share no word — exactly the limit documented above.
-The other returned a unit that answers the question from a different file than
-predicted, so the expectation was wrong rather than the retrieval.
+One failure is worth naming: a query saying `catastrophic backtracking` does
+not reach a description saying `backtracks catastrophically`. There is no
+stemming — exactly the limit documented above.
 
 **What this is:** it moves the semantic work from query time to index time.
 Matching stays lexical. It is LLM-authored keyword expansion, and its reach is
@@ -230,7 +258,7 @@ Directional local measurements, not service levels; the archived run is
 **Suite:** Python 3.10 – 3.13 on Linux and Windows, plus a job that installs
 the built wheel into a clean environment and runs every command the
 documentation prescribes, and another that runs the skill's own install line
-verbatim. 208 tests as of 0.4.2 — the count is version-stamped rather than
+verbatim. 248 tests as of 0.5.0 — the count is version-stamped rather than
 maintained, because a bare figure in a living document is a claim that rots;
 per-release counts are in [CHANGELOG.md](CHANGELOG.md).
 

{rag_your_code-0.4.2 → rag_your_code-0.5.0}/src/rag_your_code.egg-info/SOURCES.txt

@@ -13,6 +13,7 @@ src/ragyourcode/annotate.py
 src/ragyourcode/cli.py
 src/ragyourcode/config.py
 src/ragyourcode/descriptions.py
+src/ragyourcode/document.py
 src/ragyourcode/embeddings.py
 src/ragyourcode/graph.py
 src/ragyourcode/indexer.py
@@ -24,6 +25,8 @@ tests/test_agent_protocol.py
 tests/test_agentic.py
 tests/test_config.py
 tests/test_descriptions.py
+tests/test_doc_comments.py
+tests/test_document.py
 tests/test_e2e_cli.py
 tests/test_golden.py
 tests/test_graph_incremental.py
@@ -33,5 +36,6 @@ tests/test_metadata.py
 tests/test_multilanguage.py
 tests/test_parser_edges.py
 tests/test_ragyourcode.py
+tests/test_repo_queries.py
 tests/test_resilience.py
 tests/test_retrieval_correctness.py

{rag_your_code-0.4.2 → rag_your_code-0.5.0}/src/ragyourcode/__init__.py

@@ -3,4 +3,4 @@
 from .models import CodeUnit, SearchResult
 
 __all__ = ["CodeUnit", "SearchResult"]
-__version__ = "0.4.2"
+__version__ = "0.5.0"

{rag_your_code-0.4.2 → rag_your_code-0.5.0}/src/ragyourcode/agentic.py

@@ -8,10 +8,17 @@ from .search import DEFAULT_VECTOR_WEIGHT, SearchIndex, search
 
 
 def _result_ids(results: list[SearchResult]) -> set[str]:
+    """Collects the unit identifiers out of a list of search results, so two
+    result sets can be compared for overlap or novelty. Used to decide
+    whether a second retrieval round actually surfaced anything new.
+    """
     return {result.unit.id for result in results}
 
 
 def _serialize(results: list[SearchResult]) -> list[dict]:
+    """Converts search results into plain JSON-ready dictionaries for the agent
+    protocol reply.
+    """
     return [result.to_dict() for result in results]
 
 

{rag_your_code-0.4.2 → rag_your_code-0.5.0}/src/ragyourcode/annotate.py

@@ -7,11 +7,22 @@ import re
 
 
 def _humanize(name: str) -> str:
+    """Turns a programmer identifier into ordinary words: splits camelCase
+    apart, replaces underscores with spaces, lowercases the result. Empty
+    input becomes a placeholder rather than an empty string.
+    """
     words = re.sub(r"([a-z0-9])([A-Z])", r"\1 \2", name).replace("_", " ").split()
     return " ".join(words).strip().lower() or "anonymous unit"
 
 
 def describe_python(node: ast.AST, source: str, calls: list[str], imports: list[str]) -> str:
+    """Builds a readable sentence about a Python function or class without
+    using a language model: the humanised name, the arguments it accepts,
+    the functions it calls, the modules it uses, and the docstring appended
+    verbatim as stated intent. Because it only rearranges words already in
+    the source, it adds no vocabulary the code did not have, which is why
+    retrieval cannot reach a concept nobody wrote down.
+    """
     name = getattr(node, "name", "anonymous")
     kind = "method" if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)) else "class"
     args = []

{rag_your_code-0.4.2 → rag_your_code-0.5.0}/src/ragyourcode/cli.py

@@ -14,9 +14,10 @@ from .annotate import comment_for
 from .agentic import research
 from .config import BY_PATH, SETTINGS, Config, ConfigError
 from .descriptions import DescriptionStore, guidance, index_descriptions_fingerprint
+from .document import plan as plan_documentation, render_patch, summarise as summarise_documentation
 from .embeddings import embed, embedding_metadata
 from .graph import build_graph, graph_from_dict, graph_search
-from .indexer import StaleMonitor, build_units, fingerprint, index_config_fingerprint, read_index, snapshot_repository, write_index
+from .indexer import StaleMonitor, build_fingerprint, build_units, fingerprint, index_build_fingerprint, read_index, snapshot_repository, write_index
 from .search import build_search_index, context, search
 
 # Derived from the settings table so the default is written down once.
@@ -26,10 +27,24 @@ MAX_OPEN_CHARS = BY_PATH["agent.max_open_chars"].default
 
 
 def _default_index(root: Path) -> Path:
+    """Where a repository index file is kept when the caller names no other
+    location.
+    """
     return root / ".rag-your-code" / "index.json"
 
 
 def _refresh_index(root: Path, output: Path, full: bool = False, compact: bool | None = None, cfg: Config | None = None) -> dict:
+    """Builds or rebuilds a repository index and publishes it, reusing the
+    previous one where it can. It works out up front whether the rules that
+    decide what a unit is have changed — the indexing settings, the vector
+    width, or the parser itself — and when they have it discards the
+    previous work rather than reusing it, so the report can honestly say
+    whether reuse happened. That report previously claimed reuse on exactly
+    the runs that had rebuilt everything, because it was computed from
+    whether a previous index existed rather than from whether its units were
+    kept. It also applies the written descriptions and reports how many
+    units still have none.
+    """
     cfg = cfg if cfg is not None else config_module.load(root)
     previous_payload: dict = {}
     previous_units = []
@@ -48,9 +63,9 @@ def _refresh_index(root: Path, output: Path, full: bool = False, compact: bool |
     # rather than only inside build_units is what lets the reported
     # `incremental` describe what the run actually did: it claimed reuse on
     # exactly the runs where the configuration change had forbidden it.
-    previous_config = index_config_fingerprint(previous_payload) if previous_payload else None
-    config_changed = previous_config is not None and previous_config != cfg.build_fingerprint
-    if config_changed:
+    previous_build = index_build_fingerprint(previous_payload) if previous_payload else None
+    inputs_changed = previous_build is not None and previous_build != build_fingerprint(cfg)
+    if inputs_changed:
         previous_payload, previous_units = {}, []
     diagnostics: list[dict] = []
     # One snapshot for both halves: parsing from one walk and publishing hashes
@@ -64,7 +79,7 @@ def _refresh_index(root: Path, output: Path, full: bool = False, compact: bool |
         diagnostics=diagnostics,
         snapshot=snapshot,
         cfg=cfg,
-        previous_config=None if config_changed else previous_config,
+        previous_build=None if inputs_changed else previous_build,
         descriptions=store,
     )
     graph = build_graph(units)
@@ -75,7 +90,7 @@ def _refresh_index(root: Path, output: Path, full: bool = False, compact: bool |
         "graph_edges": len(graph.edges),
         "warnings": len(diagnostics),
         "incremental": bool(previous_units) and not full,
-        "rebuilt_for_config": config_changed,
+        "rebuilt_for_inputs": inputs_changed,
         "compact": bool(compact),
         "described": len(groups["described"]),
         "pending_descriptions": len(groups["missing"]) + len(groups["superseded"]),
@@ -86,6 +101,10 @@ def _refresh_index(root: Path, output: Path, full: bool = False, compact: bool |
 
 
 def _cmd_index(args: argparse.Namespace) -> int:
+    """The index command: scans a repository and writes its index, reporting
+    how many units and relationships were found and how many descriptions
+    are still pending.
+    """
     root = Path(args.root).resolve()
     cfg = config_module.load(root)
     output = Path(args.output) if args.output else _default_index(root)
@@ -94,6 +113,13 @@ def _cmd_index(args: argparse.Namespace) -> int:
 
 
 def _load(args: argparse.Namespace):
+    """Opens a published index for a read-only command and settles whether it
+    is still current. Three things can make it out of date and only one of
+    them is a file edit: the repository content can have moved, the rules
+    that decide what a unit is can have changed, or the written descriptions
+    can have changed. Neither authored input nor the parser is an indexed
+    file, so each has to report itself.
+    """
     root = Path(args.root).resolve()
     cfg = config_module.load(root)
     store = descriptions_module.load(root)
@@ -105,7 +131,7 @@ def _load(args: argparse.Namespace):
         # descriptions mean it serves text nobody wrote any more. Neither moves
         # a tracked file, so each has to report itself.
         stale = payload.get("fingerprint") != fingerprint(root, cfg)
-        stale = stale or index_config_fingerprint(payload) != cfg.build_fingerprint
+        stale = stale or index_build_fingerprint(payload) != build_fingerprint(cfg)
         payload["stale"] = stale or index_descriptions_fingerprint(payload) != store.fingerprint
     except OSError:
         payload["stale"] = True
@@ -113,6 +139,13 @@ def _load(args: argparse.Namespace):
 
 
 def _cmd_search(args: argparse.Namespace) -> int:
+    """The search command: retrieves the code units most relevant to a
+    question, optionally following relationships outward, and prints either
+    a readable context block or machine-readable output for an agent. Result
+    count, context budget and the balance between word overlap and vector
+    similarity all fall back to the repository settings when no flag
+    overrides them. Warns when the index no longer describes the repository.
+    """
     payload, units, graph, cfg, _ = _load(args)
     limit = args.limit if args.limit is not None else cfg["search.limit"]
     max_chars = args.max_chars if args.max_chars is not None else cfg["search.max_chars"]
@@ -133,6 +166,12 @@ def _cmd_search(args: argparse.Namespace) -> int:
 
 
 def _cmd_annotate(args: argparse.Namespace) -> int:
+    """The annotate command: writes a numbered inventory of every indexed unit
+    to a separate document, with its location, kind and description. Source
+    files are never touched. Refuses to run against an index that no longer
+    describes the repository, since a numbered inventory of stale code is
+    worse than none.
+    """
     payload, units, _, _, _ = _load(args)
     if payload.get("stale"):
         print("Index is stale; run `rag-your-code index` before annotating.", file=sys.stderr)
@@ -148,6 +187,14 @@ def _cmd_annotate(args: argparse.Namespace) -> int:
 
 
 def _cmd_config(args: argparse.Namespace) -> int:
+    """The config command: creates a commented settings file, lists every
+    setting with its effective value and whether it was customised, reads
+    one value, changes one value in place, or reports where the file lives.
+    Changing a value refuses anything out of range before writing, so a
+    rejected change leaves the file exactly as it was, and the reply says
+    whether the change forces a full rebuild. Creating refuses to overwrite
+    an existing file unless told to.
+    """
     root = Path(args.root).resolve()
     path = config_module.config_path(root)
     if args.action == "path":
@@ -293,7 +340,38 @@ def _apply_descriptions(units: list, store: DescriptionStore, cfg: Config) -> in
 
 
 def _cmd_describe(args: argparse.Namespace) -> int:
+    """The describe command: reports how many units have a usable description,
+    how many have one the code has since outgrown and how many have none;
+    exports a batch of pending work with source and brief; imports written
+    descriptions back; or emits a patch that moves a description into the
+    source as a doc comment. Importing says explicitly that a rebuild is
+    needed, because the published index still holds the previous wording and
+    no source file moved to signal it. The patch owns standard output so it
+    can be piped straight into git apply.
+    """
     payload, units, _, cfg, store = _load(args)
+    if args.action == "promote":
+        # A stored description exists so text about a unit can be written
+        # without touching the file, and that independence costs a digest, a
+        # relocation lookup, a fingerprint and a pruning rule -- all of them
+        # simulating a property a docstring has for free. This offers the
+        # promotion as a patch rather than performing it: the tool still never
+        # writes source, and a person stays between an agent's prose and the
+        # repository.
+        root = Path(args.root).resolve()
+        insertions = plan_documentation(units, store, root)
+        report = summarise_documentation(units, store, insertions, root)
+        patch = render_patch(root, insertions)
+        if args.output:
+            Path(args.output).write_text(patch, encoding="utf-8", newline="")
+            report["output"] = args.output
+            print(json.dumps(report, ensure_ascii=False, indent=2))
+        else:
+            # The patch owns stdout so it can be piped straight into `git
+            # apply`; the summary goes to stderr.
+            sys.stdout.write(patch)
+            print(json.dumps(report, ensure_ascii=False), file=sys.stderr)
+        return 0
     if args.action == "status":
         groups = store.classify(units)
         print(json.dumps({
@@ -484,6 +562,13 @@ def _cmd_agent(args: argparse.Namespace) -> int:
 
 
 def build_parser() -> argparse.ArgumentParser:
+    """Declares the whole command-line surface: indexing, retrieval,
+    annotation, the long-running agent, settings, and descriptions including
+    the promotion patch, with their options and help text. Options that have
+    a configurable counterpart default to nothing rather than to a literal,
+    so an unset flag means whatever the repository configured instead of a
+    number frozen into the program.
+    """
     parser = argparse.ArgumentParser(prog="rag-your-code", description="Index and retrieve explainable code units locally.")
     sub = parser.add_subparsers(dest="command", required=True)
     index = sub.add_parser("index", help="scan a repository and build its local index")
@@ -522,12 +607,12 @@ def build_parser() -> argparse.ArgumentParser:
     config_parser.add_argument("--force", action="store_true", help="with init, overwrite an existing file")
     config_parser.set_defaults(func=_cmd_config)
     describe = sub.add_parser("describe", help="inspect or supply agent-authored unit descriptions")
-    describe.add_argument("action", choices=("status", "export", "import"))
+    describe.add_argument("action", choices=("status", "export", "import", "promote"))
     describe.add_argument("file", nargs="?", help="with import, a JSON file of {id, text} objects")
     describe.add_argument("--root", default=".")
     describe.add_argument("--index")
     describe.add_argument("--limit", type=int, default=None, help=f"with export, units per batch (config describe.batch, default {BY_PATH['describe.batch'].default})")
-    describe.add_argument("--output", help="with export, write the batch here instead of stdout")
+    describe.add_argument("--output", help="with export or promote, write here instead of stdout")
     describe.set_defaults(func=_cmd_describe)
     return parser
 
@@ -557,6 +642,12 @@ def _use_utf8_streams() -> None:
 
 
 def main(argv: list[str] | None = None) -> int:
+    """The program entry point: pins the streams, parses the command line, runs
+    the chosen command, and turns an expected failure into a message and a
+    non-zero exit code instead of a stack trace. A settings problem is
+    reported separately and names the file, because that fix is always in
+    one known place.
+    """
     _use_utf8_streams()
     args = build_parser().parse_args(argv)
     try: