hivecommons-hive · Oct 29, 2026 · Oct 29, 2026 · Oct 29, 2026
@@ -72,6 +72,18 @@ tar xzf crux_0.1.0_linux_amd64.tar.gz
 ./crux --version
 ```
 
+That archive example is for Linux on amd64. On macOS choose `darwin_arm64`
+for Apple Silicon or `darwin_amd64` for Intel from the same release. Keep the
+signature-verification command unchanged. macOS includes `shasum`, so verify
+the selected archive against its signed checksum before extracting it:
+
+```sh
+# Apple Silicon example; use darwin_amd64 in both places on Intel
+grep 'crux_0.1.0_darwin_arm64.tar.gz$' checksums.txt | shasum -a 256 -c -
+tar xzf crux_0.1.0_darwin_arm64.tar.gz
+./crux --version
+```
+
 The container image is signed the same way:
 
 ```sh
@@ -117,6 +129,12 @@ crux kick scout "look at issue 42"  # send it work
 crux stop scout                     # stop it
 ```
 
+While `crux run` is still active, `crux ps` should list `scout`; `crux logs
+scout -n 50` should show the agent's startup or prompt. Output varies by
+backend. If startup fails, check `command -v tmux` and `command -v copilot`,
+then run and authenticate the agent CLI directly before retrying. Do not send
+the example issue task until you have a repository and task you intend it to work on.
+
 Agent files live under `--workdir` (default `$HIVE_WORK_DIR`, then
 `$HOME/.crux`). While `crux run` is in the foreground it opens a small
 control socket in that folder, and `ps`, `logs`, `kick` and `stop` use it
@@ -127,6 +145,11 @@ to reach the live agent.
 `crux serve` keeps the runtime up and exposes it over HTTP+JSON, so other
 programs (or you, from another shell) can drive it:
 
+The example assumes `/run/crux` already exists and is writable by the service
+user; it is not normally writable by an ordinary macOS or Linux user.
+For a local trial, use a socket path in a private directory you own instead
+and set `CRUX_SERVER` to that same path. Do not make a shared socket world-writable.
+
 ```sh
 # Serve on a unix socket. A unix socket is a file on disk that two
 # programs on the same machine use to talk to each other.
@@ -206,6 +229,14 @@ The design record is
 
 ## What crux exposes
 
+**Go integrator reference starts here.** If you only want to operate agents,
+the [commands](#commands), [service setup](#run-it-as-a-service), and
+[runbooks](https://github.com/hivecommons/crux/blob/main/runbooks/README.md) are enough. The remaining interfaces and routes
+are for programs embedding or calling Crux.
+
+<details>
+<summary>Advanced: Go interfaces, HTTP routes, host callbacks, and packages</summary>
+
 Crux has three layers you can build on. Each one is a Go package in this
 repository. The first is the Go interface. The second is the same thing
 over HTTP. The third is what crux asks the host for in return.
@@ -394,6 +425,8 @@ a refusal.
 - `hivecap`: the runtime-side adapters for the hive callback.
 - `serve`, `cli`, `cmd`: the HTTP server, the `crux` command, and the binary.
 
+</details>
+
 ## Contributing
 
 The Go code in this repository is not edited here. It is a copy of

@@ -2,6 +2,17 @@
 
 # Publishing Dibs to the MCP Registry
 
+This is an operator procedure for publishing Dibs' listing in the Model
+Context Protocol (MCP) registry, where agent clients discover the service.
+To use Dibs from an agent, follow [client setup](/docs/dibs/readme#submit-ideas-from-your-agent)
+instead; publishing a listing is not required.
+
+Before starting, have an up-to-date Dibs checkout, Git, GitHub CLI (`gh`),
+`curl`, and `jq`; authenticate `gh` with an account allowed to run repository
+workflows. DNS (Domain Name System) authentication also requires permission
+to manage `hivecommons.dev` DNS records and the repository's Actions secrets.
+Run checkout-relative commands from the repository root.
+
 The root [`server.json`](https://github.com/hivecommons/dibs/blob/main/server.json) prepares the remote-only listing
 `dev.hivecommons/dibs`, using the namespace approved in
 [issue #375](https://github.com/hivecommons/dibs/issues/375#issuecomment-6215095421).
@@ -43,11 +54,14 @@ gh workflow run mcp-registry-publish.yml --repo hivecommons/dibs
 
 ### DNS authentication key
 
-Authentication is DNS-based: the apex TXT record on `hivecommons.dev`
+Authentication is DNS-based: the apex TXT record (a text record on the bare
+domain, not a subdomain) on `hivecommons.dev`
 (`v=MCPv1; k=ed25519; p=<public key>`) must match the Ed25519 private key
 (64 hex chars, as produced by the registry's
 [DNS authentication instructions](https://github.com/modelcontextprotocol/registry/blob/main/docs/modelcontextprotocol-io/authentication.mdx#dns-authentication))
-stored in the `MCP_REGISTRY_PRIVATE_KEY` secret. To rotate, generate a new
+stored in the `MCP_REGISTRY_PRIVATE_KEY` secret. Ed25519 is the signing-key
+type; the public key goes in DNS, while the private key stays secret.
+To rotate, generate a new
 key pair, replace the TXT record (remove the old one — a stale record is tried
 first and breaks verification), then update the secret.
 

@@ -8,24 +8,26 @@
 
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://github.com/hivecommons/dibs/blob/main/LICENSE)
 
-Marketplace of ideas for connecting ideators with hive-managed repositories.
+A place to offer software ideas to projects and retain credit for them.
 
 > **Your idea, your credit, their code.**
 >
 > The missing contributor layer for the AI-agent era.
 
 Dibs is a two-sided marketplace that connects **ideators** — people who call
 dibs on ideas: great insight, but no time, tooling, or inclination to write
-code — with **hive-managed repositories** whose AI agent swarms are hungry
-for well-formed work.
+code — with **hive-managed repositories**: projects that use Hive to run
+coding agents under maintainer-chosen rules.
 
 1. **Ideators post ideas** — public or private — in plain language / markdown.
 2. **Repos opt in** to receive ideas, declaring topics and appetite.
-3. **An LLM matches** ideas to repos that want them; both sides must say yes.
+3. **A language model (LLM) matches** ideas to repos that want them; both the
+   idea contributor and the receiving project must accept the match.
 4. On **mutual acceptance**, Dibs hands the ideator a **prefilled GitHub
    issue** — they file it themselves, under their own GitHub account, so the
-   issue is natively attributed to them (label `ideated`). The hive's AI
-   agents implement it. Dibs is just the matchmaker: it never files the
+   issue is natively attributed to them (label `ideated`). The receiving project
+   can then have its agents work on it under its own review rules. In this
+   default flow Dibs is just the matchmaker: it never files the
    issue for you.
 
 ## Ideators are first-class contributors
@@ -43,7 +45,35 @@ public.
 Every implemented idea traces back to its ideator: the GitHub issue credits
 the idea's author, the resulting work carries that provenance, and the public
 **credit wall** (`/api/credits`, "Credit wall" in the UI) lists every ideator
-whose idea shipped. An idea is a contribution.
+with a settled idea: a GitHub issue URL has been recorded. This credits the
+proposal, not proof that its implementation shipped or its issue was closed.
+Settled ideas appear regardless of their visibility setting: settling a private
+idea makes its credit facts (author, title/TLDR, target, issue URL, and time)
+public, but not its body or private detail endpoint.
+
+## Try Dibs in your browser
+
+No local installation or Go toolchain is needed. Open
+[dibs.hivecommons.dev](https://dibs.hivecommons.dev) to browse the public
+surface; posting needs a Hive Hub sign-in and filing the issue needs a GitHub account.
+
+1. Sign in and describe your idea in plain language. Choose public or private
+   deliberately; unsettled private ideas are not included in the public wall.
+2. Review suggested repositories and offer the idea to a suitable project.
+   For Hive-managed targets, both sides accept before issue filing.
+3. Open the prefilled GitHub issue, review it, and file it yourself.
+4. Confirm the resulting issue URL in Dibs. This step is **settlement**:
+   it records the handoff, not completion of the proposed work. Confirming also
+   publishes the credit facts above, even for an idea marked private.
+
+Non-Hive GitHub targets can skip the receiving-project acceptance step.
+For settlement and privacy details, see the [consumer API](/docs/dibs/credit-wall-api).
+To submit from a coding agent instead, see [MCP setup](#submit-ideas-from-your-agent).
+
+## Maintainer and developer reference
+
+The following sections cover running Dibs, its API, and local development,
+not prerequisites for using the hosted site.
 
 ## Architecture
 
@@ -297,6 +327,12 @@ still call `prompts/get` directly.
 
 ## Development
 
+Requires Git and Go 1.27 or newer. Clone
+`https://github.com/hivecommons/dibs.git`, then run these commands from the
+checkout's top-level `dibs` folder. For authenticated local use, follow
+[Running locally with sign-in](#running-locally-with-sign-in); fakehub is
+for development only, not a production authentication service.
+
 ```sh
 go test -race -count=1 ./...
 go run ./cmd/dibs            # serves on :8080 at /

@@ -2,31 +2,32 @@
 
 # Dibs Roadmap
 
-Dibs is a marketplace for turning public ideas into claimable, settleable work.
+Dibs connects idea contributors to projects. A project can accept an idea;
+**settlement** records the resulting GitHub issue URL, not a completed implementation.
 This roadmap gives maintainers, ideators, and adopters a shared view of where
 the project is headed next.
 
 ## Recently shipped
 
 - End-to-end ideation, matching, and settlement flows for GitHub issue-backed
   work.
-- Intake support for common document formats with bounded PDF extraction and
-  malformed-input recovery.
+- Idea intake from common document formats, with limits on PDF text extraction
+  and recovery when an uploaded document is malformed.
 - Repository registry, credit-wall mechanics, notifications, and guided server
   flows covered by automated tests.
 
 ## Near term
 
 1. **Trust and abuse controls:** improve spam resistance for public idea intake,
-   including clearer moderation states and rate/quality signals for ideators.
+   including clearer moderation states and rate/quality signals for idea contributors.
    See the [proposed idea-intake trust design](https://github.com/hivecommons/dibs/blob/main/docs/idea-intake-trust.md);
    implementation follows in separate issues.
-2. **Forge and repo coverage:** define what it takes to support non-GitHub issue
+2. **Forge and repo coverage:** define what it takes to support issue hosts other than GitHub
    targets while growing the repository registry beyond hive-managed projects.
 3. **Credit-wall integrations:** the [consumer API reference](/docs/dibs/credit-wall-api)
    documents eligibility, settlement state, rewards, and current experimental
    stability levels. Next, define compatibility guarantees and stabilize the
-   downstream contract.
+   promises made to applications that consume this API.
 
 ## Deferred / non-goals
 

@@ -125,6 +125,39 @@ Existing autonomous lanes can open issues, create PRs, and auto-merge on green C
 | operations (paused) | full | `operations-full.md` |
 | brainstorm | advisory | `brainstorm-advisory.md` |
 
+## What hive will say on GitHub at each level
+
+ACMM constrains *agents*; the platform sweeps (sentinel, hold guard, stage
+labels, supersession, …) are not agents and used to run unconditionally
+over `project.repos`. Since the write-back containment gate
+(`pkg/writeback`, see
+[operator-reference.md](https://github.com/hivecommons/hive/blob/v5/src/docs/operator-reference.md#what-hive-writes-to-github-and-when))
+each *unsolicited* write-back kind has its own floor, and on a PR hive did
+not open it additionally needs the review opt-in label
+(`review.require_labels`, default `hive-review`). Hive-authored PRs and
+issues, `/hive` command replies and dashboard-triggered actions are never
+gated. Defaults (override under `writeback.kinds.<kind>`):
+
+| Write-back kind | L1–L3 | L4 | L5 | L6 |
+| --- | --- | --- | --- | --- |
+| `sentinel` comment + `sentinel-alert` label | dashboard only | dashboard only | opt-in label only | all PRs |
+| `hold_gate_notice` (mergeability / drift) | — | hive PRs only | hive PRs only | hive PRs only |
+| `stage_label`, `needs_decision_comment` on foreign PRs | internal tracking | internal tracking | opt-in label | opt-in label |
+| `supersession_notice`, `duplicate_fix_notice`, `reporter_trust_hold`, `covered_by_pr_label`, `issue_close`, `parent_issue_edit`, `gate_comment` | — | — | opt-in label | opt-in label |
+| `supersession_close`, `contributor_adopt`, `ci_rerun` | — | — | — | opt-in label |
+| `verdict_label` | L3: opt-in label | opt-in label | opt-in label | opt-in label |
+| `claim_comment` | — | opt-in label | opt-in label | opt-in label |
+| `welcome_comment` | — | — | opt-in label | all items |
+| `issue_file` (new hive-authored issues) | L3+ | yes | yes | yes |
+
+In practice: **L4 means hive files issues and talks only on its own PRs**;
+**L5 adds comments and labels on PRs a maintainer labelled `hive-review`**;
+**L6 lets sentinel and welcome comments reach unlabelled PRs**. A repo
+listed only so an agent can file regression issues should carry
+`writeback.per_repo.<repo>.mode: issues-only`, which holds at every level.
+`backfill: false` (default) additionally keeps every kind off items that
+predate hive's first sight of, or write access to, the repo.
+
 ## Example config alignment
 
 `src/hive.yaml.example` uses the built-in `quality` lane for automated test suites, coverage gates, and regression checks. There is no built-in `tester` lane in the ACMM packs, known-agent defaults, or shipped policy templates; operators who want a separate tester must define it as a custom agent with explicit metadata and a policy template.

@@ -129,7 +129,7 @@ older overlays, but new configs should use `bob.session_label`.
                                  #   launch_cmd, prompt, tools, and skills at launch.
 ```
 
-The dashboard API can update this field through [`POST /api/effort/{agent}/{effort}`](https://github.com/hivecommons/hive/blob/v5/src/docs/api-reference.md#agents-and-controls).
+The dashboard API can update this field through [`POST /api/effort/{agent}/{effort}`](https://github.com/hivecommons/hive/blob/v5/src/docs/api-reference/agents-and-controls.md).
 
 The dashboard shows a reasoning-effort dropdown next to the model picker for every method that has an effort control (`codex`, `agy`, `claude`, and `omp`). The value is validated at set time against the method's own set, so a `codex`-only level such as `minimal` is refused for a `claude` agent rather than stored and dropped at launch. For `omp`, the dropdown is per selected model: Hive reads `omp models --json` and uses that model's `thinking` levels, hiding the control for models that report no thinking support. Picking `default` clears the stored value; for `claude` and `omp` that means no effort flag at all and the CLI's own default. The dropdown persists through the same path as the model picker (`hive.yaml` plus the per-agent overlay under `agents_dir`), which is the durable path on a hosted spoke: a hand edit of the agent's file is reverted by the next sync, the dashboard write is not. Each dropdown change is recorded in the audit trail as `set_reasoning_effort` with the new value, like the other per-agent setting changes. The effort the agent was actually launched with is what the run rows and the `- hive:` PR trailer report, so a `claude` agent at `xhigh` shows `effort=xhigh` there and an agent with no stored effort shows none.
 
@@ -1074,6 +1074,31 @@ The `hive/tracking` label also satisfies the tracker-issue check used by `/contr
 
 **Not the same thing as the contribute filters.** `hub.contribute_labels_mode` + its label list gate which issues are *handed out to external contributors* over `/contribute` — they have never gated the hive's **own** agents, so an operator who allow-listed a queue label there (a common setup for routing labeled issues to contributors) still had a hive whose own scanner could work every other open issue. `project.issue_filter.require_labels` is the agent-side gate; configure both if you want the same label to govern both lanes.
 
+## Write-back containment (`writeback`)
+
+ACMM levels and label policy decide what *agents* may do. The `writeback`
+block decides what the *platform* may say on GitHub without being asked:
+sentinel alerts, hold-gate notices, stage labels, supersession and
+duplicate notices, reporter-trust holds, and so on. Each kind has a minimum
+level and, on PRs hive did not open, needs the review opt-in label
+(`review.require_labels`, fallback `hive-review`):
+
+```yaml
+writeback:
+  unsolicited:
+    min_level: 5
+    require_labels: true
+    backfill: false
+  per_repo:
+    torch-spyre/torch-spyre: { mode: issues-only }
+  kinds:
+    sentinel: { min_level: 5, require_label: true, unlabeled_min_level: 6 }
+```
+
+Agent kicks on items already labelled for hive, hive's own PRs and issues,
+and `/hive` command replies are never gated. The default matrix per level
+is in [acmm-policy-matrix.md](/docs/hive/acmm-policy-matrix#what-hive-will-say-on-github-at-each-level).
+
 ## When to add what
 
 | Add… | …when |

@@ -1263,7 +1263,7 @@ That last line types a fresh prompt into a pane whose CLI is still mid-turn, int
 
 **A blip is not an abandonment until the grace window says so.** The re-adoption check above is zero-width for a `1006`: the hub processes the dead socket the instant its read fails, while the relay does not even start redialing for `BASE_RECONNECT_DELAY_MS` (1 s). So on a real network blip the release always won the race, and every blip wrote an `abandoned_disconnect` run row plus a "released: connection lost" activity row for a task that resumed one second later — 11 phantom rows across 17 completed tasks in one 3.5-hour run ([#7838](https://github.com/hivecommons/hive/issues/7838)). The visible booking now waits `HIVE_CONTRIBUTE_DISCONNECT_GRACE` (default 5 s); at the deadline the hub re-runs the re-adoption check and also asks whether a completion/failure row has since been written for the task id, and writes nothing if either is true. The short release cooldown — the double-assign hedge — is still booked immediately and still withdrawn by the resume, so the window is covered either way.
 
-**Who wrote the PR does not change the stand-in rule.** Clanker PRs are adoptable on disconnect regardless of the owner's repo role: once the nudge window passes with the contributor's hive gone, the hub's hive adopts a maintainer's `author/clanker` PR exactly as it adopts anyone else's (`governor.labels.stage.adoption.maintainer_policy`, default `adopt`; `ask` parks it for an owner's Adopt, `never` opts out).
+**Who wrote the PR does not change the stand-in rule.** Clanker PRs are adoptable on disconnect regardless of the owner's repo role: once the nudge window passes with the contributor's clanker gone, the hub's hive adopts a maintainer's `author/clanker` PR exactly as it adopts anyone else's (`governor.labels.stage.adoption.maintainer_policy`, default `adopt`; `ask` parks it for an owner's Adopt, `never` opts out).
 
 **The lease has to outlive the hub process.** Leases used to live only in the hub's memory, so a restart — which self-upgrade rolls ([#5391](https://github.com/hivecommons/hive/issues/5391)) make routine rather than rare — emptied the registry while every relay carried on working. After the roll *no* in-flight resume could match, and each one produced the same four lines above, this time for a reason the relay could do nothing about ([#5681](https://github.com/hivecommons/hive/issues/5681)). Observed 2026-09-02: revoked at 14:24:40, the same issue reassigned to the same relay at 14:24:44, discarding two and a half minutes of a turn that was progressing normally. The registry is now written to `/data/contributors/task-leases.json` (owner-only) on every assignment, renewal and release, and read back at startup, so a restart is just a longer-than-usual disconnect.