commit ab497cabe8f7957bed24c7e427002ffc8f81552d
Author: Zhongwei Li <lizhongwei.nkcs@gmail.com>
Date:   Sat Nov 29 17:56:31 2025 +0800

    Initial commit

diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
new file mode 100644
index 0000000..574d06a
--- /dev/null
+++ b/.claude-plugin/plugin.json
@@ -0,0 +1,15 @@
+{
+  "name": "specweave-docs-preview",
+  "description": "Interactive documentation preview with Docusaurus. Launch local dev server to view living documentation in beautiful UI with hot reload, auto-generated sidebar, and Mermaid diagrams. Build static sites for deployment.",
+  "version": "0.24.0",
+  "author": {
+    "name": "SpecWeave Team",
+    "url": "https://spec-weave.com"
+  },
+  "skills": [
+    "./skills"
+  ],
+  "commands": [
+    "./commands"
+  ]
+}
\ No newline at end of file
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..f7a8b9e
--- /dev/null
+++ b/README.md
@@ -0,0 +1,3 @@
+# specweave-docs-preview
+
+Interactive documentation preview with Docusaurus. Launch local dev server to view living documentation in beautiful UI with hot reload, auto-generated sidebar, and Mermaid diagrams. Build static sites for deployment.
diff --git a/commands/build.md b/commands/build.md
new file mode 100644
index 0000000..35fade3
--- /dev/null
+++ b/commands/build.md
@@ -0,0 +1,489 @@
+---
+name: specweave-docs-preview:build
+description: Build static documentation site for deployment. Generates production-ready HTML/CSS/JS files optimized for static hosting.
+---
+
+# Documentation Build Command
+
+Build a production-ready static documentation site from your SpecWeave living documentation.
+
+## Your Task
+
+Execute the following workflow to build the static documentation site:
+
+### Step 1: Load the Build Utilities
+
+```typescript
+import { buildStaticSite, isSetupNeeded } from '../../../src/utils/docs-preview/index.js';
+import * as fs from 'fs-extra';
+import * as path from 'path';
+```
+
+### Step 2: Check Prerequisites
+
+```typescript
+const projectRoot = process.cwd();
+
+// Check if docs preview is configured
+const configPath = path.join(projectRoot, '.specweave', 'config.json');
+let config: any = {};
+if (fs.existsSync(configPath)) {
+  config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+}
+
+const docsConfig = config.documentation?.preview || {};
+
+console.log('\n📦 Building Documentation Site...\n');
+
+// Check if Docusaurus is installed
+const setupNeeded = await isSetupNeeded(projectRoot);
+
+if (setupNeeded) {
+  console.error('❌ Docusaurus not installed\n');
+  console.log('💡 Solution:');
+  console.log('   Run: /specweave-docs-preview:preview');
+  console.log('   This will install Docusaurus first\n');
+  process.exit(1);
+}
+```
+
+### Step 3: Build the Static Site
+
+```typescript
+try {
+  console.log('ℹ️  Building production site...');
+  console.log('   • Compiling React components');
+  console.log('   • Optimizing assets');
+  console.log('   • Generating static HTML\n');
+
+  await buildStaticSite(projectRoot);
+
+  const buildPath = path.join(projectRoot, '.specweave', 'docs-site-internal', 'build');
+  const buildStats = await getBuildStats(buildPath);
+
+  console.log('\n✅ Build Complete!\n');
+  console.log('📊 Build Statistics:');
+  console.log(`   • Pages: ${buildStats.pages} HTML files`);
+  console.log(`   • Size: ${buildStats.totalSize}`);
+  console.log(`   • Location: ${buildPath}\n`);
+
+  console.log('🚀 Deployment Options:\n');
+  console.log('1️⃣  Netlify:');
+  console.log('   cd .specweave/docs-site-internal');
+  console.log('   npx netlify deploy --dir=build --prod\n');
+
+  console.log('2️⃣  Vercel:');
+  console.log('   cd .specweave/docs-site-internal');
+  console.log('   npx vercel --prod\n');
+
+  console.log('3️⃣  GitHub Pages:');
+  console.log('   cp -r build/* docs/');
+  console.log('   git add docs/ && git commit -m "docs: update"');
+  console.log('   git push\n');
+
+  console.log('4️⃣  Static Server (local test):');
+  console.log('   npx serve build/\n');
+
+  console.log('5️⃣  Your own server:');
+  console.log('   scp -r build/* user@server:/var/www/docs/\n');
+
+} catch (error: any) {
+  console.error('\n❌ Build Failed\n');
+  console.error(`Error: ${error.message}\n`);
+
+  console.log('💡 Troubleshooting:');
+  console.log('   • Check all markdown files have valid frontmatter');
+  console.log('   • Ensure no broken internal links');
+  console.log('   • Run preview first to catch errors: /specweave-docs-preview:preview');
+  console.log('   • Check build logs above for specific errors\n');
+
+  process.exit(1);
+}
+```
+
+### Step 4: Helper Function - Get Build Statistics
+
+```typescript
+async function getBuildStats(buildPath: string): Promise<{
+  pages: number;
+  totalSize: string;
+}> {
+  let pages = 0;
+  let totalBytes = 0;
+
+  async function walk(dir: string) {
+    const files = await fs.readdir(dir);
+    for (const file of files) {
+      const filePath = path.join(dir, file);
+      const stats = await fs.stat(filePath);
+      if (stats.isDirectory()) {
+        await walk(filePath);
+      } else {
+        totalBytes += stats.size;
+        if (file.endsWith('.html')) {
+          pages++;
+        }
+      }
+    }
+  }
+
+  await walk(buildPath);
+
+  const totalMB = (totalBytes / 1024 / 1024).toFixed(2);
+  return {
+    pages,
+    totalSize: `${totalMB} MB`
+  };
+}
+```
+
+## What Gets Built
+
+### Output Directory Structure
+```
+.specweave/docs-site-internal/build/
+├── index.html                    ← Landing page
+├── docs/
+│   ├── strategy/
+│   │   ├── prd-001/
+│   │   │   └── index.html
+│   │   └── okrs/
+│   │       └── index.html
+│   ├── specs/
+│   │   ├── spec-001-auth/
+│   │   │   └── index.html
+│   │   └── spec-002-payments/
+│   │       └── index.html
+│   └── architecture/
+│       ├── hld-system/
+│       │   └── index.html
+│       └── adr/
+│           └── 0001-database-choice/
+│               └── index.html
+├── assets/
+│   ├── css/
+│   │   └── styles.[hash].css    ← Optimized CSS
+│   ├── js/
+│   │   └── runtime.[hash].js    ← React runtime
+│   └── images/                  ← Optimized images
+└── sitemap.xml                  ← Search engine sitemap
+```
+
+### Build Optimizations
+1. **Code Splitting**: React chunks loaded on demand
+2. **Asset Optimization**: CSS/JS minified and compressed
+3. **Image Optimization**: Auto-resized and compressed
+4. **Static HTML**: Pre-rendered pages for fast loading
+5. **Search Index**: Pre-generated search index
+6. **Sitemap**: Auto-generated for SEO
+
+## Deployment Examples
+
+### Netlify (Recommended)
+
+**Option 1: CLI**
+```bash
+cd .specweave/docs-site-internal
+npx netlify deploy --dir=build --prod
+```
+
+**Option 2: Drag & Drop**
+1. Go to https://app.netlify.com/drop
+2. Drag `.specweave/docs-site-internal/build/` folder
+3. Done! Get instant URL
+
+**Option 3: Git Integration**
+1. Create `netlify.toml`:
+   ```toml
+   [build]
+     base = ".specweave/docs-site-internal"
+     publish = "build"
+     command = "npm run build"
+   ```
+2. Connect GitHub repo
+3. Auto-deploy on push
+
+### Vercel
+
+```bash
+cd .specweave/docs-site-internal
+npx vercel --prod
+```
+
+### GitHub Pages
+
+**Option 1: docs/ folder**
+```bash
+# 1. Copy build to docs/
+cp -r .specweave/docs-site-internal/build/* docs/
+
+# 2. Enable GitHub Pages
+# Go to Settings → Pages → Source: main branch /docs folder
+
+# 3. Push
+git add docs/
+git commit -m "docs: update documentation site"
+git push
+```
+
+**Option 2: gh-pages branch**
+```bash
+# 1. Install gh-pages
+npm install -g gh-pages
+
+# 2. Deploy
+gh-pages -d .specweave/docs-site-internal/build
+```
+
+### AWS S3 + CloudFront
+
+```bash
+# 1. Sync to S3
+aws s3 sync .specweave/docs-site-internal/build/ s3://your-bucket/ \
+  --delete \
+  --cache-control "max-age=31536000,public"
+
+# 2. Invalidate CloudFront
+aws cloudfront create-invalidation \
+  --distribution-id YOUR_DIST_ID \
+  --paths "/*"
+```
+
+### Docker + Nginx
+
+**Dockerfile:**
+```dockerfile
+FROM nginx:alpine
+COPY .specweave/docs-site-internal/build/ /usr/share/nginx/html/
+EXPOSE 80
+```
+
+**Build and run:**
+```bash
+docker build -t docs .
+docker run -p 80:80 docs
+```
+
+### Your Own Server
+
+**Nginx config:**
+```nginx
+server {
+    listen 80;
+    server_name docs.example.com;
+    root /var/www/docs;
+    index index.html;
+
+    location / {
+        try_files $uri $uri/ /index.html;
+    }
+}
+```
+
+**Deploy:**
+```bash
+scp -r .specweave/docs-site-internal/build/* user@server:/var/www/docs/
+```
+
+## Testing Before Deployment
+
+### Local Testing with Serve
+
+```bash
+# 1. Install serve
+npm install -g serve
+
+# 2. Serve build folder
+cd .specweave/docs-site-internal
+serve build/
+
+# 3. Open browser
+# Visit: http://localhost:3000
+```
+
+### Check Lighthouse Scores
+
+```bash
+# 1. Install lighthouse
+npm install -g lighthouse
+
+# 2. Run audit
+lighthouse http://localhost:3000 \
+  --view \
+  --output html
+
+# Expected scores:
+# Performance: 100
+# Accessibility: 100
+# Best Practices: 100
+# SEO: 100
+```
+
+## Expected Output
+
+**Successful Build:**
+```
+📦 Building Documentation Site...
+
+ℹ️  Building production site...
+   • Compiling React components
+   • Optimizing assets
+   • Generating static HTML
+
+[==================================] 100%
+
+✅ Build Complete!
+
+📊 Build Statistics:
+   • Pages: 42 HTML files
+   • Size: 3.2 MB
+   • Location: /project/.specweave/docs-site-internal/build/
+
+🚀 Deployment Options:
+
+1️⃣  Netlify:
+   cd .specweave/docs-site-internal
+   npx netlify deploy --dir=build --prod
+
+2️⃣  Vercel:
+   cd .specweave/docs-site-internal
+   npx vercel --prod
+
+3️⃣  GitHub Pages:
+   cp -r build/* docs/
+   git add docs/ && git commit -m "docs: update"
+   git push
+
+4️⃣  Static Server (local test):
+   npx serve build/
+
+5️⃣  Your own server:
+   scp -r build/* user@server:/var/www/docs/
+```
+
+## Common Build Errors
+
+### Invalid Frontmatter
+```
+Error: Invalid frontmatter in file: spec-001.md
+```
+**Fix:**
+```markdown
+---
+title: User Authentication
+sidebar_position: 1
+---
+
+Content here...
+```
+
+### Broken Links
+```
+Error: Broken link in file: architecture/hld.md
+Link: ../specs/missing-file.md
+```
+**Fix:** Update or remove broken links
+
+### Missing Dependencies
+```
+Error: Module not found: 'react'
+```
+**Fix:**
+```bash
+cd .specweave/docs-site-internal
+npm install
+```
+
+## Build vs Preview
+
+| Aspect | Preview (`/specweave-docs-preview:preview`) | Build (`/specweave-docs-preview:build`) |
+|--------|---------------------------------------------|----------------------------------------|
+| **Purpose** | Development, hot reload | Production deployment |
+| **Speed** | Instant start | 5-10 seconds build |
+| **Output** | Dev server | Static files |
+| **Hot Reload** | ✅ Yes | ❌ No |
+| **Optimization** | ❌ No | ✅ Yes (minified, compressed) |
+| **Search** | ✅ Works | ✅ Pre-generated index |
+| **Use When** | Editing docs | Deploying to server |
+
+## Best Practices
+
+### 1. Build Before Every Deployment
+Always build fresh before deploying:
+```bash
+/specweave-docs-preview:build
+# Then deploy
+```
+
+### 2. Test Build Locally
+```bash
+/specweave-docs-preview:build
+cd .specweave/docs-site-internal
+npx serve build/
+# Visit http://localhost:3000 and test
+```
+
+### 3. Check All Pages
+- Click through every page
+- Test search functionality
+- Verify all links work
+- Check mobile responsiveness
+
+### 4. Optimize Images
+Before building, optimize images:
+```bash
+# Install sharp-cli
+npm install -g sharp-cli
+
+# Optimize images
+sharp -i docs/images/*.png -o docs/images/optimized/ -q 80
+```
+
+### 5. Update Sitemap
+The sitemap is auto-generated, but verify it:
+```bash
+cat .specweave/docs-site-internal/build/sitemap.xml
+```
+
+## Integration with CI/CD
+
+### GitHub Actions
+
+**.github/workflows/docs.yml:**
+```yaml
+name: Deploy Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - '.specweave/docs/**'
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: actions/setup-node@v3
+        with:
+          node-version: 20
+
+      - name: Install SpecWeave
+        run: npm install -g specweave
+
+      - name: Build Docs
+        run: specweave docs build
+
+      - name: Deploy to Netlify
+        run: |
+          cd .specweave/docs-site-internal
+          npx netlify deploy --dir=build --prod
+        env:
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_TOKEN }}
+```
+
+## See Also
+
+- `/specweave-docs-preview:preview` - Preview docs locally with hot reload
+- `specweave-docs` plugin - Documentation workflow skills
+- Docusaurus docs: https://docusaurus.io/docs/deployment
diff --git a/commands/preview.md b/commands/preview.md
new file mode 100644
index 0000000..ef8eebf
--- /dev/null
+++ b/commands/preview.md
@@ -0,0 +1,355 @@
+---
+name: specweave-docs-preview:preview
+description: Launch interactive documentation preview server with Docusaurus. Auto-generates sidebar, enables hot reload, and opens browser automatically.
+---
+
+# Documentation Preview Command
+
+Launch an interactive Docusaurus development server to preview your SpecWeave living documentation.
+
+## 🎨 Beautiful Docusaurus Experience
+
+**This command ALWAYS uses Docusaurus** - not basic file serving! You get:
+- ✅ Auto-generated navigation from folder structure
+- ✅ Search functionality (instant local search)
+- ✅ Beautiful theming (light/dark mode)
+- ✅ Mermaid diagram rendering
+- ✅ Hot reload (edit markdown, see changes instantly)
+- ✅ Professional typography and layout
+- ✅ Mobile responsive design
+
+**Never settle for basic markdown rendering when you can have this!**
+
+## Your Task
+
+Execute the following workflow to launch the documentation preview server:
+
+### Step 1: Load the Preview Utilities
+
+```typescript
+import { launchPreview, isSetupNeeded, getDocsSitePath } from '../../../src/utils/docs-preview/index.js';
+```
+
+**Note:** These utilities are already implemented in the SpecWeave codebase.
+
+### Step 2: Check Configuration
+
+Read the project configuration from `.specweave/config.json`:
+
+```typescript
+import * as fs from 'fs-extra';
+import * as path from 'path';
+
+const projectRoot = process.cwd();
+const configPath = path.join(projectRoot, '.specweave', 'config.json');
+
+let config: any = {};
+if (fs.existsSync(configPath)) {
+  config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+}
+
+const docsConfig = config.documentation?.preview || {
+  enabled: true,
+  autoInstall: true,
+  port: 3016,
+  openBrowser: true,
+  theme: 'default',
+  excludeFolders: ['legacy', 'node_modules']
+};
+```
+
+### Step 3: Check if Documentation Preview is Enabled (Auto-Enable if Needed)
+
+```typescript
+if (!docsConfig.enabled) {
+  console.log('📚 Documentation preview is currently disabled.');
+  console.log('   Enabling it now for beautiful Docusaurus experience...\n');
+
+  // Auto-enable the feature
+  config.documentation = config.documentation || {};
+  config.documentation.preview = {
+    ...docsConfig,
+    enabled: true,
+    autoInstall: true
+  };
+
+  // Save updated config
+  fs.writeFileSync(configPath, JSON.stringify(config, null, 2), 'utf-8');
+
+  console.log('✅ Documentation preview enabled!\n');
+}
+```
+
+### Step 4: Display Setup Information
+
+```typescript
+console.log('\n📚 Launching Documentation Preview...\n');
+
+const setupNeeded = await isSetupNeeded(projectRoot);
+
+if (setupNeeded) {
+  console.log('ℹ️  First-time setup required');
+  console.log('   • Installing Docusaurus (~30 seconds)');
+  console.log('   • Generating configuration');
+  console.log('   • Creating sidebar from folder structure\n');
+} else {
+  console.log('✓ Docusaurus already installed');
+  console.log('✓ Configuration up-to-date\n');
+}
+```
+
+### Step 5: Launch the Preview Server
+
+```typescript
+try {
+  const options = {
+    port: docsConfig.port || 3016,
+    openBrowser: docsConfig.openBrowser !== false,
+    theme: docsConfig.theme || 'default',
+    excludeFolders: docsConfig.excludeFolders || ['legacy', 'node_modules']
+  };
+
+  const server = await launchPreview(projectRoot, options);
+
+  console.log('\n✅ Documentation server started successfully!\n');
+  console.log(`🌐 URL: ${server.url}`);
+  console.log('🔄 Hot reload enabled - edit markdown files to see changes instantly');
+  console.log('🗂️  Sidebar auto-generated from folder structure');
+  console.log('📊 Mermaid diagrams supported');
+  console.log('\n💡 Press Ctrl+C to stop the server\n');
+
+  // Keep the process running
+  process.on('SIGINT', () => {
+    console.log('\n\n👋 Stopping documentation server...');
+    process.exit(0);
+  });
+
+} catch (error: any) {
+  console.error('\n❌ Failed to launch documentation preview\n');
+  console.error(`Error: ${error.message}\n`);
+
+  if (error.message.includes('Node.js 18+')) {
+    console.log('💡 Solution:');
+    console.log('   • Update Node.js: nvm install 20 (or download from nodejs.org)');
+    console.log('   • Current version: node --version\n');
+  } else if (error.message.includes('port')) {
+    console.log('💡 Solution:');
+    console.log('   • Change port in .specweave/config.json');
+    console.log('   • Or stop the service using port ' + (docsConfig.port || 3016));
+    console.log('   • Check with: lsof -i :' + (docsConfig.port || 3016) + '\n');
+  } else {
+    console.log('💡 Troubleshooting:');
+    console.log('   • Check Node.js version (18+ required): node --version');
+    console.log('   • Clear npm cache: npm cache clean --force');
+    console.log('   • Check .specweave/docs/internal/ exists');
+    console.log('   • Run with DEBUG=* for detailed logs\n');
+  }
+
+  process.exit(1);
+}
+```
+
+## Important Notes
+
+### Configuration
+The command uses settings from `.specweave/config.json`:
+
+```json
+{
+  "documentation": {
+    "preview": {
+      "enabled": true,
+      "autoInstall": true,
+      "port": 3016,
+      "openBrowser": true,
+      "theme": "default",
+      "excludeFolders": ["legacy", "node_modules"]
+    }
+  }
+}
+```
+
+### First-Time Setup
+On first run, the command will:
+1. Check Node.js version (requires 18+)
+2. Install Docusaurus packages (~30 seconds)
+3. Generate `docusaurus.config.js`
+4. Create sidebar from folder structure
+5. Start development server
+6. Open browser automatically
+
+### Subsequent Runs
+On subsequent runs, the command will:
+1. Check if Docusaurus is installed (instant)
+2. Regenerate sidebar (in case docs changed)
+3. Start server (~2 seconds)
+4. Open browser
+
+### Directory Structure
+```
+.specweave/
+├── docs/
+│   └── internal/              ← Source documentation
+│       ├── strategy/
+│       ├── specs/
+│       ├── architecture/
+│       ├── delivery/
+│       ├── operations/
+│       └── governance/
+└── docs-site-internal/        ← Docusaurus installation (generated)
+    ├── docs/                  ← Symlinked to internal/
+    ├── src/
+    ├── docusaurus.config.js
+    ├── sidebars.js
+    └── package.json
+```
+
+### What Gets Auto-Generated
+1. **Sidebar** (`sidebars.js`):
+   - Recursively scans `.specweave/docs/internal/`
+   - Creates categories from folders
+   - Sorts by priority (strategy first, governance last)
+   - Formats labels (kebab-case → Title Case)
+
+2. **Configuration** (`docusaurus.config.js`):
+   - Site title from project name
+   - Theme settings from config
+   - Mermaid diagram support
+   - Hot reload enabled
+
+3. **Landing Page** (`src/pages/index.js`):
+   - Welcome message
+   - Quick navigation links
+   - Project information
+
+### Hot Reload
+Changes to markdown files in `.specweave/docs/internal/` are detected automatically:
+- Edit file → Save → Browser refreshes instantly
+- No need to restart server
+- Works for all markdown files
+
+### Stopping the Server
+- Press `Ctrl+C` in terminal
+- Or close the terminal window
+- Or kill the process: `pkill -f docusaurus`
+
+## Expected Output
+
+**First Run:**
+```
+📚 Launching Documentation Preview...
+
+ℹ️  First-time setup required
+   • Installing Docusaurus (~30 seconds)
+   • Generating configuration
+   • Creating sidebar from folder structure
+
+📦 Installing Docusaurus packages...
+[============================>] 100%
+
+✓ Packages installed successfully
+✓ Configuration generated
+✓ Sidebar generated (42 documents, 8 categories)
+✓ Server started on http://localhost:3016
+
+✅ Documentation server started successfully!
+
+🌐 URL: http://localhost:3016
+🔄 Hot reload enabled - edit markdown files to see changes instantly
+🗂️  Sidebar auto-generated from folder structure
+📊 Mermaid diagrams supported
+
+💡 Press Ctrl+C to stop the server
+```
+
+**Subsequent Runs:**
+```
+📚 Launching Documentation Preview...
+
+✓ Docusaurus already installed
+✓ Configuration up-to-date
+
+✓ Sidebar generated (42 documents, 8 categories)
+✓ Server started on http://localhost:3016
+
+✅ Documentation server started successfully!
+
+🌐 URL: http://localhost:3016
+🔄 Hot reload enabled - edit markdown files to see changes instantly
+🗂️  Sidebar auto-generated from folder structure
+📊 Mermaid diagrams supported
+
+💡 Press Ctrl+C to stop the server
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Port Already in Use:**
+```
+Error: Port 3016 is already in use
+```
+Solution:
+1. Change port in `.specweave/config.json` → `documentation.preview.port`
+2. Or stop the service: `lsof -i :3016` then `kill -9 <PID>`
+
+**Node.js Version:**
+```
+Error: Node.js 18+ required (current: v16.x.x)
+```
+Solution:
+1. Update Node.js: `nvm install 20` (or download from nodejs.org)
+2. Verify: `node --version`
+
+**Missing Documentation:**
+```
+Error: No documentation found in .specweave/docs/internal/
+```
+Solution:
+1. Check folder exists: `ls .specweave/docs/internal/`
+2. Add at least one markdown file
+3. Or run `/specweave:increment` to create documentation
+
+## Integration with SpecWeave Workflow
+
+### After Creating Increment
+```bash
+/specweave:increment "User Authentication"
+# → Creates spec.md, plan.md, tasks.md
+
+/specweave-docs-preview:preview
+# → Preview shows new spec in sidebar
+```
+
+### After Completing Increment
+```bash
+/specweave:done 0008
+# → Syncs spec.md to .specweave/docs/internal/specs/spec-0008-user-auth.md
+
+# Hot reload automatically shows the new spec!
+# No need to restart preview server
+```
+
+### Viewing Architecture Decisions
+```bash
+# Create ADR
+vim .specweave/docs/internal/architecture/adr/0001-database-choice.md
+
+# Hot reload shows it instantly
+# Navigate to Architecture → ADR → Database Choice
+```
+
+## Best Practices
+
+1. **Keep Server Running**: Start once, leave running during development
+2. **Edit in IDE**: Changes reflect instantly (hot reload)
+3. **Organize Folders**: Good folder structure = good sidebar
+4. **Use Frontmatter**: Add title, position to control order
+5. **Test Search**: Built-in search works after indexing
+
+## See Also
+
+- `/specweave-docs-preview:build` - Build static site for deployment
+- `specweave-docs` plugin - General documentation skills
+- Docusaurus docs: https://docusaurus.io
diff --git a/plugin.lock.json b/plugin.lock.json
new file mode 100644
index 0000000..563d215
--- /dev/null
+++ b/plugin.lock.json
@@ -0,0 +1,53 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:anton-abyzov/specweave:plugins/specweave-docs-preview",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "cacf1d005f124667051e4710d4e0c1e9fb635453",
+    "treeHash": "685fca3af4a60fe02a1f036472ebafaafb0f1fe3c267cbcecd871b607c77118d",
+    "generatedAt": "2025-11-28T10:13:51.295296Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "specweave-docs-preview",
+    "description": "Interactive documentation preview with Docusaurus. Launch local dev server to view living documentation in beautiful UI with hot reload, auto-generated sidebar, and Mermaid diagrams. Build static sites for deployment.",
+    "version": "0.24.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "03f94ed129ecf6d3a5344241504bf639674c248698e9a5f2386bb3c58f8fa0eb"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "9f2b28219e85995d6527df7596663ca503f6941b4d39b36637faaeb8ed4fe7bb"
+      },
+      {
+        "path": "commands/preview.md",
+        "sha256": "7a5de767dd3e30aa2da350f88287d4e6a7e2f8eef9a395178a50773cfe93814f"
+      },
+      {
+        "path": "commands/build.md",
+        "sha256": "7962590b279a57419aeaaf11b990b578afac1b6e7b0d8ba5413346fd71434b9b"
+      },
+      {
+        "path": "skills/docs-preview/SKILL.md",
+        "sha256": "a7857fc64007d18634a74492d3d7ab13e7db67e0d1337a436b988300ca6221a0"
+      }
+    ],
+    "dirSha256": "685fca3af4a60fe02a1f036472ebafaafb0f1fe3c267cbcecd871b607c77118d"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}
\ No newline at end of file
diff --git a/skills/docs-preview/SKILL.md b/skills/docs-preview/SKILL.md
new file mode 100644
index 0000000..c7c482e
--- /dev/null
+++ b/skills/docs-preview/SKILL.md
@@ -0,0 +1,386 @@
+---
+name: docs-preview
+description: Documentation preview expert for Docusaurus integration. Launches interactive preview server for SpecWeave living documentation with hot reload, auto-generated sidebar, and Mermaid diagrams. Activates for preview docs, view documentation, Docusaurus server, docs UI, documentation website, local docs server, hot reload docs, static site build.
+---
+
+# Documentation Preview Skill
+
+Expert in launching and managing Docusaurus documentation preview for SpecWeave projects.
+
+## What I Do
+
+I help you preview and build your SpecWeave living documentation with Docusaurus:
+
+### 1. Interactive Preview
+- Launch local development server (default port: 3015)
+- Auto-generate sidebar from folder structure
+- Hot reload - edit markdown, see changes instantly
+- Mermaid diagram rendering
+- Mobile-responsive UI
+- Search functionality
+
+### 2. Static Site Building
+- Build production-ready static site
+- Output to `.specweave/docs-site-internal/build/`
+- Ready for deployment to any static host
+- Optimized for performance
+
+### 3. Smart Setup
+- Lazy installation (only installs when first used)
+- Checks Node.js version (18+ required)
+- Installs Docusaurus dependencies automatically
+- Configures from `.specweave/config.json` settings
+
+## Available Commands
+
+### Preview Documentation
+```bash
+/specweave-docs-preview:preview
+```
+
+**What it does:**
+1. Checks if Docusaurus is installed (installs if needed)
+2. Generates sidebar from `.specweave/docs/internal/` structure
+3. Starts development server on port 3015 (configurable)
+4. Opens browser automatically
+5. Enables hot reload
+
+**Configuration** (`.specweave/config.json`):
+```json
+{
+  "documentation": {
+    "preview": {
+      "enabled": true,
+      "autoInstall": false,
+      "port": 3015,
+      "openBrowser": true,
+      "theme": "default",
+      "excludeFolders": ["legacy", "node_modules"]
+    }
+  }
+}
+```
+
+**Example session:**
+```
+User: "Can I preview my documentation?"
+You: "Yes! I'll launch the Docusaurus preview server for you."
+     [Run: /specweave-docs-preview:preview]
+
+Output:
+📚 Setting up documentation preview...
+✓ Node.js version check passed (v20.0.0)
+✓ Docusaurus already installed
+✓ Sidebar generated (42 documents, 8 categories)
+✓ Server started on http://localhost:3015
+
+🌐 Documentation available at: http://localhost:3015
+🔄 Hot reload enabled - edit docs and see changes instantly
+💡 Press Ctrl+C to stop the server
+```
+
+### Build Static Site
+```bash
+/specweave-docs-preview:build
+```
+
+**What it does:**
+1. Checks if Docusaurus is installed
+2. Runs production build
+3. Outputs to `.specweave/docs-site-internal/build/`
+4. Shows build stats and output path
+
+**Example session:**
+```
+User: "Build my docs for deployment"
+You: "I'll build the static documentation site."
+     [Run: /specweave-docs-preview:build]
+
+Output:
+📦 Building static documentation site...
+✓ Build complete!
+📁 Output: /project/.specweave/docs-site-internal/build/
+
+To deploy:
+1. Copy build/ folder to your static host
+2. Or use: npx serve build/
+```
+
+## When to Use This Skill
+
+### Activate for questions like:
+- "How do I preview my documentation?"
+- "Show me my docs in a UI"
+- "Launch Docusaurus server"
+- "View my living documentation"
+- "Start docs preview"
+- "Build static docs site"
+- "Hot reload documentation"
+- "Documentation website"
+
+### Common workflows:
+
+**1. First-time preview:**
+```
+User: "I want to preview my docs"
+You: "I'll set up the documentation preview with Docusaurus.
+      This will install dependencies (takes ~30 seconds first time)."
+     [Run: /specweave-docs-preview:preview]
+```
+
+**2. Already running:**
+```
+User: "Preview my docs"
+You: "Checking if Docusaurus is running..."
+     [If running: "Documentation server already running at http://localhost:3015"]
+     [If not: Run /specweave-docs-preview:preview]
+```
+
+**3. Build for deployment:**
+```
+User: "I need to deploy my docs"
+You: "I'll build the static site for deployment."
+     [Run: /specweave-docs-preview:build]
+     "Once built, you can deploy the build/ folder to:"
+     "• Netlify, Vercel, GitHub Pages"
+     "• Any static host (Nginx, Apache, S3)"
+     "• Or test locally with: npx serve build/"
+```
+
+## Architecture
+
+### Folder Structure
+```
+.specweave/
+├── docs/
+│   └── internal/           ← Source documentation
+│       ├── strategy/
+│       ├── specs/
+│       ├── architecture/
+│       └── ...
+└── docs-site-internal/     ← Docusaurus installation
+    ├── docs/               ← Symlinked to internal/
+    ├── src/
+    ├── build/              ← Static output
+    ├── docusaurus.config.js
+    ├── sidebars.js         ← Auto-generated
+    └── package.json
+```
+
+### Sidebar Auto-Generation
+
+The sidebar is generated from your folder structure:
+
+**Input** (`.specweave/docs/internal/`):
+```
+internal/
+├── strategy/
+│   ├── prd-001.md
+│   └── okrs.md
+├── specs/
+│   ├── spec-001-auth.md
+│   └── spec-002-payments.md
+└── architecture/
+    ├── hld-system.md
+    └── adr/
+        └── 0001-database-choice.md
+```
+
+**Output** (`sidebars.js`):
+```javascript
+{
+  docs: [
+    {
+      type: 'category',
+      label: 'Strategy',
+      items: ['strategy/prd-001', 'strategy/okrs']
+    },
+    {
+      type: 'category',
+      label: 'Specs',
+      items: ['specs/spec-001-auth', 'specs/spec-002-payments']
+    },
+    {
+      type: 'category',
+      label: 'Architecture',
+      items: [
+        'architecture/hld-system',
+        {
+          type: 'category',
+          label: 'ADR',
+          items: ['architecture/adr/0001-database-choice']
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Configuration Options
+
+### Port Selection
+```json
+{
+  "documentation": {
+    "preview": {
+      "port": 3015
+    }
+  }
+}
+```
+
+**Why 3015?**
+- Port 3000 = React/Next.js/Vite dev servers (conflict!)
+- Port 3015 = Internal docs (SpecWeave default)
+- Port 3016 = Reserved for public docs (future)
+
+### Theme Selection
+```json
+{
+  "documentation": {
+    "preview": {
+      "theme": "default"
+    }
+  }
+}
+```
+
+**Available themes:**
+- `default` - SpecWeave blue theme
+- `classic` - Docusaurus default theme
+- `dark` - Dark mode theme
+
+### Exclude Folders
+```json
+{
+  "documentation": {
+    "preview": {
+      "excludeFolders": ["legacy", "node_modules", "archive"]
+    }
+  }
+}
+```
+
+## Troubleshooting
+
+### Port already in use
+```
+Error: Port 3015 is already in use
+Solution: Change port in config or stop other service
+```
+
+### Node.js version
+```
+Error: Node.js 18+ required
+Solution: Update Node.js (nvm install 20)
+```
+
+### Mermaid diagrams not rendering
+```
+Issue: Diagrams show as code blocks
+Solution: Use ```mermaid code fences (built-in support)
+```
+
+### Build fails
+```
+Error: Build failed
+Check:
+1. All markdown files have valid frontmatter
+2. No broken internal links
+3. Run preview first to catch errors early
+```
+
+## Best Practices
+
+### 1. Use Preview During Development
+- Start preview server: `/specweave-docs-preview:preview`
+- Edit markdown files in `.specweave/docs/internal/`
+- See changes instantly (hot reload)
+- No need to rebuild
+
+### 2. Build Before Deployment
+- Always build before deploying
+- Test build output locally: `npx serve build/`
+- Check all pages render correctly
+- Verify search works
+
+### 3. Keep Docs Organized
+- Follow SpecWeave folder structure
+- Use meaningful file names
+- Add frontmatter to markdown files:
+  ```markdown
+  ---
+  title: User Authentication
+  sidebar_position: 1
+  ---
+  ```
+
+### 4. Optimize for Search
+- Use descriptive headings
+- Include keywords naturally
+- Add alt text to images
+- Keep URL structure clean
+
+## Example: Complete Workflow
+
+```bash
+# 1. Preview docs locally
+/specweave-docs-preview:preview
+# → Opens http://localhost:3015
+# → Edit files, see changes instantly
+
+# 2. Build for production
+/specweave-docs-preview:build
+# → Outputs to .specweave/docs-site-internal/build/
+
+# 3. Deploy (example with Netlify)
+cd .specweave/docs-site-internal
+npx netlify deploy --dir=build --prod
+```
+
+## Integration with SpecWeave
+
+### Living Documentation Sync
+Documentation preview integrates with SpecWeave's living docs:
+
+1. **After increment completion:**
+   - `spec.md` synced to `.specweave/docs/internal/specs/`
+   - Preview updates automatically (hot reload)
+
+2. **Architecture decisions:**
+   - ADRs created in `.specweave/docs/internal/architecture/adr/`
+   - Instantly visible in preview
+
+3. **Multi-project support:**
+   - Each project gets its own docs folder
+   - Preview shows all projects in sidebar
+
+## Commands Summary
+
+| Command | Purpose | When to Use |
+|---------|---------|-------------|
+| `/specweave-docs-preview:preview` | Launch dev server | During development, hot reload |
+| `/specweave-docs-preview:build` | Build static site | Before deployment, production |
+
+## Technical Details
+
+### Under the Hood
+- **Framework:** Docusaurus 3.0
+- **React version:** 18+
+- **Build tool:** Webpack 5
+- **Markdown:** MDX support
+- **Diagrams:** Mermaid.js
+- **Search:** Algolia DocSearch (optional)
+
+### Performance
+- **Install time:** ~30 seconds (first time only)
+- **Build time:** ~5-10 seconds (small docs)
+- **Hot reload:** <1 second
+- **Static site:** Fully optimized, lighthouse 100
+
+## See Also
+
+- **specweave-docs** skill - General documentation workflows
+- **spec-generator** skill - Generate living docs specs
+- **sync-docs** skill - Sync docs after increments
+- **Docusaurus docs:** https://docusaurus.io