feat(runtime): add error details, method-safety mutation, search terms

[samzong]

Summary

Round 2 of runtime UX contracts for agent-facing generated CLIs, 7 commits:

• feat(runtime): usage errors carry an optional detail built only from spec metadata (enum sets, required flag/field names, output formats) via an explicit constructor; never echoes user input; cobra unknown command/flag paths stay detail-free.
• feat(runtime): API errors surface a layered detail: declared JSON fields (message, error, error.message, detail, depth <= 2, sanitized, <= 240 runes, bodies > 32KB skipped) -> known_errors cause matching the status -> unchanged status + hint. Raw response bodies are never emitted.
• feat(runtime): catalog mutation follows RFC 9110 method safety (GET/HEAD/OPTIONS/TRACE = read, other declared methods = write, unknown only for undeterminable); overlay mutation: read|write overrides every inference.
• feat(overlay): search_terms flow overlay -> CommandSpec -> generated literal -> catalog -> search index (identity synonym at summary weight) -> generated Skill docs.
• feat(codegen): body.flags skips nested object properties instead of rejecting the whole body; skipped fields land in body.set_only_fields, --set/--set-str help, and keep local required validation.
• fix(runtime): detail sanitization strips all non-graphic runes (C1 controls, bidi overrides); required set-only body fields are validated locally.

Verification

• make check (fmt-check, vet, golangci-lint, tests) — pass
• go test -race -count=1 ./... — pass
• go vet ./... — pass
• Isolated real-behavior verification: scratch copy of a downstream generated CLI (tokener) with replace to this branch, regenerated via lathe bootstrap; __lathe verify --json 20/20 checks ok; verified enum detail output, declared server message + known_errors fallback against a local mock upstream, mutation values, search_terms hit, and --name demo --dry-run producing {"name":"demo"} with nested limits skipped.

Compatibility

• SchemaVersion 13 -> 16 and CatalogSchemaVersion 20 -> 23: downstream CLIs must regenerate after bumping (enforced explicitly by AssertSchema).
• Catalog/envelope additions are all optional fields (error.detail, search_terms, body.set_only_fields).
• mutation value semantics: operations previously reported unknown for REST write methods now report write; consumer handling is unchanged, classification is more precise (documented in docs/contracts.md).
• Docs updated: docs/contracts.md, docs/cli-usage.md.

Checklist

• Tests or focused verification cover the changed surface.
• User-facing behavior changes are documented.
• Generated output under internal/generated/, .cache/, and ad-hoc skills/<cli-name>/ directories is not committed.
• Commits are signed off when this is ready to merge.

[codspeed-hq]

Merging this PR will degrade performance by 49.98%

⚠️ Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

⚠️ Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

❌ 21 regressed benchmarks

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	large	996.3 µs	2,255.3 µs	-55.83%
❌	BenchmarkFormatTableInferredColumns	471.3 µs	986 µs	-52.2%
❌	yaml	2.6 ms	5.4 ms	-52%
❌	BenchmarkCatalogJSON	1.5 ms	3.1 ms	-51.82%
❌	large	1.2 ms	2.6 ms	-51.41%
❌	json	658.3 µs	1,354.4 µs	-51.4%
❌	BenchmarkFindCatalogCommand	4.4 µs	9 µs	-51.02%
❌	small	99.9 µs	203.8 µs	-50.97%
❌	large	808.5 µs	1,639.7 µs	-50.7%
❌	miss	1.9 ms	3.8 ms	-50.58%
❌	table	379.9 µs	767.5 µs	-50.5%
❌	hit	1.9 ms	3.9 ms	-50.19%
❌	json-large	1.7 ms	3.4 ms	-49.96%
❌	json-small	129.6 µs	255.4 µs	-49.24%
❌	small	74.6 µs	144.9 µs	-48.49%
❌	BenchmarkParseNormalize	3.1 ms	6 ms	-48.08%
❌	large	707.2 µs	1,360.1 µs	-48%
❌	yaml-large	8.1 ms	15.5 ms	-47.9%
❌	small	76.7 µs	143.3 µs	-46.51%
❌	BenchmarkBuildFlat	1.1 ms	2 ms	-45.88%
...	...	...	...	...

ℹ️ Only the first 20 benchmarks are displayed. Go to the app to view all benchmarks.

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing fix/runtime-ux-round2 (edfa5f1) with main (7ec8e13)}