## Context

The CI gates prove a feature works. Nothing proves anybody can find it, and docir's user is an
AI agent that will never read this repository — it has the installed wheel, the skill `docir
agent install` wrote, and `--help`. Everything else in the repo is invisible to it.

That gap is not hypothetical. `docir bench` shipped with its only worked fixture at
`benchmarks/example_fixture.yaml`, a path the wheel does not contain — 213 entries, zero
benchmark files — while the skill named the fixture's *shape* without showing it or saying
where the document ids come from. Both surfaces read as complete to their author. An agent
following them would have written a fixture of invented ids, and `bench` would have reported
every task dropped and measured nothing.

## Decision

A business feature is done when an agent holding **only the installed package** can tell what
it is, when to reach for it, and how to invoke it — including how to obtain any input it needs.

Three surfaces carry that, and all three ship with the change:

- the **packaged skill** (`modules/agents/infra/templates/skill.md`) — what and *when*;
- the **CLI docstring** — *how*, with a worked example, since `--help` is JSON when piped and
  is the one surface an agent parses rather than guesses at;
- **`README.md`** — for the human deciding whether to adopt docir.

Edit the template, never `.claude/skills/**`, then run `docir agent update` so this repo's own
copies match what an adopter installs.

## Verification is use, not review

The instructions are then **followed**, from the state an adopter is in, and the feature run.
Re-reading what you wrote and judging it sufficient is exactly what produced the gap above. If
a step needs data, the instructions have to say where that data comes from, and following them
has to produce it.

This is adr-bea42e359960's rule one level out. That decision validates docir's prose against
the *command tree*, so a documented invocation cannot name a flag that does not exist. It
cannot tell whether the prose is enough to act on, because a resolvable command proves shape
and not sufficiency.

## Consequences

A feature costs more than its implementation, deliberately. The cost is bounded — three
surfaces and one run — and it falls on the change that introduced the feature, where the author
still knows what they meant.

It is **not** automated and should not be: a check that the skill mentions every command would
pass on a sentence naming it, which is the failure this decision exists to catch. What is
mechanised already is the narrower claim adr-bea42e359960 owns.