docs: the instruction set says what the tree actually does

[ShocOne]

CLAUDE.md is the only file that claims authority over the others, and several of its load-bearing rules no longer matched the code they govern. README.md had drifted too, and had gaps a reader could not work around.

Everything here is documentation and comments. No behaviour changes.

What was wrong

Claim	Reality
"This repo is tfpfgen v2 … the v1 repo (terraform-plugin-framework-codegen, no suffix) is the failed attempt it replaces"	That is this repo's module path and remote. The -1 suffix that made the sentence true was dropped when the repos were renamed — terraform-plugin-framework-codegen-1, tfpfgen-provider-template-1 and terraform-provider-thousandeyes-1 all redirect to their unsuffixed names now.
"Compatible releases fast-forward the moving v1 tag; breaking changes cut v2"	15 tags, all v0.x, latest v0.7.0, with v0 in sync. docs/releasing.md and every caller pin already say v0; docs/contract.md said v1 in one spot and @v0 everywhere else.
"Never reintroduce v1 vocabulary (probe, cassette, recording, scenario, blueprint, draft, merge, sweep, doctor, facts, rehearsal, curate)"	Only cassette, blueprint and doctor are absent. probe, rehearsal and scenario appear inside approved glossary definitions; docs/rehearsal.md and testdata/curated/ exist; patch-merge is an approved extension value; and recording, sweep, draft, merge, facts are ordinary English throughout. The list banned domain nouns but read as banning words.
"CI fails below 90% total (80% per core package)"	True, but "core package" is defined nowhere — the gate applies to every package in the profile, and the gate a generated provider repo runs is the total alone.
Two hygiene rules named	scripts/repo_hygiene_gate.sh enforces three. The third is: no tracked file over 1 MiB.
"Every verb keeps its exit-code contract"	docs/contract.md has one global 0/1/2 table, not a per-verb contract.

.github/workflows/release.yml told callers to pin @v1, which no longer exists.

What was missing

CLAUDE.md now records the four library absences that were already decided and nowhere written down — no OpenAPI library (internal/specmodel reads yaml.Node directly, because document order is load-bearing for the SDK generators), no test framework, no HTTP client, no mocking library — plus the test naming convention, and a Generated and measured files section covering docs/config.md, docs/emittance_tracker.md and the authored/derived split.

Verifying claims gains the rule the handoff audit demonstrates the need for: a claim about generated output is measured against a generated tree, never by grepping this repo. internal/emit/render_constraints.go spells a bound as fmt.Sprintf("%sBetween(%v, %v)", …), so grepping here for int64validator.Between finds nothing while the generator emits it.

README gains install instructions (there were none), how provider repos consume the toolkit, the backends as a named concept, the four docs/ files it never listed, and a licence line. Its repo table now names repos that exist and marks the openapi-generator proof provider as not yet stood up; the pipeline arrow starts at config validate; and docs/mapping.md's behaviour table is thirteen rows, not twelve.

Five comments carrying v1 war stories are reworded to what-and-why, which is what CLAUDE.md asks of every other comment in the tree.

Verification

make check          # fmt, build, vet, coverage 91.3% total (lowest package 85.0%), hygiene
golangci-lint run   # 0 issues
go test ./internal/config -run TestUnit_Config_ReferenceMatchesDocs

Left for you

• terraform-provider-thousandeyes and tfpfgen-provider-template still call deploymenttheory/terraform-plugin-framework-codegen-1/...@v0. It resolves only through GitHub's rename redirect, which breaks the day anything claims the old name. Fixing that is a change in those repos.
• "core package" is written here as "every package under internal/", which is what coverage_gate.sh does — say if you meant a narrower set.

🤖 Generated with Claude Code

[ShocOne]

The red check is not from this PR — main is red right now for the same reason.

TestIntegration_Specmodel_LoadsAPinnedVendorDocument and TestIntegration_IntermediateRepresentation_DerivesAPinnedVendorDocument fail because the ThousandEyes vendor moved the document:

pinned  sha256:68e45bf31813  version 7.0.100  207 path(s) / 326 operation(s)
fetched sha256:b33faf23c39f

spec.upstreamUrl for that pin tracks latest, and the vendor published 7.0.102. Fetched directly, it is a clean bump — parses fine, 208 paths / 327 operations, one new path and one new operation. The version unparsed 0 path(s) in the failure text is not a parse failure: internal/corpus has no parser to hand and uses the unparsed describer by design.

Reproduced on main with a cold cache, no changes applied:

$ git checkout main && TFPFGEN_CORPUS_DIR=$(mktemp -d) TFPFGEN_CORPUS_REQUIRED=1 \
    go test ./internal/specmodel -run TestIntegration_Specmodel_LoadsAPinnedVendorDocument
--- FAIL: TestIntegration_Specmodel_LoadsAPinnedVendorDocument
    the pinned thousandeyes document is not what … served.

It passes locally from a warm cache, which is why make check was green here; CI has no cache and fetches.

This PR touches two Go files, both comment-only (internal/corpus/corpus_test.go, internal/audit/strategy/strategy.go), so it cannot reach this. The lint and hygiene job passes.

Not repinning here. corpus.lock.json says so itself — "A change here changes what several tests mean, so it is reviewed, not applied" — and #92 and #95 were each their own PR. Say the word and I'll open one.

Worth noting for the gate itself: main last passed on 2026-08-16 and has been red since the vendor moved, with nothing to notice it. ci.yml triggers on push and pull_request only, so a pinned document rotting between merges is invisible until the next merge. A scheduled run is what would catch that class.