specweave 0.30.17 → 0.30.19

package/plugins/specweave-docs/commands/preview.md

@@ -1,135 +1,229 @@
 ---
 name: specweave-docs:preview
-description: Launch Docusaurus documentation server. Supports both public (port 3016) and internal (port 3015) documentation sites.
+description: Launch Docusaurus documentation server for internal living docs. Auto-setup on first run. Port 3015.
 ---
 
 # Documentation Preview Command
 
 Launch Docusaurus development server with hot reload, Mermaid diagrams, and auto-generated sidebar.
 
-## Usage
-
-```bash
-# Preview INTERNAL docs (SpecWeave living documentation) - DEFAULT
-/specweave-docs:preview
+## Your Task
 
-# Preview PUBLIC docs (end-user documentation)
-/specweave-docs:preview --public
-```
+**IMPORTANT**: This command must work in ANY SpecWeave user project, not just the SpecWeave repo itself.
 
-## Two Documentation Sites
+### Step 1: Check Prerequisites
 
-| Site | Port | Content | NPM Script |
-|------|------|---------|------------|
-| **Internal** | 3015 | `.specweave/docs/internal/` | `docs:internal` |
-| **Public** | 3016 | `docs-site/docs/` | `docs:dev` |
+```bash
+# Verify internal docs exist
+ls -la .specweave/docs/internal/
 
-## Your Task
+# If missing, inform user:
+# "No internal documentation found at .specweave/docs/internal/.
+#  Run 'specweave init' first or create the folder structure."
+```
 
-Execute the appropriate npm script based on user flags:
+### Step 2: Check for Cached Installation
 
 ```bash
-# Check if user wants public docs
-PUBLIC_FLAG="${1:-}"
-
-cd /path/to/project
-
-if [ "$PUBLIC_FLAG" = "--public" ]; then
-  echo "Launching PUBLIC documentation on port 3016..."
-  echo "Content: docs-site/docs/"
-  echo ""
-  npm run docs:dev
+# Check if Docusaurus is already set up in cache
+if [ -d ".specweave/cache/docs-site/node_modules" ]; then
+  echo "✓ Docusaurus installation found in cache"
+  NEEDS_INSTALL=false
 else
-  echo "Launching INTERNAL documentation on port 3015..."
-  echo "Content: .specweave/docs/internal/"
-  echo ""
-  npm run docs:internal
+  echo "⚙ First-time setup: Installing Docusaurus (~30 seconds)..."
+  NEEDS_INSTALL=true
 fi
 ```
 
-### Alternative: Run directly with npx
+### Step 3: First-Time Setup (if needed)
 
-If in a fresh project without the docs-site setup:
+If `NEEDS_INSTALL=true`, create the cached Docusaurus installation:
 
 ```bash
-# For internal docs
-cd docs-site && npm run start:internal
-
-# For public docs
-cd docs-site && npm run start
+# Create cache directory
+mkdir -p .specweave/cache/docs-site
+
+# Create package.json
+cat > .specweave/cache/docs-site/package.json << 'EOF'
+{
+  "name": "specweave-docs-preview",
+  "version": "1.0.0",
+  "private": true,
+  "scripts": {
+    "start": "docusaurus start --port 3015",
+    "build": "docusaurus build",
+    "clear": "docusaurus clear"
+  },
+  "dependencies": {
+    "@docusaurus/core": "^3.9.2",
+    "@docusaurus/preset-classic": "^3.9.2",
+    "@docusaurus/theme-mermaid": "^3.9.2",
+    "@mdx-js/react": "^3.0.0",
+    "clsx": "^2.0.0",
+    "prism-react-renderer": "^2.3.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "engines": {
+    "node": ">=20.0"
+  }
+}
+EOF
+
+# Create Docusaurus config pointing to internal docs
+cat > .specweave/cache/docs-site/docusaurus.config.ts << 'EOF'
+import {themes as prismThemes} from 'prism-react-renderer';
+import type {Config} from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
+
+const config: Config = {
+  title: 'Internal Documentation',
+  tagline: 'SpecWeave Living Documentation',
+  favicon: 'img/favicon.ico',
+  future: { v4: true },
+  url: 'http://localhost:3015',
+  baseUrl: '/',
+  onBrokenLinks: 'warn',
+  onBrokenMarkdownLinks: 'warn',
+  i18n: { defaultLocale: 'en', locales: ['en'] },
+  markdown: { mermaid: true, format: 'md' },
+  themes: ['@docusaurus/theme-mermaid'],
+  presets: [
+    [
+      'classic',
+      {
+        docs: {
+          // Path relative to this config file → ../../docs/internal/
+          path: '../../docs/internal',
+          routeBasePath: '/',
+          sidebarPath: './sidebars.ts',
+          showLastUpdateTime: true,
+          sidebarCollapsible: true,
+          sidebarCollapsed: true,
+        },
+        blog: false,
+        theme: { customCss: './src/css/custom.css' },
+      } satisfies Preset.Options,
+    ],
+  ],
+  themeConfig: {
+    colorMode: {
+      defaultMode: 'dark',
+      disableSwitch: false,
+      respectPrefersColorScheme: true,
+    },
+    navbar: {
+      title: 'Internal Docs',
+      items: [
+        {to: '/', label: 'Home', position: 'left'},
+        {type: 'search', position: 'right'},
+      ],
+    },
+    footer: {
+      style: 'dark',
+      copyright: `SpecWeave Living Documentation`,
+    },
+    prism: {
+      theme: prismThemes.github,
+      darkTheme: prismThemes.dracula,
+      additionalLanguages: ['bash', 'typescript', 'yaml', 'json'],
+    },
+    mermaid: { theme: {light: 'neutral', dark: 'dark'} },
+  } satisfies Preset.ThemeConfig,
+};
+
+export default config;
+EOF
+
+# Create auto-generated sidebar
+cat > .specweave/cache/docs-site/sidebars.ts << 'EOF'
+import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
+
+const sidebars: SidebarsConfig = {
+  docs: [
+    {
+      type: 'autogenerated',
+      dirName: '.',
+    },
+  ],
+};
+
+export default sidebars;
+EOF
+
+# Create minimal CSS
+mkdir -p .specweave/cache/docs-site/src/css
+cat > .specweave/cache/docs-site/src/css/custom.css << 'EOF'
+:root {
+  --ifm-color-primary: #2563eb;
+  --ifm-code-font-size: 95%;
+}
+[data-theme='dark'] {
+  --ifm-color-primary: #60a5fa;
+}
+EOF
+
+# Create static folder with placeholder favicon
+mkdir -p .specweave/cache/docs-site/static/img
+echo '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text y=".9em" font-size="90">📚</text></svg>' > .specweave/cache/docs-site/static/img/favicon.ico
+
+# Install dependencies using PUBLIC npm registry (avoids Azure DevOps/private registry issues)
+cd .specweave/cache/docs-site && npm install --registry=https://registry.npmjs.org --legacy-peer-deps
 ```
 
-## What You Get
-
-- **Hot reload** - Edit markdown, see changes instantly
-- **Auto sidebar** - Generated from folder structure
-- **Mermaid diagrams** - Architecture diagrams render beautifully
-- **Dark/light mode** - Toggle in navbar
-- **Local search** - Instant search across all docs
-- **Mobile responsive** - Works on any device
-
-## First-Time Setup
-
-If `docs-site/node_modules` doesn't exist:
+### Step 4: Start the Server
 
 ```bash
-npm run docs:install
+cd .specweave/cache/docs-site && npm start
 ```
 
-This installs Docusaurus dependencies (~200MB, ~30 seconds).
-
-## Ports
+This will:
+- Start Docusaurus on **http://localhost:3015**
+- Enable hot reload (edit markdown, see changes instantly)
+- Render Mermaid diagrams
+- Auto-generate sidebar from folder structure
 
-| Script | Port | URL |
-|--------|------|-----|
-| `docs:dev` | 3016 | http://localhost:3016 |
-| `docs:internal` | 3015 | http://localhost:3015 |
+### Output to User
 
-## Internal Docs Structure
+After starting, display:
 
 ```
-.specweave/docs/internal/
-├── strategy/        → Product strategy
-├── specs/           → Feature specifications (708 files!)
-│   └── specweave/
-│       ├── FS-001/  → Feature folders
-│       ├── FS-002/
-│       └── ...
-├── architecture/    → ADRs, HLDs, diagrams
-├── delivery/        → Release plans, guides
-├── operations/      → Runbooks, NFRs
-└── governance/      → Standards, conventions
+📚 Documentation Preview Server Started!
+
+   URL: http://localhost:3015
+   Content: .specweave/docs/internal/
+
+   Features:
+   • Hot reload - edit markdown, see changes instantly
+   • Mermaid diagrams - architecture diagrams render beautifully
+   • Auto sidebar - generated from folder structure
+   • Dark/light mode - toggle in navbar
+
+   Press Ctrl+C to stop the server.
 ```
 
-## Configuration Files
+## What You Get
 
-| File | Purpose |
-|------|---------|
-| `docusaurus.config.ts` | Public docs config |
-| `docusaurus.config.internal.ts` | Internal docs config |
-| `sidebars.ts` | Public docs sidebar |
-| `sidebars.internal.ts` | Internal docs sidebar |
+- **Hot reload** - Edit markdown, see changes instantly
+- **Auto sidebar** - Generated from folder structure
+- **Mermaid diagrams** - Architecture diagrams render beautifully
+- **Dark/light mode** - Toggle in navbar
+- **Local search** - Instant search across all docs
 
 ## Troubleshooting
 
 ### Port already in use
 ```bash
-# Find process using port
-lsof -i :3015
-
-# Kill it
-kill -9 <PID>
+lsof -i :3015 && kill -9 $(lsof -t -i :3015)
 ```
 
-### Missing dependencies
+### Reinstall from scratch
 ```bash
-npm run docs:install
+rm -rf .specweave/cache/docs-site && /specweave-docs:preview
 ```
 
-### Build errors
-```bash
-cd docs-site && npm run clear && npm run start:internal
-```
+### npm registry issues
+The setup uses `--registry=https://registry.npmjs.org` to bypass private registry configurations.
 
 ## See Also
 

package/plugins/specweave-docs/skills/preview/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 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.
+description: Documentation preview expert for Docusaurus integration. Launches interactive preview server for SpecWeave living documentation with hot reload, auto-generated sidebar, and Mermaid diagrams. Works in ANY SpecWeave project with auto-setup. Activates for preview docs, view documentation, Docusaurus server, docs UI, documentation website, local docs server, hot reload docs, static site build.
 ---
 
 # Documentation Preview Skill
@@ -9,27 +9,26 @@ Expert in launching and managing Docusaurus documentation preview for SpecWeave
 
 ## What I Do
 
-I help you preview and build your SpecWeave living documentation with Docusaurus:
+I help you preview your SpecWeave living documentation with Docusaurus:
 
-### 1. Interactive Preview
-- Launch local development server (default port: 3016)
-- Auto-generate sidebar from folder structure
-- Hot reload - edit markdown, see changes instantly
-- Mermaid diagram rendering
-- Mobile-responsive UI
-- Search functionality
+### Key Features
+- **Zero-config setup** - Works in any SpecWeave project automatically
+- **Cached installation** - Docusaurus cached in `.specweave/cache/docs-site/` (gitignored)
+- **Hot reload** - Edit markdown, see changes instantly
+- **Mermaid diagrams** - Architecture diagrams render beautifully
+- **Auto sidebar** - Generated from folder structure
+- **Bypasses private registries** - Uses public npm to avoid Azure DevOps/corporate issues
 
-### 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
+## How It Works
 
-### 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
+1. **First run (~30 seconds)**:
+   - Creates Docusaurus in `.specweave/cache/docs-site/`
+   - Installs dependencies from public npm registry
+   - Configures to read from `.specweave/docs/internal/`
+
+2. **Subsequent runs (instant)**:
+   - Uses cached installation
+   - Starts server immediately
 
 ## Available Commands
 
@@ -39,11 +38,10 @@ I help you preview and build your SpecWeave living documentation with Docusaurus
 ```
 
 **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 3016 (configurable)
-4. Opens browser automatically
-5. Enables hot reload
+1. Checks if `.specweave/docs/internal/` exists
+2. Sets up Docusaurus in cache (if first run)
+3. Starts dev server on **http://localhost:3015**
+4. Enables hot reload
 
 ### Build Static Site
 ```bash
@@ -51,55 +49,46 @@ I help you preview and build your SpecWeave living documentation with Docusaurus
 ```
 
 **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
+1. Builds production-ready static site
+2. Outputs to `.specweave/cache/docs-site/build/`
+3. Ready for deployment to any static host
 
 ## 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"
+### Activate for:
+- "Preview my documentation"
+- "Show me my docs in a browser"
+- "Launch Docusaurus"
 - "View my living documentation"
 - "Start docs preview"
-- "Build static docs site"
+- "I want to see my internal docs"
 
-### Common workflows:
+### Workflow
 
-**1. First-time preview:**
 ```
 User: "I want to preview my docs"
-You: "I'll set up the documentation preview with Docusaurus."
+You: "I'll launch the documentation preview server."
      [Run: /specweave-docs:preview]
 ```
 
-**2. Build for deployment:**
-```
-User: "I need to deploy my docs"
-You: "I'll build the static site for deployment."
-     [Run: /specweave-docs:build]
+## Troubleshooting
+
+### Port 3015 already in use
+```bash
+lsof -i :3015 && kill -9 $(lsof -t -i :3015)
 ```
 
-## Configuration
-
-```json
-{
-  "documentation": {
-    "preview": {
-      "enabled": true,
-      "autoInstall": true,
-      "port": 3016,
-      "openBrowser": true,
-      "theme": "default"
-    }
-  }
-}
+### Reinstall from scratch
+```bash
+rm -rf .specweave/cache/docs-site
+# Then run /specweave-docs:preview again
 ```
 
+### npm registry issues
+The setup explicitly uses `--registry=https://registry.npmjs.org` to bypass private/corporate registry configurations.
+
 ## See Also
 
+- `/specweave-docs:build` - Build static site for deployment
 - `/specweave-docs:organize` - Organize large folders with themed indexes
 - `/specweave-docs:health` - Documentation health report
-- `/specweave-docs:generate` - Generate docs from code