matrixscroll 0.6.1__tar.gz → 0.6.3__tar.gz

{matrixscroll-0.6.1 → matrixscroll-0.6.3}/.gitignore

@@ -32,9 +32,36 @@ env/
 *.swp
 .DS_Store
 
+# Secrets and credentials (never commit)
+.env
+.env.*
+!.env.example
+*.pem
+*.key
+credentials.json
+credentials/
+
+# Editor / agent local state
+.cursor/
+.playwright-cli/
+
 # Matrix Scroll local store (never commit a private key)
 .matrixscroll/
 device.json
 
 # TLA+ tools (download locally or in CI)
 tla2tools.jar
+
+# TLC run artifacts
+formal/tla/states/
+formal/tla/*_TTrace_*.tla
+formal/tla/*_TTrace_*.bin
+
+# MkDocs build output
+site/
+
+# Vale packages fetched by `vale sync`; do not commit
+.vale/styles/Google/
+.vale/styles/write-good/
+.vale/styles/ai-tells/
+.vale/styles/ai-tells-commits/

{matrixscroll-0.6.1 → matrixscroll-0.6.3}/CHANGELOG.md

@@ -4,6 +4,73 @@ All notable changes to the Matrix Scroll Python SDK are documented here. The
 format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and
 this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [0.6.3] - 2026-08-10
+
+Repository layout and documentation. No code, CLI or wire-format changes.
+
+### Added
+- **The Matrix Scroll Verify action now lives in this repo** at
+  [`.github/actions/verify`](.github/actions/verify), and the reusable MCP
+  manifest gate at `.github/workflows/mcp-manifest-gate.yml`. Both were
+  published from the separate `SSX360/matrixscroll-verify-action` repository,
+  which is now archived. Inputs, outputs and exit codes are unchanged.
+
+### Changed
+- **Call sites move to the new reference.** Replace
+  `SSX360/matrixscroll-verify-action@v1` with
+  `SSX360/matrixscroll/.github/actions/verify@action-v1`, and
+  `SSX360/matrixscroll-verify-action/.github/workflows/mcp-manifest-gate.yml@main`
+  with `SSX360/matrixscroll/.github/workflows/mcp-manifest-gate.yml@action-v1`.
+  The `action-v1` tag tracks the current action release line and is separate
+  from the SDK's `v0.6.x` tags.
+- The reusable MCP gate now defaults `matrixscroll_version` to `0.6.3`, matching
+  the action default and the published PyPI release. It runs on `workflow_call`
+  and `workflow_dispatch` only, so it does not add a job to every SDK pull
+  request.
+
+### Fixed
+- **PyPI dropped every relative link in the README.** Its sanitiser removes any
+  `href` it cannot resolve, so 17 documentation links arrived on the project
+  page as plain text and the MCP rug-pull demo GIF arrived as its alt text,
+  leaving that section without its only visual. All of them are absolute
+  `github.com` and `raw.githubusercontent.com` URLs now.
+- **Three README links promised a tamper demo at a page that redirects.**
+  `matrixscroll.com/try` routes to `/docs/`. The demo is the browser verifier
+  at `/verify/`, which carries the Tamper sample control, so the inline links
+  point there. The `Try it` entry under Public proof links repeated the
+  verifier line above it and is now the MCP Trust Scanner at `/scan/`.
+- **`SECURITY.md` offered support for 0.2.x and 0.1.x.** A reader installing
+  the published release found their version missing from the table on the page
+  the PyPI sidebar links as the security policy.
+
+## [0.6.2] - 2026-08-03
+
+Documentation and packaging metadata only. No code, CLI or wire-format changes,
+and no new dependencies.
+
+### Fixed
+- **Packaging URLs pointed at pages that had moved or gone.** `Documentation` and
+  `Verifier` routed through `ssx360.com` redirects that land on
+  `matrixscroll.com`, `Reference Device` pointed at a culled `/hardware` page,
+  and `Compare` duplicated `Documentation`. Every link now resolves directly, and
+  `Homepage` is the protocol site rather than the maintainer's.
+- **The README described a hosted control plane with billing.** SSX360 is an
+  independent audit practice that sells assessments, not a platform, so the
+  README now says who maintains the protocol and why that separation exists. The
+  links to the retired `/enterprise`, `/signup` and `/compare` pages are gone.
+
+### Documentation
+- **State the post-quantum limit where people actually read it.** The summary and
+  keywords claim FIPS 204 and FIPS 205, but nothing on the PyPI page said the
+  overlay is an algorithm implementation through liboqs rather than a
+  CMVP-validated module, or repeated liboqs's own warning against production use.
+  Honest limits now carries both.
+- Summary rewritten to lead with what the protocol does rather than the hardware
+  signing path, which is a bench prototype and not a product.
+- Install pin `matrixscroll==0.6.2`.
+
 ## [0.6.1] - 2026-07-22
 
 ### Documentation
@@ -245,6 +312,8 @@ Initial public release. Extracted from the SSX360 reference implementation.
 - Device id format: `MS-XXXX-XXXX` (SHA-256 of the raw public key, first 8 hex
   chars, uppercase).
 
+[0.6.3]: https://github.com/SSX360/matrixscroll/releases/tag/v0.6.3
+[0.6.2]: https://github.com/SSX360/matrixscroll/releases/tag/v0.6.2
 [0.6.1]: https://github.com/SSX360/matrixscroll/releases/tag/v0.6.1
 [0.6.0]: https://github.com/SSX360/matrixscroll/releases/tag/v0.6.0
 [0.5.1]: https://github.com/SSX360/matrixscroll/releases/tag/v0.5.1

{matrixscroll-0.6.1 → matrixscroll-0.6.3}/CONTRIBUTING.md

@@ -35,13 +35,27 @@ For PRs that include agent-assisted commits, publish signed commit envelopes to
 
 ```bash
 matrixscroll hook-install
-export MATRIXSCROLL_ACTOR_TYPE=agent   # or human / ci as appropriate
-export MATRIXSCROLL_TOOL=agent-runner  # or your editor / agent tool name
 git commit -m "feat: your change"
 matrixscroll envelope-publish-notes --base origin/main --head HEAD
 git push origin refs/notes/matrixscroll
 ```
 
+`actor_type` and `tool` are detected from the environment. A commit made in a
+Cursor, Claude Code, Aider, Codex, or Devin session is recorded as `agent` with
+that tool; a commit made by a CI runner is recorded as `ci`. Everything else is
+`human` and `git-cli`.
+
+Set `MATRIXSCROLL_ACTOR_TYPE` and `MATRIXSCROLL_TOOL` only when the detection
+list does not cover your agent runner, and only to describe what actually made
+the commit. Never set `MATRIXSCROLL_ACTOR_TYPE=human` inside an agent session.
+The envelope exists to record who wrote a change. A signed envelope carrying the
+wrong actor is the exact falsification this project detects.
+
+Detection and its limits are covered in
+[`docs/explanation/actor-attribution.md`](docs/explanation/actor-attribution.md),
+which also explains why envelopes already published with the wrong actor are
+left in place.
+
 CI verifies the PR range with `matrixscroll envelope-verify-range --source notes`.
 Until repository variable `ENFORCE_PROVENANCE=true` is set, missing notes produce a **warning**
 in the GitHub Step Summary rather than a hard failure.

{matrixscroll-0.6.1 → matrixscroll-0.6.3}/PKG-INFO

@@ -1,24 +1,23 @@
 Metadata-Version: 2.4
 Name: matrixscroll
-Version: 0.6.1
-Summary: Signed provenance for agent-assisted Git commits with offline Ed25519 verification; optional ML-DSA/SLH-DSA software overlay (FIPS 204/205). USB/NFC/SE050 hardware remains Ed25519.
-Project-URL: Homepage, https://ssx360.com
-Project-URL: Documentation, https://ssx360.com/docs
+Version: 0.6.3
+Summary: Sign who authorized an AI agent's actions and verify it offline. Ed25519 envelopes for Git commits and MCP tool surfaces, with an optional ML-DSA/SLH-DSA overlay (FIPS 204/205).
+Project-URL: Homepage, https://matrixscroll.com
+Project-URL: Documentation, https://matrixscroll.com/docs/
+Project-URL: Specification, https://matrixscroll.com/spec/
+Project-URL: Verifier, https://matrixscroll.com/verify/
 Project-URL: Repository, https://github.com/SSX360/matrixscroll
 Project-URL: Source, https://github.com/SSX360/matrixscroll
 Project-URL: Issues, https://github.com/SSX360/matrixscroll/issues
-Project-URL: Specification, https://github.com/SSX360/matrixscroll/blob/main/SPEC.md
 Project-URL: Whitepaper, https://github.com/SSX360/matrixscroll/blob/main/docs/WHITEPAPER.md
-Project-URL: Verifier, https://ssx360.com/verify
-Project-URL: Compare, https://ssx360.com/docs
 Project-URL: Changelog, https://github.com/SSX360/matrixscroll/blob/main/CHANGELOG.md
 Project-URL: Discussions, https://github.com/SSX360/matrixscroll/discussions
 Project-URL: Security, https://github.com/SSX360/matrixscroll/blob/main/SECURITY.md
-Project-URL: GitHub Action, https://github.com/SSX360/matrixscroll-verify-action
-Project-URL: PyPI Provenance, https://pypi.org/project/matrixscroll/0.6.1/
-Project-URL: Reference Device, https://ssx360.com/hardware
+Project-URL: GitHub Action, https://github.com/SSX360/matrixscroll/tree/main/.github/actions/verify
 Project-URL: Tests, https://github.com/SSX360/matrixscroll/tree/main/tests
 Project-URL: Public Roadmap, https://github.com/SSX360/matrixscroll/blob/main/docs/ROADMAP_2026-07.md
+Project-URL: Hardware Status, https://github.com/SSX360/matrixscroll/blob/main/docs/hardware-provider.md
+Project-URL: Maintainer, https://ssx360.com/about
 Author-email: SSX360 <security@matrixscroll.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -58,47 +57,50 @@ Description-Content-Type: text/markdown
 
 # Matrix Scroll
 
-**Try it:** [matrixscroll.com/try](https://matrixscroll.com/try) — offline tamper demo and ten-line quickstart.
-
-**Codebase direction:** [`docs/DOCTRINE.md`](docs/DOCTRINE.md)
+Signed provenance for agent-assisted Git commits, with offline Ed25519 verification.
 
 [![ci-unit](https://github.com/SSX360/matrixscroll/actions/workflows/ci-unit.yml/badge.svg)](https://github.com/SSX360/matrixscroll/actions/workflows/ci-unit.yml)
-[![Scroll Gate v2 (hosted)](https://github.com/SSX360/matrixscroll/actions/workflows/provenance-gate.yml/badge.svg)](https://github.com/SSX360/matrixscroll/actions/workflows/provenance-gate.yml)
-[![codecov](https://codecov.io/gh/SSX360/matrixscroll/graph/badge.svg)](https://codecov.io/gh/SSX360/matrixscroll)
+[![PyPI](https://img.shields.io/pypi/v/matrixscroll)](https://pypi.org/project/matrixscroll/)
+[![Python](https://img.shields.io/pypi/pyversions/matrixscroll)](https://pypi.org/project/matrixscroll/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](https://github.com/SSX360/matrixscroll/blob/main/LICENSE)
 
-**146 tests** · Hypothesis-verified security properties · [Security properties](https://github.com/SSX360/matrixscroll/blob/main/docs/SECURITY_PROPERTIES.md) · [TLA+ formal models](formal/README.md)
+Matrix Scroll is an open protocol for cryptographically signed agent
+authorization: Ed25519 records for Git commits (L1), MCP tool surfaces (L2), and
+agent runs and non-human-identity actions (L3), verified offline in the CLI, the
+browser, and CI. It is free, permanently, and is not monetized.
 
-**Agent Authorization Authority — offline-verifiable proof for every machine action.** Matrix Scroll is an
-**open protocol for cryptographically signed agent authorization** — Ed25519 records for Git commits (L1),
-MCP tool surfaces (L2), and agent runs / NHI actions (L3), verified offline in CLI, browser, and CI.
-Software emulated keys ship today; NXP SE050 secure-element signing is a
-bench-validated PoC (Jul 2026) with the same verifier contract. The Pico 2 W /
-GMT130 display bring-up is a locked L2 Hardware prototype (Jul 2026) — not GA.
+Software emulated keys ship today. NXP SE050 secure-element signing is a
+bench-validated proof of concept (Jul 2026) sharing the same verifier contract,
+and the Pico 2 W / GMT130 display bring-up is a locked L2 Hardware prototype
+(Jul 2026). Neither is generally available.
 
-*They receipt the model call. We receipt everything the machine does.*
+**Try it:** [matrixscroll.com/verify](https://matrixscroll.com/verify/) runs an offline
+tamper demo in the browser. **Codebase direction:** [`docs/DOCTRINE.md`](https://github.com/SSX360/matrixscroll/blob/main/docs/DOCTRINE.md).
+**146 tests**, Hypothesis-verified [security properties](https://github.com/SSX360/matrixscroll/blob/main/docs/SECURITY_PROPERTIES.md),
+and [TLA+ formal models](https://github.com/SSX360/matrixscroll/blob/main/formal/README.md).
 
-**Authorization ladder:** L1 Code (commits) · L2 Tools (MCP manifests) · L3 Actions (agent runs) · L4 Money (AP2 — demo) · L5 Silicon (2029+)
+**Authorization ladder:** L1 Code (commits), L2 Tools (MCP manifests), L3 Actions (agent runs), L4 Money (AP2, demo), L5 Silicon (2029+)
 
-**Hosted control plane:** identity, billing, authorization ledger, and Scroll Gate live at
-[ssx360.com](https://ssx360.com/). Enterprise teams evaluating protected-branch enforcement should
-[book a provenance pilot](https://ssx360.com/contact?intent=pilot) or visit
-[ssx360.com/enterprise](https://ssx360.com/enterprise).
-Provisioned pilot and team accounts sign in at [ssx360.com/signup](https://ssx360.com/signup).
+**Who maintains it:** [SSX360](https://ssx360.com/about), an independent audit
+practice for agent authorization. It sells assessments and never sells this
+protocol, because gating the protocol would remove the reason anyone trusts the
+audit built beside it. Teams that want an independent assessment of their own
+mandate chain can [request a call](https://ssx360.com/contact).
 
 ## Compliance evidence mapping
 
 Matrix Scroll **maps to** and **produces evidence for** (never “required by”; not a certification claim):
 
-- **DORA (Jan 2025)** — ICT change-management evidence for software changes.
-- **PCI DSS 4.0 Req 6.5 (Mar 2025)** — change-control evidence for custom software.
-- **US Treasury FS-AI RMF (Feb 2026)** — traceability for agent actions in financial software.
-- **NIST SSDF** — provenance, change authorization, and release gate review.
-- **EU AI Act Article 12** — record-keeping readiness (high-risk obligations Dec 2027), not a live mandate claim.
-- **Five Eyes Agentic AI guidance (Apr 2026)** — linked crosswalk only: [`controls/agentic_ai_controls.json`](controls/agentic_ai_controls.json)
+- **DORA (Jan 2025)**: ICT change-management evidence for software changes.
+- **PCI DSS 4.0 Req 6.5 (Mar 2025)**: change-control evidence for custom software.
+- **US Treasury FS-AI RMF (Feb 2026)**: traceability for agent actions in financial software.
+- **NIST SSDF**: provenance, change authorization, and release gate review.
+- **EU AI Act Article 12**: record-keeping readiness (high-risk obligations Dec 2027), not a live mandate claim.
+- **Five Eyes Agentic AI guidance (Apr 2026)**: linked crosswalk only: [`controls/agentic_ai_controls.json`](https://github.com/SSX360/matrixscroll/blob/main/controls/agentic_ai_controls.json)
 
-POC 2 audit readiness: [`docs/POC2_AUDIT.md`](docs/POC2_AUDIT.md)
+POC 2 audit readiness: [`docs/POC2_AUDIT.md`](https://github.com/SSX360/matrixscroll/blob/main/docs/POC2_AUDIT.md)
 
-## Install — MCP server (headline path)
+## Install the MCP server (headline path)
 
 Agents sign commits in-loop via the **provenance-only** MCP server:
 
@@ -114,29 +116,29 @@ Agents sign commits in-loop via the **provenance-only** MCP server:
 ```
 
 ```bash
-pip install "matrixscroll[mcp]==0.6.1"
-matrixscroll-mcp   # stdio — register in Cursor / Claude Desktop / VS Code
+pip install "matrixscroll[mcp]==0.6.3"
+matrixscroll-mcp   # stdio. Register in Cursor / Claude Desktop / VS Code
 ```
 
 **MCP tools (provenance verbs only):** `create_envelope`, `sign_action`, `verify_envelope`,
 `verify_pr_range` (Scroll Gate), `publish_notes`, `status`, `audit_export`, `list_envelopes`,
-`connect_card` (SE050 hardware prototype — pilot evaluation; not GA).
+`connect_card` (SE050 hardware prototype, pilot evaluation, not GA).
 
 **MCP trust tools (manifest surface):** `scan_mcp_server`, `sign_mcp_manifest`, `verify_mcp_manifest`.
 
-### MCP Trust Scanner — catch a rug-pull in 60 seconds
+### MCP Trust Scanner: catch a rug-pull in 60 seconds
 
-![MCP rug-pull detection demo](examples/demo/mcp-rugpull-demo.gif)
+![MCP rug-pull detection demo](https://raw.githubusercontent.com/SSX360/matrixscroll/main/examples/demo/mcp-rugpull-demo.gif)
 
-[Watch on asciinema](https://asciinema.org/a/rbCRkIcZnjNWmqZF) · cast file: [`examples/demo/mcp-rugpull-demo.cast`](examples/demo/mcp-rugpull-demo.cast)
+[Watch on asciinema](https://asciinema.org/a/rbCRkIcZnjNWmqZF) · cast file: [`examples/demo/mcp-rugpull-demo.cast`](https://github.com/SSX360/matrixscroll/blob/main/examples/demo/mcp-rugpull-demo.cast)
 
-Sign the tool surface. Verify at install. Offline Ed25519 manifests for MCP rug-pull detection —
-zero cloud, zero signup, exit code 2 fails your CI.
+Sign the tool surface. Verify at install. Offline Ed25519 manifests for MCP rug-pull detection.
+Zero cloud, zero signup, exit code 2 fails your CI.
 
 ```bash
-pip install "matrixscroll==0.6.1"
+pip install "matrixscroll==0.6.3"
 
-# 1. Scan a live MCP server (stdio) — fingerprints every tool: name, description, input schema
+# 1. Scan a live MCP server (stdio). Fingerprints every tool: name, description, input schema
 matrixscroll mcp scan --connect stdio --server-command "npx -y some-mcp-server" \
   -o manifest.json --pretty
 
@@ -160,31 +162,30 @@ A mutated tool description or input schema fails loudly:
 FAIL  surface_drift — do not trust this server until you review the diff
 ```
 
-Offline mode works too — no server needed: `matrixscroll mcp scan --tools ./tools.json`
+Offline mode works too, no server needed: `matrixscroll mcp scan --tools ./tools.json`
 accepts a plain JSON tool array or `{"tools": [...]}` (paste from any `tools/list` response).
 
-Gate it in CI — fail the build on unsigned or drifted manifests with the reusable workflow:
+Gate it in CI. Fail the build on unsigned or drifted manifests with the reusable workflow:
 
 ```yaml
 jobs:
   mcp-gate:
-    uses: SSX360/matrixscroll-verify-action/.github/workflows/mcp-manifest-gate.yml@main
+    uses: SSX360/matrixscroll/.github/workflows/mcp-manifest-gate.yml@action-v1
     with:
       manifest: mcp/my-server.signed.json
       baseline: mcp/my-server.baseline.json
-      matrixscroll_version: "0.6.1"
+      matrixscroll_version: "0.6.3"
 ```
 
-Full scripted demo: [`examples/demo/mcp-rugpull-demo.sh`](examples/demo/mcp-rugpull-demo.sh)  
-Golden artifact (this repo's own MCP server, signed): [`examples/mcp/matrixscroll-mcp.signed.json`](examples/mcp/matrixscroll-mcp.signed.json)  
-Schema (CC0): [`schemas/ssx360.mcp-manifest.v1.json`](schemas/ssx360.mcp-manifest.v1.json)  
-Browser demo: [matrixscroll.com/scan](https://matrixscroll.com/scan)  
-Launch checklist: [`docs/SHOW-HN-MCP-TRUST-LAUNCH.md`](docs/SHOW-HN-MCP-TRUST-LAUNCH.md)
+Full scripted demo: [`examples/demo/mcp-rugpull-demo.sh`](https://github.com/SSX360/matrixscroll/blob/main/examples/demo/mcp-rugpull-demo.sh)  
+Golden artifact (this repo's own MCP server, signed): [`examples/mcp/matrixscroll-mcp.signed.json`](https://github.com/SSX360/matrixscroll/blob/main/examples/mcp/matrixscroll-mcp.signed.json)  
+Schema (CC0): [`schemas/ssx360.mcp-manifest.v1.json`](https://github.com/SSX360/matrixscroll/blob/main/schemas/ssx360.mcp-manifest.v1.json)  
+Browser demo: [matrixscroll.com/scan](https://matrixscroll.com/scan/)
 
-## Also available — CLI & hooks
+## Also available: CLI and hooks
 
 ```bash
-pip install "matrixscroll==0.6.1"
+pip install "matrixscroll==0.6.3"
 matrixscroll hook-install
 export MATRIXSCROLL_ACTOR_TYPE=agent
 export MATRIXSCROLL_TOOL=agent-runner
@@ -205,7 +206,7 @@ matrixscroll sign-action --type ci_step \
 
 Action schema: [`schemas/action-envelope.v1.json`](https://github.com/SSX360/matrixscroll/blob/main/schemas/action-envelope.v1.json)
 
-### SSX360 Scroll — Git wrapper (Layer 3, Phase 1)
+### SSX360 Scroll: Git wrapper (Layer 3, Phase 1)
 
 Git under the hood; governance on top. **Not a Git replacement.**
 
@@ -213,10 +214,10 @@ Git under the hood; governance on top. **Not a Git replacement.**
 matrixscroll scroll commit -m "feat: governed commit"
 ```
 
-See [`docs/commercial/SSX360_SCROLL.md`](docs/commercial/SSX360_SCROLL.md).
+See [`docs/commercial/SSX360_SCROLL.md`](https://github.com/SSX360/matrixscroll/blob/main/docs/commercial/SSX360_SCROLL.md).
 
-See [`docs/quickstart-git.md`](docs/quickstart-git.md) and
-[`examples/demo/agent-commit-demo.sh`](examples/demo/agent-commit-demo.sh).
+See [`docs/quickstart-git.md`](https://github.com/SSX360/matrixscroll/blob/main/docs/quickstart-git.md) and
+[`examples/demo/agent-commit-demo.sh`](https://github.com/SSX360/matrixscroll/blob/main/examples/demo/agent-commit-demo.sh).
 
 ---
 
@@ -250,16 +251,23 @@ canonical UTF-8 JSON bytes (see [`SPEC.md`](https://github.com/SSX360/matrixscro
 
 ## Honest limits
 
-- Shipping now: PyPI `matrixscroll==0.6.1`, Git post-commit hooks,
+- Shipping now: PyPI `matrixscroll==0.6.3`, Git post-commit hooks,
   `matrixscroll sign-action`, `matrixscroll scroll commit` (thin wrapper),
   `matrixscroll envelope-verify`, Scroll Gate PR verification (partial SLSA L1–2),
   verifier, the GitHub Action, and a USB CDC host transport for the SE050
   hardware prototype path. Emulated mode is the default evaluation path.
 - Prototype (bench): Pico 2 W / RP2350 + GMT130 ST7789 LCD/LED bring-up locked
   (2026-07-21); NXP SE050 M1 signing PoC accepted (Jul 2026) on contractor
-  firmware — not GA; display bring-up UF2 keeps `pubkey`/`sign` fail-closed
+  firmware, not GA; display bring-up UF2 keeps `pubkey`/`sign` fail-closed
   until Plug & Trust restore. External Ed25519-capable hardware key backends
   and transparency-log integrations remain roadmap.
+- The post-quantum overlay implements the ML-DSA and SLH-DSA algorithms specified
+  in FIPS 204 and FIPS 205, through liboqs. That is an algorithm implementation,
+  not a CMVP-validated cryptographic module, and it is never described as FIPS
+  validated, certified or compliant. liboqs itself states that it should not be
+  relied on in production or to protect sensitive data, which is a limit worth
+  repeating rather than burying. The overlay is attached alongside the Ed25519
+  signature and never replaces it.
 - Compliance language is evidence mapping (DORA, PCI DSS 4.0, Treasury FS-AI RMF, SSDF, EU AI Act Article 12 readiness, Five Eyes agentic-AI guidance), not certification or customer endorsement.
 - Illustrative deployment profiles are not endorsements or existing customer relationships.
 - Not: IAM, sandboxing, prompt filtering, or an agent runtime.
@@ -271,7 +279,7 @@ canonical UTF-8 JSON bytes (see [`SPEC.md`](https://github.com/SSX360/matrixscro
 - Hardware keys and build attestations remain complementary roots and downstream
   proofs; Matrix Scroll covers commit-time provenance.
 - The public contract stays pure Ed25519 over canonical manifest bytes for the
-  required `signature` block — whether the signer is emulated today or
+  required `signature` block, whether the signer is emulated today or
   SE050 secure-element signing later. Software signers may optionally attach ML-DSA/SLH-DSA
   overlays (FIPS 204/205) via `matrixscroll[pqc]` without changing hardware firmware.
 
@@ -291,20 +299,21 @@ permissions so teams can evaluate the full workflow now. Hardware mode keeps
 the same verifier contract and commit envelope schema, but moves the private
 key into the SE050 secure element so the host cannot export it. That path is
 a bench-validated L2 Hardware prototype (Pico 2 W + SE050 M1 PoC) available
-for pilot evaluation — not GA.
+for pilot evaluation, not GA.
 
 ### How can I integrate Matrix Scroll into a CI/CD workflow?
 
 Install the SDK and hooks in your repo, publish commit envelopes to
 `refs/notes/matrixscroll` before PR review, and use
-`SSX360/matrixscroll-verify-action@v1` to verify the full PR commit range in
-GitHub Actions. Protected branches can then require Matrix Scroll proof
+`SSX360/matrixscroll/.github/actions/verify@action-v1` to verify the full PR
+commit range in GitHub Actions. Protected branches can then require Matrix
+Scroll proof
 alongside your existing scanners, branch protection, and build attestations.
 
 ## Quickstart (CLI)
 
 ```bash
-pip install "matrixscroll==0.6.1"
+pip install "matrixscroll==0.6.3"
 matrixscroll hook-install
 matrixscroll hook-status
 
@@ -315,10 +324,10 @@ git commit -m "feat: agent-assisted change"
 matrixscroll envelope-verify "$(git rev-parse HEAD)"
 ```
 
-**Try it in the browser:** [matrixscroll.com/try](https://matrixscroll.com/try)
+**Try it in the browser:** [matrixscroll.com/verify](https://matrixscroll.com/verify/)
 
-See [`docs/quickstart-git.md`](docs/quickstart-git.md) and run
-[`examples/demo/agent-commit-demo.sh`](examples/demo/agent-commit-demo.sh).
+See [`docs/quickstart-git.md`](https://github.com/SSX360/matrixscroll/blob/main/docs/quickstart-git.md) and run
+[`examples/demo/agent-commit-demo.sh`](https://github.com/SSX360/matrixscroll/blob/main/examples/demo/agent-commit-demo.sh).
 
 ## CI verify
 
@@ -328,12 +337,12 @@ See [`docs/quickstart-git.md`](docs/quickstart-git.md) and run
 - uses: actions/checkout@v4
   with:
     fetch-depth: 0
-- uses: SSX360/matrixscroll-verify-action@v1
+- uses: SSX360/matrixscroll/.github/actions/verify@action-v1
   with:
     head-ref: ${{ github.event.pull_request.head.sha }}
     base-ref: ${{ github.event.pull_request.base.sha }}
     source: notes
-    matrixscroll-version: "0.6.1"
+    matrixscroll-version: "0.6.3"
     require-mode: emulated
 ```
 
@@ -348,28 +357,28 @@ git push origin refs/notes/matrixscroll
 - uses: actions/checkout@v4
   with:
     fetch-depth: 0
-- uses: SSX360/matrixscroll-verify-action@v1
+- uses: SSX360/matrixscroll/.github/actions/verify@action-v1
   with:
     head-ref: ${{ github.event.pull_request.head.sha }}
     base-ref: ${{ github.event.pull_request.base.sha }}
     source: notes
-    matrixscroll-version: "0.6.1"
+    matrixscroll-version: "0.6.3"
     summary-output: provenance-summary.json
 ```
 
-See [`docs/quickstart-git.md`](docs/quickstart-git.md) and
-[`examples/ci/protected-branch.yml`](examples/ci/protected-branch.yml).
+See [`docs/quickstart-git.md`](https://github.com/SSX360/matrixscroll/blob/main/docs/quickstart-git.md) and
+[`examples/ci/protected-branch.yml`](https://github.com/SSX360/matrixscroll/blob/main/examples/ci/protected-branch.yml).
 
 The `--require-mode`, `--trusted-keys`, and actor or delegation policy checks
-ship in the current release line; examples in this README pin `0.6.1`.
+ship in the current release line; examples in this README pin `0.6.3`.
 
 ## Security: Ed25519 via cryptography
 
 Ed25519 signing, verification, and key generation use the [`cryptography`](https://pypi.org/project/cryptography/)
 package (required dependency, `>=42.0`). Official wheels ship native crypto
-backends (OpenSSL + Rust components) — no Rust toolchain for users. All
+backends (OpenSSL + Rust components), so no Rust toolchain for users. All
 primitives are centralized in `matrixscroll/crypto_backend.py`; see
-[`docs/CRYPTO_BACKEND.md`](docs/CRYPTO_BACKEND.md).
+[`docs/CRYPTO_BACKEND.md`](https://github.com/SSX360/matrixscroll/blob/main/docs/CRYPTO_BACKEND.md).
 
 ## Why it is different from Sigstore
 
@@ -384,23 +393,23 @@ when they preserve the same pure Ed25519 byte contract.
 
 ## Public proof links
 
-- Browser verifier: <https://matrixscroll.com/verify>
-- Try it (quickstart + tamper demo): <https://matrixscroll.com/try>
-- Compare page: <https://matrixscroll.com/compare>
-- Documentation: <https://matrixscroll.com/docs>
+- Browser verifier: <https://matrixscroll.com/verify/>
+- MCP Trust Scanner (browser, offline): <https://matrixscroll.com/scan/>
+- Documentation: <https://matrixscroll.com/docs/>
 - Specification: [`SPEC.md`](https://github.com/SSX360/matrixscroll/blob/main/SPEC.md)
 - Commit envelope schema: [`schemas/commit-envelope.v1.json`](https://github.com/SSX360/matrixscroll/blob/main/schemas/commit-envelope.v1.json)
-- Whitepaper: [`docs/WHITEPAPER.md`](docs/WHITEPAPER.md)
+- Whitepaper: [`docs/WHITEPAPER.md`](https://github.com/SSX360/matrixscroll/blob/main/docs/WHITEPAPER.md)
 - Conformance vectors: [`vectors/`](https://github.com/SSX360/matrixscroll/tree/main/vectors/)
-- GitHub Action: <https://github.com/SSX360/matrixscroll-verify-action>
+- GitHub Action: <https://github.com/SSX360/matrixscroll/tree/main/.github/actions/verify>
 - Agentic AI controls: [`docs/AGENTIC_AI_SECURITY.md`](https://github.com/SSX360/matrixscroll/blob/main/docs/AGENTIC_AI_SECURITY.md)
-- Site: <https://matrixscroll.com> · Control plane: <https://ssx360.com> · Enterprise: <https://ssx360.com/enterprise>
-- SE050 hardware prototype: <https://ssx360.com/enterprise#roadmap> (bench-validated; not GA)
+- Site: <https://matrixscroll.com> · Browser verifier: <https://matrixscroll.com/verify/>
+- Hardware prototype status: [`docs/hardware-provider.md`](https://github.com/SSX360/matrixscroll/blob/main/docs/hardware-provider.md) (bench-validated; not GA)
+- Maintainer, and how independence is kept: <https://ssx360.com/about>
 
 ## Python API
 
 ```bash
-pip install "matrixscroll==0.6.1"
+pip install "matrixscroll==0.6.3"
 ```
 
 ```python
@@ -450,7 +459,7 @@ matrixscroll.sign_manifest(...)  /  post-commit hook
          v
 IdentityProvider          -->  Ed25519 signature
 (L1 emulated today,
- SSX360 / SE050 prototype — bench-validated)
+ SSX360 / SE050 prototype, bench-validated)
          |
          v
 signed document  -->  matrixscroll.verify_manifest(...)
@@ -467,7 +476,7 @@ canonical bytes with Ed25519.
 For rollout order, start with `MATRIXSCROLL_MODE=emulated` for evaluation,
 layer in external Ed25519-capable signers only when they stay verifier
 compatible, and treat `hardware` as the SE050 prototype path for pilot
-evaluation — not GA.
+evaluation, not GA.
 
 ## Compliance levels
 
@@ -499,9 +508,9 @@ implementations in Rust, Go, TypeScript, and embedded C. Run them against
 ## Agentic AI guidance proof
 
 The repo includes a machine-readable control matrix at
-[`controls/agentic_ai_controls.json`](controls/agentic_ai_controls.json), an
+[`controls/agentic_ai_controls.json`](https://github.com/SSX360/matrixscroll/blob/main/controls/agentic_ai_controls.json), an
 example bounded-agent evidence manifest at
-[`examples/agentic_ai_evidence_manifest.json`](examples/agentic_ai_evidence_manifest.json),
+[`examples/agentic_ai_evidence_manifest.json`](https://github.com/SSX360/matrixscroll/blob/main/examples/agentic_ai_evidence_manifest.json),
 and executable checks in `tests/test_agentic_guidance.py`.
 
 ## Model Context Protocol (MCP) Server
@@ -513,11 +522,11 @@ The MCP server exposes **provenance verbs** (`create_envelope`, `verify_envelope
 Install and register in Cursor / Claude Desktop / VS Code:
 
 ```bash
-pip install "matrixscroll[mcp]==0.6.1"
+pip install "matrixscroll[mcp]==0.6.3"
 matrixscroll-mcp   # stdio
 ```
 
-See the [Install — MCP server](#install--mcp-server-headline-path) section above for
+See the [Install the MCP server](#install-the-mcp-server-headline-path) section above for
 the recommended `mcp.json` snippet.
 
 ## License
@@ -525,13 +534,46 @@ the recommended `mcp.json` snippet.
 - Code: **Apache-2.0** (`LICENSE`).
 - Specification text (`SPEC.md`, `vectors/`): **CC0 1.0** - public domain.
 
+## Verify this release
+
+Every release is published from GitHub Actions through PyPI Trusted Publishing,
+and every file carries a PEP 740 attestation recorded in the Sigstore
+transparency log. You do not have to take our word for who built the wheel; you
+can check it.
+
+Ask PyPI directly:
+
+```bash
+curl -H "Accept: application/vnd.pypi.integrity.v1+json" \
+  https://pypi.org/integrity/matrixscroll/0.6.3/matrixscroll-0.6.3-py3-none-any.whl/provenance
+```
+
+The response names the publisher, and it should say exactly this:
+
+```json
+{"kind": "GitHub", "repository": "SSX360/matrixscroll",
+ "workflow": "publish.yml", "environment": "pypi"}
+```
+
+Transparency-log entry for the 0.6.2 wheel: log index `2215985472`. If the
+publisher, the workflow, or the digest differs from what you expect, do not
+install the file.
+
+The human-readable view is on the
+[PyPI project page](https://pypi.org/project/matrixscroll/0.6.3/), where files
+built with attestations are marked as verified.
+
+This matters more here than for most packages. A tool that sells offline
+verifiability should be verifiable by the same standard it asks of everyone
+else.
+
 ## Security
 
-See [`SECURITY.md`](SECURITY.md) and [`docs/SECURITY_PROPERTIES.md`](https://github.com/SSX360/matrixscroll/blob/main/docs/SECURITY_PROPERTIES.md).
+See [`SECURITY.md`](https://github.com/SSX360/matrixscroll/blob/main/SECURITY.md) and [`docs/SECURITY_PROPERTIES.md`](https://github.com/SSX360/matrixscroll/blob/main/docs/SECURITY_PROPERTIES.md).
 Report vulnerabilities privately to
 **security@matrixscroll.com** or via a GitHub Security Advisory.
 
 ---
 
-**Protocol:** https://ssx360.com/docs · **Verify:** https://ssx360.com/verify  
-**Control plane:** https://ssx360.com · **Pilot:** mission@ssx360.com · **Sign in:** https://ssx360.com/signup
+**Docs:** https://matrixscroll.com/docs/ · **Spec:** https://matrixscroll.com/spec/ · **Verify:** https://matrixscroll.com/verify/  
+**Maintainer:** https://ssx360.com/about · **Contact:** mission@ssx360.com