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

{agent_readable-0.1.1 → agent_readable-0.2.0}/.github/workflows/test.yml

@@ -7,6 +7,23 @@ on:
   workflow_dispatch:
 
 jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install dev deps
+        run: uv sync --group dev
+
+      - name: Ruff check
+        run: uv run ruff check
+
+      - name: Ruff format check
+        run: uv run ruff format --check
+
   test:
     runs-on: ubuntu-latest
     strategy:

agent_readable-0.2.0/CHANGELOG.md

@@ -0,0 +1,73 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.2] - 2026-05-30
+
+### Added
+
+- `py.typed` marker so inline type annotations are visible to downstream type
+  checkers (PEP 561).
+- A module's `__all__` is now honored as the authoritative public API when
+  present, including symbols re-exported from other modules.
+- `agent_help()` now emits a `UserWarning` when a class defines both a custom
+  `__agent_help__()` and `__agent_notes__()`, since the notes are silently
+  dropped in that case.
+- Agent Skill at `skills/agent-readable/SKILL.md` following the
+  [Agent Skills open standard](https://agentskills.io). Installable via
+  `npx skills add zydo/agent-readable --skill agent-readable` and portable
+  across Claude Code, Codex CLI (OpenAI), Gemini CLI (Google), GitHub Copilot,
+  Cursor, JetBrains Junie, Goose, OpenCode, and 40+ other adopters. The skill
+  teaches the agent to call `agent_help()` before writing Python against a
+  library and to author new APIs with `__agent_notes__()`. Supersedes
+  `AGENT-PROMPT.md` as the recommended way to wire up coding agents.
+
+### Fixed
+
+- Method signatures with a positional-only `self` no longer render a dangling
+  `/` (e.g. `backup(/, target)` now renders as `backup(target)`).
+
+### Documentation
+
+- README and examples reframed around curation, not compactness. The "Why it
+  matters" section now leads with two failure modes — what-exists (curated
+  Public API list curbs hallucinated methods and stale signatures) and
+  how-to-use (lifecycle rules via `__agent_notes__()`) — instead of a
+  comparative empirical claim about which is more common. Removed the
+  "217 vs 56 lines" framing in favor of structure-and-rules language.
+- Tagline sharpened to lead with the hallucination-stopping outcome rather
+  than the protocol mechanics.
+
+### Removed
+
+- `AGENT-PROMPT.md` (superseded by the agent skill at
+  `skills/agent-readable/SKILL.md`).
+
+## [0.1.1] - 2026-05-11
+
+### Added
+
+- `agent_help()` support for functions and methods.
+
+### Documentation
+
+- Demo GIF comparing `agent_help()` and `help()`, plus additional README
+  examples.
+
+## [0.1.0] - 2026-05-10
+
+### Added
+
+- Initial release: the `agent_help()` function, the `AgentReadable` protocol,
+  `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
+[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.1.1 → agent_readable-0.2.0}/PKG-INFO

@@ -1,15 +1,16 @@
 Metadata-Version: 2.4
 Name: agent-readable
-Version: 0.1.1
+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
+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: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
@@ -26,7 +27,13 @@ Description-Content-Type: text/markdown
 
 # agent-readable
 
-A lightweight Python protocol for exposing agent-oriented documentation from classes and modules.
+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">
@@ -39,16 +46,9 @@ A lightweight Python protocol for exposing agent-oriented documentation from cla
 
 AI coding agents recognize established libraries from their training data, but they hallucinate when APIs change, when libraries are new, or when correct usage depends on rules that aren't visible from the API surface — pre-conditions, lifecycle order, anti-patterns, *"use `call()` for non-streaming, `stream()` for streaming."*
 
-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()` is verbose and only describes interfaces.
-
-`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 the rules.
+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.
 
-```text
-help(logging.Logger)        217 lines — every inherited method, dunder, and MRO detail.
-agent_help(logging.Logger)   56 lines — structured sections + any author notes.
-```
-
-The compactness is a side effect; the structure is the point.
+`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
 
@@ -60,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"): ...
@@ -91,52 +131,19 @@ 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
 
-`help()` documents the **API surface** — what each method does. But agents fail less often on *what methods exist* than on *how to use them*: lifecycle order, pre-conditions, anti-patterns, "this method is for X, that one for Y." Those rules don't fit in docstrings (which describe single methods) and don't belong in a project-level `AGENTS.md` (which describes whole repos). They're class-level, and they need to travel with refactors.
+`agent_help()` covers two failure modes agents hit on real APIs:
 
-`agent_help()` gives them a home next to the code:
+1. **What exists.** The `## Public API` section is a curated list of current signatures pulled from runtime introspection — no hallucinated methods, no stale signatures from training data, no private members leaking in. If the agent reads this list first, it stops inventing methods that don't exist and stops calling real ones with the wrong arguments.
+2. **How to use it correctly.** Lifecycle order, pre-conditions, anti-patterns, *"this method is for X, that one for Y."* These don't fit in any single method's docstring and don't belong in a project-level `AGENTS.md` (which describes whole repos). They're class-level, and they need to travel with refactors. `__agent_notes__()` gives them a home next to the code.
+
+A concrete contrast:
 
 ```
-# help(sqlite3.Connection) — 200+ lines of terminal output:
+# help(sqlite3.Connection) — every inherited dunder, in source order:
 Help on class Connection in module sqlite3:
 
 class Connection(builtins.object)
@@ -150,12 +157,13 @@ class Connection(builtins.object)
  |  ...
  |  backup(self, target, /, *, pages=-1, progress=None, ...)
  |  blobopen(self, table, column, rowid, /, *, readonly=False, ...)
- |  ... (continues for 200+ more lines)
+ |  ... (no curation, no behavioral rules, no signal that backup() needs an
+ |        open target connection before being called)
 ```
 
-`agent_help(sqlite3.Connection)` produces a scannable summary instead — 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.
+`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
 
@@ -190,14 +198,14 @@ 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.
+- `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.
+- `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.
+- `rollback()` method: Roll back to the start of any pending transaction.
 - ...
 
 ## Agent usage rules
@@ -366,7 +374,7 @@ print(agent_help(RateLimiter))
 
 ## Example 4: Any class — no setup required
 
-Even without the mixin or duck-typing, `agent_help()` still generates compact, structured Markdown from introspection. If the class (or any class in its MRO) defines `__agent_notes__()`, those notes are auto-appended too — no mixin required. The output is still more agent-friendly than `help()`.
+Even without the mixin or duck-typing, `agent_help()` still generates structured Markdown from introspection — a curated public-API list with current signatures, free of inherited dunders and MRO clutter. If the class (or any class in its MRO) defines `__agent_notes__()`, those notes are auto-appended too — no mixin required.
 Full example: [`examples/any_class.py`](examples/any_class.py).
 
 ```python
@@ -376,7 +384,7 @@ from agent_readable import agent_help
 print(agent_help(logging.Logger))
 ```
 
-`help(logging.Logger)` produces **217 lines** of output. `agent_help(logging.Logger)` produces a compact, scannable summary:
+Compare what `agent_help(logging.Logger)` returns to what `help(logging.Logger)` does — the former lists only the public methods you'd actually call, with their current signatures and docstring summaries:
 
 ````
 # Logger
@@ -429,13 +437,15 @@ Output:
 
 ## Purpose
 
-Example: Using agent_help() on modules.
+Example: Using agent_help() on modules, functions, and methods.
 
-Demonstrates both shapes of module support:
+Demonstrates non-class targets:
   1. A custom module (this file itself).
   2. A stdlib module (pathlib).
+  3. A function (connect, defined below).
+  4. A method (Query.execute, defined below).
 
-Run this file to see both outputs:
+Run this file to see all outputs:
     python examples/modules_and_functions.py
 
 ## Public API
@@ -476,20 +486,13 @@ operating systems.
 
 ## Public API
 
-- `DirEntryInfo` class: Implementation of pathlib.types.PathInfo that provides status
 - `Path` class: PurePath subclass that can make system calls.
-- `PathInfo` class: Implementation of pathlib.types.PathInfo that provides status
 - `PosixPath` class: Path subclass for non-Windows systems.
 - `PurePath` class: Base class for manipulating paths without I/O.
 - `PurePosixPath` class: PurePath subclass for non-Windows systems.
 - `PureWindowsPath` class: PurePath subclass for Windows systems.
 - `UnsupportedOperation` class: An exception that is raised when an unsupported operation is attempted.
 - `WindowsPath` class: Path subclass for Windows systems.
-- `copy_info(info, target, follow_symlinks=True)` function: Copy metadata from the given PathInfo to the given local path.
-- `copyfileobj(source_f, target_f)` function: Copy data from file-like object source_f to file-like object target_f.
-- `ensure_different_files(source, target)` function: Raise OSError(EINVAL) if both paths refer to the same file.
-- `ensure_distinct_paths(source, target)` function: Raise OSError(EINVAL) if the other path is within this path.
-- `magic_open(path, mode='r', buffering=-1, encoding=None, errors=None, newline=None)` function: Open the file pointed to by this path and return a file object, as
 
 ## Agent usage rules
 
@@ -499,7 +502,7 @@ operating systems.
 - If usage is ambiguous, prefer the simplest documented usage pattern.
 ````
 
-Modules support less customization than classes — there is no mixin inheritance or `__agent_notes__()`. You can override the auto-generated output entirely by setting a module-level `__agent_help__` attribute (callable or string), but this is discouraged since it replaces the auto-generated summary — signatures, purpose, and public API listing are all lost. Prefer clear docstrings on the module and its functions/classes instead.
+Modules support less customization than classes — there is no mixin inheritance or `__agent_notes__()`. You can override the auto-generated output entirely by setting a module-level `__agent_help__` attribute (callable or string), but this is discouraged since it replaces the auto-generated summary — signatures, purpose, and public API listing are all lost. Prefer clear docstrings on the module and its functions/classes instead. If the module defines `__all__`, that list is honored as the authoritative public API — including symbols re-exported from other modules.
 
 You can also pass a function or method directly — `agent_help()` renders the signature, full docstring, and usage rules. The output is close to `help()` for a single callable; the bigger wins are still on classes and modules.
 
@@ -543,12 +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()`?
 
-Today, you tell it. Either:
+Install the companion agent skill:
 
-- Paste [`AGENT-PROMPT.md`](AGENT-PROMPT.md) into your conversation, or
-- Add it permanently to your repo's `AGENTS.md` / `CLAUDE.md` / `.cursor/rules` / equivalent instruction file.
+```bash
+npx skills add zydo/skills --skill agent-readable
+```
 
-"You tell it" is the hard part of any new agent protocol. An MCP server (so MCP-aware clients auto-discover the tool) is 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?
 
@@ -574,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. Copy [`AGENT-PROMPT.md`](AGENT-PROMPT.md) into your coding agent's conversation, or permanently add it to your repo's `AGENTS.md`, `CLAUDE.md`, `.cursor/rules`, `.trae/rules`, `.github/copilot-instructions.md`, or equivalent instruction file. It tells your coding agent to run `agent_help()` before modifying a class, prefer docstrings over `__agent_notes__()`, and verify that docs stay 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.
 
@@ -594,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 when a duck-typed `__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
 
@@ -632,10 +642,11 @@ If a class inherits from `AgentReadableMixin`, coding agents should call `agent_
 
 ### `agent_help(obj)`
 
-Returns a string of agent-oriented documentation for a class, instance, or module.
+Returns a string of agent-oriented documentation for a class, instance, module, function, or method.
 
-- For classes and instances: if `__agent_help__()` is defined (via 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. Otherwise, auto-generated docs are produced from introspection, with `__agent_notes__()` from every class in the MRO appended automatically. If `__agent_help__()` raises, falls back to the auto-generated path (which does include notes).
-- For modules: if the module defines a `__agent_help__` attribute (callable or string), it is used. Otherwise, auto-generated docs are produced from the module docstring and its public functions and classes.
+- For classes and instances: if `__agent_help__()` is defined (via 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). Otherwise, auto-generated docs are produced from introspection, with `__agent_notes__()` from every class in the MRO appended automatically. If `__agent_help__()` raises, falls back to the auto-generated path (which does include notes).
+- For modules: if the module defines a `__agent_help__` attribute (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 (anything `inspect.isroutine` accepts): if the routine defines an `__agent_help__` attribute (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 drops `cls`. If a callable `__agent_help__` raises, falls back to the auto-generated path.
 
 ## License