docs: make verification tutorials runnable and evidence claims precise

[imran-siddique]

What this changes

Readers encountered nonexistent CLI commands, incomplete verifier examples, stale hardware guidance, and an anchoring sequence that invalidated its own proof. This change gives signing, verification, adapter, and transcript pages runnable paths and distinguishes signature checks from hardware appraisal, transcript completeness, and independently trusted registry evidence. It also repairs published links and consolidates duplicated integration instructions.

Validation: strict MkDocs build; 50 rendered HTML files and 5,322 local links checked with no broken targets; exact tutorial blocks and documentation schema assertions pass (7 tests); Ruff and mypy pass. The full Windows suite reports 1,181 passed, 1 skipped, and 5 failures. All five reproduce on unchanged base 3a561d8 (fixture byte comparisons and Windows path separators). CI remains the merge gate. No hardware deployment was performed.

Type of change

• Editorial (clarification and link repair, no normative effect)
• Example addition

Spec section

The only change in spec/trace-v0.2.md is a license-link target. No schema or runtime behavior changes.

Checklist

• DCO sign-off
• No normative change requiring a changelog or compatibility notice

[imran-siddique]

@agentrust-io/maintainers please review and approve these page-by-page documentation corrections once CI is green. The PR removes nonexistent commands, tests the exact tutorial code, and fixes the anchoring order. Strict site and local-link checks pass; the PR records the five baseline Windows test failures.

[lywinged]

Read the description and the diff at 9ff9699, then ran the checks. Two things block, both in files the PR rewrites; everything else I could check from here checks out.

docs/verification.md has every section sign double-encoded. On this head every § in the file, 11 of them, is C3 82 C2 A7 where main has C2 A7, and the built site renders them as §3.2.3, §3.2.1, §3.3.1. No other file in the tree has the sequence. The strict build passes with them in place, and a link check has no reason to look at them. Replace the 11 sequences with § and save the file as UTF-8; re-saving alone does not undo it, the usual cause is an editor round-tripping the file through cp1252, and grep -c $'\xC3\x82\xC2\xA7' docs/verification.md printing 0 is the check.

docs/trust-levels.md loses the rule #242 merged a few hours before this PR opened. a8b7620 carries the sentence your Sep 2 ruling asked for: runtime.measurement is required on every record, under software-only it is a software commitment whose preimage the producing profile must document so a verifier can recompute it, and all-zero is reserved for a producer with no commitment to offer. This head replaces it with "The measurement can be a software commitment defined by the producer. All-zero is reserved for an example or producer that offers no measurement commitment." That keeps the all-zero rule but drops "required on every record" and the documented-preimage requirement, and those two drops put the change outside the Editorial label in the description. The #242 CHANGELOG entry, still in this tree, now describes a sentence that is not in the file. Restoring the merged sentence verbatim where the replacement now sits, under Level 0, fixes the page, the changelog description and the label in one edit.

What I verified and found right, so you do not have to re-run it. The eight removed agentrust-trace ... command lines name a CLI that does not exist: the package has no [project.scripts] and no cli module. The anchoring fix is correct: the leaf covers the complete signed object, signature included, so re-signing after setting transparency changes the bytes it hashed. tests/test_docs_quickstart.py executes the tutorial blocks and both tests pass; the full Linux suite is 1186 passed, 1 skipped, with ruff, the dash check and mypy clean. The strict MkDocs build, assembled the way docs.yml assembles it, is clean at 50 rendered pages, the count your description gives. 104 headings are removed and no file in the tree links to any of them. No BOM or CRLF in the 24 changed files. The module paths and SDK calls the added text under docs/ names exist in the package, and the profile tag and the v0.1 rejection match sign.py. The hunks in CHARTER.md, GOVERNANCE.md, CONTRIBUTING.md, Governance/License.md and spec/trace-v0.2.md only retarget the LICENSE link. Not checked from here: the five Windows-only failures and the 5,322-link count, both from your description.

[imran-siddique]

Addressed both requested changes in this PR: restored the a8b7620 measurement paragraph verbatim, including the required field and documented preimage, and replaced all 11 double-encoded section symbols. Exact UTF-8 checks pass; the seven tutorial/documentation tests and dash check pass. Further page-audit changes will stay in this PR.

[lywinged]

Approving at 38efda8. Both items from the earlier review are in, and I checked them rather than reading the reply.

The encoding: docs/verification.md carried a broken section sign at 9ff9699 and carries none at this head, matching main, which has none either. The measurement requirement: the paragraph #242 landed is absent at 9ff9699 and back at this head, byte for byte against main apart from one appended sentence pointing at the quick start.

What I ran on this head, in a fresh clone. Full suite 1186 passed and 1 skipped, with ruff, tools/check_dashes.py and mypy clean. The documentation tests are 7 and they bite: changing one line of the expected output in docs/tutorials/agt-adapter.md turns test_agt_adapter_tutorial red. Building the site the way the workflow does, mkdocs reports zero link notices where main reports fourteen, including the examples/action-receipts/README.md link I raised on #295 as not that PR's job.

The premise holds where I could check it. pyproject.toml declares no console scripts, so agentrust-trace verify, verify-hardware and verify-scitt, all of which the removed pages told readers to run, never existed. The two mentions that survive are denials: both pages now say this package has no such command. Seventy-six heading texts no longer appear under docs/, and the count of uppercase RFC 2119 keywords there is 7 before and 7 after, so nothing normative went with them. No heading leaves spec/, and the build finds no link pointing at an anchor that went away.

The one change under spec/ is the license link in the header table, from a relative path to the repository URL. On the published site that relative path resolved to nothing, which is what mkdocs was reporting. README.md keeps its relative link, which is right, since it renders on GitHub and is excluded from the site.

Not this PR. The same build still prints ten warnings, three nav entries and seven links pointing at CODE_OF_CONDUCT.md, MAINTAINERS.md and SPONSORS.md, none of which is published. That is the same class as the LICENSE links this PR fixed, and it is the last of it: after those ten, the build is quiet.

Tool-assisted: the runs and this write-up.