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

agent_readable-0.2.0/.github/workflows/test.yml → agent_readable-0.3.0/.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
@@ -24,6 +24,9 @@ jobs:
       - name: Ruff format check
         run: uv run ruff format --check
 
+      - name: Mypy
+        run: uv run mypy
+
   test:
     runs-on: ubuntu-latest
     strategy:
@@ -32,10 +35,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.2.0 → agent_readable-0.3.0}/.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.2.0 → agent_readable-0.3.0}/.gitignore

@@ -43,3 +43,6 @@ hatch.toml
 
 # No external dependencies for this project, and uv.lock is only needed for local dev.
 uv.lock
+
+# Local scratch files (audits, drafts, planning docs)
+.localonly/

agent_readable-0.3.0/CHANGELOG.md

@@ -0,0 +1,142 @@
+# 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.3.0] - 2026-08-23
+
+### Added
+
+- Console script `agent-readable`, so one-off use is
+  `uvx agent-readable sqlite3:Connection` instead of
+  `uvx --from agent-readable python -m agent_readable sqlite3:Connection`.
+  `python -m agent_readable` keeps working.
+- `--version` flag for the CLI.
+- Public class attributes and module constants are now listed in the Public API
+  section with their current value: `repr` for exact primitive types (never
+  executing a custom `__repr__`), the type name otherwise.
+- Enum members are listed (e.g. ``- `RED` member: 1``), and the misleading
+  `EnumMeta.__call__` constructor signature is no longer shown for enum
+  classes.
+- Module docs now include C builtins (`inspect.isroutine` instead of
+  `inspect.isfunction`), so `agent_help(math)` lists `sin` alongside
+  pure-Python functions, and module-level constants such as `math.pi` are no
+  longer dropped by the origin heuristic.
+- A constructor that introspection renders as the placeholder `(*args,
+  **kwargs)` — e.g. masked by a metaclass `__call__` — now falls back to the
+  class's `__init__`/`__new__` signature.
+- Mypy type-checking job in CI.
+- Benchmark harness (`scripts/benchmark.py`) and methodology
+  (`docs/benchmark.md`) for measuring whether `agent_help()` context reduces
+  hallucinated-API failures versus a baseline prompt. Status: not yet run;
+  no numbers are claimed until a real run is recorded.
+
+### Changed
+
+- **Breaking:** `__agent_notes__()` sections are now always appended, including
+  after a custom `__agent_help__()`'s output. Previously the notes were
+  silently dropped when a custom `__agent_help__` was defined and a
+  `UserWarning` was emitted; defining both is now a supported combination and
+  the warning is gone. For full verbatim control of the entire output, do not
+  define `__agent_notes__()` anywhere in the MRO.
+- The CLI prints a one-line `error: ...` message to stderr and exits with
+  status 2 for targets that cannot be imported or resolved, instead of raising
+  a traceback.
+
+### Fixed
+
+- A raising `__agent_notes__()` no longer breaks `agent_help()` for the class
+  and all of its subclasses; the broken notes are skipped, mirroring the
+  existing `__agent_help__()` fallback.
+- `functools.cached_property` members are no longer silently dropped from the
+  Public API; they render as properties with the wrapped function's docstring.
+
+## [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
+
+- `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.3.0...HEAD
+[0.3.0]: https://github.com/zydo/agent-readable/compare/v0.2.1...v0.3.0
+[0.2.1]: https://github.com/zydo/agent-readable/compare/v0.2.0...v0.2.1
+[0.1.2]: https://github.com/zydo/agent-readable/compare/v0.1.1...v0.1.2
+[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.3.0/PKG-INFO

@@ -0,0 +1,97 @@
+Metadata-Version: 2.5
+Name: agent-readable
+Version: 0.3.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: 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="https://raw.githubusercontent.com/zydo/agent-readable/main/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.
+- [Benchmark](docs/benchmark.md): methodology and harness measuring whether `agent_help()` context reduces hallucinated-API failures.
+
+## Other Languages
+
+- TypeScript: [`agent-readable-ts`](https://github.com/zydo/agent-readable-ts)
+
+## License
+
+[MIT](LICENSE)

agent_readable-0.3.0/README.md

@@ -0,0 +1,70 @@
+# 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="https://raw.githubusercontent.com/zydo/agent-readable/main/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.
+- [Benchmark](docs/benchmark.md): methodology and harness measuring whether `agent_help()` context reduces hallucinated-API failures.
+
+## Other Languages
+
+- TypeScript: [`agent-readable-ts`](https://github.com/zydo/agent-readable-ts)
+
+## License
+
+[MIT](LICENSE)

agent_readable-0.3.0/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       | Replaces the auto-generated base document  | Additive: appended after the auto-doc or custom `__agent_help__()` output     |
+| Composition     | Single class wins, closest in MRO          | Accumulated across the MRO; leaf class wins on conflict                       |
+| When to use     | Custom control over the base document      | Extra do/don't rules on top of any base                                       |
+| Skipped when    | Always called if defined                   | Never skipped when defined; a notes method that raises is skipped             |
+| Mixin required? | No                                         | No                                                                            |
+
+When a class defines both `__agent_help__()` and `__agent_notes__()`, the custom help replaces the auto-generated base document and the notes are appended after it — the same additive behavior as the auto-doc path, so no combination of the two dunders silently drops notes. If you need full verbatim control of the entire output, do not define `__agent_notes__()` anywhere in the class hierarchy.
+
+## 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 (methods, properties, cached properties, constants, and enum members), default usage rules, and accumulated `__agent_notes__()` sections when present. For modules, it includes purpose, public functions (including C builtins), public classes, and constants. 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 as the base document. Duck-typed implementations replace the auto-generated base; `__agent_notes__()` sections from the MRO are still appended after it (the mixin default already embeds notes, so its output is used as-is). If `__agent_help__()` raises, `agent_help()` falls back to the auto-generated path, which does include notes. A `__agent_notes__()` that raises is skipped rather than fatal, so one broken notes method cannot take down help for a class and its subclasses.
+
+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.3.0/docs/benchmark.md

@@ -0,0 +1,79 @@
+# Benchmark: does `agent_help()` context reduce API hallucination?
+
+**Status: not yet run.** This page documents the methodology and the harness
+(`scripts/benchmark.py`). No numbers are published until a real run has been
+executed and recorded here — claims in the README about hallucination and
+token efficiency remain unevidenced until then.
+
+## The question
+
+When a coding agent writes Python against an API it has not seen (a new
+library, a recent release, a project-private module), does injecting
+`agent_help(target)` output into the prompt reduce failures compared with the
+same prompt without it?
+
+The failure modes scored are the two documented in [Why it matters](why.md):
+
+- **What exists** — hallucinated attributes and methods, measured as
+  `AttributeError` at runtime.
+- **How to use it** — wrong signatures or call shapes, measured as `TypeError`
+  at runtime.
+
+## Method
+
+For each task (one target library plus a natural-language coding prompt) and
+each condition, the harness asks the model for a single runnable script and
+executes it against the installed library:
+
+| Condition | Prompt |
+| --- | --- |
+| `baseline` | The task prompt only. |
+| `agent_help` | The task prompt plus `agent_help(target)` output labeled as reference documentation for the installed version. |
+
+Every generated script runs in a fresh subprocess against the same
+environment. Outcomes:
+
+| Outcome | Meaning |
+| --- | --- |
+| `ok` | Script exits 0. |
+| `attributeerror` | Runtime `AttributeError` — most directly indicates a hallucinated API. |
+| `typeerror` | Runtime `TypeError` — wrong signature or call shape. |
+| `nameerror`, `importerror` | Reference or import failures. |
+| `other_error`, `timeout`, `no_code`, `api_error` | Everything else; reported but not counted as API hallucination. |
+
+Headline metric: the `ok` rate per condition, plus the split between
+`attributeerror` and `typeerror`. Results are recorded below with the date,
+model, sample count, and library versions.
+
+## Running it
+
+The harness calls the Anthropic API (needs `ANTHROPIC_API_KEY` or an
+`ant auth login` profile) and requires the target libraries to be installed.
+It is deliberately not part of CI.
+
+```bash
+uv run --with anthropic --with icalendar --with feedparser \
+    python scripts/benchmark.py --samples 5 --out .localonly/benchmark-results.json
+```
+
+Custom task sets are JSON files of `{module, target, task}` entries passed via
+`--tasks`. Choose targets the model plausibly has weak training coverage of:
+small libraries, recent releases, or project-private code — for well-known
+stable APIs the model may succeed in both conditions and the benchmark
+measures nothing.
+
+## Threats to validity
+
+- **Target familiarity.** A model that already knows a library reduces the
+  gap; a model that misremembers a *changed* API may fail both conditions.
+  Unfamiliar targets are the population of interest.
+- **Task wording.** The injected documentation is the only intended
+  difference; prompts are otherwise identical.
+- **Execution-only scoring.** A script can exit 0 and still be semantically
+  wrong; `ok` is an upper bound on correctness, not a proof of it.
+- **Sample size.** Per-task differences at small sample counts are noise;
+  read the aggregate.
+
+## Results
+
+_None yet._