Merge pull request #87 from bufferings/work

feat: add VitePress documentation site with GitHub Pages deployment

Author: bufferings

.cursor/rules/changeset.mdc

@@ -1,7 +1,7 @@
 ---
-description: 'Changeset operation rules for monorepo version management'
-globs: []
-alwaysApply: true
+description: 'Rules for creating changeset files for version management'
+globs: ['**/.changeset/**']
+alwaysApply: false
 ---
 
 # Changeset Operation Rules
@@ -10,30 +10,21 @@ alwaysApply: true
 
 This project uses [Changesets](https://github.com/changesets/changesets) for monorepo version management and publishing. Since the AI assistant cannot interact with CLI prompts, we use a manual changeset file creation approach.
 
-## Current Status
-
-- **Alpha Development Mode**: Currently in `alpha` prerelease mode
-- **Base Version**: Starting from `0.1.0-alpha.0`
-- **Target**: Working towards `0.1.0` stable release
-
 ## Workflow
 
 ### 1. Making Changes
 
 When code changes are made that warrant a release:
 
-1. User requests: "Release [package-name] with [description]"
+1. User requests: "Create changeset"
 2. AI assistant creates changeset file manually
-3. AI assistant runs `pnpm changeset version`
-4. AI assistant commits the changes
 
 ### 2. Changeset File Creation
 
-**Manual Creation Process:**
-
 - AI creates `.changeset/[descriptive-name].md` file
 - Uses patch/minor/major based on change type
 - Includes clear description in English
+- Focus on difference relative to original baseline, not just current working changes
 
 **Example changeset file:**
 
@@ -45,44 +36,8 @@ When code changes are made that warrant a release:
 Fix header configuration bug in CORS plugin
 ```
 
-### 3. Version Bumping Rules
-
-**In Alpha Mode:**
-
-- **Patch changes**: `0.1.0-alpha.0` → `0.1.0-alpha.1`
-- **Minor changes**: `0.1.0-alpha.0` → `0.1.0-alpha.1` (same increment)
-- **Major changes**: `0.1.0-alpha.0` → `0.2.0-alpha.0` (only for breaking changes)
-
-**Default behavior**: Use `patch` for most changes during alpha development.
-
-### 4. Package Configuration
-
-**Included packages:**
-
-- All packages in `packages/` directory
-- Published to npm with `"access": "public"`
-
-**Excluded packages:**
-
-- `@korix/example` (configured in `ignore` array)
-
 ## Commands
 
-### Development Commands
-
-```bash
-# Create changeset (manual file creation by AI)
-# File: .changeset/[name].md
-
-# Apply version changes
-pnpm changeset version
-
-# Publish to npm (when ready)
-pnpm changeset publish
-```
-
-### Mode Management
-
 ```bash
 # Enter alpha mode (already done)
 pnpm changeset pre enter alpha
@@ -93,91 +48,3 @@ pnpm changeset pre exit
 # Re-enter alpha mode
 pnpm changeset pre enter alpha
 ```
-
-## Release Process
-
-### Alpha Releases
-
-1. Make code changes
-2. Request release: "Release [package] with [description]"
-3. AI creates changeset file
-4. AI runs `changeset version` to bump alpha number
-5. AI commits changes
-6. Continue development
-
-### Stable Release (Future)
-
-1. Complete alpha testing
-2. Run `pnpm changeset pre exit`
-3. Run `pnpm changeset version` → creates `0.1.0`
-4. Run `pnpm changeset publish`
-5. Tag and release
-
-## Best Practices
-
-### User Requests
-
-- **Simple**: "Release cors-plugin with bug fix"
-- **Specific**: "Release kori with breaking API changes" (major)
-- **Multiple**: "Release cors-plugin and kori with new features"
-
-### AI Response Pattern
-
-1. Create appropriate changeset file(s)
-2. Run `changeset version`
-3. Show version changes
-4. Commit with descriptive message
-5. Confirm completion
-
-### Version Strategy
-
-- **Alpha phase**: Focus on `patch` increments
-- **Breaking changes**: Only use `major` for significant API changes
-- **New features**: Use `minor` sparingly during alpha
-- **Bug fixes**: Always use `patch`
-
-## Configuration Files
-
-### `.changeset/config.json`
-
-```json
-{
-  "access": "public",
-  "baseBranch": "main",
-  "updateInternalDependencies": "patch",
-  "ignore": ["@korix/example"]
-}
-```
-
-### Prerelease State
-
-- Stored in `.changeset/pre.json`
-- Tracks current alpha mode
-- Automatically managed by changeset commands
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Interactive prompts**: AI cannot respond - use manual file creation
-2. **Version conflicts**: Reset and recreate changeset files
-3. **Missing main branch**: Ensure `main` branch exists for base comparison
-
-### Recovery Steps
-
-```bash
-# Reset if needed
-git checkout -- packages/*/package.json
-rm packages/*/CHANGELOG.md
-
-# Recreate changeset
-# (AI creates new changeset file)
-pnpm changeset version
-```
-
-## Notes
-
-- Always commit changeset files along with code changes
-- CHANGELOG.md files are auto-generated
-- Package.json versions are automatically updated
-- Changeset files are consumed (deleted) after version bump

.cursor/rules/docs.mdc

@@ -0,0 +1,89 @@
+---
+description: 'Guidelines for writing accurate, well-structured documentation'
+globs: ['**/docs/**/*.md', '**/README.md', '**/*.mdc']
+alwaysApply: false
+---
+
+# Documentation Writing Rules
+
+## Core Principle: Source Code First
+
+**NEVER use guesswork or assumptions when writing documentation.**
+
+### Mandatory Process
+
+1. **Read the Source Code**: Always read and understand the actual implementation before writing any documentation
+2. **Verify Examples**: All code examples must be based on real, working code from the codebase
+3. **Check API Usage**: Verify method signatures, parameter types, and return values from the actual source
+4. **Test Assumptions**: If unsure about any behavior, examine the code rather than guessing
+
+### What to Read
+
+- **Main API functions**: Understand how they work internally
+- **Type definitions**: Get accurate parameter and return types
+- **Example files**: Use patterns from existing examples in the codebase
+- **Plugin implementations**: Understand actual plugin architecture
+- **Test files**: See real usage patterns and edge cases
+
+### Prohibited Practices
+
+- ❌ Writing documentation based on common framework patterns
+- ❌ Assuming API behavior without checking source code
+- ❌ Copying examples from similar frameworks
+- ❌ Guessing method signatures or parameter types
+- ❌ Making up configuration options that don't exist
+
+### Required Practices
+
+- ✅ Read the actual source code before writing
+- ✅ Base all examples on real code from the repository
+- ✅ Verify all API calls against the implementation
+- ✅ Check type definitions for accuracy
+- ✅ Test examples against the actual codebase
+
+### When in Doubt
+
+- Read more source code
+- Look for existing examples in the codebase
+- Check test files for usage patterns
+- Never guess - always verify
+
+## Writing Style Guidelines
+
+### Clear Structure Over Bold Text
+
+**Write documents that convey importance through structure, not formatting.**
+
+### Mandatory Practices
+
+- ✅ Use heading hierarchy (h1, h2, h3) to show importance and organization
+- ✅ Write complete, flowing sentences instead of bullet-pointed fragments
+- ✅ Let content organization and natural language convey emphasis
+- ✅ Use section structure to guide readers through logical progression
+
+### Prohibited Practices
+
+- ❌ Using bold text (**text**) to emphasize importance
+- ❌ Relying on formatting instead of clear writing to convey meaning
+- ❌ Creating bullet lists where prose would be more natural
+- ❌ Bold text in navigation links and call-to-action elements
+
+### Writing Approach
+
+- Use descriptive subheadings instead of bold keywords
+- Write cohesive paragraphs that flow naturally
+- Let the information hierarchy speak for itself
+- Make important points clear through placement and context, not bold formatting
+
+### Exception
+
+Bold text may be used sparingly for:
+
+- ✅ True emphasis within technical explanations (very rare)
+- ✅ Highlighting critical warnings or errors
+
+## Remember
+
+Documentation that contains incorrect information is worse than no documentation at all. Accuracy is paramount.
+
+Quality documentation guides readers through natural flow and clear structure, not visual emphasis.

.github/workflows/deploy-docs.yml

@@ -0,0 +1,71 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: 'pages'
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          run_install: false
+
+      - name: Get pnpm store directory
+        shell: bash
+        run: |
+          echo "STORE_PATH=$(pnpm store path --silent)" >> $GITHUB_ENV
+
+      - name: Setup pnpm cache
+        uses: actions/cache@v4
+        with:
+          path: ${{ env.STORE_PATH }}
+          key: ${{ runner.os }}-pnpm-store-${{ hashFiles('**/pnpm-lock.yaml') }}
+          restore-keys: |
+            ${{ runner.os }}-pnpm-store-
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build VitePress site
+        run: pnpm docs:build
+
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: './docs/.vitepress/dist'
+
+  deploy:
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

.github/workflows/release.yml

@@ -12,6 +12,7 @@ jobs:
   release:
     name: Release
     runs-on: ubuntu-latest
+    timeout-minutes: 15
 
     permissions:
       pull-requests: write

.gitignore

@@ -31,3 +31,7 @@ tsconfig.tsbuildinfo
 
 # Turborepo
 .turbo/
+
+# VitePress
+docs/.vitepress/dist
+docs/.vitepress/cache