h4tcher-docusaurus-generator - SKILL.md Agent Skill

name: h4tcher-docusaurus-generator description: Maintainer skill — generate or refresh the hatch3r project documentation site (Docusaurus 3.x) from this repo's canonical corpus (governance/, agents/, skills/, rules/, commands/, hooks/, docs/). Use when a hatch3r maintainer asks to build, regenerate, or update the framework's own docs site. Analyzes the hatch3r repo structure, regenerates markdown into website/docs/, and previews the site. effort: medium allowed-tools: Read Grep Glob Bash(*) Write Edit

Last updated: 2026-06-05

Docusaurus Generator (hatch3r maintainer skill)

This skill refreshes the hatch3r project's own documentation site, which already exists at website/ (Docusaurus 3.x), by re-deriving its pages from this repository's canonical corpus. It is a framework-dev maintainer tool (hence the h4tcher- prefix per CLAUDE.md), not a generic per-project docs generator and not a lifecycle add/refactor/remove preset. It sources content from governance/, agents/, skills/, rules/, commands/, hooks/, and docs/.

The site lives in website/ and deploys to docs.hatch3r.com via .github/workflows/deploy-docs.yml on push to main (paths filter: website/**). There is no docs-site/ directory — operate on website/ directly. Do NOT run npx create-docusaurus: the project is already scaffolded; creating a second project is a P4 (Lean Coverage) violation.

Workflow Overview

Analyze the hatch3r repo corpus to identify what each page must reflect
Map corpus sources to the existing website/docs/** page set and website/sidebars.ts
Regenerate the affected pages in place under website/docs/
Build & Preview via the website's own npm scripts

Step 1: Analyze the hatch3r corpus

Scan this repo to identify what each page must reflect:

CLI surface: the commands under src/cli/commands/ (mirror the npx hatch3r <cmd> help) → website/docs/reference/commands/cli-commands.md
Canonical content: agents/, skills/, rules/, commands/, hooks/ — the artifacts hatch3r ships → the matching website/docs/reference/{agents,skills,rules,hooks}.md pages and reference/commands/agent-commands.md
Governance: governance/VISION.md, CONSTITUTION.md, and the audit-domain set under governance/audit/domains/ → architecture and guide pages (do not lift private governance verbatim; summarize the public-facing behavior)
Existing docs: the docs/ directory and README.md (do not duplicate; link or lift)
Source-of-truth counts: governance/inventory.json counts — page tallies (agents, skills, rules, commands, hooks) must match it

# Key sources to examine in the hatch3r repo
ls src/cli/commands/*.ts
ls agents/ skills/ rules/ commands/ hooks/
ls governance/ docs/
jq '.name, .description' package.json
jq '.counts' governance/inventory.json

Step 2: Map corpus to the existing site

The site's page set and navigation are already defined. Read both before editing so regeneration lands in the right files instead of creating new ones:

# Existing page tree and navigation — read before regenerating
find website/docs -name '*.md' | sort
cat website/sidebars.ts          # docsSidebar: category -> doc-id ordering
cat website/docusaurus.config.ts # routeBasePath 'docs', navbar/footer links, mermaid theme

Current top-level groups in website/sidebars.ts (docsSidebar): about, Getting Started, Guides, Reference (with Architecture and Commands sub-categories), troubleshooting. Every doc id listed in sidebars.ts MUST resolve to a file under website/docs/ — onBrokenLinks: 'throw' and the sidebar-id check fail the build otherwise.

Mapping rule: a corpus change updates the existing page that already documents that surface. Add a new page only when a new artifact class or CLI command has no home; when you add one, add its doc id to the matching category in website/sidebars.ts in the same change.

Step 3: Regenerate pages in place

Rewrite the affected files under website/docs/**. Keep each page's existing frontmatter shape:

---
sidebar_position: 1
title: Page Title
description: Brief description for SEO
---

# Page Title

Content here...

Content guidelines:

Write for hatch3r users (people running npx hatch3r), not framework contributors.
Keep counts and artifact lists synchronized with governance/inventory.json counts.
Link between related docs with relative doc paths (e.g. [workflow](../guides/workflow)), not absolute URLs, so the broken-link check covers them.
Do not duplicate README.md or docs/ prose — link to it or lift the canonical wording once.

Step 4: Author conventions used by this site

The site enables Mermaid (themes: ['@docusaurus/theme-mermaid'], markdown.mermaid: true) and the classic theme's admonitions and tabs. Use them as they already appear in website/docs/:

Mermaid diagrams (architecture/flow pages):
```
```mermaid
graph LR; A --> B
```
```

Admonitions for tips and warnings:

:::tip
Run `npx hatch3r status` to see drift before syncing.
:::

:::warning
`hatch3r clean` removes generated adapter outputs.
:::

Tabs for platform-specific content (the three adapters — Claude Code / Cursor / Copilot):

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
  <TabItem value="claude" label="Claude Code">...</TabItem>
  <TabItem value="cursor" label="Cursor">...</TabItem>
  <TabItem value="copilot" label="Copilot">...</TabItem>
</Tabs>

Static assets go in website/static/img/ and are referenced as /img/filename.png.

Sidebar ordering is driven by website/sidebars.ts (explicit doc-id lists per category), not by sidebar_position alone — update the array when adding or reordering pages.

Step 5: Build & Preview

Use the website's own npm scripts from within website/. The build must pass before the change is done — onBrokenLinks: 'throw' turns any dangling link into a build failure, which is the same gate .github/workflows/deploy-docs.yml and h4tcher-release-prep Step 8 enforce.

cd website

# Install dependencies (lockfile-exact, matching the deploy workflow)
npm ci

# Local dev server with live reload
npm run start

# Production build — fails on broken links; mirrors CI
NODE_OPTIONS=--max-old-space-size=4096 npm run build

# Serve the production build locally to spot-check
npm run serve

If website/ has unstaged edits after regeneration, the maintainer commits them with docs(website): <summary> (release syncs use docs(website): sync to v{version} per h4tcher-release-prep Step 8). This skill stops before commit.