@cubis/foundry 0.3.31 → 0.3.33

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/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/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/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/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/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/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/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/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/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/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/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/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/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)

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/openapi-docs/references/framework-raw-openapi.md

@@ -0,0 +1,14 @@
+# Raw OpenAPI (Spec-First) Guidance
+
+## Core Patterns
+
+- Keep a single `openapi.yaml` or `openapi.json`
+- Reuse components for schemas and security
+- Validate requests using an OpenAPI-aware validator
+
+## Example Checklist
+
+- Define tags and operationIds for all endpoints
+- Use consistent error schema across operations
+- Add examples for request/response bodies
+- Expose spec and Stoplight UI endpoints

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/openapi-docs/references/openapi-checklist.md

@@ -0,0 +1,33 @@
+# OpenAPI Checklist (3.1)
+
+## Spec Metadata
+
+- `openapi: 3.1.0`
+- `info`: title, version, description, contact
+- `servers`: local + staging/prod when available
+- `tags`: used by all documented routes
+
+## Security & Headers
+
+- Add `components.securitySchemes` for auth headers
+- Use `security` at global or route level
+- All required headers appear in `request.headers`
+- Header keys are lowercase
+
+## Schemas
+
+- Use the framework’s component registration mechanism (FastAPI Pydantic models, NestJS `@ApiProperty`, Express+zod/openapi registry, etc.)
+- Provide examples for request/response schemas
+- Prefer shared schemas for errors
+
+## Operations
+
+- `summary` and `description` on every operation
+- Responses: `200/201`, plus `400/401/403/404/500` as appropriate
+- `request.body.required: true` if Content-Type is mandatory
+
+## Consistency
+
+- Types and descriptions match actual validation
+- IDs and formats align with persistence (UUID vs ObjectId)
+- No unused tags or components

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/openapi-docs/references/stoplight-ui.md

@@ -0,0 +1,21 @@
+# Stoplight Elements UI
+
+## Standard Setup (Web Component)
+
+- Include:
+  - `https://unpkg.com/@stoplight/elements/styles.min.css`
+  - `https://unpkg.com/@stoplight/elements/web-components.min.js`
+- Embed:
+  - `<elements-api apiDescriptionUrl="/openapi.json" router="hash" layout="sidebar" />`
+
+## Recommended Options
+
+- `router="hash"` for static hosting
+- `layout="sidebar"` for readable nav
+- `tryItCredentialsPolicy="include"` when auth cookies or credentials are needed
+
+## Verification
+
+- UI loads and shows all tags
+- Try-it panel works for secured endpoints
+- Schemas and examples render correctly

package/workflows/workflows/agent-environment-setup/platforms/windsurf/skills/postman/references/steering.md

@@ -0,0 +1,26 @@
+---
+inclusion: always
+---
+
+# Generate APIs from a Collection
+- A Collection ID is required
+- Also get the workspace ID and the local environment ID. Save all the IDs in a .postman.json file. Create it if it doesn't exist.
+- Generate sample data for the APIs
+- Do not generate additional pages or documentation
+- Do not attempt to run the server after generations
+
+# Create a workspace and collection from the API
+- Read the code of the API
+- Create a workspace
+- Create a collection. Add tests as post-request scripts to all request items in the collection
+- Create a local environment
+- Save all the IDs in a .postman.json file. Create it if it doesn't exist.
+
+# Test/Run Collections
+- You are not allowed to use curl or any other API clients except Postman.
+- A Collection ID is required
+- Read the .postman.json file if it exists.
+- Use the environment for local testing if it exists. An Environment ID is required
+- The server must be running first
+- After running, display a summary of the results and a breakdown by endpoint
+- If any endpoint is failing, offer to investigate and fix the error