Scope the contract-only usage claims and fix the run-usage example

[lchoquel]

Follow-up to #8. Review on the TypeScript mirror (pipelex-sdk-js#14) surfaced three defects on the run-usage page; the same text shipped here, so this keeps the two SDK docs in sync.

Dead spec link. The page linked to docs/specs/pipelex-mthds-protocol.md in the public runtime repo, where that path does not exist — the spec lives in the internal workspace repo, so there is no public target to redirect to. The link is replaced by a by-name reference to the spec and its section.

While there: the page called this "the MTHDS protocol spec". The public MTHDS protocol spec says nothing about usage reporting — the record is a Pipelex runtime concept. Corrected per the brand boundary.

Broken example. mthds_contents=[...] parses in Python but passes an Ellipsis where a bundle source string is expected. A registered pipe_code with inputs is valid and is the more idiomatic hosted call (the protocol requires at least one of pipe_code / mthds_contents).

Two guarantees stated absolutely, then contradicted. The page said the rate table "never crosses the wire" and that job_metadata et al. "must never appear on a record" — then documented, further down, that pre-contract artifacts are relayed verbatim and do carry exactly those. The spec qualifies both claims with "on a record emitted under this contract" and names the exemption; this page now does the same at both claims instead of only in the compatibility section. Matches conformance/usage_records.py, where the legacy record is deliberately excluded from the leak guard as "the documented MUST-NOT exemption, not a leak".

Docs only — no code, no contract change. make agent-check and make agent-test pass.

🤖 Generated with Claude Code

---

Summary by cubic

Update run-usage docs to fix a bad example and remove a dead spec link, and to scope contract-only guarantees correctly. Aligns Python docs with the @pipelex/sdk mirror.

• Bug Fixes
  • Replace dead spec URL with a by-name reference; clarify usage records are a Pipelex runtime concept, not part of MTHDS.
  • Fix example: use pipe_code with inputs instead of mthds_contents=[...].
  • Qualify cost-table and metadata statements with “on a record emitted under this contract”; note the pre-contract artifacts exemption (unit_costs, job_metadata).

^{Written for commit 0b04c93. Summary will update on new commits.}

[cubic-dev-ai]

No issues found across 1 file

_{You’re at about 98% of the monthly reviewed-line limit. You may want to disable incremental reviews to conserve quota. Reviews will continue until that limit is exceeded. If you need help avoiding interruptions, please contact contact@cubic.dev.}

_{Re-trigger cubic}

[greptile-apps]

Greptile Summary

This PR corrects and clarifies the run-usage documentation. The main changes are:

• Replaces the dead specification link with a by-name reference.
• Uses a registered pipe and input mapping in the run example.
• Limits current-contract wire guarantees to exclude legacy artifacts.

Confidence Score: 5/5

This looks safe to merge.

No blocking issues found in the changed documentation.

T-Rex Logs

What T-Rex did

• Reviewed the general contract validation setup by locating the executable mocked transport fixture in run-usage-example-validation.py.
• Compared the before and after logs to confirm the hosted usage flow produced the exact payload, typed result, usage fields, and total cost.
• Verified regression coverage by confirming all 50 focused tests passed in the run-usage-focused-pytest log.

_{Ran code and verified through T-Rex}

Important Files Changed

Filename	Overview
docs/run-usage.md	Corrects the usage example, specification attribution, and legacy-record exceptions.

_{Reviews (1): Last reviewed commit: "docs(usage): scope the contract-only cla..." | Re-trigger Greptile}