Make the public API agent-friendly

[MicrowaveDev]

Make the public API agent-friendly

Implement the roadmap in docs/agent-friendly-api-implementation-plan.md so an
integration starting with only a GeeSome public origin can discover the API,
authenticate with least privilege, publish immutable assets safely, verify
stored bytes, follow asynchronous work, and resume batch publication.

Source of truth

• docs/agent-friendly-api-recommendations.md
• docs/agent-friendly-api-implementation-plan.md

Scope

This issue covers the GeeSome Node public API, gateway response contract,
reverse-proxy discovery routing, asset/operation/batch persistence, generated
OpenAPI, integration examples, and the required repository verification and
inventory updates. Existing content storage and legacy upload routes remain
backward compatible.

Acceptance criteria

• /.well-known/geesome advertises absolute externally reachable URLs,
  versions, capabilities, limits, and storage characteristics through supported
  reverse-proxy topologies.
• New API and gateway failures use stable application/problem+json responses
  with request IDs and documented status/code semantics.
• POST /v1/assets supports raw immutable upload, SHA-256 verification,
  idempotency, deterministic 201/202 responses, and a stable asset schema.
• Immutable GET/HEAD responses expose CID, digest, size, MIME type, ranges,
  request ID, and immutable caching headers.
• Operations expose stable states and remain owner-scoped.
• Integration API keys expose safe scope/expiry/revocation/last-used metadata
  without exposing secrets.
• Resumable asset batches complete without duplicate records and emit a
  deterministic hash-bound manifest.
• OpenAPI and executable examples match the deployed public prefix.
• Security route inventory, API docs, migration integrity, scalability review,
  TODO/implemented docs, and the relevant test suites are updated.

Verification

• Focused API, content, asset, operation, auth, gateway, and batch tests.
• Production-shaped reverse-proxy black-box tests.
• npm run generate-docs
• npm run security:route-inventory:update && npm run security:route-inventory
• Migration/scalability checks for persistence changes.
• npm run test:docker