docs(approvals): add a For operators section
approvals.md (655 lines) is genuinely dense implementation reference (webhook mechanics, DAG phase names, db column names, git-ref rollback internals) with nothing written for an operator deciding whether to click approve. Unlike web-ui/, this is a single top-level file with no subdirectory to give a separate landing page to, so the fix here is in-file: a "For operators" section right after the intro, covering what actually shows up on the dashboard (or hivectl CLI) and what each approval kind does when you click approve or deny, before the existing implementation detail. Every claim in the new section was checked against the rest of this file plus dashboard.md and hivectl-cli.md rather than assumed - caught one real error before pushing (hivectl approvals list doesn't exist, the verb is `pending`) and one incomplete claim (denial reasons are dashboard-only with an optional prompt; the CLI deny has no reason argument).
This commit is contained in:
parent
052767c25b
commit
23ff147953
1 changed files with 42 additions and 0 deletions
|
|
@ -8,6 +8,48 @@ root agent for top-level agents; a sub-manager for its own subtree) — is
|
|||
the policy gate in front of that queue; helper events are how it stays
|
||||
informed about what happens after a decision lands.
|
||||
|
||||
## For operators
|
||||
|
||||
Every add/remove/change to an agent lands on your dashboard's Y3R
|
||||
C4LL tab (or `hivectl approvals pending` / `approve <id>` from the
|
||||
CLI) before it takes effect. What you'll see, and what to do with it:
|
||||
|
||||
- **Config change** (`MergeConfigPr`) — an agent proposed a change to
|
||||
another agent's config (or its own, via a sub-manager) as a forge
|
||||
pull request. Review the diff on the forge — the dashboard card
|
||||
links straight to it, same as reviewing any other PR. Approving
|
||||
triggers the deploy automatically: hive-c0re re-verifies the PR
|
||||
hasn't moved since you looked at it, evaluates it (a dry run,
|
||||
nothing applied yet), merges it, and rebuilds the container. If
|
||||
anything in that chain fails, the change rolls back automatically —
|
||||
the agent stays on its last-good config, no recovery action needed
|
||||
from you.
|
||||
- **New agent** (`InitConfig` then `Spawn`) — creating a brand-new
|
||||
agent is two approvals. `InitConfig` seeds a fresh config repo from
|
||||
a template so the submitting agent can edit it; once you're happy
|
||||
with what they wrote, `Spawn` actually creates the container from
|
||||
that config. Every later change goes through the config-change flow
|
||||
above — there's no repeat "spawn" for an existing agent.
|
||||
- **Meta/flake update** (`UpdateMetaInputs`) — an agent asked to bump
|
||||
one or more Nix flake inputs (or all of them). Approving runs the
|
||||
update and commits the lock change; it doesn't rebuild anything by
|
||||
itself.
|
||||
- **Scheduled prompt** (`SchedulePrompt`) — an agent asked to schedule
|
||||
a message to one or more inboxes at a future time. You can also add
|
||||
schedules yourself directly from the SCH3DUL3S tab, which skips this
|
||||
approval step entirely — the gate here is specifically for an
|
||||
*agent* asking to schedule something, not for you doing it.
|
||||
|
||||
Don't want to approve something? **Deny it** (`DENY` on the dashboard
|
||||
card, or `hivectl approvals deny <id>`) — nothing runs. The dashboard
|
||||
prompts for an optional reason, which lands directly in the submitting
|
||||
agent's inbox if you give one; the CLI denies without one. Denying is
|
||||
final: a denied approval can't be re-approved later, the agent has to
|
||||
submit a fresh one (a new PR, a new request).
|
||||
|
||||
Everything below this point is the implementation detail behind that
|
||||
flow.
|
||||
|
||||
## End-to-end approval flow
|
||||
|
||||
Config changes flow through a **forge pull request** on the agent's
|
||||
|
|
|
|||
Loading…
Reference in a new issue