fix: align demo with External API docs & flow; cover all endpoints

[Nick-Belhovskyi]

Brings the demo in line with the LexSelect External API contract and fixes the QA-report demo findings (S2-*). The CLI now exercises every API endpoint and the docs describe all of them.

Upload flow — the headline fix (S2-01/02/03/05)

The upload happy path was broken in all three clients: they never sent content_hash_sha256, which the API requires and now verifies.

• All three (Go CLI, TS, Python) now compute the file's SHA-256 and send it hex on completion (PUT /documents/{id}), and base64 as x-amz-checksum-sha256 on the S3 PUT so the server verifies integrity from object metadata.
• TS/Python now send the inferred Content-Type instead of application/octet-stream (the S3 signature requires the matching type).

Go CLI

• root.go — stop using the loaded API key as the --api-key flag default. It was leaked verbatim in --help and on usage errors (S2-06, the most security-sensitive finding). Flags now override env/.env via PersistentPreRun.
• config.go — find .env by walking up from the CWD, so a repo-root .env works when run from cli/ (S2-09).
• list.go — register the --flat flag that was read but never defined (S2-07).
• upload.go — comma-ok type assertions on the create response (S2-14); add --single-request for the multipart POST /documents/upload.
• New commands: parse (GET /documents/{id}/parse) and render (GET /documents/{id}/render) — closes the S2-11/S2-13 coverage gaps.

Examples

• TypeScript — fixed upload flow + a final /parse fetch; documents the local-dev TLS caveat (S2-04).
• Python notebook — fixed upload flow; stops referencing a missing sample.pdf (S2-10), clarifies the page-scoped total (S2-15), and adds a parse + render demonstration.

Docs

• README.md + cli/README.md now document every endpoint (table), the corrected 3-step and single-request flows, the RFC 9457 error model (X-Request-Id, limit reject-not-clamp), the server-to-server / no-CORS stance, and the local-dev TLS caveat.

Verification

• go build / go vet / gofmt -l all clean.
• --help no longer prints the API key (verified with a fake secret: 0 occurrences).
• parse and render commands registered and listed.
• The content_hash + checksum flow matches what was verified end-to-end against the local stack on the API side.

Local-dev note: the 3-step flow's direct S3 PUT can't accept LocalStack's self-signed cert from a strict client (Go / Node) — use --single-request locally or a stack with a trusted cert. Documented in both READMEs.

🤖 Generated with Claude Code

[Nick-Belhovskyi]

Update — now verified end-to-end against a local stack (the earlier "couldn't run e2e" note was during a window where the worker was down).

Ran the built CLI against the live API with a real processed document and a real upload:

Command	Result
list	✅ projects + docs
get	✅ metadata
status	✅ completed, 5 pages
pages	✅ page dimensions
parse (new)	✅ Transcript, 5/5 pages
render (new)	✅ real Markdown output
delete	✅
upload --single-request (new)	✅ created document
upload (3-step + content_hash_sha256)	✅ File uploaded to S3 → Upload complete (200)

Both upload flows complete, so the content_hash_sha256 fix is confirmed by executing the CLI, not just by contract equivalence. --help was also checked to confirm the API key no longer leaks.

[Nick-Belhovskyi]

@specialistvlad — requesting your review since this is your repo (and your QA report surfaced these).

This PR closes the demo-repo findings from the 2026-05-28 External API QA report:

• S2-01/02/03/05 — the broken upload happy path: all three clients (Go CLI, TS, Python) now send content_hash_sha256 (hex) on completion and x-amz-checksum-sha256 (base64) on the S3 PUT, with the correct inferred Content-Type.
• S2-06 — the Go CLI no longer prints the API key in --help/usage (verified: 0 occurrences with a fake secret).
• S2-07 (--flat registered), S2-09 (.env found from repo root), S2-14 (safe type assertions).
• S2-10/15 notebook fixes; S2-11/13 coverage gaps closed with new parse, render, and --single-request (multipart) — the CLI now exercises every endpoint.
• Both READMEs now describe every endpoint, the corrected 3-step + single-request flows, the RFC 9457 error model, and the server-to-server/no-CORS stance.

Verified end-to-end against a local stack — every command runs green (see the verification comment above). Over to you for the repo-owner review.

[specialistvlad]

LGTM