Adopt OpenAPI-first for agentic-flows docs pipeline

Scope

• ✅ Add openapi/openapi.yaml (DONE)
• ✅ Add codegen scripts (openapi-typescript, @redocly/cli) (DONE)
• ✅ Generated types used in services via src/generated/ (DONE)
• ⏳ Verify npm run build auto-runs codegen and succeeds

Done When

• openapi/openapi.yaml created (single source of truth)
• Codegen dependencies installed
• Prebuild script runs npm run generate
• Zod schemas aligned with OpenAPI spec
• JSDoc links schemas to generated types
• npm run build succeeds end-to-end

Architecture Achieved

✅ OpenAPI-first: Spec drives everything
✅ DRY: Single source of truth for types
✅ Type-safe: Generated types + Zod validation
✅ SOLID: Services use generated types via dependency injection

Next Steps

Verify build pipeline works end-to-end with codegen → tsc → success.