specweave 1.0.256 → 1.0.259

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

@@ -1,103 +1,171 @@
 ---
-description: Browse and load SpecWeave living docs (public, internal, architecture, ADRs). Use when saying "show docs", "browse docs", "find docs about", "load docs", or "read ADR".
-argument-hint: "[topic] [--public] [--internal] [--adr] [--list]"
+description: Documentation hub - browse, search, serve living docs. Use for "show docs", "browse docs", "find docs", "load docs", "read ADR", "serve docs", "preview docs", "docs status".
+argument-hint: "[topic] [--serve] [--status] [--public] [--internal] [--adr] [--list]"
 ---
 
-# Living Docs Browser
+# Documentation Hub
 
 ## Project Overrides
 
 !`s="docs"; for d in .specweave/skill-memories .claude/skill-memories "$HOME/.claude/skill-memories"; do p="$d/$s.md"; [ -f "$p" ] && awk '/^## Learnings$/{ok=1;next}/^## /{ok=0}ok' "$p" && break; done 2>/dev/null; true`
 
-Browse, search, and load SpecWeave living documentation into the conversation.
+Browse, search, load, and serve SpecWeave living documentation.
 
-## Documentation Structure
+## Config-Driven Directories
 
+Read configured doc directories before any operation:
+
+```bash
+# Read configured doc directories (default: .specweave/docs)
+DOC_DIRS=$(jq -r '(.documentation.directories // [".specweave/docs"])[]' .specweave/config.json 2>/dev/null)
+[ -z "$DOC_DIRS" ] && DOC_DIRS=".specweave/docs"
 ```
-.specweave/docs/
-  public/          # User-facing docs (guides, workflows, troubleshooting, API)
-  internal/        # Developer docs (specs, architecture, ADRs, operations)
-```
+
+All search/list commands below MUST iterate over `$DOC_DIRS` instead of hardcoding `.specweave/docs`.
 
 ## Behavior
 
-### 1. No arguments or `--list`: Show available topics
+### 1. No arguments: Show documentation dashboard
+
+Run these diagnostic commands:
 
 ```bash
-echo "=== Public Docs ==="
-ls .specweave/docs/public/ 2>/dev/null || echo "(none)"
+# Read configured doc directories
+DOC_DIRS=$(jq -r '(.documentation.directories // [".specweave/docs"])[]' .specweave/config.json 2>/dev/null)
+[ -z "$DOC_DIRS" ] && DOC_DIRS=".specweave/docs"
+
+# Count documents across all directories
+DOC_COUNT=0
+for dir in $DOC_DIRS; do
+  if [ -d "$dir" ]; then
+    C=$(find "$dir" -name "*.md" -type f 2>/dev/null | wc -l | tr -d ' ')
+    DOC_COUNT=$((DOC_COUNT + C))
+  fi
+done
+echo "DOC_COUNT:$DOC_COUNT"
+
+# Check Docusaurus install status
+[ -d ".specweave/docs-site-internal/node_modules" ] && echo "DOCUSAURUS:installed" || echo "DOCUSAURUS:not_installed"
+
+# Check if docs server is running
+SERVER_INFO=$(lsof -i :3000-3010 -sTCP:LISTEN 2>/dev/null | grep -i node | head -1 | awk '{print $9}' | cut -d: -f2)
+[ -n "$SERVER_INFO" ] && echo "SERVER:running:$SERVER_INFO" || echo "SERVER:stopped"
+
+# List topics per directory
+for dir in $DOC_DIRS; do
+  echo "=== $dir ==="
+  if [ -d "$dir/public" ]; then
+    echo "  Public:"
+    ls "$dir/public/" 2>/dev/null || echo "  (none)"
+  fi
+  if [ -d "$dir/internal" ]; then
+    echo "  Internal:"
+    ls "$dir/internal/" 2>/dev/null || echo "  (none)"
+  fi
+  if [ -d "$dir/internal/architecture/adr" ]; then
+    echo "  ADRs:"
+    ls "$dir/internal/architecture/adr/" 2>/dev/null || echo "  (none)"
+  fi
+  # For non-standard directories (e.g., docs/), list top-level folders
+  if [ "$dir" != ".specweave/docs" ] && [ -d "$dir" ]; then
+    echo "  Folders:"
+    ls -d "$dir"/*/ 2>/dev/null | xargs -I{} basename {} || echo "  (none)"
+  fi
+done
+```
 
-echo ""
-echo "=== Internal Docs ==="
-ls .specweave/docs/internal/ 2>/dev/null || echo "(none)"
+Present as a clean dashboard.
 
-echo ""
-echo "=== Architecture ==="
-ls .specweave/docs/internal/architecture/ 2>/dev/null || echo "(none)"
+**Then ALWAYS include serve guidance** (same as `--serve` behavior):
+- If server is already running: "Docs server running at http://localhost:<port>"
+- If server is NOT running: Show the `specweave docs preview` instructions (see section 4 below)
 
-echo ""
-echo "=== ADRs ==="
-ls .specweave/docs/internal/architecture/adr/ 2>/dev/null || echo "(none)"
-```
+This ensures every `/sw:docs` invocation gives the user a clear path to browse docs in their browser.
+
+### 2. `--list`: List topics only
 
-Present as a clean table with folder names and brief descriptions.
+Same as dashboard but skip server/Docusaurus diagnostics. Just list folder names with descriptions.
 
-### 2. Topic argument: Load relevant docs
+### 3. Topic argument: Search and load docs
 
 When user provides a topic (e.g., `/sw:docs sync`, `/sw:docs troubleshooting`):
 
-1. **Search** for matching docs:
+1. **Search** across all configured directories:
    ```bash
-   # Find matching directories
-   find .specweave/docs -type d -iname "*<topic>*" -maxdepth 4
-
-   # Find matching files
-   find .specweave/docs -type f -iname "*<topic>*.md" -maxdepth 5
+   DOC_DIRS=$(jq -r '(.documentation.directories // [".specweave/docs"])[]' .specweave/config.json 2>/dev/null)
+   [ -z "$DOC_DIRS" ] && DOC_DIRS=".specweave/docs"
+   for dir in $DOC_DIRS; do
+     find "$dir" -type d -iname "*<topic>*" -maxdepth 4 2>/dev/null
+     find "$dir" -type f -iname "*<topic>*.md" -maxdepth 5 2>/dev/null
+   done
    ```
 
 2. **If found**: Read the most relevant files (up to 3-5) and present a summary
 3. **If not found**: Search file contents with Grep for the topic keyword, then present matches
 
-### 3. Flags
+### 4. `--serve` or serve intent: Browser preview guide
+
+Detect serve intent from: `--serve`, `--preview`, or phrases like "serve", "preview", "browser", "open docs", "start server".
+
+1. Check if server is already running:
+   ```bash
+   lsof -i :3000-3010 -sTCP:LISTEN 2>/dev/null | grep -i node
+   ```
+
+2. **If running**: "Docs server already running at http://localhost:<port>"
+3. **If not running**: Display:
+   ```
+   To view docs in browser with hot reload, run in your terminal:
+
+     specweave docs preview
+
+   First run auto-installs Docusaurus (~30-60 seconds).
+   Subsequent runs start instantly.
+
+   Options:
+     specweave docs preview --port 3005   Use specific port
+     specweave docs preview --no-browser  Don't auto-open browser
+
+   To stop: Ctrl+C in terminal, or: specweave docs kill
+   ```
+
+### 5. `--status`: Full status report
+
+Run and display output of:
+```bash
+specweave docs status
+```
+
+### 6. Flags
 
 | Flag | Behavior |
 |------|----------|
 | `--public` | Only search public docs |
 | `--internal` | Only search internal docs |
 | `--adr` | List and load ADRs specifically |
-| `--list` | Just list available topics, don't load content |
+| `--list` | List topics without diagnostics |
+| `--serve` | Browser preview guide |
+| `--status` | Run `specweave docs status` |
 
-### 4. ADR Mode (`--adr` or "ADR" in topic)
+### 7. ADR Mode (`--adr` or "ADR" in topic)
 
-List all ADRs with their titles:
+List all ADRs with their titles across all directories:
 ```bash
-for f in .specweave/docs/internal/architecture/adr/*.md; do
-  echo "$(basename "$f"): $(head -1 "$f" | sed 's/^# //')"
+DOC_DIRS=$(jq -r '(.documentation.directories // [".specweave/docs"])[]' .specweave/config.json 2>/dev/null)
+[ -z "$DOC_DIRS" ] && DOC_DIRS=".specweave/docs"
+for dir in $DOC_DIRS; do
+  for f in "$dir"/internal/architecture/adr/*.md; do
+    [ -f "$f" ] && echo "$(basename "$f"): $(head -1 "$f" | sed 's/^# //')"
+  done
 done
 ```
 
 If a specific ADR number is given, read and present it.
 
-## Output Format
+## Output Footer
+
+Always append to any output:
 
-When listing topics:
 ```
-Living Docs
-
-  Public:
-    guides/          - Getting started, core concepts, mobile
-    workflows/       - Development workflows
-    troubleshooting/ - Common issues and fixes
-    api/             - API documentation
-    integrations/    - External tool integration guides
-
-  Internal:
-    specs/           - Feature specifications
-    architecture/    - ADRs, HLD, diagrams, concepts
-    operations/      - Operational runbooks
-    repos/           - Repository module documentation
-
-  Use: /sw:docs <topic> to load specific docs
+Tip: Run `specweave docs preview` in your terminal to view all docs in browser with hot reload.
 ```
-
-When loading docs, present content with clear headers and file paths for reference.