docs: 0.3.0 sweep — kernel migration + verify-status gate, integration-point parity

[vilenarios]

Summary

End-to-end accuracy sweep across CLAUDE.md, README.md, and docs/* after the 0.3.0 release. Two themes weren't yet reflected in the long-form docs:

1. Cryptographic primitives now delegate to the shared ar-io-proof kernel (>=0.2.0, conformance-gated against test-vectors-v1.0). The plugin's ProofEngine is an adapter; key persistence stays plugin-owned. Old "via the jcs package" framing replaced with the kernel reference.
2. VerifyStatusClient + the VerifiedModel agent verify-status gate (Lane E shipped 0.2.x; per-predict re-check + cleanup shipped 0.3.0) are now first-class integration points alongside anchor() / ArioMlflowClient / VerifiedModel. README/CLAUDE bumped from "three integration points" to four; production + threat-model docs gain ops/defense sections.

What changed (no code, docs only)

File	Update
CLAUDE.md	"What this is" mentions kernel + agent gate. Integration points: 3→4 (VerifyStatusClient). VerifiedModel description covers asset_id=, verify_status_client=, on_failure, recheck_per_predict, recheck_max_cache_age, phase field. Module layout: proof.py as adapter, verify.py mentions tx_id= out-of-band routing, new verify_status_client.py + errors.py entries. Conventions add "kernel discipline" + "verify-status gate as defense layer" rules.
README.md	Dep list mentions ar-io-proof. New #### Agent verify-status gate (runtime tamper detection) subsection under VerifiedModel with full constructor example + exception-family link + loopback-only caveat.
docs/architecture.md	Paragraph naming ar-io-proof as the family-contract impl + adapter shape.
docs/verification.md	Top-of-doc kernel reference + new Tx-ID routing subsection on the tx_id= kwarg vs. legacy envelope mutation (which breaks on cross-product ario.agent/v1 envelopes).
docs/plugin-production.md	New Agent verify-status gate (runtime tamper detection) subsection under CI/CD: co-location, secret provisioning, on_failure choice, api-guard 503 fail-open behavior.
docs/plugin-threat-model.md	New T1a "Deployed-file tamper (runtime)" sibling to T1: gate covers deployed copy where IntegrityError covers the registry copy.

Test plan

• No code changes
• Local sanity: 230 passed / 21 skipped against PyPI ar-io-proof@0.2.0
• test_plugin_safety.py::test_version_matches_pyproject_toml green (version pins untouched, still 0.3.0)
• CI sweep (matrix + CodeRabbit) on this PR

Co-Authored-By: Claude Opus 4.7 noreply@anthropic.com

Summary by CodeRabbit

• Documentation
  • Enhanced verification and architecture documentation to clarify cryptographic primitives implementation and kernel responsibilities.
  • Added comprehensive production deployment guidance for runtime tamper-detection capabilities.
  • Documented agent verify-status gate configuration, failure handling, and operational topology requirements.
  • Clarified dependency specifications and verification entry point usage patterns.
  • Expanded threat model documentation with runtime deployment-file tampering scenarios.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b4c32ae3-6b9f-4c6f-9bee-f1cf772e602d

📥 Commits

Reviewing files that changed from the base of the PR and between c717d0c and c61b2fe.

📒 Files selected for processing (6)

• CLAUDE.md
• README.md
• docs/architecture.md
• docs/plugin-production.md
• docs/plugin-threat-model.md
• docs/verification.md

---

📝 Walkthrough

Walkthrough

Documentation-only update across six files. Adds the ar-io-proof kernel/adapter boundary explanation to architecture.md, verification.md, and CLAUDE.md; introduces a new "Agent verify-status gate" section to README.md and plugin-production.md; adds a T1a runtime tamper threat to plugin-threat-model.md; and documents tx-id keyword routing, soft-fail semantics, and contributor conventions.

Changes

Documentation: ar-io-proof kernel, verify-status gate, and conventions

Layer / File(s)	Summary
ar-io-proof kernel and adapter architecture docs docs/architecture.md, docs/verification.md, CLAUDE.md	architecture.md gains a "Core design" paragraph describing the ar-io-proof kernel's ownership of canonicalization/sign/verify primitives and the ario_mlflow.proof adapter's responsibility for key persistence and MLflow-shaped output. verification.md adds a note attributing byte-level checks to the kernel and describes mlflow-shaped wrappers over verify_envelope. CLAUDE.md kernel intro and module-layout sections are rewritten to enumerate kernel vs plugin adapter boundaries explicitly.
Runtime verify-status gate documentation README.md, docs/plugin-production.md, docs/plugin-threat-model.md, CLAUDE.md	README.md adds a new "Agent verify-status gate (runtime tamper detection)" section documenting VerifyStatusClient constructor parameters, failure modes, and agent verdict mapping. plugin-production.md adds a matching production guide section covering deployment topology, management-secret provisioning, and license gating. plugin-threat-model.md introduces the T1a runtime tamper threat and its mitigations. CLAUDE.md expands the four public integration points with behavioral contracts for VerifiedModel and VerifyStatusClient.
Tx-ID routing, soft-fail semantics, and conventions docs/verification.md, CLAUDE.md, README.md	verification.md adds a "Tx-ID routing" section documenting the tx_id= keyword form and the risk of the legacy _tx_id mutation. CLAUDE.md updates the "Signature Confirmed" step with soft-fail semantics for malformed envelopes and adds "Kernel discipline" and "Verify-status gate" convention bullets and further-reading links. README.md install line is updated to include the ar-io-proof kernel dependency.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

• ar-io/ar-io-mlflow#20: Implemented the ar-io-proof kernel migration and VerifiedModel runtime verify-status gate (including recheck_per_predict and phase logging) that this PR documents.
• ar-io/ar-io-mlflow#21: Changed _verify_envelope_for_tx to pass tx_id=tx_id as a keyword rather than mutating the envelope, which is exactly the migration this PR warns callers about in docs/verification.md.

Poem

🐇 Hop through the docs, the kernel is clear,
ar-io-proof holds the crypto frontier!
The gate stands guard at load and predict,
with fail_open warnings neatly depicted.
No _tx_id mutations — use keywords instead,
this bunny writes docs so no one is misled! ✍️

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The pull request title clearly summarizes the main changes: documentation updates for kernel migration and verify-status gate integration with four public integration points.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch doc-sweep-0.3.0

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}