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

agent_readable-0.1.2/.github/workflows/test.yml → agent_readable-0.2.1/.github/workflows/ci.yml

@@ -1,4 +1,4 @@
-name: Tests
+name: CI
 
 on:
   push:
@@ -10,10 +10,10 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v8.2.0
 
       - name: Install dev deps
         run: uv sync --group dev
@@ -32,10 +32,12 @@ jobs:
         python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          cache-suffix: py${{ matrix.python-version }}
 
       - name: Set up Python ${{ matrix.python-version }}
         run: uv python install ${{ matrix.python-version }}

{agent_readable-0.1.2 → agent_readable-0.2.1}/.github/workflows/publish.yml

@@ -9,16 +9,16 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v3
+        uses: astral-sh/setup-uv@v8.2.0
 
       - name: Build sdist + wheel
         run: uv build
 
       - name: Upload artifacts
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v7
         with:
           name: dist
           path: dist/
@@ -33,7 +33,7 @@ jobs:
       id-token: write
     steps:
       - name: Download artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/
@@ -48,7 +48,7 @@ jobs:
       contents: write
     steps:
       - name: Download artifacts
-        uses: actions/download-artifact@v4
+        uses: actions/download-artifact@v8
         with:
           name: dist
           path: dist/

{agent_readable-0.1.2 → agent_readable-0.2.1}/CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-07-04
+
+### Documentation
+
+- Restructured the README into a concise overview and moved detailed guidance
+  into focused docs for getting started, examples, authoring, rationale, and
+  FAQ.
+- Added CI and PyPI badges to the README.
+- Added `uv add`, `uvx`, `uv tool run`, and `pipx run` installation and
+  one-off execution examples.
+- Added the TypeScript implementation under "Other Languages".
+
+### Changed
+
+- Renamed the GitHub Actions test workflow file to `ci.yml` and its display
+  name to `CI`.
+- Updated GitHub Actions versions to Node 24-compatible releases.
+- Made the uv cache key unique for each Python version in the CI matrix.
+
 ## [0.1.2] - 2026-05-30
 
 ### Added
@@ -67,7 +86,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.1.2...HEAD
+[Unreleased]: https://github.com/zydo/agent-readable/compare/v0.2.1...HEAD
+[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
 [0.1.1]: https://github.com/zydo/agent-readable/compare/v0.1.0...v0.1.1
 [0.1.0]: https://github.com/zydo/agent-readable/releases/tag/v0.1.0

agent_readable-0.2.1/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: agent-readable
+Version: 0.2.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
+Project-URL: Changelog, https://github.com/zydo/agent-readable/blob/main/CHANGELOG.md
+Author: zydo and agent-readable contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,agent-help,ai,ai-agent,coding-agent,context-engineering,docstring,documentation,llm,mixin,prompt-engineering,protocol,vibe-coding
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Code Generators
+Classifier: Topic :: Software Development :: Documentation
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# agent-readable
+
+[![CI](https://github.com/zydo/agent-readable/actions/workflows/ci.yml/badge.svg)](https://github.com/zydo/agent-readable/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/agent-readable.svg)](https://pypi.org/project/agent-readable/)
+
+Stop coding agents from hallucinating Python APIs. `agent_help(target)` reads the live public API surface from any Python class, module, function, or method and renders compact, agent-oriented Markdown with current signatures and docstring summaries. When a library opts in, it can also return class-level usage rules such as lifecycle order, preconditions, and anti-patterns.
+
+To let your coding agent automatically call `agent_help()` before using an unfamiliar API, install the companion skill:
+
+```bash
+npx skills add zydo/skills --skill agent-readable
+```
+
+<!-- markdownlint-disable MD033 -->
+<p align="center">
+  <strong><code>logging.Logger</code> compared with <code>agent_help()</code> and <code>help()</code></strong><br>
+  <img src="docs/agent_help_vs_help.gif" alt="agent_help vs help">
+</p>
+<!-- markdownlint-enable MD033 -->
+
+## 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.
+
+```python
+from agent_readable import agent_help
+import logging
+
+print(agent_help(logging.Logger))
+```
+
+`agent_help()` works on plain Python objects with no setup required. It returns a curated public API list from runtime introspection, so agents see what exists in the installed version instead of guessing from stale training data.
+
+Library authors can optionally add usage rules next to the code:
+
+```python
+class Sensor:
+    """Reads a value from a hardware sensor."""
+
+    def read(self) -> float:
+        """Read the current sensor value."""
+
+    @classmethod
+    def __agent_notes__(cls) -> str:
+        return """
+## Do
+
+- Call `calibrate()` once during setup, before `read()`.
+
+## Do not
+
+- Do not call `read()` before calibration on first use.
+"""
+```
+
+## Docs
+
+- [Getting started](docs/getting-started.md): installation, quickstart, CLI usage, and other language implementations.
+- [Why it matters](docs/why.md): the API hallucination problem, token efficiency, and how this compares to other agent-doc patterns.
+- [Examples](docs/examples.md): wrapping existing classes, inherited notes, duck typing, plain classes, modules, functions, and methods.
+- [Authoring guide](docs/authoring.md): `__agent_help__`, `__agent_notes__`, class docstring hints, freshness guidance, and API reference.
+- [FAQ](docs/faq.md): common questions about agent skills, docstrings, `AGENTS.md`, third-party libraries, and constrained decoding.
+
+## Other Languages
+
+- TypeScript: [`agent-readable-ts`](https://github.com/zydo/agent-readable-ts)
+
+## License
+
+[MIT](LICENSE)

agent_readable-0.2.1/README.md

@@ -0,0 +1,69 @@
+# agent-readable
+
+[![CI](https://github.com/zydo/agent-readable/actions/workflows/ci.yml/badge.svg)](https://github.com/zydo/agent-readable/actions/workflows/ci.yml) [![PyPI](https://img.shields.io/pypi/v/agent-readable.svg)](https://pypi.org/project/agent-readable/)
+
+Stop coding agents from hallucinating Python APIs. `agent_help(target)` reads the live public API surface from any Python class, module, function, or method and renders compact, agent-oriented Markdown with current signatures and docstring summaries. When a library opts in, it can also return class-level usage rules such as lifecycle order, preconditions, and anti-patterns.
+
+To let your coding agent automatically call `agent_help()` before using an unfamiliar API, install the companion skill:
+
+```bash
+npx skills add zydo/skills --skill agent-readable
+```
+
+<!-- markdownlint-disable MD033 -->
+<p align="center">
+  <strong><code>logging.Logger</code> compared with <code>agent_help()</code> and <code>help()</code></strong><br>
+  <img src="docs/agent_help_vs_help.gif" alt="agent_help vs help">
+</p>
+<!-- markdownlint-enable MD033 -->
+
+## 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.
+
+```python
+from agent_readable import agent_help
+import logging
+
+print(agent_help(logging.Logger))
+```
+
+`agent_help()` works on plain Python objects with no setup required. It returns a curated public API list from runtime introspection, so agents see what exists in the installed version instead of guessing from stale training data.
+
+Library authors can optionally add usage rules next to the code:
+
+```python
+class Sensor:
+    """Reads a value from a hardware sensor."""
+
+    def read(self) -> float:
+        """Read the current sensor value."""
+
+    @classmethod
+    def __agent_notes__(cls) -> str:
+        return """
+## Do
+
+- Call `calibrate()` once during setup, before `read()`.
+
+## Do not
+
+- Do not call `read()` before calibration on first use.
+"""
+```
+
+## Docs
+
+- [Getting started](docs/getting-started.md): installation, quickstart, CLI usage, and other language implementations.
+- [Why it matters](docs/why.md): the API hallucination problem, token efficiency, and how this compares to other agent-doc patterns.
+- [Examples](docs/examples.md): wrapping existing classes, inherited notes, duck typing, plain classes, modules, functions, and methods.
+- [Authoring guide](docs/authoring.md): `__agent_help__`, `__agent_notes__`, class docstring hints, freshness guidance, and API reference.
+- [FAQ](docs/faq.md): common questions about agent skills, docstrings, `AGENTS.md`, third-party libraries, and constrained decoding.
+
+## Other Languages
+
+- TypeScript: [`agent-readable-ts`](https://github.com/zydo/agent-readable-ts)
+
+## License
+
+[MIT](LICENSE)

agent_readable-0.2.1/docs/authoring.md

@@ -0,0 +1,79 @@
+# Authoring guide
+
+## Keeping agent docs up to date
+
+Agent docs can go stale when classes change: new methods, changed behavior, or removed APIs. Install the companion skill to teach your agent to run `agent_help()` before modifying a class, prefer docstrings over `__agent_notes__()` for API summaries, and verify that the output stays accurate after changes.
+
+```bash
+npx skills add zydo/skills --skill agent-readable
+```
+
+## The `__agent_help__` protocol
+
+`__agent_help__()` is a dunder protocol for tool-specific documentation, similar in spirit to:
+
+- `__doc__`: read by Python `help()`, Sphinx, IDEs, and REPLs.
+- `__rich_repr__`: read by Rich when it renders an object.
+- `__html__`: read by Django, Jinja2, and MarkupSafe when rendering HTML.
+
+Unlike `__str__` or `__fspath__`, these dunders do not change Python runtime behavior. They are metadata slots a specific tool reads when it wants a representation. `__agent_help__` follows the same pattern for agent documentation.
+
+Classes that define a `@classmethod` named `__agent_help__` returning a `str` are considered agent-readable. Modules can define a top-level `__agent_help__` attribute, either 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.
+
+## `__agent_help__` vs `__agent_notes__`
+
+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, closest in MRO          | Accumulated across the MRO; leaf class wins on conflict                       |
+| When to use     | Total control over rendered text           | Auto-doc plus extra do/don't rules                                            |
+| Skipped when    | Always called if defined                   | Silently dropped, with `UserWarning`, when custom `__agent_help__` is present |
+| Mixin required? | No                                         | No                                                                            |
+
+When a class defines both `__agent_help__()` and `__agent_notes__()`, the notes are silently dropped because `__agent_help__()` owns the output and the auto-doc plus 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 review error. Fix it by folding the notes into `__agent_help__()`, or by dropping custom `__agent_help__()` and letting the auto-doc plus notes path run.
+
+## Class docstring hints
+
+For classes that inherit `AgentReadableMixin`, add a short hint in the class docstring:
+
+```python
+class ResourcePool(AgentReadableMixin):
+    """
+    Rotates interchangeable resources such as API keys.
+
+    Agent usage:
+        Run ``agent_help(ResourcePool)`` before using this class in generated code.
+    """
+```
+
+This way, even agents that only see the source or call `help()` are reminded to check `agent_help()`.
+
+## API reference
+
+### `agent_help(target)`
+
+Render agent-oriented Markdown for a class, module, function, or method.
+
+For classes, the output includes purpose, constructor, public API, default usage rules, and accumulated `__agent_notes__()` sections when present. For modules, it includes purpose, public functions, and public classes. For functions and methods, it includes signature, docstring, and default usage rules.
+
+For classes and instances, if `__agent_help__()` is defined through the mixin or duck typing, it is called and its return value is used verbatim. Duck-typed implementations are responsible for their own formatting, and notes are not auto-appended. If such a class also defines `__agent_notes__()`, a `UserWarning` is emitted because those notes are silently dropped. Fold them into `__agent_help__()`, or drop the custom `__agent_help__()` to use the auto-doc path. If `__agent_help__()` raises, `agent_help()` falls back to the auto-generated path, which does include notes.
+
+For modules, if the module defines a `__agent_help__` attribute, either callable or string, it is used. Otherwise, auto-generated docs are produced from the module docstring and its public functions and classes. When the module defines `__all__`, that list is the authoritative public API, so re-exported symbols are included. Otherwise public members are discovered by introspection, skipping private names and anything defined outside the module.
+
+For functions and methods, if the routine defines a `__agent_help__` attribute, either callable or string, it is used. Otherwise, auto-generated docs render the signature, full docstring, and usage rules. A bound method's signature drops `self`, and a classmethod's signature drops `cls`. If a callable `__agent_help__` raises, `agent_help()` falls back to the auto-generated path.
+
+### `AgentReadable`
+
+A runtime-checkable `typing.Protocol` that requires `__agent_help__() -> str`.
+
+### `AgentReadableMixin`
+
+A mixin class for classes that provides a default `__agent_help__()` implementation using introspection. The mixin is convenience only: defining `__agent_notes__()` directly on any class also works, and notes are collected automatically regardless of inheritance from the mixin.
+
+The mixin does not apply to modules; modules are supported directly by `agent_help()`.
+
+If a class inherits from `AgentReadableMixin`, coding agents should call `agent_help(TheClass)` before generating code that uses it.

agent_readable-0.2.1/docs/examples.md

@@ -0,0 +1,253 @@
+# Examples
+
+These examples demonstrate five ways to use `agent_help()`: three with library-author opt-in and two on plain classes or modules with no setup.
+
+## Example 1: Wrapping an existing class
+
+Add agent-readable docs to any class, including ones you do not own. Full example: [`examples/sqlite_connection.py`](../examples/sqlite_connection.py).
+
+```python
+import sqlite3
+from agent_readable import AgentReadableMixin, agent_help
+
+
+class Connection(sqlite3.Connection, AgentReadableMixin):
+    """An agent-friendly wrapper around sqlite3.Connection."""
+
+    @classmethod
+    def __agent_notes__(cls) -> str:
+        return (
+            "Additional notes about using Connection here. "
+            "For example, common pitfalls, best practices, etc."
+        )
+```
+
+Override `__agent_notes__()` to add extra guidance, or leave it out for auto-generated docs only.
+
+`agent_help(Connection)` output excerpt:
+
+```text
+# Connection
+
+## Purpose
+
+An agent-friendly wrapper around sqlite3.Connection.
+
+## Public API
+
+- `backup(target, *, pages=-1, progress=None, name='main', sleep=0.25)` method: Makes a backup of the database.
+- `close()` method: Close the database connection.
+- `commit()` method: Commit any pending transaction to the database.
+- `execute(...)` method: Executes an SQL statement.
+- `rollback()` method: Roll back to the start of any pending transaction.
+
+## 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 Connection
+
+Additional notes about using Connection here. For example, common pitfalls, best practices, etc.
+```
+
+## Example 2: Inheritance with accumulated notes
+
+Override `__agent_notes__()` to add usage guidance. Notes accumulate through inheritance automatically. Full example: [`examples/temperature.py`](../examples/temperature.py).
+
+```python
+from agent_readable import AgentReadableMixin, agent_help
+
+
+class Sensor(AgentReadableMixin):
+    """Reads a value from a hardware sensor."""
+
+    def __init__(self, pin: int, *, unit: str = "C"): ...
+
+    def read(self) -> float:
+        """Read the current sensor value."""
+
+    def calibrate(self, offset: float):
+        """Apply a calibration offset."""
+
+    @classmethod
+    def __agent_notes__(cls) -> str:
+        return """
+## Do
+
+- Call `calibrate()` once during setup, before `read()`.
+- Handle negative values -- sensors may report below zero.
+
+## Do not
+
+- Do not call `read()` before `calibrate()` on first use.
+"""
+
+
+class CalibratedSensor(Sensor):
+    """A sensor with factory calibration applied."""
+
+    def reset(self):
+        """Reset to factory calibration."""
+
+    @classmethod
+    def __agent_notes__(cls) -> str:
+        return """
+## Do
+
+- Call `reset()` if readings drift unexpectedly.
+
+## Do not
+
+- Do not call `calibrate()` -- use `reset()` instead. Factory calibration
+  is pre-applied and `calibrate()` would double-adjust.
+"""
+```
+
+`agent_help(CalibratedSensor)` includes notes from both classes. The child class's notes explicitly state they take precedence over the parent's, so the agent knows `reset()` replaces `calibrate()` for `CalibratedSensor`.
+
+## Example 3: Duck-typed custom output
+
+Any class that defines a `__agent_help__()` classmethod works, with no inheritance required. Full example: [`examples/duck_type.py`](../examples/duck_type.py).
+
+```python
+from agent_readable import agent_help
+
+
+class RateLimiter:
+    """Token bucket rate limiter."""
+
+    def __init__(self, max_tokens: int, refill_rate: float): ...
+
+    def acquire(self, tokens: int = 1) -> bool:
+        """Try to acquire tokens. Returns False if rate-limited."""
+
+    def wait(self, tokens: int = 1) -> None:
+        """Block until tokens are available."""
+
+    @classmethod
+    def __agent_help__(cls) -> str:
+        return (
+            "# RateLimiter\n"
+            "\n"
+            "## Constructor\n"
+            "\n"
+            "```python\n"
+            "RateLimiter(max_tokens: int, refill_rate: float)\n"
+            "```\n"
+            "\n"
+            "## Do\n"
+            "\n"
+            "- Use `acquire()` for non-blocking checks.\n"
+            "- Use `wait()` when you must proceed regardless of rate.\n"
+            "- Set `refill_rate` to tokens/second.\n"
+            "\n"
+            "## Do not\n"
+            "\n"
+            "- Do not call `acquire()` in a tight loop without sleeping.\n"
+            "- Do not assume `acquire()` always returns True.\n"
+        )
+
+
+print(agent_help(RateLimiter))
+```
+
+Use `__agent_help__()` when you need total control over the rendered output. Use `__agent_notes__()` when you want auto-generated API docs plus your extra rules.
+
+## Example 4: Any class, no setup required
+
+Even without the mixin or duck typing, `agent_help()` generates structured Markdown from introspection: a curated public API list with current signatures, free of inherited dunders and MRO clutter. Full example: [`examples/any_class.py`](../examples/any_class.py).
+
+```python
+import logging
+from agent_readable import agent_help
+
+print(agent_help(logging.Logger))
+```
+
+Output excerpt:
+
+````
+# Logger
+
+## Constructor
+
+```python
+Logger(name, level=0)
+```
+
+## Purpose
+
+Instances of the Logger class represent a single logging channel. A
+"logging channel" indicates an area of an application.
+
+## Public API
+
+- `addFilter(filter)` method: Add the specified filter to this handler.
+- `addHandler(hdlr)` method: Add the specified handler to this logger.
+- `debug(msg, *args, **kwargs)` method: Log 'msg % args' with severity 'DEBUG'.
+- `error(msg, *args, **kwargs)` method: Log 'msg % args' with severity 'ERROR'.
+- `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'.
+````
+
+No mixin, no duck typing: just pass any class to `agent_help()`.
+
+## Example 5: Modules, functions, and methods
+
+`agent_help()` also works on modules, functions, and methods. Full example: [`examples/modules_and_functions.py`](../examples/modules_and_functions.py).
+
+```python
+import sys
+from agent_readable import agent_help
+
+print(agent_help(sys.modules[__name__]))
+```
+
+Module output includes the module docstring, public functions, and classes:
+
+````python
+# __main__
+
+## Purpose
+
+Example: Using agent_help() on modules, functions, and methods.
+
+## Public API
+
+- `Query` class: Build and execute a query.
+- `connect(host: str, port: int = 5432) -> str` function: Connect to a database server.
+- `disconnect()` function: Close the connection.
+
+## Agent usage rules
+
+- Prefer the public API listed above.
+- Do not use private names starting with `_`.
+- Do not invent unsupported behavior.
+- If usage is ambiguous, prefer the simplest documented usage pattern.
+````
+
+You can also pass any stdlib or third-party module:
+
+```python
+import pathlib
+from agent_readable import agent_help
+
+print(agent_help(pathlib))
+```
+
+If the module defines `__all__`, that list is honored as the authoritative public API, including symbols re-exported from other modules.
+
+Functions and methods render their signature, full docstring, and usage rules:
+
+```python
+import pathlib
+from agent_readable import agent_help
+
+print(agent_help(pathlib.Path.read_text))
+```
+
+Modules support less customization than classes. You can override generated module output entirely by setting a module-level `__agent_help__` attribute, but this is discouraged because it replaces the auto-generated summary, signatures, purpose, and public API list. Prefer clear module, function, and class docstrings instead.

agent_readable-0.2.1/docs/faq.md

@@ -0,0 +1,50 @@
+# FAQ
+
+## How does my agent know to call `agent_help()` instead of `help()`?
+
+Install the companion agent skill:
+
+```bash
+npx skills add zydo/skills --skill agent-readable
+```
+
+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: invoke the skill explicitly there rather than relying on description-match auto-activation.
+
+## How is this different from `AGENTS.md`, `llms.txt`, or Cursor rules?
+
+Different granularity, different drift profile.
+
+`AGENTS.md`, `llms.txt`, and `.cursor/rules` are project-level: one file per repo. They are good for rules like "use pnpm," "run lint before commit," or "this codebase prefers functional style."
+
+`agent-readable` is class- or module-level: rules live next to the API they describe. It is better for guidance like "`ResourcePool.call()` is for non-streaming requests; for streaming, use `stream()` instead."
+
+Use both. They do not compete. The advantage of class-level docs is that they travel with the code. When someone refactors `ResourcePool` into two classes, the rules move with the relevant class in the same PR instead of sitting stale in a sidecar file.
+
+## Why not just write better docstrings?
+
+Docstrings answer "what does this do?" They are not designed for "when may I call this?" or "what is the wrong way to use this?"
+
+Mixing both categories into the docstring makes the API summary noisier without helping agents reliably find usage rules. `__agent_notes__()` is for the second category, and it accumulates across the MRO automatically. Class docstrings do not compose like that.
+
+## Does this work for libraries I do not own?
+
+Yes. Two common options:
+
+- Subclass the target class and add `AgentReadableMixin` or `__agent_notes__()`.
+- Monkey-patch: `ThirdPartyClass.__agent_notes__ = classmethod(lambda cls: "...")`.
+
+`agent_help()` collects notes from the entire MRO; the mixin is not required.
+
+## Does it work without my class doing anything?
+
+Yes. `agent_help()` falls back to introspection. 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. The strongest known mitigation is constrained decoding at the harness or decoder layer: masking illegal API tokens before generation, so the model cannot produce a nonexistent method at all.
+
+`agent_help()` takes a 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 decoder. Either way, verify generated code before merging.