`docs/states.yaml` is the documented placement and the one location auto-discovery never searches

[vjovanov]

Problem

docs/states.yaml is the placement the project recommends for a single state machine, and it is the one location auto-discovery never looks in. Both statements sit in the same section, in the spec and in the skill.

docs/functional-spec/rhei-state-machine-writer.spec.md:487-496 — "## 5. File Placement":

State machine YAML files should be placed in the project at a conventional location:

• docs/states.yaml — for projects with a single state machine.

Plans normally pick up a sibling or workspace-root states.yaml automatically when they declare **States:** <name>.

crates/rhei-cli/skills/rhei-state-machine-writer/SKILL.md:264-270 says the same, and goes further — it calls docs/states.yaml "auto-discovered by a sibling or workspace-root plan."

It is not. Discovery is resolve_declared_rhei_machine (crates/rhei-cli/src/cli/completion_context.rs:363-379), whose candidates are the rhei's own execution root, auto_state_machine_path(input), and every rhei root by name-match. Nothing under docs/.

Reproduction

Identical machine (name: custom), identical plan declaring **States:** custom, only the file's location differs:

A) docs/states.yaml   — the documented conventional placement
   × plan declares state machine 'custom', but no auto-discovered states file

B) ./states.yaml      — beside the plan
   Validation succeeded

C) docs/states.yaml passed as --state-machine docs/states.yaml
   Validation succeeded

So the recommendation works only with the override the same paragraph describes as the thing you use when you need to deviate from the convention.

Affected

• docs/functional-spec/rhei-state-machine-writer.spec.md:490 — normative, so this is a spec/implementation divergence, not just stale docs.
• crates/rhei-cli/skills/rhei-state-machine-writer/SKILL.md:266 — adds the false "auto-discovered" claim.
• crates/rhei-cli/skills/rhei-plan-writer/SKILL.md:56 — tells an agent without the CLI that the machine is "typically docs/states.yaml".
• crates/rhei-cli/skills/rhei-plan-writer/references/default-states.md:3 — same assumption.

docs/states.yaml does not exist in this repository; panta/states.yaml does. The convention is not one the project follows itself.

Expected

One decision, applied to all four files. Either:

• Document what discovery does — the rhei's own root, the plan's sibling directory, and the project root — and drop docs/ from the recommended placements; or
• Make discovery match the recommendation by adding docs/states.yaml to the candidate list.

The first is the smaller change and matches what every shipped example and this repository's own panta/states.yaml already do. Worth deciding deliberately, because the spec is the normative half.

Note the docs/states.yaml strings in tests_cli_render.rs:701 and tests_complete_reset_tooling.rs:123 are explicit --state-machine fixture paths and are unaffected — an explicit path works from anywhere.

Found while fixing #68.