From b05d3aa1fc63893c110c1e3049406a296e398d49 Mon Sep 17 00:00:00 2001 From: Andrew Anderson Date: Wed, 18 Nov 2026 20:46:38 -0500 Subject: [PATCH] =?UTF-8?q?=F0=9F=93=96=20Publish=20the=20Hive=20dashboard?= =?UTF-8?q?,=20settings,=20hub=20and=20telemetry=20pages;=20mark=20design?= =?UTF-8?q?=20records?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Sync dashboard.md, settings.md, hosted-hub.md, hub-deployment.md and telemetry.md from hivecommons/hive and add them to the Hive nav, so the dashboard help links and Ask AI answers have them. Mark Hive design records and ADRs with a hidden data-docs-kind="design-record" element the Kapa source can exclude by selector, and list the unsynced design records as deliberate omissions. Correct the CNCF Sandbox acceptance date to September 2026 per cncf/sandbox#516 and the CNCF project page. Refs hivecommons/hive#19182 Signed-off-by: Andrew Anderson --- ...ashboard-pages-and-design-record-marker.md | 8 + .../content/community/what-is-hive-commons.md | 2 +- docs/content/hive/dashboard-sections.md | 2 +- .../dashboard-sections/workflow-and-agents.md | 2 +- docs/content/hive/dashboard.md | 943 ++++++++++++++++++ docs/content/hive/getting-started.md | 8 +- docs/content/hive/hosted-hub.md | 192 ++++ docs/content/hive/hub-deployment.md | 287 ++++++ docs/content/hive/manual-provisioning.md | 2 +- .../sweeps-and-operations.md | 2 +- docs/content/hive/readme.md | 10 +- .../content/hive/register-self-hosted-hive.md | 2 +- docs/content/hive/roadmap.md | 4 +- docs/content/hive/settings.md | 145 +++ docs/content/hive/telemetry.md | 161 +++ docs/content/hive/webhooks.md | 2 +- scripts/sync-hive-docs.files.json | 18 +- scripts/sync-hive-docs.unsynced-allowlist.txt | 12 +- src/__tests__/designRecord.test.ts | 22 + src/app/docs/[...slug]/page.tsx | 4 + src/app/docs/page-map.ts | 5 + src/lib/designRecord.ts | 19 + 22 files changed, 1828 insertions(+), 24 deletions(-) create mode 100644 changelog.d/added-hive-dashboard-pages-and-design-record-marker.md create mode 100644 docs/content/hive/dashboard.md create mode 100644 docs/content/hive/hosted-hub.md create mode 100644 docs/content/hive/hub-deployment.md create mode 100644 docs/content/hive/settings.md create mode 100644 docs/content/hive/telemetry.md create mode 100644 src/__tests__/designRecord.test.ts create mode 100644 src/lib/designRecord.ts diff --git a/changelog.d/added-hive-dashboard-pages-and-design-record-marker.md b/changelog.d/added-hive-dashboard-pages-and-design-record-marker.md new file mode 100644 index 0000000..88136ec --- /dev/null +++ b/changelog.d/added-hive-dashboard-pages-and-design-record-marker.md @@ -0,0 +1,8 @@ +- Published the Hive dashboard page reference, Dashboard settings explained, + Hosted Hive Hub onboarding, Self-hosted hub deployment and Data collection + and telemetry pages, which the dashboard help links and the Ask AI answers + rely on. Hive design records and ADRs now carry a hidden + `data-docs-kind="design-record"` marker so the Kapa source can exclude them, + and the remaining unsynced design records are listed as deliberate + omissions. Corrected the CNCF Sandbox acceptance date to September 2026 + (hivecommons/hive#19182). diff --git a/docs/content/community/what-is-hive-commons.md b/docs/content/community/what-is-hive-commons.md index 1cb8e8b..c856f32 100644 --- a/docs/content/community/what-is-hive-commons.md +++ b/docs/content/community/what-is-hive-commons.md @@ -2,7 +2,7 @@ **Hive Commons** is a family of open source tools for working with AI coding agents. **Hive** manages project work. **Crux** runs the agents and can be used on its own. -Hive Commons is a [Cloud Native Computing Foundation](https://www.cncf.io/) Sandbox project. The CNCF Technical Oversight Committee voted to accept it in October 2026 ([cncf/sandbox#516](https://github.com/cncf/sandbox/issues/516)), and onboarding is tracked in [cncf/sandbox#545](https://github.com/cncf/sandbox/issues/545). +Hive Commons is a [Cloud Native Computing Foundation](https://www.cncf.io/) Sandbox project. The CNCF Technical Oversight Committee voted to accept it in September 2026: the vote in [cncf/sandbox#516](https://github.com/cncf/sandbox/issues/516) passed on September 28, 2026, and the [CNCF project page](https://www.cncf.io/projects/hive-commons/) lists it as accepted on September 29, 2026. Onboarding is tracked in [cncf/sandbox#545](https://github.com/cncf/sandbox/issues/545). ## Hive or Crux? diff --git a/docs/content/hive/dashboard-sections.md b/docs/content/hive/dashboard-sections.md index 512b8b4..91f137b 100644 --- a/docs/content/hive/dashboard-sections.md +++ b/docs/content/hive/dashboard-sections.md @@ -18,7 +18,7 @@ Each entry answers the same questions in the same order: Hive has two release lines. **v5** is the stable line. **v6** is the newer line. Where something exists on only one line, the entry says so. -For short definitions of the names the dashboard uses, see the [dashboard glossary](/docs/hive/dashboard-glossary). For how the dashboard is built, see the [spoke dashboard guide](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard.md). +For short definitions of the names the dashboard uses, see the [dashboard glossary](/docs/hive/dashboard-glossary). For how the dashboard is built, see the [spoke dashboard guide](/docs/hive/dashboard). ### Live sidebar count feedback diff --git a/docs/content/hive/dashboard-sections/workflow-and-agents.md b/docs/content/hive/dashboard-sections/workflow-and-agents.md index c2f7791..b071634 100644 --- a/docs/content/hive/dashboard-sections/workflow-and-agents.md +++ b/docs/content/hive/dashboard-sections/workflow-and-agents.md @@ -34,7 +34,7 @@ One card per repository Hive looks after, listing its open issues and pull reque - `project.forge` (or a repo's `project.repo_policies[].forge` / `forge_url` override) and the `gitlab:` or `gitea:` instance URL set the host label and links. See [Forges](/docs/hive/integrations/forges). - The `dashboard.issue_bands` settings change the band rules. - **Merge only on current base** ([#15335](https://github.com/hivecommons/hive/issues/15335)). A green `current-base` chip in the card header means the hive only merges a pull request there once its head contains the current base tip; a green head tested on an older base is updated with GitHub update-branch and merges when CI is green on the new head. The hive-wide default is the **Merge only on current base** switch under **Settings → Features → Auto-merge** (`auto_merge.require_current_base_default`, off by default; help text: "OFF by default. Before auto-merging in any lane, require the PR head to contain the current base tip; a green head tested on an older base is updated with GitHub update-branch and merges once CI is green on the new head. Costs one compare call per merge candidate. Per-repo overrides live on the repo card."). Each row under **Settings → Repos** carries the per-repo override — the **Merge only on current base** checkbox with an *inherits* marker, or an **inherit** button when the repo has its own value — written as `auto_merge.require_current_base` (on, also strict: a head the App cannot update is parked) or `auto_merge.skip_current_base` (off). `/api/status` carries the effective value per repository as `requireCurrentBase`. -- See [Repository card legend, issue bands, and PR bands](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard.md#repository-card-legend-issue-bands-and-pr-bands). +- See [Repository card legend, issue bands, and PR bands](/docs/hive/dashboard#repository-card-legend-issue-bands-and-pr-bands). ## ACMM Eval diff --git a/docs/content/hive/dashboard.md b/docs/content/hive/dashboard.md new file mode 100644 index 0000000..ee0637d --- /dev/null +++ b/docs/content/hive/dashboard.md @@ -0,0 +1,943 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard.md) during the docs build. Edit the canonical source in the Hive repository. + +# Spoke dashboard + +## Resuming a paused agent + +On the agent card, hover or focus the information icon beside **paused** to +see the recorded reason, trigger, actor and time. An owner can lift the pause +with **▶ resume**, or **▶ start & resume** if the session is down. If the +agent is disabled, turn it on first; viewers without owner access must ask an +owner to resume it. The pause is separate from the **Enabled** setting and from +per-mode cadences: after resuming, check **Cadences** if the current governor +mode still has no schedule. + +## Base preparation visibility + +The Activity Monitor shows a compact **Preparation train** pill directly above +the actual tracker items and the original train's thin gold side rail through +their rows. Existing train styling and theme tokens supply its spacing, border, +markers and font. A white marker identifies an exact-current preparation owner; +an outlined marker identifies unverified observations. Neither changes CI / +Review chevrons or creates a ready or native queue seat. The pill is drawn only +when two or more tickets are recorded for a base; a lone owner shows its state +in its row comment instead. + +Subdued comments inside the corresponding PR row retain the current pipeline +caption and add base-refresh context, known ticket age, and the hosting issue +when nested. Redundant preparation-owner and waiting-behind badges are suppressed +only where that inline context is actually rendered. Other review, CI, hold and +ready-train signals remain unchanged. The gold ready-queue popover does not +duplicate preparation information; native observations stay separate. + +Preparation FIFO follows first qualifying admission, not PR creation time or +number. Sorts, filters, pagination, collapsed repositories and linked issue trees +are unchanged: a rail ends before unrelated or backwards-ordered items, with a +continuation pill when the group resumes. A dashed rail marks missing FIFO +members or linked-child order that differs from FIFO. Mixed issue trees mark +only the actual preparation children, without moving or copying them. + +Keyboard-focusable and hoverable node/header help provides exact identities, +snapshot time when known, admission versus current heads, unverified positions, +and off-page/filtered members. Unknown predecessors prevent confirmed waiting +ordinals. Unreadable snapshots explicitly say unavailable, not zero work. +Omitted preparation policy adds no train; inactive tickets are excluded. + +These are read-only lifecycle observations, not review approval, green exact-head +CI or guaranteed merge order. Refreshed heads receive no old-head proof. The +existing tracker cache and refresh paths update comments and rail membership; +the view adds no polling, animation, admission, expiration or promotion. + +The spoke dashboard is the operator UI served from +`src/pkg/dashboard/static/index.html`. That file is **generated**: edit the +per-area sources under `src/pkg/dashboard/static-src/` and run `make +dashboard-gen` (see [Dashboard source layout](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard-source-layout.md)). For the behavior behind the labels the repository cards show or mutate, see [Hive Labels and Control Signals](/docs/hive/labels-and-control-signals). Its FAQ panel (`#faq-section` / +`#faq-panel`) is intentionally static HTML: it is not ACMM-gated, does not +fetch data, and is visible to confused L1/L2 users before they understand the +rest of the UI. Its only script is a client-side filter box (`faqFilter`) that +hides non-matching questions. + +The FAQ is a summary surface for the current v5 hive. Each question is a +collapsible `
` with a ``, grouped under +getting started (L1/L2), the L3-L6 trust ladder (including `hold` labels and +shadow mode), evidence/releases/upgrades, runs/inception/Experiment Lab, +contributors/relays/models, issue claims/attribution/audit log, +cost/cadence/pausing, and where to get help. Each answer links back to the +relevant `src/docs/*.md` source of truth rather than becoming a second spec, +and a footer points to Discord, the in-dashboard feedback form and the issue +tracker when an answer is missing. `pkg/dashboard/faq_ui_test.go` guards the +structure: section ids, one `` per question, at least one link per +answer, the filter input, and no inline `style=` inside the panel (styling is +the token-based `.faq-*` class set). + +Contributor cards use a client-side “album cover” tint: the dashboard samples each GitHub avatar in a tiny canvas, ignores low-saturation/near-black/near-white pixels, picks dominant and secondary accent colours, and applies them only as subtle background, border, avatar-ring, and role-pill washes. When avatar sampling fails, a deterministic hue derived from the login keeps the card distinct; results are cached in browser storage for seven days. + +When the FAQ names a dotted config key inside `...`, keep it in +sync with the Go config schema. `pkg/dashboard` has a guard test that extracts +those keys from the FAQ panel and asserts each path exists in `config.Config` +via YAML tags. + +## Section help + +Every dashboard section title has a small **?** mark. Hovering or focusing it shows a one-sentence summary; clicking it (or pressing Enter) opens that section's entry in [Dashboard sections explained](/docs/hive/dashboard-sections), the plain-language help page for operators. The help sentences live in one table in `index.html` (`DASHBOARD_SECTION_HELP`), and `dashboardDocsHref` is the single place that builds every help address: a hive built from the `v6` branch or a `v6.x.y` tag opens the `v6` page, anything else opens `v5`. A guard test fails when a section has no help entry or its sentence drifts from the page. + +Settings fields use the same **?** mark, rendered by `settingHelpMark(page, anchor, label, tip)`: hovering or focusing it shows the setting's tooltip, and clicking it opens the guide that explains the setting, or the tab's entry in [Dashboard settings explained](/docs/hive/settings), through the same `dashboardDocsHref`. Clicking the mark never changes the setting. + +## Design system + +Dashboard UI changes should follow the shared [dashboard design system](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard-design-system.md), [dashboard glossary and sidebar IA](/docs/hive/dashboard-glossary), and [ADR-0018](/docs/hive/adr/0018-dashboard-design-tokens). The token layer is the theme contract for future user theme/background work and the migration path away from static inline styles; `go test ./pkg/dashboard/... -run StyleRatchet -v` ratchets inline styles and raw CSS values so the debt only goes down. + + +## Shared dashboard cards and pinned notices + +Top-level dashboard sections use the shared section-card shell for their header, border, collapse state, badges, and collapsed summaries. Notices that must stay above the reorderable dashboard — release channel/upgrade status, install/configuration warnings, and the planning intro — live in the pinned `#dashboard-notices` anchor before Overview so browser-local section reordering cannot move them down the page. + +On the v5 line the standalone Platform section is not part of the default dashboard layout; on the v6 line Platform is a top-level section. On v5 its forge, mint-token-service, and skills facts now appear in **Diagnostics → Platform**, keeping the information available without consuming a top-level card. Diagnostics also includes **Quality stats**, a data-driven card rendered from the `quality` agent's configured Stats entries rather than a fixed set of deployment-specific workflow checks. The topbar health dropdown is limited to real spoke health checks from `deepHealth`, so repository workflow stats do not appear there. + +## Topbar and sidebar status + +The light dashboard topbar keeps high-signal operational state only: project name, fleet controls, health, auth, and a compact ACMM autonomy chip such as `L5 · Semi-Autonomous`. The chip is display-only and navigates to the ACMM Eval section; changing levels remains in the existing ACMM dialog/sidebar controls. + +Build/version details live in the bottom-left sidebar chip. The collapsed chip shows the short SHA, release channel, and an orange `↑` marker only when an upgrade is available. Open the chip for the full commit link, channel/tracking state, compare/release-notes links, last upgrade status when reported, copy-version, and the manual upgrade action. On small screens the sidebar is reachable through the hamburger drawer, so the version menu remains available without returning the long version strip to the topbar. On the narrowest phones (≤360px wide) the topbar also drops the 🐛 feedback and ⚙ Settings chips so the row never overflows; both stay reachable from the account (avatar) menu, and feedback from the drawer as well. + +## Übersicht widget + +The account/avatar menu's **Export → ⬇ Widget** row downloads `GET /api/widget` +with the same dashboard authentication as the rest of the API. The compact +payload mirrors the headline dashboard readouts: agent names and +running/paused/busy/next-kick state, governor mode, ACMM level, actionable +issue/open PR counts, 7-day PR throughput (opened/merged/closed), spoke version +and upgrade availability, and the fleet breaker state. + +## Reorder sections + +The main dashboard layout is browser-local and display-only. Use the `⠿` grip in each top-level section header to drag a section, or focus the grip and press Space, Up/Down, then Space/Enter to drop; Escape cancels the keyboard move. The working order is auto-saved in `localStorage` as `hive.dashboard.layout`; ACMM-hidden sections keep their slots, feature-disabled sections are excluded, and the sidebar follows the saved order. Section collapse state, hidden sections, and repository card display tweaks are captured with saved layout presets; sidebar jumps temporarily peek collapsed sections open and restore them on the next different jump unless the operator manually keeps the section open. Open the GitHub avatar menu's **Layout** section to save the current working layout as a named preset (default **My layout**), apply/rename/delete up to five saved layouts, export/import a JSON layout, or **Reset layout to default**. Reset asks for confirmation, clears the working layout on this device, and offers a short undo toast. The avatar shows a small dot whenever the working layout differs from the last applied preset or default. + +## Default collapsed cards + +A browser that has never stored any dashboard state (a new hive, or a first visit from a fresh profile) starts with the non-critical cards collapsed so a new operator first sees the cards that say whether the hive is alive and merging: **Overview**, **Governor**, **Projects**, **Review**, **Approvals**, **Agents** and **Agent activity** open expanded; **Throughput**, **Tokens**, **Cost**, **Advisory**, **Knowledge**, **Contributors**, **Inception**, **ACMM Eval**, **Diagnostics**, **Audit Log**, **Agent Logs**, **Experiment Lab** and **FAQ** start collapsed with their one-line summaries visible. The set is the `DASHBOARD_DEFAULT_COLLAPSED_SECTIONS` constant in the dashboard page. A browser that already holds dashboard state when it first loads this version is marked `legacy` in `localStorage` (`hive.dashboard.collapseDefaults`) and keeps the historical all-expanded default, including after **Reset layout to default**. An operator's explicit choice always wins: expanding a default-collapsed card stores `hive-section-collapsed-=0`, collapsing any card stores `1`, and saved presets, JSON export/import and reset round-trip those values. The avatar menu's **Layout** section also offers **Expand all sections** and **Collapse all sections**. + +To hide a dashboard section, hover or focus its left-menu row and press the small eye-off control. The row remains in the sidebar in a muted state, while the matching dashboard card is removed from the main layout. The same control changes to **Unhide
** with an eye icon; choosing it, or clicking the hidden row, restores the card in its saved order and jumps to it. Hidden sections are stored locally as `hive.dashboard.hiddenSections`; Overview cannot be hidden. + +The Experiment Lab (`dashboard.experiment_lab`) is hidden by default while +that surface is being reworked. Set `dashboard.experiment_lab: true` to show +the Experiment Lab dashboard section, its sidebar navigation item, and its +Nous status controls. The pre-rename key `dashboard.strategy_lab` is still +honoured as a deprecated alias for one release: it enables the panel, logs a +one-line deprecation at config load, and is folded into +`dashboard.experiment_lab` so the next config save writes the documented key. + +### Usage gauge + +The owner sees a fuel gauge at the top of the **Overview** card with a row for +each provider whose plan the hive's agents spend: Claude, Copilot, Codex, +Gemini, Kiro or DeepSeek. An agent counts against the provider of its +**backend**, not its model: a Claude model run through the Copilot backend +spends Copilot premium requests, so it is listed under Copilot. Each row names +the agents that use it and shows one dial for each limit the plan reports, +with the percentage left and when it resets: + +- **Claude**: the weekly limit, plus a 5-hour or model-specific weekly limit + when the plan has one. A model-specific limit is named after its model the + way Claude Code's `/usage` names it, for example "Weekly (Fable)". +- **Copilot**: the monthly premium-request quota ("Premium requests"), as + Copilot itself reports it, resetting at the start of each month. + +A dial turns amber at 25% left or less and red at 10% or less, and each row +says how old its reading is and greys out when it is more than 15 minutes old. +When a provider the agents use has no reading, its row says so and why (for +example, the hive is not signed in to Copilot) instead of showing an empty +dial. A hive whose agents all use one provider sees a single block titled +after it, such as "Claude usage left". + +The gauge shows the measurements hive already makes on its regular 5-minute +schedule, through provider rotation or the usage reading that runs by default +without it. It never moves or pauses an agent. Each row reflects the account +the hive itself is signed in with for that provider, and it is that plan's +usage, not the hive's own token budget. + +The Copilot reading signs in only with the Copilot login the agents use +(`COPILOT_GITHUB_TOKEN`, else the dashboard's Copilot login, else the shared +Copilot CLI config), never with another GitHub token on the host. It is for +display only: no relay or quota guard holds work on it. With provider rotation +on, list `github` under `governor.rotation.providers` to measure Copilot. + +Only the owner sees it. To hide it, untick **Show usage gauge** in the +Overview settings (remembered per browser). To also show it as a small chip in +the header on every page, turn on **Also show the usage gauge in the header** +(`dashboard.subscription_gauge_header`) under Settings → Dashboard. The chip's +needle shows the limit closest to empty across every provider, and clicking it +opens the gauge on the Overview. + +## Governor card + +The dashboard **Governor** card summarizes queue depth, operating mode, budget +posture, and cadence controls for the hive. Its collapsible **PRs by model** nested +sub-section reads `GET /api/governor/pr-models` with the selected `7d`, `30d`, +or `all` window. The nested header keeps the window/sort toggles visible and its +collapsed summary shows the current top-ranked model plus model count. Each +model row has a **▸ PRs** button that opens that model's pull requests in the +selected window (outcome, review rounds, fix attempts, first pass, author agent +and backend, each linked to GitHub). The list is fetched on demand with +`GET /api/governor/pr-models?window=…&model=` and cached per window and +model. +Each model row's tooltip also shows **Hive review cost**: what the hive's own +agents (reviewers, adjudicator, fixers) are estimated to have spent on that +model's PRs, joined from the cached launch-cost snapshot (see +[Launch attribution](https://github.com/hivecommons/hive/blob/v5/src/docs/token-tracking.md#launch-attribution)). A note under the +header names the launch-cost window and the spend that could not be tied to any +PR. "—" means no attributed usage, not $0. + +The Governor **actionable issues** and **actionable PRs** tiles use the shared +server-side actionable partition described in [Repository card legend, issue +bands, and PR bands](#repository-card-legend-issue-bands-and-pr-bands). Their +subtitles show the per-kind reconciliation from total open work to the +actionable split, and those two results always add back to the Overview +**Actionable now** total. + +Governor settings **Features → Auto-Merge** includes the owner-only +**Trusted-author auto-merge** block. It edits +`auto_merge.trusted_authors.{enabled,repos,require_role,require_github_permission,exclude_labels}` +through `/api/config/auto-merge`, with a watched-repo multi-select (no +selection means all watched repositories), role selector, GitHub permission +switch, and excluded-label list. + +Governor settings **Features → Review Gate** includes the owner-only +**Only review labelled PRs** toggle with a comma-separated label list. It +edits `review.require_labels` through `/api/config/review`; on, the hive +reviews only PRs carrying one of the labels (enforced in the reviewer kick +list, the review dispatch planner and the hive-review relay — see +[review-swarm.md](https://github.com/hivecommons/hive/blob/v5/src/docs/review-swarm.md#only-review-labelled-prs-reviewrequire_labels)). +Off (the default) sends an empty list and every open PR stays reviewable. + +The cadence table starts each agent row with the same `1`/`0` Agent power +rocker used in the agent settings panel, so owners can enable or disable an +agent from the table; disabled rows are dimmed, and read-only viewers see the +current state without an active control. Per-mode cells are read-only operator +overview cells; continuous modes render as an `∞ continuous` chip, and clicking +a mode cell opens the agent settings dialog to the **Cadences** form where the +operator chooses Off, Interval, or Continuous. +Rows keep the merged/open/closed PR-volume bar, then add compact effectiveness +columns from the same aggregation used by the contributor Operations **Most +effective models** panel: merged PRs, first-pass merge rate, verified-PR run +rate, failure rate, and completed-without-PR ("nothing to ship") rate. Models +that meet `HIVE_CONTRIBUTE_EFFECTIVE_MODELS_MIN_PRS` (default `5`) merged PRs +get rank badges. On `/contribute`, Operations-style column headers in Most +effective models, Rankings, and Fleet controls tier limits are keyboard-clickable +sort controls; the selected column and direction are saved in browser +`localStorage`, and a third click restores each card's default live order. The +default row order is effectiveness rank; operators can toggle back to raw PR +count without changing the selected window. + +## Throughput + +The Throughput panel is a top-level dashboard section with its own sidebar entry, listed under Overview and Governor; its subtitle uses the small muted dashboard subtitle style. For a plain-language summary see [Throughput](/docs/hive/dashboard-sections#throughput). + +The **Throughput** section (`pr-throughput-section`) summarizes +pull/merge requests and issues across tracked forges. It reads +`GET /api/pr-throughput` for selectable windows and repository filters, keeps +the historical `/api/pr-throughput` path and `pr-throughput-*` element IDs for +compatibility, and reports opened, observed merged, and observed +closed-without-merging terminal states. + +Actor attribution splits created, reviewed, and merged/closed activity into +precise buckets: + +- `hive`: changes merged or closed by this hive. This includes audited + sweep/queue/relay/governor paths (`agent_pr_created`, `agent_issue_created`, + `agent_pr_reviewed`, agent issue comments/claims, relay/sweep merges and + issue closes) and forge-observed PR terminal events whose `merged_by` actor + matches this hive's configured identity or GitHub App bot login when no audit + path exists. +- `human`: any non-bot GitHub login, including maintainers who merge through + `gh pr merge --admin --squash` or the GitHub UI. +- `other`: non-hive bot accounts only, such as Dependabot, Renovate, GitHub + Actions, Copilot coding agents, and other `*[bot]` logins. +- `unknown`: terminal observations with no recorded actor/path. Unknown counts + are kept in the actor matrix as unrecorded evidence but are excluded from the + trend share math so missing attribution is never mislabeled as automation. + +Where each row's counts come from: + +- **Created** counts only what the hive opened (`agent_pr_created`, + `agent_issue_created`, `hive_issue_created`), so its human and other columns + stay `0`. PRs and issues people open are not counted. +- **Reviewed** — PRs: the hive's own reviews (`agent_pr_reviewed`) fill the + hive column. The human, other and unknown columns come from + `pr_review_observed`: when the merged-PR settle scan first sees a PR merged + or closed inside its window, it reads that PR's reviews (one extra GitHub + read per newly terminal PR) and records every submitted review the hive did + not write — approved, changes requested, commented or dismissed — at the + review's `submitted_at`, classed like merges (`human`, `other` for `*[bot]` + logins, or `unknown` for a review whose account has since been deleted and + has no login). The list is cached for later scans of the window and read + again only when the PR's `updated_at` has moved since — GitHub bumps it on + review submission, so a review that lands after the first read is picked + up on the next scan and only the not-yet-seen reviews are recorded. The + hive's own reviews are + skipped there so they are never counted twice, pending reviews are ignored, + and each review counts once by its GitHub review ID across rescans and + restarts. Issues: the hive's issue comments and claims. +- **Merged·Closed** counts the hive's audited merge/close paths plus the + settle scan's forge-observed terminal PRs, attributed by `merged_by`. + +A person's review is therefore counted once its PR merges or closes, not when +it is submitted: a review on a PR that is still open appears later, in the +bucket of its own `submitted_at`. The settle scan is used rather than the +`pull_request_review` webhook because deliveries can be missed and have no +per-delivery record to reconcile against. + +The merged-PR and closed-issue totals that feed the Cost section's +cost-per-merged-PR and cost-per-closed-issue figures (`/api/cost` +`merged_prs` / `closed_issues`) are not re-queried from `/search/issues` on +every collection cycle. `pkg/forgestate.Counts` increments them from +`pull_request closed` (merged) and `issues closed` webhook deliveries whose +actor matches the hive's author and reconciles them against GitHub search once +per `forgestate.CountsReconcileInterval` (one hour), overwriting the webhook +tally. A rate-limited or failed reconcile keeps the last good totals and marks +them stale: `/api/cost` reports `count_stale`, `count_stale_since` and +`count_source`, and the Overview tiles read their open issue / PR totals from +the ForgeState cache when it is ready, exposing `staleSince` on +`/api/status` and `countsStale` / `countsStaleSince` per repository so the page +shows "stale since" instead of zeros. + +Issue data comes from the existing issue-request and claim-poller audit stream: +agent-created issues, agent comments/claims as triage/review signals, and +agent issue-close events. Historical human issue creation/review/closure is not +backfilled; the actor matrix and trend chart start accumulating as new audited +or observed events arrive. + +The **Hive vs human** tile and expanded trend use the same selected actor role +as the dropdown. The large percent is hive-attributed events divided by +hive + human + other-automation events in the selected window, excluding +unknown actors. For **Merged**, the share covers PR merges plus issue closes; +for **Closed**, it covers PRs closed without merging plus issue closes. The +previous percent compares against the immediately preceding window of the same +length (for example, previous 24 hours for the 24h window). + +## Settings → Knowledge → Connectors + +The Knowledge card has a **🔌 Integrations** button that opens an in-app modal for Obsidian setup plus every registered `knowledge.connectors` type. The **Knowledge** tab of the governor config dialog also has a **Connectors** section listing every `knowledge.connectors` entry: name, type, layer, a status pill (`ok`, `syncing`, `error`, `disabled`, or `pending` before the first sync), last sync, pages/facts, and the last error (truncated, full text on hover). Owners also get **Sync now**, **Edit**, **Disable/Enable** and **Remove** per row plus **Add connector**; everyone else sees a read-only table. Add/Edit uses the styled hive dialog with type-specific scope fields and a **Validate** button; credentials are referenced by environment variable name or secret file path only. Saves go through the owner-only `PUT /api/config/knowledge/connectors`. See [Knowledge connectors](https://github.com/hivecommons/hive/blob/v5/src/docs/knowledge-connectors.md). + +## Project Inception and Knowledge + +Project Inception is branded as powered by Spektacular with a linked header pill and body note. Knowledge Base collapsed summaries show the total fact count (the same source as the sidebar badge); layer health stays inside the body with a short explanation that layers are knowledge-source scopes for facts. + +## Audit Log + +The Audit Log viewport defaults to a taller resizable panel. Browser-local height changes are persisted in `localStorage` under `hive.audit.panel.height`; the entry cap/search controls remain in the card header area above the scrollable table. The collapsed **sensitive** badge is actionable: it opens the card, applies the visible **Sensitive only** filter for the same 24-hour window as the badge count, and jumps to the first sensitive row. + +## Hive Chat + +The floating **🐝 Hive Chat** panel is a command-first dashboard assistant. Type +`/help` (or `help`) to render the command registry; the same registry drives +one-line help, `/help ` details, examples, and slash-command +autocomplete and argument hints. Current commands are `/help`, `/clear`, +`/search`, `/history`, `/retry`, `/edit`, `/who`, `/agents`, `/beads`, +`/prs`, `/governor`, `/knowledge`, `/jam`, and `/spek`. + +`/prs` answers locally from the status snapshot (the same cached rows +`/api/prs` serves, so it costs no GitHub call): the open pull requests grouped +by repo, one row each — `owner/repo#N — title (@author · stage labels · age · +✅/❌/⏳ CI · approved / changes requested · needs decision · hold · mergeable)` +— under the aggregate count, capped at 25 rows with an "… and N more" footer. +The remainder of the command narrows the list and every filter is a +conjunct: `waiting on review` / `needs review` (not a draft, no approving +review, no outstanding change request), `needs decision` (`stage/085-needs-decision` or +`stage/045-needs-decision`), `hold` (held set or a hold label), `failing ci`, +`mine` (the signed-in viewer) / `by ` / `@login`, `repo ` or +a bare `owner/repo` token (the short repo name also works), and `stale` +(untouched for 7 days) / `older than 3d` (`h`, `d`, `w`). Words the parser does +not recognise are reported and ignored, and the list is still printed. + +The prompt behaves like a small terminal: `Enter` sends, `Shift+Enter` inserts a +newline, `Tab` completes slash commands, Up/Down cycle prior commands while +preserving the draft, `?` opens the shortcut overlay, `Esc` closes the overlay +or panel, and Cmd/Ctrl+K opens and focuses it. A collapsible left cheat sheet +groups clickable examples for agents, beads/issues/PRs, governor, knowledge, +jam, and Spektacular. Spek/Spektacular examples are enabled when `/api/version` +reports v6/edge; otherwise they are marked `v6/edge`. + +Chat UI state is browser-local: transcript, command history, panel size, +maximized/docked mode, cheat-sheet collapsed state, command draft, preferences, +and shortcuts live in localStorage with bounded history sizes. `/clear` clears +the transcript; `/history clear` or the cheat-sheet control clears command +history. `/history ` searches command history and `/search ` +searches the transcript. `/retry` resends the last prompt, `/edit` restores it +to the draft, suggestion chips seed common prompts, and long/code-heavy output +is collapsible with copy buttons on fenced code blocks. There is no server-side +per-user chat persistence yet because dashboard user settings are not a +general-purpose cross-browser preferences API. + +Agent questions are answered from the hive's own agent state (`/api/status` +→ `agents[]`), not by dumping the roster (#14409). Bare `/agents` (or "list +agents") prints the roster, with the block reason inline for every `BLOCKED` +agent. `/agents stuck|blocked|paused|running|idle|failed` filters it: blocked +agents show WHY (`blockedReason`: rate-limit cap, inference auth, policy +stand-down, crash loop, failed starts…) and since when (`blockedSince`); +paused agents show who paused them and why. `/agents [status|why|last| +history]`, `/agents status `, or plain "scanner status" / "status of +scanner" return only that agent's card — state, block reason + since, current +task, last completed turn and its outcome, last kick, last PR/issue acted on, +restart count; an unknown name answers `No agent named X; agents: …`. Natural +language such as "which agent completed last?", "what is scanner doing?", +"why is reviewer-2 blocked?", "when did scanner last run?" and "which agents +are idle?" goes through the same table-driven matcher. An agent question the +matcher does not recognise is handed to the configured chat responder with +the agent state attached as context; without a responder the chat says what +it does understand instead of printing the roster. + +### How a message is answered + +The server routes every message (`pkg/dashboard/api_chat_router.go`) into +one of three paths, and never discards a message's arguments: + +- **Bare command** — `/agents`, `/prs`, `/beads`, `/status` with no + arguments (or a one-word keyword such as `agents` or `prs?`) prints the + deterministic summary: the agent roster, per-repo open PR counts, bead + counts per store, the hive health line. +- **Deterministic argument handlers** — the `/agents` matcher above (and + the `/prs` filters, #14408) answer the argument vocabularies they + recognise without a model turn. +- **Grounded answer** — any other command with arguments or plain-words + question (`/agents what should the hive do next`, `what's waiting on my + decision`, `which PRs have failing CI`, `what version are we on`) is answered + by one read-only model turn over a compact snapshot of the hive state the + dashboard already holds in memory: agents (state, paused/blocked reason, + awaiting-CI, last kick and outcome, last completed action, last error), + open PRs (stage labels, review state, requested reviewers, CI and failing + checks, mergeability, merge verdict, age), actionable issues (stage, + priority, assignees, age), items parked for a decision, governor mode and + next kick, system alerts, release/commit and the last landed upgrade. The + snapshot is scoped to the command's dataset (`/prs …` carries no agents), + capped at 40 items per list and 24 KiB overall. The model is instructed to + answer from the snapshot only, to say *"I don't have that data"* rather + than guess, to cite the agents and `owner/repo#N` items it used, and that + chat cannot take actions. The turn runs on the governor reviewer endpoint + (`governor.trajectory`, falling back to `governor.litellm`) with a 25 s + timeout and at most two turns in flight per dashboard; each attempt writes + one `chat_grounded_answer` audit line (scope, question, snapshot size, + outcome). Nothing on this path can mutate hive state. +- **Fallback** — when grounding cannot run (setting off, no reviewer + endpoint, timeout, backend error, too many in flight) a scoped question + gets the command's usage naming the reason; it is never answered with the + bare dump. Unscoped free text falls through to the configured + `ChatResponder` when one exists, else the "guide agent unavailable" + message. + +**Setting.** `chat.grounded_answers.enabled` (default **true**) gates the +grounded path hive-wide; `chat.grounded_answers.model` overrides the reviewer +model for the grounding turn. See [operator-reference.md](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md). + +Markdown is rendered from escaped input only: bold, inline code, code fences, +links, GitHub-style `@mentions`, and `#issue` / `owner/repo#N` references are +decorated after escaping. Repeated or long `Status heartbeat` output is folded +to avoid burying the conversation. + +`/who` reads `GET /api/presence`. Authenticated users see display-safe +usernames/display names, GitHub avatars for plain GitHub handles, and active vs. +idle state derived from the existing focus-aware presence heartbeat. A local +dashboard with no authenticated identity does not reveal other sessions and +shows only `local`. + +## Repository card holds + +Repository cards show held issues and PRs beside the actionable pills. A user +who owns the hive, owns the repository, or has GitHub `write`, `maintain`, or +`admin` permission on that repository can click the `⏸ Hold` chip to add a hold +or the `▶ Release` chip to remove one. The server always re-checks that +permission before mutating labels. Adding +a hold applies the hive's canonical `hive-pause/` label. The name +deliberately avoids the substring `hold` so it is matched exactly. Removing a +hold only removes the label(s) that are actually causing the hold +(`hive-pause/` and/or the generic hold labels such as `hold`, +`on-hold`, or `hold/review`). The hive-specific canonical hold is +`hive-pause/`; the former `hive/` provenance label is retired +(#12539) and the boot sweep removes it from open items. On upgrade, Hive writes +`/data/hive-hold-migration-.json`: audit-backed dashboard holds are +copied to the new label, agent-provenance-only items become actionable, and +ambiguous legacy labels stay held under `hive-pause/` for operator +review. The card-level `⏸ pause` / `▶ resume` control uses the same permission +rule. + +## Repository card legend, issue bands, and PR bands + +The collapsible **Overview** section above Projects summarizes the same +client-side issue and PR bands across the selected repository view. Its SVG +charts reuse the repository-card classifiers for actionable plus held +issues/PRs, so their totals match the visible band counters and respect the +Overview settings repo filter without a separate API call. A compact KPI strip +renders the partition as an equation: **Total open issues + Total open PRs = +Actionable now + Held + Blocked/needs-human + Outside**. This is the same +partition used by the Governor actionable issue/PR subtitles. **Total open +issues** and **Total open PRs** are forge totals for the selected configured +repositories from the existing scanner tick: open GitHub issues exclude pull +requests, while open GitHub pull requests include drafts. Their subtitles show +the per-kind terms without repeating the headline total. Both totals are the +size of one canonical per-refresh open-items set, `/api/status.openItems` +(server-side: every listed open issue and PR per repository with its bucket, +built from the enumeration snapshot, the ForgeState cache items and the +last-good copy — counted items, never a separately fetched total; a repo that +reports more than it lists surfaces the remainder as `unlistedIssues` / +`unlistedPrs` and a **+N not yet listed** badge instead of inflating the +total). The left-nav **Overview** pill reads `BP = issues/PRs` — *board pressure*, +the open issues and PRs the configured repos put on this hive's board — and is +those same two tile values, written by the same KPI render from the same +`/api/status` snapshot, +and the Hive activity monitor lists exactly that set, so its header "N items +(I issues / P PRs)" equals the tile; its tooltip carries the full equation +and, after a refused GitHub enumeration or on a boot-restored snapshot, the +same last-good "stale · as of" note the KPI strip shows. It stays hidden until the status feed has answered and keeps updating +when the KPI strip is switched off. **Actionable now** is +the shared server-side count used by the Overview KPI and the Governor collapsed +split: open enumerated issues plus open enumerated PRs after hold/exempt +filters, excluding items in the waiting, done, draft, or blocked Overview +bands. The following tiles expose issue/PR splits such as `13 = 5 issues + 8 +PRs`, and the operator glyphs between cards make the full strip read like +`41 TOTAL OPEN ISSUES + 17 TOTAL OPEN PRS = 13 ACTIONABLE NOW + 13 HELD + 10 +BLOCKED / NEEDS-HUMAN + 22 OUTSIDE`. The `outside` tile is server-side and is +broken down in `/api/status` as `actionableNow.outside.breakdown[]`, with each +row naming the count, rule, current setting, and how to change it for this +hive. The rows cover hard-suppress labels (`stage/045-needs-decision`, +`needs-spec`; `needs-human` is counted under +blocked/needs-human), exempt labels from `governor.labels.exempt` plus permanent +exempt labels, reporter-trust triage from +`project.issue_filter.reporter_trust`, agent proposal filtering from +`project.issue_filter.agent_proposal`, require-label filtering from +`project.issue_filter.require_labels`, standing hive advisory/meta issues, +bot Dependency Dashboard issues, draft PRs, exempt PR labels, and +hold-adjacent/other remainder rows. See [Outside buckets](#outside-buckets) +for the bucket-by-bucket rules and [labels-and-control-signals.md](/docs/hive/labels-and-control-signals) +for the label semantics behind hold, exempt, and hard-suppress signals. Its +`actionableNow.issues` and `actionableNow.prs` splits always sum to +`actionableNow.total`. Operators can +view each Issues or PRs panel as a donut, +pie, horizontal bar, single 100% stacked bar, line/spark trend, or age +histogram. Every shape is still driven by the same band slices and +server-provided classifications. Hovering a chart element, an Overview legend +row, or a repository-card band header shows its rule from the Go band specs +carried in `/api/status` as `overview_bands`. Each actionable/held issue and PR +carries `band`, `signals`, `stale`, and `held`; the browser does not classify +labels or timestamps again. Full SSE updates carry the same fields. + + +### Outside buckets + +The Overview and Governor `outside` ⓘ tooltip uses this server-side table. The +Settings → Labels panel repeats it as **Triage buckets: what counts as outside** +and exposes the editable rows. + +| Bucket | Definition | Rule/config source | How to change | +| --- | --- | --- | --- | +| `needs-decision` (shown as "needs human decision") | Issue is parked for a maintainer ruling. | `stage/045-needs-decision` always (and the PR-only `stage/085-needs-decision`, which a pre-045 issue may still carry), plus labels in `project.issue_filter.hard_suppress_labels.needs_decision` / `.needs_direction` and the retired `needs-decision` / `needs-direction` spellings until the reconciler migrates them ([#12683](https://github.com/hivecommons/hive/issues/12683)). | Settings → Labels → Triage buckets, or edit `hive.yaml`. | +| `needs-spec` | Issue needs specification or acceptance criteria. | Labels in `project.issue_filter.hard_suppress_labels.needs_spec`; default `needs-spec`. | Settings → Labels → Triage buckets, or edit `hive.yaml`. | +| Exempt labels | Issue or PR carries a deny-list label and is never agent work. | `governor.labels.exempt` plus permanent labels such as `do-not-merge`. | Settings → Labels → Exempt labels, or edit `hive.yaml`. | +| Reporter triage | Reporter trust is enabled and the issue author is not trusted yet. | `project.issue_filter.reporter_trust` trusted associations/logins and untrusted required labels. | Settings → Labels → Reporter trust. | +| Project issue filter | Issue lacks every required allow-list label. | `project.issue_filter.require_labels`. | Settings → Labels → Required labels. | +| Agent proposal | A non-human strategist or outreach proposal lacks an approved-direction label, human assignee, or acknowledged split parent. The Activity Monitor reason is `Agent proposal awaiting approved-direction`. | `project.issue_filter.agent_proposal` (omitted for defaults; `agent_proposal: {}` disables the gate). | Edit `hive.yaml`; see [Agent-filed direction proposals](/docs/hive/agent-configuration#agent-filed-direction-proposals). | +| Standing meta/advisory | Hive's own advisory report or issue labelled `hive/advisory`; it is coordination state, not work. | Fixed scanner rule: advisory title/label. | Rename/close the advisory, or remove the advisory label if it should become work. | +| Dependency dashboard | Bot dependency dashboard control panel, not a concrete task. | Fixed scanner rule: Renovate/Dependabot-style bot author plus Dependency/Renovate Dashboard title. | File concrete child issues or close/rename the dashboard issue. | +| Draft PRs | Pull request is open but marked draft. | GitHub draft state. | Use GitHub's **Ready for review** action. | +| Hold-adjacent/other | Safety remainder for open items that did not match a named actionable, held, blocked, or outside classifier. | Fixed scanner fallback. | Check labels and scanner rules; add a dedicated classifier if the remainder is meaningful. | + +The Issues and PRs panels link directly to `/api/overview/issues.csv` and +`/api/overview/prs.csv` by default, or to the matching `.json` endpoints when +JSON export is selected; non-empty legend rows add a `band` query filter and +repo-filtered views add one or more `repo` query filters. +Exports use the current cached snapshot and the same Go classifier as the +page, so a download reflects the latest server state even between page updates. +Automation can use the corresponding `.json` endpoints and optional `band`, +`repo`, `stale`, and `held` filters. Cookie sessions work directly; token-authenticated +pages include their API token in the download link's query string. + +The Overview header's ⚙️ popover stores browser-local chart preferences under +`hive-overview-charts`: which chart types are in rotation, whether the carousel +is enabled, the 5-second to 5-minute interval, transition style, duration, donut +label mode, KPI visibility, export format, and the bounded +client-side line/spark history. The repo multi-select is stored separately under +`hive.overview.repos`, with All/None shortcuts and an Org shortcut when the +hive spans multiple GitHub organizations. The default remains donut-only with +the carousel off, a 30-second interval, fade transition, normal duration, KPI +strip on, CSV exports, and all repos selected. +Manual arrows and dot indicators are available even when timed rotation is off; +timed rotation pauses while the panel is hovered or the tab is hidden, and +reduced-motion users get instant swaps. + +The **Projects** section uses a consistent card header grid: reorder grip, truncated repository name, status badges, labelled auto-merge switch, spacer, and actions. It also includes a compact, collapsible pill legend. It is +stored per browser in `localStorage` and uses the same pill classes as the cards, +so theme changes update the legend automatically. The legend lists the issue +and PR bands (rendered from the shared band table, each with its rule as a +tooltip), issue held pills, plan chips, hold/release controls, issue state +glyphs (`⛔`, `❓`, `👤`, `✓`, role badges, stale `🕒`) and PR states (`✓`, +`◐`, `⚠`, held `⏸`, failing CI `✗ CI`, conflicts `⑂`, stale `🕒`, +reviewed `💬`, auto-merge `🔀`, agent role badges, review-class badges +such as `FIX`, and the red `sentinel` pill). A PR that carries the configured +sentinel alert label (`sentinel.label`, default `sentinel-alert`, matched +case-insensitively) is drawn red on its card, status chip and main pill, whether +it is listed as held or open; red wins over the held, needs-human and merge +colours, and the row keeps its other chips. The sentinel flagged it for a +possible security override, privilege escalation or codebase damage, and Hive +will not merge it until a maintainer reviews it and removes the label. Trusted +authors normally get a sentinel comment rather than the label, so their PRs are +usually not red. The label name reaches the page through `/api/role` +(`sentinel_label`, every role); until it is known no row is drawn red. Repository cards also show a labelled auto-merge switch: it is effectively off below L6, switching the hive to L6 turns it on for every active repo, and owners may toggle individual repos afterward. + +Actionable issue pills are grouped client-side for display only; enumeration, +holds, filters, ranking, and agent kick behaviour are unchanged. Bands are +named after the action the operator should take (or an explicit "nothing +needed"), not after how the dashboard classified the issue. Each issue appears +in exactly one band, while non-winning states remain as badges on the pill: + +1. **Unclaimed** (`unclaimed`) — no other band matched: nobody is assigned, + nothing claimed it, and no human gate applies. This does not by itself mean + agents will pick it up. +2. **Claimed** (`claimed`) — a claim is a comment; the `stage/020-claimed` / + `stage/030-pr-in-progress` label is a mirror Hive keeps in sync (the retired + `claimed` and `hive/in-progress` spellings are still recognised for the + migration cycle). The display band also recognises assignees and any + `hive/claimed-by-*` label — the generic `hive/claimed-by-human`, an + agent's `hive/claimed-by-` and the retired per-login spelling + alike; the claimant's login is shown from the claim record, not the label. +3. **Needs triage** (`triage`) — an `agent/` label and no human has + acknowledged the proposal under #5117: no `approved-direction` label and no + human assignee (the snapshot's `human_acknowledged`; a human *comment* only + satisfies the PR-time gate and is not in the payload). Acknowledge it, or + close it. Once acknowledged the issue falls through to Unclaimed/Claimed + with the role badge still on the pill. +4. **Needs human** (`needs human`) — labels such as `blocked`, `stage/045-needs-decision`, + `stage/085-needs-decision`, `2-discussing`, `Epic`, `needs-human`, or `needs-triage`. Note that the + `needs-triage` *label* lands here, not in the Needs triage band. +5. **Confirm & close** (`close?`) — labels such as `hive/already-done`, + `stage/040-covered-by-pr` (and any later mirrored PR stage; formerly + `🐝 covered by PR` / `hive/covered-by-pr`), and `hive/likely-done`: an agent + believes the work landed; verify and close. + +Precedence is confirm & close → needs human → claimed → needs triage → unclaimed, +so a human gate beats an assignment and done beats all other display states. +Within each band, issues sort by `updated_at` oldest first. The issue breakdown +also shows `N no activity > 14d` for actionable issues older than the stale +threshold. + +Operators can tune only the display taxonomy under `dashboard.issue_bands`: + +```yaml +dashboard: + issue_bands: + waiting_labels: [blocked, stage/045-needs-decision, stage/085-needs-decision, needs-decision, 2-discussing, Epic, needs-human, needs-triage] + done_labels: [hive/already-done, stage/040-covered-by-pr, "🐝 covered by PR", hive/covered-by-pr, hive/likely-done] + stale_days: 14 +``` + +These settings deliberately do not reuse `governor.labels.exempt`, +`contribute_skip_labels`, or `project.issue_filter`; those decide work +eligibility, while issue bands decide how the dashboard describes already +enumerated work. Linked-PR badges render from the `linked_prs` payload and are not inferred by the card. + +PR pills are also grouped client-side for display only. Open and held PRs appear +in exactly one band; held PRs are no longer appended after the actionable list. +First match wins for classification: + +1. **Needs human** — `needs-human`, held, `stage/085-needs-decision`, + `2-discussing`, or configured `dashboard.issue_bands.waiting_labels`. +2. **Merge-eligible** — merge verdict `eligible`, or queued for Hive + auto-merge. +3. **Blocked** — merge verdict `blocked`, conflicts (`mergeable: no`), or + failing CI with failing check names. +4. **In review** — merge verdict `outstanding`, a recorded Hive review link, + or a GitHub review decision (see below). +5. **Draft** — draft PRs. +6. **Open** — everything else. + +The display order is needs human → merge-eligible → blocked → in review → +open → draft. Within a band, PRs sort by oldest `updated_at`, then review class +(`fix`, refactor/docs or unknown, `tests`), oldest `created_at`, and PR number. +The PR snapshot includes `updated_at` specifically so this order can match issue +band aging without extra GitHub API calls. The existing +`dashboard.issue_bands.waiting_labels` and `stale_days` settings are reused for +PR display; changing them does not alter enumeration, holds, review, or merge +queueing. + +## Linked PR issue signals + +Repository issue pills show a `🔗` badge when Hive has verified a pull request related to that issue. Open PRs apply `stage/040-covered-by-pr` (the retired `🐝 covered by PR`); merged PRs on still-open issues apply `hive/likely-done`. The badge's tooltip grades the claim: "closes via PR #N" (the PR carries a closing keyword, or Hive linked it from the branch name), "covered by PR #N (partial)" (the PR says `Refs #N` / `Part of #N` and merging it will not close the issue), or "merged via PR #N". These are pending signals, not resolution: the issue remains in the actionable list until GitHub closes it, GitHub reports the PR in `closingIssuesReferences`, or an operator confirms coverage. + +The badge is derived from Hive's own PR-claim evidence — the same source that applies the label — not from GitHub's closing-link data, so it is present for every covered issue whether the claim is closing or partial, and whether the issue is actionable or suppressed into the card's "covered by PR" group ([#12144](https://github.com/hivecommons/hive/issues/12144)). One badge renders per issue; when several PRs cover it the closing PR is primary, the count is appended (`🔗×2`), and the tooltip lists the rest. The status payload exposes the evidence as `linked_prs: [{number, state, merged, url, closing, reference}]` plus `claim_context` on each actionable `github.Issue` and on each `claimed_by_pr` entry in `nonActionableIssues`. + +## Review pipeline board + +The **Review** section opens with a separately collapsible **Pipeline** tile that shows every open PR as a card in the column for its review stage, from `GET /api/review/pipeline`: unreviewed, reviewing, changes requested, fixing, human hold, approved (merged and abandoned columns stay empty until the API returns those PRs). Each card shows the PR link, an agent or contributor marker, time in stage, reviewer chips, P0–P3 finding counts, the fix-loop counter (red once it is within one of the cap) and the next-action link. Filter by repo, author kind or stage; column headers carry counts. A ⚡ marker on the card means a webhook push or review request triggered the review of the current head (`trigger: event`), ⏳ that one is queued; see [Event-driven dispatch](https://github.com/hivecommons/hive/blob/v5/src/docs/review-swarm.md#event-driven-dispatch). The board refreshes every 30 seconds and keeps its scroll position. The sibling **Queue** tile is separately collapsible too, ranking the same open PRs in Hive’s suggested review order from `GET /api/review/queue` without hiding the Pipeline tile. A contributor PR the supersession sweep detected as superseded by a merged PR is tagged **superseded** there, with a link to the merged PR, whether or not `supersession_sweep.close_contributor_prs` is on; only when auto-close is on does the tag also show when the grace window ends and the sweep will close it, otherwise it reads "close as superseded or keep open" with no countdown. Owners get **Close now** and **Keep open** (adds `hive/keep-open`, which the sweep never auto-closes). Each queue row reflects the PR's `stage` from the stage-label store ([labels-and-control-signals.md](/docs/hive/labels-and-control-signals/stage-labels#stagestalled--nobody-is-working-this)): the `stage/stalled` label's tooltip reads "no activity for Xh — nobody is working this PR", a red **waiting on hive Xh** pill marks a PR past its stage dwell while the hive itself holds it (checks running or reviewer verdict pending — the reviewer lane, not the author, needs attention), and an **N hops, M back** pill carries the stage transition history (`stage.history[]`) in its tooltip, replacing the retired `stage/regressed` label. + +## Hive activity monitor + +The **Hive activity monitor** section (sidebar, Dashboard group; expanded by default) is the "where is my pizza" view of the hive: one entry per open issue and PR from `GET /api/stage-tracker`, each a title line over a thin tracker strip. Issues and PRs share one set of columns — `Open → Actionable → Claimed → PR in progress → CI / Review → Merge gate → ✓` — with the step names printed once in a column header. Covering PRs nest under their issue: an issue with no PR yet draws the whole strip like any other row (its lit step is Open/Actionable/Claimed with the steps ahead faint); once exactly one PR covers it the issue and PR collapse into a single entry: the issue's `#N title` on the left, `[author icon] #PR title` in the *PR in progress* column of the same title line, and one continuous strip beneath — Open/Actionable/Claimed passed, then the PR's stage drives the lit chevron through `CI / Review → Merge gate → ✓` (chips, tooltip and `since` come from the PR). With two or more covering PRs the issue's own strip stops at Claimed — all passed, nothing lit — and directly beneath, one indented sub-row per open covering PR (furthest along first) carries `[author icon] #N title` at the *PR in progress* column and that PR's own strip from there on with its own lit chevron, modifier chip, tooltip and `since`. A PR linked to an open issue in the list has no top-level row of its own (`nested_under`); PRs with no linked issue keep a full-width row. The *Pull requests* filter flattens the list (every PR a top-level row); *Issues* and *All* show the nested view. Only the current step is coloured (amber, named in words; the ✓ chevron turns green once merged). Whether it moves depends on its *motion bucket* (`stageTrackerMotion()` in `index.html`): **static** — a steady fill — for Open, Open · on hold (any hold label, whatever else is on the item), Actionable (010), Claimed (020), a PR in progress / Covered by PR (030/040) by a human author, Merged, and any stage the dashboard does not recognise; **active** — a gentle pulse — when the hive is acting (030/040 with a hive or clanker author, 050 review pending, 060 reviewed, 070 fixing, 074 adopted by hive, 080 merge gate, 095 pre-merge soak, 100 merge queue); **needs-human** — a slower amber→red breathe — when a person must move (015 triage needed, 045/085 needs decision, 071 needs author, 072 returned to contributor, 090 ready for a human merge, or any `stalled` / `blocked` / `needs-human` / `needs-decision` / `needs-triage` modifier). Under `prefers-reduced-motion` nothing animates and a needs-human step keeps a steady red tint instead; passed and upcoming steps are low-contrast shapes with a small grey glyph each. Side stages ride the step they branch from — 070/071/072/074 light *CI / Review* as "Fixing" / "Needs author" / "Returned to contributor" / "Adopted by hive", 085/090 light *Merge gate* as "Needs human decision" / "Ready for human merge". The lit chevron ends with a small icon of whose move it is, in the chevron's ink (person = human, robot = clanker, hexagon = hive): the claimant on *Claimed*, the PR author on *PR in progress* and *Returned to contributor*, hive on *CI / Review* / *Adopted by hive* / *Queued for merge*, a human on *Triage needed* / *Needs human decision* / *Ready for human merge*; *Open* and *Actionable* carry none; 015 (an actionable issue no maintainer has triaged yet) and 045 light *Actionable* as "Triage needed" / "Needs human decision"; 040 shares *PR in progress* with 030, 060/080/100 light *Merge gate* as "Queued for merge" (the chevron tooltip distinguishes "not yet admitted — reason" from "admitted, merging") (the chevron tooltip names the exact stage). Every PR stage has a word: 050/060 "CI / Review", 070 "Fixing" (the author's move — a `needs-rebase` chip beside it says *what* is being fixed; the stage labeller always puts a needs-rebase PR at 070/071/072, never 050/060), 071 "Needs author" (a human-authored PR the author must act on), 072 "Returned to contributor" (a clanker PR handed back to its hive), 074 "Adopted by hive", 080/100 "Queued for merge", 085 "Needs human decision", 090 "Ready for human merge". A PR with no linked issue is named exactly once: its title line reads `[kind icon] [author icon] #N title` on the left (no entry in the *PR in progress* column) over one continuous strip with Open/Actionable/Claimed passed and its own stage lit; the `[author icon] #N title` entry under the *PR in progress* header appears only for covering PRs (single-PR entries and nested sub-rows). The author icon is coloured by `author/*` kind (hive blue, clanker purple, human teal). A PR is never an issue in this list: when the same number arrives through both the issues feed and the pulls feed, the PR record wins and the issue-feed copy is dropped server-side (pairing is keyed by repo, kind and number, so a PR can never be its own parent), and the *Issues* filter never shows one. A `since` column on the title line gives time on the current step (red when stalled), with at most one muted health-modifier chip to its left; the reason sentence, actor, nudges, flags and the last stage hops live in the hover tooltip. Titles never wrap: an issue title is cut with an ellipsis before it would reach the *PR in progress* column (leaving a clear gap, so the PR entry always starts at the column's left edge) and a PR title before the chips and `since`; the full title is on the title element's own hover tooltip, separate from the strip's reason tooltip. Rows are sorted furthest-along first by default (a covered issue ranks by its furthest-along PR, not its own 040), then longest-waiting first; the *Sort* select also offers longest waiting, newest and number, with an arrow button that reverses the direction. The list is complete: every open issue and PR of the watched repos is an entry — including claimed, in-progress, needs-human / needs-decision / needs-triage-filtered and reporter-held issues, draft PRs and PRs carrying an exempt label — and an item with no stage yet sits at *Open*. The toolbar filters the cached payload in the browser: *All / Pull requests / Issues*, *Repo*, a search box (`#number`, number or title substring, also matching a covering PR), *Since* (any / over 1 hour / over 1 day / over 1 week on the current step, or *past the stage dwell* = stalled or longer than the step's configured dwell), *Author* (human / clanker / hive) and a *Needs attention* toggle; a row of label chips built from the labels present (`stage/*`, `needs-*`, `author/*`, `role/*`, then any other label shared by two or more items) narrows further — chips of one family OR together, families AND together. *Clear filters* appears whenever something is narrowed. Filter, sort and page size persist in the browser (`localStorage`); the page does not. Pages hold 25 / 50 / 100 rows (default 50) with Prev / Next above and below the list and a "showing X–Y of N (M filtered out)" line; the section header reads "N items (I issues / P PRs) · M need attention" for the whole list (N, I, P come from `open_issues` / `open_prs` in the payload — the same `openItems` set behind the Overview tile, so N equals the tile's total open issues + PRs — with "· X match filters" appended while a filter is on) while the sidebar badge shows the same N (total open items, same render pass — never a separately computed number) with the needs-attention count (modifiers present, or on 071/072/085/090, counted over every item) in its hover tooltip and as the warn-coloured header suffix. The meta line also says "updated Ns ago · cache|fresh": the payload is built server-side at most once per `dashboard.stage_tracker.cache_ttl_s` (default = `governor.eval_interval_s`) from the spoke's existing GitHub snapshot and served with an `ETag`, so the 30-second poll costs a 304 and never a GitHub call (it turns amber once the payload is older than two TTLs). A GitHub webhook naming a listed PR or issue re-reads just that item (one `GET`, debounced by `dashboard.stage_tracker.webhook_refresh_debounce_ms`, default `2000`; off with `dashboard.stage_tracker.webhook_refresh: false`) and patches its row within seconds, ahead of the next eval cycle; see [Webhook-driven PR cache invalidation](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md#webhook-driven-pr-cache-invalidation) and, for how that patch relates to the cadence tick and the reconcile that overwrites it (and what `/api/status.webhooks.mode` means when it reads `polling`), [webhooks.md](/docs/hive/webhooks). Section details: [dashboard-sections.md](/docs/hive/dashboard-sections#hive-activity-monitor); stage semantics: [labels-and-control-signals.md](/docs/hive/labels-and-control-signals/stage-labels#stage-labels-stagennn--the-pipeline-state-machine). + +**Phones.** At phone widths (`max-width: 640px`, or a coarse pointer up to 820px) the *Furthest along* and *Longest waiting* sorts order rows attention-first: every row that needs a person sits above the rest, ahead of the stage column (held and draft rows keep sinking to the bottom); *Newest* and *Number* are unchanged. A sticky line above the list ("⚠ N waiting on you · M need attention") toggles the Waiting on you filter; it is drawn only while at least one row is waiting on you or needs attention. The `attentionFirst` field is stored with the other tracker filter fields and defaults on; it has no toolbar control yet, so the ordering cannot be switched off from the page. Desktop ordering and the toolbar are unchanged. The gate is `webstatic/testdata/tracker-phone-attention-first.js`, run by `dashboard-mobile-shots.mjs` against the activity-density fixture at 390×844 (attention rows lead, count line inside the viewport at rest). + +**Sounds (opt-in).** The speaker chip at the right end of the toolbar (🔇 off / 🔊 on; default off, remembered per browser under the `localStorage` key `hive.tracker.sound`) enables two short sounds, both synthesised in the browser with the Web Audio API (no audio file, no network request). The **merge zap** — just under half a second of bug-zapper arc: a ~4 ms high-voltage "snap", then a sputtering electric sizzle (bright noise and a 240 Hz square chopped by a 120 Hz mains pulse train, dropping out and re-striking at random) that holds ~80 ms and dies away, high-passed at 700 Hz — plays when a pull request the tab was already showing merges while the page is open. The trigger compares tracker payloads: a PR counts as merged when its stage reaches the ✓ cap or when its key appears in the payload's `recently_merged` list (the hive's `pr_merged` audit entries of the last 30 minutes — sweep, queue, relay and human merges the PR poller observed alike — which is how a PR that simply dropped out of the open list is told apart from one closed unmerged). Entries that name the repo by its configured short name are qualified to the `owner/name` the rows carry, and a PR that drops off the list a poll before its audit entry lands is still remembered as open until `recently_merged` settles it, so the two never have to arrive in the same payload. It never fires on the first load, for rows that were already merged, for issues, or for a PR it has already zapped; several merges in one refresh play at most two zaps. The **new-item buzz** — a quieter 0.18 s sawtooth near 120 Hz with a ~30 Hz tremolo through a lowpass — plays when an issue or pull request appears on the list that the previous payload did not have; it never fires on the first populated payload, buzzes once per item, and plays at most two buzzes per refresh. Nothing plays while the tab is hidden. Turning the chip on plays one zap then one buzz so you can hear both. The audio context is created on a user gesture and resumed if the browser suspended it; if the autoplay policy still holds it suspended when a sound is due, that sound is skipped and the next click or key press re-arms it. Detection runs over the union of every configured repo's rows, keyed `owner/name/kind#number`, so the sounds fire for each repo the hive governs. Either sound can be replaced from the card's ⚙ settings modal with a user-supplied file (WAV or anything `decodeAudioData` accepts, capped at 4 MB) stored in the browser's IndexedDB (`hive-tracker-sounds`); a stored file that fails to decode falls back to the built-in voice. The modal also carries the **Play sounds** master toggle and a 0–100 **Volume** slider (`localStorage` key `hive.tracker.sound.volume`) that scales the master gain of both built-in and uploaded sounds. Closed issues are not an event the tracker payload carries, so nothing plays for them. + +The endpoint returns `stages` (the stage table with `short`, `branch_from`, configured dwell and `falls_to` — the lower same-kind stages a move to which is a regression per the stage engine, so the event line says "fell back to" only for those; 015 → 010 triage accepted, 085 → 080 decision made and 072 → 070 author resuming read "moved to"), `items` (one per open issue/PR represented by the status snapshot, including actionable and held items plus display-only non-actionable issues, drafts, and exempt PRs: `labels`, `created_at`, `updated_at`, `bucket`, `bucket_reason`, stage, `stage_since`, humanised `reason`/`caption`, `actor`, `modifiers`, `author_kind` + `author_kind_source` (`label`, `inferred`, or `registry` — the author has a contributor-hub profile on this hive, so their clanker pushed it; the row icon, tooltip and claimant all read this one value), `lane`, `tier`, `linked_pr`, `linked_prs` (number, title, url, author, author kind, stage, `stage_since`, `caption` and `modifiers` of each open covering PR — enough to draw the nested sub-row without a second lookup), `nested_under` (on a PR: the issue it is listed under), nudge info and the last eight `history` hops from the stage store) and `author_kind_labels`. It answers `{"status":"initializing"}` until the first scan. + +### Maintainer notes + +Each row (and each PR sub-row under an issue) carries a small **🗒** button +beside its decision controls — the item's **maintainer notes**: short notes +one maintainer leaves for the others ("waiting on legal", "don't merge before +the v5 cut", "asked the author about the test on Discord"), the way the +decision badge records what was decided. A count rides on the button once +the item has any (`🗒 2`), the row's hover tooltip repeats it, and clicking +opens an inline expander listing every note (author avatar and login, +relative time, text) over a one-line composer — **Add note**, or +⌘/Ctrl+Enter. The author is always the dashboard session's GitHub login. + +What they are, and are not: + +- **Private to the hive's maintainers.** Notes are stored on the spoke in + the append-only `/data/maintainer-notes.jsonl` next to the decision + ledgers and are **never written to GitHub** — no comment, no label, no + mention. Anyone signed in to the dashboard sees them; adding one takes + write on the repository (the same check as the hold chip and the decision + buttons); a note is deleted by its author or an owner, and a delete is a + tombstone record, not a rewrite. +- **Shared live.** Every add or delete is broadcast on the dashboard event + stream as a `maintainer-notes` frame, so the other maintainers' rows + update without a reload. A draft a maintainer is typing survives the + monitor's own refreshes. +- **Read by the agents.** The scheduler types an item's live notes into the + agent's kick under a `# Maintainer notes` heading (newest first, capped at + 1 KB with "… and N more note(s) on the dashboard"), so what a maintainer + wrote on the row reaches whoever picks the item up — the same seam that + injects decisions and in-flight context ([Kick size and the list + caps](/docs/hive/operator-reference/sweeps-and-operations#kick-size-and-the-list-caps)). + Write them as instructions to a colleague, not as GitHub prose. + +API: `GET /api/notes?repo=&number=`, `POST /api/notes` `{repo, number, +text}` (≤ 2000 characters), `DELETE /api/notes/{id}` — see the +[REST reference](/docs/hive/api-reference/packs-and-acmm). Audit log actions: +`maintainer_note_add`, `maintainer_note_delete`. + +## Code activity reader + +The code activity reader is a kiosk view at `?kiosk=1&view=reader` that shows +pushed changes as readable paragraphs. It supersedes the Matrix code view +([#16137](https://github.com/hivecommons/hive/issues/16137)). The Activity Monitor +topbar has one **Code activity** entry, opening the reader in a new tab when +`dashboard.matrix.enabled` is set. The decorative Matrix view and its rain, +cascade, ghost and terminal effects are retired; there is no side-by-side +legacy view. Saved `?kiosk=1&view=matrix` display URLs keep working as a +deprecated alias that opens the reader; prefer `?kiosk=1&view=reader`. The +`mx.*` URL options and `hive.matrix.*` browser preferences are ignored. + +The internal `dashboard.matrix.*` configuration names and `/api/matrix/lines` +endpoint are deprecated names retained for compatibility; do not rename existing +configuration. They continue to enforce the same public repository allowlist, +author restriction, dashboard read authorization and scrub/path filters. Code +activity stays **off by default**: this cutover enables no capture or broadcast. +When inactive, the content endpoint answers 404 and the reader says it is not +enabled. There is no anonymous access or workspace/pre-push capture. + +- **Cards.** Each card is a complete contiguous add/remove region from a + validated unified-diff hunk at an actual published PR head. Indentation, blank lines + and repeated lines are kept. Additions start with a green `+`, and removals + start with a red `−`. Long lines wrap at a + fixed font size and are never truncated. Every card shows the repository + and PR number, the file, the source label (`Pushed PR`), and when hive + observed the change. The repository links to the real pull request. Code is + always shown as text and is never parsed as HTML. +- **Pacing.** One card is read at a time. A card stays in focus for a few + seconds plus a little more for each line, up to 30 seconds, and then the + next card scrolls into view. New work waits behind the paragraph being read. + When the reader is caught up, it holds quietly. Opening backlog is labelled + **Buffered snapshot**. **Replay buffered snapshot** explicitly replays only + the retained regions with a replay label; automatic replay is off. There is + no filler, typing effect or sound. +- **Pause.** Press **P**, press **Space**, or use the **Pause** button to pause + or resume. Scrolling with the wheel, touch, arrow keys, Page Up/Page Down, + Home or End also pauses the reader so you can inspect the text. The feed is + native, scrollable text. +- **Motion.** With `prefers-reduced-motion`, every card is shown at once and + nothing scrolls by itself. Hiding the tab clears buffered browser code; + returning obtains a new buffered snapshot. + +The reader requests `GET /api/matrix/lines?format=regions&since=` through +existing dashboard read authorization. The sentinel's existing optional patch +observer feeds this memory-only projection; no new poller or workspace collector +is installed. Only positively identified Hive/clanker PRs from explicitly +allowlisted, verified-public repositories are eligible. Private or unknown +visibility fails closed. The source reports its last completed ingest pass and +next expected pass; a cold empty feed does **not** mean no work happened. Its +freshness is bounded by sentinel polling, unchanged-head suppression and budgets, +not a live editor stream. + +Changed regions preserve both signs, indentation, blanks and repeated lines. +An unsafe addition **or removal** drops its entire region. Built-in path denies +and configured exclusions still apply. Admission, pagination, deduplication and +eviction operate on whole regions. Limits are 4,096 runes per line, 16 KiB per +region, 200 changed lines per head, 600 per minute, and 2,000 lines / 512 KiB of +server text. Browser history holds at most 1,200 lines / 256 KiB of UTF-16 text +and 32 visible cards, evicting whole regions. These are text bounds, not total +process-memory measurements. Secret filtering remains heuristic. + +Policy changes clear server buffers and rotate a policy epoch. The browser +clears its retained code and replay history on a changed epoch, disabled or +unauthorized response, failed pull, or hidden tab. A 30-second authorized pull +recovers missed sequence-only SSE nudges; code is never sent on SSE or logged. +Buffers no longer persist across restarts, including the legacy Matrix line +projection. Existing `/data/matrix-lines.json` files are neither restored nor +updated; operators may remove such historical files according to their own +retention policy. The sentinel evaluated-head map remains separate and persists. +There is no `dashboard.matrix.workspaces` setting or pre-push capture. + +## PR review and link signals + +PR pills also carry GitHub's own review state and conversation evidence +([#8968](https://github.com/hivecommons/hive/issues/8968)). Every field is +display-only: no enumeration, review, hold, or merge gate reads any of them. + +- **Review decision.** `protection.review_decision` (`APPROVED`, + `CHANGES_REQUESTED`, `REVIEW_REQUIRED`), with `protection.approvals_given` + and `protection.changes_requested_by`, comes from the one-per-repository + GraphQL query the sweep already runs for branch-protection facts + (`protectionCollector`, `pkg/github/protection_facts.go`). The pill shows + 👍 approved, 👎 changes requested (tooltip names the reviewers), or 👀 + review required. GitHub reports a null decision on a base branch that + requires no review; the decision then stays unknown — it is never inferred + — and the reviewer opinions GitHub did return are shown as opinions + ("2 approvals on GitHub — no review decision", "changes requested by @x — + no review decision from GitHub"). Any decision or opinion places the PR in + the **In review** band unless a higher band already claimed it. +- **Requested reviewers and teams.** `requested_reviewers` (logins) and + `requested_teams` (slugs) come from the list payload at enumeration time — + no additional request — on actionable, held, and stale-draft PRs alike. The + pill shows 👥; the tooltip lists them. +- **Conversation volume.** `comment_count` and `review_thread_count` are + GitHub totals (`totalCount` only, no thread nodes) added to the same + per-repository GraphQL request as the review decision, so they cost + response size rather than an additional request. The pill shows `🗨 N` + with the sum; the tooltip splits comments from review threads. Nothing is + shown when both are zero. +- **Linked issues.** `linked_issues: [{number, title, repo, state, url}]` + are the `closingIssuesReferences` GitHub reports for the PR: the first 10 + from the batch PR query when it answered for the repository (the default + path), else the first 20 from that same per-repository review-signals + request. Both producers fill every field. The pill's action cluster shows + a `🔗` badge that opens the first still-open one (else the first); the + tooltip lists all. This is the PR-side mirror of the issue column's + `linked_prs` badge, and like it comes only from the snapshot — the card + never infers or fetches relationships. The + [activity monitor](#hive-activity-monitor) uses `title` and `state` to + name a linked issue that is not itself listed in the snapshot. A reference + that reaches the cycle with only its number — an older persisted snapshot, + or an issue already closed by an earlier PR while a superseded PR's body + still says `Fixes #N` — is completed after the review-signals pass + (`EnrichLinkedIssueTitles`, `pkg/github/linked_issue_titles.go`): from the + forgestate cache when it still holds the issue, else one targeted issue + read per issue, remembered for 24 hours (a failed read for one hour, a 404 + for the full day), at most eight reads per cycle — never one per cycle per + issue. + +The extended request is tried first; a forge that rejects one of the added +fields (an older GHE) is asked the decision-only query instead, so the review +decision the merge-block wording depends on is never lost to a display +field. Stale drafts, which `EnrichCIStatus` never touches, receive these +signals through `EnrichReviewSignalsAndWorkPRs` — the same per-repository +query and no per-PR mergeability or check-run fetch, since a draft is not a +merge candidate. The same call stamps `linked_issues` onto the sidelined PRs +(drafts, exempt-labelled) in each repository's work details, so a draft whose +body says `Fixes #N` pairs with that issue in the activity monitor; a +repository with both stale drafts and sidelined PRs still costs one query, and +none when the batch PR query already answered. + + +### Settings → Labels → Reporter trust: clanker-requested + +The Reporter trust block also controls the opt-in `clanker_requested` policy, which steers untrusted contributors to the [ClankeR relay](/docs/hive/contributor-relay#steering-outside-prs-to-the-relay-clanker_requested): + +- **Toggle** for `project.issue_filter.reporter_trust.clanker_requested` (off by default). +- **Label name** (placeholder `clanker-requested`) for `clanker_requested_label`; it must not be blank. +- **Comment addendum** textarea for `clanker_requested_addendum` (optional, max 1000 bytes). +- A live **preview** of the comment text, updated as you type. + +`GET`/`PUT /api/config/governor` expose and validate `clankerRequested`, `clankerRequestedLabel` and `clankerRequestedAddendum`. See [Contributor trust tiers and delegated agent roles](https://github.com/hivecommons/hive/blob/v5/src/docs/contributor-trust-and-roles.md#clanker-requested-policy-for-outside-prs). + +## Appearance themes + +Owners can choose a hive-wide dashboard theme in **Settings → Appearance** or by +editing the persisted config through `PUT /api/config/dashboard/theme`. The +config surface is: + +```yaml +dashboard: + theme: hive # built-in id from /api/themes, or custom + theme_overrides: + tokens: + "--accent": "#e0a33a" + background: + image: https://example.org/bg.svg # https or data: URI only + opacity: 0.08 + attachment: fixed + custom_css: | + .panel { border-radius: 2px; } +``` + +Built-ins are loaded from one YAML file per theme under `src/pkg/dashboard/theme/themes/`. Initial themes include `hive`, `hive-dark`, `hive-light`, `star-wars`, `dungeons-and-dragons`, `star-trek`, `cyberpunk`, `terminal`, `solarized-dark`, `nord`, and migrated contributor profile skins such as `contributor-violet-advisor`. Theme files can set `scopes: [dashboard, contributor]` so the same catalog drives dashboard Appearance and contributor profile styling. Tokens are +validated against the dashboard's `:root` CSS custom properties so typos fail +fast. Custom CSS is capped at 32 KiB, strips HTML/style-breakout characters, and +only permits `https:` or bounded `data:` URLs; inlined backgrounds are capped at +256 KiB. `/api/theme.css` serves the effective theme with an ETag and is linked +from the document head so the themed stylesheet is available before first paint. + +### Settings → Appearance + +The **Appearance** tab in Settings renders the built-in preset gallery with +swatches for background, panel, accent, and text colors. Hovering a card previews +it, **Apply** persists the preset, **Reset to preset** removes overrides, and +**Apply background/CSS** saves the background URL, opacity, honeycomb watermark, +and custom CSS textarea (with byte counter). The existing dark/light button asks +the theme API for the closest light or dark built-in variant and refreshes +`/api/theme.css` without reloading the dashboard. + +Preset screenshots are committed in `src/docs/images/themes/` for the shipped catalog. + +The contributor profile page uses the same theme catalog. Its former local profile +style numbers map to `contributor-*` theme ids, so existing browser-local choices +continue to work while new themes appear in the profile picker. Contributor CSS is +layered after shared theme variables and hive-wide custom CSS: theme vars → admin +Appearance custom CSS → contributor `?style=owner/repo/path.css@ref` stylesheet. + + +### How to add a dashboard theme + +Create one YAML file in `src/pkg/dashboard/theme/themes/` and give it a unique +`id`, display `name`, original `description`, `author`, `dark` flag, `tokens`, +optional `background`, optional `custom_css`, and `fonts` stacks. The directory +README documents the full schema and guardrails. The theme loader embeds every +`*.yaml` file with `embed.FS`; adding a file automatically makes it appear in +`GET /api/themes`, `GET /api/theme.css?theme=`, and Settings → Appearance. +CI runs `pkg/dashboard/theme` tests that parse every file, enforce unique IDs, +and reject unsupported dashboard CSS variables, so theme-only changes are a good +first issue when the palette is original and avoids logos, copyrighted imagery, +quotes, or bundled proprietary fonts. + +## UI conventions: no native browser dialogs + +Hive hub and spoke UI code must not call browser-native dialog APIs such as `prompt()`, `alert()`, `confirm()`, `showModalDialog()`, or native-styled `.showModal()`. Use the themed in-app helpers instead (`hivePrompt`, `hiveConfirm`, `hiveAlert`/toast, or the contribute admin modal) so dialogs match the dashboard, are accessible, and do not block the whole tab. The ratchet tests `TestNoNativeBrowserDialogsRatchet` in `pkg/dashboard` and `pkg/hub` scan shipped UI sources and should be updated only to make the rule stricter. + +## Settings → Compliance + +The **Compliance** tab in Settings (merger or owner) shows how this hive's +configuration lines up with the selected compliance framework profiles. It +opens with a banner: Hive is not certified; the tab maps your configuration +to control requirements. + +- **Framework profile** — tick the frameworks to evaluate + (`compliance.frameworks`); saved by the footer **Save & close** through the + owner-only `PUT /api/config/governor/compliance`. +- **Controls** — every control grouped by domain with its implementing + setting(s), current → recommended value and a status pill. Owners get an + inline toggle for boolean settings and **Apply recommended** per domain + (a themed confirmation lists each change); other settings link to their + owning tab with **Open setting**. Changes are staged in the owning section + and written only on Save. Mergers see the tab read-only. + +Details, including which settings can be toggled inline, are in +[Compliance controls](https://github.com/hivecommons/hive/blob/v5/src/docs/compliance.md#using-the-compliance-tab). diff --git a/docs/content/hive/getting-started.md b/docs/content/hive/getting-started.md index 9fcd661..782a378 100644 --- a/docs/content/hive/getting-started.md +++ b/docs/content/hive/getting-started.md @@ -16,7 +16,7 @@ You do not need to reach L6. At L6, permitted lanes can merge when automated che | Starting point | Action | Continue when | |---|---|---| -| No hive; you want hosting | Open [Request a hive](https://hive.hivecommons.dev/get-started) and follow [Hosted Hub onboarding](https://github.com/hivecommons/hive/blob/v5/src/docs/hosted-hub.md). Sign in with GitHub, supply the repository URL, and request a starting level. | An admin has approved and provisioned it; **My Hives** shows its dashboard URL. | +| No hive; you want hosting | Open [Request a hive](https://hive.hivecommons.dev/get-started) and follow [Hosted Hub onboarding](/docs/hive/hosted-hub). Sign in with GitHub, supply the repository URL, and request a starting level. | An admin has approved and provisioned it; **My Hives** shows its dashboard URL. | | No hive; you will operate it | Choose [Docker Compose](https://github.com/hivecommons/hive/blob/v5/src/docs/quickstart-docker-compose.md), [Podman](https://github.com/hivecommons/hive/blob/v5/src/docs/quickstart-podman.md), or [Kubernetes](https://github.com/hivecommons/hive/blob/v5/src/docs/kubernetes-deployment.md). Complete that guide's runtime, storage, network, and login setup first. | Your container is running and you can open its dashboard. | | You already have a dashboard URL | Sign in with the GitHub identity granted access by its owner. | You can see the welcome checklist and settings. | @@ -73,7 +73,7 @@ not an unmanaged standalone deployment. ## Your first week (do exactly this) -1. **Connect and authenticate.** Finish Step 0, then follow [hosted first-run setup](https://github.com/hivecommons/hive/blob/v5/src/docs/hosted-hub.md#3-finish-first-run-setup-on-the-spoke-dashboard) for **Settings → Model Gateways** or the per-backend CLI login. A gateway's **Test** should report `OK — N models available`; a CLI backend must finish its login. Check errors rather than waiting for authentication to fix itself. +1. **Connect and authenticate.** Finish Step 0, then follow [hosted first-run setup](/docs/hive/hosted-hub#3-finish-first-run-setup-on-the-spoke-dashboard) for **Settings → Model Gateways** or the per-backend CLI login. A gateway's **Test** should report `OK — N models available`; a CLI backend must finish its login. Check errors rather than waiting for authentication to fix itself. 2. **Confirm limits before work starts.** Check the ACMM badge and **Settings → Budget**. Set Total Tokens, Period (days), and Critical Percent. To observe without new issues or PRs, use L2. Leave supervisor paused and brainstorm unchanged for this first exercise. 3. **Set cadences, then enable workers.** At L2, open the gear settings for scanner, quality, and guide. Set each available governor/load-mode cadence to **12h or 1d**, then un-pause them. Start with one agent if you want to distinguish its output. Check reviewer separately if enabled: it can post COMMENT-only reviews at L2, not approvals or merges. 4. **Verify setup.** Allow 2–3 minutes for configuration/status propagation. Confirm App access, backend authentication, the applied level, and the saved cadence. A first run can take 5–10 minutes or a full cadence interval; a heartbeat alone does not mean work has run. Check Activity and authentication errors if no run appears. @@ -331,7 +331,7 @@ These agents first become available at L5 and remain **paused by default** at L5 1. Open **Settings → Project Observability**. Declare the stack your managed project actually runs and save. This may be OpenTelemetry, Prometheus, Grafana, a `ServiceMonitor`, or a commercial backend. Without that declaration, their PR-capable policies fail closed. 2. Set each agent's cadence before un-pausing it; **24h** is a conservative start. Saving the observability declaration never changes cadences (#7261), so both steps are required. -Leaving them paused is valid. See [Telemetry agent](https://github.com/hivecommons/hive/blob/v5/src/docs/telemetry.md), [Operations agent](https://github.com/hivecommons/hive/blob/v5/src/docs/operations.md), and the `project_observability` block in [agent configuration](/docs/hive/agent-configuration). +Leaving them paused is valid. See [Telemetry agent](/docs/hive/telemetry), [Operations agent](https://github.com/hivecommons/hive/blob/v5/src/docs/operations.md), and the `project_observability` block in [agent configuration](/docs/hive/agent-configuration). ### L5 review routine @@ -417,7 +417,7 @@ to grant; remaining at a lower level is valid. --- For configuration beyond this first path, use [agent configuration](/docs/hive/agent-configuration), -[settings](https://github.com/hivecommons/hive/blob/v5/src/docs/settings.md), and the [documentation map](/docs/hive/documentation-map). +[settings](/docs/hive/settings), and the [documentation map](/docs/hive/documentation-map). ## What this guide doesn't cover (and why) diff --git a/docs/content/hive/hosted-hub.md b/docs/content/hive/hosted-hub.md new file mode 100644 index 0000000..5c8f6b9 --- /dev/null +++ b/docs/content/hive/hosted-hub.md @@ -0,0 +1,192 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/hosted-hub.md) during the docs build. Edit the canonical source in the Hive repository. + +# Hosted Hive Hub onboarding + +The hosted Hive Hub at is the no-cluster path for +trying Hive. The hub hosts the OAuth-protected onboarding pages, lists public +hives, and provisions spoke dashboards for approved requests. The legacy +`https://hive.hivecommons.dev` hostname redirects during the cutover; use +`https://hive.hivecommons.dev` for new bookmarks and configuration. + +This guide follows the current hub and dashboard UI: + +- hub routes such as `/login`, `/get-started`, `/dashboard`, `/my-hives`, and + `/fleet` are registered in `src/pkg/hub/server.go`, `src/pkg/hub/saas.go`, and + `src/pkg/hub/oauth.go`; +- the request wizard labels are **Login**, **Your Repo**, and **Request** in + `src/pkg/hub/static/get-started.html`; +- the spoke dashboard settings tabs are rendered by + `src/pkg/dashboard/static/index.html` as **Forge App**, **Model Gateways**, + **Budget**, **Repos**, and the per-agent **General** tab. + +## 1. Sign in + +1. Open . +2. Click **Sign in** or open . +3. Complete the GitHub login. The hosted hub uses your GitHub identity to know + who is requesting the hive; the wizard says it requests no account + permissions and stores no password. +4. After login, open **My Hives** from the header or go to + . The same dashboard is also aliased + at `/my-hives`. + +## 2. Request a hosted hive for a repo + +1. Click **Get Started** or **Request a Hive**, or open + . +2. In **Your Repo**, paste the repository URL the hive should manage. Accepted + examples in the UI include `github.com/my-org/my-repo` and + `https://github.ibm.com/my-org/my-repo`. GitHub.com and GitHub Enterprise are + supported; GitLab/Gitea/Forgejo URLs are rejected by the wizard today. +3. In **Request**, pick the starting ACMM level. The wizard currently offers + L1–L3 and marks **L3 — Quality-Gated (Measured)** as the recommended start. + L4–L6 appear as **Available after provisioning** because higher automation is + advanced from the spoke dashboard after the hive is running. +4. Add optional contact details, review the summary, and click **Request a + Hive**. +5. Wait for an admin to approve and provision the request. When the hive is + ready it appears under **My Hives** with its dashboard URL. + +### Notify Discord when a request is filed + +Hub operators can mirror each new hosted-hive request into the community +Discord `#requests` channel. In Discord, open **Channel settings → +Integrations → Webhooks → New Webhook** for `#requests`, then copy the webhook +URL. Store it as a hub secret and expose it only to the `hive-hub` container: + +```yaml +env: + - name: HIVE_HUB_DISCORD_REQUESTS_WEBHOOK + valueFrom: + secretKeyRef: + name: hive-hub-secrets + key: HIVE_HUB_DISCORD_REQUESTS_WEBHOOK + optional: true +``` + +The same value can also be configured in hub YAML as +`hub.notifications.discord.requests_webhook_url`, but the environment variable +is preferred for Kubernetes because the Discord URL is a secret. The hub posts +only after a new provision request is persisted; edits, approvals, denials, and +status changes do not send messages. + +## 3. Finish first-run setup on the spoke dashboard + +Open the hive dashboard from **My Hives**. The dashboard's welcome checklist and +settings tabs guide the rest of setup. + +### Install or authorize the GitHub App + +The hosted wizard does not ask you to install the GitHub App before +provisioning. After provisioning, the spoke dashboard prompts you with the +right install link for the GitHub host your repo lives on. + +Use either: + +- the welcome checklist action **Install GitHub App**; or +- **Settings → Forge App**, where the **Active config** card shows the App ID, + App slug, API URL, Base URL, Installation ID, key fingerprint, and **Auth + state**. If installation is missing, click **Install GitHub App on + ``**, finish the GitHub install/authorization flow, then click + **Re-check**. + +When adding more repos later, use **Settings → Repos**. The add flow checks +GitHub App access and, when needed, offers **Install/authorize the App for +``** followed by **Re-check & add**. + +### Configure model gateways and keys + +Open **Settings → Model Gateways** when an agent uses OpenRouter, LiteLLM, vLLM, +llm-d, watsonx, or another OpenAI-compatible endpoint. When you save a new +gateway key, Hive rewrites the persisted key file and immediately refreshes the +in-pod proxy routes for already-running agents, so the next kick uses the new +key without a manual agent restart. The gateway row shows the SHA-256 of the +effective key (first 12 hex characters, full value on hover) and the settings +API returns the same hash as `keySHA256`; compare it with LiteLLM's key hash to +verify which key agents will present. Hive logs this hash as `api_key_sha256` +when an inference route is set, never the key itself. + +- Click **+ Add gateway** for a manual gateway. The form has **Preset**, + **Name**, **Endpoint URL**, **API Key**, optional **Key name**, and **Default + Model** fields. Keys are stored privately on the hive and are not written into + `hive.yaml`, logs, or config downloads. +- Click **⚡ Fund this hive with OpenRouter** to generate an OpenRouter + authorization QR/link. A scoped OpenRouter key is stored as the `openrouter` + gateway when authorization completes. +- Use **Test** on a saved gateway. Success reads `OK — N models available`. + Failures are shown as `Connection failed: ...` and classify common causes such + as an auth rejection (`HTTP 401`), DNS/connectivity, `5xx`, or budget/rate + limiting (`HTTP 429`). + +### Log in Copilot-backed agents + +Agents that use `copilot` need a device-flow login on the spoke. The welcome +checklist calls this **Log in once per method** and explains that one Copilot +login covers every Copilot agent. Use the checklist **Show me** action or open an +agent terminal with the cyan **▶ terminal** button and complete `/login` in the +CLI when prompted. The login modal shows a device code, **Copy**, **Open GitHub +→**, and a polling status until authorization finishes. + +### Confirm budget and ACMM settings + +- Open the maturity-level dialog from the amber ACMM badge to confirm the hive's + ACMM level. The hosted request starts at the selected level, but higher levels + should be earned as CI, coverage, and operator trust improve. +- Open **Settings → Budget** to set **Total Tokens**, **Period (days)**, and + **Critical Percent**. The UI notes that an exhausted budget suppresses most + kicks; per-agent exemptions are available on the same tab. + +## 4. Read the Fleet page + +Open . The page title is **Fleet health** and +the table columns are **Hive**, **ACMM**, **Mode**, **Version**, **Divergence +(expects · running · able)**, and **Output (90d)**. + +Key signals: + +- The left dot summarizes the hive as problem, warning, ok, unknown, offline, or + parked. +- The **WHY** chip and remediation line explain non-green rows when the hub has a + specific fix. +- **Divergence (expects · running · able)** compares how many agents the governor + expects, how many are running, and how many can actually work. A **PROBLEM** + chip means the governor expects agents to be on but they are blocked. +- Agent restart storms are also surfaced as problem chips when a reported agent + reaches `HIVE_HUB_AGENT_RESTART_PROBLEM_THRESHOLD` restarts in 24 hours + (default `5`). Owners/admins can click **reset** beside the chip to start + counting from the reset point while troubleshooting recurrence. +- Capability chips show green/amber/red/gray for able/partial/blocked/unknown, + with ticks for issue, PR, and merge capability. +- Filters at the top let you narrow by **problems only**, **advisory output**, + **budget**, and **gh app** health. +- Per-hive drift badges (`heartbeat-stale`, `duplicate-spoke`, `identity-split`, + `version-absent`, and more) flag rows whose state deviates from the fleet or + cannot be trusted. Each kind, its severity, and who is expected to fix it + (hive owner vs hub operator) are listed in the + [fleet drift signals reference](https://github.com/hivecommons/hive/blob/v5/src/docs/fleet-drift-signals.md). + +For the open issues and pull requests the hives you can see are working on, +open **📡 Fleet activity** (next to **🔬 Evidence**) or +. It is a read-only board that refreshes +every 15 seconds and says which hives are stale or not reporting. See +[Hub Fleet activity page](https://github.com/hivecommons/hive/blob/v5/src/docs/hub-fleet-activity.md). + +## Common problems and fixes + +| Symptom | Likely cause | Fix | +|---|---|---| +| Gateway test says `Connection failed` or the fleet diagnosis says `inference auth` | The gateway key is stale, rejected (`HTTP 401`), DNS/connectivity failed, or the provider returned a budget/rate-limit response. | Open the spoke dashboard, go to **Settings → Model Gateways**, edit the affected gateway, update **Endpoint URL** or **API Key**, and click **Test**. | +| Copilot agents show `stuck at login` or fleet remediation says **Copilot device-flow login on the spoke dashboard** | The Copilot CLI has no usable device-flow login in the spoke. | Open the hive dashboard, use **Log in once per method**, or open **▶ terminal** and run `/login` in the Copilot CLI. | +| Fleet shows `budget exhausted`, `budget critical`, or remediation says **Raise or reset the budget limit (Settings → Budget)** | The governor token budget is depleted or set too low. | Open **Settings → Budget**, raise **Total Tokens**, adjust **Period (days)**/**Critical Percent**, or exempt a specific agent if it must keep running. | +| GitHub App health is `broken`, `not-installed`, or repo add says the App needs access | The GitHub App is not installed on the org/repo, points at the wrong installation, or lacks access after a repo/org change. | Open **Settings → Forge App**, click **Install GitHub App on ``** or **View App settings**, complete the GitHub flow, then click **Re-check**. For repo additions, use **Install/authorize the App for ``** and **Re-check & add**. | +| A requested hive disappeared or the old per-hive URL times out | Unconfigured or inactive hosted hives can be reaped to free capacity. | Request a new hive at , install the Forge App in the first session, and update bookmarks to the new URL. | +| **Settings → Hub → Dashboard URL** is read-only ("Owned by the hub (heartbeat)"), or saving a new value answers `409` | On a hosted hive the hub owns `hub.dashboard_url`: its ingress terminates the hostname and the heartbeat delivers the vanity URL, so a local edit would be reverted by the next beat — and until then it would be the OAuth callback origin, so a typo could lock you out. | Nothing to fix: the field records where the hub serves your dashboard. To serve it from a different host of your own, set `dashboard.public_url` (it takes precedence for OAuth and is never overwritten by the heartbeat). | + +## Getting help + +- For project questions or hosted-hub problems, open an issue in + and include the hive name, repo, + and the visible fleet/dashboard error text. Do not include API keys, private + keys, cookies, or tokens. +- For self-hosted hub operation, use the [self-hosted hub deployment guide](/docs/hive/hub-deployment), + [fleet health guide](https://github.com/hivecommons/hive/blob/v5/src/docs/fleet-health.md), and [troubleshooting guide](/docs/hive/troubleshooting). diff --git a/docs/content/hive/hub-deployment.md b/docs/content/hive/hub-deployment.md new file mode 100644 index 0000000..bc85c6b --- /dev/null +++ b/docs/content/hive/hub-deployment.md @@ -0,0 +1,287 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/hub-deployment.md) during the docs build. Edit the canonical source in the Hive repository. + +# Self-hosted hub deployment + +Hive can run either as a spoke dashboard or as the hub. The same Go binary serves both roles; `HIVE_MODE=hub` selects the hub server in `cmd/hive/main.go`. + +Use a self-hosted hub when you need a private registry, private SaaS provisioning, air-gapped control, or a hub URL other than `https://hive.hivecommons.dev`. If you only need a hosted spoke, use the hosted Hive Hub instead. + +## What `Dockerfile.hub` builds + +`src/Dockerfile.hub` builds only `./cmd/hive`, installs `kubectl`, creates `/data` and `/etc/hive`, sets `HIVE_MODE=hub`, and runs: + +```sh +hive --config /etc/hive/hive.yaml +``` + +The hub listen port is still controlled by `HIVE_HUB_PORT` in the binary and defaults to `3001`. The Dockerfile exposes port `80`, so set `HIVE_HUB_PORT=80` if your container platform expects the process to bind that exposed port. + +## Required storage + +Use a persistent volume mounted at `/data`. The production/manual-provisioning docs describe the live hub as namespace `hive-hub`, PVC `hive-hub-data-rwx`, mounted at `/data`. + +The hub stores live SaaS state under `/data`: + +| Path | Purpose | +|---|---| +| `/data/saas/hives//meta.json` | Per-hive SaaS record used by auth, upgrades, assignments, and dashboard links. | +| `/data/hub-registry.json` | Fleet registry populated by spoke heartbeats. | +| `/data/saas/hub-secret.key` | Optional fallback heartbeat bearer secret when `HIVE_HUB_SECRET` is not set on the hub. | +| `/data/saas/clusters.json` | Cluster definitions used by automated provisioning. | + +Use ReadWriteMany storage for hosted spoke PVCs. The provisioning template in `pkg/hub/saas_provision.go` requests `ReadWriteMany` and its rolling update strategy relies on both old and new pods being able to mount `/data` during a surge. + +## Minimal hub environment + +| Variable | Required | Notes | +|---|---:|---| +| `HIVE_MODE=hub` | Yes | Selects hub mode. | +| `HIVE_HUB_PORT` | No | Defaults to `3001`. Set to `80` for the published hub image contract if needed. | +| `HIVE_CONFIG` or `--config` | No | Defaults to `/etc/hive/hive.yaml`; `Dockerfile.hub` passes `--config /etc/hive/hive.yaml`. | +| `HIVE_HUB_SECRET` | Strongly recommended | Master secret from which heartbeat bearers and per-hive keys derive. If unset, the hub reads `/data/saas/hub-secret.key` when present. The hub additionally maintains a rotation generation set alongside it — see [security-model.md](/docs/hive/security-model#9-platform-and-supply-chain); rotate via the admin endpoint, never by swapping the master in place. | +| `HIVE_HUB_OAUTH_CLIENT_ID` / `HIVE_HUB_OAUTH_CLIENT_SECRET` | Enables **GitHub** login | These two enable the GitHub provider specifically. Human login is multi-provider: Google, IBMid, Red Hat, Microsoft Entra ID, and a generic OIDC slot are each enabled independently via `HIVE_HUB_OIDC__CLIENT_ID` (+ `_CLIENT_SECRET`, `_ISSUER`, `_SCOPES`, `_DISPLAY` — see [env-vars.md](/docs/hive/env-vars#hub-login-providers)). With two or more providers configured the hub shows a provider picker at `/login`; with exactly one it redirects straight into it; with none it logs OAuth disabled and registers no login routes. A provider with a client id but a missing/invalid issuer is silently skipped (check the `hub login enabled providers=` startup log line). | +| `HIVE_GITHUB_TOKEN` or GitHub App config | Required for operations that call GitHub | Same GitHub auth rules as a spoke. | +| `HIVE_HUB_SLACK_BOT_TOKEN`, `HIVE_NTFY_SERVER`, `HIVE_NTFY_TOPIC` | No | Optional hub notifications. | +| `HIVE_BACKUP_*`, `OCI_*`, `HIVE_KUBECONFIG_DIR` | No | Required only for disaster-recovery backup and OCI/FSS provisioning flows. See `backup-restore.md`. | + +## Hub config shape + +The hub still reads `hive.yaml`. The hub-specific code mainly uses the `hub` block, GitHub credentials, dashboard/auth settings, and any provisioning-related data under `/data/saas`. A minimal seed keeps the normal project and GitHub validation satisfied: + +```yaml +project: + org: your-org + repos: [your-repo] + primary_repo: your-repo + +github: + token: ${HIVE_GITHUB_TOKEN} + +dashboard: + auth_token: ${HIVE_DASHBOARD_TOKEN} + +hub: + enabled: true + url: https://hive.example.com +``` + +Keep secret values in Kubernetes Secrets or environment variables; do not write token values directly into `hive.yaml`. + +## Registering spokes to your hub + +A spoke points at the hub with its config `hub.url` or the `HIVE_HUB_URL` override. Protected hubs require the same heartbeat secret on every spoke: + +```yaml +hub: + enabled: true + url: https://hive.example.com +``` + +```yaml +env: + - name: HIVE_HUB_URL + value: https://hive.example.com + - name: HIVE_HUB_SECRET + valueFrom: + secretKeyRef: + name: hive-secrets + key: HIVE_HUB_SECRET +``` + +Without `HIVE_HUB_SECRET`, a protected hub returns `401 unauthorized`, the spoke logs `hub heartbeat rejected status=401`, and the hub shows the hive offline. This matches the gotcha in `manual-provisioning.md`. + +### Customer profile sharing + +`HIVE_HUB_CUSTOMERS_SHARE_ENABLED` is off by default. Set it to `1`, `true`, +`yes`, or `on` in the hub environment to enable **Profile sharing** in Fleet +and on hive cards where the signed-in person holds a grant. The hub dashboard's +operator settings show the effective state. With the switch off, the page and +its API return `404`; stored choices are not deleted. + +People can enter or clear their real name, organization, and country, then +confirm or withdraw their own selections separately for each hive. Legacy, +administrator-entered, and inferred values are not eligible for sharing. A +material disclosure change requires reconfirmation. This phase records consent +on the hub only and does not send any profile fields to hives. + +### Reserved `byo-` hive IDs (credential fence) + +Hive IDs that start with `byo-` are reserved for hives that their owners run and register themselves ([#18060](https://github.com/hivecommons/hive/issues/18060)). A hub lists such a hive as directory metadata only, so its heartbeat response never carries hub-held credentials or management actions, whatever key the spoke authenticated with. The hub withholds these fields: the GitHub App config (including cluster, secondary and webhook relay keys), the pending gateway, the claimed project config, the cluster ID, the authorized-user list, visibility, upgrade and branch-switch instructions, the upgrade announcement and policy, spoke restarts, agent-restart resets, fleet-breaker instructions, and self-experiment flags. Display-only data such as admin banners still flows. When the fence withholds a field, the hub logs `heartbeat: credential fence withheld fields from self-service hive` with the field names, never the values. Do not give an operator-provisioned hive a `byo-` ID. + +### Self-service registration + +The fence above is always on. The registration flow that fills the `byo-` namespace is opt-in. With it enabled, a signed-in hub user lists a hive they run on their own infrastructure without an operator issuing anything. The owner-facing steps are in [Register a self-hosted hive on a hub](/docs/hive/register-self-hosted-hive); this section is for the operator running the hub. + +#### Enable it + +| Variable | Default | What it controls | +|---|---|---| +| `HIVE_HUB_SELFSERVICE_REGISTRATION` | off | Turns on `/api/hub/selfservice/*` and the **Register your own hive** form on the dashboard. Accepts `1/true/yes/on`. Read per request, so no restart is needed. While off, every route except `GET /api/hub/selfservice/status` answers `404`, and the dashboard button sends users to the self-hosting guide instead of the form. | +| `HIVE_HUB_SELFSERVICE_MAX_PER_USER` | `5` | How many `byo-` hives one GitHub login may hold at once. The next registration answers `429` until the user removes one. | +| `HIVE_HUB_SELFSERVICE_MAX_REPOS` | `20` | How many repos one registration may list ([#18642](https://github.com/hivecommons/hive/issues/18642)). Each repo is one read-only GitHub ownership check, so values above `500` are clamped to `500`. `POST /api/hub/selfservice/hives` answers `400` over the cap; `POST /api/hub/v1/registrations` answers `413` with `limit: max_repos`. Advertised to clients by `GET /api/hub/v1` as `limits.max_repos`. Read per request. | +| `HIVE_HUB_SELFSERVICE_EXPIRY` | `24h` | How long a registered hive may go without an accepted heartbeat before the sweep removes it. Counted from the last accepted heartbeat, or from registration while there has been none. | +| `HIVE_HUB_SELFSERVICE_SWEEP_INTERVAL` | `10m` | How often the expiry sweep runs. Read at startup; restart after changing. | + +All four are listed with the other hub variables in [env-vars.md](/docs/hive/env-vars). + +#### What a registration does + +1. The user is signed in through the hub's GitHub OAuth, so the hub holds their encrypted GitHub token. Without a stored token or a GitHub login the request is refused. +2. The user supplies a short name, an org, up to 20 `owner/name` repos and an `https` dashboard URL. The hub builds the ID as `byo---`; the double hyphen keeps IDs unambiguous, since logins may contain `-` but never `--`, and a name may not start with `-`. Nothing the user sends can produce an ID outside the `byo-` prefix, and a name that would borrow another namespace (such as `hosted-`) is refused. +3. For every repo the hub calls GitHub with the user's own token and requires `permissions.admin`. `maintain` and `write` are not enough. One failing repo refuses the whole request with `403` naming that repo, and nothing is stored. +4. The hub checks the per-user cap and that the ID is not already taken, in the registry or by a hub-provisioned hive. +5. The hub mints a random heartbeat key, stores only its hash in `/data/hub-selfservice.json`, and returns the raw key in the `201` response together with Compose, Podman and Kubernetes snippets. The raw key appears nowhere else: not in the list route, not in a log line, not on disk. + +The registry entry becomes a `self-hosted` hive in Active Hives and the fleet views once a heartbeat is accepted. The type is assigned by the hub; the spoke cannot claim it. + +#### What a `byo-` key can and cannot do + +- It authenticates heartbeats for exactly one hive ID, the one it was minted for. Presenting it with any other ID fails. +- A `byo-` ID is verified only against its stored hash. The master-derived paths are never tried for a `byo-` ID, so `HIVE_HUB_SECRET` and keys derived from it never authenticate a self-service hive, and a self-service key never authenticates a `hosted-` or operator-provisioned ID. +- The owner never receives `HIVE_HUB_SECRET`. The hub never consults it in the self-service routes and never returns it. +- Everything the fence withholds still applies: the hub sends the hive no GitHub App config, gateway, cluster ID, authorized users, upgrade or branch-switch instructions, restarts or fleet-breaker actions. Listing is directory metadata only. + +#### Editing a registration + +`PATCH /api/hub/v1/registrations/{id}` changes `repos` and `dashboard_url` in place, so adding a repo no longer means deleting the registration and registering again (which revoked the key and took the spoke offline). The heartbeat key is not touched: the spoke keeps heartbeating with the key it has. + +- **Who:** the owner, signed in to the hub. A registration key cannot edit its own record, and a hub admin who does not own the hive gets `404`. +- **`If-Match` is required.** `GET /api/hub/v1/registrations/{id}` returns the `ETag`; send it back on the `PATCH`. A missing header is `428`, a stale one is `412` with the current `ETag`, so two operators editing at once cannot silently overwrite each other. Heartbeats do not change the `ETag`. +- **`repos`:** a full list replaces the repos, or `{"add": [...], "remove": [...]}` changes them. Only the repos an edit adds are checked against GitHub (the same read-only `permissions.admin` check as registration, with the owner's own stored token); one failing repo refuses the whole edit and nothing is applied. Kept repos keep their proof time, and removed repos lose theirs. At least one repo must remain, and `HIVE_HUB_SELFSERVICE_MAX_REPOS` applies (`413 {limit: "max_repos"}`). +- **`dashboard_url`:** an `https` URL to a public address, or `""` to clear it. +- **Not editable:** `org`, the owner, the ID and the keys. To change the `org`, delete the registration and register it again. +- **No GitHub writes.** The edit changes the hub's own registry only. + +The route is part of the v1 registration protocol and follows the same switch as the rest of it, `HIVE_HUB_SELFSERVICE_REGISTRATION`; discovery (`GET /api/hub/v1`) lists it under `operations` with `if_match: "required"` and its fields under `patch_fields`, so a hub that does not offer it does not advertise it. The v6 `/api/hub/selfservice/*` routes are unchanged. + +#### Rotation + +The owner can rotate from the **Self-hosted hives** list or with `POST /api/hub/selfservice/hives/{id}/rotate`. The hub mints a new key and keeps the previous hash live for a 10 minute overlap so a running spoke can pick up the new value without a gap. After the overlap only the new key is accepted. Only the owner can rotate; a hub admin who does not own the hive gets `404`, the same answer as for a missing hive. + +#### Expiry sweep + +A background sweep runs every `HIVE_HUB_SELFSERVICE_SWEEP_INTERVAL` and removes any `byo-` hive whose last accepted heartbeat is older than `HIVE_HUB_SELFSERVICE_EXPIRY`, or that never heartbeated within that window after registration. The key is revoked and the registry entry is removed in the same pass. The owner registers again when the hive is back; there is no grace list. + +#### Revoking as admin + +A hub admin removes any self-service hive with `DELETE /api/hub/selfservice/hives/{id}` or from the dashboard. The key stops authenticating immediately and the listing disappears. The owner's own **Remove** button does the same for their hives. The audit line records who did it and whether it was the owner or an admin. If you need to stop all registrations at once, unset `HIVE_HUB_SELFSERVICE_REGISTRATION`; existing entries keep heartbeating until they expire or are removed. + +#### Audit events + +Every decision writes one structured log line, documented in [audit-log.md](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-log.md): + +| Event | When | +|---|---| +| `selfservice_hive_registered` | A registration passed every check and a key was minted. | +| `selfservice_hive_refused` | A registration was turned away; `reason` is one of `invalid_name`, `reserved_prefix`, `duplicate_id`, `invalid_repos`, `invalid_dashboard_url`, `invalid_update` (a `PATCH` body that was refused), `per_user_cap`, `no_github_token`, `no_github_login`, `not_repo_admin`, `ownership_check_error`. | +| `selfservice_hive_updated` | The owner edited the repos or dashboard URL with `PATCH`; the line counts repos added and removed and carries no key. | +| `selfservice_hive_rotated` | The owner rotated the key; `overlap` is how long the old key keeps working. | +| `selfservice_hive_revoked` | The owner or an admin removed the hive; `by_admin` tells which. | +| `selfservice_hive_expired` | The sweep removed a hive; `last_heartbeat` is RFC 3339 or `never`. | + +No audit line ever carries a key or a hash. + +## Hosted spoke provisioning model + +The hub's SaaS provisioner creates or records: + +1. Namespace, RBAC, Secret, ConfigMap, Service, route/ingress, Deployment, and an RWX `hive-data` PVC. +2. A mounted `/data` volume where the spoke writes runtime config and state. +3. `HIVE_ID`, `POD_NAMESPACE`, `HIVE_LEVEL`, `HIVE_HUB_URL`, `HIVE_HUB_SECRET`, optional `HIVE_AUTHORIZED_USERS`, and inference endpoint env vars in the spoke Deployment. +4. `/data/saas/hives//meta.json` on the hub PVC. Heartbeats can be accepted without this record, but hub-driven upgrades and dashboard links need it. + +For push-reported clusters where the hub cannot run `kubectl`, follow the manifest-level workflow in `manual-provisioning.md`; this guide intentionally keeps the hub setup consistent with that battle-tested path. + +### Push-reported cluster entries + +`/data/saas/clusters.json` also accepts per-cluster network overrides for hives it provisions: `upstream_proxy` (`{url, hosts[], no_proxy[]}`, a CONNECT forward proxy, injected as `HIVE_UPSTREAM_PROXY_*` env) and `host_aliases` (`[{ip, hostnames[]}]`, rendered as Pod `hostAliases` for a GHE reachable only via a TLS reverse proxy on a fixed IP; existing hives are converged by a rate-limited reconcile sweep and, on every cluster including push-reported ones, by each spoke from its heartbeat response). See [network-requirements.md](https://github.com/hivecommons/hive/blob/v5/src/docs/network-requirements.md). + +`/data/saas/clusters.json` keeps the historical compatibility key `pull_only`. Set `pull_only: true` when the hub cannot reach that cluster's Kubernetes API and the spokes must dial out to the hub instead. Operator-facing surfaces call these clusters **push-reported** because their node stats, dashboard token proofs, and liveness arrive in spoke heartbeats pushed from the cluster. + +A push-reported entry still needs its stable identity (for example `id`, `name`, `domain`, app/forge fields), but it does not need a usable `kubeconfig_path` for hub-side reads. If node stats are absent, upgrade the spokes to a build that sends heartbeat cluster health and then check the error reason shown in the Clusters panel. + +Each spoke must also know its hub registry cluster ID. Hosted provisioning writes +both `hub.cluster_id` and `HIVE_CLUSTER_ID`; manual or older hosted manifests +must set one of them to the cluster entry ID (for example `vllm-d`). Without +that identity, the heartbeat still proves liveness but deliberately omits +`cluster_health`, because the spoke cannot know which cluster row it is +authoritative for. + +Heartbeat node health needs read-only cluster-scoped RBAC for: + +- core `nodes` `get,list` (capacity, allocatable, readiness, GPU labels) +- `metrics.k8s.io` `nodes` `list` (live CPU/memory usage from metrics-server) + +Do not grant `nodes/proxy` to a tenant ServiceAccount: it reaches every kubelet's `/exec`, `/attach` and `/pods` endpoints through the API server. The spoke's kubelet `stats/summary` disk-usage read is best-effort; without it the Node card shows disk capacity but no live usage percentage. + +When `metrics.k8s.io` is unavailable or forbidden, spokes still report node count, vCPU, memory and disk capacity from the core Node API. The hub marks only the live-usage data partial and carries the precise `node_health_error` reason, such as `metrics API failed: ... HTTP 403` or a missing metrics API, instead of the generic "check RBAC and metrics-server" note. + +Tenant roles deliberately omit `nodes/proxy` (which permits cross-tenant kubelet exec) and cluster-wide `pods list` (which exposes other tenants' pod specs). Push-reported tenant health therefore has no live disk percentage, pod/hive counts or request-based remaining hive capacity; the collector reports partial health (`pods API failed: ... HTTP 403`) while retaining node capacity and available CPU/memory metrics. Do not restore those grants to suppress the partial-health warning. + +On hub startup and every 15 minutes, the SHA poller narrows existing registered tenants' `hive-node-health-reader-*` roles on kubectl-reachable clusters. It does not restart pods, create missing roles, or touch shared operator roles. Failed reads/patches are logged and retried. For push-reported clusters the hub cannot perform this migration: a cluster administrator must replace each existing tenant role's rules with the safe node/NodeMetrics rules in [Manual provisioning](/docs/hive/manual-provisioning). Apply the same correction to orphaned roles no longer represented in the hub registry. Deploy the hub fix as well as the provisioning template fix; upgrading tenant pods alone does not revoke previously issued RBAC grants. + +## API surface to know + +The hub registers heartbeat, registry, SaaS, contributor, OAuth, webhook, backup, and callback-related routes from the Go hub packages. Operators normally interact through the dashboard, but the important external contracts are: + +- `POST /api/heartbeat` — spoke heartbeat, bearer-authenticated by `HIVE_HUB_SECRET` when configured. +- `POST /api/saas/hives` — hub-admin SaaS hive creation path. +- `/api/saas/auth-check` — ingress auth check used by hub-proxied spoke dashboards. +- `/contribute` and `/api/contribute/*` — contributor relay registration and WebSocket flow. +- `/api/registry` and leaderboard/fleet views — public or authenticated hub registry views. + +See `api-reference.md` and the dashboard OpenAPI file for route details, and `manual-provisioning.md` for known failure modes. + +### Search engine indexing + +Only the hub's public landing pages (`/`, `/learn`, `/get-started`, `/reading`, `/contribute`) are meant to be indexed; everything else is an API, an auth gate, or an operator console, and a crawler walking it just collects 401/403s (the "Blocked due to unauthorized request" errors in Google Search Console). The hub enforces that in three layers, all in `src/pkg/hub/robots.go`: + +- `GET /robots.txt` is generated per request host. On the configured public host (`HIVE_HUB_PUBLIC_URL`, default `hive.hivecommons.dev`, plus `localhost`) it allows `/` and emits one `Disallow:` line per gated route group (`/api/`, `/metrics`, `/openapi.json`, `/login`, `/logout`, `/auth/`, `/oauth`, `/openrouter/`, `/dashboard`, `/access-denied`, `/error/`, `/fleet`, `/my-hives`, `/gh-setup`, `/ws`, `/static/`) followed by the `Sitemap:` pointer; `sitemap.xml` lists public pages only. On any other host — a hosted tenant, an internal Service name, a preview hostname — it answers `User-agent: *` / `Disallow: /`. A CI test derives the auth-gated routes from the mux registrations and fails if one is not covered by a `Disallow` line. +- Every response under a disallowed group, every 401 or 403, and every redirect into `/login` carries `X-Robots-Tag: noindex, nofollow`; the login pages also carry ``. +- Hosted spoke dashboards (`.hive.hivecommons.dev`) are never indexable: the hub's ingress auth-check lets `/robots.txt` through unauthenticated and the spoke serves `Disallow: /` for it, and every spoke response — including the 401 login page — carries `X-Robots-Tag: noindex, nofollow` (`src/pkg/dashboard/robots.go`). + +Verify from outside with `curl -A Googlebot https://hive.hivecommons.dev/robots.txt` and `curl -sI https://hive.hivecommons.dev/api/hub/stats | grep -i x-robots`. + +## Running several spokes under one hub + +Splitting one large hive into several subject-scoped spokes stops agents competing over unrelated work. It also surfaces things that are fleet-wide in reality but per-hive in the implementation — provider quota, the shared GitHub App rate limit, agent credentials, and repo ownership ([#5691](https://github.com/hivecommons/hive/issues/5691) is the RFC tracking those). + +The first of those the hub now checks for you is **repo ownership**. + +### Repo-ownership overlap + +Two spokes managing the same repo puts two fleets on one backlog, opening competing PRs on it — the exact thing a split exists to prevent. Nothing stopped that, even though the hub receives every spoke's repo list on every heartbeat. + +The hub now compares those lists and reports any repo claimed by more than one spoke: + +- `GET /api/registry` gains a `repoOverlaps` array. It is **omitted entirely** when the fleet is clean, so its presence is the signal: + + ```json + { + "hives": [ ... ], + "repoOverlaps": [ + { + "host": "github.com", + "repo": "tuna-os/docs", + "hives": [ + { "id": "h-hive", "name": "hive" }, + { "id": "h-reef", "name": "reef" } + ] + } + ] + } + ``` + +- A **warning** fleet alert (`repo-overlap`) is raised on *both* hives in the pair, naming the other spoke and the shared repos. Either operator can act, and alerting on only one would read as that hive being at fault rather than the pair being ambiguous. + +Matching is deliberate about what counts as the same repo, because two spokes are configured separately and so are the pair most likely to spell one repo differently: + +| Compared | Rule | +|---|---| +| `docs`, `tuna-os/docs`, `https://github.com/tuna-os/docs.git` | the same repo — bare, owner-qualified and URL forms all resolve to `owner/repo` | +| `Tuna-OS/Docs` vs `tuna-os/docs` | the same repo — GitHub owner/repo names are case-insensitive | +| `acme/ui` on `github.com` vs on `github.ibm.com` | **different** repos — the GitHub host is part of the identity | +| a spoke listing its own primary repo in `repos[]` | one claim, not a conflict with itself | +| a repo with no owner (no `org` recorded) | ignored — inventing an owner would invent conflicts between unrelated repos that share a name | + +This is **read-side only**: it is derived per request from data the registry already holds, adds nothing to the heartbeat protocol, and is not persisted. It reports and does not refuse — an overlap is a warning, not a bar. A repo two subject areas legitimately share (a docs repo is the common case) is real, so the alert is acknowledgeable like any other; whether overlap should ever *block* assignment, and how such a repo would be allowlisted, is still open on the RFC. diff --git a/docs/content/hive/manual-provisioning.md b/docs/content/hive/manual-provisioning.md index 8925b30..ba3b29a 100644 --- a/docs/content/hive/manual-provisioning.md +++ b/docs/content/hive/manual-provisioning.md @@ -2,7 +2,7 @@ # Provisioning a Hosted Hive -This is a **Kubernetes operator runbook**, including a separate standalone path. If you only want a hosted dashboard, use [Hosted Hive Hub onboarding](https://github.com/hivecommons/hive/blob/v5/src/docs/hosted-hub.md): request a hive and wait for an administrator to provision it. You do not need cluster credentials. +This is a **Kubernetes operator runbook**, including a separate standalone path. If you only want a hosted dashboard, use [Hosted Hive Hub onboarding](/docs/hive/hosted-hub): request a hive and wait for an administrator to provision it. You do not need cluster credentials. ## Choose one provisioning task diff --git a/docs/content/hive/operator-reference/sweeps-and-operations.md b/docs/content/hive/operator-reference/sweeps-and-operations.md index 9dff32f..8417c66 100644 --- a/docs/content/hive/operator-reference/sweeps-and-operations.md +++ b/docs/content/hive/operator-reference/sweeps-and-operations.md @@ -911,7 +911,7 @@ level=INFO msg="knowledge: injected 3900 bytes from 7 entries (skipped 3 for cap `injected_bytes` / `entries` are the rendered `# Relevant Knowledge` block; `skipped_for_cap` counts relevant facts dropped whole because they did not fit `knowledge.primer.max_bytes` (`cap_bytes`); `agents_md_bytes` and `skills_bytes` are the repository `AGENTS.md` block and the requested-skills block that share the kick. A zero line (`primed=true`, 0 entries) means priming ran and found nothing relevant — the signal that the store lacks entries for that lane's work. The line is not emitted when knowledge is disabled or there was nothing to prime, so a hive without a knowledge store does not log a zero on every kick. Read it against `src/docs/knowledge-entries.md` when deciding whether a fact belongs in `AGENTS.md` (paid on every kick) or in a scoped entry (paid only when it matches). -**Maintainer notes in the kick.** When a maintainer has left [notes](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard.md#maintainer-notes) on an item the kick lists, the scheduler appends one `# Maintainer notes` section — a `## owner/repo#N` block per noted item, newest note first, each capped at 1 KiB with "… and N more note(s) on the dashboard" when the rest did not fit. The notes come from the spoke's `/data/maintainer-notes.jsonl`, never from GitHub, and the section is omitted entirely when no listed item has any, so an unused feature costs no bytes. +**Maintainer notes in the kick.** When a maintainer has left [notes](/docs/hive/dashboard#maintainer-notes) on an item the kick lists, the scheduler appends one `# Maintainer notes` section — a `## owner/repo#N` block per noted item, newest note first, each capped at 1 KiB with "… and N more note(s) on the dashboard" when the rest did not fit. The notes come from the spoke's `/data/maintainer-notes.jsonl`, never from GitHub, and the section is omitted entirely when no listed item has any, so an unused feature costs no bytes. ### What consumes tokens while agents are paused diff --git a/docs/content/hive/readme.md b/docs/content/hive/readme.md index c5d9110..8797067 100644 --- a/docs/content/hive/readme.md +++ b/docs/content/hive/readme.md @@ -14,7 +14,7 @@ Choose how to obtain a running hive **before** configuring its agents: | Your situation | Start here | Expected result | |---|---|---| -| You want a hosted hive, without running a cluster | [Hosted onboarding](https://github.com/hivecommons/hive/blob/v5/src/docs/hosted-hub.md); request at [hive.hivecommons.dev/get-started](https://hive.hivecommons.dev/get-started) | After admin approval and provisioning, **My Hives** links to your dashboard. | +| You want a hosted hive, without running a cluster | [Hosted onboarding](/docs/hive/hosted-hub); request at [hive.hivecommons.dev/get-started](https://hive.hivecommons.dev/get-started) | After admin approval and provisioning, **My Hives** links to your dashboard. | | You want to run one hive yourself | [Docker Compose](https://github.com/hivecommons/hive/blob/v5/src/docs/quickstart-docker-compose.md), [Podman](https://github.com/hivecommons/hive/blob/v5/src/docs/quickstart-podman.md), or [Kubernetes](https://github.com/hivecommons/hive/blob/v5/src/docs/kubernetes-deployment.md) | Your own running container and dashboard, with storage and authentication configured. To list it on a hub afterwards, see [Register a self-hosted hive](/docs/hive/register-self-hosted-hive). | | Someone has already given you dashboard access | [Getting started](/docs/hive/getting-started#step-0--before-you-start-do-this-first) | Connect the GitHub App, authenticate a model backend, set a budget, then enable agents conservatively. | @@ -26,7 +26,7 @@ the chosen runtime, deployment privileges, and repository credentials; the Compose guide supports a PAT as well as an App. An agent separately needs its supported backend login, subscription, or model-gateway credentials. -Once you can open a dashboard, follow [Getting started](/docs/hive/getting-started) for the first session and its success checks. Operating a fleet is a separate task: see [self-hosted hub deployment](https://github.com/hivecommons/hive/blob/v5/src/docs/hub-deployment.md). +Once you can open a dashboard, follow [Getting started](/docs/hive/getting-started) for the first session and its success checks. Operating a fleet is a separate task: see [self-hosted hub deployment](/docs/hive/hub-deployment). ## How Hive is organized @@ -42,7 +42,7 @@ A terminal agent is a power tool: you hold it, aim it, and it stops when you sto - **[Agents](/docs/hive/agent-configuration):** AI workers assigned a job, model, schedule (cadence), and permissions. - **[Governor](/docs/hive/architecture#3-the-governor-loop--from-queue-depth-to-a-kick):** the scheduler that checks for work and sends an agent a task (a kick). - **[ACMM levels](/docs/hive/acmm-policy-matrix):** the **AI Codebase Maturity Model** — six levels that map how mature a codebase's tests, reviews and security posture are to what agents may observe, propose, open, review, or merge ([paper](https://arxiv.org/abs/2604.09388)). -- **[Hub](https://github.com/hivecommons/hive/blob/v5/src/docs/hosted-hub.md):** the service that registers hives, receives their periodic status reports (heartbeats), and shows the fleet. +- **[Hub](/docs/hive/hosted-hub):** the service that registers hives, receives their periodic status reports (heartbeats), and shows the fleet. - **[Contributors and ClankeR relay](/docs/hive/contributor-relay):** a way for trusted contributors to donate compute and run delegated work with permissions checked by the hub. ## How it works @@ -63,14 +63,14 @@ A terminal agent is a power tool: you hold it, aim it, and it stops when you sto - [Dashboard sections explained](/docs/hive/dashboard-sections) — what each dashboard section shows and what to do about it. - [Activity monitor copy inventory](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard-copy-inventory.md) — every operator-visible string builder in the activity monitor, with before/after word counts and the hover budget. - [Hive on your iPhone Home Screen](https://github.com/hivecommons/hive/blob/v5/src/docs/ios-widget.md) — a Home Screen widget with issue/PR counts and sparklines (Scriptable, no server change). -- [Dashboard settings explained](https://github.com/hivecommons/hive/blob/v5/src/docs/settings.md) — what each Settings tab controls and where each setting is documented. +- [Dashboard settings explained](/docs/hive/settings) — what each Settings tab controls and where each setting is documented. - [Maintainer commands](https://github.com/hivecommons/hive/blob/v5/src/docs/maintainer-commands.md) — slash commands for un-parking issues, requesting help, confirming fixes, reopening issues, and using label or assignment helpers. - [Release channels](/docs/hive/release-channels) — what `stable`, `candidate`, and `edge` each mean and what to expect from them. - [Security model](/docs/hive/security-model) — agent safety control inventory, threats, enforcement modes, residual gaps and operator audit checklist. - [Hive trust levels vs Copilot assisted permissions](/docs/hive/copilot-permissions-comparison) — what GitHub's per-action permission mode (GA 2026-10-26) does, what Hive's levels, lanes, proxy and gates do, and where each covers ground the other does not. -- [Data collection and telemetry](https://github.com/hivecommons/hive/blob/v5/src/docs/telemetry.md) +- [Data collection and telemetry](/docs/hive/telemetry) - [Monitoring a hive with Prometheus and Grafana](https://github.com/hivecommons/hive/blob/v5/src/docs/monitoring.md) - [Securing your hive: a first-time operator's guide](/docs/hive/securing-your-hive) - [Community and support](https://github.com/hivecommons/hive/blob/v5/src/docs/community.md) diff --git a/docs/content/hive/register-self-hosted-hive.md b/docs/content/hive/register-self-hosted-hive.md index c2a2099..38f2d95 100644 --- a/docs/content/hive/register-self-hosted-hive.md +++ b/docs/content/hive/register-self-hosted-hive.md @@ -2,7 +2,7 @@ # Register a self-hosted hive on a hub -This page is for people who run their own hive and want it listed on a hub such as hive.hivecommons.dev. It mirrors the **Self-host** card on the hub's `/get-started` page. Operators who run a hub and want to enable or audit this flow should read [hub-deployment.md](https://github.com/hivecommons/hive/blob/v5/src/docs/hub-deployment.md#self-service-registration) instead. +This page is for people who run their own hive and want it listed on a hub such as hive.hivecommons.dev. It mirrors the **Self-host** card on the hub's `/get-started` page. Operators who run a hub and want to enable or audit this flow should read [hub-deployment.md](/docs/hive/hub-deployment#self-service-registration) instead. A self-hosted hive is complete on its own. Listing it on a hub is optional and gives you a public entry in Active Hives, an online badge, and a place in the fleet views. The hub lists your hive as directory metadata only. It never sends your hive credentials, upgrades or management actions, and you never receive the hub's master secret. diff --git a/docs/content/hive/roadmap.md b/docs/content/hive/roadmap.md index 845f9a1..9e43c4b 100644 --- a/docs/content/hive/roadmap.md +++ b/docs/content/hive/roadmap.md @@ -32,7 +32,7 @@ the historical item dates below are not a fresh audit of every linked issue. | Long-running work | Foundations available; integration work | Track stages and verified results, including work that never opens a PR. | [#8290](https://github.com/hivecommons/hive/issues/8290) | | Multi-spoke operation | Accepted direction; foundations available | See overlapping repository claims, shared capacity, and provider limits. | [#5691](https://github.com/hivecommons/hive/issues/5691) | | Backend capacity and placement | Accepted direction | Make scheduling respect model availability, quota, and policy. | [#5698](https://github.com/hivecommons/hive/issues/5698) | -| Hosted onboarding | Available service; improvements continue | Try Hive without operating a cluster, subject to approval and capacity. | [Hosted onboarding](https://github.com/hivecommons/hive/blob/v5/src/docs/hosted-hub.md) | +| Hosted onboarding | Available service; improvements continue | Try Hive without operating a cluster, subject to approval and capacity. | [Hosted onboarding](/docs/hive/hosted-hub) | | Retrospective learning | Deterministic foundation; further work | Learn from completed tasks through reviewable findings and knowledge. | [Retro lane](https://github.com/hivecommons/hive/blob/v5/src/docs/retro-lane.md) | | Large-spoke reliability | Fixes and reference available; measurement continues | Handle a growing backlog without hiding or stranding the work. | [Scale envelope](https://github.com/hivecommons/hive/blob/v5/src/docs/scale-envelope.md) | @@ -107,7 +107,7 @@ and linked current guides for operator decisions. | Spoke-based lite enrollment | Keep `hivectl enroll OWNER/REPO` as a zero-secret on-ramp by adding repos to an existing spoke or provisioning a hosted lite spoke; the hub tracks only spokes. | [#2808](https://github.com/hivecommons/hive/issues/2808), [lite enrollment](https://github.com/hivecommons/hive/blob/v5/src/docs/lite-enrollment.md) | | Multi-spoke constellation foundations | Accepted for v5 phase 1 after production evidence from tunaos.org (self-hosted hub, two ACMM L5/L6 spokes, 43 repos). The first slice, repo-claim overlap detection, shipped in #5705; remaining slices add spoke charters, fleet headroom, GitHub App budget visibility, shared-credential guidance, and route recommendations without turning the hub into a hard control plane. | [#5691](https://github.com/hivecommons/hive/issues/5691), [RFC #5691](https://github.com/hivecommons/hive/blob/v5/docs/rfc-5691-constellation.md), [#5705](https://github.com/hivecommons/hive/pull/5705), [#5796](https://github.com/hivecommons/hive/pull/5796) | | Backend capacity, model inventory, and placement | Accepted for v5 phase 1 because multi-spoke fleets are constrained by shared provider quota, model availability, and policy, not only by repo ownership. The work standardizes capacity readings, inventory authority, tier floors, scoped limits, and opt-in placement / pacing before scheduler behaviour depends on them. | [#5698](https://github.com/hivecommons/hive/issues/5698), [RFC #5698](https://github.com/hivecommons/hive/blob/v5/docs/rfc-5698-backend-capacity-model-inventory-placement.md), [#5784](https://github.com/hivecommons/hive/pull/5784) | -| Hosted Hive Hub positioning | Anchor the hosted hub (hive.hivecommons.dev) as the evaluation-grade, best-effort on-ramp: OAuth/OIDC accounts, admin-granted hosted quota, per-user and per-cluster capacity controls, `/data/saas` records, bounded usage/timeline history, hosted-vs-self-hosted guidance, and early exercise of the v5 constellation/capacity workstreams. | [#6017](https://github.com/hivecommons/hive/issues/6017), [ROADMAP.md](https://github.com/hivecommons/hive/blob/v5/ROADMAP.md#hosted-hive-hub), [hosted-hub](https://github.com/hivecommons/hive/blob/v5/src/docs/hosted-hub.md) | +| Hosted Hive Hub positioning | Anchor the hosted hub (hive.hivecommons.dev) as the evaluation-grade, best-effort on-ramp: OAuth/OIDC accounts, admin-granted hosted quota, per-user and per-cluster capacity controls, `/data/saas` records, bounded usage/timeline history, hosted-vs-self-hosted guidance, and early exercise of the v5 constellation/capacity workstreams. | [#6017](https://github.com/hivecommons/hive/issues/6017), [ROADMAP.md](https://github.com/hivecommons/hive/blob/v5/ROADMAP.md#hosted-hive-hub), [hosted-hub](/docs/hive/hosted-hub) | | Retrospective learning lane | Build from deterministic post-completion advisory beads toward LLM-assisted retro summaries and knowledge extraction. | [#2809](https://github.com/hivecommons/hive/issues/2809), [retro lane](https://github.com/hivecommons/hive/blob/v5/src/docs/retro-lane.md) | | Large-spoke scale envelope | State how a **single** spoke behaves as its backlog grows, rather than discovering it one bug at a time. The [scale envelope](https://github.com/hivecommons/hive/blob/v5/src/docs/scale-envelope.md) page now records the design rule (overflow must paginate, prioritize, or shed load — never fail closed on the work that would drain the backlog), the fact that caps are render-side while issue/PR enumeration is uncapped, and an inventory of every cap with its overflow behaviour and tunability. Evidence base: the 2026-09-17 projectbluefin cluster (~304 open PRs across 16 repos) — uncapped kick PR list (#7368, fixed by #7379/#7395), restart/kick loop on a long delivery (#7363, fixed by #7378), stand-down on render-cap overflow (#7385, scoped per repo by #7391), fork-unaware repair queue (#7386). Remaining: decide one policy for which caps are operator-tunable vs hardcoded-and-narrowly-scoped, and measure enumeration cost against API rate limits at this shape. | [#7392](https://github.com/hivecommons/hive/issues/7392), [scale envelope](https://github.com/hivecommons/hive/blob/v5/src/docs/scale-envelope.md), [#7385](https://github.com/hivecommons/hive/issues/7385) | | ADR back-fill for remaining subsystems | **Done.** Back-filled accepted ADRs capture the knowledge system, skill registry, CEL/channel triggers, and hub/spoke mechanics, so architecture decisions stay auditable. | [ADR-0011](/docs/hive/adr/0011-knowledge-system), [ADR-0012](/docs/hive/adr/0012-skill-registry), [ADR-0013](/docs/hive/adr/0013-cel-triggers), [ADR-0014](/docs/hive/adr/0014-hub-spoke) | diff --git a/docs/content/hive/settings.md b/docs/content/hive/settings.md new file mode 100644 index 0000000..8729dba --- /dev/null +++ b/docs/content/hive/settings.md @@ -0,0 +1,145 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/settings.md) during the docs build. Edit the canonical source in the Hive repository. + +# Dashboard settings explained + +This page is the starting point for the dashboard's **Settings** tabs. It has one entry per tab: what the tab controls and which page explains it in depth. + +Every setting on a Settings tab has a small **?** mark next to its name. Rest the pointer on it, or move to it with the Tab key, to see a short explanation of the setting. Click it, tap it, or press Enter on it to open the page that explains the setting in a new tab. When a setting has its own guide, the mark opens that guide; otherwise it opens this page at the tab's entry. Clicking a mark never changes the setting. + +For the dashboard's other sections, see [Dashboard sections explained](/docs/hive/dashboard-sections). If a key has no editable control, see [Editing `hive.yaml`](https://github.com/hivecommons/hive/blob/v5/src/docs/editing-hive-yaml.md) for file locations and reload behavior. + +## Linking to a setting + +`/#config/governor/` opens Settings on a tab. Add a search term as a third part, `/#config/governor//`, and Settings opens with the search box already holding ``, so the results list the matching settings. For example, `#config/governor/Features/issues.close_on_merge` opens Settings searching for that key. + +### Triage: does this RFC already exist? + +Many RFCs ask for something a setting already does. With `issues.rfc_existing_check.enabled: true` (default off), Hive checks each new open issue labelled `rfc`, `enhancement` or `kind/feature` against the Settings search index. It compares the issue title and body with each indexed setting's key, label, section and search text by keyword overlap. There is no model call. Hive then posts one comment carrying ``. The comment lists the best matches. Each match links to Settings with the search set to its key (the link above, built from `dashboard.public_url`) and to a docs search for the key. Hive finds the marker before posting, so it never comments twice, including after a restart. The check only comments: it never adds labels, closes issues, or decides anything. + +| Key | Default | Meaning | +|---|---|---| +| `issues.rfc_existing_check.enabled` | `false` | Turn the check on. | +| `issues.rfc_existing_check.post_when_nothing_found` | `false` | Also post a one-time "Nothing found" comment when no setting matches. | +| `issues.rfc_existing_check.labels` | `[rfc, enhancement, kind/feature]` | Labels that mark an issue as an RFC or feature request. Matching ignores case. | +| `issues.rfc_existing_check.max_matches` | `5` | Most settings listed in one comment. | +| `issues.rfc_existing_check.max_age` | `168h` | Skip issues opened longer ago than this, so turning the check on does not comment on the backlog. | + +These keys are set in `hive.yaml` only; they have no Settings control yet. + +## General + +Hive-wide basics: the hive ID, the ACMM maturity level, how often the governor evaluates the hive, the fleet-wide default for explain mode, and whether agent-created PRs and issues carry an attribution trailer. The **Eval loop pacing** block sets the eval-interval cap, the webhook-healthy interval, the conserve-mode multiplier, how often optional sweeps run and the provider spend-limit probe interval; a saved change applies from the next eval cycle. It also shows, read-only, whether the mode thresholds are pack-seeded or operator-owned. + +- ACMM levels and the agents each level runs: [ACMM levels](/docs/hive/agent-configuration#acmm-levels-agent-rosters-as-packs). +- Explain mode: [Explain mode](/docs/hive/agent-configuration#explain-mode-debugging-agent-behaviour). +- Every configuration block and notable field: [Hive operator reference](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md#configuration-blocks). + +## Thresholds + +The issue and PR counts that move the governor between modes, and how those thresholds scale as the hive manages more repos. See [Governor mode thresholds](https://github.com/hivecommons/hive/blob/v5/src/docs/governor-thresholds.md). + +## Labels + +Which labels hold, require, or route work, the label the merger queue applies to queue a PR for auto-merge (applies after a restart), and the reporter-trust rules for outside PRs. See [Labels and control signals](/docs/hive/labels-and-control-signals) and [Label policy](/docs/hive/agent-configuration#label-policy-which-issues-agents-may-work). + +## Repos + +The repos the hive manages and the caps on how many issues and PRs are listed in one kick (`governor.kick_limits`). See the `governor.kick_limits` row of the [notable fields](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md#notable-fields). + +The same tab has a **Parent auto-close** card (owner only, `repos..parent_autoclose`): per monitored repo, choose "Close finished parents (default)", "Also close epics and holds", "Also close trackers whose work is done" or "Never auto-close parents". It shows the effective value for each repo, applies on save without a restart, and is audited. A parent a person reopened is never re-closed, and issues marked as tracking issues are never auto-closed. See [stage-labels](/docs/hive/labels-and-control-signals/stage-labels#decomposed-parents--closed-by-their-children-never-stalled). + +## Budget + +The token budget and its rolling period, optional dollar and coin caps, the percentage at which the governor enters budget-critical mode, per-agent exemptions, and the model lock that stops automatic model downgrades. See [Governor cadence and budget](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md#governor-cadence-and-budget) and [Token collection and usage tracking](https://github.com/hivecommons/hive/blob/v5/src/docs/token-tracking.md). + +## Notifications + +The ntfy, Discord, and Slack destinations and which hive events are sent to them. See [Notifications](https://github.com/hivecommons/hive/blob/v5/src/docs/notifications.md#configuration). + +## Health + +The escalation breaker, which hands an agent's work to a human after a set number of consecutive red attempts, and the agent self-healing watchdog. See [Agent Self-Healing Watchdog](https://github.com/hivecommons/hive/blob/v5/src/docs/agent-watchdog.md#configuration). + +## Sensing + +How long a rate-limit alert stays active and how long an agent is paused after a rate limit is detected. + +## Logging + +Where rolling log files are written, when they rotate, how long rotated files are kept, the log level, and whether rotated files are compressed. The log directory is read-only at runtime; change it in `hive.yaml`. + +## Security and Access + +Input/output scanning, the agent sandbox runner, and suspicious-activity alerts. See [ioscan](https://github.com/hivecommons/hive/blob/v5/src/docs/ioscan.md), [Credential-free sandbox isolation](https://github.com/hivecommons/hive/blob/v5/src/docs/sandbox-isolation.md), [Suspicious-activity alerts](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md#suspicious-activity-alerts-sentinel), and the [Security Model](/docs/hive/security-model). + +## Features + +Optional capabilities, each off or inert until you turn it on. Where a feature has its own guide, its **?** mark opens that guide: + +- Retro loop: [Retro lane](https://github.com/hivecommons/hive/blob/v5/src/docs/retro-lane.md). +- Formal verification: [Formal verification](https://github.com/hivecommons/hive/blob/v5/src/docs/formal-verification.md). +- Audit publication: [Audit campaign](https://github.com/hivecommons/hive/blob/v5/src/docs/audit-campaign.md#publication). +- Token mint: [Token mint](https://github.com/hivecommons/hive/blob/v5/src/docs/token-mint.md). +- Spek stage runner: [Spektacular](/docs/hive/integrations/spektacular). +- Auto-merge: [App self-merge sweep](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md#app-self-merge-sweep-auto_merge), [Trusted bot authors](https://github.com/hivecommons/hive/blob/v5/src/docs/hive-merge.md#trusted-bot-authors), and [Trusted-author auto-merge](https://github.com/hivecommons/hive/blob/v5/src/docs/hive-merge.md#trusted-author-auto-merge). +- Review gate: [Review swarm](https://github.com/hivecommons/hive/blob/v5/src/docs/review-swarm.md#configuration), [Blocking line and backlog](https://github.com/hivecommons/hive/blob/v5/src/docs/review-swarm.md#blocking-line-reviewseverity-reviewbacklog), and [external review bot threads](https://github.com/hivecommons/hive/blob/v5/src/docs/review-bot-threads.md). +- Trajectory review: [Trajectory-Review Lane](https://github.com/hivecommons/hive/blob/v5/src/docs/trajectory-review.md#configuration). +- Linear agent: [Linear agent integration](https://github.com/hivecommons/hive/blob/v5/src/docs/linear-agent.md). +- Upstream watch: [Upstream watch](https://github.com/hivecommons/hive/blob/v5/src/docs/upstream-watch.md#configuration). + +The other features on this tab (OpenTelemetry export, external execution, auto-plan, issue claims, PR follow-up, long-running runs, provider rotation, merge recommendations, convergence rollout, stall replan, and question auto-close) are explained by their **?** tooltips, and their configuration keys are listed in the [Hive operator reference](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md#configuration-blocks). + +## Knowledge + +Whether the public read-only knowledge MCP endpoint is on, the knowledge pipeline, and the external knowledge connectors. The **Knowledge pipeline** block opens with the **Mid-task advisor for sidecar runtimes** switch (`knowledge.sidecar_advise`, off by default, applies at once, needs `knowledge.advisor` set in `hive.yaml`; see [Sidecar runtimes](/docs/hive/agent-knowledge-and-memory#sidecar-runtimes-knowledgesidecar_advise)), then sets the bead synthesizer (schedule, target layer, minimum confidence, per-cycle fact and GitHub API caps, bead retention), scheduled curator promotion (schedule, threshold, source and target layers), repository code maps (schedule, layer, size cap) and the kick primer's fact and byte caps. Turning the bead synthesizer on or off applies at once; the other pipeline settings apply after a restart, and 0 or empty restores the default. The engine, the vault paths and the primer merge strategy are shown read-only because they are set in `hive.yaml`. The repositories to map and the primer priority list stay yaml-only. See [Knowledge curator](https://github.com/hivecommons/hive/blob/v5/src/docs/knowledge-curator.md) and [Knowledge connectors](https://github.com/hivecommons/hive/blob/v5/src/docs/knowledge-connectors.md). + +## Meeting attendee + +The persona hive attends meetings as (Betty by default): pick a preset or edit its name, display name, aliases, pronouns, voice type, language, accent, Kokoro voice, humor and intro (with a live preview and a **Play sample** button; clicking a preset card also plays that persona's introduction in its own voice, see [Hearing a preset](/docs/hive/meetings#hearing-a-preset)), set how often she answers room questions unprompted, and see the address people invite her with. Owner or read-write. Changes apply after a restart. See [Meeting attendee settings](/docs/hive/meetings#meeting-attendee-settings). + +## Advisory + +How many advisory findings are shown, how often they refresh, and when a finding counts as stale. See [Advisory](https://github.com/hivecommons/hive/blob/v5/src/docs/advisory.md) and [Advisory staleness](https://github.com/hivecommons/hive/blob/v5/src/docs/advisory-staleness.md). + +## Work Source + +Where Hive reads its work from (GitHub Issues, GitHub Projects, Linear, or Jira) and each source's credentials and filters. See [Work sources](/docs/hive/work-sources). + +## Hub + +The link between this hive and its hub: hub registration, public listing, heartbeat identifiers, automatic updates, public snapshots, and the contributor queue that relays draw work from. + +- Hub registration: [Registering spokes to your hub](/docs/hive/hub-deployment#registering-spokes-to-your-hub). +- Heartbeat identifiers: [Withholding heartbeat identifiers](/docs/hive/telemetry#withholding-heartbeat-identifiers). +- Snapshots: [Public snapshots](https://github.com/hivecommons/hive/blob/v5/src/docs/snapshots.md). +- Contributors: [ClankeR contributor relay](/docs/hive/contributor-relay) and [Contributor trust tiers and delegated agent roles](https://github.com/hivecommons/hive/blob/v5/src/docs/contributor-trust-and-roles.md). + +The **Hub settings** block at the bottom of the tab sets explicit task acceptance, the already-done label and hold, contributor wall retention, the contributor announcement (text, level, expiry), the snapshot rebuild interval, the self-upgrade drain timeout, the task-status push loop and the NPS prompt. They save with the rest of the tab; 0 or empty restores the default. The upgrade drain timeout and task-status push apply after a restart. While a self-upgrade is draining, the spoke reports the kicks it is waiting on and the time left in every heartbeat, so the hub holds the upgrade instead of abandoning it as orphaned; the hub timeline and stuck-upgrade alert show the drain. The cluster ID and hive type are shown read-only because hub provisioning writes them, as are the deprecated `contribute_already_done_unverified_hold_days` and `contribute_close_already_done` keys and the announcement ID the dashboard mints. The hub-only provision-request Discord webhook and NPS relay pull secret are write-only: the tab shows only whether each is set. + +## Model Gateways + +The OpenAI-compatible gateways (LiteLLM, OpenRouter, vLLM, and others) agents send inference through, and their keys. See [Configure model gateways and keys](/docs/hive/hosted-hub#configure-model-gateways-and-keys). + +## Dashboard + +Settings for the dashboard itself (`dashboard.*`): its port and agent poll interval, the Experiment Lab, whether the header also shows the usage gauge, hub-proxied auth, Sessions, the dashboard auth token, the access allowlist, and the issue bands. + +**Inception (spek) sessions** (`dashboard.sessions.enabled`, on by default) turns on the [Inception (spek)](/docs/hive/dashboard-sections#inception-spek) section, named shared CLI-agent terminals inside the dashboard that open in the hive's shared spek workspace, which replaced the removed Inception wizard. Set it to false to hide the section. The `HIVE_SESSIONS_ENABLED` environment variable, when set, overrides the switch, and the dialog says so. Beside it are the three limits, `dashboard.sessions.max_sessions`, `dashboard.sessions.max_per_user` and `dashboard.sessions.idle_ttl_hours`; 0 keeps the built-in default (12, 4 and 72), and `HIVE_SESSIONS_MAX`, `HIVE_SESSIONS_MAX_PER_USER` and `HIVE_SESSIONS_IDLE_TTL_HOURS` override them. **Answer the CLI startup screens** (`dashboard.sessions.autostart`, on by default) lets the hive take a starting session's CLI through its startup screens (first-run notice, trust for the session's folder, onboarding) to its input prompt, so the first request runs without a person; it never answers a permission prompt and never signs in, and `HIVE_SESSIONS_AUTOSTART` overrides the switch. See the [Sessions API](/docs/hive/api-reference/sessions). + +**Also show the usage gauge in the header** (`dashboard.subscription_gauge_header`, off by default) adds a small fuel-dial chip to the header on every page, showing how much is left in the limit closest to running out across the plans the hive's agents spend (Claude, Copilot and others). The full gauge, with a row per provider, is on the Overview by default for the owner and can be hidden there from the Overview settings. Both show the measurements hive already makes; only the owner sees them; and they show the providers' plans, not the hive's token budget. See [Usage gauge](/docs/hive/dashboard#usage-gauge). + +## Compliance + +How your configuration maps to SOC 2, FedRAMP, and ISO 27001 controls. See [The Settings → Compliance tab](https://github.com/hivecommons/hive/blob/v5/src/docs/compliance.md#the-settings--compliance-tab). + +## Agent: General + +One agent's identity, engine, model, and behaviour: name, role, kick template, operating mode, sandbox, CLI pin, caveman, Jev, and explain modes, and the repos and keywords it works on. See [Agent Configuration](/docs/hive/agent-configuration#anatomy-of-an-agent). + +## Agent: Pipeline + +The deterministic pre-kick pipeline stages that run for this agent before the model is invoked. Turn a stage off to skip it for this agent. Each stage's **?** tooltip explains the stage. See [Agent Configuration](/docs/hive/agent-configuration). + +## Agent: Hooks + +Shell scripts the agent runs before each governor kick (pre-kick) and after it finishes and returns to idle (post-idle). Pre-kick scripts run in order. These per-agent scripts are separate from the hive-wide [state-triggered hooks](https://github.com/hivecommons/hive/blob/v5/src/docs/hooks.md). diff --git a/docs/content/hive/telemetry.md b/docs/content/hive/telemetry.md new file mode 100644 index 0000000..d3fe56d --- /dev/null +++ b/docs/content/hive/telemetry.md @@ -0,0 +1,161 @@ +> **Synced from Hive.** This page is pulled from [hivecommons/hive@v5](https://github.com/hivecommons/hive/blob/v5/src/docs/telemetry.md) during the docs build. Edit the canonical source in the Hive repository. + +# Data collection and telemetry + +Hive sends a small number of operational signals outside the running hive only through the paths below. This page documents what is collected, where it goes, who can read it, retention where the code defines it, and how an operator can disable each path. The Linux Foundation telemetry policy says project software should not collect telemetry by default without LF legal review and prior user consent; Hive therefore treats any phone-home style path as a review item before changing defaults. + +## Summary + +| Path | What leaves the hive/browser | Destination and visibility | Default / consent | Retention | Disable path | Code references | +|---|---|---|---|---|---|---| +| Hub heartbeat | Hive ID; org/repos/primary repo; configured AI author; GitHub API/base host; ACMM level; agent names, state, backend/model counts; governor mode and queue counts; process/version/image/uptime; dashboard URL/snapshot URL/public flag/cluster ID; health summaries; token/budget counters; contributor counts, leaderboard usernames/avatar URLs/task counts/current task; active/engaged dashboard usernames and last-action timestamps; repo activity counts; PR/CVE/fleet counters; advisory/error strings; non-secret GitHub App IDs/slugs/installation IDs/key fingerprints; dashboard-token hash; file-descriptor counts; cluster-health status. No raw GitHub tokens, App private keys, dashboard tokens, session IDs, or heartbeat secrets are sent. | Configured hub at `hub.url` / `HIVE_HUB_URL`; hub UI/API access is hub-admin/operator gated. | Sent every two minutes when the hive is hub-linked. A standalone hive with no hub URL does not heartbeat. Once hub-linked, sensitive identifier classes can be withheld with `hub.heartbeat_omit` (see [Withholding heartbeat identifiers](#withholding-heartbeat-identifiers)); other fields are not configurable. | Hub registry retention is operational state, not currently documented as a fixed expiry. | Remove the hub link (`hub.url` / `HIVE_HUB_URL`) to stop all hub features. `hub.heartbeat_omit` withholds identifier classes per hive; a core-heartbeat disable switch is still pending maintainer direction (tracking issue: [#10202](https://github.com/hivecommons/hive/issues/10202)). | `src/cmd/hive/boot_heartbeat_deps.go`; `src/cmd/hive/main.go` (`bootHeartbeatWith`); `src/pkg/hub/spoke/heartbeat.go` (`HeartbeatPayload`); `src/pkg/hub/hub_keys.go` (`SpokeHeartbeatKey`). | +| Task-status push / contributor relay status | Hive ID, contributor summary, and leaderboard entries: GitHub username, avatar URL, trust tier, tasks completed/failed, active flag, and current task title. | Same configured hub, authenticated with the per-hive heartbeat bearer. | Defaults on when the hive is hub-linked; controlled by `hub.task_status_push` / `HIVE_HUB_TASK_STATUS_PUSH`. | Operational hub state; no fixed expiry documented. | Set `hub.task_status_push: false` or `HIVE_HUB_TASK_STATUS_PUSH=false` and restart; this stops only the separate task-status loop. | `src/cmd/hive/main.go` (`StartTaskStatusPush` collector); `src/pkg/hub/spoke/heartbeat.go` (`TaskStatusPayload`). | +| Dashboard feedback reports | User-entered title/description/screenshots; optional diagnostics if the user keeps **Include diagnostics** checked: version, commit, channel, ACMM level, hive ID, hosted/hub-linked flags, agent count, agent names/backend/model/state, browser user agent/platform/language, screen/window size, dashboard page, plus recent console errors and failed local `/api` calls. Project org/repo is sent only if the user checks **Also include project org/repos**. Tokens, bearer strings, emails, and secret-looking key/value text are redacted before submission. | The diagnostic bundle is committed to the `hive-feedback` branch of `hivecommons/hive` or `hivecommons/docs` with the GitHub App installation token (hub-less: the spoke's; hub-linked: minted by the hub for that spoke). The issue itself is opened by the user from a prefilled `issues/new` URL that links to the bundle; Hive never authors feedback with a user, bot, or operator token, and dashboard login requests no OAuth scope (#1927). | User-initiated only. The modal previews exactly what will be sent; diagnostics can be unchecked; project org/repos require a second opt-in checkbox. | GitHub issue retention follows GitHub/project issue retention. The spoke stores up to 50 local feedback issue references in `/data/feedback-submissions.json`. | Do not submit; uncheck diagnostics/project context; remove screenshots. Operators can also avoid hub relay by not hub-linking. | `src/pkg/dashboard/static/index.html` (`FEEDBACK_DIAGNOSTIC_FIELDS`, preview, checkboxes); `src/pkg/dashboard/feedback.go`. | +| Build-containment lookup | A commit SHA (the hive's running commit and the commit being asked about) or a PR number, sent as part of a GitHub REST `compare` or `pulls` request. Only when an operator runs a lookup (`GET /api/saas/build-contains` on the hub, `GET /api/version/contains` on a hive). No hive identifier, org, repo name or user is in the request. | `api.github.com`, the public `hivecommons/hive` repository, using the hub's read-only GitHub identity or the hive's own configured GitHub client. The answer is shown to the caller only. | On demand only; no background polling. A hive with no GitHub client answers `unknown` and sends nothing. | None stored; compare answers are cached in memory, for the life of the process. | Do not run the lookup; there is no setting because nothing is sent otherwise. | `src/pkg/buildcontains/buildcontains.go`; `src/pkg/hub/build_contains.go`; `src/pkg/dashboard/api_version_contains.go`. | +| NPS prompt | Score 1-4, optional free text, hive ID, and dashboard version. The signed-in username is used only locally for rate limiting and is not sent. | Hub `POST /api/nps/ingest`, or an explicitly configured NPS relay for standalone hives; only hub admins can read stored responses. | Hosted spokes default on; self-hosted/federated/standalone default off. Standalone relay requires explicit `hub.nps_enabled`/`HIVE_NPS_ENABLED` and `hub.nps_relay_url`/`HIVE_NPS_RELAY_URL`. | Hub store keeps at most 1,000 responses per hive and 10,000 total, oldest dropped first. | `hub.nps_enabled: false` or `HIVE_NPS_ENABLED=false`; leave relay URL unset. | `src/docs/nps.md`; `src/docs/env-vars.md`; `src/pkg/dashboard/nps.go`; `src/pkg/hub/nps.go`. | +| Hosted hub web analytics | GA4 page/event data from hub-hosted pages, including custom hub events such as hive creation/deletion. Existing event code includes hive IDs and creation inputs such as org, primary repo, ACMM level, and cluster ID. | Google Analytics via `www.googletagmanager.com`, property `G-4707R797K3`. | Loaded by hosted hub static HTML pages. This is website analytics, not spoke software telemetry, but it still needs privacy review because custom events may include project identifiers. | Google Analytics retention is controlled in the GA property, not in this repository. | Browser tracking protections or removing the hosted hub GA script; there is no repository config flag. | `src/pkg/hub/assets/dashboard.html`; `src/pkg/hub/saas_pages.go`; `src/pkg/hub/static/*.html` pages such as `reading.html` and `cncf-reference-architecture.html`. | +| Crash/error reporting | No Sentry/PostHog/Segment/Plausible crash reporter was found in `src` during the onboarding audit. Errors are logged locally; selected log-safe health/error strings can appear in hub heartbeats as described above. | Local logs and, for selected operational state, the configured hub. | No third-party crash reporting by default. | Local log/PVC retention is deployment-specific. | N/A for third-party crash reporting; disable hub link for heartbeat-carried operational errors. | Audit search: `telemetry|analytics|metrics push|phone.?home|posthog|segment|plausible|gtag|googletagmanager|sentry` over Go/HTML/JS/Markdown. | + +## Linux Foundation telemetry-policy status + +| Policy requirement | Hive status | Gap / follow-up | +|---|---|---| +| Do not collect telemetry by default without Linux Foundation review and approval. | Standalone hives do not heartbeat or send NPS relay data unless configured. Hub-linked/hosted hives always send operational heartbeats to the configured hub. Hosted hub pages load GA4. | Heartbeats and hosted GA4/custom events should be reviewed with CNCF/LF before this onboarding item is marked complete. | +| Specify exactly what is collected. | NPS is documented in `src/docs/nps.md`; feedback diagnostics disclose fields in the UI. This page now documents heartbeats, task-status, feedback, NPS, analytics, and crash reporting. | Keep this page updated when heartbeat or feedback fields change. | +| Demonstrate anonymization and avoid personal/end-user/confidential data. | No raw secrets are intended in the heartbeat; feedback redacts token/email/secret-looking text; NPS intentionally omits user identity. | Heartbeats can include GitHub usernames, org/repo names, dashboard usernames, current task titles, project identifiers, hive IDs, and GA4 custom event identifiers. These are not fully anonymized and may be business-sensitive. | +| Notify users and require consent before collection starts. | Feedback is explicit and previewed; project org/repo diagnostics require a separate checkbox. NPS has an enable switch and documented defaults. | Hub heartbeats are tied to hub-link configuration and are not separately consented or field-configurable; hosted GA4 notice/consent is not documented in this repo. | +| Document storage and project-community access. | NPS retention and admin-only read path are documented. Heartbeat and task-status visibility is hub-side operational/admin UI. | Fixed retention for heartbeat/task-status registry data and GA4 retention are not documented. | +| Secure the collection mechanism. | Heartbeats and task-status use per-hive derived bearer credentials; heartbeat responses are signed; feedback/NPS size caps and redaction are implemented. | Security posture depends on the configured hub and GA4; continue to review any new phone-home path before enabling it by default. | +| Make approved telemetry data available to project participants. | NPS is admin-only by design; hub operational state is hub-admin/operator visible. | If LF approves any project telemetry program, define what aggregate data is shared with the community and where. | + +## Heartbeats are not a crash reporter + +The heartbeat is an operational control-plane link between a spoke and its configured hub. It is used for liveness, health, upgrade/config delivery, hosted-spoke lifecycle, and fleet views. It should not be treated as an anonymous metrics program: the payload contains stable project and hive identifiers and may contain GitHub usernames. Operators that do not want this link should run without `hub.url`/`HIVE_HUB_URL`; Hive does not currently provide a per-field heartbeat opt-out (tracking issue: [#10202](https://github.com/hivecommons/hive/issues/10202)). + +--- + +## Disabling task-status pushes + +The separate task-status loop can be disabled without losing the core heartbeat, liveness, hub-managed upgrade policy, or config delivery: + +```yaml +hub: + task_status_push: false +``` + +Alternatively set `HIVE_HUB_TASK_STATUS_PUSH=false`. The environment variable overrides the config and accepts `1/true/yes/on` and `0/false/no/off` (case-insensitive, ignoring surrounding whitespace). Empty or invalid values fall back to the config. An absent config value defaults to `true`, preserving existing behavior. Restart the hive after changing this setting; it is evaluated at startup, not hot-reloaded. + +This switch stops only the separate `StartTaskStatusPush` loop. The core heartbeat still sends its normal payload, including contributor counts and leaderboard fields. Use `hub.heartbeat_omit` below to withhold sensitive identifier classes from that payload; disabling task-status pushes is not a blanket telemetry opt-out. + +## Withholding heartbeat identifiers + +Set `hub.heartbeat_omit` in `hive.yaml` to a list of classes to strip from every hub heartbeat and task-status push. Hive ID, version/commit, cluster ID and auto-upgrade state are never removed, so upgrade and config delivery keep working. Unknown class names fail config validation. The dashboard **Settings → Hub → Telemetry** section shows which classes are currently withheld (read-only). + +```yaml +hub: + heartbeat_omit: [repos, users, task_titles, dashboard_urls] +``` + +| Class | Withheld fields | Tradeoff when omitted | +|---|---|---| +| `repos` | `repos`, `primary_repo`, `repo_activity`, `repo_target_issue` | Hub cannot list the hive's repositories or per-repo activity, and cannot flag repo-target misconfiguration. | +| `users` | `owner`, `ai_author`, `ai_author_effective`, active/engaged dashboard usernames, per-user last actions, the whole leaderboard (heartbeat and task-status) | Hub loses owner display, the contributor leaderboard and per-user time-in-hive. | +| `task_titles` | Leaderboard `current_task` | Hub leaderboard shows who is active but not what they are working on. | +| `dashboard_urls` | `dashboard_url`, `snapshot_url`, public-URL self-check | Hub cannot link to the hive's dashboard or snapshot, and cannot probe URL reachability. | + +## Activity digest + +`hub.activity` controls the bounded, read-only activity digest the heartbeat carries for the hub-wide Activity Monitor ([#15963](https://github.com/hivecommons/hive/issues/15963), RFC [#15861](https://github.com/hivecommons/hive/issues/15861)). It is built in process from the dashboard's stage tracker: repo, number, kind, title, author kind, stage and modifier pills of open items, plus totals by stage and modifier. + +```yaml +hub: + activity: + enabled: true # default: on for hosted spokes (hub.hive_type: hosted) not withholding repos; off for self-hosted + max_items: 100 # default 100; clamped to the hub's 250-item ceiling + share_private: false # private-repository items are dropped (still counted in totals) unless true +``` + +When the cap applies, items needing a human or a decision are kept first, then stalled ones, then the furthest stage, and the number left out is reported as `truncated`. A repository counts as public only when the hub lists the hive as public (`hub.is_public`, its project repos) or it is on `HIVE_PUBLIC_REPOS`. Once the hub acknowledges a digest's etag, later beats send only `etag` and `generated_at` until the tracker changes. A tracker change also sends an activity-only update over the heartbeat endpoint and bearer, at most one every 15 seconds; changes arriving meanwhile are merged into it. The block also carries `events` ([#15964](https://github.com/hivecommons/hive/issues/15964)): the stage hops, opens and merges the spoke saw since the hub last acknowledged them, derived by diffing successive tracker snapshots (the first one only seeds the baseline), each with a sequence number. At most 200 are buffered; the oldest are dropped first and `events_dropped` discloses how many. Events stay buffered, and are resent, until a heartbeat or update response's `activity_events_ack` covers them. Private-repository items yield no events unless `share_private` is on. The hub keeps at most 1,000 events across the fleet in memory only, and no event is kept longer than 24 hours; when the ring is full it drops the oldest event of the hive holding the most events, so one hive cannot evict another hive's events. `hub.heartbeat_omit` applies: `repos` withholds every item and event (totals remain) and `task_titles` blanks titles. + +## Telemetry agent + +The telemetry agent audits and, once opted in, improves the **observability of the managed project** — the repositories the hive watches, not the hive's own internal metrics/tracing (see [Config.OTel/Tracing](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md) for that, a deliberately separate concern). It is an L5/L6-only agent: absent from the roster below L5 and paused in every governor mode at L5/L6 until an operator explicitly opts in. + +## What the telemetry agent does + +On each kick, telemetry follows its ACMM-level policy template (`telemetry-advisory.md`, `telemetry-holdgated.md`, or `telemetry-full.md`) and: + +- Inspects tracing, metrics, structured logging, scrape targets, dashboards, monitoring custom resources, collector/exporter configuration, and web analytics in the repositories it is authorized to audit (`$HIVE_REPOS`). +- Detects the project's *existing* observability stack before recommending anything, and prefers OpenTelemetry as a vendor-neutral spine — but only acts on a backend an operator has explicitly configured. +- Flags unbounded metric labels, high-cardinality span attributes, missing scrape targets, inconsistent span names, and dashboards that aren't source-controlled. +- Never reveals credentials, endpoints, API keys, or secret values in its output — it refers only to environment-variable or secret names. + +At **advisory** level (ACMM L2–L4, though telemetry does not actually appear in the roster until L5 — see [ACMM level gating](#acmm-level-gating) below), it writes each confirmed finding as an advisory bead owned by `telemetry` and returns an `AgentReport` with `kind: "findings"`. It never creates GitHub issues, branches, commits, or pull requests in this mode. + +At **hold-gated** (L5) and **full** (L6) modes, telemetry runs in `ISSUES_AND_PRS` and, in addition to filing findings, can open bounded, hold-gated pull requests: OpenTelemetry SDK wiring and request-path spans, bounded metrics and `/metrics` endpoints, structured logging, dashboard JSON, alert-rule YAML, `ServiceMonitor`/`PodMonitor` resources, collector/exporter configuration, dashboard-lint CI, and GA4 wiring for an identified web property. It re-verifies and closes only stale beads it owns, and files findings with a `[telemetry]` title. + +Telemetry must never, at any PR-capable level: commit credentials, literal collector endpoints, API keys, or secret values; add an exporter that sends data off-box without an explicitly configured backend; introduce unbounded labels or span attributes; merge its own PR; or (at L5) remove a `hold`/`on-hold`/`do-not-merge` label. At L6 it still never merges its own PR, and it must not modify work already labeled `hold`, `on-hold`, or `do-not-merge`. + +## ACMM level gating + +Telemetry and operations are **L5/L6-only opt-in agents**. Per the built-in ACMM packs (`src/pkg/config/packs/level-5.yaml`, `level-6.yaml`): + +- They are absent from the roster entirely at L1–L4 — no pack below L5 defines a `telemetry` entry, so the agent does not appear in the dashboard, does not spawn a pane, and cannot be kicked. +- At L5 and L6 they are present but their cadence is `paused` in **every** governor mode (`surge`, `busy`, `quiet`, `idle`) until an operator opts in. This is not a description of typical defaults — the pack literally sets `telemetry: paused` in all four cadence tables at both levels. +- `kick_template` is `telemetry-holdgated.md` at L5 and `telemetry-full.md` at L6, matching the hold-gated-vs-full PR behavior described above. + +## When to enable telemetry + +Enable telemetry once you're comfortable with the rest of your L5/L6 roster and want automated observability hardening for the *managed* project — bounded metrics, tracing, and dashboards-as-code, on a backend you've explicitly named. Leave it paused if you have no observability backend in mind yet: with nothing configured, its policies fail closed, so it will only detect and report the existing stack rather than propose changes. + +## How to opt in: `governor.project_observability` + +Un-pausing the agent alone does nothing useful — telemetry's PR-capable policies fail closed without a confirmed target stack. Configure the opt-in under **Settings → Project Observability** in the dashboard: + +```yaml +governor: + project_observability: + open_source: [opentelemetry, prometheus, grafana] + kube_native: [servicemonitor] + commercial: [honeycomb] + references: + honeycomb: + endpoint_env: OTEL_EXPORTER_OTLP_ENDPOINT + credential_secret: observability/honeycomb-key +``` + +Reference fields accept **names only** — an environment-variable name or a `secret-name/key` reference. Literal endpoints, tokens, and API keys are rejected. Selecting platforms and saving persists them under `governor.project_observability` — and nothing else: saving does **not** un-pause the agent (#7261 removed the enable toggles this tab used to carry). The tab shows a read-only status line per agent reporting its `Enabled` flag and real per-mode cadences; to actually run telemetry, un-pause it yourself from **Agents → Cadences** (a conservative `24h` in each mode is a good starting point). + +After telemetry's first advisory run, platforms mentioned in its findings are preselected as suggestions in the Project Observability tab. They stay unsaved until an operator reviews and clicks **Save** — only then does the persisted declaration govern future telemetry (and operations) work. + +## How telemetry interacts with other agents + +Telemetry's lane keywords (`observability`, `opentelemetry`, `prometheus`, `grafana`, `tracing`, `metrics`, `structured-logging`, `servicemonitor`, `podmonitor`) are disjoint from operations' (health, SLO, runbook, incident, rollback, alerting terms), so the two agents do not compete for the same issues. Both share the same `${PROJECT_OBSERVABILITY}` prompt section and the same `governor.project_observability` configuration — telemetry adds the instrumentation; operations builds the health/SLO/runbook layer on top of it. + +## Configuration reference + +Registered defaults (`applyKnownAgentDefaults` in `src/pkg/config/config.go`), applied when a field is left blank in your own config: + +| Field | Default | +|-------|---------| +| `emoji` | 📡 | +| `color` | `#00a8cc` | +| `aliases` | `["tm"]` | +| `bead_role` | `worker` | +| `sort_order` | `65` | +| `include_repos` | `true` | +| `lane_keywords` | `observability`, `opentelemetry`, `prometheus`, `grafana`, `tracing`, `metrics`, `structured-logging`, `servicemonitor`, `podmonitor` | +| `detect_keywords` | `telemetry`, `observability`, `opentelemetry`, `prometheus` | + +ACMM packs define `backend: copilot` (though the effective backend is subject to the allow/deny fallback), `model: claude-sonnet-4-6`, `mode: ISSUES_AND_PRS`, `stale_timeout: 28800`, and the level-appropriate `kick_template`. + +## Cadence and budget considerations + +Telemetry is a heavyweight, PR-capable agent once enabled. Follow the same guidance as every other agent un-paused at L5/L6: set all modes to `12h` or `1d` first, watch its output for a few cycles, and only shorten the cadence once you understand what it's producing and how much budget it consumes per run. + +## What to read next + +- **[Operations Agent](https://github.com/hivecommons/hive/blob/v5/src/docs/operations.md)** — the companion L5/L6 opt-in agent for operational readiness (health checks, SLOs, runbooks). +- **[Agent Configuration](/docs/hive/agent-configuration)** — every agent field, the ACMM level packs, and `project_observability` details. +- **[ACMM Policy Matrix](/docs/hive/acmm-policy-matrix)** — the full per-level, per-agent policy table, including the L5/L6-only gating note. +- **[Getting Started](/docs/hive/getting-started)** — when to opt in as part of the level-climbing journey. diff --git a/docs/content/hive/webhooks.md b/docs/content/hive/webhooks.md index bd3e2d1..6b62048 100644 --- a/docs/content/hive/webhooks.md +++ b/docs/content/hive/webhooks.md @@ -9,7 +9,7 @@ of the ForgeState epic [#13381](https://github.com/hivecommons/hive/issues/13381)). The receiver, the App/hub set-up and what each delivery invalidates are in [Webhook-driven PR cache invalidation](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md#webhook-driven-pr-cache-invalidation); -the dashboard side is in [dashboard.md](https://github.com/hivecommons/hive/blob/v5/src/docs/dashboard.md#hive-activity-monitor). +the dashboard side is in [dashboard.md](/docs/hive/dashboard#hive-activity-monitor). The priority order throughout is **accuracy → latency → API thrift**. A delivery is a free hint; every outbound GitHub call is budgeted. The rules diff --git a/scripts/sync-hive-docs.files.json b/scripts/sync-hive-docs.files.json index 71e15f4..8e1e24b 100644 --- a/scripts/sync-hive-docs.files.json +++ b/scripts/sync-hive-docs.files.json @@ -20,7 +20,7 @@ }, { "source": "acmm-policy-matrix.md", - "comment": "Operations pages — single-sourced from hive src/docs (previously hand-copied into docs/content/hive and prone to drift; migrated to auto-sync)." + "comment": "Operations pages \u2014 single-sourced from hive src/docs (previously hand-copied into docs/content/hive and prone to drift; migrated to auto-sync)." }, { "source": "running-at-level-6.md", @@ -399,5 +399,21 @@ }, { "source": "ui-render-evidence.md" + }, + { + "source": "dashboard.md", + "comment": "Dashboard pages the dashboard help links and Ask AI answers rely on (hivecommons/hive#19182)." + }, + { + "source": "settings.md" + }, + { + "source": "hosted-hub.md" + }, + { + "source": "hub-deployment.md" + }, + { + "source": "telemetry.md" } ] diff --git a/scripts/sync-hive-docs.unsynced-allowlist.txt b/scripts/sync-hive-docs.unsynced-allowlist.txt index c3bacf3..438121c 100644 --- a/scripts/sync-hive-docs.unsynced-allowlist.txt +++ b/scripts/sync-hive-docs.unsynced-allowlist.txt @@ -51,7 +51,6 @@ dashboard-copy-inventory.md dashboard-design-system.md dashboard-source-layout.md dashboard-standalone-upgrades.md -dashboard.md deployment-scripts.md design/crux.md design/discord-issue-promotion.md @@ -92,9 +91,7 @@ hive-open-issue.md hive-open-pr.md hivecommons-migration.md hooks.md -hosted-hub.md house-style.md -hub-deployment.md hub-fleet-activity.md inception.md intent-verification.md @@ -168,7 +165,6 @@ scale-envelope.md security-response.md security-self-assessment.md security.md -settings.md skills.md snapshots.md soc2-control-mapping.md @@ -179,7 +175,6 @@ strategy-lab.md streaming-the-activity-monitor.md supervisor.md swarm.md -telemetry.md tls-setup.md token-access-log.md token-mint.md @@ -194,3 +189,10 @@ v5-sync-policy.md vibe-kanban.md what-is-hive.md work-source-terminology.md + +# Design records stay on GitHub: proposals read as current behaviour to the +# site search and its Ask AI answers (hivecommons/hive#19182). +design/authorization-decision-point.md +design/customers-hub-consent.md +design/dashboard-ask-ai-help.md +design/session-taint.md diff --git a/src/__tests__/designRecord.test.ts b/src/__tests__/designRecord.test.ts new file mode 100644 index 0000000..5ad60cc --- /dev/null +++ b/src/__tests__/designRecord.test.ts @@ -0,0 +1,22 @@ +import { describe, expect, it } from "vitest"; +import { DESIGN_RECORD_SELECTOR, isDesignRecordPage } from "@/lib/designRecord"; + +describe("isDesignRecordPage", () => { + it("marks Hive design records and ADRs", () => { + expect(isDesignRecordPage("hive", "design/customers.md")).toBe(true); + expect(isDesignRecordPage("hive", "adr/0014-hub-spoke.md")).toBe(true); + }); + + it("leaves operator pages and other projects unmarked", () => { + expect(isDesignRecordPage("hive", "dashboard-sections.md")).toBe(false); + expect(isDesignRecordPage("hive", "operator-reference/readme.md")).toBe( + false + ); + expect(isDesignRecordPage("crux", "design/notes.md")).toBe(false); + expect(isDesignRecordPage(undefined, "design/customers.md")).toBe(false); + }); + + it("exposes the selector the Kapa source excludes", () => { + expect(DESIGN_RECORD_SELECTOR).toBe('[data-docs-kind="design-record"]'); + }); +}); diff --git a/src/app/docs/[...slug]/page.tsx b/src/app/docs/[...slug]/page.tsx index 09b5633..5829d08 100644 --- a/src/app/docs/[...slug]/page.tsx +++ b/src/app/docs/[...slug]/page.tsx @@ -7,6 +7,7 @@ import { escapeStrayBraces } from '@/lib/escapeStrayBraces' import { sanitizeHtmlForMdx, removeCommentPatterns } from '@/lib/sanitizeHtml' import { rewriteRelativeImagePaths } from '@/lib/rewriteImagePaths' import { rewriteRelativeDocLinks } from '@/lib/rewriteDocLinks' +import { DESIGN_RECORD_ATTRIBUTE, DESIGN_RECORD_VALUE, isDesignRecordPage } from '@/lib/designRecord' import { remarkStripMdxJs } from '@/lib/remarkStripMdxJs' import { buildPageMap, docsContentPath, getContentPath, isGeneralSectionFile } from '../page-map' import { CURRENT_VERSION, type ProjectId } from '@/config/versions' @@ -389,6 +390,9 @@ export default async function DocPage({ params }: Props) { dangerouslySetInnerHTML={{ __html: JSON.stringify(integrationsJsonLd()) }} /> ) : null} + {isDesignRecordPage(projectId, filePath) ? ( +