Hive Commons Documentation

Documentation for the Hive Commons projects

Official documentation site for Hive Commons, served at docs.hivecommons.dev. It covers:

• Hive — autonomous AI agent fleets for your repositories
• Crux — run AI coding agents on their own, without Hive
• hotshot — screenshots straight into your AI coding terminal
• pluk — pub-sub event streaming for AI agent tmux sessions
• rationguard — detect and rebut rationalization patterns in AI agent output
• promptargs — template expansion for AI prompts
• dibs — claim ideas so contributors get credit when agents implement them
• Spektacular (Spek) — spec-driven development for AI coding agents (canonical site: spektacular.dev)

How content is sourced

Hive, hotshot, pluk, rationguard, promptargs, dibs, Crux, and Spektacular docs are single-sourced from their repositories and pulled at build time:

• scripts/sync-hive-docs.ts pulls Hive docs from hivecommons/hive (src/docs/, branch v5; override with HIVE_DOCS_OWNER / HIVE_DOCS_REPO / HIVE_DOCS_REF). The pages it pulls are listed in scripts/sync-hive-docs.files.json. After syncing it reports file-list drift: upstream pages next to synced subdirectory pages, or linked from synced pages, that are not listed (so their links fall back to GitHub URLs). The report is printed and added to $GITHUB_STEP_SUMMARY and never fails the build; with SYNC_HIVE_DOCS_HEAL=1 (or --heal), used by the scheduled docs refresh, it appends the drift to the list, syncs the new pages and adds them to NAV_STRUCTURE_HIVE in src/app/docs/page-map.ts. List intentional omissions in scripts/sync-hive-docs.unsynced-allowlist.txt.
• scripts/sync-sibling-docs.ts pulls the hotshot, pluk, rationguard, promptargs, dibs, Crux, and Spektacular docs from their repos. Spektacular also pulls its tutorials from hivecommons/spektacular-website (MDX, converted to Markdown by scripts/mdx-to-markdown.ts; override the ref with SPEKTACULAR_WEBSITE_DOCS_REF). Override the org for all sibling repos with SIBLING_DOCS_OWNER (default hivecommons), or the branch/ref for an individual project with HOTSHOT_DOCS_REF, PLUK_DOCS_REF, RATIONGUARD_DOCS_REF, PROMPTARGS_DOCS_REF, DIBS_DOCS_REF, CRUX_DOCS_REF, or SPEKTACULAR_DOCS_REF.

Edit the canonical source in the project repository — not the synced copies under docs/content/. If a sync source is unreachable at build time, the build fails so stale content is never deployed silently. For offline local work, set DOCS_SYNC_OPTIONAL=1 to keep the committed copies instead (CI and Netlify always use the strict behavior). Only the meeting-recordings refresh always falls back to its committed data.

Development

Requires Node.js 22.19 or newer (.nvmrc pins 22, matching CI).

npm install
npm run dev        # http://localhost:3000

The site is Next.js + Nextra, deployed on Netlify (site hivecommons-docs). Navigation is defined in src/app/docs/page-map.ts; project registry in src/config/versions.ts.

Observability

The site exposes per-instance API metrics via /api/metrics in Prometheus text format. The endpoint serves bounded, in-process counters and histograms for the search, docs-image and healthz API handlers only (not static assets or page traffic); the route labels match ApiRoutes in src/lib/metrics.ts and the alert rules in monitoring/docs-api-alerts.yml.

Scope and durability: The registry is process-local with no configured exporter or backend. On Netlify, instances are ephemeral, so the /api/metrics snapshot is not durable or site-wide. It is suitable only for immediate, per-instance instrumentation during development or local testing.

Site-wide telemetry: If persistent, aggregated request telemetry is needed, use a deployment-supported collection path — for example, Netlify's platform-native traffic analytics, or an explicitly operator-configured scraper/aggregator that polls /api/metrics across instances and persists data to a central observability backend.

Readiness check: /api/healthz reports whether the instance can actually serve docs content. It verifies that the local docs content tree (docsContentPath in src/app/docs/page-map.ts) exists, is a directory, and is non-empty — the dependency every page render and /api/search read from at request time. It returns {"status": "ok"} with HTTP 200 when that check passes, or {"status": "unhealthy", "reason": "<cause>"} with HTTP 503 otherwise (for example a bad build, a failed volume mount, or an incomplete version-branch checkout). This guards against an instance returning 200 on its normal routes while actually serving broken or empty documentation.

Runbooks

If a deploy ships broken pages or missing content, start at runbooks/README.md; it indexes the site rollback runbook.

Contributing

PRs welcome. Sign your commits (DCO): git commit -s.

Contributions are welcome. CONTRIBUTING.md covers local setup and tests. Reporting a security vulnerability? Follow SECURITY.md to report it privately, not through public issues. Please follow the Hive Commons Code of Conduct.

Questions? Join the Hive Commons Discord, watch the hive live on Twitch, or join a community meeting.

License

Apache 2.0