[High] Publish OpenAPI 3 specification and enforce API contract tests in CI

[robertocarlous]

Labels: priority/high, area/api, documentation, feature

Body:

## Summary
NeuroWealth has a growing REST surface (`/api/auth`, `/api/portfolio`, `/api/deposit`, `/api/vault`, `/api/admin`, etc.) but no machine-readable API contract. This slows frontend development, makes breaking changes likely, and blocks third-party integrations.

## Problem
- No OpenAPI/Swagger spec exists in the repo
- Response shapes vary (`{ error }` vs `{ success, data }` vs nested `transaction`)
- Zod validators exist per-route but are not exported as API documentation
- New contributors must read route files to understand request/response contracts

## User story
**As a** frontend or integrator developer,  
**I want** an accurate OpenAPI document for all public endpoints,  
**so that** I can generate clients, validate payloads, and catch breaking API changes in CI.

## Proposed solution
### Phase 1 — Spec generation
- Add `openapi.yaml` (or `docs/openapi.yaml`) covering:
  - Auth (`/api/auth/challenge`, `/verify`, `/logout`)
  - Portfolio, transactions, deposit, withdraw, vault
  - Health (`/health/live`, `/health/ready`)
  - Public vs authenticated vs admin routes clearly tagged
- Document auth scheme: `Bearer JWT`
- Include standard error schema:
  ```json
  { "error": "string", "details": "optional array/object" }

  ## Acceptance criteria

 OpenAPI 3.1 spec committed and versioned
 All public /api/* routes documented with request/response schemas
 Security schemes documented (Bearer, Admin token, Internal token)
 CI job validates spec syntax and runs contract tests on key endpoints
 README links to API docs and contribution guide for updating spec
 Breaking change policy documented (semver for API surface)

[Senorespecial]

I would like to work on this issue, pls assign

[shadrach68]

I would like to work on this issue because I am a full-stack developer with 5+ years experience. I focus on identifying root causes and delivering clean, efficient, and maintainable solutions, with thorough testing to ensure reliable results.

[Truphile]

Hi there,

I would love to take on this issue! I have thoroughly reviewed the requirements and the problem statement, and I am ready to start working on a clean, production-ready implementation.

If assigned, you can expect:

• A clean architecture implementation that adheres strictly to the project's existing design patterns.
• Proper handling of edge cases, strict validation, and robust error handling.
• Comprehensive unit and integration tests covering all acceptance criteria.

Please assign this issue to me if it is available, and I will get a pull request ready for your review as soon as possible. Thank you!

[Biokes]

Hi maintainer,
I'm a Software Engineer and I'd like to take this issue. I understand the requirements and will follow the existing project structure, keep the implementation clean, and include proper tests where applicable.

[Chucks1093]

I am a solide backend engineer amd can implement this issue confidently. I would like to be assigned to start working on it.

[grantfox-oss]

🦊 GrantFox — @Chucks1093 has been assigned to this issue as part of the Official Campaign campaign!

Next steps:

1. Open a Pull Request referencing this issue (e.g., Closes #165)
2. Your PR will be reviewed by the Neurowealth maintainers

Good luck! Track your progress on GrantFox.

[grantfox-oss]

🎉 This issue has been marked as completed on GrantFox as part of the Official Campaign campaign!

@Chucks1093's PR #207 was approved and merged by @robertocarlous.

🏆 @Chucks1093: You earned 35 FoxPoints for this contribution! Your current tier: Explorer (203 total points). Track your full progress on GrantFox.

👏 Great work, @Chucks1093! Keep contributing to Neurowealth.