The handbook's sections were agent-lifecycle, integrations, swarm, tools,
trust-boundary and web-ui, which do not follow how the system is built, so a
reader could not tell which layer a page is about. Its pages now sit in
swarm/, hives/ and agents/, with the accounts an agent can hold outside the
system in external-accounts/.
- swarm/: forge, matrix and the knowledge repo join the swarm pages, and so
does the swarmctl reference.
- hives/: the dashboard, hivectl and its reference, and the operator/agent
boundary, with a README that takes over the old web-ui and tools pages.
- agents/: the roster, persistence, config changes, the agent's own web page
(was web-ui/agent) and the security model, with a README.
- external-accounts/: GitHub and GitLab.
Pages are moved whole; none is split yet. Every reference follows: relative
links in the docs, `docs/2-handbook/...` paths in code comments, the nix
checks that regenerate the CLI references and the ignore list, and docs/README.md,
whose handbook section is now by layer.
The labels and reviewers columns had no sort, so "every column sorts" was
false; both now sort on their joined text.
A branch protection rule's name is a glob the forge compiles with `/` as its
separator, which also takes `?`, `[a-z]`, `[!a-z]`, `{a,b}` and a backslash
escape. The report read only `*` and `**`, so a rule such as `{main,release}`
matched nothing and its PRs showed as protected by no rule, needing no
approvals. It now reads all of them.
The reports tab holds cards, so a card named "issue report" repeats the word.
The card is now "issues", beside "pull requests", and the handbook says the
same.
The pull requests card gets a diff column, the lines a PR adds and removes
(`+120 −8`), sortable on the total. The controller takes the counts from the
forge's pull request list, so no call is added. The column that said "has all
approvals" is now headed "approved".
The reports tab gets a "pull requests" card under the issue report. It lists
the open PRs of every repo, or of one picked in a repo select, with the
columns a reviewer or merger filters on: author, labels, requested
reviewers, base branch, WIP (the forge's draft flag), approvals against the
base branch's protection rule, has all approvals, conflicts, protected base
and CI. Every column sorts, the small-set columns filter by picking values,
and the browser keeps the filters and the repo. No filter applies at first.
swarm-controller resolves each row so the page makes no calls of its own:
GET /api/pr-report and GET /api/repos/{org}/{repo}/pr-report. The required
approvals come from the first matching branch protection rule (an
unprotected base asks for none); an approval counts when it is the
reviewer's latest decision, on the current head, neither stale nor
dismissed and official.
A free-text table cell gets a minimum width, so a table with many columns
scrolls sideways instead of wrapping a title to a word a line.
The limit was a constant of ten in swarm-wire, so a repo with eleven rules
could not be reviewed and nothing short of a rebuild changed it. It is now
`max_classifications` in the classifier settings, beside
`max_concurrent_reviews`: 1 to 1000, ten until set, and a document stored
before the field decodes with the default. The classifier settings form in
the swarm UI gets a "rules per review" field, and the try-out's add button
stops at the saved limit instead of a hard-coded ten.
The controller checks a try-out, and a requested review's rules file, against
the setting where the run starts. The rules file itself may hold up to the
1000 the setting allows, so raising the limit needs no change to a repo.
A review whose rules exceed the limit posts a no-verdict comment saying so.
A run's reply deadline was a constant that covered ten classifications, a
minute plus three each. It is now computed from the run's own size, so a
bigger run waits as long as it needs and a default-sized one still waits 31
minutes. The classifier's answer window in the queue permissions covers the
biggest run the setting allows.
On the jobs, builds and hives cards the picker was alone on the first line of
the body. DisclosureAction puts a body's control in the header of the
disclosure it is in, beside the chevron and outside the toggle, so it costs no
row and pressing it does not fold the card.
preact 11's types reject the side panel's role=dialog on an aside, which the
nix agent-typecheck check runs. The drawer is a div, whose CSS is
class-based, so nothing else changes.
All four packages move from preact 10.29.8 to 11.2.0. The new types need four
small changes in swarm-ui and the shared dropdown: a ref that may be empty is
typed RefObject<T | null>, HTMLAttributes is imported from preact instead of
read from the JSX namespace, and TextField's type is the five kinds it is
used with, asserted once for the input's new union. npm-deps-hash follows the
lockfile.
chart.js 4.5.1 to 4.6.1, marked 18.0.6 to 18.1.3, wouter-preact 3.10.0 to
3.13.0 and esbuild 0.28.1 to 0.28.2 (the pins), and the lockfile's dompurify
3.4.12 to 3.4.17, which clears the audit's one critical advisory (npm audit
reports 0 vulnerabilities now). preact stays on 10.29.8: 11 is a major
release. npm-deps-hash follows the lockfile.
JobqGraph takes an optional loading element, so the dashboard keeps its text
and the swarm UI's jobs tab passes a placeholder built from the graph's own
node and row classes: a root with two children and a second root, with the
real indent and rail.
The form's credential choice now starts on 'log in with a password', listed
first, with a note that the swarm's own login gives the account a device of
its own. Choosing 'paste a token' shows a warning: a token from Element or
another client belongs to a device that is already logged in, so the agent
cannot use its encryption keys and the account will not decrypt encrypted
rooms.
The broadcast grid showed nothing while the agents loaded, and the egress
card a 'loading the … domains' line. They now show grey placeholders in the
shape of what is coming: six agent chips with the real chip's height (160 px,
measured), and three domain rows with their remove buttons.
Classifier settings, the try-out target row and classification rows, and the
schedule cadence each wrote their own flex row with its own flex basis and
gap. FieldGrid is one grid with equal columns and one gap, FieldGridFull
spans a row, and the four forms use it, so a lone last field keeps its column
width and the columns share their edges in every row.
The label 'message <agent>' is the input's placeholder (the label stays for
screen readers). The send button shows a spinner over its label while the
request is pending and keeps its width, and the 'sent' line is gone: the box
empties when the message is held. Spinner is a component of its own now, used
by the button and the refresh picker.
The schedules card, the notification router card (flows and recent
deliveries) and the flow editor showed a bare 'loading…' line. They now show
grey placeholders in the layout of what is coming: schedule cards with the
real card's row heights, flow cards with a block for the graph, the
deliveries table's header over blank rows, and lines for the editor.
durationLabel moves to util.ts, termPaths to agent/terminal/term-paths.ts,
StateBadges and tokenTotal to agent/state, and TryOutResult to
pages/review-common, so the builds, runs and agent pages no longer import
across page folders. SectionHeading is the body-size section heading the
create form and the egress card each styled; Preformatted is the scrolling
text block of the builds tail and the AGENTS.md view, which now share one
chrome and are both keyboard-scrollable. The components page shows both.
useSubmit holds the idle, sending, done and error state and the request
flow that six forms each wrote out; FormResult shows the success line and
the problem panel; FormStack is the column the link, claude-login,
inference and limits forms each styled by hand. The create-agent, link
account, backend-env and agent-input forms use the submit flow; the link,
claude-login, inference and limits forms use FormStack.
Every docs directory moves under 1-getting-started, 2-handbook,
4-implementation or 5-project; the options reference (section 3) comes from
the website and has no directory here. trust-boundary stays whole under the
handbook for now. web-ui, swarm and tools split between handbook and
implementation, and the command-line references move to
2-handbook/reference. Links, path references in code and nix, and the docs
index follow the moves; no page content changes.
Hint, ActionRow, Toolbar, EmptyState and ExternalLink replace the muted
text, button row, refresh bar, empty line and _blank anchor that each page
restyled under its own class. ExpandableCard (with a loading twin) holds the
builds and recent-runs cards, which had identical head and body CSS. The
create form's raw checkbox becomes CheckboxField. The components page shows
each new piece.
The two groups of fields had different column counts, so their edges never met,
and the price labels carried their unit, which wrapped in a monospace font and
pushed those inputs below their neighbours. Every group is one CSS grid now. The
provider fields sit under a "provider" heading, with the URL and the model each
on a full row so their placeholders are not cut off, shorter price labels and
the unit said once under them.
BadgeSkeleton is the twin of Badge: the real Badge frame, as tall as an
interactive one (the settings values are buttons), with a placeholder for its
value. Permissions, resource caps, internet and allowed domains use it in place of
their "loading…" text, the details popover shows lines of text, and the
AGENTS.md editor a block, in place of theirs. SkeletonLines is a few stacked
lines for such blocks.
The globe of the egress card and of the allowed-domains box showed as a
plain monochrome glyph where the bee and the bell were emoji: a font with a
text-style glyph for the globe won over the emoji font. The two globes now carry
the emoji variation selector, and a panel's icon asks for emoji presentation
(font-variant-emoji), so another icon cannot fall the same way.
The page's composer (its input, slash commands and completion), POST /send in
hive-agent, the OperatorMsg request of the agent socket and its handler in
hive-c0re, and the broker-error helper only the send route used are deleted:
writing to an agent is the swarm UI's terminal. cancel turn, new session and
log out stay in the state badge's menu; POST /api/compact stays, with nothing
on the page calling it. The request-line limit keeps its size, and its comment
says it is a generous bound now. The docs describe the actions in place of the
footer and the prompt.
TableSkeleton is the twin of Table: the same columns, so the same header cells,
with a placeholder shape in each cell of three blank rows and no sort or
filter, which have nothing to work on yet. The hives card and the alerts table
use it in place of their "loading…" text.
The checkbox list was capped at 12em and scrolled, and the box shrinks the
list to its widest label, so the scrollbar sat in the middle of the popover
with the lower permissions hidden. The permissions are a short fixed list:
MultiselectFilterOptions takes scrollable={false} and the permissions box
uses it. Filter lists that can grow long keep the scroll area.
A new Skeleton (a shimmering shape, still where motion is off) and a region
that tells assistive tech once that something is loading. The agent card's
header is split into AgentCardLayout, a layout with a slot for each part: the
card fills the slots with the real icon, badges and controls, its new
AgentCardSkeleton twin fills the same slots with placeholder shapes, so the
card that replaces it lands in the same place. The agents page uses the twin in
place of its "loading…" text.
usePolled takes a cache key: it saves each answer in localStorage and starts
from the saved one, so opening the agents, alerts, builds, review runs or hives
view shows the last data at once and the refresh spinner marks the update. A
saved answer is dropped after a day, when it was saved by another build of the
UI, at log out (a new onLogout of the shared user menu) and when the gateway
ends the login (a new onSessionEnded of the session guard). Pages with an
editor (schedules, notification flows, broadcast) do not use it.
usePolled reports when a request is in flight (through a new onBusy of the
poller) and holds it on for at least 0.4 seconds, so a quick answer still
reads as a refresh. The picker swaps its clock for the spinner, in the same
box so its width stays, and the spinner stands still where motion is off.
Every page with a picker passes it; a page with several polled requests shows
it while any of them runs. The Jobs page fetches through shared components
and has none yet.
The two controls sat among the pane's header badges as a labelled badge and a
cross glyph. They are now icon badges in the top right corner, through a
`trailing` slot of the terminal preview, so the header on the left keeps the
agent, split, subagents and state badges and a narrow pane wraps less.
The menu on an agent's terminal page used to open the subagent on a tab of
its own. It now starts a group of this terminal and the subagent's, split to
the right; in a group's pane it splits that pane. A pane's layout key is the
agent, or `agent/subagent` for a subagent's pane, so the layout operations
stay as they are and a destroyed agent takes its subagent panes with it. A
subagent already in the group shows a marker and does nothing when chosen,
and maximize opens a subagent pane's terminal on its own.
