feat(dx): add docusaurus v3 documentation site with github pages ci/cd

.github/workflows/docs.yml

@@ -0,0 +1,75 @@
+name: Deploy Docs to GitHub Pages
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - '.github/workflows/docs.yml'
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build Docusaurus site
+        run: npm run build
+
+  deploy:
+    needs: build
+    if: github.event_name == 'push' || github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build Docusaurus site
+        run: npm run build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: docs/build
+          publish_branch: gh-pages
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+node_modules
+
+# Build output
+build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/docs/cli-reference/agent.md

@@ -0,0 +1,89 @@
+---
+id: agent
+title: shep agent
+---
+
+# `shep agent`
+
+Manage and run Shep agents. List available agents, check status, and invoke agents directly.
+
+## Synopsis
+
+```bash
+shep agent [subcommand] [options]
+```
+
+## Subcommands
+
+### `shep agent list`
+
+List all available agents.
+
+```bash
+shep agent list
+```
+
+### `shep agent run <agent-name>`
+
+Run an agent directly with a custom prompt.
+
+```bash
+shep agent run code-explorer --prompt "Explain the auth module"
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--prompt <text>` | The prompt to send to the agent |
+| `--file <path>` | Read prompt from a file |
+| `--repo <path>` | Target repository path |
+| `--output <path>` | Save agent output to a file |
+| `--max-steps <n>` | Override maximum steps |
+
+### `shep agent status`
+
+Show the status of currently running agents.
+
+```bash
+shep agent status
+```
+
+### `shep agent stop <id>`
+
+Stop a running agent by ID.
+
+```bash
+shep agent stop abc123
+```
+
+### `shep agent logs <id>`
+
+Stream logs for a running or completed agent.
+
+```bash
+shep agent logs abc123
+shep agent logs abc123 --follow
+```
+
+## Available Agents
+
+| Agent | Description |
+|-------|-------------|
+| `code-explorer` | Analyzes codebase structure and patterns |
+| `code-architect` | Designs implementation plans |
+| `code-developer` | Writes code following plans |
+| `code-reviewer` | Reviews code for quality and bugs |
+
+## Examples
+
+```bash
+# Run the explorer to understand an auth module
+shep agent run code-explorer --prompt "Trace the authentication flow"
+
+# Check what's currently running
+shep agent status
+
+# Stream logs from a running agent
+shep agent logs abc123 --follow
+```

docs/docs/cli-reference/feat.md

@@ -0,0 +1,94 @@
+---
+id: feat
+title: shep feat
+---
+
+# `shep feat`
+
+Create and manage features — the primary way to kick off automated development work.
+
+## Synopsis
+
+```bash
+shep feat [subcommand] [options]
+shep feat "<description>"
+```
+
+## Subcommands
+
+### `shep feat <description>`
+
+Create a new feature from a natural language description.
+
+```bash
+shep feat "Add pagination to the user list endpoint"
+```
+
+Shep will:
+1. Parse the description and create a feature spec
+2. Start the agent pipeline on a new branch
+3. Stream progress to your terminal
+
+**Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--branch <name>` | Custom branch name | Auto-generated |
+| `--no-commit` | Don't commit automatically | `false` |
+| `--dry-run` | Preview without executing | `false` |
+| `--repo <path>` | Path to target repository | Current directory |
+
+### `shep feat list`
+
+List all features in the current repository.
+
+```bash
+shep feat list
+```
+
+**Options:**
+
+| Option | Description |
+|--------|-------------|
+| `--status <status>` | Filter by status (`pending`, `in_progress`, `review`, `complete`) |
+| `--json` | Output as JSON |
+
+### `shep feat show <id>`
+
+Show details for a specific feature.
+
+```bash
+shep feat show 001
+```
+
+### `shep feat run <id>`
+
+Run or re-run a feature's agent pipeline.
+
+```bash
+shep feat run 001
+```
+
+### `shep feat status <id>`
+
+Check the current status of a feature.
+
+```bash
+shep feat status 001
+```
+
+## Examples
+
+```bash
+# Implement a new feature
+shep feat "Add email verification to the signup flow"
+
+# Fix a bug
+shep feat "Fix the 500 error when deleting a user with active sessions"
+
+# Refactor
+shep feat "Extract database connection logic into a singleton service"
+
+# On a specific repo
+shep feat "Add API rate limiting" --repo ~/projects/my-api
+```

docs/docs/cli-reference/ide.md

@@ -0,0 +1,80 @@
+---
+id: ide
+title: shep ide
+---
+
+# `shep ide`
+
+Launch IDE integration for AI-powered coding directly within your editor.
+
+## Synopsis
+
+```bash
+shep ide [subcommand] [options]
+```
+
+## Usage
+
+```bash
+# Launch IDE integration (auto-detects installed IDE)
+shep ide
+
+# Open in a specific IDE
+shep ide --editor cursor
+shep ide --editor vscode
+```
+
+## Subcommands
+
+### `shep ide open`
+
+Open the current repository in an IDE with Shep integration active.
+
+```bash
+shep ide open
+shep ide open ~/projects/my-app
+```
+
+**Options:**
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--editor <name>` | IDE to launch (`cursor`, `vscode`, `windsurf`) | Auto-detect |
+| `--feature <id>` | Open with a specific feature branch checked out | — |
+
+### `shep ide list`
+
+List detected IDEs on your system.
+
+```bash
+shep ide list
+```
+
+### `shep ide config`
+
+Configure IDE integration settings.
+
+```bash
+shep ide config
+```
+
+## Supported IDEs
+
+| IDE | Identifier | Notes |
+|-----|-----------|-------|
+| Cursor | `cursor` | Full AI integration |
+| VS Code | `vscode` | Extension-based integration |
+| Windsurf | `windsurf` | Full AI integration |
+
+## Examples
+
+```bash
+# Auto-detect and launch IDE
+shep ide
+
+# Open a specific feature in Cursor
+shep ide open --editor cursor --feature 005
+
+# Check what IDEs are installed
+shep ide list
+```