agent-readable 0.3.0__tar.gz → 0.3.1__tar.gz

{agent_readable-0.3.0 → agent_readable-0.3.1}/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-08-23
+
+### Documentation
+
+- Restructured the getting-started one-off CLI section into two parallel
+  series, uv and pip, each with a one-off command and a repeated-use install,
+  and added a "Your own project" section for documenting project-local
+  targets.
+
 ## [0.3.0] - 2026-08-23
 
 ### Added
@@ -134,7 +143,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `AgentReadableMixin`, `__agent_notes__` accumulation across the MRO, module
   support, and the `python -m agent_readable` CLI.
 
-[Unreleased]: https://github.com/zydo/agent-readable/compare/v0.3.0...HEAD
+[Unreleased]: https://github.com/zydo/agent-readable/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/zydo/agent-readable/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/zydo/agent-readable/compare/v0.2.1...v0.3.0
 [0.2.1]: https://github.com/zydo/agent-readable/compare/v0.2.0...v0.2.1
 [0.1.2]: https://github.com/zydo/agent-readable/compare/v0.1.1...v0.1.2

{agent_readable-0.3.0 → agent_readable-0.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agent-readable
-Version: 0.3.0
+Version: 0.3.1
 Summary: A lightweight Python protocol for agent-oriented documentation
 Project-URL: Repository, https://github.com/zydo/agent-readable
 Project-URL: Issues, https://github.com/zydo/agent-readable/issues
@@ -46,7 +46,7 @@ npx skills add zydo/skills --skill agent-readable
 
 ## Quickstart
 
-See [Getting started](docs/getting-started.md) for installation, one-off CLI usage with `uvx`, `uv tool run`, or `pipx`, and full CLI examples.
+See [Getting started](docs/getting-started.md) for installation and one-off CLI usage in two parallel series — uv and pip.
 
 ```python
 from agent_readable import agent_help

{agent_readable-0.3.0 → agent_readable-0.3.1}/README.md

@@ -19,7 +19,7 @@ npx skills add zydo/skills --skill agent-readable
 
 ## Quickstart
 
-See [Getting started](docs/getting-started.md) for installation, one-off CLI usage with `uvx`, `uv tool run`, or `pipx`, and full CLI examples.
+See [Getting started](docs/getting-started.md) for installation and one-off CLI usage in two parallel series — uv and pip.
 
 ```python
 from agent_readable import agent_help

{agent_readable-0.3.0 → agent_readable-0.3.1}/docs/getting-started.md

@@ -16,29 +16,35 @@ Requires Python 3.10+. No runtime dependencies.
 
 ## One-off CLI use
 
-If you only want to print readable documentation for a Python target and do not want to add `agent-readable` to the current environment, run it in a temporary tool environment:
+Two parallel series — pick whichever matches your tooling. Each one-off command creates an isolated tool environment on first use, caches it for instant repeat runs, and never touches the current environment. Replace `sqlite3:Connection` with any importable class, module, function, or method.
 
-The examples below use `sqlite3:Connection` as the target; replace it with any importable class, module, function, or method.
-
-With `uvx`:
+### uv series
 
 ```bash
-uvx --from agent-readable agent-readable sqlite3:Connection
-```
+# One-off — isolated tool environment, cached by uv
+uvx agent-readable sqlite3:Connection
 
-With `uv tool run`:
+# One-off for a third-party package — --with adds it to the environment
+uvx --with requests agent-readable requests:Session
 
-```bash
-uv tool run --from agent-readable agent-readable sqlite3:Connection
+# Repeated use — install once, then run the bare command
+uv tool install agent-readable
+agent-readable sqlite3:Connection
 ```
 
-With `pipx`:
+### pip series
 
 ```bash
+# One-off — pipx builds and caches an isolated environment
 pipx run --spec agent-readable agent-readable sqlite3:Connection
-```
 
-`uvx` is shorthand for `uv tool run`, and `python -m agent_readable` works identically wherever the package is installed. These commands are useful for standard-library targets and packages available inside the temporary environment. For your own project classes, run from an environment where that project is importable.
+# Repeated use — install once with pipx (isolated, on PATH)
+pipx install agent-readable
+agent-readable sqlite3:Connection
+
+# Plain pip — persistent install into any environment you choose
+pip install agent-readable
+```
 
 To let your coding agent automatically call `agent_help()` before using an unfamiliar API, install the companion skill:
 
@@ -46,6 +52,22 @@ To let your coding agent automatically call `agent_help()` before using an unfam
 npx skills add zydo/skills --skill agent-readable
 ```
 
+## Your own project
+
+The one-off environments above cannot import your own project's code. Run the CLI from an environment where the project is importable:
+
+```bash
+uv add --dev agent-readable
+uv run agent-readable my_package.temperature:CalibratedSensor
+```
+
+Or with pip, install into the project's environment and run the bare command:
+
+```bash
+pip install agent-readable
+agent-readable my_package.temperature:CalibratedSensor
+```
+
 ## Quickstart
 
 `agent_help()` works on any Python class, module, function, or method with no opt-in required. Point it at a stdlib class:

{agent_readable-0.3.0 → agent_readable-0.3.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "agent-readable"
-version = "0.3.0"
+version = "0.3.1"
 description = "A lightweight Python protocol for agent-oriented documentation"
 readme = "README.md"
 license = "MIT"