Synced from Hive. This page is pulled from hivecommons/hive@v5 during the docs build. Edit the canonical source in the Hive repository.

Documentation map

Use this map when you already know the area you need and want the full Hive documentation catalog.

Documentation for the current Hive line (branch v5; the code and docs live under the src/ directory). The v2 branch was retired in August 2026 — operators upgrading a v2 deployment should start with the v2 → v4 migration guide, and v4 operators should use the v4 → v5 migration guide.

Operations

• Manual provisioning — heartbeat-only cluster provisioning, hub access roles, and common gotchas.
• Hosted Hive Hub — signing in at https://hive.hivecommons.dev, requesting a hosted hive, installing the GitHub App, configuring model gateways and Copilot login, reading /fleet, and fixing common setup problems.
• Self-hosted hub deployment — HIVE_MODE=hub, hub storage, heartbeat secrets, and SaaS spoke registration.
• CAP_NET_ADMIN and self-hosted spokes — the container runs with or without NET_ADMIN; granting it (--cap-add NET_ADMIN / securityContext.capabilities.add) enables the full forced-proxy-egress gate, and what the degraded best-effort mode means without it.
• Config layering — how ConfigMap seed, PVC dashboard overlay, and runtime config interact.
• Operator reference — top-level config blocks, hive flags/env, GitHub token scopes, and image provenance.
• Token mint — the opt-in mint: block (pkg/mint): what a minted token grants, key lifecycle, and the trust boundary an operator must get right before enabling it. Companion to ADR-0007.
• Changelog — recent user-visible changes and release notes.
• Release channels — stable/candidate/edge moving image tags, per-line channel ownership (v5 → candidate/latest, v6 → edge, v4 → none), switching a hive to a channel, and the version pill.
• Digest-verifiable rollback - the operator runbook for pinning a hive back to a prior immutable short-SHA build for all three images (hive, hive-contributor, hive-hub), stopping the hub automation that would undo it, and verifying by digest rather than by tag that the pin landed on the running spoke.
• v5 GA readiness bar — measurable release-train, migration, safety, and governance criteria that must be evidenced before v5 can be promoted beyond the active-development edge channel.
• v5 GA candidate week sequencing — dependency-ordered plan for the remaining human-gated GA-bar steps: candidate-SHA designation, candidate-pinned measurements, the two bound exercises, and the v4 freeze evaluation.
• Stable soak and promotion policy (v5 line) — the CI-enforced gate between candidate and stable: soak conditions, immutable short-SHA rollback tags, the emergency exception path (what it waives, and the post-hoc evidence that closes its follow-up issue), and the ledger of exceptions taken with their per-image rollback digests.
• HiveCommons migration tracker — phased org/package migration status, operator promises, and sequenced closeout checklist.
• v4 → v5 forward-port sync policy — proposed cadence, ownership, merge-commit top-up procedure, and the PR/review contract for keeping v5 topped up with v4; protects the v5 GA bar from unbounded drift.
• v4 feature-freeze execution runbook — the mechanics behind the accepted freeze policy (#6346), already wired behind the V4_FEATURE_FREEZE repository variable: the-command declaration, the freeze-marshal role, the ordered checklist (declare, gate v4 intake, retarget the agent fleet, retire batch-sync), the post-freeze v4 → v5 cherry-pick procedure, and the channel/default-branch remap at GA cut.
• v5 migration — operator announcement — draft, do not publish until #7721 Phase 0 completes: the migration-week announcement text (channel table before/after, per-selection operator actions, security-fix policy while stable lags, rollback, key dates) and the marshal’s publication checklist.
• dibs domain cutover — staged operator sequence for moving dibs to dibs.hivecommons.dev, including DNS, Let’s Encrypt quota hold, Certificate/Ingress manifests, redirect verification, and rollback.
• Serving spokes from the fleet wildcard certificate — how to point a cluster’s provisioned spokes at the wildcard instead of certificate per hive, the two cluster prerequisites that must hold first, and which hosts a wildcard cannot cover.
• Tagged releases — the automated v1.2.3 release path: what triggers a release, how the version is inferred from CHANGELOG.md, the commit convention that drives it, the human escape hatch, how it relates to the moving release channels above, and the per-release SPDX SBOM attached to each GitHub Release (and why it is a release artifact, not an in-image attestation — see #3760).
• Dashboard-triggered standalone upgrades — the dashboard upgrade button for standalone (Compose/Podman-Quadlet) hives: the HIVE_DEPLOYMENT_RUNTIME/HIVE_DEPLOYMENT_PODMAN_MODE runtime contract, the closed host-side helper (hive-dashboard-upgrade-helper.sh), and why an unproven runtime deliberately hides the button.
• Spoke dashboard — the static dashboard FAQ panel contract: not ACMM-gated, no JS/fetch, grouped L1-L6/runs/contributors/claims/cost help, and guarded config-key references.
• Dashboard design system — shared token catalogue, component variants, migration rules, ratchet plan, and #8536 theme override contract for spoke, contributor, and hub dashboard surfaces.
• The auto-update Compose profile — what unattended Watchtower updates cost you, what the Docker socket proxy does and does not fix, and why Kubernetes should not use this profile at all.
• Environment variable reference — centralized list of runtime, deployment, hub, backup, and contributor environment variables.
• Kubernetes deployment — the operator path for Kubernetes: prerequisites, namespace, secret, ConfigMap, PVC, Deployment, Service, Ingress, and published ports. Lives in the root README alongside the Compose and Podman quick starts; the manifests it applies are src/deploy/k8s/. See also dashboard route and health checks and the Kubernetes CronJob in backup and restore.
• Troubleshooting — container logs, config validation, agent tmux sessions, dashboard auth, GitHub credential checks, and GitHub App workflow-permission push rejections.
• Cross-cluster migration — the manual procedure for moving a hive between clusters.
• Self-hosted Kubernetes cluster move — moving a self-hosted (non-hub) Kubernetes hive between clusters: which PVC/Secret/ConfigMap paths hold identity and state, a generic kubectl-based PVC copy, target prerequisites, and verification.
• Hub-registered hive cutover — cross-cutting rules for any hub-registered hive’s move: what identity is, how the hub reads heartbeat/dashboard_url, why source and target must never run concurrently, the required cutover order, and rollback.
• Moving a Hive between hosts, same runtime — host-to-host move procedures preserving hive identity and state for Docker Compose → Compose, Podman Quadlet rootless → rootless (including a different /etc/subuid base on the target), and Podman Quadlet rootful → rootful: what’s host-bound, a target preflight checklist, exact volumes/paths to archive, the stop-source-before-start-target rule, and post-restore verification. All procedures are DOCUMENTED, NOT EXECUTED.
• Cross-runtime moves — Podman → Docker (the reverse of backup-restore.md’s executed Docker → Podman migration), and Compose/Quadlet ↔ Kubernetes: volume ↔ PVC, secrets ↔ Kubernetes Secrets, and which host-bound settings must change. Documented, not executed.
• v2 → v4 migration — upgrading a v2 deployment: the config is compatible unmodified, and what actually changes is the image tag, the published 7681 port, and the Compose/Kubernetes security settings.
• v4 → v5 migration — upgrading a v4 deployment before the 2026-12-21 EOL: channel/tag changes, additive config deltas, Kubernetes/Compose/Podman rollout steps, verification, and digest rollback.
• Major-version upgrade guide — preparing for v4 → v5 and future major-version boundaries.
• Dashboard route and health checks — dashboard-route-rbac.yaml, route_exists, listener probes, and alert behavior.
• Fleet health: the verdict and remediation hints — the per-hive green/amber/red/unknown verdict on /fleet: what each state means, ACMM-banded output expectations, precedence (App broken beats provider limit beats budget beats generic no-output), the cause → remediation table, detector semantics (error streaks, consent wedge, no cadence, channel lag) with the carry-forward rule that lets a recovered hive clear its own alarm, and a symptom → fix troubleshooting table.
• Fleet drift signals — the per-hive deviation badges on My Hives: all signal kinds (heartbeat-stale, duplicate-spoke, identity-split, version-absent, pinned-image, …) with severities and who fixes each (owner vs hub operator), the derived fleet norm behind branch-mismatch/version-behind, the deliberate suppression rules (placeholders, actively-upgrading hives, status-flipping yielding to duplicate-spoke), and the in-memory first-seen semantics.
• Fleet self-reporting (governor.fleet_report) — how a hive reports its own hive-attributable failures upstream to hivecommons/hive: the file_upstream opt-in (default off = dry-run preview on the dashboard), the two triggers (acmm-shortfall after two unmet weekly epochs with attributable evidence, and hive-code-defect on hive’s own component allowlist with no shortfall required), exactly which fields leave the hive and which never do (the raw hive ID is replaced by a truncated SHA-256), fingerprint deduplication via comment + 👍 reaction instead of duplicate issues, and recovery comments that close issues the hive itself opened.
• Agent self-healing watchdog — liveness and readiness reconciliation for launched agents: liveness classification, restart backoff, crash-loop escalation, the auth probe that refuses to restart into dead credentials, and the conditions array on /api/agents. Ships in mode: observe, which audits the restarts it would have made without making them.
• Audit log format — the JSONL schema of /data/audit.jsonl: the five fields, how to parse the flat detail string (and why repo is not first-class), the pseudo-users, and why size-triggered rotation means the effective lookback varies per hive rather than being 90 days.
• Per-repo agent pause — quieting repository without stopping the hive: project.paused_repos, the dashboard toggle and POST /api/repos/pause, the provenance every pause carries (who/when/why), and exactly which layers enforce it — the MITM proxy, the hive-open-pr/hive-merge relays, work enumeration and the auto-merge sweeps — plus what a pause deliberately does not stop (reads, the hive’s own control plane, and your own pushes).
• Token-access audit log - the other audit log: /var/run/hive-metrics/token-access.jsonl, appended by gh-wrapper.sh on every agent gh call and by git-credential-hive.sh on every credential lookup, served (owner-gated, last 100 lines) by GET /api/token-access. Covers both line schemas, the entrypoint pre-creation/permission model, why an empty log is not “no activity”, and the blind spots (contributor mode, wrapper bypass, tmpfs non-durability).
• Per-repo agents — scoping an agent to the repositories it serves with repos:, so which agents exist is a per-repo answer instead of a hive-wide: what a scope narrows (kick contents, $HIVE_REPO/$HIVE_REPOS, the AUTHORIZED REPOS block) and what enforces it deterministically (the MITM proxy plus the hive-open-pr/hive-merge/hive-open-issue relays), the optional repos: key on a BYO AgentSpec and why it is an optional interface rather than a sixth contract method, the repos_owner marker that keeps a pack apply from widening a specialist, and what a scope deliberately does not block.
• hive-open-pr — how agents open pull requests as the App bot instead of via gh pr create: the flags, the UID-ownership anchor that makes the request forge-resistant, and the asynchronous contract (exit 0 means requested, not opened).
• hive-merge — how agents merge pull requests as the App bot instead of the GitHub MCP merge_pull_request tool: the flags, the F4 target-binding (pinned head SHA + governor merge-eligible list), and the retry/re-engagement behavior when required checks are still red.
• hive-open-issue — how agents create issues, post comments, and claim issues as the App bot instead of gh issue create/gh issue comment: the three request shapes, title dedupe (exact match first, canonical subject — trailing qualifier stripped — as the fallback, #6927), and the exponential-backoff retry contract.
• Review-bot threads on hive-mediated PRs — how the hive addresses and resolves inline threads left by external review bots (Copilot, chatgpt-codex-connector[bot], CodeRabbit) on PRs it opened: the classification.review_bots key, the review-threads.json monitor, the FIX-BEFORE-NEW kick block that routes each PR back to the agent that opened it, and the hive-review --thread / --resolve-thread relay whose watcher-side guard refuses to touch a human’s thread (#7360).
• Network and port requirements — inbound ports, proxy paths, egress, and firewall guidance.
• TLS, HTTPS, and certificates — termination patterns and certificate ownership.
• Security notes — log scrubbing and secret redaction guarantees/limits.
• Token collection and usage tracking — session JSONL, /api/cost, and hub usage rollups.
• Notifications — ntfy, Slack, and Discord alert channels, plus the two-way Discord bot.
• State-triggered hooks — declarative transition → action rules, the transition catalog, the vetted action set, and the security model (RFC #4001).
• CEL-based agent triggers — the triggers: config key: declarative CEL rules that kick an agent on a normalized source-control event, additive to built-in label/governor triggering, the event.* field reference, and the fail-closed compile/runtime contract.
• Long-running runs — how a run starts, including default-off triage admission and inception completion admitting an explicit GitHub issue into the first spec lease.
• Spektacular stage runner — the Hive side of long-running runs (#8303, umbrella #8290): a run moves through spec → plan → implement stages on task lease, Spektacular owns each artifact’s state while Hive owns the workflow. Covers the default-off runs.spektacular config block and Governor Features toggle, the max_stage_retries budget, and what advances a lease. The design record for the artifacts a run leaves behind is design/run-artifacts.md.
• Audit campaign — the runs three-gate model proven on a workload that never opens a pull request (#8327): owner-triggered activation, campaign/inspection/finding beads, shadow-mode execution with deterministic finding identity, per-inspection stage receipts and proof predicates, and the guard that refuses to run while HIVE_GITHUB_TOKEN is present. Publication remains default-off and is skipped unless publication.enabled is set.
• Public snapshots — read-only /snapshot, custom CSS, and frame-ancestor sharing.
• hivectl — command-line client for the dashboard API, including hivectl tui, the full-screen terminal dashboard: keybindings, pane cadence, and v1 boundaries. See the design record for the reasoning behind it.
• bd beads CLI — work-ledger and knowledge command reference for operators and contributors.
• Backup and restore — hive-backup, Kubernetes CronJob, spoke backup scope, and setting the backup encryption key from Governor Config (hosted flow). Host-level backup, restore, and docker compose down -v are given per runtime: Docker Compose, and Podman/Quadlet with the executed backup → wipe → restore cycle in both root modes, the rootless mapped-UID trap that makes a host-shell tar skip the GitHub App key, and the Docker→Podman migration (the two volume stores are never shared). Also covers restoring a pkg/spokebackup archive: the archive-path → container-path mapping, and the executed hive-backup restore path that applies it — including the identity guard that refuses to splice hive’s config and GitHub App keys another’s (#6529).
• Hub disaster recovery — the hub-level runbook that goes beyond per-hive backup: hub backup and key escrow, spoke fleet recovery, Slack blast, and the full rebuild-from-zero procedure after a catastrophic loss.
• Deployment helper scripts — the all-in-one LXC setup, Proxmox LXC, and blue-green Compose helpers. All are Docker-only; the page states each script’s runtime scope and where a Podman operator should go instead.
• bin/ pipeline script index — map of the deterministic pipeline and operational scripts, grouped by function.
• Dashboard API reference — pragmatic route index for dashboard and hub endpoints.
• Dashboard OpenAPI spec — machine-readable REST API reference for integrations.
• ioscan status — the untrusted-input scanner/canary feature (live and default-on in v4).
• Deployment scripts — inventory of deployment helpers, including dashboard TTY panes and hive-panes.

Contributors and access

• Getting started as a first-time contributor — the end-to-end path for a first code or documentation contribution, tying the reference docs together and answering the Hive-specific questions they don’t.
• Local development — the local workflow for contributing to the Go codebase on v4: prerequisites, build, and test loop.
• ClankeR contributor relay — local contributor setup, multi-hub subscriptions, moving a relay to another machine, and role requests.
• Backend smoke — the live canary for the contributor CLI integration: who runs it (the project’s CI, centrally — not hive operators), the latest/pinned lanes and what a red in each means, how failures become deduplicated issues with evidence attached, the API-key vs subscription-login credential options, and the per-hive run telemetry behind /api/contribute/run-stats with its scenario ratchet.
• CLI pins and the automated pin bump — where each agent CLI’s version and per-arch digest are pinned in the two Dockerfiles, why they are pinned rather than self-updating, and how cli-pin-bump.yml resolves the latest release, recomputes the digests, smokes the image, and opens labelled PR per CLI.
• Contributor trust tiers and delegated agent roles — newcomer/contributor/trusted/merger/advisor semantics, Acting as, grants, and delegatable roles.
• Credly badges — planned integration design; currently a placeholder mapping.

Configuration and agents

• Agent configuration — agent fields, methods, models, pins, cadences, caveman mode, ACMM packs, and live-linked definition_source (with its seed-only trust model).
• Formal verification — the optional L5/L6 quality.formal capability for agent-authored Spin/Promela models, reporting-only CI, and deduplicated counterexample issues.
• Advisory digest — what the digest shows (max_findings, show_all), how stale findings are marked unverified, and which positive signals retire findings.
• Advisory digest staleness — when the hub raises the stale-advisory pill and alert, the gates that deliberately suppress it (undelivered App, App cannot write, all agents quiet), and the admin diagnostics that measure hidden staleness.
• Governor mode thresholds — how idle/quiet/busy/surge thresholds scale with repo count, the threshold_scaling curves, and when explicit thresholds win.
• Large-spoke scale envelope — the backlog size spoke is known to work at, why kick-prompt caps are render-side while enumeration is uncapped, and an inventory of every cap that changes behaviour at scale (default, overflow behaviour, and whether it is operator-tunable).
• Supervisor agent — supervisor policy modes, bead roles, and when to enable the orchestration lane.
• Telemetry agent — the L5/L6-only opt-in observability agent, ACMM level gating, and the project_observability opt-in flow.
• Operations agent — the L5/L6-only opt-in operational-readiness agent (health checks, SLOs, runbooks), ACMM level gating, and the project_observability opt-in flow.
• Custom dashboard stylesheets — operator-supplied CSS for the dashboard and public snapshot.
• Branding a hive — persistent per-deployment name, mark, and colours via <data>/branding/branding.json and custom.css (HIVE_BRANDING_JSON/HIVE_BRANDING_CSS); distinct from the per-request ?style= stylesheets above.
• Portable AgentDefinition format — standalone YAML schema for importing/exporting agent definitions.
• Knowledge curator — automatic fact extraction and promotion knobs, plus the other knowledge: sub-sections: git_sources (indexing a remote repo, layer semantics, private-repo auth (unsupported), diagnosing a failed source), vaults (local Obsidian vaults, git-sync), documents (PDF/URL import), and bead_synthesizer (on-by-default bead→wiki synthesis and retention policy, and how to turn it off).
• Skill registry — the /data/skills/ file format and front-matter fields. Delivered to agents today: skills are opt-in per agent via skills: [name, ...], resolved registry-first with an AGENTS.md repo-local fallback, and the rendered block is prepended to the kick’s ${KNOWLEDGE}. Both sources reload on every kick. An 8 KiB whole-skill cap applies; a skill that would exceed it is dropped whole, never truncated.
• AGENTS.md repo instructions — the per-repo AGENTS.md file format Hive’s parser (pkg/agentsmd) understands, including front-matter skills: and inline ## Skill: sections. Wired into kicks, but needs a checkout: Hive agents keep no clones, so set project.checkouts_dir to a directory holding checkout per repo. Without it there is no root to read and injection stays a no-op, which is the default.
• Agent peer-awareness logging (pluk) — pluk log format, hive-panes, availability, and retention.
• Strategy Lab (Nous) — experiment lifecycle, dashboard/API configuration, fast-fail bounds, and the gate-decision flow. No nous: block in hive.yaml.
• GitHub App setup — the Forge App on GitHub and GitHub Enterprise: app creation, permissions, Setup URL, and /gh-setup.
• Forge setup: GitLab, Gitea, and Forgejo — the non-GitHub forges. Adapters exist and are tested, but are not wired into any running code path: a hive cannot run against GitLab, Gitea, or Forgejo today, and project.forge changes what the dashboard displays. Covers the gitlab:/gitea: config surface that does parse, why the gh-CLI agent path is GitHub-only, and how project.forge differs from github.forge.
• ACMM policy matrix — capability levels and policy modes.
• ACMM level-up advisor — the advisory-only pkg/acmmadvisor computation behind GET /api/acmm-recommendation: the signals it measures, per-level thresholds, and why it never changes the applied level.
• ACMM waivers — how a repo declares in .acmm.yml that a criterion is satisfied off-repo, why the file-existence check needs it, and the properties that keep a waiver from becoming a way around the model — chiefly that a waiver can restore full green but can never advance a level.
• Inception — operator guide to the L1 brainstorm/inception workflow: phases, API, and template variables.
• Planning intelligence — how a large GitHub issue becomes an epic the architect lane decomposes into child beads, the human plan-review gate that withholds those children until approved, and stall-replan.
• Review swarm — the five review perspectives, the verdict collector and its report contract, and the opt-in merge-gate integration and bounded auto-fix cycle for review findings.
• Duplicate PR sweep — the opt-in (duplicate_sweep.enabled) cross-PR pass that clusters open PRs by changed-file set and suggests which to keep: the two confidence tiers, how a survivor is chosen, why a bot regeneration series gets summary instead of a comment per PR, and why the output is always a suggestion a human acts on and never an automated close.
• Hold-gated review queue triage — the triage-class policy for the human review queue (T0 fixes, T1 behavior-adjacent, T2 additive), the shipped review_class presentational sort in last-actionable.json and the dashboard PR list, and the open mechanism options awaiting maintainer decisions (#6183).
• Retro lane — the opt-in (retro.enabled) post-completion pass that reconstructs a record for each closed bead and flags patterns such as excessive fix attempts or kicks; deterministic by default, with LLM analysis separately opt-in.
• Work sources — governor.work_source: the four type options (github default, github_projects, linear, jira), config fields, required credentials, and priority/hold-label mapping per source.
• Linear agent integration — joining a Linear workspace as a first-class agent member: webhook verification, the 10-second session acknowledgement, which hive agent takes sessions, and narrating completion back as agent activities.
• Lite enrollment — the zero-repo-secret on-ramp: hivectl enroll OWNER/REPO adds a repo to a spoke’s project.repos, with prerequisites and the hosted lite-spoke path.
• ACMM policy fragments — per-level ACMM policy references.
• Sandbox isolation and agent guardrails — isolation layers and operator guardrail notes.
• Per-agent gh restrictions — file-based wrapper denials in /etc/hive/restrictions/.
• Podman rootless CI — rootless Podman contract for contribute-hive.
• Podman Quadlet .kube compatibility spike — why the standalone Kubernetes overlay is not a safe direct source for Podman units.
• Podman ownership and cleanup contract — the labels that mark a resource Hive-owned and the guard that keeps Podman/Buildah cleanup from reaching the operator’s other containers, Distroboxes, and images.
• Podman preflight: SELinux, mounts, secrets, and ports — read-only diagnostics for SELinux state and mount labeling, configuration/secrets readability, and published host-port availability, with remediation that never disables SELinux or widens a secret.
• Podman preflight: subordinate IDs, graphroot, and networking — read-only diagnostics for rootless subordinate UID/GID delegation, unsupported (NFS and other distributed) container storage, and the rootless network backend/helper, with remediation that never edits /etc/subuid or /etc/subgid.
• CLI backend setup — setup notes for Claude, Copilot, Goose, Bob, Pi, Codex, and Aider.
• Backend support tiers and acceptance bar — the policy for adding a CLI backend: the three tiers (core/headless-pod, supported/confined, experimental/unconfined), the criteria each requires with the exact file or test a PR must touch (list parity, declared posture, flag-honoring proof, credential detection, pinned install, refusal gate, confinement floor, headless entry point, unattended-credential verification, allowlist touchpoints), and how a backend moves between tiers.
• Inference backends — vLLM, llm-d, LiteLLM, and Model Gateway troubleshooting.
• apiproxy — Anthropic-compatible proxy logging and deployment notes.
• Outreach anti-spam ruleset — the deduplication and anti-spam rules the outreach agent operates under across awesome lists, project issues, directories, and community threads.
• v1 to v2 migration — historical. Both ends of this migration are retired; v2 was retired in August 2026. Kept for operators still on v1, who should read it alongside v2 → v4 migration above. New deployments do not need it.

Architecture and design

• Architecture — process model, governor loop, guardrails, hub/spoke, and walkthrough.
• Automatic repo ACMM reconciler — proposed design for per-repo ACMM targets, gap-to-work reconciliation, human hand-off, waivers, and anti-gaming controls (RFC #6235).
• Hive federation design — the multi-hive registry: live /api/hives endpoints, project, contributor flow across hubs, and what remains future design work.
• Public roadmap — the v4 direction as Now / Next / Later, with the tracking issue behind each item. Directional rather than a promise, maintained by pull request; check the date in its header before relying on the ordering.
• Landscape and positioning — how Hive’s operations-plane design compares to nearby agentic orchestration tools, with public references per project. Explicitly time-sensitive; check the conducted date in its header before quoting product details.
• CNCF reference architecture — CNCF submission/reference template.
• Podman CI runner map — measured hosted-runner capabilities and which Podman lane goes where; SELinux is the lane needing non-hosted infrastructure.
• CI runner labels — how runs-on: picks the self-hosted fleet, why a fork must degrade to a GitHub-hosted runner, and the variable hivecommons sets.
• Gate-integrity invariants for agent lanes — proposed write-gate rules for agent lanes: no history rewrites on branches a lane did not create, no sign-off on other authors’ commits, and hold-gated demotion for gate manipulation.
• Design documents — longer-form design records with the full reasoning behind a decision, indexed with a status each (shipped / partly shipped / design / historical) so a proposal is not mistaken for current behaviour: master secret rotation, wrapped master delivery to pull-only spokes, PR reach telemetry, and the knowledge system.
• Discord reaction-consensus issue promotion — proposed design for turning Discord reaction consensus into an audited Hive label write that composes with project.issue_filter.require_labels (RFC #6239).
• GitHub @-mention triggers — v6 design, now shipped on the v6 branch in all three phases (#7582, #7597, #7623), for the first inbound GitHub trigger: a human summons an agent by mentioning the App on an issue or PR, mirroring the Linear agent-session path, replying through Converse on the existing write path, with poll-first transport and guards mapped to mechanisms that already exist (RFC #7483). Not present on v4 or v5.
• Podman Compose-provider selection spike — why podman compose must name its provider explicitly, and which provider needs no Docker tooling.
• Sourcing token metering from ccusage behind a tokens.Source seam — proposed design for ccusage-backed token metering with attribution preservation, Bob fallback, and cutover diagnostics (RFC #6234).
• Trajectory review — trajectory safety lane and review signals.
• Podman Quadlet .container/.pod spike — feasibility result for explicit Quadlet units: readiness via Notify=healthy, the startup-timeout trap, and what the generator does not validate.

Historical/design notes

Some documents describe planned or design-only work rather than live features. Those pages are marked at the top, for example Credly badges. The longer-form design records under design/ are a whole directory of these: each entry in that index carries a status, because those pages are the reference record of a decision and are deliberately not rewritten as later stages ship.

Security (v4)

• Security model — operator guide — Ed25519-only sessions/SSO, per-hive keys, master key rotation, forced proxy egress and CAP_NET_ADMIN, privilege model, and supply-chain posture.

• Security threat model — actors, boundaries, layered defenses, known gaps, and reporting.

• Security response process — who responds to a vulnerability report (the Maintainer Committee, rostered in OWNERS), the end-to-end handling flow and the 60-day fix commitment, how membership is added and rotated, the escalation path if a reporter gets no response, and the project’s known limits stated plainly.

• CNCF TAG-Security self-assessment — the CNCF Incubation self-assessment artifact: metadata, actors/actions/goals, critical security components with file/line citations, project compliance, secure development practices, vulnerability response process, and the three most significant known weaknesses stated plainly.

• ioscan red-team evaluation — measured, not asserted: a 43-payload adversarial corpus run through the production input path. 42% of attacks withheld from the agent, 58% reached it verbatim, with the per-family breakdown, the two Unicode table gaps a single character exploited (both now closed), the benign-text false positives, and the proxy deny rules that contain what gets through — verified across all four ACMM modes on every test run.

• CNCF General Technical Review — the full Day 0/1/2 GTR questionnaire answered against this repository, cited file-by-file, with every currently-unanswerable question marked [NEEDS OPERATOR INPUT] rather than guessed at.

• Heartbeat bearer cutover — retiring the fleet-wide heartbeat bearer, whose possession proves “some provisioned spoke” and lets any spoke heartbeat as any hive, in favour of the per-hive key — without re-provisioning the fleet, and the precondition that gates the removal.

• Rootless Podman startup and exit-77 behavior — measured rootless matrix: fail-closed exit 77, gate installation under --cap-add NET_ADMIN, proven interception, and what is still unproven.

• IPv6 egress-gate bypass — measured: the forced-proxy redirect is IPv4-only, so agent traffic to :443 over IPv6 never meets it (5 IPv6 connections, 0 redirects; 5 IPv4 connections, 5 redirects, same run). Names the fix slice.

• Rootful Podman egress-gate baseline — the rootful baseline the rootless result is measured against: fail-closed exit 77, redirect and ambient-capability evidence, and SO_MARK isolated from the owner-UID exemption.

• Podman support matrix: rootful/rootless × enforcing/advisory — the support statement for standalone Hive under Podman: which of the four combinations is supported, experimental, or a deliberate unenforced choice, what evidence settles each, and the gaps carried forward.

• Release qualification: SELinux-enforcing Podman — the Podman lane hosted CI cannot run, and why: a per-release, reproducible procedure on an enforcing Fedora/CentOS Stream-class host covering :z/:Z mounts, MCS label behaviour, and secret access, with a results ledger and a stop condition that records UNEXECUTED rather than passing from a permissive host.

• hive-data under SELinux enforcing — what the named volume actually guarantees: podman labels it container_file_t:s0 with no MCS category at create time, which is what lets a recreated container (a fresh category every start, --rm deleting the old) still read the data. Ownership after the copy-up, what survives unit deletion and reinstall, what does destroy it, why :Z on the volume line is a silent footgun where :Z on the config and secret bind mounts is correct, and why EnvironmentFile= needs no flag at all.

• SELinux AVC evidence, and the hive-launch group secret — the audit-log evidence behind the qualification above: the actual AVC records per case rather than pass/fail inferred from an exit status, plus the 0440 hive-launch (GID 1002) secret read through a supplementary group. Records three defects in shipped advice, including a label check that reads garbage where uutils coreutils shadows GNU, and an MCS denial that produces no audit record at all.

• Standalone Hive under Podman: the Quadlet units — the .container, .volume, and .network units that start Hive and its authenticating gateway on Podman in both root modes, the published-port boundary they encode (3001 published, the raw ttyd terminal on 7681 never) and how it was measured, the install and boot-persistence steps, and why systemctl start returning means the healthcheck passed rather than merely that a process was spawned. Also records the Docker-free run (#4448): the quick start executed verbatim with docker removed from PATH and DOCKER_HOST pointed at a nonexistent socket, reaching {"status":"ok"} on 3001 with no Docker socket mounted anywhere — and states plainly which #4188 criterion that closes and which stays open.

• Quadlet lifecycle: stop, start, restart, recreate, and boot persistence — what those units actually report as an operator drives them, in both root modes, including the first live rootful start. Records that a clean systemctl stop left the unit failed, that systemctl enable fails outright on a generated unit, and that is-enabled cannot tell you whether Hive will come back after a reboot; ships bin/hive-podman-lifecycle-probe.sh as the repeatable check and records the reboot row as NOT EXECUTED rather than inferring it.

• Host-execution capability matrix — what real execution environment can actually do, measured rather than asserted, before any new execution runtime is proposed on the strength of what it supposedly cannot. Command, exit status and verbatim output per capability for /dev/kvm, systemd, reboot, lingering, SELinux, rootful Podman, modprobe and NET_ADMIN. The result was not the expected: most are present, and the reason the reboot rows in the lifecycle page stay unexecuted is topology — the session runs on the host that would restart — not permission. Scoped hard to path on host, and says so.

• Quadlet update and rollback: moving the image, and getting back — the deliberate manual path from Hive image to another and back, pinned by digest in a Quadlet drop-in because the shipped unit names a floating tag that cannot be rolled back to. Executed in both root modes between two real v4 builds: an 11-second healthy update, a failed update that held the unit in activating for the full 301-second TimeoutStartSec and then looped without ever reading failed, and an 11-second rollback out of it with hive-data intact throughout. Ships bin/hive-podman-update.sh.

• Health-aware auto-update: whether it works on this unit, and what it costs — the #4411 decision, measured rather than assumed. podman auto-update --rollback DOES fire on this unit despite it never reading failed, because podman reads the D-Bus start-job result (timeout) and not ActiveState; Restart=always is kept untouched and never even fires. Driven against a bad-but-startable image. Also what it costs: full TimeoutStartSec of downtime per bad update, repeated on every timer firing because podman does not remember a rollback, and a digest pin that silently wins. Opt-in, via bin/hive-podman-update.sh autoupdate on. Executed in both root modes — rootless (#4411) and rootful under the system manager (#4447), which is the enforcing mode.

• Architecture Decision Records — lightweight ADR process and records 0001-0017.

• Intent verification — tier-based change authorization for merge eligibility.

• Rootless Podman CI seam — documented test intent and static contract for contributor-container runtime handling.

• Release-line carry-forward guard — the nine workflows pinned to hardcoded version-branch names, the single source of truth they are asserted against, and what to edit when a new release line is cut.