v4 docs --- mkdocs to docusaurus migration

.claude/skills/generate-llms-catalog/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: generate-llms-catalog
+description: >-
+  Generate llms.txt and catalog.json files for LLM consumption from the
+  Bactopia docs site content. Run this skill whenever documentation content
+  is added, removed, or updated, when the user asks to regenerate the LLM
+  catalog, refresh llms.txt, update the LLM index, or sync the static LLM
+  files with the current documentation.
+---
+
+# Generate LLMs Catalog
+
+Regenerate `static/llms.txt` and `static/catalog.json` from all documentation
+content files. These files provide machine-readable indexes of the Bactopia
+documentation for LLM consumption.
+
+- `llms.txt` follows the [llms.txt standard](https://llmstxt.org/)
+- `catalog.json` provides structured metadata (title, description, tags, URL) per page
+
+## Steps
+
+### 1. Run the generator
+
+```bash
+python bin/generate-llms-catalog.py
+```
+
+Or via Make:
+
+```bash
+make llms-catalog
+```
+
+The script walks all 6 content areas (docs, bactopia-tools, bactopia-pipelines,
+developers, impact, blog), parses YAML frontmatter from each `.md`/`.mdx` file,
+and generates both output files.
+
+Expected output:
+
+```
+Collecting Bactopia...
+  7 pages
+Collecting Bactopia Tools...
+  68 pages
+Collecting Bactopia Pipelines...
+  4 pages
+Collecting Developers...
+  221 pages
+Collecting Impact & Outreach...
+  5 pages
+Collecting Blog...
+  2 pages
+
+Wrote static/llms.txt
+Wrote static/catalog.json
+
+Total: 307 pages across 6 sections
+```
+
+### 2. Verify output
+
+Check that both files were generated correctly:
+
+- `static/llms.txt` -- should have `# Bactopia` heading, blockquote tagline,
+  section headings matching the navbar, and one `- [Title](URL): description`
+  entry per page
+- `static/catalog.json` -- should be valid JSON with `site`, `generated`,
+  `total_pages`, and `sections` array. Each section should have `pages` with
+  `title`, `description`, `url`, `path`, `tags`, and `source_file`
+
+### 3. Build check
+
+Run `npm run build` to confirm the site builds with the new static files.
+Both should be served at the site root:
+
+- `https://bactopia.github.io/llms.txt`
+- `https://bactopia.github.io/catalog.json`

.claude/skills/generate-skills-docs/SKILL.md

@@ -0,0 +1,184 @@
+---
+name: generate-skills-docs
+description: >-
+  Generate the AI Skills reference page for the Bactopia docs site.
+  Runs a Python parser to extract structured metadata from the bactopia repo's
+  SKILL.md files, then generates developers/ai-skills/index.mdx with an overview
+  table and per-skill entries. Use this skill whenever skills are added,
+  removed, or updated in the bactopia repo, when the user asks to regenerate
+  the skills docs page, refresh the skills reference, update the AI skills
+  documentation, or sync the docs site with the current set of bactopia skills.
+---
+
+# Generate Skills Docs
+
+Regenerate the AI Skills reference page (`developers/ai-skills/index.mdx`) from the
+SKILL.md files in the bactopia repo. This skill combines a deterministic Python
+parser for structured extraction with Claude's ability to synthesize
+natural-language content (when-to-use bullets, examples, related skills).
+
+## Steps
+
+### 1. Run the parser
+
+Run `bin/generate-skills.py` to extract structured metadata from all SKILL.md files:
+
+```bash
+python bin/generate-skills.py /home/rpetit3/repos/bactopia/bactopia/.claude/skills --json
+```
+
+If the user provides a different bactopia repo path, substitute it. The script outputs
+JSON with this shape per skill:
+
+```json
+{
+  "name": "skill-name",
+  "description": "Full description from frontmatter",
+  "first_sentence": "First sentence of description.",
+  "summary": "First paragraph of the markdown body.",
+  "category": "Scaffolding|Maintenance|Review & Quality|Testing|Project",
+  "cli_command": "bactopia-*",
+  "cli_page": "/developers/cli/bactopia-*"
+}
+```
+
+### 2. Generate the MDX page
+
+Using the JSON output, write `developers/ai-skills/index.mdx` with this structure:
+
+#### Frontmatter
+
+```yaml
+---
+title: AI Skills
+description: Reference for AI skills that automate Bactopia development tasks
+---
+```
+
+#### Page body
+
+Follow this outline exactly:
+
+```markdown
+# AI Skills
+
+[intro paragraph -- see below]
+
+## Overview
+
+[summary table of all skills]
+
+## Scaffolding
+
+[skills with add-* prefix]
+
+## Maintenance
+
+[skills with update-*/merge-* prefix]
+
+## Review & Quality
+
+[skills with review-* prefix]
+
+## Testing
+
+[skills with run-* prefix]
+
+## Project
+
+[skills with project-* prefix]
+```
+
+#### Intro paragraph
+
+Write 2-3 sentences explaining:
+- These skills automate common Bactopia development tasks through AI-assisted coding tools
+- Each skill wraps one or more bactopia-py CLI commands with interactive guidance
+- Skills live in the bactopia repo at `.claude/skills/` and are invoked with `/skill-name`
+
+Include a link: `[View skills on GitHub](https://github.com/bactopia/bactopia/tree/main/.claude/skills)`
+
+#### Overview table
+
+```markdown
+| Skill | Category | Description |
+|-------|----------|-------------|
+| [`/add-bactopia-tool`](#add-bactopia-tool) | Scaffolding | First sentence from description... |
+```
+
+Use the `first_sentence` field from the JSON. Link each skill name to its heading
+anchor on the same page.
+
+#### Per-skill entries
+
+For each skill, write an entry under its category heading:
+
+```markdown
+### `/skill-name`
+
+[summary -- first paragraph from the SKILL.md body]
+
+**Wraps:** [`bactopia-command`](/developers/cli/bactopia-command)
+
+**When to use:**
+- [2-3 bullet points extracted from the description's trigger phrases]
+- [Focus on the "Use when asked to..." patterns in the description]
+
+**Examples:**
+\`\`\`
+/skill-name argument1
+/skill-name argument2
+\`\`\`
+
+**Related skills:** [`/sibling`](#sibling), [`/other`](#other)
+```
+
+Guidelines for each field:
+
+- **Summary**: Use the `summary` field from JSON (first paragraph of body).
+  Keep it to 1-2 sentences. If the summary is too long, trim to the essential point.
+- **Wraps**: Link to the CLI Reference page using the `cli_page` field.
+- **When to use**: Extract from the `description` field. Look for phrases like
+  "Use when asked to...", "Use this skill whenever...", or the comma-separated
+  list of trigger contexts. Convert to 2-3 concise bullet points.
+- **Examples**: Create 2-3 realistic invocation examples. For skills that take
+  a component name (like `/run-tests` or `/update-module`), show examples with
+  different component names. For skills with no arguments (like `/project-status`),
+  show just the bare invocation.
+- **Related skills**: Cross-reference skills that are commonly used together.
+  Use these relationships:
+  - `add-bactopia-tool` <-> `add-module`, `add-subworkflow`, `run-tests`, `update-catalog`
+  - `add-module` <-> `add-bactopia-tool`, `add-subworkflow`
+  - `add-subworkflow` <-> `add-bactopia-tool`, `add-module`
+  - `update-module` <-> `merge-schemas`, `project-status`
+  - `update-catalog` <-> `project-status`, `merge-schemas`
+  - `merge-schemas` <-> `update-module`, `update-catalog`
+  - `review-groovydoc` <-> `review-citations`, `review-docs`
+  - `review-citations` <-> `review-groovydoc`, `review-docs`
+  - `review-docs` <-> `review-groovydoc`, `review-citations`, `project-status`
+  - `review-tests` <-> `run-tests`
+  - `run-tests` <-> `review-tests`
+  - `project-status` <-> `update-catalog`, `run-tests`
+
+### 3. Verify sidebar and index
+
+Check that `sidebars-developers.ts` includes `'ai-skills'` after
+`'nf-bactopia/index'`. If not, add it.
+
+Check that `developers/index.mdx` has an "AI Skills" section between
+"nf-bactopia Plugin" and "Subworkflows". If not, add:
+
+```markdown
+## AI Skills
+
+Automation skills that orchestrate Bactopia CLI commands through AI-assisted
+coding tools for scaffolding, maintenance, review, and testing tasks.
+
+[Browse AI Skills](/developers/ai-skills)
+```
+
+### 4. Build check
+
+Run `npm run build` to confirm the page builds without errors. If there are
+MDX parsing issues, fix them (common culprits: unescaped `<`, `>`, `{`, `}`
+in descriptions).

.github/pull_request_template.md

@@ -0,0 +1,23 @@
+## Summary
+
+<!-- Brief description of what this PR does -->
+
+## Type of Change
+
+- [ ] Content update (new or modified documentation)
+- [ ] Correction (typo, broken link, inaccurate information)
+- [ ] Site infrastructure (config, styling, components, CI/CD)
+- [ ] Auto-generation (templates, scripts, data files)
+
+## Version Impact
+
+- [ ] This change affects the current live version only (no snapshot needed)
+- [ ] A version snapshot should be created before merging (new Bactopia release)
+- [ ] A snapshot rebuild is needed after merging (fix to snapshotted content)
+
+## Checklist
+
+- [ ] Site builds without errors (`npm run build`)
+- [ ] Changes verified in the dev server (`npm start`)
+- [ ] `snapshots.json` updated (if adding/removing a version)
+- [ ] LLM catalog regenerated (`make llms-catalog`) if pages were added/removed/renamed

.github/workflows/create-snapshot.yml

@@ -0,0 +1,97 @@
+name: Create Version Snapshot
+
+on:
+  workflow_dispatch:
+    inputs:
+      version:
+        description: 'Version tag (e.g., v4.0.0)'
+        required: true
+      bactopia_ref:
+        description: 'bactopia/bactopia ref to checkout (branch, tag, or SHA)'
+        required: false
+        default: 'main'
+
+jobs:
+  create-snapshot:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Checkout docs repo
+        uses: actions/checkout@v4
+
+      - name: Checkout bactopia source repo
+        uses: actions/checkout@v4
+        with:
+          repository: bactopia/bactopia
+          path: bactopia-source
+          ref: ${{ inputs.bactopia_ref }}
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install Python dependencies
+        run: pip install -r requirements.txt
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install Node dependencies
+        run: npm ci
+
+      - name: Generate docs from bactopia source
+        run: make generate BACTOPIA_REPO=bactopia-source
+        env:
+          BACTOPIA_DEV_PYTHON: python
+
+      - name: Build snapshot with version banner
+        run: npm run build
+        env:
+          DOCS_VERSION: ${{ inputs.version }}
+
+      - name: Report snapshot file count
+        run: |
+          count=$(find build -type f | wc -l)
+          echo "Snapshot file count: $count"
+          echo "SNAPSHOT_FILES=$count" >> "$GITHUB_ENV"
+
+      - name: Push snapshot to orphan branch
+        run: |
+          cd build
+          git init
+          git checkout --orphan "snapshot/${{ inputs.version }}"
+          git add -A
+          git -c user.name="github-actions" -c user.email="github-actions@github.com" \
+            commit -m "Snapshot ${{ inputs.version }} (${{ env.SNAPSHOT_FILES }} files)"
+          git remote add origin "https://x-access-token:${{ secrets.GITHUB_TOKEN }}@github.com/${{ github.repository }}.git"
+          git push origin "snapshot/${{ inputs.version }}" --force
+          echo "Pushed snapshot/${{ inputs.version }} (${{ env.SNAPSHOT_FILES }} files)"
+
+      - name: Update snapshots.json on master
+        run: |
+          python3 -c "
+          import json, sys
+          f = 'snapshots.json'
+          d = json.load(open(f))
+          v = '${{ inputs.version }}'
+          n = int('${{ env.SNAPSHOT_FILES }}')
+          # Update existing entry or add new one
+          existing = [s for s in d['snapshots'] if s['version'] == v]
+          if existing:
+              existing[0]['files'] = n
+              existing[0]['active'] = True
+              print(f'Updated {v} (files={n})')
+          else:
+              d['snapshots'].insert(0, {'version': v, 'branch': f'snapshot/{v}', 'files': n, 'active': True})
+              print(f'Added {v} (files={n})')
+          json.dump(d, open(f, 'w'), indent=2)
+          "
+          git add snapshots.json
+          git -c user.name="github-actions" -c user.email="github-actions@github.com" \
+            commit -m "add ${{ inputs.version }} to snapshots.json (${{ env.SNAPSHOT_FILES }} files)"
+          git push