recx-cli 0.0.4__tar.gz → 0.1.1__tar.gz

{recx_cli-0.0.4 → recx_cli-0.1.1}/.gitignore

@@ -22,3 +22,6 @@ KYOSEI_ISSUE.md
 CLAUDE.md
 CLAUDE.local.md
 .kyosei
+
+# internal working documents (subagent drafts, raw proposals); local only
+docs/internal/

{recx_cli-0.0.4 → recx_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: recx-cli
-Version: 0.0.4
+Version: 0.1.1
 Summary: Validator for RECX.yaml manifests: the recx check command.
 Project-URL: Homepage, https://github.com/jbmv/recx
 Project-URL: Repository, https://github.com/jbmv/recx
@@ -38,8 +38,11 @@ than write it again, recording where it came from in its own project's manifest.
 
 Taking part is meant to cost a repository little. One prompt produces a complete, valid
 manifest, and the Claude Code plugin checks it whenever a session ends, so it stays valid as
-the code changes. No hosted service is involved, because the fixed filename serves as the index.
-On GitHub, manifests can be found by searching code for `path:/(^|\/)recx\.ya?ml$/i`.
+the code changes. No hosted service is involved. The fixed filename and the GitHub topic `recx`
+serve as the index, and a scheduled workflow in this repository collects the valid manifests it
+finds into a static file each day. In GitHub's web interface, manifests can also be found by
+searching code for `path:/(^|\/)recx\.ya?ml$/i`; GitHub's code search API does not accept that
+regular expression.
 
 ## The manifest
 
@@ -70,22 +73,59 @@ anything listed can be reused without asking.
 - **Any other agent:** paste the prompt in [ADOPT.md](ADOPT.md).
 - **By hand:** start from the example above, then run `uvx --from recx-cli recx check`.
 
+Then add the GitHub topic `recx` to the repository, so the daily index finds it promptly.
+
+The plugin's hook runs when a session or one of its subagents stops (Claude Code's Stop and
+SubagentStop events). It blocks on an invalid manifest, and it reminds, without blocking, when
+files under a module's `path` changed during the session while RECX.yaml did not. A commit can
+record that module entries were checked against its tree with a trailer such as
+`Recx-Checked: lib, cli`; the reminder then disregards that commit's changes to those modules
+and the changes of the session's commits it descends from. `RECX_DRIFT_REMINDER=off` turns
+the reminder off. The [manifest skill](plugin/skills/manifest/SKILL.md) describes both in full.
+
+## Searching
+
+```sh
+recx search "retry an http request with exponential backoff"
+recx search parse rss feeds --language python --json
+recx show OWNER/NAME
+```
+
+`recx search` downloads the published index (https://jbmv.github.io/recx/v1/index.json),
+caches it for six hours, and ranks entries by keyword overlap with the query, weighting
+capabilities above summaries and descriptions. It returns every entry that shares a term with
+the query, ordered by score, and leaves the judgement of relevance to the agent reading the
+results. `--json` gives the structured form a tool or agent should use, and the same result is
+available from Python as `recx_cli.search.search()`. `recx show` prints one indexed entry in
+full. Neither command needs a GitHub token or runs anything from a repository.
+
+Every result is written by the repository's author and has been checked only against the
+schema. The output says so in a fixed `notice`, and the JSON lists the author-written paths in
+`untrusted`. The index never contains a manifest's `setup` or `run` commands. Before reusing
+anything, read the repository's licence file and its current `RECX.yaml`, and run its evidence
+only in a sandbox. [docs/integrating.md](docs/integrating.md) explains how to call search from
+another tool, and [docs/design/search.md](docs/design/search.md) describes the index, the crawler
+and the ranking in full.
+
 ## What's here
 
 | | |
 |---|---|
 | [spec/](spec/) | The spec, its JSON Schema, and valid and invalid example manifests |
-| `recx-cli` on PyPI | `recx check`, the validator (`pip install recx-cli`) |
+| `recx-cli` on PyPI | `recx check`, `recx evidence`, `recx search` and `recx show` (`pip install recx-cli`) |
 | `@jbmv/recx` on npm | The schema and examples, for JavaScript tooling |
 | [plugin/](plugin/) | The Claude Code plugin; this repository is its marketplace |
+| [crawler/](crawler/) | The daily crawler that builds the search index, run by a scheduled workflow |
+| [docs/design/](docs/design/) | Design documents |
 | [RECX.yaml](RECX.yaml) | recx's own manifest |
 
 ## Status
 
 Experimental. The spec is a v0.1 draft and may change before 1.0; every manifest states the
 version it was written against. `recx check` enforces the whole spec except rule 4, that the
-license file matches `license`. The manifest, the validator and the plugin exist; search, the
-second part described above, is not built yet.
+license file matches `license`; the search crawler applies it as far as GitHub's licence
+detection allows. Search is in its first version: it ranks by keywords, has no synonym handling,
+and has no MCP server yet.
 
 ## Kyosei
 

{recx_cli-0.0.4 → recx_cli-0.1.1}/README.md

@@ -24,8 +24,11 @@ than write it again, recording where it came from in its own project's manifest.
 
 Taking part is meant to cost a repository little. One prompt produces a complete, valid
 manifest, and the Claude Code plugin checks it whenever a session ends, so it stays valid as
-the code changes. No hosted service is involved, because the fixed filename serves as the index.
-On GitHub, manifests can be found by searching code for `path:/(^|\/)recx\.ya?ml$/i`.
+the code changes. No hosted service is involved. The fixed filename and the GitHub topic `recx`
+serve as the index, and a scheduled workflow in this repository collects the valid manifests it
+finds into a static file each day. In GitHub's web interface, manifests can also be found by
+searching code for `path:/(^|\/)recx\.ya?ml$/i`; GitHub's code search API does not accept that
+regular expression.
 
 ## The manifest
 
@@ -56,22 +59,59 @@ anything listed can be reused without asking.
 - **Any other agent:** paste the prompt in [ADOPT.md](ADOPT.md).
 - **By hand:** start from the example above, then run `uvx --from recx-cli recx check`.
 
+Then add the GitHub topic `recx` to the repository, so the daily index finds it promptly.
+
+The plugin's hook runs when a session or one of its subagents stops (Claude Code's Stop and
+SubagentStop events). It blocks on an invalid manifest, and it reminds, without blocking, when
+files under a module's `path` changed during the session while RECX.yaml did not. A commit can
+record that module entries were checked against its tree with a trailer such as
+`Recx-Checked: lib, cli`; the reminder then disregards that commit's changes to those modules
+and the changes of the session's commits it descends from. `RECX_DRIFT_REMINDER=off` turns
+the reminder off. The [manifest skill](plugin/skills/manifest/SKILL.md) describes both in full.
+
+## Searching
+
+```sh
+recx search "retry an http request with exponential backoff"
+recx search parse rss feeds --language python --json
+recx show OWNER/NAME
+```
+
+`recx search` downloads the published index (https://jbmv.github.io/recx/v1/index.json),
+caches it for six hours, and ranks entries by keyword overlap with the query, weighting
+capabilities above summaries and descriptions. It returns every entry that shares a term with
+the query, ordered by score, and leaves the judgement of relevance to the agent reading the
+results. `--json` gives the structured form a tool or agent should use, and the same result is
+available from Python as `recx_cli.search.search()`. `recx show` prints one indexed entry in
+full. Neither command needs a GitHub token or runs anything from a repository.
+
+Every result is written by the repository's author and has been checked only against the
+schema. The output says so in a fixed `notice`, and the JSON lists the author-written paths in
+`untrusted`. The index never contains a manifest's `setup` or `run` commands. Before reusing
+anything, read the repository's licence file and its current `RECX.yaml`, and run its evidence
+only in a sandbox. [docs/integrating.md](docs/integrating.md) explains how to call search from
+another tool, and [docs/design/search.md](docs/design/search.md) describes the index, the crawler
+and the ranking in full.
+
 ## What's here
 
 | | |
 |---|---|
 | [spec/](spec/) | The spec, its JSON Schema, and valid and invalid example manifests |
-| `recx-cli` on PyPI | `recx check`, the validator (`pip install recx-cli`) |
+| `recx-cli` on PyPI | `recx check`, `recx evidence`, `recx search` and `recx show` (`pip install recx-cli`) |
 | `@jbmv/recx` on npm | The schema and examples, for JavaScript tooling |
 | [plugin/](plugin/) | The Claude Code plugin; this repository is its marketplace |
+| [crawler/](crawler/) | The daily crawler that builds the search index, run by a scheduled workflow |
+| [docs/design/](docs/design/) | Design documents |
 | [RECX.yaml](RECX.yaml) | recx's own manifest |
 
 ## Status
 
 Experimental. The spec is a v0.1 draft and may change before 1.0; every manifest states the
 version it was written against. `recx check` enforces the whole spec except rule 4, that the
-license file matches `license`. The manifest, the validator and the plugin exist; search, the
-second part described above, is not built yet.
+license file matches `license`; the search crawler applies it as far as GitHub's licence
+detection allows. Search is in its first version: it ranks by keywords, has no synonym handling,
+and has no MCP server yet.
 
 ## Kyosei
 

{recx_cli-0.0.4 → recx_cli-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "recx-cli"
-version = "0.0.4"
+version = "0.1.1"
 description = "Validator for RECX.yaml manifests: the recx check command."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -38,3 +38,4 @@ include = ["/src", "/spec", "/tests", "/README.md", "/LICENSE", "/pyproject.toml
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
+pythonpath = ["."]  # lets tests import the crawler/ package, which is not in the wheel

{recx_cli-0.0.4 → recx_cli-0.1.1}/spec/SPEC.md

@@ -32,8 +32,14 @@ recx's own validator checks both.
 
 - The filename is exactly `RECX.yaml`, at the repository root. There is one per repository.
   That fixed name is what makes manifests findable: searching code for the filename returns
-  only manifests. On GitHub, signed in, search code for `path:/(^|\/)recx\.ya?ml$/i`. That
-  query also catches misspellings, so keep only root-level files named exactly `RECX.yaml`.
+  only manifests. In GitHub's web interface, signed in, search code for
+  `path:/(^|\/)recx\.ya?ml$/i`; the query also catches misspellings, so keep only root-level
+  files named exactly `RECX.yaml`. GitHub's code search API does not accept regular
+  expressions, so a program searches for `filename:RECX.yaml path:/` and applies the same
+  filter.
+- A repository with a manifest should also carry the GitHub topic `recx`. Code search indexes
+  new and small repositories slowly, and sometimes not at all; repository topics become
+  searchable quickly.
 - It is UTF-8 YAML 1.2. JSON is valid YAML, so a tool may write JSON into it.
 - It is at most 64 KiB.
 - It uses no anchors (`&`), aliases (`*`) or merge keys (`<<`), and no mapping repeats a key.