docs(turn-loop): fix stale plugin defaults + dashboardLinks reader

Verified against nix/agent-modules/claude-settings.nix (claudeMarketplaces
and claudePlugins defaults both gained a second entry — the hive's own
claude-plugins marketplace and base@hyperhive plugin — that the doc never
picked up) and hive-agent/src/web_ui/state.rs (dashboardLinks is read by
the harness's own per-agent web UI, not hive-c0re / the operator
dashboard).
This commit is contained in:
iris 2026-08-15 12:26:50 +02:00 committed by mara
commit b662bc8578

View file

@ -71,9 +71,9 @@ hyperhive.dashboardLinks = [
];
```
Declares extra navigation links that appear on the agent's dashboard
card and in the per-agent page header alongside the built-in forge /
config / container links. Each entry has:
Declares extra navigation links that appear in the per-agent page
header alongside the built-in forge / config / container links. Each
entry has:
| Field | Required | Description |
|-------|----------|-------------|
@ -82,10 +82,12 @@ config / container links. Each entry has:
| `icon` | no | Emoji or short glyph prefix. Defaults to empty string. |
The list is written to `<state>/hyperhive-dashboard-links.json` by a
one-shot systemd unit at container boot. `hive-c0re` reads the file on
each container-view snapshot and attaches the links to the agent card
(`kind = External`) without any code change. Omitting the option
(default empty) produces no extra links.
one-shot systemd unit at container boot. The harness's own web UI
(`agent_links` in `hive-agent/src/web_ui/state.rs`) reads the file on
each `/api/state` snapshot and appends the entries to the per-agent
nav as `kind = External` links — no `hive-c0re` / operator-dashboard
involvement, and no code change needed to pick up a new entry.
Omitting the option (default empty) produces no extra links.
## Custom static files
@ -174,31 +176,43 @@ hive.
## Claude Code plugins
The harness installs Claude Code plugins before the serve loop opens.
Two per-agent `agent.nix` options control this:
Three per-agent `agent.nix` options control this:
```nix
hyperhive.claudeMarketplaces = [ "anthropics/claude-plugins-official" ]; # default
hyperhive.claudePlugins = [ "skill-creator@claude-plugins-official" ]; # default
hyperhive.claudePluginsAutoUpdate = false; # default
hyperhive.claudeMarketplaces = [ # default
"anthropics/claude-plugins-official"
"${hyperhive.packages.claude-plugins}" # hive's own local marketplace, registered as `hyperhive`
];
hyperhive.claudePlugins = [ # default
"skill-creator@claude-plugins-official"
"base@hyperhive"
];
hyperhive.claudePluginsAutoUpdate = false; # default
```
- **`claudeMarketplaces`** — list of marketplace sources passed to
`claude plugin marketplace add <source>`. The official Anthropic
marketplace is pre-configured by default; override or extend to add
custom marketplaces. Idempotent — re-adding an existing source is
a no-op.
`claude plugin marketplace add <source>`. Defaults to Anthropic's
official marketplace plus hyperhive's own `claude-plugins` nix
package (see `nix/packages/claude-plugins.nix`) — a local-path
marketplace registered under the name `hyperhive`, so a hive-authored
skill needs no forge repo or git remote to ship. Override or extend
to add custom marketplaces. Idempotent — re-adding an existing
source is a no-op.
- **`claudePlugins`** — list of plugin specs passed to
`claude plugin install <spec>`. Each spec is installed on every boot
(`install` is expected to be idempotent); failures log a warning but
do not abort boot. Defaults to Anthropic's `skill-creator`, so every
agent can author, refine, and evaluate its own skills without any
per-agent wiring.
do not abort boot. Defaults to Anthropic's `skill-creator` (so every
agent can author, refine, and evaluate its own skills) plus
hyperhive's own `base` plugin — skills that apply to every agent
regardless of role (currently just `state-hygiene`) — all without
any per-agent wiring.
> Both plugin lists follow ordinary NixOS list-option semantics: a
> per-agent definition **replaces** the default, it does not extend it.
> An agent that sets `claudePlugins` and still wants `skill-creator`
> has to list it explicitly alongside its own entries — likewise for
> the official marketplace in `claudeMarketplaces`.
> An agent that sets `claudePlugins` and still wants the defaults has
> to list `skill-creator@claude-plugins-official` and `base@hyperhive`
> explicitly alongside its own entries — likewise for the two default
> entries in `claudeMarketplaces`.
- **`claudePluginsAutoUpdate`** — when `true`, runs
`claude plugin marketplace update` before installing plugins to pull
the latest index. Disabled by default to keep boot times short and