cli-usereq 0.68.0__tar.gz → 0.68.2__tar.gz

{cli_usereq-0.68.0/src/cli_usereq.egg-info → cli_usereq-0.68.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-usereq
-Version: 0.68.0
+Version: 0.68.2
 Summary: Initialize a project with prompts, agents, and templates from the useReq repository.
 Author: Ogekuri
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -709,7 +709,7 @@ Dynamic: license-file
 > * **No Support or Feature Requests:** Please **do not** open issues, bug reports, or feature requests. They will not be addressed or accepted at this stage of development.
 > * **No Warranty:** This software is provided **"AS IS"**, without warranty of any kind, express or implied. You may use it strictly for **testing and evaluation purposes** at your own sole risk.
 
-# useReq / req (0.68.0)
+# useReq / req (0.68.2)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">
@@ -719,14 +719,23 @@ Dynamic: license-file
   <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv">
 </p>
 
-**The `req` CLI provisions requirements-driven development prompts for LLM agents.**
-
+<p align="center">
+<strong>The `req` CLI provisions requirements-driven development prompts for LLM agents.</strong><br>
 In more detail: useReq packages a catalog of requirements-engineering prompts (write, create, change, implement, check, and more) and installs them as user-level prompts, commands, skills, and agents for the CLIs and agents you already use — exposed as `/req-<name>`, `/req:<name>`, `/skill:req-<name>`, `$req-<name>`, or `/req-<name>.prompt` depending on the provider. It also ships an embedded source-analysis toolkit (token counting, references, compression, construct extraction, static checks) that operates on your project across 20 programming languages, plus git-worktree helpers for parallel task execution. Everything is driven by one user-global configuration file (`~/.config/usereq/config.json`); nothing is written into your project repository. It runs as a Python package (installed as `req`, `usereq`, or `use-req`) or directly via `uvx`.
+</p>
 
-Quick index: [Feature Highlights](#feature-highlights) | [Quick Start](#quick-start) | [User's Guide](#users-guide) | [Acknowledgments](#acknowledgments)
+<p align="center">
+  <a href="#feature-highlights">Feature Highlights</a> |
+  <a href="#quick-start">Quick Start</a> |
+  <a href="#requirements">Requirements</a> |
+  <a href="#users-guide">User's Guide</a> |
+  <a href="#acknowledgments">Acknowledgments</a>
+</p>
 
-🚧 **Status: DRAFT — Proof-of-Concept (PoC) version, work in progress** 🚧
-⚠️ **IMPORTANT NOTICE**: Created with [PI-useReq/pi-usereq](https://www.npmjs.com/package/pi-usereq) 🤖✨ ⚠️
+<p align="center">
+🚧 <strong>STAGE:</strong> PRE-ALPHA 📝 - Proof-of-Concept (PoC) version 🏗️ 🚧<br>
+⚠️ <strong>IMPORTANT NOTICE</strong>: Created with <a href="https://www.npmjs.com/package/pi-usereq"><strong>PI-useReq/pi-usereq</strong></a> 🤖✨ ⚠️<br>
+</p>
 
 # Feature Highlights
 
@@ -806,7 +815,7 @@ This exposes the CLI as `req` (also callable as `use-req` / `usereq` or `python
 req --upgrade
 ```
 
-On Linux this executes `uv tool install cli-usereq --force` from the PyPI index; on other platforms the manual command is printed and `uv` is not executed. Use `req --upgrade --github` to install the latest GitHub release instead of PyPI. When the upgrade succeeds and `auto-install` is enabled (the default), the persisted providers are automatically re-provisioned — equivalent to running `install`. Provide `--prj-base` in the same invocation to enable this; without it, a warning is printed and the provider update is skipped. Disable the behavior persistently with `--disable-auto-install` and re-enable it with `--enable-auto-install`.
+On Linux this executes `uv tool install cli-usereq --force` from the PyPI index; on other platforms the manual command is printed and `uv` is not executed. Use `req --upgrade --develop` (or the equivalent `req --upgrade --dev`) to install the latest GitHub release instead of PyPI. When the upgrade succeeds and `auto-install` is enabled (the default), the persisted providers are automatically re-provisioned — equivalent to running `install`. Provide `--prj-base` in the same invocation to enable this; without it, a warning is printed and the provider update is skipped. Disable the behavior persistently with `--disable-auto-install` and re-enable it with `--enable-auto-install`.
 
 ### Install from GitHub (alternative channel)
 
@@ -820,10 +829,10 @@ uv tool install cli-usereq --force --from git+https://github.com/Ogekuri/CLI-use
 uvx --from git+https://github.com/Ogekuri/CLI-useReq.git req --help
 
 # or upgrade an existing installation to the latest GitHub release
-req --upgrade --github
+req --upgrade --develop
 ```
 
-On Linux `req --upgrade --github` executes `uv tool install cli-usereq --force --from git+https://github.com/Ogekuri/CLI-useReq.git`; on other platforms the manual command is printed and `uv` is not executed.
+On Linux `req --upgrade --develop` (or `req --upgrade --dev`) executes `uv tool install cli-usereq --force --from git+https://github.com/Ogekuri/CLI-useReq.git`; on other platforms the manual command is printed and `uv` is not executed.
 
 ### Tool removal
 
@@ -835,7 +844,6 @@ req --uninstall     # executes `uv tool uninstall cli-usereq` on Linux and clean
 
 - `req install --prj-base PRJ_BASE` — installs or updates the providers persisted in the configuration and prints a Unicode installation summary report (per-provider `Prompts Installed` / `Modules Installed` columns). Requires at least one enabled provider, otherwise an English error is printed and the exit code is 4.
 - `req uninstall` — reciprocal of `install`: removes the `req-*` artifacts of the configured providers from the user-level provider directories.
-- `req --remove` — same artifact removal, flag form.
 - `req show` — prints the active configuration as tables: settings (including `auto-install`), provider enablement status, one dedicated per-provider table showing the installation status of the `prompts`, `agents`, and `skills` components detected on disk, and the enabled static-check entries.
 
 Artifacts are always installed into **user-level CLI configuration directories under your HOME** (`~/.claude`, `~/.codex`, `~/.antigravity`, `~/.config/opencode`, `~/.pi/agent`); nothing is ever written into the project repository.
@@ -914,26 +922,26 @@ A standalone testbed is available: `req --test-static-check {dummy,pylance,ruff,
 
 `req` can be run from any directory. Two path arguments drive location resolution:
 
-- `--prj-base <project-folder>` — mandatory for every command that reads or writes project files (`install`, `--update`, the analysis subcommands, `--docs-check`, `--set-*-dir`).
-- `--git-base <git-repository-folder>` — mandatory for every git command and for every analysis subcommand.
+- `--prj-base <project-folder>` — mandatory for commands that read or write project files (`install`, `--docs-check`, `--set-*-dir`, and the project-scan subcommands `tokens`, `references`, `compress`, `find`, `static-check`, `files-static-check`).
+- `--git-base <git-repository-folder>` — mandatory for the git commands (`--git-check`, `--git-wt-name`, `--git-wt-create`, `--git-wt-delete`); not required by any analysis subcommand.
 - `--prj-base` and `--git-base` are never persisted in `~/.config/usereq/config.json`.
 
 ### Analysis subcommands
 
-The analysis commands are bare subcommands (no `--` prefix) and each one requires both `--prj-base` and `--git-base`. Legacy `--`-prefixed forms are not accepted.
+The analysis commands are bare subcommands (no `--` prefix); the project-scan ones require `--prj-base`, and none of them requires `--git-base`. Legacy `--`-prefixed forms are not accepted.
 
 | Subcommand | Purpose |
 | --- | --- |
-| `files-tokens --prj-base P --git-base G FILE [FILE ...]` | Count tokens and chars for the given files |
-| `files-references --prj-base P --git-base G FILE [FILE ...]` | Generate LLM reference markdown for the given files |
-| `files-compress --prj-base P --git-base G [--enable-line-numbers] FILE [FILE ...]` | Generate compressed output for the given files |
-| `files-find --prj-base P --git-base G [--enable-line-numbers] TAG PATTERN FILE [FILE ...]` | Find and extract specific constructs from the given files |
-| `files-static-check --prj-base P --git-base G FILE [FILE ...]` | Run static analysis on the given files |
-| `tokens --prj-base P --git-base G` | Count tokens/chars for canonical docs (`REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md`) in configured `docs-dir` |
-| `references --prj-base P --git-base G` | Reference markdown for source files selected by `git ls-files --cached --others --exclude-standard` under configured `src-dir` |
-| `compress --prj-base P --git-base G [--enable-line-numbers]` | Compressed output for the same project selection |
-| `find --prj-base P --git-base G [--enable-line-numbers] TAG PATTERN` | Extract constructs from the same project selection |
-| `static-check --prj-base P --git-base G` | Static analysis on `src-dir` + `tests-dir` selections (excluding `fixtures/`) |
+| `files-tokens FILE [FILE ...]` | Count tokens and chars for the given files |
+| `files-references FILE [FILE ...]` | Generate LLM reference markdown for the given files |
+| `files-compress [--enable-line-numbers] FILE [FILE ...]` | Generate compressed output for the given files |
+| `files-find [--enable-line-numbers] TAG PATTERN FILE [FILE ...]` | Find and extract specific constructs from the given files |
+| `files-static-check --prj-base P FILE [FILE ...]` | Run static analysis on the given files |
+| `tokens --prj-base P` | Count tokens/chars for canonical docs (`REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md`) in configured `docs-dir` |
+| `references --prj-base P` | Reference markdown for source files selected by `git ls-files --cached --others --exclude-standard` under configured `src-dir` |
+| `compress --prj-base P [--enable-line-numbers]` | Compressed output for the same project selection |
+| `find --prj-base P [--enable-line-numbers] TAG PATTERN` | Extract constructs from the same project selection |
+| `static-check --prj-base P` | Static analysis on `src-dir` + `tests-dir` selections (excluding `fixtures/`) |
 
 Notes:
 
@@ -974,11 +982,9 @@ Notes:
 
 ### Other flags
 
-- `--update` — update an existing installation from the persisted configuration (requires an existing `~/.config/usereq/config.json`); the `install` subcommand is the canonical form.
-- `--remove` — remove `req-*` artifacts generated by useReq from the configured user-level provider directories.
 - `--verbose` / `--debug` — detailed and diagnostic output.
 - `--ver` / `--version` — print the installed package version, query PyPI and GitHub, and print `PyPI latest: <version>` and `GitHub latest: <version>` lines (`unknown` when a repository cannot be reached).
-- `--github` — with `--upgrade`: install from the GitHub repository `git+https://github.com/Ogekuri/CLI-useReq.git` instead of PyPI.
+- `--develop` / `--dev` — with `--upgrade`: install from the GitHub repository `git+https://github.com/Ogekuri/CLI-useReq.git` instead of PyPI; `--dev` is an equivalent alias of `--develop`.
 - `-h` / `--help` — print command help and exit.
 
 A startup release check queries the latest PyPI release (idle-gated to at most once per hour; once per day on API failures) and prints a bright-green stderr notice when a newer version is available.
@@ -1083,7 +1089,7 @@ Requirements-driven projects keep their normative documentation under the config
 
 - `scripts/req.sh` runs the CLI via `uv run python -m usereq.cli` from the repository root, forwarding all user arguments unchanged.
 - `scripts/test-install.sh` performs an isolated-HOME smoke installation (`--enable pi:prompts,skills` + `install`).
-- `scripts/prompts-update.sh` synchronizes the bundled prompts from the upstream [Ogekuri/Prompts](https://github.com/Ogekuri/Prompts) releases into `src/usereq/resources/prompts`.
+- `scripts/prompts-update.sh` synchronizes the bundled prompts from the upstream [Ogekuri/CLI-Prompts](https://github.com/Ogekuri/CLI-Prompts) releases into `src/usereq/resources/prompts`.
 - `uv.lock` is the canonical dependency lockfile for execution, build, development, testing, and static analysis.
 
 ## Note on Git usage
@@ -1127,7 +1133,7 @@ This program is distributed in the hope that it will be useful, but **without an
 
 # Acknowledgments
 
-- **[Ogekuri/Prompts](https://github.com/Ogekuri/Prompts)** — upstream source of the bundled requirements-engineering prompt catalog (`src/usereq/resources/prompts`).
+- **[Ogekuri/CLI-Prompts](https://github.com/Ogekuri/CLI-Prompts)** — upstream source of the bundled requirements-engineering prompt catalog (`src/usereq/resources/prompts`).
 - **[Astral](https://astral.sh)** — for `uv`, the Python package and project manager that powers installation, execution, and self-upgrade.
 - **[OpenAI tiktoken](https://github.com/openai/tiktoken)** — token counting for LLM context budgeting.
 - **[pyright](https://github.com/microsoft/pyright)** and **[ruff](https://github.com/astral-sh/ruff)** — the static-analysis engines exposed through the `Pylance` and `Ruff` modules.

{cli_usereq-0.68.0 → cli_usereq-0.68.2}/README.md

@@ -10,7 +10,7 @@
 > * **No Support or Feature Requests:** Please **do not** open issues, bug reports, or feature requests. They will not be addressed or accepted at this stage of development.
 > * **No Warranty:** This software is provided **"AS IS"**, without warranty of any kind, express or implied. You may use it strictly for **testing and evaluation purposes** at your own sole risk.
 
-# useReq / req (0.68.0)
+# useReq / req (0.68.2)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">
@@ -20,14 +20,23 @@
   <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv">
 </p>
 
-**The `req` CLI provisions requirements-driven development prompts for LLM agents.**
-
+<p align="center">
+<strong>The `req` CLI provisions requirements-driven development prompts for LLM agents.</strong><br>
 In more detail: useReq packages a catalog of requirements-engineering prompts (write, create, change, implement, check, and more) and installs them as user-level prompts, commands, skills, and agents for the CLIs and agents you already use — exposed as `/req-<name>`, `/req:<name>`, `/skill:req-<name>`, `$req-<name>`, or `/req-<name>.prompt` depending on the provider. It also ships an embedded source-analysis toolkit (token counting, references, compression, construct extraction, static checks) that operates on your project across 20 programming languages, plus git-worktree helpers for parallel task execution. Everything is driven by one user-global configuration file (`~/.config/usereq/config.json`); nothing is written into your project repository. It runs as a Python package (installed as `req`, `usereq`, or `use-req`) or directly via `uvx`.
+</p>
 
-Quick index: [Feature Highlights](#feature-highlights) | [Quick Start](#quick-start) | [User's Guide](#users-guide) | [Acknowledgments](#acknowledgments)
+<p align="center">
+  <a href="#feature-highlights">Feature Highlights</a> |
+  <a href="#quick-start">Quick Start</a> |
+  <a href="#requirements">Requirements</a> |
+  <a href="#users-guide">User's Guide</a> |
+  <a href="#acknowledgments">Acknowledgments</a>
+</p>
 
-🚧 **Status: DRAFT — Proof-of-Concept (PoC) version, work in progress** 🚧
-⚠️ **IMPORTANT NOTICE**: Created with [PI-useReq/pi-usereq](https://www.npmjs.com/package/pi-usereq) 🤖✨ ⚠️
+<p align="center">
+🚧 <strong>STAGE:</strong> PRE-ALPHA 📝 - Proof-of-Concept (PoC) version 🏗️ 🚧<br>
+⚠️ <strong>IMPORTANT NOTICE</strong>: Created with <a href="https://www.npmjs.com/package/pi-usereq"><strong>PI-useReq/pi-usereq</strong></a> 🤖✨ ⚠️<br>
+</p>
 
 # Feature Highlights
 
@@ -107,7 +116,7 @@ This exposes the CLI as `req` (also callable as `use-req` / `usereq` or `python
 req --upgrade
 ```
 
-On Linux this executes `uv tool install cli-usereq --force` from the PyPI index; on other platforms the manual command is printed and `uv` is not executed. Use `req --upgrade --github` to install the latest GitHub release instead of PyPI. When the upgrade succeeds and `auto-install` is enabled (the default), the persisted providers are automatically re-provisioned — equivalent to running `install`. Provide `--prj-base` in the same invocation to enable this; without it, a warning is printed and the provider update is skipped. Disable the behavior persistently with `--disable-auto-install` and re-enable it with `--enable-auto-install`.
+On Linux this executes `uv tool install cli-usereq --force` from the PyPI index; on other platforms the manual command is printed and `uv` is not executed. Use `req --upgrade --develop` (or the equivalent `req --upgrade --dev`) to install the latest GitHub release instead of PyPI. When the upgrade succeeds and `auto-install` is enabled (the default), the persisted providers are automatically re-provisioned — equivalent to running `install`. Provide `--prj-base` in the same invocation to enable this; without it, a warning is printed and the provider update is skipped. Disable the behavior persistently with `--disable-auto-install` and re-enable it with `--enable-auto-install`.
 
 ### Install from GitHub (alternative channel)
 
@@ -121,10 +130,10 @@ uv tool install cli-usereq --force --from git+https://github.com/Ogekuri/CLI-use
 uvx --from git+https://github.com/Ogekuri/CLI-useReq.git req --help
 
 # or upgrade an existing installation to the latest GitHub release
-req --upgrade --github
+req --upgrade --develop
 ```
 
-On Linux `req --upgrade --github` executes `uv tool install cli-usereq --force --from git+https://github.com/Ogekuri/CLI-useReq.git`; on other platforms the manual command is printed and `uv` is not executed.
+On Linux `req --upgrade --develop` (or `req --upgrade --dev`) executes `uv tool install cli-usereq --force --from git+https://github.com/Ogekuri/CLI-useReq.git`; on other platforms the manual command is printed and `uv` is not executed.
 
 ### Tool removal
 
@@ -136,7 +145,6 @@ req --uninstall     # executes `uv tool uninstall cli-usereq` on Linux and clean
 
 - `req install --prj-base PRJ_BASE` — installs or updates the providers persisted in the configuration and prints a Unicode installation summary report (per-provider `Prompts Installed` / `Modules Installed` columns). Requires at least one enabled provider, otherwise an English error is printed and the exit code is 4.
 - `req uninstall` — reciprocal of `install`: removes the `req-*` artifacts of the configured providers from the user-level provider directories.
-- `req --remove` — same artifact removal, flag form.
 - `req show` — prints the active configuration as tables: settings (including `auto-install`), provider enablement status, one dedicated per-provider table showing the installation status of the `prompts`, `agents`, and `skills` components detected on disk, and the enabled static-check entries.
 
 Artifacts are always installed into **user-level CLI configuration directories under your HOME** (`~/.claude`, `~/.codex`, `~/.antigravity`, `~/.config/opencode`, `~/.pi/agent`); nothing is ever written into the project repository.
@@ -215,26 +223,26 @@ A standalone testbed is available: `req --test-static-check {dummy,pylance,ruff,
 
 `req` can be run from any directory. Two path arguments drive location resolution:
 
-- `--prj-base <project-folder>` — mandatory for every command that reads or writes project files (`install`, `--update`, the analysis subcommands, `--docs-check`, `--set-*-dir`).
-- `--git-base <git-repository-folder>` — mandatory for every git command and for every analysis subcommand.
+- `--prj-base <project-folder>` — mandatory for commands that read or write project files (`install`, `--docs-check`, `--set-*-dir`, and the project-scan subcommands `tokens`, `references`, `compress`, `find`, `static-check`, `files-static-check`).
+- `--git-base <git-repository-folder>` — mandatory for the git commands (`--git-check`, `--git-wt-name`, `--git-wt-create`, `--git-wt-delete`); not required by any analysis subcommand.
 - `--prj-base` and `--git-base` are never persisted in `~/.config/usereq/config.json`.
 
 ### Analysis subcommands
 
-The analysis commands are bare subcommands (no `--` prefix) and each one requires both `--prj-base` and `--git-base`. Legacy `--`-prefixed forms are not accepted.
+The analysis commands are bare subcommands (no `--` prefix); the project-scan ones require `--prj-base`, and none of them requires `--git-base`. Legacy `--`-prefixed forms are not accepted.
 
 | Subcommand | Purpose |
 | --- | --- |
-| `files-tokens --prj-base P --git-base G FILE [FILE ...]` | Count tokens and chars for the given files |
-| `files-references --prj-base P --git-base G FILE [FILE ...]` | Generate LLM reference markdown for the given files |
-| `files-compress --prj-base P --git-base G [--enable-line-numbers] FILE [FILE ...]` | Generate compressed output for the given files |
-| `files-find --prj-base P --git-base G [--enable-line-numbers] TAG PATTERN FILE [FILE ...]` | Find and extract specific constructs from the given files |
-| `files-static-check --prj-base P --git-base G FILE [FILE ...]` | Run static analysis on the given files |
-| `tokens --prj-base P --git-base G` | Count tokens/chars for canonical docs (`REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md`) in configured `docs-dir` |
-| `references --prj-base P --git-base G` | Reference markdown for source files selected by `git ls-files --cached --others --exclude-standard` under configured `src-dir` |
-| `compress --prj-base P --git-base G [--enable-line-numbers]` | Compressed output for the same project selection |
-| `find --prj-base P --git-base G [--enable-line-numbers] TAG PATTERN` | Extract constructs from the same project selection |
-| `static-check --prj-base P --git-base G` | Static analysis on `src-dir` + `tests-dir` selections (excluding `fixtures/`) |
+| `files-tokens FILE [FILE ...]` | Count tokens and chars for the given files |
+| `files-references FILE [FILE ...]` | Generate LLM reference markdown for the given files |
+| `files-compress [--enable-line-numbers] FILE [FILE ...]` | Generate compressed output for the given files |
+| `files-find [--enable-line-numbers] TAG PATTERN FILE [FILE ...]` | Find and extract specific constructs from the given files |
+| `files-static-check --prj-base P FILE [FILE ...]` | Run static analysis on the given files |
+| `tokens --prj-base P` | Count tokens/chars for canonical docs (`REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md`) in configured `docs-dir` |
+| `references --prj-base P` | Reference markdown for source files selected by `git ls-files --cached --others --exclude-standard` under configured `src-dir` |
+| `compress --prj-base P [--enable-line-numbers]` | Compressed output for the same project selection |
+| `find --prj-base P [--enable-line-numbers] TAG PATTERN` | Extract constructs from the same project selection |
+| `static-check --prj-base P` | Static analysis on `src-dir` + `tests-dir` selections (excluding `fixtures/`) |
 
 Notes:
 
@@ -275,11 +283,9 @@ Notes:
 
 ### Other flags
 
-- `--update` — update an existing installation from the persisted configuration (requires an existing `~/.config/usereq/config.json`); the `install` subcommand is the canonical form.
-- `--remove` — remove `req-*` artifacts generated by useReq from the configured user-level provider directories.
 - `--verbose` / `--debug` — detailed and diagnostic output.
 - `--ver` / `--version` — print the installed package version, query PyPI and GitHub, and print `PyPI latest: <version>` and `GitHub latest: <version>` lines (`unknown` when a repository cannot be reached).
-- `--github` — with `--upgrade`: install from the GitHub repository `git+https://github.com/Ogekuri/CLI-useReq.git` instead of PyPI.
+- `--develop` / `--dev` — with `--upgrade`: install from the GitHub repository `git+https://github.com/Ogekuri/CLI-useReq.git` instead of PyPI; `--dev` is an equivalent alias of `--develop`.
 - `-h` / `--help` — print command help and exit.
 
 A startup release check queries the latest PyPI release (idle-gated to at most once per hour; once per day on API failures) and prints a bright-green stderr notice when a newer version is available.
@@ -384,7 +390,7 @@ Requirements-driven projects keep their normative documentation under the config
 
 - `scripts/req.sh` runs the CLI via `uv run python -m usereq.cli` from the repository root, forwarding all user arguments unchanged.
 - `scripts/test-install.sh` performs an isolated-HOME smoke installation (`--enable pi:prompts,skills` + `install`).
-- `scripts/prompts-update.sh` synchronizes the bundled prompts from the upstream [Ogekuri/Prompts](https://github.com/Ogekuri/Prompts) releases into `src/usereq/resources/prompts`.
+- `scripts/prompts-update.sh` synchronizes the bundled prompts from the upstream [Ogekuri/CLI-Prompts](https://github.com/Ogekuri/CLI-Prompts) releases into `src/usereq/resources/prompts`.
 - `uv.lock` is the canonical dependency lockfile for execution, build, development, testing, and static analysis.
 
 ## Note on Git usage
@@ -428,7 +434,7 @@ This program is distributed in the hope that it will be useful, but **without an
 
 # Acknowledgments
 
-- **[Ogekuri/Prompts](https://github.com/Ogekuri/Prompts)** — upstream source of the bundled requirements-engineering prompt catalog (`src/usereq/resources/prompts`).
+- **[Ogekuri/CLI-Prompts](https://github.com/Ogekuri/CLI-Prompts)** — upstream source of the bundled requirements-engineering prompt catalog (`src/usereq/resources/prompts`).
 - **[Astral](https://astral.sh)** — for `uv`, the Python package and project manager that powers installation, execution, and self-upgrade.
 - **[OpenAI tiktoken](https://github.com/openai/tiktoken)** — token counting for LLM context budgeting.
 - **[pyright](https://github.com/microsoft/pyright)** and **[ruff](https://github.com/astral-sh/ruff)** — the static-analysis engines exposed through the `Pylance` and `Ruff` modules.

{cli_usereq-0.68.0 → cli_usereq-0.68.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cli-usereq"
-version = "0.68.0"
+version = "0.68.2"
 description = "Initialize a project with prompts, agents, and templates from the useReq repository."
 readme = "README.md"
 requires-python = ">=3.11"

{cli_usereq-0.68.0 → cli_usereq-0.68.2/src/cli_usereq.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cli-usereq
-Version: 0.68.0
+Version: 0.68.2
 Summary: Initialize a project with prompts, agents, and templates from the useReq repository.
 Author: Ogekuri
 License:                     GNU GENERAL PUBLIC LICENSE
@@ -709,7 +709,7 @@ Dynamic: license-file
 > * **No Support or Feature Requests:** Please **do not** open issues, bug reports, or feature requests. They will not be addressed or accepted at this stage of development.
 > * **No Warranty:** This software is provided **"AS IS"**, without warranty of any kind, express or implied. You may use it strictly for **testing and evaluation purposes** at your own sole risk.
 
-# useReq / req (0.68.0)
+# useReq / req (0.68.2)
 
 <p align="center">
   <img src="https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python 3.11+">
@@ -719,14 +719,23 @@ Dynamic: license-file
   <img src="https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v0.json" alt="uv">
 </p>
 
-**The `req` CLI provisions requirements-driven development prompts for LLM agents.**
-
+<p align="center">
+<strong>The `req` CLI provisions requirements-driven development prompts for LLM agents.</strong><br>
 In more detail: useReq packages a catalog of requirements-engineering prompts (write, create, change, implement, check, and more) and installs them as user-level prompts, commands, skills, and agents for the CLIs and agents you already use — exposed as `/req-<name>`, `/req:<name>`, `/skill:req-<name>`, `$req-<name>`, or `/req-<name>.prompt` depending on the provider. It also ships an embedded source-analysis toolkit (token counting, references, compression, construct extraction, static checks) that operates on your project across 20 programming languages, plus git-worktree helpers for parallel task execution. Everything is driven by one user-global configuration file (`~/.config/usereq/config.json`); nothing is written into your project repository. It runs as a Python package (installed as `req`, `usereq`, or `use-req`) or directly via `uvx`.
+</p>
 
-Quick index: [Feature Highlights](#feature-highlights) | [Quick Start](#quick-start) | [User's Guide](#users-guide) | [Acknowledgments](#acknowledgments)
+<p align="center">
+  <a href="#feature-highlights">Feature Highlights</a> |
+  <a href="#quick-start">Quick Start</a> |
+  <a href="#requirements">Requirements</a> |
+  <a href="#users-guide">User's Guide</a> |
+  <a href="#acknowledgments">Acknowledgments</a>
+</p>
 
-🚧 **Status: DRAFT — Proof-of-Concept (PoC) version, work in progress** 🚧
-⚠️ **IMPORTANT NOTICE**: Created with [PI-useReq/pi-usereq](https://www.npmjs.com/package/pi-usereq) 🤖✨ ⚠️
+<p align="center">
+🚧 <strong>STAGE:</strong> PRE-ALPHA 📝 - Proof-of-Concept (PoC) version 🏗️ 🚧<br>
+⚠️ <strong>IMPORTANT NOTICE</strong>: Created with <a href="https://www.npmjs.com/package/pi-usereq"><strong>PI-useReq/pi-usereq</strong></a> 🤖✨ ⚠️<br>
+</p>
 
 # Feature Highlights
 
@@ -806,7 +815,7 @@ This exposes the CLI as `req` (also callable as `use-req` / `usereq` or `python
 req --upgrade
 ```
 
-On Linux this executes `uv tool install cli-usereq --force` from the PyPI index; on other platforms the manual command is printed and `uv` is not executed. Use `req --upgrade --github` to install the latest GitHub release instead of PyPI. When the upgrade succeeds and `auto-install` is enabled (the default), the persisted providers are automatically re-provisioned — equivalent to running `install`. Provide `--prj-base` in the same invocation to enable this; without it, a warning is printed and the provider update is skipped. Disable the behavior persistently with `--disable-auto-install` and re-enable it with `--enable-auto-install`.
+On Linux this executes `uv tool install cli-usereq --force` from the PyPI index; on other platforms the manual command is printed and `uv` is not executed. Use `req --upgrade --develop` (or the equivalent `req --upgrade --dev`) to install the latest GitHub release instead of PyPI. When the upgrade succeeds and `auto-install` is enabled (the default), the persisted providers are automatically re-provisioned — equivalent to running `install`. Provide `--prj-base` in the same invocation to enable this; without it, a warning is printed and the provider update is skipped. Disable the behavior persistently with `--disable-auto-install` and re-enable it with `--enable-auto-install`.
 
 ### Install from GitHub (alternative channel)
 
@@ -820,10 +829,10 @@ uv tool install cli-usereq --force --from git+https://github.com/Ogekuri/CLI-use
 uvx --from git+https://github.com/Ogekuri/CLI-useReq.git req --help
 
 # or upgrade an existing installation to the latest GitHub release
-req --upgrade --github
+req --upgrade --develop
 ```
 
-On Linux `req --upgrade --github` executes `uv tool install cli-usereq --force --from git+https://github.com/Ogekuri/CLI-useReq.git`; on other platforms the manual command is printed and `uv` is not executed.
+On Linux `req --upgrade --develop` (or `req --upgrade --dev`) executes `uv tool install cli-usereq --force --from git+https://github.com/Ogekuri/CLI-useReq.git`; on other platforms the manual command is printed and `uv` is not executed.
 
 ### Tool removal
 
@@ -835,7 +844,6 @@ req --uninstall     # executes `uv tool uninstall cli-usereq` on Linux and clean
 
 - `req install --prj-base PRJ_BASE` — installs or updates the providers persisted in the configuration and prints a Unicode installation summary report (per-provider `Prompts Installed` / `Modules Installed` columns). Requires at least one enabled provider, otherwise an English error is printed and the exit code is 4.
 - `req uninstall` — reciprocal of `install`: removes the `req-*` artifacts of the configured providers from the user-level provider directories.
-- `req --remove` — same artifact removal, flag form.
 - `req show` — prints the active configuration as tables: settings (including `auto-install`), provider enablement status, one dedicated per-provider table showing the installation status of the `prompts`, `agents`, and `skills` components detected on disk, and the enabled static-check entries.
 
 Artifacts are always installed into **user-level CLI configuration directories under your HOME** (`~/.claude`, `~/.codex`, `~/.antigravity`, `~/.config/opencode`, `~/.pi/agent`); nothing is ever written into the project repository.
@@ -914,26 +922,26 @@ A standalone testbed is available: `req --test-static-check {dummy,pylance,ruff,
 
 `req` can be run from any directory. Two path arguments drive location resolution:
 
-- `--prj-base <project-folder>` — mandatory for every command that reads or writes project files (`install`, `--update`, the analysis subcommands, `--docs-check`, `--set-*-dir`).
-- `--git-base <git-repository-folder>` — mandatory for every git command and for every analysis subcommand.
+- `--prj-base <project-folder>` — mandatory for commands that read or write project files (`install`, `--docs-check`, `--set-*-dir`, and the project-scan subcommands `tokens`, `references`, `compress`, `find`, `static-check`, `files-static-check`).
+- `--git-base <git-repository-folder>` — mandatory for the git commands (`--git-check`, `--git-wt-name`, `--git-wt-create`, `--git-wt-delete`); not required by any analysis subcommand.
 - `--prj-base` and `--git-base` are never persisted in `~/.config/usereq/config.json`.
 
 ### Analysis subcommands
 
-The analysis commands are bare subcommands (no `--` prefix) and each one requires both `--prj-base` and `--git-base`. Legacy `--`-prefixed forms are not accepted.
+The analysis commands are bare subcommands (no `--` prefix); the project-scan ones require `--prj-base`, and none of them requires `--git-base`. Legacy `--`-prefixed forms are not accepted.
 
 | Subcommand | Purpose |
 | --- | --- |
-| `files-tokens --prj-base P --git-base G FILE [FILE ...]` | Count tokens and chars for the given files |
-| `files-references --prj-base P --git-base G FILE [FILE ...]` | Generate LLM reference markdown for the given files |
-| `files-compress --prj-base P --git-base G [--enable-line-numbers] FILE [FILE ...]` | Generate compressed output for the given files |
-| `files-find --prj-base P --git-base G [--enable-line-numbers] TAG PATTERN FILE [FILE ...]` | Find and extract specific constructs from the given files |
-| `files-static-check --prj-base P --git-base G FILE [FILE ...]` | Run static analysis on the given files |
-| `tokens --prj-base P --git-base G` | Count tokens/chars for canonical docs (`REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md`) in configured `docs-dir` |
-| `references --prj-base P --git-base G` | Reference markdown for source files selected by `git ls-files --cached --others --exclude-standard` under configured `src-dir` |
-| `compress --prj-base P --git-base G [--enable-line-numbers]` | Compressed output for the same project selection |
-| `find --prj-base P --git-base G [--enable-line-numbers] TAG PATTERN` | Extract constructs from the same project selection |
-| `static-check --prj-base P --git-base G` | Static analysis on `src-dir` + `tests-dir` selections (excluding `fixtures/`) |
+| `files-tokens FILE [FILE ...]` | Count tokens and chars for the given files |
+| `files-references FILE [FILE ...]` | Generate LLM reference markdown for the given files |
+| `files-compress [--enable-line-numbers] FILE [FILE ...]` | Generate compressed output for the given files |
+| `files-find [--enable-line-numbers] TAG PATTERN FILE [FILE ...]` | Find and extract specific constructs from the given files |
+| `files-static-check --prj-base P FILE [FILE ...]` | Run static analysis on the given files |
+| `tokens --prj-base P` | Count tokens/chars for canonical docs (`REQUIREMENTS.md`, `WORKFLOW.md`, `REFERENCES.md`) in configured `docs-dir` |
+| `references --prj-base P` | Reference markdown for source files selected by `git ls-files --cached --others --exclude-standard` under configured `src-dir` |
+| `compress --prj-base P [--enable-line-numbers]` | Compressed output for the same project selection |
+| `find --prj-base P [--enable-line-numbers] TAG PATTERN` | Extract constructs from the same project selection |
+| `static-check --prj-base P` | Static analysis on `src-dir` + `tests-dir` selections (excluding `fixtures/`) |
 
 Notes:
 
@@ -974,11 +982,9 @@ Notes:
 
 ### Other flags
 
-- `--update` — update an existing installation from the persisted configuration (requires an existing `~/.config/usereq/config.json`); the `install` subcommand is the canonical form.
-- `--remove` — remove `req-*` artifacts generated by useReq from the configured user-level provider directories.
 - `--verbose` / `--debug` — detailed and diagnostic output.
 - `--ver` / `--version` — print the installed package version, query PyPI and GitHub, and print `PyPI latest: <version>` and `GitHub latest: <version>` lines (`unknown` when a repository cannot be reached).
-- `--github` — with `--upgrade`: install from the GitHub repository `git+https://github.com/Ogekuri/CLI-useReq.git` instead of PyPI.
+- `--develop` / `--dev` — with `--upgrade`: install from the GitHub repository `git+https://github.com/Ogekuri/CLI-useReq.git` instead of PyPI; `--dev` is an equivalent alias of `--develop`.
 - `-h` / `--help` — print command help and exit.
 
 A startup release check queries the latest PyPI release (idle-gated to at most once per hour; once per day on API failures) and prints a bright-green stderr notice when a newer version is available.
@@ -1083,7 +1089,7 @@ Requirements-driven projects keep their normative documentation under the config
 
 - `scripts/req.sh` runs the CLI via `uv run python -m usereq.cli` from the repository root, forwarding all user arguments unchanged.
 - `scripts/test-install.sh` performs an isolated-HOME smoke installation (`--enable pi:prompts,skills` + `install`).
-- `scripts/prompts-update.sh` synchronizes the bundled prompts from the upstream [Ogekuri/Prompts](https://github.com/Ogekuri/Prompts) releases into `src/usereq/resources/prompts`.
+- `scripts/prompts-update.sh` synchronizes the bundled prompts from the upstream [Ogekuri/CLI-Prompts](https://github.com/Ogekuri/CLI-Prompts) releases into `src/usereq/resources/prompts`.
 - `uv.lock` is the canonical dependency lockfile for execution, build, development, testing, and static analysis.
 
 ## Note on Git usage
@@ -1127,7 +1133,7 @@ This program is distributed in the hope that it will be useful, but **without an
 
 # Acknowledgments
 
-- **[Ogekuri/Prompts](https://github.com/Ogekuri/Prompts)** — upstream source of the bundled requirements-engineering prompt catalog (`src/usereq/resources/prompts`).
+- **[Ogekuri/CLI-Prompts](https://github.com/Ogekuri/CLI-Prompts)** — upstream source of the bundled requirements-engineering prompt catalog (`src/usereq/resources/prompts`).
 - **[Astral](https://astral.sh)** — for `uv`, the Python package and project manager that powers installation, execution, and self-upgrade.
 - **[OpenAI tiktoken](https://github.com/openai/tiktoken)** — token counting for LLM context budgeting.
 - **[pyright](https://github.com/microsoft/pyright)** and **[ruff](https://github.com/astral-sh/ruff)** — the static-analysis engines exposed through the `Pylance` and `Ruff` modules.

{cli_usereq-0.68.0 → cli_usereq-0.68.2}/src/usereq/__init__.py

@@ -18,7 +18,7 @@ from . import source_analyzer  # usereq.source_analyzer submodule
 from . import token_counter  # usereq.token_counter submodule
 from typing import Any
 
-__version__ = "0.68.0"
+__version__ = "0.68.2"
 """! @brief Semantic version string of the package."""