agent-readable 0.1.2__tar.gz → 0.2.0__tar.gz

{agent_readable-0.1.2 → agent_readable-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-readable
-Version: 0.1.2
+Version: 0.2.0
 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
@@ -27,7 +27,13 @@ Description-Content-Type: text/markdown
 
 # agent-readable
 
-Stop coding agents from hallucinating your library's API. Ship the usage rules — lifecycle order, pre-conditions, anti-patterns — right next to your code.
+Stop coding agents from hallucinating Python APIs. `agent_help(target)` reads the live public-API surface off any class, module, function, or method — no author opt-in needed — and optionally returns class-level usage rules (lifecycle order, pre-conditions, anti-patterns) when the library ships them.
+
+To let your coding agent automatically call `agent_help()` before using an unfamiliar API, install the skill:
+
+```bash
+npx skills add zydo/skills --skill agent-readable
+```
 
 <!-- markdownlint-disable MD033 -->
 <p align="center">
@@ -42,7 +48,7 @@ AI coding agents recognize established libraries from their training data, but t
 
 Today there's nowhere to put those rules where an agent will reliably find them. Docstrings document the API surface, not behavioral rules. `AGENTS.md` and `llms.txt` work at project granularity, drift fast, and don't travel with refactors. `help()` only describes interfaces — and mixes inherited dunders and MRO detail in with the methods you actually want to use.
 
-`agent-readable` adds two dunders — `__agent_help__` (full custom output) and `__agent_notes__` (additive guidance that accumulates across inheritance) — that live next to the code. Library authors annotate once; any agent that calls `agent_help(cls)` gets a curated public-API list with current signatures, the class's behavioral rules attached, and no inherited-dunder or MRO noise to wade through.
+`agent-readable` has two halves, and the lighter one stands alone. The **consume side** is one function — `agent_help(target)` — that works on every Python library today, annotated or not. It introspects the live, installed class/module/function and returns a curated public-API list with current signatures, no inherited-dunder or MRO noise to wade through. That alone closes the *what exists* hallucination — agents stop inventing methods that aren't there and stop calling real ones with stale signatures. The **author side** adds two dunders: `__agent_help__` for full custom output and `__agent_notes__` for additive behavioral rules that accumulate across inheritance. When a library opts in, those rules show up next to the public-API list in the same `agent_help()` output — so the rules travel with refactors instead of rotting in a sidecar file.
 
 ## Installation
 
@@ -54,11 +60,51 @@ Requires Python 3.10+. No runtime dependencies.
 
 ## Quickstart
 
+`agent_help()` works on **any Python class, module, function, or method — no opt-in required**. Point it at a stdlib class:
+
 ```python
-from agent_readable import AgentReadableMixin, agent_help
+from agent_readable import agent_help
+import logging
 
+print(agent_help(logging.Logger))
+```
 
-class Sensor(AgentReadableMixin):
+Output (excerpted):
+
+````
+# Logger
+
+## Constructor
+
+```python
+Logger(name, level=0)
+```
+
+## Purpose
+
+Instances of the Logger class represent a single logging channel. ...
+
+## Public API
+
+- `addHandler(hdlr)` method: Add the specified handler to this logger.
+- `debug(msg, *args, **kwargs)` method: Log 'msg % args' with severity 'DEBUG'.
+- `info(msg, *args, **kwargs)` method: Log 'msg % args' with severity 'INFO'.
+- `setLevel(level)` method: Set the logging level of this logger.
+- `warning(msg, *args, **kwargs)` method: Log 'msg % args' with severity 'WARNING'.
+- ...
+````
+
+The `## Public API` list comes from **runtime introspection of the live, installed version** — current signatures, no inherited-dunder noise, no stale training-data guesses. Substitute any class, module, function, or method (yours, a third party's, or a stdlib one); zero setup on the target side.
+
+### Library authors: ship usage rules next to the code (optional)
+
+When you own the class, you can also ship class-level usage rules — lifecycle order, pre-conditions, anti-patterns — that `agent_help()` returns alongside the auto-generated public-API list. Define a `__agent_notes__()` classmethod (no mixin, no inheritance required); notes accumulate across the MRO so subclasses don't lose parent rules:
+
+```python
+from agent_readable import agent_help
+
+
+class Sensor:
     """Reads a value from a hardware sensor."""
 
     def __init__(self, pin: int, *, unit: str = "C"): ...
@@ -85,43 +131,7 @@ class Sensor(AgentReadableMixin):
 print(agent_help(Sensor))
 ```
 
-Output:
-
-````
-# Sensor
-
-## Constructor
-
-```python
-Sensor(pin: int, *, unit: str = 'C')
-```
-
-## Purpose
-
-Reads a value from a hardware sensor.
-
-## Public API
-
-- `calibrate(offset: float)` method: Apply a calibration offset.
-- `read() -> float` method: Read the current sensor value.
-
-## Agent usage rules
-
-- Prefer the public API listed above.
-- Do not use private methods or attributes starting with `_`.
-- Do not invent unsupported behavior.
-- If usage is ambiguous, prefer the simplest documented usage pattern.
-
-## Notes from class Sensor
-
-## Do
-
-- Call `calibrate()` once during setup, before `read()`.
-
-## Do not
-
-- Do not call `read()` before `calibrate()` on first use.
-````
+`agent_help(Sensor)` now returns the same auto-generated public-API list, plus a `## Notes from class Sensor` section carrying the rules above. Full output and inheritance-with-notes behavior in [Example 2](#example-2-inheritance-with-accumulated-notes) below.
 
 ## Why it matters
 
@@ -153,7 +163,7 @@ class Connection(builtins.object)
 
 `agent_help(sqlite3.Connection)` produces a curated public-API list with current signatures and any class-level rules attached — see Example 1 below. Notes from `__agent_notes__()` accumulate across inheritance. Class docs travel with the code in commits, reviews, and refactors. Drift gets caught in code review, not weeks later in a sidecar file.
 
-The examples below demonstrate four ways to use `agent_help()`.
+The examples below demonstrate five ways to use `agent_help()`, three with library-author opt-in (Examples 1–3) and two on plain classes/modules with no setup (Examples 4–5).
 
 ## Example 1: Wrapping an existing class
 
@@ -536,9 +546,13 @@ Outputs agent-oriented documentation for the given class, module, function, or m
 
 ### How does my agent know to call `agent_help()` instead of `help()`?
 
-Install the agent **skill** that ships in this repo at [`skills/agent-readable/`](skills/agent-readable/). It follows the [Agent Skills open standard](https://agentskills.io) — adopted by Claude Code, Codex CLI (OpenAI), Gemini CLI (Google), GitHub Copilot, Cursor, JetBrains Junie, Goose, OpenCode, and 40+ other tools — so dropping the folder into your agent's skills directory (`~/.claude/skills/`, `~/.codex/skills/`, your editor's equivalent) is enough for the agent to discover it. The skill teaches the agent to install `agent-readable`, call `agent_help(target)` before writing code against a class, module, function, or method, and add `__agent_notes__()` (or improve docstrings) when authoring new public APIs.
+Install the companion agent skill:
+
+```bash
+npx skills add zydo/skills --skill agent-readable
+```
 
-The folder lives next to the source code for now; a hub-published version (so you can install it through your harness's marketplace) is the next step on the roadmap.
+The skill teaches the agent to install `agent-readable`, call `agent_help(target)` before writing code against a class, module, function, or method, and add `__agent_notes__()` (or improve docstrings) when authoring new public APIs. (Cursor is among the adopters too, but its skill integration is manual — you invoke the skill explicitly there rather than relying on description-match auto-activation.)
 
 ### How is this different from `AGENTS.md` / `llms.txt` / Cursor rules?
 
@@ -564,19 +578,23 @@ Yes. Two ways:
 
 Yes — `agent_help()` falls back to introspection (Example 4). You get a structured summary of every plain class, mixin or not. Notes are added on top *if* the class defines them; otherwise the auto-doc is what you see.
 
+### Is `agent_help()` the strongest fix for API hallucination?
+
+No, and worth being upfront about it. The strongest known mitigation is **constrained decoding** at the harness or decoder layer — masking illegal API tokens before generation, so the model can't produce a nonexistent method at all. `agent_help()` takes the lighter, library-side path: an authoritative usage guide injected into the agent's context, leaving the agent to read and follow it. Recent research on Python API misuse shows the in-context route leaves a meaningful slice of hallucinations on the table even when verified API references are provided. The two approaches compose. Pick `agent_help()` when you have leverage on the library side and want a fix that works on every agent and every library today, without harness changes. Reach for constrained decoding when you control the harness or the decoder. Either way, verify generated code before merging.
+
 ## Keeping agent docs up to date
 
-Agent docs can go stale when classes change — new methods, changed behavior, removed APIs. Install the skill at [`skills/agent-readable/`](skills/agent-readable/) into your agent (see the FAQ above for the install). It teaches your agent to run `agent_help()` before modifying a class, prefer docstrings over `__agent_notes__()`, and verify that the output stays accurate after changes.
+Agent docs can go stale when classes change — new methods, changed behavior, removed APIs. Install the companion skill (`npx skills add zydo/skills --skill agent-readable`) to teach your agent to run `agent_help()` before modifying a class, prefer docstrings over `__agent_notes__()`, and verify that the output stays accurate after changes.
 
 ## The `__agent_help__` protocol
 
-`__agent_help__()` is a dunder protocol, similar in spirit to ecosystem protocols such as:
+`__agent_help__()` is a dunder protocol for tool-specific documentation, similar in spirit to:
 
-- `__str__` (str) — string representation
-- `__rich_repr__` (Rich) — custom console representation
-- `__html__` (Django, Jinja2) — HTML rendering
-- `__array__` (NumPy) — array conversion
-- `__fspath__` (os.fspath) — filesystem path conversion
+- `__doc__` (Python `help()`, Sphinx, IDEs, REPLs) — the canonical "this is my human-readable documentation" slot, read by inspection tools and surfaced through `help()`
+- `__rich_repr__` (Rich) — Rich-specific console representation read only when Rich renders the object
+- `__html__` (Django, Jinja2, MarkupSafe) — HTML-renderer-specific representation read only when those template engines render the object
+
+Unlike `__str__` or `__fspath__`, these dunders don't change Python runtime behavior — they're metadata slots a specific tool reads when it wants a representation. `__agent_help__` follows the same pattern for the agent-docs case.
 
 Classes that define a `@classmethod` named `__agent_help__` returning a `str` are considered agent-readable. Modules can define a top-level `__agent_help__` attribute (callable or string). Call the top-level `agent_help(obj)` function to get the docs — just like `str()` calls `__str__()`. The `AgentReadable` `typing.Protocol` and `AgentReadableMixin` are provided for convenience and type-checking, but neither is required.
 
@@ -584,13 +602,15 @@ Classes that define a `@classmethod` named `__agent_help__` returning a `str` ar
 
 The two dunders intentionally encode different composition rules:
 
-| Aspect          | `__agent_help__()`                              | `__agent_notes__()`                                                                           |
-| --------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| Semantics       | **Replacement** — returned string IS the output | **Additive** — appended to auto-generated docs                                                |
-| Composition     | Single class wins (the one closest in MRO)      | Accumulated across the MRO; leaf class wins on conflict (header marks this)                   |
-| When to use     | Total control over the rendered text            | "Auto-doc + my extra do/don't rules"                                                          |
-| Skipped when    | (always called if defined)                      | Skipped (with a `UserWarning`) when a custom `__agent_help__` is present (it owns the output) |
-| Mixin required? | No — duck-typed classmethod is enough           | No — defining `__agent_notes__` on any class is enough                                        |
+| Aspect          | `__agent_help__()`                              | `__agent_notes__()`                                                                                  |
+| --------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Semantics       | **Replacement** — returned string IS the output | **Additive** — appended to auto-generated docs                                                       |
+| Composition     | Single class wins (the one closest in MRO)      | Accumulated across the MRO; leaf class wins on conflict (header marks this)                          |
+| When to use     | Total control over the rendered text            | "Auto-doc + my extra do/don't rules"                                                                 |
+| Skipped when    | (always called if defined)                      | Silently dropped (with `UserWarning`) when a custom `__agent_help__` is present (it owns the output) |
+| Mixin required? | No — duck-typed classmethod is enough           | No — defining `__agent_notes__` on any class is enough                                               |
+
+**Heads up on the both-defined case.** When a class defines both `__agent_help__()` and `__agent_notes__()`, the notes are silently dropped — `__agent_help__()` owns the output, and the auto-doc + notes path never runs. A `UserWarning` is emitted, but warnings are easy to miss in agent shells, CI logs, and notebooks — **treat "both defined" as a hard review error** rather than something the warning will reliably catch. Fix it by folding the notes into `__agent_help__()`, or by dropping the custom `__agent_help__()` and letting the auto-doc + notes path run.
 
 ## Class docstring hints
 

{agent_readable-0.1.2 → agent_readable-0.2.0}/README.md

@@ -1,6 +1,12 @@
 # agent-readable
 
-Stop coding agents from hallucinating your library's API. Ship the usage rules — lifecycle order, pre-conditions, anti-patterns — right next to your code.
+Stop coding agents from hallucinating Python APIs. `agent_help(target)` reads the live public-API surface off any class, module, function, or method — no author opt-in needed — and optionally returns class-level usage rules (lifecycle order, pre-conditions, anti-patterns) when the library ships them.
+
+To let your coding agent automatically call `agent_help()` before using an unfamiliar API, install the skill:
+
+```bash
+npx skills add zydo/skills --skill agent-readable
+```
 
 <!-- markdownlint-disable MD033 -->
 <p align="center">
@@ -15,7 +21,7 @@ AI coding agents recognize established libraries from their training data, but t
 
 Today there's nowhere to put those rules where an agent will reliably find them. Docstrings document the API surface, not behavioral rules. `AGENTS.md` and `llms.txt` work at project granularity, drift fast, and don't travel with refactors. `help()` only describes interfaces — and mixes inherited dunders and MRO detail in with the methods you actually want to use.
 
-`agent-readable` adds two dunders — `__agent_help__` (full custom output) and `__agent_notes__` (additive guidance that accumulates across inheritance) — that live next to the code. Library authors annotate once; any agent that calls `agent_help(cls)` gets a curated public-API list with current signatures, the class's behavioral rules attached, and no inherited-dunder or MRO noise to wade through.
+`agent-readable` has two halves, and the lighter one stands alone. The **consume side** is one function — `agent_help(target)` — that works on every Python library today, annotated or not. It introspects the live, installed class/module/function and returns a curated public-API list with current signatures, no inherited-dunder or MRO noise to wade through. That alone closes the *what exists* hallucination — agents stop inventing methods that aren't there and stop calling real ones with stale signatures. The **author side** adds two dunders: `__agent_help__` for full custom output and `__agent_notes__` for additive behavioral rules that accumulate across inheritance. When a library opts in, those rules show up next to the public-API list in the same `agent_help()` output — so the rules travel with refactors instead of rotting in a sidecar file.
 
 ## Installation
 
@@ -27,11 +33,51 @@ Requires Python 3.10+. No runtime dependencies.
 
 ## Quickstart
 
+`agent_help()` works on **any Python class, module, function, or method — no opt-in required**. Point it at a stdlib class:
+
 ```python
-from agent_readable import AgentReadableMixin, agent_help
+from agent_readable import agent_help
+import logging
 
+print(agent_help(logging.Logger))
+```
 
-class Sensor(AgentReadableMixin):
+Output (excerpted):
+
+````
+# Logger
+
+## Constructor
+
+```python
+Logger(name, level=0)
+```
+
+## Purpose
+
+Instances of the Logger class represent a single logging channel. ...
+
+## Public API
+
+- `addHandler(hdlr)` method: Add the specified handler to this logger.
+- `debug(msg, *args, **kwargs)` method: Log 'msg % args' with severity 'DEBUG'.
+- `info(msg, *args, **kwargs)` method: Log 'msg % args' with severity 'INFO'.
+- `setLevel(level)` method: Set the logging level of this logger.
+- `warning(msg, *args, **kwargs)` method: Log 'msg % args' with severity 'WARNING'.
+- ...
+````
+
+The `## Public API` list comes from **runtime introspection of the live, installed version** — current signatures, no inherited-dunder noise, no stale training-data guesses. Substitute any class, module, function, or method (yours, a third party's, or a stdlib one); zero setup on the target side.
+
+### Library authors: ship usage rules next to the code (optional)
+
+When you own the class, you can also ship class-level usage rules — lifecycle order, pre-conditions, anti-patterns — that `agent_help()` returns alongside the auto-generated public-API list. Define a `__agent_notes__()` classmethod (no mixin, no inheritance required); notes accumulate across the MRO so subclasses don't lose parent rules:
+
+```python
+from agent_readable import agent_help
+
+
+class Sensor:
     """Reads a value from a hardware sensor."""
 
     def __init__(self, pin: int, *, unit: str = "C"): ...
@@ -58,43 +104,7 @@ class Sensor(AgentReadableMixin):
 print(agent_help(Sensor))
 ```
 
-Output:
-
-````
-# Sensor
-
-## Constructor
-
-```python
-Sensor(pin: int, *, unit: str = 'C')
-```
-
-## Purpose
-
-Reads a value from a hardware sensor.
-
-## Public API
-
-- `calibrate(offset: float)` method: Apply a calibration offset.
-- `read() -> float` method: Read the current sensor value.
-
-## Agent usage rules
-
-- Prefer the public API listed above.
-- Do not use private methods or attributes starting with `_`.
-- Do not invent unsupported behavior.
-- If usage is ambiguous, prefer the simplest documented usage pattern.
-
-## Notes from class Sensor
-
-## Do
-
-- Call `calibrate()` once during setup, before `read()`.
-
-## Do not
-
-- Do not call `read()` before `calibrate()` on first use.
-````
+`agent_help(Sensor)` now returns the same auto-generated public-API list, plus a `## Notes from class Sensor` section carrying the rules above. Full output and inheritance-with-notes behavior in [Example 2](#example-2-inheritance-with-accumulated-notes) below.
 
 ## Why it matters
 
@@ -126,7 +136,7 @@ class Connection(builtins.object)
 
 `agent_help(sqlite3.Connection)` produces a curated public-API list with current signatures and any class-level rules attached — see Example 1 below. Notes from `__agent_notes__()` accumulate across inheritance. Class docs travel with the code in commits, reviews, and refactors. Drift gets caught in code review, not weeks later in a sidecar file.
 
-The examples below demonstrate four ways to use `agent_help()`.
+The examples below demonstrate five ways to use `agent_help()`, three with library-author opt-in (Examples 1–3) and two on plain classes/modules with no setup (Examples 4–5).
 
 ## Example 1: Wrapping an existing class
 
@@ -509,9 +519,13 @@ Outputs agent-oriented documentation for the given class, module, function, or m
 
 ### How does my agent know to call `agent_help()` instead of `help()`?
 
-Install the agent **skill** that ships in this repo at [`skills/agent-readable/`](skills/agent-readable/). It follows the [Agent Skills open standard](https://agentskills.io) — adopted by Claude Code, Codex CLI (OpenAI), Gemini CLI (Google), GitHub Copilot, Cursor, JetBrains Junie, Goose, OpenCode, and 40+ other tools — so dropping the folder into your agent's skills directory (`~/.claude/skills/`, `~/.codex/skills/`, your editor's equivalent) is enough for the agent to discover it. The skill teaches the agent to install `agent-readable`, call `agent_help(target)` before writing code against a class, module, function, or method, and add `__agent_notes__()` (or improve docstrings) when authoring new public APIs.
+Install the companion agent skill:
+
+```bash
+npx skills add zydo/skills --skill agent-readable
+```
 
-The folder lives next to the source code for now; a hub-published version (so you can install it through your harness's marketplace) is the next step on the roadmap.
+The skill teaches the agent to install `agent-readable`, call `agent_help(target)` before writing code against a class, module, function, or method, and add `__agent_notes__()` (or improve docstrings) when authoring new public APIs. (Cursor is among the adopters too, but its skill integration is manual — you invoke the skill explicitly there rather than relying on description-match auto-activation.)
 
 ### How is this different from `AGENTS.md` / `llms.txt` / Cursor rules?
 
@@ -537,19 +551,23 @@ Yes. Two ways:
 
 Yes — `agent_help()` falls back to introspection (Example 4). You get a structured summary of every plain class, mixin or not. Notes are added on top *if* the class defines them; otherwise the auto-doc is what you see.
 
+### Is `agent_help()` the strongest fix for API hallucination?
+
+No, and worth being upfront about it. The strongest known mitigation is **constrained decoding** at the harness or decoder layer — masking illegal API tokens before generation, so the model can't produce a nonexistent method at all. `agent_help()` takes the lighter, library-side path: an authoritative usage guide injected into the agent's context, leaving the agent to read and follow it. Recent research on Python API misuse shows the in-context route leaves a meaningful slice of hallucinations on the table even when verified API references are provided. The two approaches compose. Pick `agent_help()` when you have leverage on the library side and want a fix that works on every agent and every library today, without harness changes. Reach for constrained decoding when you control the harness or the decoder. Either way, verify generated code before merging.
+
 ## Keeping agent docs up to date
 
-Agent docs can go stale when classes change — new methods, changed behavior, removed APIs. Install the skill at [`skills/agent-readable/`](skills/agent-readable/) into your agent (see the FAQ above for the install). It teaches your agent to run `agent_help()` before modifying a class, prefer docstrings over `__agent_notes__()`, and verify that the output stays accurate after changes.
+Agent docs can go stale when classes change — new methods, changed behavior, removed APIs. Install the companion skill (`npx skills add zydo/skills --skill agent-readable`) to teach your agent to run `agent_help()` before modifying a class, prefer docstrings over `__agent_notes__()`, and verify that the output stays accurate after changes.
 
 ## The `__agent_help__` protocol
 
-`__agent_help__()` is a dunder protocol, similar in spirit to ecosystem protocols such as:
+`__agent_help__()` is a dunder protocol for tool-specific documentation, similar in spirit to:
 
-- `__str__` (str) — string representation
-- `__rich_repr__` (Rich) — custom console representation
-- `__html__` (Django, Jinja2) — HTML rendering
-- `__array__` (NumPy) — array conversion
-- `__fspath__` (os.fspath) — filesystem path conversion
+- `__doc__` (Python `help()`, Sphinx, IDEs, REPLs) — the canonical "this is my human-readable documentation" slot, read by inspection tools and surfaced through `help()`
+- `__rich_repr__` (Rich) — Rich-specific console representation read only when Rich renders the object
+- `__html__` (Django, Jinja2, MarkupSafe) — HTML-renderer-specific representation read only when those template engines render the object
+
+Unlike `__str__` or `__fspath__`, these dunders don't change Python runtime behavior — they're metadata slots a specific tool reads when it wants a representation. `__agent_help__` follows the same pattern for the agent-docs case.
 
 Classes that define a `@classmethod` named `__agent_help__` returning a `str` are considered agent-readable. Modules can define a top-level `__agent_help__` attribute (callable or string). Call the top-level `agent_help(obj)` function to get the docs — just like `str()` calls `__str__()`. The `AgentReadable` `typing.Protocol` and `AgentReadableMixin` are provided for convenience and type-checking, but neither is required.
 
@@ -557,13 +575,15 @@ Classes that define a `@classmethod` named `__agent_help__` returning a `str` ar
 
 The two dunders intentionally encode different composition rules:
 
-| Aspect          | `__agent_help__()`                              | `__agent_notes__()`                                                                           |
-| --------------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------- |
-| Semantics       | **Replacement** — returned string IS the output | **Additive** — appended to auto-generated docs                                                |
-| Composition     | Single class wins (the one closest in MRO)      | Accumulated across the MRO; leaf class wins on conflict (header marks this)                   |
-| When to use     | Total control over the rendered text            | "Auto-doc + my extra do/don't rules"                                                          |
-| Skipped when    | (always called if defined)                      | Skipped (with a `UserWarning`) when a custom `__agent_help__` is present (it owns the output) |
-| Mixin required? | No — duck-typed classmethod is enough           | No — defining `__agent_notes__` on any class is enough                                        |
+| Aspect          | `__agent_help__()`                              | `__agent_notes__()`                                                                                  |
+| --------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| Semantics       | **Replacement** — returned string IS the output | **Additive** — appended to auto-generated docs                                                       |
+| Composition     | Single class wins (the one closest in MRO)      | Accumulated across the MRO; leaf class wins on conflict (header marks this)                          |
+| When to use     | Total control over the rendered text            | "Auto-doc + my extra do/don't rules"                                                                 |
+| Skipped when    | (always called if defined)                      | Silently dropped (with `UserWarning`) when a custom `__agent_help__` is present (it owns the output) |
+| Mixin required? | No — duck-typed classmethod is enough           | No — defining `__agent_notes__` on any class is enough                                               |
+
+**Heads up on the both-defined case.** When a class defines both `__agent_help__()` and `__agent_notes__()`, the notes are silently dropped — `__agent_help__()` owns the output, and the auto-doc + notes path never runs. A `UserWarning` is emitted, but warnings are easy to miss in agent shells, CI logs, and notebooks — **treat "both defined" as a hard review error** rather than something the warning will reliably catch. Fix it by folding the notes into `__agent_help__()`, or by dropping the custom `__agent_help__()` and letting the auto-doc + notes path run.
 
 ## Class docstring hints
 

{agent_readable-0.1.2 → agent_readable-0.2.0}/pyproject.toml

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

agent_readable-0.1.2/skills/agent-readable/SKILL.md

@@ -1,183 +0,0 @@
----
-name: agent-readable
-description: Use agent_readable to get authoritative usage guidance for Python classes, modules, functions, and methods before writing code against them, and to make new Python APIs agent-readable. Activate when writing or modifying Python code that calls into a class, module, function, or method from any library, OR when adding/changing a public Python API. Covers calling `agent_help(obj)` for structured docs + behavioral rules, and authoring docstrings + `__agent_notes__()` so usage rules travel with the code.
----
-
-# agent-readable
-
-`agent-readable` is a tiny Python library (`pip install agent-readable`, zero
-runtime deps, Python 3.10+) that gives any class, module, function, or method a
-structured, agent-oriented "usage guide" — the canonical answer to *how do I
-correctly use this?* — produced by one call: `agent_help(obj)`.
-
-This skill teaches you two jobs:
-
-1. **Consume** — before writing Python code that uses a class, module, function,
-   or method, call `agent_help(target)` and use the output as the source of truth.
-2. **Author** — when adding or modifying a public Python API, make it
-   agent-readable so future agents get correct usage on the first try.
-
-**Current language support:** Python 3.10+. Counterparts in other languages are
-on the roadmap; when they ship, this skill will gain sections for them and the
-same trigger will fan out across languages.
-
-## When to activate this skill
-
-* The user asks you to write, modify, or refactor Python code that calls into a
-  class, module, function, or method (from a third-party library or from this
-  project).
-* The user asks you to add or change a public Python class, module, or function
-  (especially one other code or other agents will use).
-* The user mentions `agent_help`, `__agent_notes__`, `AgentReadableMixin`, the
-  `AgentReadable` protocol, or the `agent-readable` library by name.
-
-## Install
-
-```bash
-pip install agent-readable      # or: uv add agent-readable
-```
-
-Python 3.10+. No runtime dependencies. The library exposes one top-level function
-(`agent_help`), one protocol (`AgentReadable`), and one optional mixin
-(`AgentReadableMixin`).
-
-## Job 1 — Consume: call `agent_help(target)` first
-
-**Before writing code against a Python target, always call `agent_help(target)`.**
-Even if the target does *not* opt in: `agent_help()` falls back to introspection
-and returns a structured, current-signature public-API listing — strictly better
-than guessing from training data.
-
-```python
-from agent_readable import agent_help
-
-print(agent_help(SomeClass))      # class — constructor, public API, notes
-print(agent_help(some_instance))  # instance — dispatches to its class
-print(agent_help(some_module))    # module — docstring + public functions/classes
-print(agent_help(some_func))      # function or method — signature + docstring
-```
-
-From a coding-agent shell:
-
-```bash
-python -c "from agent_readable import agent_help; import target_lib; print(agent_help(target_lib.SomeClass))"
-```
-
-### How to read the output
-
-`agent_help()` returns Markdown with these sections (a subset appears depending
-on the target):
-
-* `# <name>` and `## Purpose` — the docstring summary.
-* `## Constructor` / `## Signature` — the **current** signature (the source of
-  truth, beats anything in training data).
-* `## Public API` — every public member with current signatures. Treat this as
-  the authoritative list; do not call methods not listed here.
-* `## Agent usage rules` — generic rules (prefer the public API, no private
-  names, etc.).
-* `## Notes from class <X>` — **load-bearing** class-specific behavioral rules:
-  lifecycle order, pre-conditions, anti-patterns. If a note says *"call
-  `calibrate()` once before `read()`"*, honor it. If multiple `Notes from class`
-  sections appear, the leaf class wins on conflict (the header marks this).
-
-If you are unsure how to use a target, run `agent_help()` again — it is cheap and
-the docstrings/notes are the canonical source.
-
-## Job 2 — Author: make new Python APIs agent-readable
-
-Default to **better docstrings** first; only reach for the dunders when
-docstrings cannot compose the rule.
-
-### 2a. Docstrings are the primary surface
-
-`agent_help()` already extracts docstrings: the class docstring becomes
-`## Purpose`, and each method's first paragraph becomes its `## Public API`
-summary. So the bar for a good docstring here is the same as for any
-well-documented library: concise summary line, then params/returns/raises if
-nontrivial. Keep per-method behavior in the method's docstring — that is where it
-stays attached through refactors.
-
-### 2b. Add `__agent_notes__()` only for cross-method behavioral rules
-
-When a rule does not fit in any single method's docstring — lifecycle order
-across methods, pre-conditions, anti-patterns ("use `call()` for non-streaming,
-`stream()` for streaming"), do/don't lists — put it on the **class** as a
-`classmethod` named `__agent_notes__()`:
-
-```python
-class Sensor:
-    """Reads a value from a hardware sensor."""
-
-    def __init__(self, pin: int, *, unit: str = "C"): ...
-    def calibrate(self, offset: float): ...
-    def read(self) -> float: ...
-
-    @classmethod
-    def __agent_notes__(cls) -> str:
-        return """
-## Do
-
-- Call `calibrate()` once during setup, before `read()`.
-
-## Do not
-
-- Do not call `read()` before `calibrate()` on first use.
-"""
-```
-
-Facts about `__agent_notes__()` worth knowing:
-
-* **Accumulates across the MRO.** Every class in the inheritance chain that
-  defines its own `__agent_notes__()` contributes a section to `agent_help()`'s
-  output. The leaf class is marked as taking precedence on conflict.
-* **Do not call `super().__agent_notes__()`** — collection is automatic.
-* **No mixin required.** Defining `__agent_notes__` on any class is enough.
-  Monkey-patching also works for classes you do not own:
-  ```python
-  ThirdPartyClass.__agent_notes__ = classmethod(lambda cls: "...")
-  ```
-* **Optional `AgentReadableMixin`.** Inheriting from
-  `agent_readable.AgentReadableMixin` is purely a convenience for type-checking
-  and IDE hints — `agent_help()` works on plain classes too.
-
-### 2c. Almost never define a custom `__agent_help__()`
-
-`__agent_help__()` **replaces** the entire auto-generated output. Use it only
-when you have a hand-formatted help string you genuinely want to ship verbatim.
-In every other case, let the auto-doc generate from your class + docstrings +
-`__agent_notes__()`.
-
-### 2d. Verify after annotating
-
-After adding or changing notes, run:
-
-```bash
-python -c "from agent_readable import agent_help; from your_module import YourClass; print(agent_help(YourClass))"
-```
-
-Check that signatures are correct (you may need to fix type hints), notes appear
-in MRO order with the leaf class marked precedence-winning, and no private
-members leaked into `## Public API`.
-
-## Footguns
-
-* **Do not define both a custom `__agent_help__()` and `__agent_notes__()` on
-  the same class.** A custom `__agent_help__()` owns the full output, so the
-  notes are silently dropped (a `UserWarning` is emitted). Fix it one of two
-  ways: fold the notes into your custom `__agent_help__()`, or remove the
-  custom `__agent_help__()` and let the auto-doc + notes path run.
-* **Do not put per-method instructions in `__agent_notes__()`.** Single-method
-  behavior belongs in that method's docstring, where it stays attached through
-  refactors. `__agent_notes__()` is for rules that span methods.
-* **Do not mix `agent_help()` with `help()`.** `help()` returns hundreds of
-  lines of inherited dunders and MRO detail; `agent_help()` returns a curated,
-  structured guide with behavioral rules attached. Use `agent_help()`.
-
-## The one rule
-
-> Before writing or modifying Python code that uses an external class, module,
-> function, or method, call `agent_help(target)` and use its output as the
-> canonical usage guide.
-
-That call is cheap, runs in any coding-agent shell, and works on any Python
-object — annotated or not.