Prepare ProofPath for external reviewers

[safal207]

Goal

Make ProofPath easier to review, run, and critique by external grant reviewers, cybersecurity researchers, and open-source contributors.

ProofPath should be understandable in 60 seconds and runnable in a few minutes.

Current positioning

Core message:

Valid credentials should not automatically mean valid action.

ProofPath is a defensive pre-execution gateway for high-risk AI-agent/API actions. It complements HTTPS, OAuth, IAM, API keys, and ordinary infrastructure security by adding an action-level decision and audit boundary before execution.

Reviewer path

A reviewer should be able to follow this path:

1. README.md — understand the project quickly.
2. docs/reviewer-summary.md — read the 1–2 page summary.
3. examples/agent-dangerous-action/README.md — run or inspect the dangerous-action demo.
4. docs/demo-transcript.md — see expected behavior.
5. docs/grant-updates/security-grant-revision-proofpath-update.md — understand the revised grant-submission context.
6. specs/threat-model.md — inspect the threat model.
7. specs/proofpath-http-profile-v0.1.md — inspect the protocol profile.
8. COMMUNITY_EXPERIMENTS.md — choose a feedback/red-team path.

Tasks

• Verify all reviewer links in README.md resolve correctly.
• Confirm the quick demo commands work from a clean checkout.
• Capture expected ACCEPT and BLOCK outputs in docs/demo-transcript.md.
• Add a short “expected output” section to the dangerous-action demo README.
• Add a minimal architecture diagram or text flow for reviewer scanning.
• Make current limitations explicit and easy to find.
• Add 3–5 negative test cases for missing intent, missing causal parent, missing scope, invalid reversibility, and irreversible action without approval.
• Add an audit-log verification note: what is currently implemented and what is planned.
• Check whether GitHub Actions is running consistently on main.
• Invite external feedback through the community experiment issues.

Acceptance criteria

• A reviewer can understand ProofPath without reading the whole repository.
• A developer can run the dangerous-action demo locally.
• The repo does not claim that ProofPath replaces HTTPS/OAuth/IAM/API keys.
• The repo does not claim endorsement by any funder.
• Current limitations are stated clearly.
• CI status is known and documented honestly.

Notes

This issue tracks repository readiness, not new scope expansion. The priority is clarity, reproducibility, and conservative security framing.