blockmine 1.21.0 → 1.22.0

package/.claude/skills/documentation-as-code/SKILL.md

@@ -0,0 +1,323 @@
+# Documentation as Code
+
+Comprehensive guide to technical writing, docs-as-code practices, API documentation, diagram generation, and documentation automation.
+
+## Purpose
+
+Enable teams to create, maintain, and publish high-quality technical documentation using version control, code review, and CI/CD practices.
+
+## When to Use This Skill
+
+Automatically activates when working on:
+- README files and project documentation
+- API documentation (OpenAPI/Swagger)
+- Architecture diagrams (PlantUML, Mermaid)
+- Documentation sites (Docusaurus, MkDocs)
+- Technical writing and style guides
+- Documentation automation and testing
+- Changelog management
+- Developer onboarding docs
+
+## Quick Start Checklist
+
+When creating documentation:
+
+- [ ] Write in Markdown (version-controllable)
+- [ ] Use clear, concise language
+- [ ] Include code examples
+- [ ] Add diagrams where helpful
+- [ ] Set up docs-as-code workflow (Git + CI/CD)
+- [ ] Enable automated link checking
+- [ ] Configure spell checking
+- [ ] Create table of contents
+- [ ] Test code examples
+- [ ] Set up documentation site (if needed)
+
+## Core Concepts
+
+### Docs-as-Code Philosophy
+
+**Treat documentation like code:**
+```
+Version Control → Git (PRs, reviews, history)
+Review Process → Pull requests with feedback
+CI/CD → Build, test, deploy automatically
+Testing → Link checking, spell checking, code validation
+Publishing → Automated deployment to docs site
+```
+
+### Documentation Types
+
+```
+README: Project overview, quick start
+API Docs: REST, GraphQL endpoint documentation
+Architecture: System design, diagrams, ADRs
+Runbooks: Operational procedures
+Guides: How-to tutorials, best practices
+Reference: API reference, configuration options
+Changelog: Version history, release notes
+```
+
+## Common Patterns
+
+### Pattern 1: Project README Structure
+
+```markdown
+# Project Name
+
+Brief description (1-2 sentences)
+
+## Features
+
+- Feature 1
+- Feature 2
+- Feature 3
+
+## Quick Start
+
+```bash
+npm install
+npm run dev
+```
+
+## Documentation
+
+- [API Reference](docs/api.md)
+- [Architecture](docs/architecture.md)
+- [Contributing](CONTRIBUTING.md)
+
+## Installation
+
+Detailed installation instructions
+
+## Usage
+
+Code examples
+
+## Configuration
+
+Environment variables, config files
+
+## Contributing
+
+How to contribute
+
+## License
+
+MIT
+```
+
+---
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+🎯 SKILL ACTIVATED: documentation-as-code
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+
+### Pattern 2: API Documentation (OpenAPI)
+
+```yaml
+# openapi.yaml
+openapi: 3.0.0
+info:
+  title: User API
+  version: 1.0.0
+
+paths:
+  /users:
+    get:
+      summary: List all users
+      parameters:
+        - name: page
+          in: query
+          schema:
+            type: integer
+      responses:
+        '200':
+          description: Successful response
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/User'
+
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        name:
+          type: string
+        email:
+          type: string
+```
+
+---
+
+### Pattern 3: Diagrams as Code
+
+```
+PlantUML:
+@startuml
+User -> API: Request
+API -> Database: Query
+Database -> API: Result
+API -> User: Response
+@enduml
+
+Mermaid:
+```mermaid
+graph LR
+  A[User] --> B[API Gateway]
+  B --> C[Service 1]
+  B --> D[Service 2]
+```
+```
+
+## Resource Files
+
+For detailed guidance on specific topics, see:
+
+### Technical Writing
+- **[technical-writing-guide.md](resources/technical-writing-guide.md)** - Structure, clarity, examples, audience targeting, style guidelines
+- **[markdown-best-practices.md](resources/markdown-best-practices.md)** - GFM, formatting, linking, images, tables, code blocks
+
+### API Documentation
+- **[api-documentation.md](resources/api-documentation.md)** - OpenAPI/Swagger, REST docs, GraphQL docs, API design documentation
+- **[openapi-specification.md](resources/openapi-specification.md)** - OpenAPI 3.0 spec, schemas, paths, components, examples
+
+### Diagrams & Visualization
+- **[diagram-generation.md](resources/diagram-generation.md)** - PlantUML, Mermaid, diagrams.net, C4 model, architecture diagrams
+- **[documentation-sites.md](resources/documentation-sites.md)** - Docusaurus, MkDocs, GitBook, VuePress, Astro Starlight
+
+### Automation & Testing
+- **[documentation-automation.md](resources/documentation-automation.md)** - Auto-generation, linting, link checking, CI/CD pipelines
+- **[readme-engineering.md](resources/readme-engineering.md)** - Project READMEs, structure, badges, quick starts, examples
+
+### Version Control
+- **[changelog-management.md](resources/changelog-management.md)** - Keep a Changelog, semantic versioning, release notes, automation
+- **[docs-as-code-workflow.md](resources/docs-as-code-workflow.md)** - Git workflow, PR reviews, versioning, deployment strategies
+
+## Best Practices
+
+### 1. Write for Your Audience
+
+**Developer documentation:**
+- Technical, concise
+- Code examples
+- API references
+
+**User documentation:**
+- Less technical
+- Step-by-step guides
+- Screenshots
+
+### 2. Show, Don't Just Tell
+
+```markdown
+# ❌ Bad
+The API returns user data.
+
+# ✅ Good
+The API returns user data in JSON format:
+
+```json
+{
+  "id": "123",
+  "name": "John Doe",
+  "email": "john@example.com"
+}
+```
+```
+
+### 3. Keep It Up to Date
+
+- Documentation updates in same PR as code changes
+- Automated link checking
+- Regular documentation reviews
+- Mark deprecated features clearly
+
+### 4. Use Version Control
+
+- All docs in Git
+- Pull request reviews
+- Track changes over time
+- Easy rollback if needed
+
+### 5. Automate Everything
+
+- Build docs automatically (CI/CD)
+- Check links (broken link detection)
+- Spell check
+- Deploy on merge to main
+
+### 6. Make It Searchable
+
+- Use docs site with search (Algolia, etc.)
+- Clear headings and structure
+- Table of contents
+- Good SEO (if public)
+
+## Anti-Patterns to Avoid
+
+❌ Documentation in Word/Google Docs (not version controlled)
+❌ Outdated code examples
+❌ No diagrams (hard to understand architecture)
+❌ Inconsistent formatting
+❌ No table of contents (large docs)
+❌ Broken links (not tested)
+❌ Jargon without explanation
+❌ Missing quick start guide
+
+## Common Tasks
+
+### Task: Create OpenAPI Documentation
+
+1. Define API spec in `openapi.yaml`
+2. Add schemas, paths, responses
+3. Generate docs with Swagger UI or Redoc
+4. Host on docs site
+5. Keep in sync with code (codegen or validation)
+
+### Task: Set Up Documentation Site
+
+1. Choose tool (Docusaurus, MkDocs, etc.)
+2. Initialize site structure
+3. Write documentation in Markdown
+4. Configure navigation/sidebar
+5. Set up CI/CD (deploy on push to main)
+6. Add search (Algolia)
+
+### Task: Generate Architecture Diagram
+
+1. Choose tool (PlantUML, Mermaid, draw.io)
+2. Create diagram as code
+3. Commit to Git (version controlled)
+4. Auto-generate PNG/SVG in CI
+5. Embed in documentation
+
+## Integration Points
+
+This skill integrates with:
+- **skill-developer**: Documenting skills
+- **backend-dev-guidelines**: API documentation
+- **frontend-dev-guidelines**: Component documentation
+- **infrastructure-architecture**: Architecture diagrams and docs
+- All skills: Every project needs documentation
+
+## Triggers and Activation
+
+This skill activates when you:
+- Edit README or .md files
+- Work with OpenAPI/Swagger specs
+- Create architecture diagrams
+- Set up documentation sites
+- Write technical content
+
+---
+
+**Total Resources:** 10 detailed guides covering all aspects of documentation as code
+**Focus:** Version control, automation, API docs, diagrams, technical writing
+**Maintained by:** Documentation team based on industry best practices

package/.claude/skills/documentation-as-code/resources/api-documentation.md

@@ -0,0 +1,90 @@
+# API Documentation
+
+Guide to documenting REST APIs, GraphQL APIs, and generating interactive API documentation using OpenAPI/Swagger.
+
+## REST API Documentation Template
+
+```markdown
+## POST /api/users
+
+Create a new user account.
+
+### Authentication
+Requires API key:
+```
+Authorization: Bearer <token>
+```
+
+### Request
+```json
+{
+  "email": "user@example.com",
+  "name": "John Doe"
+}
+```
+
+### Response (201)
+```json
+{
+  "id": "usr_123",
+  "email": "user@example.com",
+  "name": "John Doe"
+}
+```
+
+### Errors
+- 400: Invalid input
+- 401: Unauthorized
+- 409: Email exists
+```
+
+## OpenAPI Example
+
+```yaml
+openapi: 3.0.0
+info:
+  title: API
+  version: 1.0.0
+
+paths:
+  /users:
+    post:
+      summary: Create user
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/UserInput'
+      responses:
+        '201':
+          description: Created
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+
+components:
+  schemas:
+    User:
+      type: object
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+```
+
+## Best Practices
+
+✅ Complete request/response examples
+✅ Document all error codes
+✅ Show authentication requirements
+✅ Include curl examples
+✅ Keep spec synced with code
+✅ Use Swagger UI for interactive docs
+
+---
+
+**Related Resources:**
+- openapi-specification.md - Complete OpenAPI guide
+- technical-writing-guide.md - Writing style

package/.claude/skills/documentation-as-code/resources/changelog-management.md

@@ -0,0 +1,79 @@
+# Changelog Management
+
+Guide to maintaining changelogs following Keep a Changelog format.
+
+## Keep a Changelog Format
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+### Added
+- New feature X
+
+### Changed
+- Updated feature Y
+
+### Fixed
+- Bug fix Z
+
+## [1.2.0] - 2024-01-15
+
+### Added
+- API endpoint for user management
+- JWT authentication
+
+### Changed
+- Improved error handling
+
+### Deprecated
+- Old authentication method (use JWT)
+
+### Removed
+- Support for Node.js 14
+
+### Fixed
+- Memory leak in worker process
+
+### Security
+- Updated dependencies to fix CVE-2024-0001
+
+## [1.1.0] - 2023-12-01
+...
+
+## [1.0.0] - 2023-11-01
+- Initial release
+```
+
+## Semantic Versioning
+
+```
+MAJOR.MINOR.PATCH
+
+MAJOR: Breaking changes
+MINOR: New features (backward-compatible)
+PATCH: Bug fixes (backward-compatible)
+
+Examples:
+1.0.0 → 1.0.1: Bug fix
+1.0.1 → 1.1.0: New feature
+1.1.0 → 2.0.0: Breaking change
+```
+
+## Automation
+
+```bash
+# Generate changelog from Git commits
+npx conventional-changelog-cli -p angular -i CHANGELOG.md -s
+```
+
+---
+
+**Related Resources:**
+- docs-as-code-workflow.md - Versioning workflow

package/.claude/skills/documentation-as-code/resources/diagram-generation.md

@@ -0,0 +1,44 @@
+# Diagram Generation
+
+Guide to creating diagrams as code using PlantUML, Mermaid, and other tools.
+
+## Mermaid (GitHub-native)
+
+```markdown
+```mermaid
+graph LR
+  A[User] --> B[API]
+  B --> C[Database]
+```
+
+```mermaid
+sequenceDiagram
+  User->>API: Request
+  API->>DB: Query
+  DB-->>API: Result
+  API-->>User: Response
+```
+```
+
+## PlantUML
+
+```plantuml
+@startuml
+User -> API: Request
+API -> Database: Query
+Database -> API: Result
+API -> User: Response
+@enduml
+```
+
+## Best Practices
+
+✅ Version control diagrams as code
+✅ Use consistent notation
+✅ Keep diagrams simple
+✅ Auto-generate images in CI
+
+---
+
+**Related Resources:**
+- technical-writing-guide.md - When to use diagrams

package/.claude/skills/documentation-as-code/resources/docs-as-code-workflow.md

@@ -0,0 +1,99 @@
+# Docs-as-Code Workflow
+
+Complete workflow for treating documentation like code with Git, reviews, and CI/CD.
+
+## Git Workflow
+
+```bash
+# Create documentation branch
+git checkout -b docs/add-api-guide
+
+# Write documentation
+vim docs/api-guide.md
+
+# Commit with clear message
+git add docs/api-guide.md
+git commit -m "docs: Add API authentication guide"
+
+# Push and create PR
+git push origin docs/add-api-guide
+gh pr create --title "Add API authentication guide"
+```
+
+## Pull Request Review
+
+```markdown
+## Documentation PR Checklist
+
+- [ ] Spelling and grammar checked
+- [ ] Code examples tested
+- [ ] Links verified (no broken links)
+- [ ] Screenshots up-to-date (if any)
+- [ ] TOC updated
+- [ ] Related docs updated
+```
+
+## CI/CD Pipeline
+
+```yaml
+# .github/workflows/docs.yml
+name: Documentation
+on: [push, pull_request]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Lint Markdown
+        run: npx markdownlint-cli '**/*.md'
+
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Check Links
+        uses: gaurav-nelson/github-action-markdown-link-check@v1
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Build Docs Site
+        run: |
+          npm install
+          npm run build
+      - name: Deploy to GitHub Pages
+        if: github.ref == 'refs/heads/main'
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./build
+```
+
+## Versioning
+
+```
+docs/
+  v1.0/
+    getting-started.md
+    api-reference.md
+  v2.0/
+    getting-started.md
+    api-reference.md
+  latest/ → symlink to v2.0
+```
+
+## Best Practices
+
+✅ Update docs in same PR as code changes
+✅ Require docs review before merge
+✅ Auto-deploy docs on main branch
+✅ Version docs alongside code
+✅ Use branch protection for docs/
+
+---
+
+**Related Resources:**
+- documentation-automation.md - Automation tools
+- changelog-management.md - Version tracking

package/.claude/skills/documentation-as-code/resources/documentation-automation.md

@@ -0,0 +1,68 @@
+# Documentation Automation
+
+Guide to automating documentation workflows with linting, link checking, and CI/CD.
+
+## Link Checking
+
+```yaml
+# .github/workflows/link-check.yml
+name: Check Links
+on: [pull_request]
+jobs:
+  link-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: gaurav-nelson/github-action-markdown-link-check@v1
+        with:
+          config-file: '.markdown-link-check.json'
+```
+
+```json
+// .markdown-link-check.json
+{
+  "ignorePatterns": [
+    { "pattern": "^http://localhost" }
+  ],
+  "timeout": "20s",
+  "retryOn429": true
+}
+```
+
+## Markdown Linting
+
+```yaml
+# .markdownlint.json
+{
+  "default": true,
+  "MD013": false,
+  "MD033": false
+}
+```
+
+```bash
+npx markdownlint-cli '**/*.md'
+```
+
+## Spell Checking
+
+```bash
+npx cspell "docs/**/*.md"
+```
+
+## Auto-Generate Docs
+
+```typescript
+// Generate API docs from code
+import { generateDocs } from 'typedoc';
+
+generateDocs({
+  entryPoints: ['./src/index.ts'],
+  out: './docs/api'
+});
+```
+
+---
+
+**Related Resources:**
+- docs-as-code-workflow.md - Complete workflow