Use after staging changes and before or after ``git commit`` when you need
commit-time actor/tool proof. Prefer ``sign_action`` for non-Git evidence
(CI steps, IaC, migrations). Do not use for verification — call
``verify_envelope`` or ``verify_pr_range`` instead.

Side effects: may write ``.matrixscroll/envelopes/<sha>.json`` when ``save``
is true. Requires a Git repo and Matrix Scroll identity store. No network.
Returns ``{ok, sha, envelope, path, error?}``.

Parameters:
    workspace: Git repo root (defaults to detected repo).
    commit_sha: Existing commit to envelope (defaults to staged/next commit).
    actor_type: Provenance actor, e.g. agent, human, ci.
    tool: Producing tool name, e.g. cursor, claude-code.
    agent_scope: Optional bounded scope path/glob for agent commits.
    sign: Ed25519-sign the envelope (default True).
    save: Persist under .matrixscroll/envelopes (default True).

Use for a single commit SHA or explicit envelope JSON file. Prefer
``verify_pr_range`` for PR/branch ranges and ``audit_export`` for procurement
bundles spanning many commits. Do not use when you only need hook status —
call ``status`` instead.

Read-only: no network or SSX360_API_KEY required. Does not modify Git state.
Returns ``{ok, sha, actor_type, mode, error?, envelope?}``; ``ok`` is false
on signature, policy, expiry, or missing-envelope errors.

Parameters:
    workspace: Git repo root (defaults to detected repo).
    commit_sha: Commit SHA to verify (uses local envelope file).
    envelope / envelope_path: Optional explicit path to envelope JSON.
    require_mode: Policy filter, e.g. emulated or hardware (empty skips).
    trusted_keys / trusted_keys_file: JSON file listing trusted public keys.
    check_expiry: Reject envelopes with expired delegation timestamps.
    require_actor_types / deny_actor_types: Actor policy allow/deny lists.

Use for merge gates and PR review (many commits). Prefer ``verify_envelope``
for one commit offline. Prefer ``audit_export`` when auditors need bundles,
not pass/fail on a range.

Hosted mode (default): calls ssx360.com; requires SSX360_API_KEY.
Set ``source=local|notes|bundle`` to verify offline without an API key.
Read-only for Git refs; hosted mode emits usage to ssx360.com.
Returns ``{ok, verified_count, unsigned_shas?, failures?, error?}``.

Parameters:
    workspace: Git repo root (defaults to detected repo).
    base: Range start ref (exclusive), e.g. origin/main.
    head: Range end ref (inclusive), e.g. HEAD or PR head SHA.
    source: Envelope transport — hosted, local, notes, or bundle.
    notes_ref: Git notes ref when source=notes.
    bundle_dir: Bundle directory when source=bundle.
    require_mode: Policy require_mode filter.
    trusted_keys_file: Trusted keys JSON for signed/untrusted actor checks.
    require_actor_types / deny_actor_types: Actor policy lists.
    allow_empty: Accept a labelled empty range. Defaults to false.

Use after ``create_envelope`` when CI reads ``refs/notes/matrixscroll``.
Do not use for offline single-commit checks — call ``verify_envelope``.
Do not use for hosted org audit — call ``audit_export`` with SSX360_API_KEY.

Side effects: updates the local git notes ref only; push
``refs/notes/matrixscroll`` to remote separately. Returns
``{ok, published, notes_ref, error?}``.

Parameters:
    workspace: Git repo root (defaults to detected repo).
    base: Range start ref (exclusive) for envelopes to publish.
    head: Range end ref (inclusive) for envelopes to publish.
    notes_ref: Git notes ref to write (default refs/notes/matrixscroll).

Call first in a new repo before any verify/sign tool. Read-only: no Git or
filesystem writes, no network. Do not use for signature checks — call
``verify_envelope`` or ``verify_pr_range`` instead.

Returns ``{ok, config, hook_installed, envelope_count, mode?, device_id?}``.

Parameters:
    workspace: Git repo root (defaults to detected repo).

Use for CI steps, IaC changes, DB migrations, API calls, contract deploys,
or agent delegation grants. Prefer ``create_envelope`` for Git commits.
Do not use for verification — call ``verify_envelope`` on exported JSON.

Side effects: writes ``save_path`` when set; uses local identity store.
No network unless you later upload the signed artifact yourself.
Returns ``{ok, signed, device_id, mode, path?, error?}``.

Parameters:
    action_type: Provenance label (git_commit, ci_step, iac_change, etc.).
    payload: JSON object to sign (no top-level signature block).
    key_path: Optional MATRIXSCROLL_HOME override for CI ephemeral keys.
    save_path: Optional file path to write the signed document.

Use when auditors need envelope bundles (JSON, GUAC JSONL, or evidence-pack).
Prefer ``verify_pr_range`` for merge-gate pass/fail on a commit range.
Prefer ``list_envelopes`` to browse hosted metadata without exporting files.

Hosted mode requires SSX360_API_KEY and calls ssx360.com/api/v1/audit/export.
Local fallback: exports from git notes or on-disk envelopes when no API key.
Side effects: writes files under ``output_dir`` locally; hosted mode returns
download metadata. Returns ``{ok, bundle?, download_url?, error?}``.

Parameters:
    start_date / end_date: ISO 8601 UTC bounds (hosted filter).
    signer_id: Filter by device_id or public-key fingerprint.
    format: json, guac, or evidence-pack serialization.
    include_verification: Attach per-envelope verification replay data.
    workspace / base / head / output_dir: Local fallback range and output path.

Use for paginated org triage and agent memory. Requires SSX360_API_KEY.
Do not use for offline Git repos — call ``status`` and ``verify_envelope``.
Do not use for bulk export — call ``audit_export`` instead.

Read-only: no local Git writes. Returns ``{ok, envelopes, total?, error?}``.

Parameters:
    limit: Maximum envelopes per page (1–200, default 50).
    offset: Pagination skip index (zero-based).
    signer_filter: Optional device_id or public-key prefix.

Use before ``sign_mcp_manifest`` to capture install-time tool names, descriptions,
and input schema hashes. Re-scan later and pass results to ``verify_mcp_manifest``
with a baseline to detect rug-pull drift. Read-only; no network required when
``tools`` is supplied directly.

Returns ``{ok, tool_count, surface_hash, manifest}``.

Use after ``scan_mcp_server``. Prefer ``verify_mcp_manifest`` for checks.
Side effects: may write ``save_path``; uses local identity store. No network.
Returns ``{ok, signed, device_id, path?, error?}``.

Use in CI or before trusting an MCP server after upgrade. Read-only; no network.
Returns ``{ok, surface_hash, tool_count, drift?, error?}``; ``ok`` is false on
bad signature or surface drift vs baseline.

Use when a WEB_WIZARD or Steel run completes. Hashes the full trace bytes,
records step count and run_id, and writes an offline-verifiable envelope.
Side effects: writes envelope file; uses local identity store. No network.
Returns ``{ok, signed, path?, error?}``.

Use in CI or auditor handoff. Read-only; no network.
Returns ``{ok, run_id?, step_count?, error?}``.