neutral

Phase 15 — Documentation Publishing

Transforms existing developer-facing markdown in docs/manual/ and docs/operations/ into a production-quality Hugo documentation site. Starts with a cleanup pass to bring all 38 documentation files to a consistent standard, then scaffolds a Hugo project using module mounts (no content duplication), generates an API reference from the Huma-served OpenAPI spec, and deploys via GitHub Pages.

Status: Complete Depends on: Phases 1-14 complete (all documented features), Phase 19 complete (tool registry docs) Migrations: None Branch: dev

---

Why Now

With Phases 1-19 complete, Cruvero has 27 manual files and 11 operations files covering every subsystem — but the documentation has three structural problems:

1. Inconsistent quality — Several files are stubs rather than usable documentation. scripts-demos.md (19 lines), templates.md (22 lines), mcp.md (25 lines), and alerts.md (29 lines) lack introductory context, prerequisites, and working examples. testing.md (50 lines) jumps straight into bullet points with no orientation for new readers.
2. Missing structure — config-env.md lists 129+ environment variables in a flat table for the core section, making it hard to find settings for a specific subsystem. cli.md documents 37+ commands with flag definitions but lacks end-to-end workflow examples showing how commands compose. docs/operations/ has no README index.
3. No public docs surface — All documentation lives as raw markdown files in the repository. There is no rendered site, no sidebar navigation, no API reference page, and no search. External operators and contributors must browse the repo tree to find documentation.

Phase 15 solves all three by first cleaning every file to production quality, then publishing them through Hugo with an embedded API reference.

---

Architecture

Hugo module mounts — no content duplication

Hugo's module mount system maps source directories directly into Hugo's content tree. The actual markdown files in docs/manual/ and docs/operations/ remain untouched — Hugo reads them in place.

docs/site/
├── hugo.toml              # Module mounts, theme config, menu
├── layouts/
│   ├── _default/          # Base templates
│   └── shortcodes/        # Custom shortcodes (env-var table, CLI ref)
├── static/
│   └── api/
│       └── openapi.json   # Exported spec (generated, gitignored)
└── content/
    └── api-reference/
        └── _index.md      # Redoc embed page (only manually-authored content page)

Source mapping (hugo.toml module mounts):
  docs/manual/    → content/manual/
  docs/operations/ → content/operations/

Hugo Book theme

The Hugo Book theme provides sidebar navigation, table of contents, and search out of the box. It reads directory structure and _index.md files to build navigation — no separate nav config file to maintain.

OpenAPI reference

The Huma framework already serves the OpenAPI spec at /api-docs/openapi (configured in internal/api/server.go:103). A new cmd/openapi-export CLI builds the Huma API object with all registered routes and writes the spec to a static JSON file without starting the HTTP server. The Hugo site embeds this spec using Redoc standalone (loaded from CDN, no npm dependency).

Dual-format compatibility

All markdown continues to render correctly on GitHub. Hugo-specific features use:

• Front matter (invisible on GitHub)
• Link render hooks (rewrite .md extensions to Hugo paths)
• Shortcodes only in Hugo-only pages (api-reference/_index.md)

No Hugo shortcodes are injected into docs/manual/ or docs/operations/ files.

---

Sub-Phases

Sub-Phase	Name	Prompts	Depends On
15A	Documentation Cleanup	2	—
15B	Hugo Site Foundation	2	15A
15C	API Reference & Cross-Linking	2	15B
15D	CI/CD Pipeline	1	15C

Total: 4 sub-phases, 7 prompts, 2 documentation files

Dependency Graph

15A (Cleanup) → 15B (Hugo Scaffold) → 15C (API Reference) → 15D (CI/CD)

Strictly sequential: each sub-phase builds on the previous.

---

Sub-Phase Details

15A: Documentation Cleanup

Bring all 38 documentation files to production quality before publishing.

Manual docs (27 files):

• Add intro paragraph + "Who this is for" / prerequisites to files lacking them (testing.md, templates.md, overview.md)
• Expand stubs: scripts-demos.md (19→80+ lines), templates.md (22→60+ lines), mcp.md (25→80+ lines), testing.md (50→120+ lines)
• Reorganize config-env.md core section by feature subsystem (agent, memory, tools, embedding, security, quota, temporal, observability) instead of flat list
• Add workflow examples to cli.md showing multi-command sequences (agent run → inspect → replay, supervisor create → monitor → approve)
• Consistent formatting: all files get H1 title, intro paragraph, proper section hierarchy, fenced code blocks with language tags

Operations docs (11 files):

• Create docs/operations/README.md as section index
• Add intro paragraphs and prerequisites to alerts.md (29 lines), checklists, and shorter runbooks
• Ensure all runbooks have "When to use" and "Prerequisites" sections

Cross-cutting:

• Create docs/manual/glossary.md with Cruvero-specific terms (agent, supervisor, tool registry, immune system, quarantine, salience, provenance, etc.)
• Add cross-reference links between related docs (e.g., tools.md ↔ tool-registry-restructure.md, immune.md ↔ runbooks)

15B: Hugo Site Foundation

Scaffold the Hugo project and content mapping.

• Initialize Hugo project at docs/site/ with Hugo Book theme as a Go module
• Configure hugo.toml with module mounts mapping docs/manual/ and docs/operations/ into content tree
• Create _index.md files for each content section (manual, operations, operations/checklists, operations/runbooks)
• Add front matter generation script (scripts/docs/add-frontmatter.sh) that injects Hugo front matter into source markdown without modifying visible content
• Add Makefile targets: make docs-build, make docs-serve, make docs-clean
• Create custom sidebar weight ordering via front matter
• Add .gitignore entries for Hugo build artifacts (docs/site/public/, docs/site/resources/)

15C: API Reference & Cross-Linking

Generate and embed the OpenAPI spec.

• Create cmd/openapi-export/main.go that builds the Huma API with all route registrations and writes openapi.json to stdout or a file path
• Create docs/site/content/api-reference/_index.md with Redoc CDN embed (<redoc> tag pointing to /api/openapi.json)
• Add Hugo link render hook (layouts/_default/_markup/render-link.html) that strips .md extensions for Hugo URLs while preserving them for GitHub
• Add breadcrumb partial if not provided by theme
• Add make docs-openapi target to generate the spec file

15D: CI/CD Pipeline

Automate Hugo build and deployment.

• Create .github/workflows/docs.yml:
  • Trigger: push to main affecting docs/**, internal/api/**, or docs/site/**
  • Jobs: build Hugo site, validate links (htmltest), deploy to GitHub Pages via actions/deploy-pages
• Add link validation step using htmltest (checks internal links, anchors, image references)
• Add make docs-linkcheck target for local validation
• Update scripts/docs/add-frontmatter.sh to be idempotent (safe to run in CI)

---

Environment Variables

Variable	Default	Description
HUGO_BASEURL	/	Base URL for Hugo site (set in CI for GitHub Pages)
HUGO_ENV	development	Hugo environment (production in CI)

No CRUVERO_* environment variables are introduced by this phase. Hugo configuration uses Hugo's native config mechanism (hugo.toml).

---

Files Overview

New Files

File	Sub-Phase	Description
docs/manual/glossary.md	15A	Cruvero terminology glossary
docs/operations/README.md	15A	Operations section index
docs/site/hugo.toml	15B	Hugo site configuration with module mounts
docs/site/go.mod	15B	Go module for Hugo theme dependency
docs/site/go.sum	15B	Go module checksums
docs/site/layouts/_default/_markup/render-link.html	15C	Link render hook for dual-format compat
docs/site/content/api-reference/_index.md	15C	Redoc API reference page
docs/site/content/manual/_index.md	15B	Manual section index for Hugo nav
docs/site/content/operations/_index.md	15B	Operations section index for Hugo nav
docs/site/content/operations/checklists/_index.md	15B	Checklists subsection index
docs/site/content/operations/runbooks/_index.md	15B	Runbooks subsection index
docs/site/static/api/openapi.json	15C	Generated OpenAPI spec (gitignored)
cmd/openapi-export/main.go	15C	Static OpenAPI spec export CLI
scripts/docs/add-frontmatter.sh	15B	Front matter injection script
.github/workflows/docs.yml	15D	Hugo build + deploy workflow

Modified Files

File	Sub-Phase	Change
docs/manual/testing.md	15A	Expand from 50 to 120+ lines with intro, structure
docs/manual/mcp.md	15A	Expand from 25 to 80+ lines
docs/manual/templates.md	15A	Expand from 22 to 60+ lines
docs/manual/scripts-demos.md	15A	Expand from 19 to 80+ lines
docs/manual/config-env.md	15A	Reorganize core vars by subsystem
docs/manual/cli.md	15A	Add workflow example sections
docs/manual/alerts.md	15A	Expand from 29 lines with intro/prerequisites
docs/operations/*.md	15A	Add intros and prerequisites where missing
Makefile	15B	Add docs-build, docs-serve, docs-clean, docs-openapi targets
docs/phases/INDEX.MD	15A	Add glossary and operations/README entries
.gitignore	15B	Add Hugo build artifacts

---

Success Metrics

Metric	Target
Documentation files with intro paragraph	38/38 (100%)
Stub files expanded	5 files above minimum line thresholds
Hugo build	hugo --minify exits 0 with no warnings
Dual-format rendering	All markdown renders correctly on GitHub AND Hugo
OpenAPI spec	Covers all Phase 14 API endpoints
Link validation	htmltest reports 0 broken internal links
Local preview	make docs-serve renders at localhost:1313
CI deployment	Push to main triggers build + deploy to GitHub Pages
Glossary	20+ Cruvero-specific terms defined
Operations index	docs/operations/README.md links all 11 operations files

---

Code Quality Requirements (SonarQube)

The only Go code in this phase is cmd/openapi-export/main.go. It must:

• Error handling: Handle Huma API construction errors explicitly
• No dead code: No unused imports or variables
• Resource cleanup: Close any file handles with defer
• Linting gate: Run go vet ./cmd/openapi-export/... and golangci-lint run ./cmd/openapi-export/...

Shell scripts (scripts/docs/add-frontmatter.sh) must:

• Use set -euo pipefail
• Be idempotent (safe to run multiple times)
• Include usage comments

---

Risk Mitigation

Risk	Mitigation
Hugo module mounts break GitHub rendering	Module mounts are read-only references. Source files are never modified by Hugo.
Front matter injection changes file content	Script adds YAML front matter block only if absent. Idempotent. GitHub renders front matter as a table (harmless).
OpenAPI export diverges from running server	Export CLI uses same route registration functions as cmd/api/main.go. Single source of truth.
Hugo theme version breaks build	Pin theme version in go.mod. Dependabot or manual updates.
Large generated spec in repo	openapi.json is gitignored. Generated in CI from source.
Redoc CDN unavailable	Pin specific Redoc version URL. Fallback: bundle standalone JS.

---

Relationship to Other Phases

Phase	Relationship
Phase 14 (Production API)	15C exports OpenAPI spec from Huma routes registered in Phase 14
Phase 17 (PII Guard)	15A cleanup includes PII-related docs (immune.md, security runbooks)
Phase 18 (Prompt Library)	15A cleanup includes prompt-library.md
Phase 19 (Tool Registry)	15A cleanup includes tool-registry-restructure.md
Phase 20 (React UI)	15A cleanup includes ui-react.md, flow-builder.md
Phase 21 (Kubernetes)	Hugo site complements k8s deployment guide in docs/manual/

---

Progress Notes

(none yet)