rag-your-code 1.1.0__tar.gz → 1.2.0__tar.gz

{rag_your_code-1.1.0/src/rag_your_code.egg-info → rag_your_code-1.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rag-your-code
-Version: 1.1.0
+Version: 1.2.0
 Summary: A local, explainable RAG index for codebases and coding agents
 Author: rag-your-code contributors
 License-Expression: MIT
@@ -129,7 +129,7 @@ the scale.
 
 The default embedder is a signed feature hash. Ablating it entirely moves the
 three positive rulers by **±1 question in either direction** while the vectors
-occupy **65.4%** of the index. That was known since 0.6.0 and left unexplained.
+occupy **65.3%** of the index. That was known since 0.6.0 and left unexplained.
 The explanation, measured here:
 
 - **Not saturation.** Median 56 distinct tokens per unit into 384 buckets;
@@ -323,9 +323,9 @@ it answers a different question and names a different diagnosis.
 
 | | |
 |---|---|
-| query, median | **0.41 ms** |
-| query, p95 | 0.60 ms |
-| refusing an unanswerable query | **0.01 ms** |
+| query, median | **0.83 ms** |
+| query, p95 | 1.68 ms |
+| refusing an unanswerable query | **0.03 ms** |
 
 Refusal is cheaper than answering by a factor of forty: an unanswerable query
 touches only the posting lists of its own distinctive words, never the corpus.
@@ -364,22 +364,22 @@ declaration spans.
 **On a repository nobody has described, Grep wins.** That is the measured
 result and it is not softened here.
 
-| foreign repository · 35 questions · 1,257 units · no descriptions | Grep loop | rag-your-code |
+| foreign repository · 35 questions · 1,267 units · no descriptions | Grep loop | rag-your-code |
 |---|---|---|
 | right file first | **34.3%** | 31.4% |
 | right file in top 3 | **60.0%** | 48.6% |
-| lines matched across the repo, all questions | 33,115 | — |
-| characters returned, all questions | — | **163,521** |
+| lines matched across the repo, all questions | 33,213 | — |
+| characters returned, all questions | — | **163,294** |
 | questions it answers | 35 | 28 |
 
 **Once the vocabulary exists, it is not close.**
 
-| this repository · 70 questions · 557 units · 303 described | Grep loop | rag-your-code |
+| this repository · 70 questions · 569 units · 304 described | Grep loop | rag-your-code |
 |---|---|---|
-| right file first | 25.7% | **57.1%** |
+| right file first | 25.7% | **58.6%** |
 | right file in top 3 | 64.3% | **75.7%** |
-| lines matched across the repo, all questions | 39,550 | — |
-| characters returned, all questions | — | **278,929** |
+| lines matched across the repo, all questions | 40,150 | — |
+| characters returned, all questions | — | **277,327** |
 | questions it answers | 70 | 60 |
 
 Those two tables are the whole argument of section 3.3, measured against a real
@@ -396,7 +396,7 @@ Three qualifications, because the table would otherwise flatter both sides:
   file; a hit here is a declaration with an exact span, a score, and the words
   it matched on. The agent that reads the result opens 40 lines, not a file.
 - **Grep answers everything.** It never declines, which is why it hands back
-  33,115 matching lines for 35 questions — about 950 lines per question, no
+  33,213 matching lines for 35 questions — about 950 lines per question, no
   ranking, no spans, no indication which match is the definition. This returns
   roughly 5,800 characters per question, ranked. Seven of 35 and ten of 70
   questions come back empty here instead, with a reason.
@@ -527,9 +527,21 @@ measured worse, so it stays off there.
 /reload-plugins
 ```
 
-One skill, no hooks, no agents, no MCP server: **~39 tokens added to every
-session**, ~1.4k only when it fires. The skill installs the package on first
-use.
+Four commands and one skill. No hooks, no agents, no MCP server:
+
+| | |
+|---|---|
+| `/rag-your-code:index` | index, and say which rung this repository is on |
+| `/rag-your-code:search` | ask in plain language; cite `path:line` |
+| `/rag-your-code:describe` | write the vocabulary the source does not contain |
+| `/rag-your-code:status` | stale? coverage? which embedder? what next? |
+
+Measured with `claude plugin details` on an installed copy: **~249 tokens added
+to every session** (skill ~30, each command ~50–60), and 590–2,400 only when
+one of them fires. That is up from ~39 in 1.1.0, and the increase is the price
+of being findable — a skill fires only when a model decides it should, which
+left the whole plugin with no entry point a person could discover. The commands
+install the Python package on first use.
 
 **As a CLI:**
 
@@ -627,7 +639,7 @@ wrong: of the eight inspected, seven are unrelated tests winning on
 prose. A callee-before-caller rerank fires on zero questions and the `name`
 field weight moves nothing, because an underscored test name is a single token.
 
-**The vectors are 65.4% of the index and earn ±1 question** under the default
+**The vectors are 65.3% of the index and earn ±1 question** under the default
 embedder. Not removed: the same storage is what makes an optional model work,
 and the schema stays one shape.
 

{rag_your_code-1.1.0 → rag_your_code-1.2.0}/README.md

@@ -100,7 +100,7 @@ the scale.
 
 The default embedder is a signed feature hash. Ablating it entirely moves the
 three positive rulers by **±1 question in either direction** while the vectors
-occupy **65.4%** of the index. That was known since 0.6.0 and left unexplained.
+occupy **65.3%** of the index. That was known since 0.6.0 and left unexplained.
 The explanation, measured here:
 
 - **Not saturation.** Median 56 distinct tokens per unit into 384 buckets;
@@ -294,9 +294,9 @@ it answers a different question and names a different diagnosis.
 
 | | |
 |---|---|
-| query, median | **0.41 ms** |
-| query, p95 | 0.60 ms |
-| refusing an unanswerable query | **0.01 ms** |
+| query, median | **0.83 ms** |
+| query, p95 | 1.68 ms |
+| refusing an unanswerable query | **0.03 ms** |
 
 Refusal is cheaper than answering by a factor of forty: an unanswerable query
 touches only the posting lists of its own distinctive words, never the corpus.
@@ -335,22 +335,22 @@ declaration spans.
 **On a repository nobody has described, Grep wins.** That is the measured
 result and it is not softened here.
 
-| foreign repository · 35 questions · 1,257 units · no descriptions | Grep loop | rag-your-code |
+| foreign repository · 35 questions · 1,267 units · no descriptions | Grep loop | rag-your-code |
 |---|---|---|
 | right file first | **34.3%** | 31.4% |
 | right file in top 3 | **60.0%** | 48.6% |
-| lines matched across the repo, all questions | 33,115 | — |
-| characters returned, all questions | — | **163,521** |
+| lines matched across the repo, all questions | 33,213 | — |
+| characters returned, all questions | — | **163,294** |
 | questions it answers | 35 | 28 |
 
 **Once the vocabulary exists, it is not close.**
 
-| this repository · 70 questions · 557 units · 303 described | Grep loop | rag-your-code |
+| this repository · 70 questions · 569 units · 304 described | Grep loop | rag-your-code |
 |---|---|---|
-| right file first | 25.7% | **57.1%** |
+| right file first | 25.7% | **58.6%** |
 | right file in top 3 | 64.3% | **75.7%** |
-| lines matched across the repo, all questions | 39,550 | — |
-| characters returned, all questions | — | **278,929** |
+| lines matched across the repo, all questions | 40,150 | — |
+| characters returned, all questions | — | **277,327** |
 | questions it answers | 70 | 60 |
 
 Those two tables are the whole argument of section 3.3, measured against a real
@@ -367,7 +367,7 @@ Three qualifications, because the table would otherwise flatter both sides:
   file; a hit here is a declaration with an exact span, a score, and the words
   it matched on. The agent that reads the result opens 40 lines, not a file.
 - **Grep answers everything.** It never declines, which is why it hands back
-  33,115 matching lines for 35 questions — about 950 lines per question, no
+  33,213 matching lines for 35 questions — about 950 lines per question, no
   ranking, no spans, no indication which match is the definition. This returns
   roughly 5,800 characters per question, ranked. Seven of 35 and ten of 70
   questions come back empty here instead, with a reason.
@@ -498,9 +498,21 @@ measured worse, so it stays off there.
 /reload-plugins
 ```
 
-One skill, no hooks, no agents, no MCP server: **~39 tokens added to every
-session**, ~1.4k only when it fires. The skill installs the package on first
-use.
+Four commands and one skill. No hooks, no agents, no MCP server:
+
+| | |
+|---|---|
+| `/rag-your-code:index` | index, and say which rung this repository is on |
+| `/rag-your-code:search` | ask in plain language; cite `path:line` |
+| `/rag-your-code:describe` | write the vocabulary the source does not contain |
+| `/rag-your-code:status` | stale? coverage? which embedder? what next? |
+
+Measured with `claude plugin details` on an installed copy: **~249 tokens added
+to every session** (skill ~30, each command ~50–60), and 590–2,400 only when
+one of them fires. That is up from ~39 in 1.1.0, and the increase is the price
+of being findable — a skill fires only when a model decides it should, which
+left the whole plugin with no entry point a person could discover. The commands
+install the Python package on first use.
 
 **As a CLI:**
 
@@ -598,7 +610,7 @@ wrong: of the eight inspected, seven are unrelated tests winning on
 prose. A callee-before-caller rerank fires on zero questions and the `name`
 field weight moves nothing, because an underscored test name is a single token.
 
-**The vectors are 65.4% of the index and earn ±1 question** under the default
+**The vectors are 65.3% of the index and earn ±1 question** under the default
 embedder. Not removed: the same storage is what makes an optional model work,
 and the schema stays one shape.
 

{rag_your_code-1.1.0 → rag_your_code-1.2.0}/pyproject.toml

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

{rag_your_code-1.1.0 → rag_your_code-1.2.0/src/rag_your_code.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: rag-your-code
-Version: 1.1.0
+Version: 1.2.0
 Summary: A local, explainable RAG index for codebases and coding agents
 Author: rag-your-code contributors
 License-Expression: MIT
@@ -129,7 +129,7 @@ the scale.
 
 The default embedder is a signed feature hash. Ablating it entirely moves the
 three positive rulers by **±1 question in either direction** while the vectors
-occupy **65.4%** of the index. That was known since 0.6.0 and left unexplained.
+occupy **65.3%** of the index. That was known since 0.6.0 and left unexplained.
 The explanation, measured here:
 
 - **Not saturation.** Median 56 distinct tokens per unit into 384 buckets;
@@ -323,9 +323,9 @@ it answers a different question and names a different diagnosis.
 
 | | |
 |---|---|
-| query, median | **0.41 ms** |
-| query, p95 | 0.60 ms |
-| refusing an unanswerable query | **0.01 ms** |
+| query, median | **0.83 ms** |
+| query, p95 | 1.68 ms |
+| refusing an unanswerable query | **0.03 ms** |
 
 Refusal is cheaper than answering by a factor of forty: an unanswerable query
 touches only the posting lists of its own distinctive words, never the corpus.
@@ -364,22 +364,22 @@ declaration spans.
 **On a repository nobody has described, Grep wins.** That is the measured
 result and it is not softened here.
 
-| foreign repository · 35 questions · 1,257 units · no descriptions | Grep loop | rag-your-code |
+| foreign repository · 35 questions · 1,267 units · no descriptions | Grep loop | rag-your-code |
 |---|---|---|
 | right file first | **34.3%** | 31.4% |
 | right file in top 3 | **60.0%** | 48.6% |
-| lines matched across the repo, all questions | 33,115 | — |
-| characters returned, all questions | — | **163,521** |
+| lines matched across the repo, all questions | 33,213 | — |
+| characters returned, all questions | — | **163,294** |
 | questions it answers | 35 | 28 |
 
 **Once the vocabulary exists, it is not close.**
 
-| this repository · 70 questions · 557 units · 303 described | Grep loop | rag-your-code |
+| this repository · 70 questions · 569 units · 304 described | Grep loop | rag-your-code |
 |---|---|---|
-| right file first | 25.7% | **57.1%** |
+| right file first | 25.7% | **58.6%** |
 | right file in top 3 | 64.3% | **75.7%** |
-| lines matched across the repo, all questions | 39,550 | — |
-| characters returned, all questions | — | **278,929** |
+| lines matched across the repo, all questions | 40,150 | — |
+| characters returned, all questions | — | **277,327** |
 | questions it answers | 70 | 60 |
 
 Those two tables are the whole argument of section 3.3, measured against a real
@@ -396,7 +396,7 @@ Three qualifications, because the table would otherwise flatter both sides:
   file; a hit here is a declaration with an exact span, a score, and the words
   it matched on. The agent that reads the result opens 40 lines, not a file.
 - **Grep answers everything.** It never declines, which is why it hands back
-  33,115 matching lines for 35 questions — about 950 lines per question, no
+  33,213 matching lines for 35 questions — about 950 lines per question, no
   ranking, no spans, no indication which match is the definition. This returns
   roughly 5,800 characters per question, ranked. Seven of 35 and ten of 70
   questions come back empty here instead, with a reason.
@@ -527,9 +527,21 @@ measured worse, so it stays off there.
 /reload-plugins
 ```
 
-One skill, no hooks, no agents, no MCP server: **~39 tokens added to every
-session**, ~1.4k only when it fires. The skill installs the package on first
-use.
+Four commands and one skill. No hooks, no agents, no MCP server:
+
+| | |
+|---|---|
+| `/rag-your-code:index` | index, and say which rung this repository is on |
+| `/rag-your-code:search` | ask in plain language; cite `path:line` |
+| `/rag-your-code:describe` | write the vocabulary the source does not contain |
+| `/rag-your-code:status` | stale? coverage? which embedder? what next? |
+
+Measured with `claude plugin details` on an installed copy: **~249 tokens added
+to every session** (skill ~30, each command ~50–60), and 590–2,400 only when
+one of them fires. That is up from ~39 in 1.1.0, and the increase is the price
+of being findable — a skill fires only when a model decides it should, which
+left the whole plugin with no entry point a person could discover. The commands
+install the Python package on first use.
 
 **As a CLI:**
 
@@ -627,7 +639,7 @@ wrong: of the eight inspected, seven are unrelated tests winning on
 prose. A callee-before-caller rerank fires on zero questions and the `name`
 field weight moves nothing, because an underscored test name is a single token.
 
-**The vectors are 65.4% of the index and earn ±1 question** under the default
+**The vectors are 65.3% of the index and earn ±1 question** under the default
 embedder. Not removed: the same storage is what makes an optional model work,
 and the schema stays one shape.
 

{rag_your_code-1.1.0 → rag_your_code-1.2.0}/src/ragyourcode/__init__.py

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

{rag_your_code-1.1.0 → rag_your_code-1.2.0}/src/ragyourcode/cli.py

@@ -174,6 +174,42 @@ def _load(args: argparse.Namespace):
     return payload, units, graph_from_dict(units, payload.get("graph")), cfg, store
 
 
+# Refusal reasons that writing descriptions can actually fix. `scattered` is
+# deliberately absent: it means the words are here but never together, which is
+# what a question about a subject the repository does not implement looks like,
+# and telling somebody to describe more code would be advice that cannot work.
+_DESCRIBABLE_REASONS = frozenset({
+    "no_query_term_in_index",
+    "only_ubiquitous_terms_matched",
+    "too_little_of_the_query_matched",
+})
+
+
+def _describe_nudge(store, units, reason: str) -> str:
+    """The one line worth printing when a question came back empty and the
+    vocabulary that would have answered it has not been written yet.
+
+    Deliberately tied to a refusal rather than to a low score. "The results
+    looked weak" would need a threshold on a score, which is the failure this
+    project has already had once -- a constant tied to whatever scale the
+    ranking currently produces. A refusal is a fact, not a judgement, and it is
+    also the only moment the reader has actually lost something.
+    """
+    if reason not in _DESCRIBABLE_REASONS:
+        return ""
+    groups = store.classify(units)
+    undescribed = len(groups["missing"]) + len(groups["superseded"])
+    if not undescribed:
+        return ""
+    total = len(units) or 1
+    return (
+        f"\n{undescribed} of {total} declarations carry only the sentence the parser generated, "
+        f"which adds no word the source did not already have.\n"
+        f"Writing descriptions is what makes a question phrased in your own words reachable: "
+        f"run `rag-your-code bootstrap .` for the next batch."
+    )
+
+
 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
@@ -182,7 +218,7 @@ def _cmd_search(args: argparse.Namespace) -> int:
     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)
+    payload, units, graph, cfg, store = _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"]
     weight = cfg["search.vector_weight"]
@@ -209,7 +245,10 @@ def _cmd_search(args: argparse.Namespace) -> int:
         if payload.get("stale"):
             print("Warning: index is stale; run `rag-your-code index` to refresh.", file=sys.stderr)
         if report:
-            print(f"No matching code units.\n{report['hint']}")
+            # The JSON reply is unchanged: a machine reads `diagnosis` and does
+            # not need prose about it. This line exists for the person watching,
+            # who otherwise has no way to learn that the lever exists at all.
+            print(f"No matching code units.\n{report['hint']}{_describe_nudge(store, units, report['reason'])}")
         else:
             print(context(results, max_chars))
     return 0

{rag_your_code-1.1.0 → rag_your_code-1.2.0}/tests/test_e2e_cli.py

@@ -66,6 +66,80 @@ def test_search_without_index_is_a_concise_error(tmp_path: Path):
     assert "Traceback" not in proc.stderr
 
 
+def _undescribed_repository(root: Path, count: int) -> Path:
+    """Enough declarations for the evidence bars to be at full strength, none of
+    them carrying a written description.
+    """
+    for index in range(count):
+        (root / f"ledger_{index}.py").write_text(
+            f"def post_ledger_entry_{index}(entry, ledger):\n"
+            '    """Post an accounting entry to the ledger and return it."""\n'
+            "    return ledger\n",
+            encoding="utf-8",
+        )
+    return root
+
+
+def test_a_refused_search_says_that_descriptions_are_the_missing_piece(tmp_path: Path):
+    """The lever nobody can discover on their own.
+
+    Writing descriptions is the largest single move available on retrieval
+    quality, and until now the only place that said so was a skill that fires
+    when a model decides it should, or a command a user has to already know
+    exists. A refusal is the moment somebody has actually lost something, so it
+    is the moment worth spending a line on.
+    """
+    _undescribed_repository(tmp_path, 220)
+    run_cli("index", str(tmp_path), cwd=Path.cwd())
+    refused = run_cli("search", "how is the mooring winch tension calibrated", "--root", str(tmp_path), cwd=Path.cwd())
+    assert "No matching code units." in refused.stdout
+    assert "declarations carry only the sentence the parser generated" in refused.stdout
+    assert "bootstrap" in refused.stdout
+
+
+def test_the_machine_readable_reply_gains_no_prose(tmp_path: Path):
+    """The nudge is for the person watching. An agent reads `diagnosis` and
+    branches on `reason`; prose in the JSON would be a second, softer copy of a
+    field it already has.
+    """
+    _undescribed_repository(tmp_path, 220)
+    run_cli("index", str(tmp_path), cwd=Path.cwd())
+    reply = json.loads(
+        run_cli("search", "how is the mooring winch tension calibrated", "--root", str(tmp_path), "--json", cwd=Path.cwd()).stdout
+    )
+    assert reply["results"] == []
+    assert reply["diagnosis"]["reason"]
+    assert "declarations carry only" not in json.dumps(reply)
+
+
+def test_no_nudge_when_the_subject_is_simply_not_here(tmp_path: Path):
+    """`matched_terms_are_scattered` means the words are present but never
+    together, which is what a question about a subject the repository does not
+    implement looks like. Describing more code cannot fix that, so advising it
+    would be advice that cannot work.
+    """
+    from ragyourcode.cli import _describe_nudge
+
+    class _Store:
+        def classify(self, units):
+            return {"described": [], "superseded": [], "missing": list(units)}
+
+    units = [object()] * 10
+    assert _describe_nudge(_Store(), units, "matched_terms_are_scattered") == ""
+    assert _describe_nudge(_Store(), units, "too_little_of_the_query_matched")
+
+
+def test_no_nudge_once_everything_carries_a_description(tmp_path: Path):
+    """A repository that has done the work is not told to do it again."""
+    from ragyourcode.cli import _describe_nudge
+
+    class _Store:
+        def classify(self, units):
+            return {"described": list(units), "superseded": [], "missing": []}
+
+    assert _describe_nudge(_Store(), [object()] * 10, "no_query_term_in_index") == ""
+
+
 SAMPLE_WITH_NON_ASCII = '''def 重试请求(url):
     "重试失败的 HTTP 请求 🚀 with backoff."
     return url

{rag_your_code-1.1.0 → rag_your_code-1.2.0}/tests/test_metadata.py

@@ -49,7 +49,13 @@ def test_the_manifests_point_at_a_repository_that_exists():
 
 # --- the documentation an agent is told to follow must be executable --------
 
-DOCS = ("skills/rag-your-code/SKILL.md", "README.md")
+COMMANDS = tuple(sorted(str(path.relative_to(ROOT)).replace("\\", "/") for path in (ROOT / "commands").glob("*.md")))
+# Every document that hands somebody a command to run. The command files are
+# included by discovery rather than by name: a fifth command added without a
+# line here would otherwise be the one file nothing checks, which is exactly how
+# an install line naming a package index this project does not publish to
+# shipped twice.
+DOCS = ("skills/rag-your-code/SKILL.md", "README.md") + COMMANDS
 
 
 def _subcommands() -> set[str]:
@@ -83,12 +89,18 @@ def test_every_documented_subcommand_exists():
 
 def test_every_documented_protocol_action_is_handled():
     known = _protocol_actions()
+    everywhere: set[str] = set()
     for name in DOCS:
         text = (ROOT / name).read_text(encoding="utf-8")
         used = set(re.findall(r'"action"\s*:\s*"([a-z_]+)"', text))
         unknown = used - known
         assert not unknown, f"{name} documents actions the agent loop ignores: {sorted(unknown)}"
-        assert used, f"{name} should show at least one protocol action"
+        everywhere |= used
+    # The anti-vacuity guard belongs to the set, not to each file. A command
+    # file documents the command line and has no reason to mention the
+    # subprocess protocol at all; requiring one from every document would make
+    # this pass only by forcing irrelevant JSON into user-facing pages.
+    assert everywhere, "no document shows a protocol action; this guard would then pass vacuously"
 
 
 def test_the_documented_list_of_actions_is_the_real_list():
@@ -159,6 +171,38 @@ def test_no_document_claims_this_package_is_on_an_index_it_is_not_on():
     assert seen, "the install instructions vanished; this guard would then pass vacuously"
 
 
+def test_every_command_is_loadable_and_describes_itself():
+    """A command file is a plugin's user-facing surface, and Claude Code reads
+    its frontmatter to list it. A missing or empty `description` makes the
+    command invisible in the very place a user goes to discover it -- which is
+    the whole reason these exist, since a skill only fires when a model decides
+    it should.
+    """
+    assert COMMANDS, "the plugin ships no commands; this guard would pass vacuously"
+    for name in COMMANDS:
+        text = (ROOT / name).read_text(encoding="utf-8")
+        assert text.startswith("---\n"), f"{name}: no frontmatter block"
+        front = text.split("---\n", 2)[1]
+        described = re.search(r"^description:\s*(\S.*)$", front, re.M)
+        assert described, f"{name}: frontmatter carries no description"
+        assert len(described.group(1)) <= 200, f"{name}: description is a paragraph, not a listing line"
+        assert re.search(r"^# /rag-your-code:", text, re.M), f"{name}: body does not name the command it is"
+
+
+def test_every_command_a_document_offers_actually_exists():
+    """Both directions, for the same reason the settings table is checked both
+    ways: a document offering `/rag-your-code:describe` when no such command
+    exists is a dead end at the exact moment somebody took the advice, and a
+    command nobody is told about is not a feature.
+    """
+    real = {Path(name).stem for name in COMMANDS}
+    offered: set[str] = set()
+    for name in ("README.md", "skills/rag-your-code/SKILL.md", *COMMANDS):
+        offered.update(re.findall(r"/rag-your-code:([a-z-]+)", (ROOT / name).read_text(encoding="utf-8")))
+    assert offered - real == set(), f"documents offer commands that do not exist: {sorted(offered - real)}"
+    assert real - offered == set(), f"commands nobody is told about: {sorted(real - offered)}"
+
+
 def test_the_documented_fixture_counts_are_the_real_ones():
     """Numbers stated in prose, checked against the data they describe.