blockmine 1.20.0 → 1.22.0

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

@@ -0,0 +1,79 @@
+# Documentation Sites
+
+Guide to setting up documentation sites using Docusaurus, MkDocs, GitBook, and other static site generators.
+
+## Docusaurus (React-based)
+
+```bash
+npx create-docusaurus@latest my-docs classic
+cd my-docs
+npm start
+```
+
+```javascript
+// docusaurus.config.js
+module.exports = {
+  title: 'My Docs',
+  tagline: 'Documentation site',
+  url: 'https://docs.example.com',
+  baseUrl: '/',
+  organizationName: 'myorg',
+  projectName: 'my-docs',
+  themeConfig: {
+    navbar: {
+      title: 'Docs',
+      items: [
+        { to: 'docs/intro', label: 'Tutorial', position: 'left' },
+        { href: 'https://github.com/myorg/my-docs', label: 'GitHub', position: 'right' },
+      ],
+    },
+  },
+};
+```
+
+## MkDocs (Python-based)
+
+```bash
+pip install mkdocs
+mkdocs new my-docs
+cd my-docs
+mkdocs serve
+```
+
+```yaml
+# mkdocs.yml
+site_name: My Docs
+theme:
+  name: material
+nav:
+  - Home: index.md
+  - Getting Started: getting-started.md
+  - API Reference: api.md
+```
+
+## Deployment
+
+```yaml
+# .github/workflows/docs.yml
+name: Deploy Docs
+on:
+  push:
+    branches: [main]
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Build
+        run: npm run build
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./build
+```
+
+---
+
+**Related Resources:**
+- documentation-automation.md - CI/CD for docs

package/.claude/skills/documentation-as-code/resources/markdown-best-practices.md

@@ -0,0 +1,162 @@
+# Markdown Best Practices
+
+Guide to effective Markdown usage following GitHub Flavored Markdown (GFM) standards.
+
+## Headings
+
+```markdown
+# H1 - Document Title (one per document)
+## H2 - Major sections
+### H3 - Subsections
+#### H4 - Sub-subsections
+
+# ✅ Good: Clear hierarchy
+# API Documentation
+## Authentication
+### JWT Tokens
+#### Token Expiration
+
+# ❌ Bad: Skipping levels
+# API Documentation
+#### Token Expiration
+```
+
+## Code Blocks
+
+```markdown
+# Inline code
+Use `backticks` for inline code.
+
+# Code blocks with syntax highlighting
+```typescript
+const user = { name: "John" };
+```
+
+# Shell commands
+```bash
+npm install
+npm run dev
+```
+```
+
+## Links
+
+```markdown
+# Inline links
+[Link text](https://example.com)
+
+# Reference links (better for multiple uses)
+[Google][1]
+[GitHub][2]
+
+[1]: https://google.com
+[2]: https://github.com
+
+# Internal links
+[See Architecture](./architecture.md)
+[Jump to section](#installation)
+```
+
+## Images
+
+```markdown
+# Basic image
+![Alt text](./images/diagram.png)
+
+# Image with title
+![Architecture Diagram](./arch.png "System Architecture")
+
+# Linked image
+[![Badge](badge.png)](https://example.com)
+```
+
+## Tables
+
+```markdown
+| Column 1 | Column 2 | Column 3 |
+|----------|----------|----------|
+| Value 1  | Value 2  | Value 3  |
+| Value 4  | Value 5  | Value 6  |
+
+# Alignment
+| Left | Center | Right |
+|:-----|:------:|------:|
+| L1   |   C1   |    R1 |
+```
+
+## Lists
+
+```markdown
+# Unordered
+- Item 1
+- Item 2
+  - Nested item
+  - Another nested
+
+# Ordered
+1. First step
+2. Second step
+   1. Sub-step A
+   2. Sub-step B
+
+# Task lists
+- [x] Completed task
+- [ ] Incomplete task
+```
+
+## Emphasis
+
+```markdown
+*Italic* or _italic_
+**Bold** or __bold__
+***Bold and italic***
+~~Strikethrough~~
+`Code`
+```
+
+## Blockquotes
+
+```markdown
+> Single line quote
+
+> Multi-line quote
+> continues here
+> and here
+
+> **Note:** Use for important callouts
+```
+
+## Horizontal Rules
+
+```markdown
+---
+or
+***
+or
+___
+```
+
+## Best Practices
+
+✅ Use consistent heading hierarchy
+✅ Add blank lines around headings, lists, code blocks
+✅ Use fenced code blocks with language tags
+✅ Provide alt text for images
+✅ Use relative links for internal docs
+✅ Use reference links for repeated URLs
+✅ Keep lines under 120 characters (where possible)
+
+## Anti-Patterns
+
+❌ Mixing ordered/unordered list styles
+❌ Skipping heading levels (H1 → H4)
+❌ No blank lines between elements
+❌ Missing language tags on code blocks
+❌ Broken relative links
+❌ No alt text on images
+
+---
+
+**Related Resources:**
+- technical-writing-guide.md - Writing style
+- documentation-automation.md - Linting and validation

package/.claude/skills/documentation-as-code/resources/openapi-specification.md

@@ -0,0 +1,77 @@
+# OpenAPI Specification
+
+Complete guide to OpenAPI 3.0 specification for API documentation.
+
+## Basic Structure
+
+```yaml
+openapi: 3.0.0
+info:
+  title: My API
+  version: 1.0.0
+  description: API description
+  contact:
+    email: api@example.com
+
+servers:
+  - url: https://api.example.com/v1
+
+paths:
+  /users/{id}:
+    get:
+      summary: Get user by ID
+      parameters:
+        - name: id
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: Success
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/User'
+
+components:
+  schemas:
+    User:
+      type: object
+      required:
+        - id
+        - email
+      properties:
+        id:
+          type: string
+        email:
+          type: string
+          format: email
+
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+
+security:
+  - bearerAuth: []
+```
+
+## Generating Docs
+
+```bash
+# Swagger UI
+npx swagger-ui-watcher openapi.yaml
+
+# Redoc
+npx redoc-cli serve openapi.yaml
+
+# Generate static site
+npx redoc-cli bundle openapi.yaml -o index.html
+```
+
+---
+
+**Related Resources:**
+- api-documentation.md - API documentation practices

package/.claude/skills/documentation-as-code/resources/readme-engineering.md

@@ -0,0 +1,60 @@
+# README Engineering
+
+Guide to creating effective project READMEs.
+
+## Template
+
+```markdown
+# Project Name
+
+Brief description (1-2 sentences)
+
+## Features
+- Feature 1
+- Feature 2
+
+## Quick Start
+```bash
+npm install
+npm run dev
+```
+
+## Installation
+Detailed steps
+
+## Usage
+Examples
+
+## Configuration
+Environment variables
+
+## API Reference
+Link to full docs
+
+## Contributing
+Guidelines
+
+## License
+MIT
+```
+
+## Badges
+
+```markdown
+![Build Status](https://github.com/user/repo/workflows/CI/badge.svg)
+![Coverage](https://codecov.io/gh/user/repo/branch/main/graph/badge.svg)
+![npm](https://img.shields.io/npm/v/package)
+```
+
+## Best Practices
+
+✅ Clear quick start (<5 minutes)
+✅ Working code examples
+✅ Link to full documentation
+✅ Badges for build status
+✅ Screenshots for UI projects
+
+---
+
+**Related Resources:**
+- technical-writing-guide.md - Writing style

package/.claude/skills/documentation-as-code/resources/technical-writing-guide.md

@@ -0,0 +1,202 @@
+# Technical Writing Guide
+
+Guide to writing clear, effective technical documentation for developers.
+
+## Writing Principles
+
+### 1. Clarity First
+- Use simple, direct language
+- Avoid jargon (or explain it)
+- One idea per sentence
+- Short paragraphs (3-5 sentences)
+
+### 2. Show Examples
+Always include code examples:
+
+```markdown
+❌ Bad: "Configure the database connection"
+
+✅ Good: "Configure the database connection in `.env`:
+```
+DATABASE_URL=postgresql://localhost:5432/mydb
+```
+```
+
+### 3. Structure Content
+```
+1. What (brief description)
+2. Why (use case/benefit)
+3. How (step-by-step)
+4. Example (working code)
+```
+
+## Document Structure
+
+### README Template
+```markdown
+# Project Name
+Brief 1-2 sentence description
+
+## Features
+- Bullet points
+
+## Quick Start
+```bash
+# Minimal working example
+npm install
+npm run dev
+```
+
+## Documentation Links
+## Installation
+## Usage
+## Configuration
+## Contributing
+```
+
+### API Endpoint Documentation
+```markdown
+## POST /api/users
+
+Creates a new user account.
+
+### Request Body
+```json
+{
+  "email": "user@example.com",
+  "password": "securepass123"
+}
+```
+
+### Response (201 Created)
+```json
+{
+  "id": "usr_123",
+  "email": "user@example.com",
+  "created_at": "2024-01-15T10:30:00Z"
+}
+```
+
+### Errors
+- `400 Bad Request` - Invalid email format
+- `409 Conflict` - Email already exists
+```
+
+## Style Guidelines
+
+### Voice
+- Active voice: "The API returns..." not "Data is returned by..."
+- Present tense: "The function calculates..." not "The function will calculate..."
+- Second person: "You can configure..." not "Users can configure..."
+
+### Code Examples
+```typescript
+// ✅ Good: Full working example
+import express from 'express';
+
+const app = express();
+app.get('/users', (req, res) => {
+  res.json({ users: [] });
+});
+
+// ❌ Bad: Incomplete snippet
+app.get('/users', ...
+```
+
+### Lists
+Use numbered lists for sequential steps:
+```markdown
+1. Install dependencies
+2. Configure environment
+3. Run the application
+```
+
+Use bullet points for non-sequential items:
+```markdown
+- Feature A
+- Feature B
+- Feature C
+```
+
+## Common Patterns
+
+### How-To Guide
+```markdown
+# How to Deploy to Production
+
+## Prerequisites
+- Node.js 18+
+- AWS CLI configured
+- Production environment variables
+
+## Steps
+
+1. Build the application:
+```bash
+npm run build
+```
+
+2. Run tests:
+```bash
+npm test
+```
+
+3. Deploy to AWS:
+```bash
+aws deploy push --application app-name
+```
+
+## Verification
+Check deployment status:
+```bash
+aws deploy get-deployment --deployment-id <id>
+```
+```
+
+### Troubleshooting Section
+```markdown
+## Troubleshooting
+
+### Error: "Connection refused"
+**Cause**: Database is not running
+**Solution**: Start the database:
+```bash
+docker-compose up -d postgres
+```
+
+### Error: "Port 3000 already in use"
+**Cause**: Another process is using port 3000
+**Solution**: Kill the process or use a different port:
+```bash
+kill $(lsof -t -i:3000)
+# or
+PORT=3001 npm run dev
+```
+```
+
+## Best Practices
+
+✅ Start with a quick start guide (< 5 minutes to working app)
+✅ Include code examples for every concept
+✅ Use screenshots for UI-heavy documentation
+✅ Keep examples up-to-date
+✅ Test all code examples before publishing
+✅ Use consistent formatting
+✅ Link to related documentation
+
+## Anti-Patterns
+
+❌ Walls of text without code examples
+❌ Outdated screenshots
+❌ Broken links
+❌ Assuming too much knowledge
+❌ Incomplete code snippets
+❌ No troubleshooting section
+❌ Missing prerequisites
+
+---
+
+**Related Resources:**
+- markdown-best-practices.md - Markdown formatting
+- api-documentation.md - API-specific writing
+- readme-engineering.md - README best practices