feat: publish OpenAPI 3.1 spec and add CI contract validation

[Chucks1093]

Closes #165

What was implemented

docs/openapi.yaml — OpenAPI 3.1 specification

A complete machine-readable API contract covering all route groups mentioned in the issue:

Tag	Endpoints documented
health	GET /health, GET /health/ready
auth	GET /api/auth/challenge, POST /api/auth/verify, POST /api/auth/logout
portfolio	GET /api/portfolio, POST /api/portfolio/query (NLP)
transactions	GET /api/transactions (paginated, filterable by type)
deposit	POST /api/deposit
withdraw	POST /api/withdraw
vault	GET /api/vault, POST /api/vault/deposit, POST /api/vault/withdraw
admin	GET /api/admin/users, GET /api/admin/stats

All three security schemes are documented:

• BearerAuth — JWT from /api/auth/verify, used on all authenticated routes
• AdminToken — X-Admin-Token header for /api/admin/*
• InternalToken — X-Internal-Token for service-to-service calls

Reusable schemas are defined for ErrorResponse, Portfolio, Position, Transaction, VaultPosition, AuthChallengeResponse, AuthVerifyRequest/Response, and HealthResponse. Amount fields use string type throughout to avoid IEEE 754 precision loss on financial values.

.github/workflows/api-contract.yml — CI enforcement

Two-job pipeline that runs on any PR touching docs/openapi.yaml or src/routes/**:

1. validate-spec — installs @redocly/cli, runs redocly lint (catches schema errors, missing $ref targets, broken rules), then redocly bundle to verify all references resolve.
2. contract-tests — builds and starts the server, then runs smoke tests:
   • Confirms GET /health returns HTTP 200
   • Validates the response body contains all required fields (status, timestamp, version, environment)
   • Confirms protected routes (/api/portfolio, /api/transactions, /api/vault) return 401 when called without a token

README.md — API documentation entry point

Added a root README with:

• Route/auth reference table linking to the spec
• npx @redocly/cli preview-docs docs/openapi.yaml command for local rendering
• Contribution guide: update the spec in the same PR as route changes
• Breaking-change policy: semver, two-week notice window