docs

What this skill does

# Generate Docusaurus Documentation Site

Transform ADRs and OpenSpec specs (located via the **Artifact Path Resolution** pattern from `references/shared-patterns.md`) into a polished documentation website with:

- RFC 2119 keyword highlighting (MUST, SHALL, MAY, etc.)
- ADR cross-reference linking (ADR-0001 becomes a clickable link)
- SPEC cross-reference linking (PREFIX-NNN links to spec requirement anchors)
- Status/Date/Domain badge components
- Requirement box components for spec tables
- Consequence keyword highlighting (Good/Bad/Neutral) in ADRs
- Dark mode support
- Auto-generated sidebars

Supports two modes:
- **Scaffold mode**: Creates a standalone `docs-site/` with its own Docusaurus installation
- **Integration mode**: Generates a build-time plugin into an existing Docusaurus site

## Process

### Step 0: Resolve Artifact Paths

<!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Artifact Path Resolution" -->

Follow the **Artifact Path Resolution** pattern from `references/shared-patterns.md` to determine the ADR and spec directories. If `$ARGUMENTS` contains `--module <name>`, resolve paths relative to that module; otherwise, in a workspace, aggregate across all modules. The resolved ADR directory is `{adr-dir}` and spec directory is `{spec-dir}`.

<!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Cross-Module Aggregation" -->

**Cross-module aggregation**: When in aggregate mode (no `--module`, workspace detected), include all modules' artifacts in the docs site. Organize the sidebar navigation by module:

```
Architecture/
├── api/
│   ├── ADRs/
│   │   ├── ADR-0001: Choose REST over GraphQL
│   │   └── ADR-0002: Choose PostgreSQL
│   └── Specs/
│       └── SPEC-0001: Web Dashboard
├── worker/
│   ├── ADRs/
│   │   └── ADR-0001: Choose Redis for queues
│   └── Specs/
│       └── SPEC-0001: Job Processing
└── Overview (cross-module index page)
```

Each module's artifacts are transformed independently and placed under a module-named directory in the docs output. The index page lists all modules with artifact counts. When `--module` is provided, generate docs for that single module only (flat structure, no module subdirectory). When in single-module mode (no workspace), operate normally with the existing flat structure.

### Step 1: Pre-flight Checks

- Check if Node.js is installed. If not, tell the user: "Node.js is required to run the docs site. Please install it from https://nodejs.org/ and re-run this command." and stop.
- Check if `{adr-dir}` has any ADR `.md` files
- Check if `{spec-dir}` has any spec directories (containing `spec.md`). Validate spec pairing per `references/shared-patterns.md` § "Spec Pairing Validation".
- If NEITHER has content, tell the user: "No ADRs or specs found. Create some first with `/sdd:adr` or `/sdd:spec`, then re-run `/sdd:docs`." and stop.
- If only one has content, proceed but note which is empty (e.g., "No specs found yet -- the docs site will only include ADRs for now.")

### Step 2: Detect Existing Docusaurus Site and Upgrade State

#### 2.1: Check for upgrade manifest

Check if `.sdd-docs.json` exists at the project root.

**If `.sdd-docs.json` exists:**
- Read and parse the manifest
- Check if the `siteDir` referenced in the manifest still exists on disk
  - **If siteDir exists** → enter **Upgrade Mode** (Step 3C). Skip Steps 2.2 and 2.3.
  - **If siteDir is missing** → warn the user: "Found `.sdd-docs.json` but the site directory `{siteDir}` no longer exists." Use `AskUserQuestion` to offer:
    - "Re-scaffold a new docs site" → proceed with **Scaffold Mode** (Step 3A)
    - "Cancel" → stop

**If `.sdd-docs.json` does NOT exist**, continue to Step 2.2.

#### 2.2: Scan for existing Docusaurus sites

Scan the project root for directories containing `docusaurus.config.ts` or `docusaurus.config.js`:

```bash
find . -maxdepth 2 -name 'docusaurus.config.*' -not -path './docs-site/*' -not -path './node_modules/*' 2>/dev/null
```

#### 2.3: Choose mode

**If an existing docs site directory is detected** (`docs-site/` exists or an integration site was found in 2.2) **but no `.sdd-docs.json`**:
- Warn: "Upgrade tracking unavailable — `.sdd-docs.json` not found."
- Use `AskUserQuestion` to offer:
  - "Create manifest from current state" → compute SHA-256 checksums of all managed files in the existing site, write `.sdd-docs.json` using the current state as baseline, then enter **Upgrade Mode** (Step 3C)
  - "Continue without upgrade tracking" → proceed to mode selection below
  - "Cancel" → stop

**If an existing non-scaffold Docusaurus site is found** (from Step 2.2), use `AskUserQuestion` to let the user choose:
- Option A: "Integrate into {directory}" -- proceed with **Integration Mode** (Step 3B)
- Option B: "Scaffold a new docs site" -- proceed with **Scaffold Mode** (Step 3A)

**If no existing site is found**, proceed directly with **Scaffold Mode** (Step 3A).

---

### Step 3A: Scaffold Mode

Read and follow the plugin's `skills/docs/references/scaffold-mode.md` for the full scaffold workflow. After completion, proceed to Step 4 below.

---

### Step 3B: Integration Mode

Read and follow the plugin's `skills/docs/references/integration-mode.md` for the full integration workflow. After completion, proceed to Step 4 below.

---

### Step 3C: Upgrade Mode

Read and follow the plugin's `skills/docs/references/upgrade-mode.md` for the full upgrade workflow. This handles manifest-based file management, conflict resolution, and new template detection.

---

### Step 4: Create Manifest

Runs after Step 3A or 3B to establish upgrade tracking.

**Determine managed files** based on mode:
- **Scaffold**: files in `docs-site/plugins/sdd-content/`, `docs-site/src/components/`, `docs-site/src/css/`, `docs-site/src/theme/`
- **Integration**: files in `{site}/plugins/sync-spec-docs/`, `{site}/src/components/design-docs/`, `{site}/src/css/design-docs.css`, `{site}/src/theme/MDXComponents.tsx` (if created/modified)

Compute SHA-256 checksum for each file (`shasum -a 256 {file-path}`), then write `.sdd-docs.json`:

```json
{
  "version": "<plugin version from .claude-plugin/plugin.json>",
  "mode": "scaffold" | "integration",
  "siteDir": "<relative path to site dir>",
  "createdAt": "<ISO 8601>",
  "updatedAt": "<ISO 8601>",
  "files": {
    "<relative-path>": { "checksum": "sha256:<hex-digest>", "managed": true }
  }
}
```

Tell the user: "Created `.sdd-docs.json` with {N} tracked files. Future runs of `/sdd:docs` will detect changes and offer upgrades."

---

## Key Template Files Reference

### Scaffold Mode Templates (`templates/docusaurus/`)

The templates directory contains production-ready versions of all files. The `cp -r` approach copies everything; you only need to customize `docusaurus.config.ts` and `package.json`.

#### Docusaurus Plugin (plugins/sdd-content/)
- `index.js` -- Consolidated Docusaurus plugin that:
  - Uses `lib-artifact-transforms` for YAML frontmatter parsing (replaces ~120 lines of custom YAML)
  - Builds the artifact graph per SPEC-0018 edge schema with 5 ADR edge types + 4 spec edge types
  - Generates MDX files from ADRs and specs with badges, RFC 2119 keyword highlighting, cross-references (Governing: ADR-0006, SPEC-0004)
  - Generates index pages (landing page, ADR section, spec section) with sidebar hierarchy diagrams
  - Generates the artifact graph page with stats, full Mermaid flowchart, and orphan lists
  - Implements `getPathsToWatch()` for native Docusaurus hot reload (replaces chokidar-cli + concurrently)

### Integration Mode Templates (`templates/integration/sync-spec-docs/`)

A self-contained Docusaurus plugin with adapted transform scripts.

#### Plugin Entry
- `index.js` -- Docusaurus plugin that runs transforms during `loadContent()` and watches source files via `getPathsToWatch()`

#### Transform Scripts (lib/)
- `transform-adrs.js` -- ADR transforms with parameterized paths
- `transform-openspecs.js` -- OpenSpec transforms with parameterized paths