@cubis/foundry 0.3.67 → 0.3.68

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/code-documenter/references/api-docs-nestjs-express.md

@@ -1,223 +0,0 @@
-# API Documentation: NestJS & Express
-
-> Reference for: Code Documenter
-> Load when: Documenting Node.js API frameworks
-
-## NestJS (@nestjs/swagger)
-
-NestJS requires explicit decorators for OpenAPI documentation.
-
-### Controller Documentation
-
-```typescript
-import { Controller, Post, Body, Get, Param } from '@nestjs/common';
-import {
-  ApiTags,
-  ApiOperation,
-  ApiResponse,
-  ApiParam,
-  ApiBearerAuth,
-} from '@nestjs/swagger';
-
-@ApiTags('Users')
-@ApiBearerAuth()
-@Controller('users')
-export class UsersController {
-  @Post()
-  @ApiOperation({ summary: 'Create a new user' })
-  @ApiResponse({
-    status: 201,
-    description: 'User created successfully',
-    type: UserDto,
-  })
-  @ApiResponse({
-    status: 400,
-    description: 'Invalid input data',
-  })
-  async create(@Body() dto: CreateUserDto): Promise<UserDto> {
-    return this.usersService.create(dto);
-  }
-
-  @Get(':id')
-  @ApiOperation({ summary: 'Get user by ID' })
-  @ApiParam({
-    name: 'id',
-    description: 'User unique identifier',
-    example: '123',
-  })
-  @ApiResponse({ status: 200, type: UserDto })
-  @ApiResponse({ status: 404, description: 'User not found' })
-  async findOne(@Param('id') id: string): Promise<UserDto> {
-    return this.usersService.findOne(id);
-  }
-}
-```
-
-### DTO Documentation
-
-```typescript
-import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
-import { IsEmail, IsString, MinLength } from 'class-validator';
-
-export class CreateUserDto {
-  @ApiProperty({
-    description: "User's display name",
-    example: 'John Doe',
-    minLength: 1,
-    maxLength: 100,
-  })
-  @IsString()
-  @MinLength(1)
-  name: string;
-
-  @ApiProperty({
-    description: "User's email address",
-    example: 'john@example.com',
-  })
-  @IsEmail()
-  email: string;
-
-  @ApiPropertyOptional({
-    description: 'Profile picture URL',
-    example: 'https://example.com/avatar.jpg',
-  })
-  avatarUrl?: string;
-}
-```
-
-## Express (swagger-jsdoc)
-
-Express uses JSDoc comments with swagger annotations.
-
-### Setup
-
-```javascript
-const swaggerJsdoc = require('swagger-jsdoc');
-const swaggerUi = require('swagger-ui-express');
-
-const options = {
-  definition: {
-    openapi: '3.0.0',
-    info: {
-      title: 'API Documentation',
-      version: '1.0.0',
-    },
-  },
-  apis: ['./routes/*.js'],
-};
-
-const specs = swaggerJsdoc(options);
-app.use('/api-docs', swaggerUi.serve, swaggerUi.setup(specs));
-```
-
-### Route Documentation
-
-```javascript
-/**
- * @swagger
- * /users:
- *   post:
- *     summary: Create a new user
- *     tags: [Users]
- *     requestBody:
- *       required: true
- *       content:
- *         application/json:
- *           schema:
- *             $ref: '#/components/schemas/CreateUser'
- *     responses:
- *       201:
- *         description: User created successfully
- *         content:
- *           application/json:
- *             schema:
- *               $ref: '#/components/schemas/User'
- *       400:
- *         description: Invalid input
- */
-router.post('/users', createUser);
-
-/**
- * @swagger
- * /users/{id}:
- *   get:
- *     summary: Get user by ID
- *     tags: [Users]
- *     parameters:
- *       - in: path
- *         name: id
- *         required: true
- *         schema:
- *           type: string
- *         description: User ID
- *     responses:
- *       200:
- *         description: User found
- *         content:
- *           application/json:
- *             schema:
- *               $ref: '#/components/schemas/User'
- *       404:
- *         description: User not found
- */
-router.get('/users/:id', getUser);
-```
-
-### Schema Documentation
-
-```javascript
-/**
- * @swagger
- * components:
- *   schemas:
- *     CreateUser:
- *       type: object
- *       required:
- *         - name
- *         - email
- *       properties:
- *         name:
- *           type: string
- *           description: User's display name
- *           example: John Doe
- *         email:
- *           type: string
- *           format: email
- *           description: User's email address
- *           example: john@example.com
- *     User:
- *       allOf:
- *         - $ref: '#/components/schemas/CreateUser'
- *         - type: object
- *           properties:
- *             id:
- *               type: string
- *               description: Unique identifier
- *             createdAt:
- *               type: string
- *               format: date-time
- */
-```
-
-## Quick Reference
-
-| NestJS Decorator | Purpose |
-|------------------|---------|
-| `@ApiTags()` | Group endpoints |
-| `@ApiOperation()` | Endpoint summary |
-| `@ApiResponse()` | Response documentation |
-| `@ApiParam()` | Path parameter |
-| `@ApiQuery()` | Query parameter |
-| `@ApiBody()` | Request body |
-| `@ApiBearerAuth()` | Auth requirement |
-| `@ApiProperty()` | DTO property |
-
-| Express swagger-jsdoc | Purpose |
-|-----------------------|---------|
-| `@swagger` | Start swagger block |
-| `tags` | Group endpoints |
-| `summary` | Short description |
-| `parameters` | Path/query params |
-| `requestBody` | Request body schema |
-| `responses` | Response schemas |
-| `$ref` | Reference schema |

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/code-documenter/references/coverage-reports.md

@@ -1,128 +0,0 @@
-# Coverage Reports
-
-> Reference for: Code Documenter
-> Load when: Generating documentation reports
-
-## Documentation Coverage Report Template
-
-```markdown
-# Documentation Report: {project_name}
-
-## Summary
-- **Files analyzed**: 45
-- **Functions documented**: 120/150 (80%)
-- **Classes documented**: 25/25 (100%)
-- **API endpoints documented**: 30/30 (100%)
-
-## Coverage Before/After
-- Before: 45%
-- After: 92%
-
-## Files Modified
-
-| File | Functions Added | Notes |
-|------|-----------------|-------|
-| src/services/user.ts | 8 | All public methods |
-| src/services/auth.ts | 5 | Added examples |
-| src/controllers/users.ts | 6 | Added @Api decorators |
-| src/dto/user.dto.ts | 4 | Added @ApiProperty |
-
-## API Documentation
-
-- **Framework**: NestJS
-- **Strategy**: @nestjs/swagger decorators
-- **Swagger UI**: /api/docs
-- **OpenAPI spec**: /api-json
-
-## Documentation Style
-
-- **Python**: Google style docstrings
-- **TypeScript**: JSDoc with @param, @returns
-- **API**: OpenAPI 3.0 via decorators
-
-## Next Steps
-
-### Recommendations
-1. Run `npm run docs:lint` to validate JSDoc
-2. Add `eslint-plugin-jsdoc` to enforce documentation
-3. Consider adding examples for complex functions
-4. Set up documentation CI checks
-
-### Missing Documentation
-| File | Missing | Priority |
-|------|---------|----------|
-| src/utils/crypto.ts | 3 functions | High |
-| src/helpers/date.ts | 2 functions | Medium |
-
-### CI Integration
-```yaml
-# Add to CI pipeline
-- name: Check documentation
-  run: npm run docs:check
-
-- name: Generate API docs
-  run: npm run docs:generate
-```
-```
-
-## Checklist During Documentation
-
-```markdown
-## Documentation Checklist
-
-### Before Starting
-- [ ] Confirmed format preference (Google/JSDoc/etc.)
-- [ ] Identified files to exclude (tests, generated)
-- [ ] Detected framework for API docs
-
-### Functions/Methods
-- [ ] All public functions documented
-- [ ] Parameters described with types
-- [ ] Return values documented
-- [ ] Exceptions/errors documented
-- [ ] Examples added for complex functions
-
-### Classes
-- [ ] Class purpose described
-- [ ] Constructor parameters documented
-- [ ] Public methods documented
-- [ ] Important attributes explained
-
-### API Endpoints
-- [ ] All endpoints have summaries
-- [ ] Request bodies documented
-- [ ] Response schemas defined
-- [ ] Error responses documented
-- [ ] Authentication requirements noted
-
-### Final Checks
-- [ ] Ran documentation linter
-- [ ] Verified Swagger UI renders correctly
-- [ ] No inaccurate documentation
-- [ ] Coverage report generated
-```
-
-## Framework-Specific Linting
-
-```bash
-# JavaScript/TypeScript - ESLint
-npm install eslint-plugin-jsdoc --save-dev
-# Add to .eslintrc: "plugins": ["jsdoc"]
-
-# Python - pydocstyle
-pip install pydocstyle
-pydocstyle --convention=google src/
-
-# Python - interrogate (coverage)
-pip install interrogate
-interrogate -v src/
-```
-
-## Quick Reference
-
-| Metric | Good | Acceptable | Poor |
-|--------|------|------------|------|
-| Function coverage | >90% | 70-90% | <70% |
-| Class coverage | 100% | >90% | <90% |
-| API endpoint coverage | 100% | 100% | <100% |
-| Example coverage | >50% | 30-50% | <30% |

package/workflows/workflows/agent-environment-setup/platforms/cursor/skills/code-documenter/references/documentation-systems.md

@@ -1,336 +0,0 @@
-# Documentation Systems & Infrastructure
-
-> Reference for: Code Documenter
-> Load when: Building documentation sites, static generators, multi-version docs, search systems
-
-## Static Site Generators
-
-### Docusaurus (Meta)
-
-```bash
-# Setup
-npx create-docusaurus@latest docs classic
-cd docs && npm start
-
-# Structure
-docs/
-├── docs/           # Documentation pages
-├── blog/           # Blog posts
-├── src/
-│   └── pages/      # Custom pages
-└── docusaurus.config.js
-```
-
-**docusaurus.config.js:**
-```javascript
-module.exports = {
-  title: 'My API',
-  tagline: 'Build amazing things',
-  url: 'https://docs.example.com',
-  baseUrl: '/',
-
-  themeConfig: {
-    navbar: {
-      items: [
-        {to: '/docs/intro', label: 'Docs', position: 'left'},
-        {to: '/api', label: 'API', position: 'left'},
-      ],
-    },
-
-    // Algolia search
-    algolia: {
-      apiKey: 'YOUR_API_KEY',
-      indexName: 'your_index',
-      contextualSearch: true,
-    },
-
-    prism: {
-      theme: lightCodeTheme,
-      darkTheme: darkCodeTheme,
-      additionalLanguages: ['python', 'rust'],
-    },
-  },
-};
-```
-
-### MkDocs (Python)
-
-```yaml
-# mkdocs.yml
-site_name: My API Documentation
-theme:
-  name: material
-  features:
-    - navigation.tabs
-    - navigation.sections
-    - toc.integrate
-    - search.suggest
-    - search.highlight
-  palette:
-    - scheme: default
-      toggle:
-        icon: material/brightness-7
-        name: Switch to dark mode
-    - scheme: slate
-      toggle:
-        icon: material/brightness-4
-        name: Switch to light mode
-
-plugins:
-  - search
-  - mkdocstrings:
-      handlers:
-        python:
-          options:
-            show_source: true
-  - git-revision-date-localized
-
-markdown_extensions:
-  - pymdownx.highlight
-  - pymdownx.superfences
-  - admonition
-  - codehilite
-
-nav:
-  - Home: index.md
-  - Getting Started: getting-started.md
-  - API Reference: api/
-```
-
-### VitePress (Vue)
-
-```typescript
-// .vitepress/config.ts
-export default defineConfig({
-  title: 'API Docs',
-  description: 'Developer documentation',
-
-  themeConfig: {
-    nav: [
-      { text: 'Guide', link: '/guide/' },
-      { text: 'API', link: '/api/' },
-    ],
-
-    sidebar: {
-      '/guide/': [
-        {
-          text: 'Introduction',
-          items: [
-            { text: 'Getting Started', link: '/guide/getting-started' },
-            { text: 'Configuration', link: '/guide/config' },
-          ],
-        },
-      ],
-    },
-
-    search: {
-      provider: 'local',
-    },
-
-    editLink: {
-      pattern: 'https://github.com/user/repo/edit/main/docs/:path',
-    },
-  },
-});
-```
-
-## Multi-Version Documentation
-
-### Version Switcher
-
-```javascript
-// Docusaurus versions
-{
-  versions: {
-    current: {
-      label: '2.0 (Next)',
-      path: 'next',
-    },
-  },
-  onlyIncludeVersions: ['current', '1.5', '1.4'],
-}
-```
-
-### Migration Guides
-
-```markdown
-# Migration Guide: v1 to v2
-
-## Breaking Changes
-
-### Authentication
-**v1:**
-```python
-client.authenticate(api_key)
-```
-
-**v2:**
-```python
-client = Client(api_key=api_key)  # Pass in constructor
-```
-
-### Renamed Methods
-| v1 | v2 | Notes |
-|----|----|----- |
-| `get_user()` | `fetch_user()` | Async now |
-| `delete_user()` | `remove_user()` | Returns Promise |
-
-## Deprecation Timeline
-- v1.x: Supported until Dec 2025
-- v2.0: Released Jan 2025
-- v2.1: Current (June 2025)
-```
-
-## Search Implementation
-
-### Algolia DocSearch
-
-```html
-<!-- Add to theme -->
-<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@docsearch/css@3" />
-
-<script src="https://cdn.jsdelivr.net/npm/@docsearch/js@3"></script>
-<script>
-  docsearch({
-    appId: 'YOUR_APP_ID',
-    apiKey: 'YOUR_API_KEY',
-    indexName: 'your_index',
-    container: '#docsearch',
-  });
-</script>
-```
-
-### Local Search (Lunr.js)
-
-```javascript
-const idx = lunr(function() {
-  this.ref('id');
-  this.field('title', { boost: 10 });
-  this.field('content');
-
-  documents.forEach(doc => this.add(doc));
-});
-
-// Search
-const results = idx.search('authentication');
-```
-
-## Documentation Testing
-
-### Link Checking
-
-```bash
-# linkcheck (Python)
-pip install linkchecker
-linkchecker http://localhost:3000/docs
-
-# broken-link-checker (Node)
-npm install -g broken-link-checker
-blc http://localhost:3000 -ro
-```
-
-### Code Example Testing
-
-```python
-# doctest for Python examples
-"""
->>> add(2, 3)
-5
->>> add(-1, 1)
-0
-"""
-
-# Run tests
-python -m doctest -v docs/*.md
-```
-
-```javascript
-// Jest for TypeScript examples
-// Extract code blocks and test
-import { runExamples } from './test-docs';
-
-test('API examples work', async () => {
-  const examples = extractExamples('./docs/api.md');
-  await expect(runExamples(examples)).resolves.toBeTruthy();
-});
-```
-
-## Performance Optimization
-
-### Build Optimization
-
-```javascript
-// Webpack/Vite config
-export default {
-  build: {
-    rollupOptions: {
-      output: {
-        manualChunks: {
-          'vendor': ['react', 'react-dom'],
-        },
-      },
-    },
-  },
-
-  optimizeDeps: {
-    include: ['prismjs'],
-  },
-};
-```
-
-### CDN & Caching
-
-```nginx
-# nginx.conf
-location /docs {
-  expires 1y;
-  add_header Cache-Control "public, immutable";
-}
-
-location ~* \.(html)$ {
-  expires 1h;
-  add_header Cache-Control "public, must-revalidate";
-}
-```
-
-## Analytics Integration
-
-### Google Analytics
-
-```javascript
-// Docusaurus
-gtag: {
-  trackingID: 'G-XXXXXXXXXX',
-  anonymizeIP: true,
-},
-```
-
-### Custom Analytics
-
-```javascript
-// Track search queries
-function trackSearch(query, results) {
-  analytics.track('docs_search', {
-    query,
-    resultCount: results.length,
-    timestamp: new Date(),
-  });
-}
-```
-
-## Quick Reference
-
-| Tool | Best For | Tech Stack |
-|------|----------|-----------|
-| Docusaurus | React projects, versioning | React, MDX |
-| MkDocs | Python projects, simple setup | Python, Jinja2 |
-| VitePress | Vue projects, fast builds | Vue, Vite |
-| Nextra | Next.js integration | React, Next.js |
-| Mintlify | Modern UI, AI search | React |
-
-| Search Solution | Cost | Features |
-|----------------|------|----------|
-| Algolia DocSearch | Free (OSS) | Fast, typo-tolerant |
-| Local (Lunr.js) | Free | Offline, no server |
-| Typesense | Free (self-host) | Privacy-focused |
-| Meilisearch | Free (self-host) | Fast, relevance |