matrixscroll 0.2.5__tar.gz → 0.2.6__tar.gz

{matrixscroll-0.2.5 → matrixscroll-0.2.6}/CHANGELOG.md

@@ -4,9 +4,30 @@ 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).
 
-## [0.2.5] - 2026-06-24
+## [0.2.6] - 2026-06-21
 
-Post-HN patch: GitHub gpgsig commit binding, SE050 mock transport, YubiKey pubkey export, Rekor/GUAC CLI MVP.
+SDK rollout hardening: generic public attribution, SE050 host transport preview,
+and repo-local hardware rollout docs.
+
+### Added
+- **USB CDC host transport preview** - `SerialSE050Transport` for newline-delimited
+  JSON `ping` / `pubkey` / `sign` framing over the RP2350 USB bridge.
+- **Hardware extra** - `pip install "matrixscroll[hardware]"` now pulls in
+  `pyserial` for the SE050 host path.
+- **Rollout docs** - adopter kit, five-minute guide, hardware provider quickstart,
+  SE050 protocol reference, and contractor-facing PoC scope kept inside the SDK repo.
+
+### Changed
+- **Public quickstarts** - replaced editor-specific public quickstarts with
+  generic agent-facing guidance while keeping the manifest schema and API unchanged.
+- **Hardware messaging** - clarified that the SDK now ships a host transport
+  preview and mock path, while real device signing still depends on firmware PoC validation.
+- **Release copy** - aligned README, support docs, CI examples, and package metadata
+  around the `0.2.6` rollout surface.
+
+## [0.2.5] - 2026-06-20
+
+Credibility and compatibility patch: GitHub gpgsig commit binding, SE050 mock transport, YubiKey pubkey export, Rekor/GUAC CLI MVP.
 
 ### Added
 - **GitHub `gpgsig` commit binding** — verify envelopes against raw commit object SHA when OpenPGP signatures are present.

{matrixscroll-0.2.5 → matrixscroll-0.2.6}/CONTRIBUTING.md

@@ -36,7 +36,7 @@ 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=cursor        # or your IDE / agent tool name
+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

matrixscroll-0.2.6/PKG-INFO

@@ -0,0 +1,267 @@
+Metadata-Version: 2.4
+Name: matrixscroll
+Version: 0.2.6
+Summary: Signed provenance for agent-assisted Git commits with offline verification; emulated Ed25519 ships today and the SE050 hardware path remains an optional preview.
+Project-URL: Homepage, https://matrixscroll.com
+Project-URL: Documentation, https://matrixscroll.com/docs
+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://matrixscroll.com/verify
+Project-URL: Compare, https://matrixscroll.com/compare
+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/
+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: Reference Device, https://matrixscroll.com/device
+Author-email: SSX360 <security@matrixscroll.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: ai,ed25519,matrixscroll,provenance,root-of-trust,secure-element,signing,ssx360,supply-chain
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: cryptography>=41.0
+Provides-Extra: dev
+Requires-Dist: build>=1.0; extra == 'dev'
+Requires-Dist: pytest>=7.4; extra == 'dev'
+Provides-Extra: git
+Provides-Extra: hardware
+Requires-Dist: pyserial>=3.5; extra == 'hardware'
+Provides-Extra: tpm
+Provides-Extra: yubikey
+Requires-Dist: python-pkcs11>=0.7; extra == 'yubikey'
+Description-Content-Type: text/markdown
+
+# Matrix Scroll
+
+Signed provenance for agent-assisted Git commits with offline verification.
+
+Matrix Scroll is a cryptographic evidence layer for Git. When an agent, CI
+workflow, or human operator produces a commit, a signed commit envelope can
+record the actor, tool, and optional bounded scope. Anyone can verify that
+envelope locally, in CI, or in the browser without trusting the editor session
+that produced it.
+
+The reference SDK ships pure Ed25519 over canonical manifest bytes today. The
+SSX360 / NXP SE050 path is the compatible next trust layer and remains a
+preview path until device acceptance is complete.
+
+## Honest limits
+
+- Shipping now: PyPI `matrixscroll==0.2.6`, Git post-commit hooks,
+  `matrixscroll envelope-verify`, Scroll Gate PR verification, browser
+  verifier, the GitHub Action, and a USB CDC host transport preview for the
+  SE050 rollout path.
+- In progress: RP2350 + SE050 firmware validation, external Ed25519-capable
+  hardware key backends, and transparency-log integrations.
+- Not: IAM, sandboxing, prompt filtering, or an agent runtime.
+
+## Quickstart
+
+```bash
+pip install "matrixscroll==0.2.6"
+matrixscroll hook-install
+
+export MATRIXSCROLL_ACTOR_TYPE=agent
+export MATRIXSCROLL_TOOL=agent-runner
+git commit -m "feat: agent-assisted change"
+
+matrixscroll envelope-verify "$(git rev-parse HEAD)"
+```
+
+See [`docs/quickstart-git.md`](docs/quickstart-git.md) and run
+[`examples/demo/agent-commit-demo.sh`](examples/demo/agent-commit-demo.sh).
+
+## CI verify
+
+### Scroll Gate for a PR commit range
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: SSX360/matrixscroll-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.2.6"
+    require-mode: emulated
+```
+
+Publish envelopes to git notes before review:
+
+```bash
+matrixscroll envelope-publish-notes --base origin/main --head HEAD
+git push origin refs/notes/matrixscroll
+```
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: SSX360/matrixscroll-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.2.6"
+    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).
+
+The `--require-mode`, `--trusted-keys`, and actor or delegation policy checks
+are available in the `0.2.x` line; the examples in this README pin `0.2.6`.
+
+## Why it is different from Sigstore
+
+Sigstore, GitHub artifact attestations, and SLSA answer "what was built in
+CI?" Matrix Scroll answers "who signed this commit before push?" The systems
+are complementary: Matrix Scroll signs commit envelopes at commit time, while
+artifact-attestation systems sign build outputs later in the delivery chain.
+
+Matrix Scroll does not compete with general authentication keys on their home
+field. Existing hardware roots can become Matrix Scroll signing backends only
+when they preserve the same pure Ed25519 byte contract.
+
+## Public proof links
+
+- Browser verifier: <https://matrixscroll.com/verify/>
+- Compare page: <https://matrixscroll.com/compare/>
+- Specification: [`SPEC.md`](SPEC.md)
+- Commit envelope schema: [`schemas/commit-envelope.v1.json`](schemas/commit-envelope.v1.json)
+- Whitepaper: [`docs/WHITEPAPER.md`](docs/WHITEPAPER.md)
+- Conformance vectors: [`vectors/`](vectors/)
+- GitHub Action: <https://github.com/SSX360/matrixscroll-verify-action>
+- Agentic AI controls: [`docs/AGENTIC_AI_SECURITY.md`](docs/AGENTIC_AI_SECURITY.md)
+- Site: <https://matrixscroll.com>
+- Reference device path: <https://matrixscroll.com/device/>
+
+## Python API
+
+```bash
+pip install "matrixscroll==0.2.6"
+```
+
+```python
+import matrixscroll
+
+print(matrixscroll.status())
+# {'schema': 'matrixscroll.identity.v1', 'available': True,
+#  'mode': 'emulated', 'device_id': 'MS-A3F2-9C81', ...}
+
+signed = matrixscroll.sign_manifest({"release": "v1.0.0", "artifacts": [...]})
+
+assert matrixscroll.verify_manifest(signed)
+```
+
+## CLI
+
+```bash
+$ matrixscroll status
+{
+  "available": true,
+  "device_id": "MS-A3F2-9C81",
+  "mode": "emulated",
+  "public_key": "...",
+  "schema": "matrixscroll.identity.v1"
+}
+
+$ matrixscroll sign release.json > release.signed.json
+$ matrixscroll verify release.signed.json
+{"device_id": "MS-A3F2-9C81", "mode": "emulated", "ok": true, "signed_at": "..."}
+```
+
+`matrixscroll verify` exits `0` on a valid signature and `2` on failure
+(tampered manifest, missing signature block, wrong schema or algorithm,
+mismatched device ID, malformed public key, unreadable file).
+
+## How it works
+
+```text
+your IDE / agent / CI
+         |
+         |  commit envelope, release manifest, evidence pack, SBOM
+         v
+matrixscroll.sign_manifest(...)  /  post-commit hook
+         |
+         |  canonical JSON (sorted keys, ASCII-escaped, no NaN,
+         |  signature block excluded from input)
+         v
+IdentityProvider          -->  Ed25519 signature
+(L1 emulated today,
+ SSX360 / SE050 roadmap)
+         |
+         v
+signed document  -->  matrixscroll.verify_manifest(...)
+                      (anyone, anywhere, offline)
+```
+
+Switch providers with `MATRIXSCROLL_MODE`. Hardware mode includes a USB CDC
+host transport preview and a mock path for CI; real SE050 signing still
+depends on device firmware validation. External-key backends stay out of the
+mainline until they can sign the same canonical bytes with Ed25519.
+
+## Compliance levels
+
+| Level | Provider | Backed by | Status |
+| ----- | -------- | --------- | ------ |
+| **L1** Emulated | `EmulatedProvider` | Software key, file-backed (0600) | Shipping |
+| **L2** Hardware | `HardwareProvider` | NXP SE050 secure element (SSX360) | In progress |
+| **L3** Attested | future | L2 + remote attestation | Roadmap |
+
+`status()` exposes the active level via the `mode` and `available` fields.
+
+## Storage and trust boundaries
+
+- Emulated key store: `~/.matrixscroll/device.json`
+  (override with `MATRIXSCROLL_HOME`).
+- The directory is created `0700`; the seed file is opened `0600` with
+  `O_CREAT|O_EXCL` so the private seed is never momentarily world-readable.
+- A corrupt or truncated store fails loud (`IdentityError`) rather than
+  silently minting a fresh identity.
+- The planned hardware path holds nothing private on disk; the seed is sealed
+  in the secure element.
+
+## Reference implementation, not the only one
+
+Matrix Scroll is a protocol. This Python package is the reference. We welcome
+implementations in Rust, Go, TypeScript, and embedded C. Run them against
+[`vectors/`](vectors/) to self-certify. See `CONTRIBUTING.md`.
+
+## Agentic AI guidance proof
+
+The repo includes a machine-readable control matrix at
+[`controls/agentic_ai_controls.json`](controls/agentic_ai_controls.json), an
+example bounded-agent evidence manifest at
+[`examples/agentic_ai_evidence_manifest.json`](examples/agentic_ai_evidence_manifest.json),
+and executable checks in `tests/test_agentic_guidance.py`.
+
+## License
+
+- Code: **Apache-2.0** (`LICENSE`).
+- Specification text (`SPEC.md`, `vectors/`): **CC0 1.0** - public domain.
+
+## Security
+
+See [`SECURITY.md`](SECURITY.md). Report vulnerabilities privately to
+**security@matrixscroll.com** or via a GitHub Security Advisory.

matrixscroll-0.2.6/README.md

@@ -0,0 +1,216 @@
+# Matrix Scroll
+
+Signed provenance for agent-assisted Git commits with offline verification.
+
+Matrix Scroll is a cryptographic evidence layer for Git. When an agent, CI
+workflow, or human operator produces a commit, a signed commit envelope can
+record the actor, tool, and optional bounded scope. Anyone can verify that
+envelope locally, in CI, or in the browser without trusting the editor session
+that produced it.
+
+The reference SDK ships pure Ed25519 over canonical manifest bytes today. The
+SSX360 / NXP SE050 path is the compatible next trust layer and remains a
+preview path until device acceptance is complete.
+
+## Honest limits
+
+- Shipping now: PyPI `matrixscroll==0.2.6`, Git post-commit hooks,
+  `matrixscroll envelope-verify`, Scroll Gate PR verification, browser
+  verifier, the GitHub Action, and a USB CDC host transport preview for the
+  SE050 rollout path.
+- In progress: RP2350 + SE050 firmware validation, external Ed25519-capable
+  hardware key backends, and transparency-log integrations.
+- Not: IAM, sandboxing, prompt filtering, or an agent runtime.
+
+## Quickstart
+
+```bash
+pip install "matrixscroll==0.2.6"
+matrixscroll hook-install
+
+export MATRIXSCROLL_ACTOR_TYPE=agent
+export MATRIXSCROLL_TOOL=agent-runner
+git commit -m "feat: agent-assisted change"
+
+matrixscroll envelope-verify "$(git rev-parse HEAD)"
+```
+
+See [`docs/quickstart-git.md`](docs/quickstart-git.md) and run
+[`examples/demo/agent-commit-demo.sh`](examples/demo/agent-commit-demo.sh).
+
+## CI verify
+
+### Scroll Gate for a PR commit range
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: SSX360/matrixscroll-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.2.6"
+    require-mode: emulated
+```
+
+Publish envelopes to git notes before review:
+
+```bash
+matrixscroll envelope-publish-notes --base origin/main --head HEAD
+git push origin refs/notes/matrixscroll
+```
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- uses: SSX360/matrixscroll-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.2.6"
+    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).
+
+The `--require-mode`, `--trusted-keys`, and actor or delegation policy checks
+are available in the `0.2.x` line; the examples in this README pin `0.2.6`.
+
+## Why it is different from Sigstore
+
+Sigstore, GitHub artifact attestations, and SLSA answer "what was built in
+CI?" Matrix Scroll answers "who signed this commit before push?" The systems
+are complementary: Matrix Scroll signs commit envelopes at commit time, while
+artifact-attestation systems sign build outputs later in the delivery chain.
+
+Matrix Scroll does not compete with general authentication keys on their home
+field. Existing hardware roots can become Matrix Scroll signing backends only
+when they preserve the same pure Ed25519 byte contract.
+
+## Public proof links
+
+- Browser verifier: <https://matrixscroll.com/verify/>
+- Compare page: <https://matrixscroll.com/compare/>
+- Specification: [`SPEC.md`](SPEC.md)
+- Commit envelope schema: [`schemas/commit-envelope.v1.json`](schemas/commit-envelope.v1.json)
+- Whitepaper: [`docs/WHITEPAPER.md`](docs/WHITEPAPER.md)
+- Conformance vectors: [`vectors/`](vectors/)
+- GitHub Action: <https://github.com/SSX360/matrixscroll-verify-action>
+- Agentic AI controls: [`docs/AGENTIC_AI_SECURITY.md`](docs/AGENTIC_AI_SECURITY.md)
+- Site: <https://matrixscroll.com>
+- Reference device path: <https://matrixscroll.com/device/>
+
+## Python API
+
+```bash
+pip install "matrixscroll==0.2.6"
+```
+
+```python
+import matrixscroll
+
+print(matrixscroll.status())
+# {'schema': 'matrixscroll.identity.v1', 'available': True,
+#  'mode': 'emulated', 'device_id': 'MS-A3F2-9C81', ...}
+
+signed = matrixscroll.sign_manifest({"release": "v1.0.0", "artifacts": [...]})
+
+assert matrixscroll.verify_manifest(signed)
+```
+
+## CLI
+
+```bash
+$ matrixscroll status
+{
+  "available": true,
+  "device_id": "MS-A3F2-9C81",
+  "mode": "emulated",
+  "public_key": "...",
+  "schema": "matrixscroll.identity.v1"
+}
+
+$ matrixscroll sign release.json > release.signed.json
+$ matrixscroll verify release.signed.json
+{"device_id": "MS-A3F2-9C81", "mode": "emulated", "ok": true, "signed_at": "..."}
+```
+
+`matrixscroll verify` exits `0` on a valid signature and `2` on failure
+(tampered manifest, missing signature block, wrong schema or algorithm,
+mismatched device ID, malformed public key, unreadable file).
+
+## How it works
+
+```text
+your IDE / agent / CI
+         |
+         |  commit envelope, release manifest, evidence pack, SBOM
+         v
+matrixscroll.sign_manifest(...)  /  post-commit hook
+         |
+         |  canonical JSON (sorted keys, ASCII-escaped, no NaN,
+         |  signature block excluded from input)
+         v
+IdentityProvider          -->  Ed25519 signature
+(L1 emulated today,
+ SSX360 / SE050 roadmap)
+         |
+         v
+signed document  -->  matrixscroll.verify_manifest(...)
+                      (anyone, anywhere, offline)
+```
+
+Switch providers with `MATRIXSCROLL_MODE`. Hardware mode includes a USB CDC
+host transport preview and a mock path for CI; real SE050 signing still
+depends on device firmware validation. External-key backends stay out of the
+mainline until they can sign the same canonical bytes with Ed25519.
+
+## Compliance levels
+
+| Level | Provider | Backed by | Status |
+| ----- | -------- | --------- | ------ |
+| **L1** Emulated | `EmulatedProvider` | Software key, file-backed (0600) | Shipping |
+| **L2** Hardware | `HardwareProvider` | NXP SE050 secure element (SSX360) | In progress |
+| **L3** Attested | future | L2 + remote attestation | Roadmap |
+
+`status()` exposes the active level via the `mode` and `available` fields.
+
+## Storage and trust boundaries
+
+- Emulated key store: `~/.matrixscroll/device.json`
+  (override with `MATRIXSCROLL_HOME`).
+- The directory is created `0700`; the seed file is opened `0600` with
+  `O_CREAT|O_EXCL` so the private seed is never momentarily world-readable.
+- A corrupt or truncated store fails loud (`IdentityError`) rather than
+  silently minting a fresh identity.
+- The planned hardware path holds nothing private on disk; the seed is sealed
+  in the secure element.
+
+## Reference implementation, not the only one
+
+Matrix Scroll is a protocol. This Python package is the reference. We welcome
+implementations in Rust, Go, TypeScript, and embedded C. Run them against
+[`vectors/`](vectors/) to self-certify. See `CONTRIBUTING.md`.
+
+## Agentic AI guidance proof
+
+The repo includes a machine-readable control matrix at
+[`controls/agentic_ai_controls.json`](controls/agentic_ai_controls.json), an
+example bounded-agent evidence manifest at
+[`examples/agentic_ai_evidence_manifest.json`](examples/agentic_ai_evidence_manifest.json),
+and executable checks in `tests/test_agentic_guidance.py`.
+
+## License
+
+- Code: **Apache-2.0** (`LICENSE`).
+- Specification text (`SPEC.md`, `vectors/`): **CC0 1.0** - public domain.
+
+## Security
+
+See [`SECURITY.md`](SECURITY.md). Report vulnerabilities privately to
+**security@matrixscroll.com** or via a GitHub Security Advisory.

matrixscroll-0.2.6/docs/ADOPTER_KIT.md

@@ -0,0 +1,70 @@
+# Adopter Kit
+
+This page is for OSS maintainers, platform teams, and design-partner engineers
+who want to trial Matrix Scroll without changing their core workflow.
+
+## Best first-fit teams
+
+- OSS repos with active PR review and at least one protected branch
+- platform or DevSecOps teams evaluating agent-assisted coding controls
+- teams that already use GitHub Actions and can add one verification job
+
+## 15-minute pilot
+
+1. Install `matrixscroll==0.2.6` in one repo.
+2. Run `matrixscroll hook-install`.
+3. Make one agent-assisted commit and verify it locally.
+4. Publish notes with `matrixscroll envelope-publish-notes`.
+5. Add `SSX360/matrixscroll-verify-action@v1` to PR CI.
+
+## Suggested evaluation workflow
+
+```yaml
+name: Verify PR commit envelopes
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  verify-provenance:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: SSX360/matrixscroll-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.2.6"
+          require-mode: emulated
+```
+
+## What to collect during the pilot
+
+- one passing local `envelope-verify`
+- one passing PR range check
+- one example of a failed verify after tampering or missing notes
+- reviewer feedback on whether actor / tool attribution is useful
+
+## Success criteria
+
+- the team can explain the difference between commit-time and artifact-time proof
+- the GitHub Action is understandable to the repo owner
+- the team can point to one real decision that the envelope data improved
+
+## What not to assume
+
+- L1 emulated mode is not a hardware root of trust
+- Matrix Scroll does not replace IAM or sandboxing
+- Matrix Scroll does not replace release-signing or artifact attestations
+
+## Public follow-through
+
+If a pilot works, publish one of these:
+
+- a short repo note describing the evaluation
+- a screenshot of the passing GitHub Action
+- a testimonial about why commit-time attribution mattered

matrixscroll-0.2.6/docs/COMMIT_TIME_VS_ARTIFACT_TIME.md

@@ -0,0 +1,51 @@
+# Commit-Time Proof vs Artifact-Time Proof
+
+Matrix Scroll is easiest to understand when compared to the supply-chain tools
+developers already know.
+
+## The short version
+
+- **Matrix Scroll:** "Who signed this commit before push?"
+- **Sigstore / GitHub attestations / SLSA:** "What was built in CI?"
+
+These answers are different, and mature teams usually want both.
+
+## Side-by-side
+
+| Question | Matrix Scroll | Sigstore / GitHub attestations / SLSA |
+|----------|---------------|----------------------------------------|
+| Primary layer | Git commit | Build artifact |
+| Timing | Before push | After build |
+| Main unit | Commit envelope | Package, container, or predicate |
+| Actor / tool in record | Yes | Usually no |
+| Offline verify | Yes | Varies by workflow |
+| Hardware path | In progress | External to the standard flow |
+
+## Where Matrix Scroll fits
+
+Use Matrix Scroll when you need:
+
+- evidence that an agent, CI job, or human produced a commit
+- a verifier that works on any clone
+- a commit-native gate before merge
+
+Use artifact-layer tools when you need:
+
+- release signing
+- container provenance
+- SBOM / predicate chains
+- deployment and registry policy
+
+## How to use them together
+
+1. Sign agent-assisted commits with Matrix Scroll.
+2. Verify commit ranges in PRs with `SSX360/matrixscroll-verify-action@v1`.
+3. Keep Sigstore, GitHub attestations, or SLSA on the release path.
+
+That gives teams both commit-time attribution and artifact-time provenance.
+
+## Public proof links
+
+- [Compare page](https://matrixscroll.com/compare/)
+- [Browser verifier](https://matrixscroll.com/verify/)
+- [SPEC.md](../SPEC.md)

{matrixscroll-0.2.5 → matrixscroll-0.2.6}/docs/COMPARISON.md

@@ -60,7 +60,7 @@ No single competitor listed above combines all four today.
 - **CI gate:** Scroll Gate ships in **0.2.3+** — PR commit-range verification via `envelope-verify-range`, git notes transport (`refs/notes/matrixscroll`), and filesystem bundles. [`matrixscroll-verify-action`](https://github.com/SSX360/matrixscroll-verify-action) supports `head-ref`/`base-ref` range mode with agent/human counts.
 - **Owner/delegation attestation:** Optional `delegation` block in commit envelope schema (**0.2.4+**); see [`delegation-attestation-rfc.md`](delegation-attestation-rfc.md). Alien still leads on OIDC/DPoP owner binding.
 - **Multi-agent commits:** Multiple actors in one envelope — on the roadmap.
-- **Rekor / transparency log:** Not shipped yet; would align with Sigstore ecosystem expectations.
+- **Rekor / GUAC export:** Dry-run CLI ships in **0.2.6** (`envelope-publish-rekor`, `envelope-export-guac`); full Rekor upload integration still in progress.
 - **Hardware:** SSX360 reference device and Scroll Key retail are **in progress**; L1 emulated key is what you can use now.
 
 ## When to use what