@cubis/foundry 0.3.10

package/Ai Agent Workflow/skills/oneup-design/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: "oneup-design"
+displayName: "OneUp Design System"
+description: "OneUp HR design system with One* components, colors, spacing, and typography tokens"
+keywords: ["design", "ui", "component", "color", "spacing", "padding", "typography", "OneText", "OneButton", "OneCard", "widget", "theme"]
+---
+
+# OneUp Design System
+
+## Onboarding
+
+Import the design system:
+```dart
+import '../../../../core/design_system/one_design_system.dart';
+```
+
+## When to Load Steering Files
+
+- Working with colors → `colors.md`
+- Working with spacing/padding → `spacing.md`
+- Using One* components → `components.md`
+
+## MCP Tools (Use Before Writing UI)
+
+1. `listComponents` → Find One* component
+2. `getComponentSpec` → Get props/examples
+3. `getDesignTokens` → Get tokens
+4. `validateWidget` → Validate compliance
+
+## Quick Reference
+
+### Colors
+
+```dart
+// Theme-aware
+context.colors.primary
+context.colors.surface
+context.colors.onSurface
+
+// Static
+OneColor.success   // #2DC656
+OneColor.error     // #FF3C35
+OneColor.white
+```
+
+### Spacing
+
+```dart
+OneSpacing.sm   // 8
+OneSpacing.md   // 12
+OneSpacing.lg   // 16
+OneSpacing.xl   // 20
+```
+
+### Padding
+
+```dart
+OnePadding.screenHorizontal  // h: 20
+OnePadding.cardAll           // all: 16
+OnePadding.custom(left: OneSpacing.sm)
+```
+
+### Forbidden Patterns
+
+```dart
+// ❌ Never use
+SizedBox(height: 16)         // Use OneSpacing.lg
+Color(0xFF...)               // Use context.colors.X
+Colors.white                 // Use OneColor.white
+Text(...)                    // Use OneText.X()
+ElevatedButton(...)          // Use OneButton.primary()
+```

package/Ai Agent Workflow/skills/oneup-design/references/colors.md

@@ -0,0 +1,41 @@
+# Color Tokens
+
+## Theme-Aware Colors
+
+Use `context.colors.X` - these adapt to light/dark theme:
+
+| Token | Access | Usage |
+|-------|--------|-------|
+| primary | `context.colors.primary` | Primary actions, buttons, links |
+| onPrimary | `context.colors.onPrimary` | Text/icons on primary |
+| secondary | `context.colors.secondary` | Secondary actions |
+| surface | `context.colors.surface` | Card backgrounds, sheets |
+| onSurface | `context.colors.onSurface` | Primary text |
+| onSurfaceVariant | `context.colors.onSurfaceVariant` | Secondary text, hints |
+| outline | `context.colors.outline` | Borders, dividers |
+| error | `context.colors.error` | Error states |
+
+## Static Colors
+
+Use `OneColor.X` - fixed colors for status:
+
+| Token | Hex | Usage |
+|-------|-----|-------|
+| success | #2DC656 | Success indicators |
+| warning | #FFBF00 | Warning indicators |
+| error | #FF3C35 | Error badges |
+| info | #48AFFA | Info indicators |
+| white | #FFFFFF | White overlays |
+| black | #000000 | Black overlays |
+| disableColor | #70808F | Disabled states |
+
+## Forbidden
+
+```dart
+// ❌ NEVER use these
+Color(0xFF123456);
+Colors.white;
+Colors.black;
+Theme.of(context).colorScheme.primary;
+OneColor.primary;  // Use context.colors.primary instead
+```

package/Ai Agent Workflow/skills/oneup-design/references/components.md

@@ -0,0 +1,53 @@
+# Component Mapping
+
+## Flutter → One* Components
+
+| Flutter Widget | One* Component |
+|----------------|----------------|
+| ElevatedButton | OneButton |
+| TextButton | OneButton.text |
+| OutlinedButton | OneButton.outlined |
+| TextField | OneTextField |
+| Card | OneCard |
+| Text | OneText |
+| CircularProgressIndicator | OneLoading |
+| Checkbox | OneCheckbox |
+| Switch | OneSwitch |
+| Radio | OneRadio |
+| Slider | OneSlider |
+| BottomSheet | OneBottomSheet |
+| Dialog | OneDialog |
+| SnackBar | OneSnackBar |
+| AppBar | OneAppBar |
+| Chip | OneChip |
+| Badge | OneBadge |
+| Avatar | OneAvatar |
+| Divider | OneDivider |
+
+## Usage Examples
+
+```dart
+// ❌ Don't use
+ElevatedButton(
+  onPressed: () {},
+  child: Text('Submit'),
+)
+
+// ✅ Use instead
+OneButton(
+  onPressed: () {},
+  label: 'Submit',
+)
+```
+
+```dart
+// ❌ Don't use
+TextField(
+  decoration: InputDecoration(labelText: 'Email'),
+)
+
+// ✅ Use instead
+OneTextField(
+  label: 'Email',
+)
+```

package/Ai Agent Workflow/skills/oneup-design/references/spacing.md

@@ -0,0 +1,84 @@
+# OneSpacing Tokens
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs4 | 1 | `SizedBox(height: OneSpacing.xs4)` |
+| xs3 | 2 | `SizedBox(height: OneSpacing.xs3)` |
+| xs2 | 4 | `SizedBox(height: OneSpacing.xs2)` |
+| n5 | 5 | `SizedBox(height: OneSpacing.n5)` |
+| xs | 6 | `SizedBox(height: OneSpacing.xs)` |
+| sm | 8 | `SizedBox(height: OneSpacing.sm)` |
+| n10 | 10 | `SizedBox(height: OneSpacing.n10)` |
+| md | 12 | `SizedBox(height: OneSpacing.md)` |
+| lg | 16 | `SizedBox(height: OneSpacing.lg)` |
+| xl | 20 | `SizedBox(height: OneSpacing.xl)` |
+| xl2 | 24 | `SizedBox(height: OneSpacing.xl2)` |
+| n28 | 28 | `SizedBox(height: OneSpacing.n28)` |
+| xl3 | 32 | `SizedBox(height: OneSpacing.xl3)` |
+| xl4 | 40 | `SizedBox(height: OneSpacing.xl4)` |
+| xl5 | 48 | `SizedBox(height: OneSpacing.xl5)` |
+| xl6 | 64 | `SizedBox(height: OneSpacing.xl6)` |
+
+# OnePadding Presets
+
+| Preset | Value | Use Case |
+|--------|-------|----------|
+| screenHorizontal | h: 20 | Screen body padding |
+| screenVertical | v: 20 | Screen vertical |
+| screenAll | all: 20 | Full screen padding |
+| cardAll | all: 16 | Card internal padding |
+| cardHorizontal | h: 16 | Card horizontal |
+| cardVertical | v: 12 | Card vertical |
+| listItem | h: 16, v: 12 | List item padding |
+| button | h: 24, v: 12 | Button internal |
+| formField | bottom: 16 | Form field gap |
+| section | bottom: 24 | Section gap |
+| xs | all: 4 | Extra small |
+| sm | all: 8 | Small |
+| md | all: 12 | Medium |
+| lg | all: 16 | Large |
+| xl | all: 20 | Extra large |
+| xl2 | all: 24 | 2X large |
+| horizontalXs-Xl | h: 4-20 | Horizontal only |
+| verticalXs-Xl | v: 4-20 | Vertical only |
+
+## Custom Padding
+```dart
+OnePadding.custom(left: OneSpacing.sm, bottom: OneSpacing.lg)
+OnePadding.symmetric(horizontal: OneSpacing.lg, vertical: OneSpacing.md)
+OnePadding.only(top: OneSpacing.xl)
+```
+
+# OneRadius Tokens
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs4 | 1 | `BorderRadius.circular(OneRadius.xs4)` |
+| xs | 4 | `BorderRadius.circular(OneRadius.xs)` |
+| sm | 6 | `BorderRadius.circular(OneRadius.sm)` |
+| md | 8 | `BorderRadius.circular(OneRadius.md)` |
+| lg | 12 | `BorderRadius.circular(OneRadius.lg)` |
+| xl | 16 | `BorderRadius.circular(OneRadius.xl)` |
+| xl2 | 20 | `BorderRadius.circular(OneRadius.xl2)` |
+| xl3 | 24 | `BorderRadius.circular(OneRadius.xl3)` |
+| full | 9999 | Pill shape |
+
+## Pre-built BorderRadius
+```dart
+OneRadius.radiusXs   // BorderRadius.circular(4)
+OneRadius.radiusSm   // BorderRadius.circular(6)
+OneRadius.radiusMd   // BorderRadius.circular(8)
+OneRadius.radiusLg   // BorderRadius.circular(12)
+OneRadius.radiusXl   // BorderRadius.circular(16)
+OneRadius.radiusFull // BorderRadius.circular(9999)
+```
+
+# Forbidden Patterns
+
+```dart
+// ❌ NEVER USE RAW VALUES
+SizedBox(height: 16)                    // Use OneSpacing.lg
+EdgeInsets.all(12)                      // Use OnePadding.md
+EdgeInsets.symmetric(horizontal: 20)    // Use OnePadding.screenHorizontal
+BorderRadius.circular(8)                // Use OneRadius.md
+```

package/Ai Agent Workflow/skills/oneup-design/steering/colors.md

@@ -0,0 +1,41 @@
+# Color Tokens
+
+## Theme-Aware Colors
+
+Use `context.colors.X` - these adapt to light/dark theme:
+
+| Token | Access | Usage |
+|-------|--------|-------|
+| primary | `context.colors.primary` | Primary actions, buttons, links |
+| onPrimary | `context.colors.onPrimary` | Text/icons on primary |
+| secondary | `context.colors.secondary` | Secondary actions |
+| surface | `context.colors.surface` | Card backgrounds, sheets |
+| onSurface | `context.colors.onSurface` | Primary text |
+| onSurfaceVariant | `context.colors.onSurfaceVariant` | Secondary text, hints |
+| outline | `context.colors.outline` | Borders, dividers |
+| error | `context.colors.error` | Error states |
+
+## Static Colors
+
+Use `OneColor.X` - fixed colors for status:
+
+| Token | Hex | Usage |
+|-------|-----|-------|
+| success | #2DC656 | Success indicators |
+| warning | #FFBF00 | Warning indicators |
+| error | #FF3C35 | Error badges |
+| info | #48AFFA | Info indicators |
+| white | #FFFFFF | White overlays |
+| black | #000000 | Black overlays |
+| disableColor | #70808F | Disabled states |
+
+## Forbidden
+
+```dart
+// ❌ NEVER use these
+Color(0xFF123456);
+Colors.white;
+Colors.black;
+Theme.of(context).colorScheme.primary;
+OneColor.primary;  // Use context.colors.primary instead
+```

package/Ai Agent Workflow/skills/oneup-design/steering/components.md

@@ -0,0 +1,53 @@
+# Component Mapping
+
+## Flutter → One* Components
+
+| Flutter Widget | One* Component |
+|----------------|----------------|
+| ElevatedButton | OneButton |
+| TextButton | OneButton.text |
+| OutlinedButton | OneButton.outlined |
+| TextField | OneTextField |
+| Card | OneCard |
+| Text | OneText |
+| CircularProgressIndicator | OneLoading |
+| Checkbox | OneCheckbox |
+| Switch | OneSwitch |
+| Radio | OneRadio |
+| Slider | OneSlider |
+| BottomSheet | OneBottomSheet |
+| Dialog | OneDialog |
+| SnackBar | OneSnackBar |
+| AppBar | OneAppBar |
+| Chip | OneChip |
+| Badge | OneBadge |
+| Avatar | OneAvatar |
+| Divider | OneDivider |
+
+## Usage Examples
+
+```dart
+// ❌ Don't use
+ElevatedButton(
+  onPressed: () {},
+  child: Text('Submit'),
+)
+
+// ✅ Use instead
+OneButton(
+  onPressed: () {},
+  label: 'Submit',
+)
+```
+
+```dart
+// ❌ Don't use
+TextField(
+  decoration: InputDecoration(labelText: 'Email'),
+)
+
+// ✅ Use instead
+OneTextField(
+  label: 'Email',
+)
+```

package/Ai Agent Workflow/skills/oneup-design/steering/spacing.md

@@ -0,0 +1,84 @@
+# OneSpacing Tokens
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs4 | 1 | `SizedBox(height: OneSpacing.xs4)` |
+| xs3 | 2 | `SizedBox(height: OneSpacing.xs3)` |
+| xs2 | 4 | `SizedBox(height: OneSpacing.xs2)` |
+| n5 | 5 | `SizedBox(height: OneSpacing.n5)` |
+| xs | 6 | `SizedBox(height: OneSpacing.xs)` |
+| sm | 8 | `SizedBox(height: OneSpacing.sm)` |
+| n10 | 10 | `SizedBox(height: OneSpacing.n10)` |
+| md | 12 | `SizedBox(height: OneSpacing.md)` |
+| lg | 16 | `SizedBox(height: OneSpacing.lg)` |
+| xl | 20 | `SizedBox(height: OneSpacing.xl)` |
+| xl2 | 24 | `SizedBox(height: OneSpacing.xl2)` |
+| n28 | 28 | `SizedBox(height: OneSpacing.n28)` |
+| xl3 | 32 | `SizedBox(height: OneSpacing.xl3)` |
+| xl4 | 40 | `SizedBox(height: OneSpacing.xl4)` |
+| xl5 | 48 | `SizedBox(height: OneSpacing.xl5)` |
+| xl6 | 64 | `SizedBox(height: OneSpacing.xl6)` |
+
+# OnePadding Presets
+
+| Preset | Value | Use Case |
+|--------|-------|----------|
+| screenHorizontal | h: 20 | Screen body padding |
+| screenVertical | v: 20 | Screen vertical |
+| screenAll | all: 20 | Full screen padding |
+| cardAll | all: 16 | Card internal padding |
+| cardHorizontal | h: 16 | Card horizontal |
+| cardVertical | v: 12 | Card vertical |
+| listItem | h: 16, v: 12 | List item padding |
+| button | h: 24, v: 12 | Button internal |
+| formField | bottom: 16 | Form field gap |
+| section | bottom: 24 | Section gap |
+| xs | all: 4 | Extra small |
+| sm | all: 8 | Small |
+| md | all: 12 | Medium |
+| lg | all: 16 | Large |
+| xl | all: 20 | Extra large |
+| xl2 | all: 24 | 2X large |
+| horizontalXs-Xl | h: 4-20 | Horizontal only |
+| verticalXs-Xl | v: 4-20 | Vertical only |
+
+## Custom Padding
+```dart
+OnePadding.custom(left: OneSpacing.sm, bottom: OneSpacing.lg)
+OnePadding.symmetric(horizontal: OneSpacing.lg, vertical: OneSpacing.md)
+OnePadding.only(top: OneSpacing.xl)
+```
+
+# OneRadius Tokens
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs4 | 1 | `BorderRadius.circular(OneRadius.xs4)` |
+| xs | 4 | `BorderRadius.circular(OneRadius.xs)` |
+| sm | 6 | `BorderRadius.circular(OneRadius.sm)` |
+| md | 8 | `BorderRadius.circular(OneRadius.md)` |
+| lg | 12 | `BorderRadius.circular(OneRadius.lg)` |
+| xl | 16 | `BorderRadius.circular(OneRadius.xl)` |
+| xl2 | 20 | `BorderRadius.circular(OneRadius.xl2)` |
+| xl3 | 24 | `BorderRadius.circular(OneRadius.xl3)` |
+| full | 9999 | Pill shape |
+
+## Pre-built BorderRadius
+```dart
+OneRadius.radiusXs   // BorderRadius.circular(4)
+OneRadius.radiusSm   // BorderRadius.circular(6)
+OneRadius.radiusMd   // BorderRadius.circular(8)
+OneRadius.radiusLg   // BorderRadius.circular(12)
+OneRadius.radiusXl   // BorderRadius.circular(16)
+OneRadius.radiusFull // BorderRadius.circular(9999)
+```
+
+# Forbidden Patterns
+
+```dart
+// ❌ NEVER USE RAW VALUES
+SizedBox(height: 16)                    // Use OneSpacing.lg
+EdgeInsets.all(12)                      // Use OnePadding.md
+EdgeInsets.symmetric(horizontal: 20)    // Use OnePadding.screenHorizontal
+BorderRadius.circular(8)                // Use OneRadius.md
+```

package/Ai Agent Workflow/skills/openapi-docs/POWER.md

@@ -0,0 +1,78 @@
+---
+name: openapi-docs
+displayName: OpenAPI Docs & Stoplight UI
+description:
+  Use when writing or updating OpenAPI specifications, defining request/response
+  schemas, or configuring Stoplight Elements (Swagger-style) documentation UI.
+keywords:
+  - openapi
+  - api docs
+  - swagger ui
+  - stoplight
+  - elements
+  - documentation
+author: OneUp
+---
+
+# OpenAPI Docs & Stoplight UI
+
+## Overview
+
+API documentation specialist who produces clean, consistent OpenAPI 3.1 specs and a polished Stoplight Elements UI across frameworks (FastAPI, NestJS, Express, Hono, etc.).
+
+## Role Definition
+
+You are a technical writer and API designer. You standardize request/response schemas, ensure authentication is documented accurately, and keep UI docs consistent with runtime behavior across different stacks.
+
+## When to Use This Skill
+
+- Creating new API endpoints with OpenAPI documentation (FastAPI, NestJS, Express, Hono, raw OpenAPI files)
+- Updating request/response schemas or error contracts
+- Adding or fixing authentication/headers in docs
+- Setting up or refining Stoplight Elements UI
+- Defining CRUD endpoints (create, update, delete)
+
+## Core Workflow
+
+1. **Inventory** - Identify endpoints, auth headers, and response types
+2. **Schemas** - Define reusable schemas and examples
+3. **Operations** - Document create/update/delete with standard responses
+4. **Errors** - Add consistent error responses for all routes
+5. **UI** - Wire Stoplight Elements to the OpenAPI spec
+
+## Available Steering Files
+
+| Topic             | Reference                         | Load When                          |
+| ----------------- | --------------------------------- | ---------------------------------- |
+| OpenAPI Checklist | references/openapi-checklist.md     | Before writing or updating specs   |
+| CRUD Templates    | references/crud-templates.md        | Adding create/update/delete routes |
+| Stoplight UI      | references/stoplight-ui.md          | Configuring or styling docs UI     |
+| FastAPI           | references/framework-fastapi.md     | FastAPI-specific documentation     |
+| NestJS            | references/framework-nestjs.md      | NestJS Swagger integration         |
+| Express           | references/framework-express.md     | Express spec-first or code-first   |
+| Raw OpenAPI       | references/framework-raw-openapi.md | Spec-first workflows               |
+
+## Constraints
+
+### MUST DO
+
+- Ensure headers in docs match actual middleware requirements
+- Reuse schemas via the framework’s component registration mechanism (e.g., FastAPI models, NestJS decorators, Zod/OpenAPI registries)
+- Include examples for request bodies and error payloads
+- Document 4xx and 5xx error responses
+- Keep descriptions concise and user-focused
+
+### MUST NOT DO
+
+- Invent undocumented headers or parameters
+- Drift away from runtime validation rules
+- Document endpoints that don’t exist
+- Use inconsistent casing for headers
+
+## Output Template
+
+1. Summary of changes
+2. Updated schemas and examples
+3. Updated endpoints (create/update/delete)
+4. Stoplight UI status and URL
+5. Verification notes

package/Ai Agent Workflow/skills/openapi-docs/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: "openapi-docs"
+description: "Use when writing or updating OpenAPI specifications, defining request/response schemas, or configuring Stoplight Elements (Swagger-style) documentation UI."
+---
+
+
+# OpenAPI Docs & Stoplight UI
+
+## Overview
+
+API documentation specialist who produces clean, consistent OpenAPI 3.1 specs and a polished Stoplight Elements UI across frameworks (FastAPI, NestJS, Express, Hono, etc.).
+
+## Role Definition
+
+You are a technical writer and API designer. You standardize request/response schemas, ensure authentication is documented accurately, and keep UI docs consistent with runtime behavior across different stacks.
+
+## When to Use This Skill
+
+- Creating new API endpoints with OpenAPI documentation (FastAPI, NestJS, Express, Hono, raw OpenAPI files)
+- Updating request/response schemas or error contracts
+- Adding or fixing authentication/headers in docs
+- Setting up or refining Stoplight Elements UI
+- Defining CRUD endpoints (create, update, delete)
+
+## Core Workflow
+
+1. **Inventory** - Identify endpoints, auth headers, and response types
+2. **Schemas** - Define reusable schemas and examples
+3. **Operations** - Document create/update/delete with standard responses
+4. **Errors** - Add consistent error responses for all routes
+5. **UI** - Wire Stoplight Elements to the OpenAPI spec
+
+## Available Steering Files
+
+| Topic             | Reference                         | Load When                          |
+| ----------------- | --------------------------------- | ---------------------------------- |
+| OpenAPI Checklist | references/openapi-checklist.md     | Before writing or updating specs   |
+| CRUD Templates    | references/crud-templates.md        | Adding create/update/delete routes |
+| Stoplight UI      | references/stoplight-ui.md          | Configuring or styling docs UI     |
+| FastAPI           | references/framework-fastapi.md     | FastAPI-specific documentation     |
+| NestJS            | references/framework-nestjs.md      | NestJS Swagger integration         |
+| Express           | references/framework-express.md     | Express spec-first or code-first   |
+| Raw OpenAPI       | references/framework-raw-openapi.md | Spec-first workflows               |
+
+## Constraints
+
+### MUST DO
+
+- Ensure headers in docs match actual middleware requirements
+- Reuse schemas via the framework’s component registration mechanism (e.g., FastAPI models, NestJS decorators, Zod/OpenAPI registries)
+- Include examples for request bodies and error payloads
+- Document 4xx and 5xx error responses
+- Keep descriptions concise and user-focused
+
+### MUST NOT DO
+
+- Invent undocumented headers or parameters
+- Drift away from runtime validation rules
+- Document endpoints that don’t exist
+- Use inconsistent casing for headers
+
+## Output Template
+
+1. Summary of changes
+2. Updated schemas and examples
+3. Updated endpoints (create/update/delete)
+4. Stoplight UI status and URL
+5. Verification notes

package/Ai Agent Workflow/skills/openapi-docs/references/crud-templates.md

@@ -0,0 +1,43 @@
+# CRUD Templates (Create / Update / Delete)
+
+## Create (POST)
+
+- `summary`: Create <resource>
+- `request.body`:
+  - `application/json` schema with required fields
+  - example payload
+- Responses:
+  - `201` with created resource schema
+  - `400` validation error
+  - `401` missing auth
+  - `403` forbidden
+  - `500` server error
+
+## Update (PUT/PATCH)
+
+- `summary`: Update <resource>
+- `request.params`: `{ id }`
+- `request.body`: optional fields for update
+- Responses:
+  - `200` with updated resource schema
+  - `400` validation error
+  - `401` missing auth
+  - `403` forbidden
+  - `404` not found
+  - `500` server error
+
+## Delete (DELETE)
+
+- `summary`: Delete <resource>
+- `request.params`: `{ id }`
+- Responses:
+  - `204` no content (or `200` with confirmation schema)
+  - `401` missing auth
+  - `403` forbidden
+  - `404` not found
+  - `500` server error
+
+## Notes
+
+- Ensure `request.headers` includes all required auth headers
+- Use shared `ErrorResponse` schema for errors

package/Ai Agent Workflow/skills/openapi-docs/references/framework-express.md

@@ -0,0 +1,19 @@
+# Express OpenAPI Guidance
+
+## Core Patterns
+
+- Maintain a source OpenAPI file (YAML/JSON) or generate via schema tools
+- Validate requests with a middleware (zod, joi, ajv)
+- Ensure validation and docs stay in sync
+
+## Options
+
+- Code-first: Zod/OpenAPI registry or tsoa
+- Spec-first: Handwritten OpenAPI with request validation middleware
+
+## Example Checklist
+
+- Centralize schemas for reuse
+- Add standard error responses across routes
+- Document auth headers explicitly
+- Serve `/openapi.json` and Stoplight UI at `/docs`

package/Ai Agent Workflow/skills/openapi-docs/references/framework-fastapi.md

@@ -0,0 +1,20 @@
+# FastAPI OpenAPI Guidance
+
+## Core Patterns
+
+- Use Pydantic models for request/response schemas
+- Use `response_model` for output typing and docs
+- Use `status_code` on route decorators
+- Use dependency injection for auth headers
+
+## Example Checklist
+
+- Define `BaseModel` for request/response
+- Add examples via `Field(..., example=...)`
+- Document security scheme with `HTTPBearer` or `APIKeyHeader`
+- Add tags on routes for grouping
+
+## Notes
+
+- FastAPI auto-generates OpenAPI 3.1 in recent versions; verify version
+- Use `openapi_url` and `docs_url` to expose spec and UI routes

package/Ai Agent Workflow/skills/openapi-docs/references/framework-nestjs.md

@@ -0,0 +1,20 @@
+# NestJS OpenAPI Guidance
+
+## Core Patterns
+
+- Use `@nestjs/swagger` decorators for schemas and routes
+- Use DTO classes with `@ApiProperty()`
+- Set `@ApiTags()` per controller
+- Use `@ApiBearerAuth()` or `@ApiSecurity()` for API keys
+
+## Example Checklist
+
+- Create DTOs for create/update responses
+- Add `@ApiResponse()` for 200/201/400/401/403/404/500
+- Use `@ApiHeader()` for required headers
+- Generate spec via `SwaggerModule.createDocument()`
+
+## Notes
+
+- Keep DTO validation (class-validator) aligned with docs
+- Export `/openapi.json` and mount UI (Stoplight or Swagger)