From 6f328aaf90831fb416cec6d8ff295e7b8b4673d3 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Thu, 24 Sep 2026 08:46:14 -0400 Subject: [PATCH] docs: sync Hive documentation map Add the new Hive documentation map to the sync manifest and Hive overview navigation, then refresh synced Hive content from v5 so the Introduction and map render with canonical links. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Signed-off-by: Andrew Anderson --- docs/content/hive/adr/readme.md | 1 + docs/content/hive/agent-configuration.md | 2 +- docs/content/hive/architecture.md | 9 +- docs/content/hive/contributor-relay.md | 72 ++++++-- docs/content/hive/documentation-map.md | 191 ++++++++++++++++++++++ docs/content/hive/hivectl.md | 23 +++ docs/content/hive/readme.md | 200 +++-------------------- docs/content/hive/troubleshooting.md | 2 + scripts/sync-hive-docs.ts | 1 + src/app/docs/page-map.ts | 1 + 10 files changed, 311 insertions(+), 191 deletions(-) create mode 100644 docs/content/hive/documentation-map.md diff --git a/docs/content/hive/adr/readme.md b/docs/content/hive/adr/readme.md index 6899f2c..040c104 100644 --- a/docs/content/hive/adr/readme.md +++ b/docs/content/hive/adr/readme.md @@ -55,3 +55,4 @@ What becomes easier, harder, safer, or riskier because of this decision? - [ADR-0015: Scope `style-src` as two directives and accept inline style attributes](/docs/hive/adr/0015-csp-style-src-scope) - [ADR-0016: Scope `script-src` as two directives, close the element half with hashes](/docs/hive/adr/0016-csp-script-src-scope) - [ADR-0017: Quadlet `.container`/`.pod` units as the Podman persistent lifecycle](/docs/hive/adr/0017-podman-quadlet-lifecycle) +- [ADR-0018: Shared dashboard design tokens and component layer](https://github.com/hivecommons/hive/blob/v5/src/docs/adr/0018-dashboard-design-tokens.md) diff --git a/docs/content/hive/agent-configuration.md b/docs/content/hive/agent-configuration.md index 71714b3..614be57 100644 --- a/docs/content/hive/agent-configuration.md +++ b/docs/content/hive/agent-configuration.md @@ -830,7 +830,7 @@ A stage receipt includes the normal report envelope (`lane`, `kind`, `findings`, ## What to read next - **[Supervisor agent](https://github.com/hivecommons/hive/blob/v5/src/docs/supervisor.md)** — what the supervisor does, how it differs from the governor, when to enable it, `bead_role` semantics, and policy modes. -- **[Documentation index](/docs/hive/readme)** — what hive is, setup, and the full topic-guide surface. +- **[Documentation map](/docs/hive/documentation-map)** — setup and the full topic-guide surface. - **[Architecture](/docs/hive/architecture)** — process model, deterministic pipeline, governor loop, guardrails, and hub/spoke design. - **[Portable AgentDefinition format](https://github.com/hivecommons/hive/blob/v5/src/AGENT-DEFINITION.md)** — standalone YAML schema for agent imports, exports, and overlays. - **[AGENTS.md repo instructions](https://github.com/hivecommons/hive/blob/v5/src/docs/agents-md.md)** — the per-repo instruction file format Hive's parser understands. Injected into kicks once `project.checkouts_dir` gives Hive a checkout to read it from — see the page. diff --git a/docs/content/hive/architecture.md b/docs/content/hive/architecture.md index 287c481..48d985f 100644 --- a/docs/content/hive/architecture.md +++ b/docs/content/hive/architecture.md @@ -186,10 +186,11 @@ flowchart LR ## Archetypes for long-running work -Long-running runs use a provisional vocabulary while the stage handoff receipt -schema and proof contract settle ([#8295](https://github.com/hivecommons/hive/issues/8295)). -The names describe roles in the existing architecture, not new machinery, and -remain provisional until the adapter, effect, and proof contract lands. +Long-running runs use the settled archetype vocabulary recorded in +[#7620](https://github.com/hivecommons/hive/issues/7620) and implemented through +the #8290 runs work. The names describe roles in the existing architecture, not +new machinery: the receipt schema, adapter, effect, and proof contract have +landed, so these terms are now the design record rather than provisional labels. **Oracle** is the source-of-truth observer for actionable work. In Hive that is the `pkg/worksource` seam: it normalizes GitHub issues, Linear/Jira items, and diff --git a/docs/content/hive/contributor-relay.md b/docs/content/hive/contributor-relay.md index 01ddc26..40238b5 100644 --- a/docs/content/hive/contributor-relay.md +++ b/docs/content/hive/contributor-relay.md @@ -40,6 +40,15 @@ just contribute-hive `contribute-setup` is one-time per hive: it registers you (your GitHub identity plus a registration token stored in `${HOME}/.config/hive/contributor.env`), authenticates `gh`, and verifies the CLI backend you chose. Every hive also serves a landing page at **`https:///contribute`** with live queue stats and copy-paste setup commands tailored to the CLI you pick. +Operators can publish a short **Help & community** link list with +`contribute.help_links` (also editable from Governor → Hub and `/contribute` +Management). The dashboard shows those links on Onboarding and Operations, and +the hub includes them in `auth_ok` so the relay prints them once when it +connects. Use it for contributor docs, Discord/Slack invites, or a maintainer +issue queue. Discord `https://discord.com/channels//` URLs only +work for people already in that server; use a `https://discord.gg/...` invite if +new contributors need to join. + `contribute-hive` starts the relay in one of two modes: ```bash @@ -110,6 +119,8 @@ Important environment variables: | `AGENT_BACKEND` | `claude` | CLI/backend to run (`claude`, `copilot`, `goose`, `bob`, `codex`, `pi`, `aider`, `litellm`, `agy`, `opencode`, `kilo`, `muse`, `omp`, depending on image support and credentials). `omp` is interactive-only: Hive starts normal `omp --model ` in the prepared tmux cwd and passes no fabricated permission flags. It has no verified local confinement mechanism, so local mode refuses it without `HIVE_OMP_DANGEROUSLY_RUN_UNCONFINED=1`; container mode is the supported boundary. `agy` has the same confinement limit. `opencode`, `kilo`, and `muse` only run headless (`CONTRIBUTOR_MODE=headless`) — hive has no interactive-tmux wiring for them. | | `AGENT_MODEL` | unset (backend default) | Optional model override passed to the contributor agent (e.g. `claude-sonnet-4-6`, `gpt-4o`, `gemini-2.5-pro`). Declared to the hive when the relay connects. | | `AGENT_REASONING_EFFORT` | unset | Reasoning effort override. Consumed by `codex` (`-c model_reasoning_effort`), by `agy` (`--effort low\|medium\|high`, required whenever a model is set, else agy ignores the model), by `muse` (`--reasoning-effort none\|minimal\|low\|medium\|high\|xhigh\|max\|ultra`, applied with or without a model; a value outside that set is dropped rather than passed, because muse exits 2 on it), and by `claude` (`--effort low\|medium\|high\|xhigh\|max`, applied with or without a model; a value outside that set is dropped the same way, and unset leaves Claude Code at its own default - [#8377](https://github.com/hivecommons/hive/issues/8377)). Ignored by other backends, including inference routes such as `litellm` that drive the claude binary. | +| `HIVE_CONTRIBUTOR_KNOWLEDGE_EXPORT_MAX_FACTS` | `80` | Maximum entries in the `/api/knowledge/export` response when it is fetched with a contributor registration token. Owner/API-token exports remain full; contributor startup context receives a bounded summary with a truncation marker and should fetch more specific entries on demand with `hive knowledge` or the Hive MCP knowledge tool. | +| `HIVE_CONTRIBUTOR_KNOWLEDGE_TOKEN_BUDGET` | `12000` | Estimated startup-token budget for the Hive knowledge file linked into backends that need a smaller context. Pi uses this budget for its auto-loaded `AGENTS.md`/`CLAUDE.md`: Hive keeps the full export at `~/agent.md`, writes a budgeted `~/agent.pi-context.md`, orders repo/task-matching entries first when those task env vars are present, appends a truncation marker when entries are omitted, and points the model at `hive knowledge` / the Hive MCP knowledge tool for on-demand lookup. | | `CONTRIBUTOR_MODE` | `interactive` | `interactive` keeps a tmux/TTY session. `headless` is for one-shot/no-TTY task delivery. | | `HIVE_AGENT_SESSION` | `contributor` | tmux session name for interactive mode. | | `HIVE_SESSION` | backend name (`AGENT_BACKEND`) | Optional session label for running multiple relays under one GitHub account (see [Running multiple backends under one account](#running-multiple-backends-under-one-account)). Relays with distinct labels get independent session-scoped identities (`ContributorID#session`) on the hub, so their task leases, assignment cooldowns, failure streaks, and ownership fences do not collide. Auth, trust tier, model admission, and rate-limit accounting stay per-account. Sanitized on the hub: only `[A-Za-z0-9._-]` survive, capped at 32 bytes; a label that sanitizes to empty counts as unset. Set it to the **empty string** to opt out — the relay then declares no session and keeps the bare per-account identity (the historical single-session behavior). | @@ -152,7 +163,7 @@ mode fixed for Goose in [#2393](https://github.com/hivecommons/hive/issues/2393) | `copilot` | `copilot-instructions.md`, `COPILOT.md`, `CLAUDE.md` | | `goose` | `AGENTS.md`, `.goosehints`, `.goose-instructions.md`, `CLAUDE.md` | | `codex` | `AGENTS.md`, `CLAUDE.md` | -| `pi` | `AGENTS.md`, `CLAUDE.md` | +| `pi` | `AGENTS.md`, `CLAUDE.md` (linked to a budgeted `agent.pi-context.md`; full export stays at `agent.md`) | | `bob` | `.bob/AGENTS.md`, `CLAUDE.md` (compatibility) | | `agy` | `CLAUDE.md` | | `opencode` | `AGENTS.md`, `CLAUDE.md` | @@ -520,6 +531,7 @@ Only issues that pass **all** of these filters are offered to contributors: | Control | Config key | Behavior | |---|---|---| | **Repos for Contribute** | `disabled_repos` | Per-repo toggle. A monitored repo serves work unless it is listed in `disabled_repos`; newly added repos default to **on**. | +| **Repo Filters** | `contribute_repo_filters` | Optional full `owner/repo` overrides edited from each Repos-for-Contribute row. Each override has the same title, author, and label lists plus `deny`/`allow` modes. Hive-wide skip labels and hive-wide filters run first, so a repo can never re-admit work they denied; repo deny mode extends the hive-wide deny list and repo allow mode narrows only that repo. | | **Label filter** | `contribute_labels_mode` + `contribute_deny_labels` | Set `contribute_labels_mode` to `deny` (default) so listed labels exclude an issue (e.g. `hold`, `wontfix`, `duplicate`), or to `allow` so an issue must carry one of the listed labels to queue (e.g. `good-first-issue`, `help-wanted`). | | **Contribute skip labels** | `contribute_skip_labels` / `HIVE_CONTRIBUTE_SKIP_LABELS` | Hive-wide “not contributor work” labels that are never offered even before normal filters run. Default: `blocked,tracking,epic,discussion,question,needs-decision,needs-triage`; `blocked` is always added as a floor. Comma-separated entries are case-insensitive and use `path.Match`-style `*` globs, so projectbluefin can set `wayfinder:map,wayfinder:grilling,wayfinder:research` (or `wayfinder:*`) to keep decision briefs out of the relay. | | **Title filter** | `contribute_titles_mode` + `contribute_deny_titles` | Title patterns. With `contribute_titles_mode` set to `deny` (default) a matching title excludes the issue; set it to `allow` so only issues whose title matches one of the patterns queue. Supports `*`-wildcards (`*dashboard*`, `epic:*`) and slash-delimited regex (`/renovate/`, always case-insensitive). | @@ -530,6 +542,21 @@ The legacy `contribute_allow_labels` field is retained only for one-time migrati The list keys keep their `deny_*` names in every mode for backward compatibility with existing on-disk config; the `*_mode` key decides whether the list is a denylist or an allowlist. An empty list in `allow` mode is treated as "filter off" rather than "nothing passes", so a half-configured filter never silently empties the queue. +Per-repo filter entries are keyed by full repo name: + +```yaml +hub: + contribute_repo_filters: + projectbluefin/common: + labels_mode: deny + deny_labels: ["2-discussing"] + projectbluefin/docs: + labels_mode: allow + deny_labels: ["good-first-issue"] +``` + +The Operations policy panel and withheld-work diagnostics show the effective repo filter when it is what kept an issue out of the queue. + ### Cooldown After a contributor completes an issue, the hub keeps that issue out of the queue for a while so the same work is not handed straight back out: @@ -538,9 +565,16 @@ After a contributor completes an issue, the hub keeps that issue out of the queu |---|---|---| | **Cooldown** | `contribute_cooldown_enabled` | Toggles the post-completion cooldown. Absent (older config) or `true` means enabled; an explicit `false` disables it, so no completed issue is ever excluded for cooldown. Failure quarantine is separate and stays on either way. | | **Cooldown Hours** | `contribute_cooldown_hours` | Length of the with-PR completion cooldown in hours. `0` or unset means the default of `168` (one week); any positive value is clamped to `1`-`8760`. The short no-PR cooldown is fixed and not tuned here. | +| **Already-done label** | `contribute_already_done_label` | Label applied when a `no_work_needed` verdict is marked `verdict_reason_kind: "already_done"` (or legacy text such as `merged PR #123 already resolves this`). Default `hive/already-done`, which is also in the default contribute skip labels so it stays out of the offer queue until a maintainer removes it. | +| **Close already done** | `contribute_close_already_done` | When explicitly `true`, a verified already-done verdict may close the issue after the hub verifies the cited PR is merged, or commit is on the default branch. Unset defaults to comment + label only; close is still ACMM-gated. | +| **Already-done hold** | `contribute_already_done_hold_days` | Days to suppress re-offer when an already-done verdict is pending label/comment or cites evidence the hub cannot verify. Default `30`; valid non-zero values are clamped to `1`-`365`. | ### Queue hold and priority +The **Operations** tab also includes a public-safe **Most effective models** panel. It reads the same aggregate PR rework data as the Governor PRs-by-model view plus the contributor task-run log, then ranks model + CLI pairs for `7d`, `30d`, or `all` by visible measures: merged PRs, first-pass merge rate, average review rounds, average fix attempts, verified-PR run rate, failure rate, and completed-without-PR (“nothing to ship”) rate. Rows below `HIVE_CONTRIBUTE_EFFECTIVE_MODELS_MIN_PRS` merged PRs (default `5`) are shown under “Not enough data yet” instead of being ranked, and the response is aggregate-only: no contributor usernames, pane output, tokens, or per-contributor breakdowns. + +The dashboard **Governor** card's **PRs by model** section uses that same model-effectiveness aggregation for the same `7d`, `30d`, and `all` windows. It keeps the merged/open/closed bar for PR volume, adds compact columns for merged count, first-pass merge rate, verified-PR run rate, failure rate, and “nothing to ship” rate, and badges ranked models that clear the merged-PR threshold. Operators can toggle the row order between effectiveness rank (default) and raw PR count. + The **Operations** tab lets an operator reorder and park individual issues in the ready-work queue. Both controls persist on the hub configuration alongside the filters above, but they are edited only through two authenticated endpoints (owner or read-write role; a read-only or anonymous caller gets `403`): | Endpoint | Config key | Behavior | @@ -564,7 +598,7 @@ Withheld rows carry a stable reason code and, where the refusing gate had one, t | Reason | Meaning | Evidence | |---|---|---| | `open_pr_claim` | An open pull request already claims the issue. | Claiming PR URL and author | -| `issue_claim` | Someone has claimed the issue on the issue itself - a `hive-claim` marker comment or an assignee - and the claim has not expired ([#8380](https://github.com/hivecommons/hive/issues/8380)). Only while `governor.claims.enabled` is on. | `claimed_by` and `claim_expires_at` | +| `issue_claim` | Someone has claimed the issue on the issue itself - a `hive-claim` marker comment posted by the hive's own App bot, or an assignee - and the claim has not expired ([#8380](https://github.com/hivecommons/hive/issues/8380)). Only while `governor.claims.enabled` is on. | `claimed_by` and `claim_expires_at` | | `merged_claim_stale` | A merged pull request (or a verified `no_work_needed` verdict) has claimed to fix the issue for 7+ days and the issue is still open; the next step is a maintainer's — close it, or say what remains ([#8003](https://github.com/hivecommons/hive/issues/8003)). | Fixing PR URL and author; the age in days | | `issue_churn` | The issue has already absorbed several merged or abandoned pull requests without settling, so what is left is a maintainer's call ([#7995](https://github.com/hivecommons/hive/issues/7995)). | Merged / closed-unmerged counts and the PR numbers | | `workflow_blocked` | The issue carries the `blocked` workflow label. | Matched label | @@ -648,6 +682,10 @@ deliberate gate, not an oversight. The generated Secret contains the registration token and `GH_TOKEN` as Kubernetes Secret data. Treat it as sensitive cluster-readable material and prefer a pinned image tag/digest for repeatable operation. +## Operations messages + +Owners and read-write operators can use the Operations page's **Message** action on a contributor card (or after a run-history lookup) to send a short note to exactly that contributor ([#8461](https://github.com/hivecommons/hive/issues/8461)). The hub stores the note on the recipient's contributor profile until the contributor acknowledges it, shows it as a banner on their signed-in `/contribute` Operations/Profile pages, and pushes it to every live relay connection for that same contributor identity. The relay prints the note as "Message from the hive operator" (reverse video on a TTY unless `NO_COLOR` is set) and strips terminal control characters before output; the text is never passed to the agent CLI as input. Acknowledgement, and an optional short reply, are recorded back on the profile so operators can see whether the message was delivered and read. + ## How the hub picks work for contributors Two admission behaviors are worth knowing when your relay seems idle: @@ -657,11 +695,7 @@ Two admission behaviors are worth knowing when your relay seems idle: - **A closing keyword written as prose counts.** The claim parser used to require GitHub's own trailer shape, `keyword #N` (optionally with a colon), so a merged PR whose body read *"Resolves architect issue #1232 (first incremental step)"* produced **no claim at all** ([#7995](https://github.com/hivecommons/hive/issues/7995)). Since that issue the closing tier accepts the same bounded run of prose the non-closing reference tier already did — at most 40 characters, no `.`, newline or `#` — so `Resolves architect issue #1232` and `Fixes the bug in #12` are closing claims. GitHub will still not auto-close on those, and hive does not pretend it will: a claim here is about whether the **work landed**, and a merged PR that says it resolves an issue is the strongest evidence the hub gets, so it suppresses rather than being released for re-verification after every merge. The prose gap must begin with a space or tab, which is what keeps a Conventional Commits type prefix (`fix:`, `fix(scope):`) from claiming the first issue number in a title. The closing tier remains single-issue, matching GitHub's one-keyword-per-number rule; only the reference tier reads lists. - **A merged fix does not expire on a clock.** A strong claim from a merged PR — or a verified `no_work_needed` verdict — used to leave the ledger 72 hours after the merge, because the settle scan looks back 72h and the ledger TTL matched it. The PR was still merged; only the clock had moved. So the issue went straight back into the offer pool, an agent re-verified "already fixed on main", and the verdict claim it left sat on the same 72h clock — one wasted task cycle every three days for as long as nobody closed the issue ([#8003](https://github.com/hivecommons/hive/issues/8003): projectbluefin/chairlift#55, fixed by #133, re-offered three times with two "please close" agent comments on it). Settled claims are now carried forward across scans for 30 days from the merge; a merged *weak* claim (a `Refs #N`, or an external author's PR) is not — it never asserted it finished the issue, and is still released with context as before. And because the hold has by then outlasted every automatic bound, after **7 days** the contribute queue stops describing it as "an open pull request already claims this issue" and withholds it under `merged_claim_stale`, whose prose is the question a maintainer has to answer: *Fixed by merged PR #133 4 days ago; the issue is still open — close it or say what remains.* - **An issue that keeps consuming pull requests is withheld for a maintainer.** The claim ledger answers "is somebody on this right now?"; it could not answer "has this issue already cost seven pull requests?" ([#7995](https://github.com/hivecommons/hive/issues/7995)). projectbluefin/documentation#1232 — an incremental architecture issue — went three merged and four closed PRs deep and was still NEXT UP: every cycle an agent found remaining work, shipped the next slice, and the issue came back after the merge, because only a human can decide that an incremental issue is *done*. So the same two PR listings the claim scan already pages through now also feed a cumulative **churn history**: which pull requests have been observed against each issue, and how each one ended. A closed-without-merge PR still claims nothing — the issue stays released for work — it only counts. Once an issue reaches **2 merged** or **2 closed-unmerged** pull requests, the contribute queue stops offering it and withholds it with reason `issue_churn`, on the same operator-visible Withheld surface as an open-PR claim, carrying the counts and the PR numbers a maintainer needs in order to answer the question. Nothing is closed, commented on, or relabelled by the guard. It lapses on its own: records age out 14 days after a pull request was last seen (deliberately longer than the 72h settle scan, because the pattern plays out over a week or more), and a maintainer who has triaged the issue can clear the guard immediately by adding the label `hive: churn-triaged`. -- **An issue someone has claimed on the issue itself is withheld until the claim expires** ([#8380](https://github.com/hivecommons/hive/issues/8380), default OFF: `governor.claims.enabled: true`, or the "Issue claims" toggle on the Features panel). The PR claim ledger above protects the *end* of the pipeline; nothing marked the window between "I started on this" and "I opened a PR", so two workers that do not share hub state - a contributor reading the issue list, a second operator session, an agent on another hive - could both build the same issue (#8336 grew two identical PRs minutes apart). A claim makes the issue itself the source of truth. It is recognised in two forms, both read at enumeration time so every listing (the contribute queue, kick prompts including the scanner's, the runs API) sees the same fields: - - a **claim comment** carrying the marker `` followed by a human line (`Claimed by until .`); the most recently started marker on the issue is the one that counts, so posting a new one renews or takes over; - - an **assignee**, when no marker comment exists; that claim runs for the TTL from the issue's last activity, so an assignee who keeps the issue moving keeps it and one who went quiet loses it. - - Claims **expire**: the marker names its own expiry, and `governor.claims.ttl_s` (default 4h) is the TTL written on hub-posted claims and applied to assignee-inferred ones. An expired claim releases the issue on the next enumeration with no comment edit and no poller - liveness is judged every time the fields are read. A withheld issue shows on the Withheld surface under `issue_claim` with `claimed_by` and `claim_expires_at`. An open PR referencing the issue is the stronger, later signal and is checked first; a live claim is checked before churn. The hub itself asserts a claim when it leases a task to a relay contributor: at a trust tier whose mode may write issue comments (`newcomer` and above - the ISSUES_ONLY rung) it posts the claim comment on the issue through the forge seam, at `advisor` and `reviewer` it records the claim on the lease only; either way the runs API (`GET /api/runs`) shows `claimed_by`, `claim_expires_at` and `claim_posted`, and the lease registry carries them across a restart. A failed comment post never refuses the assignment. Reading claims costs one comment fetch per actionable issue on first sight and none until the issue's `updated_at` moves; with the feature off nothing is fetched, no field is emitted and every payload is byte-for-byte what it was. +- **An issue somebody has *claimed* is not offered — and a clanker already on it is pulled off when a higher rank claims it.** The PR-claim ledger above only knows about work that has reached a pull request. Since [#8380](https://github.com/hivecommons/hive/issues/8380) the hub also keeps a **worker-claim ledger**: who is on an issue *right now*, ranked **human > agent > contributor > external**. A person claims from the terminal (`hivectl claim owner/repo#N`) or the API (`POST /api/claims/{owner}/{repo}/{number}`); the hub records an **agent** claim for every issue a governor kick hands one of its own agents; and the relay records a **contributor** claim for your session the moment it leases you a task, releasing it when the task completes, is abandoned, is yanked or its lease expires. `selectTask` excludes every issue another holder claims exactly as it excludes leased items, and the scheduler withholds them from kicks under *In Flight*. Precedence is enforced on write: a higher rank **takes over** and the displaced holder is told to stop — for a relay session that means the hub yanks that one task (`task_revoke`, generation bumped so a late completion is fenced) and hands the session its next admissible item in the same call, leaving your other sessions alone; for an agent or an external bot it means a `🔁` comment addressed to it plus a `preempted:` label on the issue. Same rank warns unless forced; a lower rank is refused. Claims lapse on a per-kind TTL (`claims.human_ttl_s` 4h, `agent_ttl_s` 2h, `contributor_ttl_s` 30m — the relay lease length — capped by `max_ttl_s` 24h) and `claims.enabled: false` turns the whole mechanism off. Every transition is mirrored onto the issue as a comment carrying a `` marker (or `` on takeover) and a `claimed` label, so a relay that only reads GitHub can still see it was preempted. - **Claims expire.** Ledger entries live 72 hours — refreshed while the PR stays open, or anchored at the merge for a merged claim, so a settled issue is suppressed for 72h after its fix lands and nothing is stranded forever. An **open** claiming PR that goes red on a required check and stale releases the issue back to the queue; merged claims never take that valve — a fix already on `main` cannot go red. - **A repository the App cannot mint a token for is excluded, not fatal.** Since C4 the `task_assign` token is scoped to the chosen item's repository, so GitHub's `422 There is at least one repository that does not exist or is not accessible to the parent installation` means *that repo* — renamed, deleted, or removed from the installation — and nothing about the tier or the App key. It used to fail the whole selection with `token_mint_failed`, and because selection is deterministic the same doomed item was chosen on every 30 s retry: one stale entry in the project repo list (a renamed repo) wedged a hive for every contributor while `actionable_items` sat at 19 ([#7869](https://github.com/hivecommons/hive/issues/7869)). Now the claim is rolled back, the repo is excluded from selection for `mintFailureRepoCooldown` (10 min, so the fleet is not re-discovering it every retry, but the operator's fix takes effect without a restart), and the *same* call selects again from the remaining candidates (bounded at three such skips). If nothing else is admissible the reason is `repo_unmintable` rather than `no_matching_work` or `token_mint_failed`, and the hub log names the repo with a pointer at the repo list. Non-repo mint failures (5xx, bad key, an unaccepted permission) keep the `token_mint_failed` contract and exclude nothing — they would recur for any candidate. @@ -724,8 +758,8 @@ Evidence, strongest first, and what each buys: | Evidence | Where it is checked | What the ledger books | |---|---|---| | A PR URL for the task's repo that GitHub confirms exists and is not refuted (`resolveTaskPR()` → hub `verifyReportedPRDetail`) | relay + hub | Full completion: `TasksCompleted++`, `TasksWithPR++`, with-PR cooldown. The only evidence that is not self-reported. | -| A `no_work_needed` verdict whose reason cites a settling PR or commit that GitHub confirms ([#7871](https://github.com/hivecommons/hive/issues/7871)) | hub, async after booking | `no_work_needed` completion plus a **verified** claim-ledger entry on the issue — the citation becomes a real claim, not prose. | -| A `no_work_needed` verdict with no verifiable citation ([#3987](https://github.com/hivecommons/hive/issues/3987)) | hub | `no_work_needed` completion; offer-pool suppression until newer activity or the window ends. Nothing is closed or labelled. | +| A `no_work_needed` verdict whose reason cites a settling PR or commit that GitHub confirms ([#7871](https://github.com/hivecommons/hive/issues/7871), [#8477](https://github.com/hivecommons/hive/issues/8477)) | hub, async after booking | `no_work_needed` completion plus a **verified** claim-ledger entry on the issue — the citation becomes a real claim, not prose. If the relay marks it `verdict_reason_kind: "already_done"` with `evidence: {"pr": 123}` or `{"commit": "sha"}` (or old relay text conservatively matches "merged PR #123" / "already fixed"), the hub comments and applies `contribute_already_done_label` (default `hive/already-done`). With `contribute_close_already_done: true` and sufficient ACMM, it closes instead after commenting/labeling. | +| A `no_work_needed` verdict with no verifiable citation ([#3987](https://github.com/hivecommons/hive/issues/3987)) | hub | `no_work_needed` completion; offer-pool suppression until newer activity or the window ends. If it was marked already-done but verification failed, the issue is still commented/labeled when possible, the run is marked `already-done-unverified`, and the longer `contribute_already_done_hold_days` window is used. | | A `blocked` verdict — nothing in the repo can move until something outside it lands ([#7924](https://github.com/hivecommons/hive/issues/7924)) | hub + relay | `blocked` completion: the **full with-PR cooldown** at once (not the 4h ladder), a marked ledger row carrying the reason, no settle attempt from it. The relay, with the task credential, applies the repo's `blocked` label so the admission gate holds the issue until a human clears it. | | A PR-less `complete` from a relay that said how it decided (`completion_signal` = `verdict` or `chrome_idle`; [#6723](https://github.com/hivecommons/hive/issues/6723), [#7862](https://github.com/hivecommons/hive/issues/7862)) | hub `isEvidenceLessCompletion` | **Evidence-less**: the flat `completedNoPRCooldownHours` cooldown only, no escalation, no `TasksCompleted++`. | | A PR-less `complete` with `completion_signal` = `unknown` (a relay predating [#5376](https://github.com/hivecommons/hive/issues/5376), or the headless path) | hub | Booked as a completion — the deliberate compatibility exception: the hub changes behaviour only for a relay that has told it how the task ended. Upgrading the relay closes it. | @@ -753,6 +787,12 @@ The agent can now say it explicitly, the same way it says `no_work_needed`: - **Relay: the label.** When the hub's `auth_ok` `permissions` include `issues:write` (every tier from `newcomer` up) and the task is a GitHub issue, the relay runs `gh issue edit --add-label blocked` with the task credential *before* dropping it at task exit — the same ordering as the #7879 PR comment. If the repository does not define the label, the relay creates it once and retries once; any further failure costs a log line, never the completion. Without `issues:write` (an `advisor`-tier credential, an older hub that sends no `permissions`), the cooldown above is the whole hold. **Lifting the label stays human**: the relay never removes it, so the admission gate holds the issue past the cooldown until someone who knows the dependency has cleared says so. - **Prompt: the comment.** The assignment prompt now asks the agent, before printing either `no_work_needed` or `blocked`, to leave one comment on the issue naming exactly what covers or blocks it — the open or merged PR, the commit, or the external dependency — signed with the same `— hive: …` attribution line as a PR body. That comment is what puts the finding on GitHub rather than only in this hub's ledger: it creates the PR→issue cross-reference nobody had made (fsdk-containers#299 was correctly `no_work_needed` for open PR #289 with no text ref, no sidebar link and an empty cross-reference timeline, so the merge could not close it and the next cycle had to re-verify), and it tells a human why the `blocked` label appeared. The prompt also fixes a boundary: the agent must never edit someone else's PR body to add `Fixes #N` — if that PR's merge should close the issue, it says so in a comment on the PR, noting that only a maintainer editing the body makes the merge close it. +### A maintainer-decision verdict is labelled until a human answers + +When the agent determines that nothing is shippable until a maintainer makes a design, policy, or approval decision, it prints `HIVE_VERDICT: no_work_needed — decision: ` ([#8470](https://github.com/hivecommons/hive/issues/8470)). The relay keeps the backward-compatible `no_work_needed` wire verdict and adds `verdict_needs_decision: true`; a verified PR still wins and suppresses the verdict. + +The hub books the issue for the full with-PR cooldown immediately and records a `needs_decision` ledger/run-log marker. The relay applies the label advertised by the hub in `auth_ok` (`hub.contribute_needs_decision_label`, default `needs-decision`) using the same task credential path as the `blocked` label. Empty config disables relay labelling, but the cooldown still applies. The relay posts no extra comment: the contributor's assessment comment is the human-readable record. The label is never cleared automatically; removing it is the maintainer signal that the decision has been made. The configured label is also treated as a contributor skip label, so a custom label such as `2-discussing` keeps the issue out of the offer queue until a human removes it. + ### A prompt that was typed is not a prompt that was submitted The relay delivers a task prompt by typing it into the pane with `tmux send-keys -l` and then sending Enter. A task prompt is around 2 KB, so it arrives as one burst — and a TUI that implements bracketed-paste handling classifies a burst that fast as **pasted content**. codex collapses it to `[Pasted Content 1024 chars]` in its input widget and takes the Enters that follow as newlines *inside* the paste rather than as submit. The prompt sits in the widget, and the agent is never told anything. @@ -1477,10 +1517,16 @@ Protocol 1.4 adds one optional relay health report: `auth_response` may carry `knowledge_loaded: true|false` plus `knowledge_error` when the relay's `~/agent.md` is missing or fails the knowledge-export shape check. The hub stores that state on the contributor profile and surfaces it on the Operations clanker -row as either `no knowledge loaded` or `knowledge: unknown` for old relays that -omit the field. A relay may later send `knowledge_state` with the same two fields -when its background knowledge refresh changes the loaded state; old hubs ignore -the new message, and new hubs treat an absent field as unknown rather than false. +row: loaded knowledge renders no badge, a reported missing or invalid export shows +`no knowledge loaded` with the relay's reason in the tooltip, and a protocol 1.4+ +relay that omits the state shows the warning `knowledge: not reported` because a +current relay should have sent it. Older relays (protocol before 1.4, or no +declared protocol) instead get a neutral grey `knowledge: not reported — relay +too old` badge whose tooltip points at the protocol mismatch line and tells the +contributor to update the checkout and restart `just contribute-hive`. A relay +may later send `knowledge_state` with the same two fields when its background +knowledge refresh changes the loaded state; old hubs ignore the new message, and +new hubs treat an absent field as not reported rather than false. ## Custom stylesheets diff --git a/docs/content/hive/documentation-map.md b/docs/content/hive/documentation-map.md new file mode 100644 index 0000000..e137acf --- /dev/null +++ b/docs/content/hive/documentation-map.md @@ -0,0 +1,191 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/documentation-map.md) 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](https://github.com/hivecommons/hive/blob/v5/src/docs/migration-v2-v4.md), and v4 operators should use the [v4 → v5 migration guide](https://github.com/hivecommons/hive/blob/v5/src/docs/migration-v4-v5.md). + +## Operations + +- [Manual provisioning](/docs/hive/manual-provisioning) — heartbeat-only cluster provisioning, hub access roles, and common gotchas. +- [Hosted Hive Hub onboarding](https://github.com/hivecommons/hive/blob/v5/src/docs/hosted-hub.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/hub-deployment.md) — `HIVE_MODE=hub`, hub storage, heartbeat secrets, and SaaS spoke registration. +- [`CAP_NET_ADMIN` and self-hosted spokes](/docs/hive/net-admin-requirement) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/config-layering.md) — how ConfigMap seed, PVC dashboard overlay, and runtime config interact. +- [Operator reference](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md) — top-level config blocks, hive flags/env, GitHub token scopes, and image provenance. +- [Token mint](https://github.com/hivecommons/hive/blob/v5/src/docs/token-mint.md) — 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](/docs/hive/adr/0007-token-mint). +- [Changelog](https://github.com/hivecommons/hive/blob/v5/CHANGELOG.md) — recent user-visible changes and release notes. +- [Release channels](/docs/hive/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](https://github.com/hivecommons/hive/blob/v5/src/docs/release-rollback.md) - 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](https://github.com/hivecommons/hive/blob/v5/src/docs/v5-ga.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/v5-candidate-week.md) — 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)](https://github.com/hivecommons/hive/blob/v5/src/docs/stable-soak-policy.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/hivecommons-migration.md) — phased org/package migration status, operator promises, and sequenced closeout checklist. +- [v4 → v5 forward-port sync policy](https://github.com/hivecommons/hive/blob/v5/src/docs/v5-sync-policy.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/v4-freeze-runbook.md) — the mechanics behind the accepted freeze policy (#6346), already wired behind the `V4_FEATURE_FREEZE` repository variable: the one-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](https://github.com/hivecommons/hive/blob/v5/src/docs/v5-migration-announcement.md) — **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](https://github.com/hivecommons/hive/blob/v5/src/docs/dibs-domain-cutover.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/spoke-wildcard-tls.md) — how to point a cluster's provisioned spokes at the wildcard instead of one certificate per hive, the two cluster prerequisites that must hold first, and which hosts a wildcard cannot cover. +- [Tagged releases](https://github.com/hivecommons/hive/blob/v5/src/docs/releases.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard-standalone-upgrades.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard-design-system.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/auto-update-profile.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/env-vars.md) — centralized list of runtime, deployment, hub, backup, and contributor environment variables. +- [Kubernetes deployment](https://github.com/hivecommons/hive/blob/v5/README.md#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/`](https://github.com/hivecommons/hive/blob/v5/src/deploy/k8s/). See also [dashboard route and health checks](https://github.com/hivecommons/hive/blob/v5/src/docs/health-checks.md) and the Kubernetes CronJob in [backup and restore](/docs/hive/backup-dr). +- [Troubleshooting](/docs/hive/troubleshooting) — container logs, config validation, agent tmux sessions, dashboard auth, GitHub credential checks, and GitHub App workflow-permission push rejections. +- [Cross-cluster migration](https://github.com/hivecommons/hive/blob/v5/src/docs/cross-cluster-migration.md) — the manual procedure for moving a hive between clusters. +- [Self-hosted Kubernetes cluster move](https://github.com/hivecommons/hive/blob/v5/src/docs/move-kubernetes.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/move-hub-registered-cutover.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/move-host.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/move-cross-runtime.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/migration-v2-v4.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/migration-v4-v5.md) — 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](https://github.com/hivecommons/hive/blob/v5/UPGRADE.md) — preparing for v4 → v5 and future major-version boundaries. +- [Dashboard route and health checks](https://github.com/hivecommons/hive/blob/v5/src/docs/health-checks.md) — `dashboard-route-rbac.yaml`, `route_exists`, listener probes, and alert behavior. +- [Fleet health: the verdict and remediation hints](https://github.com/hivecommons/hive/blob/v5/src/docs/fleet-health.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/fleet-drift-signals.md) — 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`)](https://github.com/hivecommons/hive/blob/v5/src/docs/fleet-report.md) — 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 only issues the hive itself opened. +- [Agent self-healing watchdog](https://github.com/hivecommons/hive/blob/v5/src/docs/agent-watchdog.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-log.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/repo-pause.md) — quieting ONE 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](https://github.com/hivecommons/hive/blob/v5/src/docs/token-access-log.md) - 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](https://github.com/hivecommons/hive/blob/v5/src/docs/per-repo-agents.md) — scoping an agent to the repositories it serves with `repos:`, so which agents exist is a per-repo answer instead of a hive-wide one: 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`](https://github.com/hivecommons/hive/blob/v5/src/docs/hive-open-pr.md) — 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`](https://github.com/hivecommons/hive/blob/v5/src/docs/hive-merge.md) — 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`](https://github.com/hivecommons/hive/blob/v5/src/docs/hive-open-issue.md) — 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](https://github.com/hivecommons/hive/issues/6927)), and the exponential-backoff retry contract. +- [Review-bot threads on hive-mediated PRs](https://github.com/hivecommons/hive/blob/v5/src/docs/review-bot-threads.md) — 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](https://github.com/hivecommons/hive/issues/7360)). +- [Network and port requirements](https://github.com/hivecommons/hive/blob/v5/src/docs/network-requirements.md) — inbound ports, proxy paths, egress, and firewall guidance. +- [TLS, HTTPS, and certificates](https://github.com/hivecommons/hive/blob/v5/src/docs/tls-setup.md) — termination patterns and certificate ownership. +- [Security notes](https://github.com/hivecommons/hive/blob/v5/src/docs/security.md) — log scrubbing and secret redaction guarantees/limits. +- [Token collection and usage tracking](https://github.com/hivecommons/hive/blob/v5/src/docs/token-tracking.md) — session JSONL, `/api/cost`, and hub usage rollups. +- [Notifications](https://github.com/hivecommons/hive/blob/v5/src/docs/notifications.md) — ntfy, Slack, and Discord alert channels, plus the two-way [Discord bot](https://github.com/hivecommons/hive/blob/v5/discord/README.md). +- [State-triggered hooks](https://github.com/hivecommons/hive/blob/v5/src/docs/hooks.md) — declarative `transition → action` rules, the transition catalog, the vetted action set, and the security model (RFC #4001). +- [CEL-based agent triggers](https://github.com/hivecommons/hive/blob/v5/src/docs/cel-triggers.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/runs.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/spektacular.md) — the Hive side of long-running runs (#8303, umbrella #8290): a run moves through `spec` → `plan` → `implement` stages on one 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`](https://github.com/hivecommons/hive/blob/v5/src/docs/design/run-artifacts.md). +- [Audit campaign](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-campaign.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/snapshots.md) — read-only `/snapshot`, custom CSS, and frame-ancestor sharing. +- [hivectl](/docs/hive/hivectl) — command-line client for the dashboard API, including + [`hivectl tui`](/docs/hive/hivectl#tui--live-terminal-dashboard), the full-screen + terminal dashboard: keybindings, pane cadence, and v1 boundaries. See + [the design record](https://github.com/hivecommons/hive/blob/v5/src/docs/design/tui.md) for the reasoning behind it. +- [`bd` beads CLI](https://github.com/hivecommons/hive/blob/v5/src/docs/beads-cli.md) — work-ledger and knowledge command reference for operators and contributors. +- [Backup and restore](/docs/hive/backup-dr) — `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 one hive's config and GitHub App keys onto another's ([#6529](https://github.com/hivecommons/hive/issues/6529)). +- [Hub disaster recovery](https://github.com/hivecommons/hive/blob/v5/docs/HUB_DISASTER_RECOVERY.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/deployment-scripts.md) — 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](https://github.com/hivecommons/hive/blob/v5/bin/README.md) — map of the deterministic pipeline and operational scripts, grouped by function. +- [Dashboard API reference](https://github.com/hivecommons/hive/blob/v5/src/docs/api-reference.md) — pragmatic route index for dashboard and hub endpoints. +- [Dashboard OpenAPI spec](https://github.com/hivecommons/hive/blob/v5/dashboard/openapi.json) — machine-readable REST API reference for integrations. +- [ioscan status](https://github.com/hivecommons/hive/blob/v5/src/docs/ioscan.md) — the untrusted-input scanner/canary feature (live and default-on in v4). +- [Deployment scripts](https://github.com/hivecommons/hive/blob/v5/src/deploy/README.md) — inventory of deployment helpers, including dashboard TTY panes and `hive-panes`. + +## Contributors and access + +- [Getting started as a first-time contributor](https://github.com/hivecommons/hive/blob/v5/docs/getting-started-contributing.md) — 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](https://github.com/hivecommons/hive/blob/v5/docs/development.md) — the local workflow for contributing to the Go codebase on `v4`: prerequisites, build, and test loop. +- [ClankeR contributor relay](/docs/hive/contributor-relay) — local contributor setup, multi-hub subscriptions, moving a relay to another machine, and role requests. +- [Backend smoke](https://github.com/hivecommons/hive/blob/v5/src/docs/backend-smoke.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/cli-pins.md) — 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 one labelled PR per CLI. +- [Contributor trust tiers and delegated agent roles](https://github.com/hivecommons/hive/blob/v5/src/docs/contributor-trust-and-roles.md) — newcomer/contributor/trusted/merger/advisor semantics, **Acting as**, grants, and delegatable roles. +- [Credly badges](https://github.com/hivecommons/hive/blob/v5/src/docs/credly-badges.md) — planned integration design; currently a placeholder mapping only. + +## Configuration and agents + +- [Agent configuration](/docs/hive/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](https://github.com/hivecommons/hive/blob/v5/src/docs/formal-verification.md) — the optional L5/L6 `quality.formal` capability for agent-authored Spin/Promela models, reporting-only CI, and deduplicated counterexample issues. +- [Advisory digest](https://github.com/hivecommons/hive/blob/v5/src/docs/advisory.md) — what the digest shows (`max_findings`, `show_all`), how stale findings are marked unverified, and which positive signals retire findings. +- [Advisory digest staleness](https://github.com/hivecommons/hive/blob/v5/src/docs/advisory-staleness.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/governor-thresholds.md) — how idle/quiet/busy/surge thresholds scale with repo count, the `threshold_scaling` curves, and when explicit thresholds win. +- [Large-spoke scale envelope](https://github.com/hivecommons/hive/blob/v5/src/docs/scale-envelope.md) — the backlog size one 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](https://github.com/hivecommons/hive/blob/v5/src/docs/supervisor.md) — supervisor policy modes, bead roles, and when to enable the orchestration lane. +- [Telemetry agent](https://github.com/hivecommons/hive/blob/v5/src/docs/telemetry.md) — the L5/L6-only opt-in observability agent, ACMM level gating, and the `project_observability` opt-in flow. +- [Operations agent](https://github.com/hivecommons/hive/blob/v5/src/docs/operations.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/custom-stylesheets.md) — operator-supplied CSS for the dashboard and public snapshot. +- [Branding a hive](https://github.com/hivecommons/hive/blob/v5/src/docs/branding.md) — persistent per-deployment name, mark, and colours via `/branding/branding.json` and `custom.css` (`HIVE_BRANDING_JSON`/`HIVE_BRANDING_CSS`); distinct from the per-request `?style=` stylesheets above. +- [Portable AgentDefinition format](https://github.com/hivecommons/hive/blob/v5/src/AGENT-DEFINITION.md) — standalone YAML schema for importing/exporting agent definitions. +- [Knowledge curator](https://github.com/hivecommons/hive/blob/v5/src/docs/knowledge-curator.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/skills.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/agents-md.md) — 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 one 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)](https://github.com/hivecommons/hive/blob/v5/src/docs/agent-logging.md) — pluk log format, `hive-panes`, availability, and retention. +- [Strategy Lab (Nous)](https://github.com/hivecommons/hive/blob/v5/src/docs/strategy-lab.md) — experiment lifecycle, dashboard/API configuration, fast-fail bounds, and the gate-decision flow. No `nous:` block in `hive.yaml`. +- [GitHub App setup](https://github.com/hivecommons/hive/blob/v5/src/docs/github-app-setup.md) — the Forge App on GitHub and GitHub Enterprise: app creation, permissions, Setup URL, and `/gh-setup`. +- [Forge setup: GitLab, Gitea, and Forgejo](https://github.com/hivecommons/hive/blob/v5/src/docs/forge-app-setup.md) — 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` only 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](/docs/hive/acmm-policy-matrix) — capability levels and policy modes. +- [ACMM level-up advisor](https://github.com/hivecommons/hive/blob/v5/src/docs/acmm-advisor.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/acmm-waivers.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/inception.md) — operator guide to the L1 brainstorm/inception workflow: phases, API, and template variables. +- [Planning intelligence](https://github.com/hivecommons/hive/blob/v5/src/docs/planning-intelligence.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/review-swarm.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/duplicate-sweep.md) — the opt-in (`duplicate_sweep.enabled`) cross-PR pass that clusters open PRs by changed-file set and suggests which one to keep: the two confidence tiers, how a survivor is chosen, why a bot regeneration series gets one 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](https://github.com/hivecommons/hive/blob/v5/src/docs/review-queue-triage.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/retro-lane.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/work-sources.md) — `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](https://github.com/hivecommons/hive/blob/v5/src/docs/linear-agent.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/lite-enrollment.md) — 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](https://github.com/hivecommons/hive/blob/v5/examples/acmm/README.md) — per-level ACMM policy references. +- [Sandbox isolation and agent guardrails](https://github.com/hivecommons/hive/blob/v5/src/docs/sandbox-isolation.md) — isolation layers and operator guardrail notes. +- [Per-agent gh restrictions](https://github.com/hivecommons/hive/blob/v5/config/restrictions/README.md) — file-based wrapper denials in `/etc/hive/restrictions/`. +- [Podman rootless CI](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-rootless-ci.md) — rootless Podman contract for `contribute-hive`. +- [Podman Quadlet `.kube` compatibility spike](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-quadlet-kube-spike.md) — why the standalone Kubernetes overlay is not a safe direct source for Podman units. +- [Podman ownership and cleanup contract](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-ownership-cleanup.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-preflight-host.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-preflight-ids.md) — 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](https://github.com/hivecommons/hive/blob/v5/docs/backend-setup.md) — setup notes for Claude, Copilot, Goose, Bob, Pi, Codex, and Aider. +- [Backend support tiers and acceptance bar](https://github.com/hivecommons/hive/blob/v5/src/docs/backend-support-tiers.md) — 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](https://github.com/hivecommons/hive/blob/v5/docs/inference-backends.md) — vLLM, llm-d, LiteLLM, and Model Gateway troubleshooting. +- [apiproxy](https://github.com/hivecommons/hive/blob/v5/src/docs/apiproxy.md) — Anthropic-compatible proxy logging and deployment notes. +- [Outreach anti-spam ruleset](https://github.com/hivecommons/hive/blob/v5/docs/outreach-antispam.md) — the deduplication and anti-spam rules the outreach agent operates under across awesome lists, project issues, directories, and community threads. +- [v1 to v2 migration](https://github.com/hivecommons/hive/blob/v5/docs/migration-v1-v2.md) — **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](https://github.com/hivecommons/hive/blob/v5/src/docs/migration-v2-v4.md) above. New deployments do not need it. + +## Architecture and design + +- [Architecture](/docs/hive/architecture) — process model, governor loop, guardrails, hub/spoke, and walkthrough. +- [Automatic repo ACMM onboarding reconciler](https://github.com/hivecommons/hive/blob/v5/src/docs/design/repo-acmm-onboarding.md) — proposed design for per-repo ACMM targets, gap-to-work reconciliation, human hand-off, waivers, and anti-gaming controls (RFC #6235). +- [Hive federation design](https://github.com/hivecommons/hive/blob/v5/docs/federation-design.md) — the multi-hive registry: live `/api/hives` endpoints, project onboarding, contributor flow across hubs, and what remains future design work. +- [Public roadmap](/docs/hive/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](/docs/hive/landscape) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/cncf-reference-architecture.md) — CNCF submission/reference template. +- [Podman CI runner map](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-ci-runner-map.md) — measured hosted-runner capabilities and which Podman lane goes where; SELinux is the only lane needing non-hosted infrastructure. +- [CI runner labels](https://github.com/hivecommons/hive/blob/v5/src/docs/ci-runner-labels.md) — how `runs-on:` picks the self-hosted fleet, why a fork must degrade to a GitHub-hosted runner, and the one variable `hivecommons` sets. +- [Gate-integrity invariants for agent lanes](https://github.com/hivecommons/hive/blob/v5/src/docs/design/gate-integrity-invariants.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/design/README.md) — longer-form design records with the full reasoning behind a decision, indexed with a status each (shipped / partly shipped / design only / 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](https://github.com/hivecommons/hive/blob/v5/src/docs/design/discord-issue-promotion.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/design/github-mention-triggers.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-compose-provider-spike.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/design/token-metering-ccusage.md) — proposed design for ccusage-backed token metering with attribution preservation, Bob fallback, and cutover diagnostics (RFC #6234). +- [Trajectory review](https://github.com/hivecommons/hive/blob/v5/src/docs/trajectory-review.md) — trajectory safety lane and review signals. +- [Podman Quadlet `.container`/`.pod` spike](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-quadlet-container-pod-spike.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/credly-badges.md). The longer-form design records under [`design/`](https://github.com/hivecommons/hive/blob/v5/src/docs/design/README.md) 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](/docs/hive/security-model) — 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](/docs/hive/security-threat-model) — actors, boundaries, layered defenses, known gaps, and reporting. +- [Security response process](https://github.com/hivecommons/hive/blob/v5/src/docs/security-response.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/security-self-assessment.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/ioscan-red-team.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/general-technical-review.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/heartbeat-bearer-cutover.md) — retiring the fleet-wide heartbeat bearer, whose possession proves only "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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-rootless-startup-spike.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-ipv6-egress-bypass.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-rootful-egress-baseline.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-support-matrix.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-selinux-release-qualification.md) — the one 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-volume-persistence.md) — 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 one) 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-selinux-avc-evidence.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-standalone-quadlet.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-quadlet-lifecycle.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-host-execution-gap.md) — what one 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 one: 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 one path on one host, and says so. +- [Quadlet update and rollback: moving the image, and getting back](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-quadlet-update-rollback.md) — the deliberate manual path from one 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-auto-update.md) — 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: one 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 only, 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](/docs/hive/adr/readme) — lightweight ADR process and records 0001-0017. +- [Intent verification](https://github.com/hivecommons/hive/blob/v5/src/docs/intent-verification.md) — tier-based change authorization for merge eligibility. +- [Rootless Podman CI seam](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-rootless-ci.md) — documented test intent and static contract for contributor-container runtime handling. +- [Release-line carry-forward guard](https://github.com/hivecommons/hive/blob/v5/src/docs/release-line-guard.md) — 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. diff --git a/docs/content/hive/hivectl.md b/docs/content/hive/hivectl.md index 93dd7f9..e702d4c 100644 --- a/docs/content/hive/hivectl.md +++ b/docs/content/hive/hivectl.md @@ -174,6 +174,29 @@ hivectl governor agent-add ux-discovery --backend copilot --model claude-sonnet- hivectl governor agent-remove ux-discovery --yes ``` +### claim / unclaim / claims — issue claims + +```bash +hivectl claim hivecommons/hive#8380 # "mine" — contributors and agents back off +hivectl claim hivecommons/hive#8380 --until 6h # hold longer than the hive default (4h) +hivectl claim hivecommons/hive#8380 # run again to renew +hivectl takeover hivecommons/hive#8380 # = claim --force: take over another person's claim +hivectl unclaim hivecommons/hive#8380 # release yours (or a lower-ranked holder's) +hivectl unclaim hivecommons/hive#8380 --force # owner override: release regardless of holder +hivectl claims -o json # every live claim on this hive +``` + +A claim records who is working an issue *right now* ([#8380](https://github.com/hivecommons/hive/issues/8380)). +Holders are ranked **human > agent > contributor > external**: a human's claim takes an issue over from a hive +agent or a relay contributor (the "clanker") and the displaced holder is told to stop — a relay session is +yanked off the item and handed different work immediately; an agent or an external bot sees the takeover +comment and the `preempted:` label on the issue. At the same rank the command warns (`held`, exit 3 +with the holder named) unless `--force`. A lower rank can never displace a higher one. Claims lapse on their +own (default 4h for a person, 2h for an agent kick, 30m for a relay task — configurable under `claims:` in +`hive.yaml`) and a relay's claim is released the moment its task finishes or is revoked. The hive mirrors each +transition onto the GitHub issue as a `🔒`/`🔁`/`🔓` comment with a machine-readable `` +marker and a `claimed` label, so a human, a script or another hive can see the hold without asking the API. + ### observe — read-only metrics ```bash diff --git a/docs/content/hive/readme.md b/docs/content/hive/readme.md index 06f78cc..2eb8c7d 100644 --- a/docs/content/hive/readme.md +++ b/docs/content/hive/readme.md @@ -1,188 +1,42 @@ > **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/README.md) during the docs build. Edit the canonical source in the Hive repository. -# Hive documentation +# Hive introduction -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](https://github.com/hivecommons/hive/blob/v5/src/docs/migration-v2-v4.md), and v4 operators should use the [v4 → v5 migration guide](https://github.com/hivecommons/hive/blob/v5/src/docs/migration-v4-v5.md). +Hive is a governed fleet of AI coding agents for maintaining real GitHub and forge repositories. A hive helps with triage, fixes, reviews, release operations, and operational follow-up by watching the work a project already has — issues, pull requests, review queues, and health signals — then routing appropriate tasks to agents while deterministic guardrails handle filtering, permissions, merge eligibility, audit trails, and policy. Maintainers set the autonomy boundary through the Governor and ACMM levels, so Hive can range from advisory triage to carefully gated fixes and reviews without turning repository control over to an unconstrained model. -Start with [Architecture](/docs/hive/architecture) for the system overview, then use the topic guides below. New users should start with the [getting-started guide](/docs/hive/getting-started) — it covers setting up the Forge App (the app for your source control system, e.g., GitHub, GitHub Enterprise, GitLab, or Gitea) and what to do if an inactive hosted hive is reaped. If you want the no-cluster hosted path, use the [hosted Hive Hub onboarding guide](https://github.com/hivecommons/hive/blob/v5/src/docs/hosted-hub.md). +Hive is for maintainers of busy open source projects who need help keeping queues moving, and for platform teams that want a repeatable operations plane for agent work across many repositories. It is especially useful when the hard part is not invoking one agent, but coordinating many agents with clear ownership, safety checks, and a path for human oversight. -## Operations +## Core concepts -- [Manual provisioning](/docs/hive/manual-provisioning) — heartbeat-only cluster provisioning, hub access roles, and common gotchas. -- [Hosted Hive Hub onboarding](https://github.com/hivecommons/hive/blob/v5/src/docs/hosted-hub.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/hub-deployment.md) — `HIVE_MODE=hub`, hub storage, heartbeat secrets, and SaaS spoke registration. -- [`CAP_NET_ADMIN` and self-hosted spokes](/docs/hive/net-admin-requirement) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/config-layering.md) — how ConfigMap seed, PVC dashboard overlay, and runtime config interact. -- [Operator reference](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md) — top-level config blocks, hive flags/env, GitHub token scopes, and image provenance. -- [Token mint](https://github.com/hivecommons/hive/blob/v5/src/docs/token-mint.md) — 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](/docs/hive/adr/0007-token-mint). -- [Changelog](https://github.com/hivecommons/hive/blob/v5/CHANGELOG.md) — recent user-visible changes and release notes. -- [Release channels](/docs/hive/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](https://github.com/hivecommons/hive/blob/v5/src/docs/release-rollback.md) - 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](https://github.com/hivecommons/hive/blob/v5/src/docs/v5-ga.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/v5-candidate-week.md) — 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)](https://github.com/hivecommons/hive/blob/v5/src/docs/stable-soak-policy.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/hivecommons-migration.md) — phased org/package migration status, operator promises, and sequenced closeout checklist. -- [v4 → v5 forward-port sync policy](https://github.com/hivecommons/hive/blob/v5/src/docs/v5-sync-policy.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/v4-freeze-runbook.md) — the mechanics behind the accepted freeze policy (#6346), already wired behind the `V4_FEATURE_FREEZE` repository variable: the one-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](https://github.com/hivecommons/hive/blob/v5/src/docs/v5-migration-announcement.md) — **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](https://github.com/hivecommons/hive/blob/v5/src/docs/dibs-domain-cutover.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/spoke-wildcard-tls.md) — how to point a cluster's provisioned spokes at the wildcard instead of one certificate per hive, the two cluster prerequisites that must hold first, and which hosts a wildcard cannot cover. -- [Tagged releases](https://github.com/hivecommons/hive/blob/v5/src/docs/releases.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard-standalone-upgrades.md) — 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. -- [The `auto-update` Compose profile](https://github.com/hivecommons/hive/blob/v5/src/docs/auto-update-profile.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/env-vars.md) — centralized list of runtime, deployment, hub, backup, and contributor environment variables. -- [Kubernetes deployment](https://github.com/hivecommons/hive/blob/v5/README.md#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/`](https://github.com/hivecommons/hive/blob/v5/src/deploy/k8s/). See also [dashboard route and health checks](https://github.com/hivecommons/hive/blob/v5/src/docs/health-checks.md) and the Kubernetes CronJob in [backup and restore](/docs/hive/backup-dr). -- [Troubleshooting](/docs/hive/troubleshooting) — container logs, config validation, agent tmux sessions, dashboard auth, GitHub credential checks, and GitHub App workflow-permission push rejections. -- [Cross-cluster migration](https://github.com/hivecommons/hive/blob/v5/src/docs/cross-cluster-migration.md) — the manual procedure for moving a hive between clusters. -- [Self-hosted Kubernetes cluster move](https://github.com/hivecommons/hive/blob/v5/src/docs/move-kubernetes.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/move-hub-registered-cutover.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/move-host.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/move-cross-runtime.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/migration-v2-v4.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/migration-v4-v5.md) — 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](https://github.com/hivecommons/hive/blob/v5/UPGRADE.md) — preparing for v4 → v5 and future major-version boundaries. -- [Dashboard route and health checks](https://github.com/hivecommons/hive/blob/v5/src/docs/health-checks.md) — `dashboard-route-rbac.yaml`, `route_exists`, listener probes, and alert behavior. -- [Fleet health: the verdict and remediation hints](https://github.com/hivecommons/hive/blob/v5/src/docs/fleet-health.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/fleet-drift-signals.md) — 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`)](https://github.com/hivecommons/hive/blob/v5/src/docs/fleet-report.md) — 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 only issues the hive itself opened. -- [Agent self-healing watchdog](https://github.com/hivecommons/hive/blob/v5/src/docs/agent-watchdog.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-log.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/repo-pause.md) — quieting ONE 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](https://github.com/hivecommons/hive/blob/v5/src/docs/token-access-log.md) - 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](https://github.com/hivecommons/hive/blob/v5/src/docs/per-repo-agents.md) — scoping an agent to the repositories it serves with `repos:`, so which agents exist is a per-repo answer instead of a hive-wide one: 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`](https://github.com/hivecommons/hive/blob/v5/src/docs/hive-open-pr.md) — 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`](https://github.com/hivecommons/hive/blob/v5/src/docs/hive-merge.md) — 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`](https://github.com/hivecommons/hive/blob/v5/src/docs/hive-open-issue.md) — 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](https://github.com/hivecommons/hive/issues/6927)), and the exponential-backoff retry contract. -- [Review-bot threads on hive-mediated PRs](https://github.com/hivecommons/hive/blob/v5/src/docs/review-bot-threads.md) — 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](https://github.com/hivecommons/hive/issues/7360)). -- [Network and port requirements](https://github.com/hivecommons/hive/blob/v5/src/docs/network-requirements.md) — inbound ports, proxy paths, egress, and firewall guidance. -- [TLS, HTTPS, and certificates](https://github.com/hivecommons/hive/blob/v5/src/docs/tls-setup.md) — termination patterns and certificate ownership. -- [Security notes](https://github.com/hivecommons/hive/blob/v5/src/docs/security.md) — log scrubbing and secret redaction guarantees/limits. -- [Token collection and usage tracking](https://github.com/hivecommons/hive/blob/v5/src/docs/token-tracking.md) — session JSONL, `/api/cost`, and hub usage rollups. -- [Notifications](https://github.com/hivecommons/hive/blob/v5/src/docs/notifications.md) — ntfy, Slack, and Discord alert channels, plus the two-way [Discord bot](https://github.com/hivecommons/hive/blob/v5/discord/README.md). -- [State-triggered hooks](https://github.com/hivecommons/hive/blob/v5/src/docs/hooks.md) — declarative `transition → action` rules, the transition catalog, the vetted action set, and the security model (RFC #4001). -- [CEL-based agent triggers](https://github.com/hivecommons/hive/blob/v5/src/docs/cel-triggers.md) — 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. -- [Spektacular stage runner](https://github.com/hivecommons/hive/blob/v5/src/docs/spektacular.md) — the Hive side of long-running runs (#8303, umbrella #8290): a run moves through `spec` → `plan` → `implement` stages on one 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`](https://github.com/hivecommons/hive/blob/v5/src/docs/design/run-artifacts.md). -- [Report-only audit campaign pilot](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-campaign.md) — the runs three-gate model proven on a workload that never opens a pull request (#8327): 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 stays off in this slice. -- [Public snapshots](https://github.com/hivecommons/hive/blob/v5/src/docs/snapshots.md) — read-only `/snapshot`, custom CSS, and frame-ancestor sharing. -- [hivectl](/docs/hive/hivectl) — command-line client for the dashboard API, including - [`hivectl tui`](/docs/hive/hivectl#tui--live-terminal-dashboard), the full-screen - terminal dashboard: keybindings, pane cadence, and v1 boundaries. See - [the design record](https://github.com/hivecommons/hive/blob/v5/src/docs/design/tui.md) for the reasoning behind it. -- [`bd` beads CLI](https://github.com/hivecommons/hive/blob/v5/src/docs/beads-cli.md) — work-ledger and knowledge command reference for operators and contributors. -- [Backup and restore](/docs/hive/backup-dr) — `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 one hive's config and GitHub App keys onto another's ([#6529](https://github.com/hivecommons/hive/issues/6529)). -- [Hub disaster recovery](https://github.com/hivecommons/hive/blob/v5/docs/HUB_DISASTER_RECOVERY.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/deployment-scripts.md) — 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](https://github.com/hivecommons/hive/blob/v5/bin/README.md) — map of the deterministic pipeline and operational scripts, grouped by function. -- [Dashboard API reference](https://github.com/hivecommons/hive/blob/v5/src/docs/api-reference.md) — pragmatic route index for dashboard and hub endpoints. -- [Dashboard OpenAPI spec](https://github.com/hivecommons/hive/blob/v5/dashboard/openapi.json) — machine-readable REST API reference for integrations. -- [ioscan status](https://github.com/hivecommons/hive/blob/v5/src/docs/ioscan.md) — the untrusted-input scanner/canary feature (live and default-on in v4). -- [Deployment scripts](https://github.com/hivecommons/hive/blob/v5/src/deploy/README.md) — inventory of deployment helpers, including dashboard TTY panes and `hive-panes`. +- **[Hive and spoke](/docs/hive/architecture#8-hub--spoke):** a spoke is the running hive that serves repositories; a hub can register, provision, and observe multiple spokes. +- **[Agents](/docs/hive/agent-configuration):** configured AI workers with scopes, models, cadences, and permissions for specific lanes of work. +- **[Governor](/docs/hive/architecture#3-the-governor-loop--from-queue-depth-to-a-kick):** the scheduler and policy loop that decides what work is actionable and when agents should be kicked. +- **[ACMM levels](/docs/hive/acmm-policy-matrix):** the autonomy model that maps project maturity to what agents may observe, propose, open, review, or merge. +- **[Hub](https://github.com/hivecommons/hive/blob/v5/src/docs/hosted-hub.md):** the hosted or self-hosted control plane for onboarding hives, heartbeats, fleet views, and hosted-spoke lifecycle. +- **[Contributors and ClankeR relay](/docs/hive/contributor-relay):** a way for trusted contributors to donate compute and run delegated work through hub-mediated roles. -## Contributors and access +## How it works -- [Getting started as a first-time contributor](https://github.com/hivecommons/hive/blob/v5/docs/getting-started-contributing.md) — 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](https://github.com/hivecommons/hive/blob/v5/docs/development.md) — the local workflow for contributing to the Go codebase on `v4`: prerequisites, build, and test loop. -- [ClankeR contributor relay](/docs/hive/contributor-relay) — local contributor setup, multi-hub subscriptions, moving a relay to another machine, and role requests. -- [Backend smoke](https://github.com/hivecommons/hive/blob/v5/src/docs/backend-smoke.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/cli-pins.md) — 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 one labelled PR per CLI. -- [Contributor trust tiers and delegated agent roles](https://github.com/hivecommons/hive/blob/v5/src/docs/contributor-trust-and-roles.md) — newcomer/contributor/trusted/merger/advisor semantics, **Acting as**, grants, and delegatable roles. -- [Credly badges](https://github.com/hivecommons/hive/blob/v5/src/docs/credly-badges.md) — planned integration design; currently a placeholder mapping only. +1. Connect a repository through the Forge App and configure the project, agents, model backends, and desired ACMM level. +2. The Governor enumerates actionable work and applies deterministic filters before any agent sees a task. +3. Agents receive bounded kicks, work in their configured lanes, and use Hive relays for audited writes such as issues, pull requests, reviews, or merges. +4. Dashboards, logs, fleet health, and hub heartbeats show what happened and what still needs human attention. -## Configuration and agents +## Ways to run Hive -- [Agent configuration](/docs/hive/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](https://github.com/hivecommons/hive/blob/v5/src/docs/formal-verification.md) — the optional L5/L6 `quality.formal` capability for agent-authored Spin/Promela models, reporting-only CI, and deduplicated counterexample issues. -- [Advisory digest](https://github.com/hivecommons/hive/blob/v5/src/docs/advisory.md) — what the digest shows (`max_findings`, `show_all`), how stale findings are marked unverified, and which positive signals retire findings. -- [Advisory digest staleness](https://github.com/hivecommons/hive/blob/v5/src/docs/advisory-staleness.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/governor-thresholds.md) — how idle/quiet/busy/surge thresholds scale with repo count, the `threshold_scaling` curves, and when explicit thresholds win. -- [Large-spoke scale envelope](https://github.com/hivecommons/hive/blob/v5/src/docs/scale-envelope.md) — the backlog size one 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](https://github.com/hivecommons/hive/blob/v5/src/docs/supervisor.md) — supervisor policy modes, bead roles, and when to enable the orchestration lane. -- [Telemetry agent](https://github.com/hivecommons/hive/blob/v5/src/docs/telemetry.md) — the L5/L6-only opt-in observability agent, ACMM level gating, and the `project_observability` opt-in flow. -- [Operations agent](https://github.com/hivecommons/hive/blob/v5/src/docs/operations.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/custom-stylesheets.md) — operator-supplied CSS for the dashboard and public snapshot. -- [Branding a hive](https://github.com/hivecommons/hive/blob/v5/src/docs/branding.md) — persistent per-deployment name, mark, and colours via `/branding/branding.json` and `custom.css` (`HIVE_BRANDING_JSON`/`HIVE_BRANDING_CSS`); distinct from the per-request `?style=` stylesheets above. -- [Portable AgentDefinition format](https://github.com/hivecommons/hive/blob/v5/src/AGENT-DEFINITION.md) — standalone YAML schema for importing/exporting agent definitions. -- [Knowledge curator](https://github.com/hivecommons/hive/blob/v5/src/docs/knowledge-curator.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/skills.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/agents-md.md) — 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 one 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)](https://github.com/hivecommons/hive/blob/v5/src/docs/agent-logging.md) — pluk log format, `hive-panes`, availability, and retention. -- [Strategy Lab (Nous)](https://github.com/hivecommons/hive/blob/v5/src/docs/strategy-lab.md) — experiment lifecycle, dashboard/API configuration, fast-fail bounds, and the gate-decision flow. No `nous:` block in `hive.yaml`. -- [GitHub App setup](https://github.com/hivecommons/hive/blob/v5/src/docs/github-app-setup.md) — the Forge App on GitHub and GitHub Enterprise: app creation, permissions, Setup URL, and `/gh-setup`. -- [Forge setup: GitLab, Gitea, and Forgejo](https://github.com/hivecommons/hive/blob/v5/src/docs/forge-app-setup.md) — 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` only 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](/docs/hive/acmm-policy-matrix) — capability levels and policy modes. -- [ACMM level-up advisor](https://github.com/hivecommons/hive/blob/v5/src/docs/acmm-advisor.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/acmm-waivers.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/inception.md) — operator guide to the L1 brainstorm/inception workflow: phases, API, and template variables. -- [Planning intelligence](https://github.com/hivecommons/hive/blob/v5/src/docs/planning-intelligence.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/review-swarm.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/duplicate-sweep.md) — the opt-in (`duplicate_sweep.enabled`) cross-PR pass that clusters open PRs by changed-file set and suggests which one to keep: the two confidence tiers, how a survivor is chosen, why a bot regeneration series gets one 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](https://github.com/hivecommons/hive/blob/v5/src/docs/review-queue-triage.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/retro-lane.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/work-sources.md) — `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](https://github.com/hivecommons/hive/blob/v5/src/docs/linear-agent.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/lite-enrollment.md) — 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](https://github.com/hivecommons/hive/blob/v5/examples/acmm/README.md) — per-level ACMM policy references. -- [Sandbox isolation and agent guardrails](https://github.com/hivecommons/hive/blob/v5/src/docs/sandbox-isolation.md) — isolation layers and operator guardrail notes. -- [Per-agent gh restrictions](https://github.com/hivecommons/hive/blob/v5/config/restrictions/README.md) — file-based wrapper denials in `/etc/hive/restrictions/`. -- [Podman rootless CI](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-rootless-ci.md) — rootless Podman contract for `contribute-hive`. -- [Podman Quadlet `.kube` compatibility spike](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-quadlet-kube-spike.md) — why the standalone Kubernetes overlay is not a safe direct source for Podman units. -- [Podman ownership and cleanup contract](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-ownership-cleanup.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-preflight-host.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-preflight-ids.md) — 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](https://github.com/hivecommons/hive/blob/v5/docs/backend-setup.md) — setup notes for Claude, Copilot, Goose, Bob, Pi, Codex, and Aider. -- [Backend support tiers and acceptance bar](https://github.com/hivecommons/hive/blob/v5/src/docs/backend-support-tiers.md) — 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](https://github.com/hivecommons/hive/blob/v5/docs/inference-backends.md) — vLLM, llm-d, LiteLLM, and Model Gateway troubleshooting. -- [apiproxy](https://github.com/hivecommons/hive/blob/v5/src/docs/apiproxy.md) — Anthropic-compatible proxy logging and deployment notes. -- [Outreach anti-spam ruleset](https://github.com/hivecommons/hive/blob/v5/docs/outreach-antispam.md) — the deduplication and anti-spam rules the outreach agent operates under across awesome lists, project issues, directories, and community threads. -- [v1 to v2 migration](https://github.com/hivecommons/hive/blob/v5/docs/migration-v1-v2.md) — **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](https://github.com/hivecommons/hive/blob/v5/src/docs/migration-v2-v4.md) above. New deployments do not need it. +- **Hosted Hive Hub:** start at [`https://hive.hivecommons.dev`](https://hive.hivecommons.dev) and follow the [hosted onboarding guide](https://github.com/hivecommons/hive/blob/v5/src/docs/hosted-hub.md) for the no-cluster path. +- **Self-hosted:** run your own spoke on [Kubernetes](https://github.com/hivecommons/hive/blob/v5/README.md#kubernetes-deployment) or [Podman](https://github.com/hivecommons/hive/blob/v5/README.md#quick-start-podman), or operate a [self-hosted hub](https://github.com/hivecommons/hive/blob/v5/src/docs/hub-deployment.md) for a fleet. -## Architecture and design +## Get started -- [Architecture](/docs/hive/architecture) — process model, governor loop, guardrails, hub/spoke, and walkthrough. -- [Automatic repo ACMM onboarding reconciler](https://github.com/hivecommons/hive/blob/v5/src/docs/design/repo-acmm-onboarding.md) — proposed design for per-repo ACMM targets, gap-to-work reconciliation, human hand-off, waivers, and anti-gaming controls (RFC #6235). -- [Hive federation design](https://github.com/hivecommons/hive/blob/v5/docs/federation-design.md) — the multi-hive registry: live `/api/hives` endpoints, project onboarding, contributor flow across hubs, and what remains future design work. -- [Public roadmap](/docs/hive/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](/docs/hive/landscape) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/cncf-reference-architecture.md) — CNCF submission/reference template. -- [Podman CI runner map](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-ci-runner-map.md) — measured hosted-runner capabilities and which Podman lane goes where; SELinux is the only lane needing non-hosted infrastructure. -- [CI runner labels](https://github.com/hivecommons/hive/blob/v5/src/docs/ci-runner-labels.md) — how `runs-on:` picks the self-hosted fleet, why a fork must degrade to a GitHub-hosted runner, and the one variable `hivecommons` sets. -- [Gate-integrity invariants for agent lanes](https://github.com/hivecommons/hive/blob/v5/src/docs/design/gate-integrity-invariants.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/design/README.md) — longer-form design records with the full reasoning behind a decision, indexed with a status each (shipped / partly shipped / design only / 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](https://github.com/hivecommons/hive/blob/v5/src/docs/design/discord-issue-promotion.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/design/github-mention-triggers.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-compose-provider-spike.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/design/token-metering-ccusage.md) — proposed design for ccusage-backed token metering with attribution preservation, Bob fallback, and cutover diagnostics (RFC #6234). -- [Trajectory review](https://github.com/hivecommons/hive/blob/v5/src/docs/trajectory-review.md) — trajectory safety lane and review signals. -- [Podman Quadlet `.container`/`.pod` spike](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-quadlet-container-pod-spike.md) — feasibility result for explicit Quadlet units: readiness via `Notify=healthy`, the startup-timeout trap, and what the generator does not validate. +Start with [Zero to Automation: Getting Started with Hive](/docs/hive/getting-started). If you want the hosted path, read [Hosted Hive Hub onboarding](https://github.com/hivecommons/hive/blob/v5/src/docs/hosted-hub.md) next. -## Historical/design notes +## Where to go next -Some documents describe planned or design-only work rather than live features. Those pages are marked at the top, for example [Credly badges](https://github.com/hivecommons/hive/blob/v5/src/docs/credly-badges.md). The longer-form design records under [`design/`](https://github.com/hivecommons/hive/blob/v5/src/docs/design/README.md) 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. +- [Architecture](/docs/hive/architecture) +- [Getting started](/docs/hive/getting-started) +- [Operator reference](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md) +- [Security model](/docs/hive/security-model) +- [Documentation map](/docs/hive/documentation-map) -## Security (v4) - -- [Security model — operator guide](/docs/hive/security-model) — 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](/docs/hive/security-threat-model) — actors, boundaries, layered defenses, known gaps, and reporting. -- [Security response process](https://github.com/hivecommons/hive/blob/v5/src/docs/security-response.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/security-self-assessment.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/ioscan-red-team.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/general-technical-review.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/heartbeat-bearer-cutover.md) — retiring the fleet-wide heartbeat bearer, whose possession proves only "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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-rootless-startup-spike.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-ipv6-egress-bypass.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-rootful-egress-baseline.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-support-matrix.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-selinux-release-qualification.md) — the one 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-volume-persistence.md) — 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 one) 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-selinux-avc-evidence.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-standalone-quadlet.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-quadlet-lifecycle.md) — 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-host-execution-gap.md) — what one 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 one: 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 one path on one host, and says so. -- [Quadlet update and rollback: moving the image, and getting back](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-quadlet-update-rollback.md) — the deliberate manual path from one 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](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-auto-update.md) — 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: one 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 only, 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](/docs/hive/adr/readme) — lightweight ADR process and records 0001-0017. -- [Intent verification](https://github.com/hivecommons/hive/blob/v5/src/docs/intent-verification.md) — tier-based change authorization for merge eligibility. -- [Rootless Podman CI seam](https://github.com/hivecommons/hive/blob/v5/src/docs/podman-rootless-ci.md) — documented test intent and static contract for contributor-container runtime handling. -- [Release-line carry-forward guard](https://github.com/hivecommons/hive/blob/v5/src/docs/release-line-guard.md) — 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. +Current docs target branch `v5`; use the [documentation map](/docs/hive/documentation-map) for v2 → v4 and v4 → v5 migration pointers. diff --git a/docs/content/hive/troubleshooting.md b/docs/content/hive/troubleshooting.md index 32a1e46..313c1bf 100644 --- a/docs/content/hive/troubleshooting.md +++ b/docs/content/hive/troubleshooting.md @@ -206,6 +206,8 @@ If an agent returns to "needs login" immediately after resuming, the credentials On the containerized runtime you normally do **not** need to configure an auto-approve phrase. Claude Code agents launch with `--dangerously-skip-permissions` (`src/pkg/agent/manager.go`), and the manager's `dismissInferencePrompts` routine polls the pane and auto-dismisses the startup consent screens (the "Bypass Permissions mode" dialog, the custom-API-key prompt, and generic "Enter to confirm" menus) dynamically, without a hardcoded phrase list. +Inference backends (`litellm`, `vllm`, `llm-d`) run Claude Code with an isolated per-agent `HOME`. Hive pre-seeds that HOME's `.claude.json` with onboarding complete and workspace trust entries for `/data/agents/` and any repo/worktree directories already present below it, then repairs those entries before each Claude launch. This keeps fresh pods from stopping on Claude Code's "Quick safety check: Is this a project you created or one you trust?" dialog. + If an agent still looks wedged on a prompt, capture the pane (`tmux capture-pane -t hive- -p -S -80`) and check the `hive` logs. A prompt whose selected default is negative (for example "No, exit") is navigated away from before Enter is sent; a genuinely novel prompt that the routine does not recognize is the case to report, along with the captured pane text. ## Notifications (ntfy / Slack / Discord) never arrive diff --git a/scripts/sync-hive-docs.ts b/scripts/sync-hive-docs.ts index a2ac86a..24a1d77 100644 --- a/scripts/sync-hive-docs.ts +++ b/scripts/sync-hive-docs.ts @@ -14,6 +14,7 @@ const canonicalBase = `https://github.com/${owner}/${repo}/blob/${branch}/src/do const files: Array<{ source: string; target?: string }> = [ { source: "README.md", target: "readme.md" }, + { source: "documentation-map.md" }, { source: "architecture.md" }, { source: "security-threat-model.md" }, { source: "roadmap.md" }, diff --git a/src/app/docs/page-map.ts b/src/app/docs/page-map.ts index 9eee91c..78c5e46 100644 --- a/src/app/docs/page-map.ts +++ b/src/app/docs/page-map.ts @@ -95,6 +95,7 @@ const NAV_STRUCTURE_HIVE: Array<{ title: string; items: NavItem[] }> = [ items: [ { 'Introduction': 'readme.md' }, { 'Getting Started': 'getting-started.md' }, + { 'Documentation Map': 'documentation-map.md' }, { 'Architecture': 'architecture.md' }, { 'Roadmap': 'roadmap.md' }, { 'Landscape': 'landscape.md' },