Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion CONTRIBUTING.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Contributing to Hive

Thank you for helping improve Hive. This guide is for contributing code and documentation to this repository. If you want to donate compute to a running hive, see [Contribute to a Hive](README.md#contribute-to-a-hive) instead.
Thank you for helping improve Hive. This guide is for contributing code and documentation to this repository. If you want to donate compute to a running hive, see [Contribute to a Hive](src/docs/what-is-hive.md#contribute-to-a-hive) instead.

**New here?** Start with the [getting-started guide for first-time contributors](docs/getting-started-contributing.md) β€” it walks the end-to-end journey (finding an issue, local setup, testing without a cluster, key concepts, and what the review/CI process looks like) and links back into this guide for the mechanics. For live community help, [Join our Discord](https://hivecommons.dev/discord).

Expand Down
180 changes: 30 additions & 150 deletions README.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion bin/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ Most production scripts are installed under `/usr/local/bin` by `bin/hive-deploy
| Script | Stage | Purpose |
|---|---|---|
| `hive.sh` | CLI | Operator command wrapper for starting the supervisor, checking status, attaching, kicking agents, reading logs, and stopping agents. |
| `hive-setup.sh` | Bootstrap | All-in-one Ubuntu 24.04 LXC setup for a Docker-based Hive v2 instance, including generated `hive.yaml` and env files. **Docker-only**: it installs Docker Engine and drives `docker compose`, and predates `HIVE_DEPLOY_RUNTIME`, so that variable does not redirect it. For a Podman install follow the [README's Quick Start (Podman)](../README.md#quick-start-podman); see [Deployment helper scripts](../src/docs/deployment-scripts.md#all-in-one-lxc-setup). |
| `hive-setup.sh` | Bootstrap | All-in-one Ubuntu 24.04 LXC setup for a Docker-based Hive v2 instance, including generated `hive.yaml` and env files. **Docker-only**: it installs Docker Engine and drives `docker compose`, and predates `HIVE_DEPLOY_RUNTIME`, so that variable does not redirect it. For a Podman install follow the [Quick Start (Podman)](../src/docs/quickstart-podman.md); see [Deployment helper scripts](../src/docs/deployment-scripts.md#all-in-one-lxc-setup). |
| `hive-prereq-check.sh` | Bootstrap | Validates host prerequisites for a Docker-based Hive v2 install and can attempt fixes with `--fix`. |
| `hive-deploy.sh` | Deploy | Pulls the latest Hive repository and syncs scripts to `/usr/local/bin`; also restarts Discord bot components when their files change. |
| `hive-checkout-guard.sh` | Deploy | `ExecStartPre` guard for systemd units that execute code out of a checkout (e.g. `hive-discord.service`, `hive-snapshot.service`): refuses to let the unit start when the checkout directory or its entrypoint files could have been planted by an unprivileged local user (#5435). Its exit status is the assertion β€” every unsafe path exits non-zero, so a violation actually stops `ExecStart`. |
Expand Down
1 change: 1 addition & 0 deletions changelog.d/changed-readme-evidence-cards.md
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
- README rewritten around plain-language evidence cards: `hivectl evidence benchmark` now also renders dark/light full-width SVG cards (accuracy, a before/after scenario from one real pull request, prompt injection, cost, "also" strip, how-it-works ladder) gated by `--readme-min-base` (default 200), takes `--stories` and `--red-team` inputs, and the generated README block lists Accuracy / Security / Cost / Also with no statistical vocabulary; the detailed charts and intervals stay in `src/docs/benchmarks/`, and the former README overview moved to `src/docs/what-is-hive.md`.
2 changes: 1 addition & 1 deletion examples/kubestellar/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
> of the v1 approach and as context for the agent definitions in
> [`agents/`](agents/), which remain current-style. Do not follow the
> installation steps below for a new deployment β€” use the
> [Quick Start](../../README.md#quick-start) instead, and see
> [Quick Start](../../src/docs/what-is-hive.md#run-it) instead, and see
> [`docs/LEGACY-v1-architecture.md`](../../docs/LEGACY-v1-architecture.md)
> for the retired v1 architecture this example ran on.

Expand Down
2 changes: 1 addition & 1 deletion security-insights.yml
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ project:
social: https://github.com/clubanderson
primary: true
documentation:
quickstart-guide: https://github.com/hivecommons/hive/blob/v5/README.md#quick-start
quickstart-guide: https://github.com/hivecommons/hive/blob/v5/src/docs/what-is-hive.md#run-it
detailed-guide: https://docs.hivecommons.dev
code-of-conduct: https://github.com/hivecommons/.github/blob/main/CODE_OF_CONDUCT.md
repositories:
Expand Down
20 changes: 17 additions & 3 deletions src/docs/benchmarks/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,30 @@ Reproducible comparison of pull requests that went through Hive's review swarm (

| Month | Report | Charts |
|---|---|---|
| 2026-10 | [outcomes-2026-10.md](outcomes-2026-10.md) | [bars](assets/outcomes-2026-10-bars.svg) Β· [trend](assets/outcomes-2026-10-trend.svg) |
| 2026-10 | [outcomes-2026-10.md](outcomes-2026-10.md) | [bars](assets/outcomes-2026-10-bars.svg) Β· [trend](assets/outcomes-2026-10-trend.svg) Β· README cards `assets/outcomes-2026-10-card-*.svg` |

Each report ships with `outcomes-YYYY-MM.json`, the computed `Report` the markdown, charts and README block are rendered from. `pkg/outcomebench` `TestCommittedReportMatchesReadme` re-renders the newest JSON and fails when the committed markdown, SVGs or the repository README's `<!-- outcomes:start -->…<!-- outcomes:end -->` block differ, so none of them can drift.
Each report ships with `outcomes-YYYY-MM.json`, the computed `Report` the markdown, charts, README cards and README block are rendered from, plus the inputs that are not derivable from the evidence tree: `cost-YYYY-MM.json` (saved `GET /api/cost`), `stories-YYYY-MM.json` (curated caught β†’ fixed β†’ merged examples, timestamps taken from the evidence bundles) and `red-team-YYYY-MM.json` (prompt-injection evaluation counts from [ioscan-red-team.md](../ioscan-red-team.md)). `pkg/outcomebench` `TestCommittedReportMatchesReadme` re-renders the newest JSON and fails when the committed markdown, SVGs, cards or the repository README's `<!-- outcomes:start -->…<!-- outcomes:end -->` block differ, so none of them can drift.

## README cards

The repository README shows this data as plain-language cards (one number, one sentence, a footer naming the base and month), with the detailed charts and intervals kept in the monthly report. Rules the generator enforces for the README:

- A production-count card is drawn only when its base is at least `--readme-min-base` (default 200), separate from the n β‰₯ 10 report threshold. The 43-merge revert bucket, for example, stays in the report.
- The checks-passing card is drawn only when a check result is recorded on at least 80 % of reviewed merges; below that the pass rate would describe a biased subset.
- No statistical vocabulary (intervals, medians, cohorts, n=) appears in the README or on a card; `TestReadmeVocabulary` enforces the list and `TestReadmeProseBudget` keeps README prose under 600 words and 10 sections.
- Every card is a real-text SVG in dark and light (`<picture>` + `prefers-color-scheme`) using the dashboard's own palette.
- The prompt-injection card comes from Hive's own evaluation set, says so on the card, and is not subject to the minimum base because it is not a production count.

Each report's "What the README shows and leaves out" section records, per card, whether it was drawn and on what base.

## Regenerate

```sh
# on a spoke, or anywhere with a copy of its evidence tree
src/scripts/outcome-benchmark.sh --root /data/evidence --month 2026-10 \
--spend cost.json # saved GET /api/cost, for cost per merged PR
--spend cost-2026-10.json # saved GET /api/cost, for cost per merged PR
--stories stories-2026-10.json # curated caught β†’ fixed β†’ merged examples
--red-team red-team-2026-10.json # prompt-injection evaluation counts
--hub hub.json # saved GET /api/hub/evidence (admin session), optional
--source "hive-oke spoke snapshot 2026-10-27" \
--readme # also rewrite README.md's outcomes block
Expand Down
20 changes: 20 additions & 0 deletions src/docs/benchmarks/assets/outcomes-2026-10-card-accuracy-dark.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
37 changes: 37 additions & 0 deletions src/docs/benchmarks/assets/outcomes-2026-10-card-also-dark.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
34 changes: 34 additions & 0 deletions src/docs/benchmarks/assets/outcomes-2026-10-card-also-light.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
20 changes: 20 additions & 0 deletions src/docs/benchmarks/assets/outcomes-2026-10-card-cost-dark.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Loading