docs: restructure README following opena2a-cli template

[thebenignhacker]

Summary

• Plain left-aligned markdown (logo inlined small, not centered). First runnable command + simulated output land within line 30 of the file, so a new user sees concrete value before scrolling.
• Commands grouped into four tables by job (Assess / Encrypt / Vault / Operate) instead of one mixed code block plus a paragraph list. A new "Which command do I want" intent table replaces the redundant "What It Does" + "Common Commands" + "Use Cases" trio.
• New "Verifying releases" section documents the trust signal that actually ships today: SHA256SUMS.txt on each GitHub Release. Workflows have --provenance + id-token: write scaffolding but published artifacts on npm 0.3.4 and PyPI 1.4.3 carry no SLSA attestations or Sigstore signatures, so the README does not claim them yet.
• Drops the centered marketing slogan and the hardcoded Python SDK v1.4.3 line that would age instantly.
• Corrects the census ecosystem count from 5 to "11 + NVD" so it matches the CLI's census --help output.
• 246 -> 209 lines.

Verification done before drafting

• npm view cryptoserve dist.attestations returns missing on 0.3.4; PyPI 1.4.3 wheels show has_sig: false. README claims only SHA256SUMS.txt parity, which is verifiable.
• Algorithm DB: Object.keys(ALGORITHM_DB).length == 131. README says "131 algorithms".
• Languages: 5 source-scanner profiles (go, python, java, rust, c) covering 6 languages (JS/TS via manifest scanner, Java/Kotlin and C/C++ as combined profiles). README says "6 languages" with the explicit list.
• Every linked doc path (docs/cli.md, docs/security/index.md, etc.) exists in the tree.
• Em-dash scan: grep -cP '—' README.md returns 0. Style Check workflow should pass.

Test plan

• Style Check workflow green on this PR.
• CI workflow green.
• Render the file on GitHub and confirm the inline logo sits next to the H1 without overlapping the badges.
• Eyeball that the first npx cryptoserve scan . block lands above the fold on a standard laptop viewport.
• Confirm "Which command do I want" reads naturally to a first-time user.

Follow-ups (not in this PR)

• Enable SLSA provenance and Sigstore signatures for real on the next publish, then revise the "Verifying releases" section to point at npm view ... dist.attestations and python -m sigstore verify.
• Decide whether docs/use-cases/ is worth creating (OpenA2A has it; this PR omits it to avoid linking to nonexistent files).

[github-actions]

Claude finished @thebenignhacker's task —— View job

---

Security-Focused PR Review

Completed security analysis of README.md documentation changes.

Tasks

• Read repository guidelines (CLAUDE.md)
• Read changed README.md file
• Perform security analysis per 12-point checklist
• Post findings

---

Security Analysis Results

This PR contains documentation-only changes to README.md. I've reviewed all code examples, commands, and links against the 12-point security checklist:

✅ No Security Issues Found

Checks Performed:

1. Injection vulnerabilities - N/A (documentation only, no executable code)
2. Authentication/authorization bypasses - N/A (no auth logic)
3. Insecure deserialization or eval - N/A (no code execution)
4. Hardcoded credentials or secrets - ✅ PASS
   • All password/secret references use environment variables ($SECRET) or placeholders (<value>)
   • Line 79: --password $SECRET - safe (env var)
   • Line 81: vault set API_KEY <value> - safe (placeholder)
5. SSRF or open redirect risks - N/A (no network requests in code)
6. Cryptographic misuse - N/A (documentation of a crypto tool, not implementing crypto)
7. Prototype pollution - N/A (no JavaScript object manipulation)
8. ReDoS - N/A (no regex in executable code)
9. Command injection - ✅ PASS
   • All shell commands are safe examples
   • No string interpolation of untrusted input
   • Line 178: Good security practice documented - explicitly warns against curl | sh, recommends downloading and verifying checksums first

Logic Bugs (Items 10-12): N/A - No scoring, gating, or filter logic in this documentation change

Reviewed Code Examples:

• npx cryptoserve scan . - safe
• pip install cryptoserve - safe
• npm install -g cryptoserve - safe
• Docker commands (line 175) - safe, uses official registry path
• Git clone commands (line 49, 203) - safe, official repo
• CI/CD examples (lines 131-136) - safe, demonstrates proper SARIF upload

External Links: All links point to official project domains or GitHub resources:

• cryptoserve.dev (project website)
• census.cryptoserve.dev (project subdomain)
• github.com/ecolibria/cryptoserve (project repo)
• npmjs.com/package/cryptoserve (official package)
• pypi.org/project/cryptoserve (official package)

Notable Security Improvements in PR:

• Line 178: Documents proper release verification via SHA256SUMS.txt
• Line 178: Explicitly warns against piping curl to shell - this is a security best practice
• Lines 60-69: Documents verification procedures for npm/PyPI releases
• Accurately states that SLSA attestations are not yet available (transparency)

Conclusion

This is a safe documentation restructure with no security concerns. The PR actually improves security awareness by:

1. Warning users not to use curl | sh pattern
2. Documenting proper release verification procedures
3. Being transparent about current attestation coverage

FINDINGS_COUNT=0

---

[github-actions]

Manual review required. This PR did not meet auto-merge criteria:

• Security review found issues (findings: unknown)
• PR author 'thebenignhacker' is not in the trusted auto-merge list
• Too many lines changed (285 > 200)
• PR is too new (2 min < 5 min minimum)