Refresh README messaging for TrustSignal discoverability#68
Refresh README messaging for TrustSignal discoverability#68chrismaz11 wants to merge 1 commit intomasterfrom
Conversation
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 07205fdc8b
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| ### Verification Request | ||
|
|
||
| ```json | ||
| POST /api/attest-evidence |
There was a problem hiding this comment.
The README now instructs integrators to call POST /api/attest-evidence, but this route is not implemented in the repo (I checked API wiring in apps/api/src/server.ts, which registers POST /api/v1/verify, and the public contract in openapi.yaml also exposes /api/v1/verify). Following this example will fail with 404 on the very first request, which breaks the advertised evaluator/integration flow.
Useful? React with 👍 / 👎.
| HTTP/1.1 201 Created | ||
|
|
||
| { | ||
| "receipt_id": "tsig_rcpt_01JTQY8N1Q0M4F4F5T4J4B8Y9R", | ||
| "status": "signed", |
There was a problem hiding this comment.
This sample response shows HTTP/1.1 201 Created and snake_case fields like receipt_id/attested_at, but the documented and implemented verifier contract returns a 200 response with camelCase fields (receiptId, receiptSignature, etc.) in openapi.yaml and the /api/v1/verify handler path in apps/api/src/server.ts. Consumers who build parsing logic from this README example will not match real responses.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
This PR rewrites the repository’s main README to be TrustSignal-first, positioning it as “evidence integrity infrastructure” and directing readers to trustsignal.dev for documentation, security materials, and pilot access.
Changes:
- Replaces the prior developer/evaluator-focused README content with product-led messaging and a simplified flow overview.
- Adds workflow fit framing, a receipt model example, and consolidated documentation links.
- Introduces a “claims boundary,” security notes, and pilot/contact calls-to-action.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| | Verification core | 6 / 10 | Cryptographic hashing and JWS signing knowledge needed | | ||
| | Smart contracts | 8 / 10 | Requires Solidity and Hardhat experience | | ||
| | ZKP circuits | 9 / 10 | Requires Rust and Halo2 zero-knowledge proof expertise | | ||
| To report a vulnerability: [info@trustsignal.dev](mailto:info@trustsignal.dev) |
There was a problem hiding this comment.
The README lists info@trustsignal.dev as the vulnerability reporting address, but SECURITY.md instructs reporters to use security@trustsignal.dev. Please make these consistent so security reports go to the right inbox.
| To report a vulnerability: [info@trustsignal.dev](mailto:info@trustsignal.dev) | |
| To report a vulnerability: [security@trustsignal.dev](mailto:security@trustsignal.dev) |
| | Layer | What Stays in Place | | ||
| |---|---| | ||
| | Evidence collection | Your existing platform (Vanta, Drata, internal collector) | | ||
| | System of record | Unchanged - TrustSignal adds to it, not replaces it | |
There was a problem hiding this comment.
Minor grammar: "Unchanged - TrustSignal adds to it, not replaces it" is ungrammatical. Consider rephrasing to something like "Unchanged — TrustSignal adds to it; it does not replace it" for clarity.
| | System of record | Unchanged - TrustSignal adds to it, not replaces it | | |
| | System of record | Unchanged — TrustSignal adds to it; it does not replace it | |
| receipt_id: "tsig_rcpt_01JTQY8N1Q0M4F4F5T4J4B8Y9R", | ||
| source: "vanta", | ||
| artifact_hash: "sha256:93f6f35a550cbe1c3f0b5f0c12b9f0d62f3f9c6f8c6a4eddd8fa1fbfd4654af1", | ||
| control_id: "CC6.1", | ||
| timestamp: "2026-03-11T21:00:00Z", | ||
| receipt_status: "signed", | ||
| verification_status: "match", | ||
| provenance: { | ||
| artifact_type: "compliance_evidence", |
There was a problem hiding this comment.
The "Receipt Model" example uses snake_case fields (e.g., receipt_id, receipt_status, verification_status) that don't appear in the OpenAPI receipt/response schemas (which use camelCase like receiptId, plus nested receipt/canonicalReceipt for stored receipts). Suggest aligning this model to openapi.yaml so integrators don't implement against a non-existent shape.
| receipt_id: "tsig_rcpt_01JTQY8N1Q0M4F4F5T4J4B8Y9R", | |
| source: "vanta", | |
| artifact_hash: "sha256:93f6f35a550cbe1c3f0b5f0c12b9f0d62f3f9c6f8c6a4eddd8fa1fbfd4654af1", | |
| control_id: "CC6.1", | |
| timestamp: "2026-03-11T21:00:00Z", | |
| receipt_status: "signed", | |
| verification_status: "match", | |
| provenance: { | |
| artifact_type: "compliance_evidence", | |
| receiptId: "tsig_rcpt_01JTQY8N1Q0M4F4F5T4J4B8Y9R", | |
| source: "vanta", | |
| artifactHash: "sha256:93f6f35a550cbe1c3f0b5f0c12b9f0d62f3f9c6f8c6a4eddd8fa1fbfd4654af1", | |
| controlId: "CC6.1", | |
| createdAt: "2026-03-11T21:00:00Z", | |
| receiptStatus: "signed", | |
| verificationStatus: "match", | |
| provenance: { | |
| artifactType: "compliance_evidence", |
| ┌─────────────────┐ POST /api/attest-evidence ┌──────────────────┐ | ||
| │ Your Workflow │ ──────────────────────────────► │ TrustSignal │ | ||
| │ (Vanta, Drata, │ │ Integrity Layer │ | ||
| │ internal GRC) │ ◄────────────────────────────── │ │ | ||
| └─────────────────┘ Signed receipt + signal └──────────────────┘ |
There was a problem hiding this comment.
The README references a POST /api/attest-evidence endpoint, but this path doesn't exist in the repo/OpenAPI contract (current public endpoint is POST /api/v1/verify). Please update the diagram to match the actual API surface (or update the OpenAPI/implementation if the endpoint was renamed).
| ```json | ||
| POST /api/attest-evidence | ||
| Content-Type: application/json | ||
|
|
||
| { | ||
| "source": "vanta", | ||
| "artifact_hash": "sha256:93f6f35a550cbe1c3f0b5f0c12b9f0d62f3f9c6f8c6a4eddd8fa1fbfd4654af1", | ||
| "control_id": "CC6.1", | ||
| "timestamp": "2026-03-11T21:00:00Z", |
There was a problem hiding this comment.
This request example is marked as JSON but includes HTTP request lines, and the payload shape/field naming (e.g., artifact_hash, control_id) does not match the OpenAPI VerificationRequest schema. Consider switching the fence to an HTTP/curl example and aligning the endpoint + body to POST /api/v1/verify per openapi.yaml.
| ```json | ||
| HTTP/1.1 201 Created | ||
|
|
||
| { | ||
| "receipt_id": "tsig_rcpt_01JTQY8N1Q0M4F4F5T4J4B8Y9R", | ||
| "status": "signed", | ||
| "source": "vanta", | ||
| "control_id": "CC6.1", | ||
| "attested_at": "2026-03-11T21:00:01Z", | ||
| "signature": "tsig_sig_01JTQY8QK6X4YF7M6T2P9A5D3H", | ||
| "provenance": { |
There was a problem hiding this comment.
The receipt response example appears inconsistent with the documented API: OpenAPI returns 200 from POST /api/v1/verify and uses camelCase fields like receiptId rather than receipt_id / attested_at. Please align this example with the contract to avoid sending users to a non-existent response format.
Summary
Why
The existing README was weaker as an indexed landing page for brand and product discoverability. This version is closer to homepage-quality copy and matches the current site story.