hive-c0re/src/dashboard/approvals.rs

@@ -16,7 +16,7 @@ use super::{AppState, error_response};
 use crate::actions;
 use crate::coordinator::Coordinator;
 
-/// Approve a pending approval row.
+/// `POST /api/approve/{id}` — approve a pending approval row.
 #[utoipa::path(
     post,
     path = "/api/approve/{id}",
@@ -47,7 +47,7 @@ pub(super) struct DenyForm {
     note: Option<String>,
 }
 
-/// Deny a pending approval row, with an optional
+/// `POST /api/deny/{id}` — deny a pending approval row, with an optional
 /// note (form field `note`).
 #[utoipa::path(
     post,

hive-c0re/src/dashboard/build_logs.rs

@@ -29,10 +29,8 @@ pub(super) struct BuildLogsAllQuery {
     limit: Option<usize>,
 }
 
-/// Most-recent build log headers across
-/// all agents, newest first.
-///
-/// Same JSON shape as the per-agent endpoint.
+/// `GET /api/build-logs?limit=N` — most-recent build log headers across
+/// all agents, newest first. Same JSON shape as the per-agent endpoint.
 #[utoipa::path(
     get,
     path = "/api/build-logs",
@@ -62,11 +60,11 @@ pub(super) struct BuildLogsQuery {
     limit: Option<usize>,
 }
 
-/// Most-recent build log
-/// headers for one agent, newest first.
-///
-/// Returns `Vec<BuildLogHeader>` (JSON). Backs the per-agent log chip
-/// in the agent card and the side-panel header list.
+/// `GET /api/build-logs/{agent}?limit=N` — most-recent build log
+/// headers for one agent, newest first. Returns
+/// `Vec<BuildLogHeader>` (JSON). Limit defaults to 10, server-side
+/// cap at 50. Backs the per-agent log chip in the agent card and
+/// the side-panel header list.
 #[utoipa::path(
     get,
     path = "/api/build-logs/{agent}",
@@ -103,12 +101,10 @@ pub(super) async fn get_build_logs_agent(
     }
 }
 
-/// Full build log row (stdout +
-/// stderr concatenated) by id.
-///
-/// Returns `BuildLogFull` (JSON), or HTTP 404 when the id doesn't
-/// exist (vacuum-reaped, or the operator passed a stale id from a
-/// refresh race).
+/// `GET /api/build-logs/id/{id}` — full build log row (stdout +
+/// stderr concatenated) by id. Returns `BuildLogFull` (JSON), or
+/// HTTP 404 when the id doesn't exist (vacuum-reaped, or the
+/// operator passed a stale id from a refresh race).
 #[utoipa::path(
     get,
     path = "/api/build-logs/id/{id}",
@@ -131,16 +127,14 @@ pub(super) async fn get_build_log_full(
     }
 }
 
-/// The build log for a **queue node**,
-/// resolved node id → log-row id → full log.
-///
-/// Same `BuildLogFull` JSON (`stdout` / `stderr` + header) as
-/// `get_build_log_full`; HTTP 404 when the node has no linked log (the
-/// client gates the request on `NodeView.build_log_id`, but a vacuum
-/// race can still 404). This is the on-demand live-log-panel fetch,
-/// distinct from the `build_log_id` on the wire — that id is for
-/// deep-linking to the BUILD L0GS tab's full history view, not for
-/// fetching the log content itself.
+/// `GET /api/build-log/{node_id}` — the build log for a **queue node**,
+/// resolved node id → log-row id → full log. Same `BuildLogFull` JSON
+/// (`stdout` / `stderr` + header) as `get_build_log_full`; HTTP 404 when the
+/// node has no linked log (the client gates the request on
+/// `NodeView.build_log_id`, but a vacuum race can still 404). This is the
+/// on-demand live-log-panel fetch, distinct from the `build_log_id` on the
+/// wire — that id is for deep-linking to the BUILD L0GS tab's full history
+/// view, not for fetching the log content itself.
 #[utoipa::path(
     get,
     path = "/api/build-log/{node_id}",
@@ -166,7 +160,7 @@ pub(super) async fn get_build_log_for_node(
     }
 }
 
-/// The node's build log as `text/plain`
+/// `GET /api/build-log/{node_id}/raw` — the node's build log as `text/plain`
 /// for download (delegates to `get_build_log_raw` after resolving the node id).
 #[utoipa::path(
     get,
@@ -206,16 +200,15 @@ struct BuildLogFrame {
     done: bool,
 }
 
-/// SSE stream that delivers
-/// incremental stdout/stderr as a build runs.
+/// `GET /api/build-logs/id/{id}/stream` — SSE stream that delivers
+/// incremental stdout/stderr as a build runs. The client connects when
+/// it opens a running-build panel; the stream closes automatically once
+/// the build finishes (or the row disappears due to a vacuum).
 ///
-/// The client connects when it opens a running-build panel; the
-/// stream closes automatically once the build finishes (or the row
-/// disappears due to a vacuum). Each frame is a JSON-serialised
-/// `BuildLogFrame`. The first frame always carries the full
-/// accumulated log so far (cursors start at 0); subsequent frames
-/// carry only new bytes. `done: true` on the final frame signals the
-/// browser to close the `EventSource`.
+/// Each frame is a JSON-serialised `BuildLogFrame`. The first frame
+/// always carries the full accumulated log so far (cursors start at 0);
+/// subsequent frames carry only new bytes. `done: true` on the final
+/// frame signals the browser to close the `EventSource`.
 #[utoipa::path(
     get,
     path = "/api/build-logs/id/{id}/stream",
@@ -314,10 +307,8 @@ pub(super) async fn get_build_log_stream(
     Sse::new(ReceiverStream::new(rx)).keep_alive(KeepAlive::default())
 }
 
-/// Full log as `text/plain` for
-/// download.
-///
-/// Stdout and stderr are concatenated with a `--- stderr ---`
+/// `GET /api/build-logs/id/{id}/raw` — full log as `text/plain` for
+/// download. Stdout and stderr are concatenated with a `--- stderr ---`
 /// separator (same layout the JS side-panel renders). The
 /// `Content-Disposition` header triggers a browser download with a
 /// descriptive filename so the operator can save and share the log.

hive-c0re/src/dashboard/extra_forges.rs

@@ -58,13 +58,11 @@ pub(super) struct ExtraForgesQuery {
     agent: String,
 }
 
-/// List the external forge
-/// accounts currently provisioned for `agent`.
-///
-/// Derived from every `forge-<label>-token` file in its state dir
-/// (mirrors `matrix_accounts.rs`'s filename-scan listing). `base_url`
-/// is backfilled from the matching `forge-<label>.json` sidecar when
-/// present. Never returns a token.
+/// `GET /api/extra-forges?agent=<name>` — list the external forge accounts
+/// currently provisioned for `agent`, derived from every `forge-<label>-
+/// token` file in its state dir (mirrors `matrix_accounts.rs`'s filename-scan
+/// listing). `base_url` is backfilled from the matching `forge-<label>.json`
+/// sidecar when present. Never returns a token.
 #[utoipa::path(
     get,
     path = "/api/extra-forges",
@@ -135,12 +133,10 @@ struct ExtraForgeAccountResult {
     ok: bool,
 }
 
-/// Add persists the operator-pasted
+/// `POST /api/extra-forge-account` — add persists the operator-pasted
 /// label/base-URL/token to the agent's state dir via hive-priv; remove
-/// deletes both files.
-///
-/// Purely local — no remote account creation or revocation, there is
-/// no admin access assumed on the external forge.
+/// deletes both files. Purely local — no remote account creation or
+/// revocation, there is no admin access assumed on the external forge.
 /// Operator-authenticated (dashboard). Never echoes the token back.
 #[utoipa::path(
     post,

hive-c0re/src/dashboard/health.rs

@@ -28,7 +28,7 @@ use utoipa::ToSchema;
 
 use crate::host_stats::ServerWarning;
 
-/// Liveness. Always `200`; no further checks.
+/// `GET /health/live` — liveness. Always `200`; no further checks.
 #[utoipa::path(
     get,
     path = "/health/live",
@@ -49,13 +49,12 @@ struct ReadyBody {
     warnings: Vec<ServerWarning>,
 }
 
-/// Readiness.
-///
-/// `200` with `{"status":"ok", "warnings": [...]}` unless a `crit`-level
-/// warning is currently set in [`crate::warnings::snapshot`], in which
-/// case `503` with `{"status":"degraded", ...}`. `warnings` always
-/// carries the full current list (including `warn`-level entries not
-/// affecting the status) so a poller gets detail either way.
+/// `GET /health/ready` — readiness. `200` with `{"status":"ok", "warnings":
+/// [...]}` unless a `crit`-level warning is currently set in
+/// [`crate::warnings::snapshot`], in which case `503` with
+/// `{"status":"degraded", ...}`. `warnings` always carries the full
+/// current list (including `warn`-level entries not affecting the
+/// status) so a poller gets detail either way.
 #[utoipa::path(
     get,
     path = "/health/ready",

hive-c0re/src/dashboard/infra_containers.rs

@@ -14,15 +14,14 @@ use hive_priv_sock::{InfraAction, InfraContainer};
 
 use super::{AppState, error_response};
 
-/// Start / stop / restart a
-/// hive infrastructure container from the dashboard.
-///
-/// `name` parses into [`InfraContainer`] (the allowlist; unrecognised
-/// names 400), `action` into `start` / `stop` / `restart`. Every attempt
-/// lands in the audit log (actor `"operator"`, action `start_infra` /
-/// `stop_infra` / `restart_infra`) and streams as an `AuditEntryAdded`
-/// event, so operator-driven and agent-driven (`infra_admin`) infra
-/// actions show up in the same AUDIT view.
+/// `POST /api/infra-container/{name}/{action}` — start / stop / restart a
+/// hive infrastructure container from the dashboard. `name` parses into
+/// [`InfraContainer`] (the allowlist; unrecognised names 400), `action`
+/// into `start` / `stop` / `restart`. Every attempt lands in the audit log
+/// (actor `"operator"`, action `start_infra` / `stop_infra` /
+/// `restart_infra`) and streams as an `AuditEntryAdded` event, so
+/// operator-driven and agent-driven (`infra_admin`) infra actions show up
+/// in the same AUDIT view.
 #[utoipa::path(
     post,
     path = "/api/infra-container/{name}/{action}",

hive-c0re/src/dashboard/journal.rs

@@ -34,7 +34,6 @@ pub(super) struct JournalQuery {
 }
 
 /// Read `journalctl -M <container> -b` and return its text output.
-///
 /// Operator-only by virtue of the dashboard being host-bound. hive-c0re
 /// runs unprivileged (privsep), so the `-M` read — which enters the
 /// container namespace and needs root — is delegated to hive-priv.
@@ -160,12 +159,10 @@ pub(super) struct JournalHostQuery {
     lines: Option<u32>,
 }
 
-/// Host-side journald (no
-/// `-M` container flag).
-///
-/// Restricted to an allow-list of known host services so arbitrary unit
-/// names can't be probed. Operator-only by virtue of the dashboard binding
-/// to a host-only port.
+/// `GET /api/journal-host?unit=<unit>&lines=N` — host-side journald (no
+/// `-M` container flag). Restricted to an allow-list of known host services
+/// so arbitrary unit names can't be probed. Operator-only by virtue of the
+/// dashboard binding to a host-only port.
 #[utoipa::path(
     get,
     path = "/api/journal-host",

hive-c0re/src/dashboard/lifecycle_ops.rs

@@ -30,7 +30,7 @@ use super::{AppState, Ident, error_response, guard_agent_name, strip_container_p
 use crate::job_queue::{Source, submit};
 use crate::{actions, lifecycle};
 
-/// Queue a rebuild DAG for `name`.
+/// `POST /api/rebuild/{name}` — queue a rebuild DAG for `name`.
 #[utoipa::path(
     post,
     path = "/api/rebuild/{name}",
@@ -59,10 +59,8 @@ pub(super) async fn post_rebuild(
     (StatusCode::OK, "ok").into_response()
 }
 
-/// Stop `name`, hard by default or
-/// gracefully when `graceful=1`.
-///
-/// Graceful mode: quiesce → drain → stop.
+/// `POST /api/kill/{name}?graceful=1` — stop `name`, hard by default or
+/// gracefully (quiesce → drain → stop) when `graceful=1`.
 #[utoipa::path(
     post,
     path = "/api/kill/{name}",
@@ -121,10 +119,8 @@ pub(super) async fn post_kill(
     (StatusCode::OK, "ok").into_response()
 }
 
-/// Restart `name`, hard by default
-/// or gracefully when `graceful=1`.
-///
-/// Graceful mode: quiesce → drain → restart.
+/// `POST /api/restart/{name}?graceful=1` — restart `name`, hard by default
+/// or gracefully (quiesce → drain → restart) when `graceful=1`.
 #[utoipa::path(
     post,
     path = "/api/restart/{name}",
@@ -176,7 +172,7 @@ pub(super) struct StartParams {
     paused: bool,
 }
 
-/// Start `name`, optionally paused.
+/// `POST /api/start/{name}?paused=1` — start `name`, optionally paused.
 ///
 /// Plain `?paused=1` mirrors `hivectl agent <name> start --paused`: if
 /// `name` is already running, this just writes the pause marker in place
@@ -236,7 +232,7 @@ pub(super) async fn post_start(
     (StatusCode::OK, "ok").into_response()
 }
 
-/// Write the pause marker for `name`.
+/// `POST /api/pause/{name}` — write the pause marker for `name`.
 ///
 /// Unlike the lifecycle ops above this is not a DAG: it writes a single
 /// marker file, which the harness stats at the top of its serve loop.
@@ -275,7 +271,7 @@ pub(super) async fn post_pause(
     (StatusCode::OK, "ok").into_response()
 }
 
-/// Remove the pause marker for `name`.
+/// `POST /api/resume/{name}` — remove the pause marker for `name`.
 ///
 /// The inverse of `post_pause`. Removing a non-existent marker is a no-op
 /// (idempotent). Triggers an immediate rescan so the paused badge clears.
@@ -321,7 +317,7 @@ pub(super) struct ResourceLimitsForm {
     memory_max: String,
 }
 
-/// Write per-agent CPU/memory limit
+/// `POST /api/resource-limits/{name}` — write per-agent CPU/memory limit
 /// overrides for `name`.
 ///
 /// An empty `cpu_quota` or `memory_max` field clears that field's override,
@@ -394,7 +390,7 @@ pub(super) async fn post_resource_limits(
     (StatusCode::OK, "ok").into_response()
 }
 
-/// Queue a rebuild DAG for every live agent
+/// `POST /api/update-all` — queue a rebuild DAG for every live agent
 /// container.
 #[utoipa::path(
     post,
@@ -427,10 +423,9 @@ pub(super) struct DestroyForm {
     purge: Option<String>,
 }
 
-/// Destroy `name`'s container.
-///
-/// Form field `purge` (any non-empty value, e.g. `"on"`) also wipes the
-/// retained state dir instead of leaving a tombstone.
+/// `POST /api/destroy/{name}` — destroy `name`'s container. Form field
+/// `purge` (any non-empty value, e.g. `"on"`) also wipes the retained
+/// state dir instead of leaving a tombstone.
 #[utoipa::path(
     post,
     path = "/api/destroy/{name}",

hive-c0re/src/dashboard/matrix_accounts.rs

@@ -103,10 +103,8 @@ fn account_name_from_filename(fname: &str) -> Option<String> {
     Some(suffix.to_owned())
 }
 
-/// Matrix accounts provisioned
-/// for `agent`.
-///
-/// Backfilled with `homeserver`/`live`/`user_id` from the daemon's
+/// `GET /api/matrix-accounts?agent=<name>` — matrix accounts provisioned
+/// for `agent`, backfilled with `homeserver`/`live`/`user_id` from the daemon's
 /// snapshot.
 #[utoipa::path(
     get,
@@ -190,7 +188,6 @@ struct MatrixLoginResult {
 }
 
 /// Provision (or refresh) the token for an agent's extra matrix account.
-///
 /// password mode → `m.login.password`; token mode → validate via `whoami`.
 /// On success writes the token to `matrix-token-<account>` via hive-priv and
 /// kicks the daemon. Operator-authenticated (dashboard). Never echoes the
@@ -296,9 +293,7 @@ struct GithubAccountResult {
 }
 
 /// Provision (or refresh) an agent's GitHub PAT from the dashboard
-/// credentials tab.
-///
-/// Validates the agent name, then writes the PAT to
+/// credentials tab. Validates the agent name, then writes the PAT to
 /// `<state>/github-token` (`0600`, agent-owned) via hive-priv. No account
 /// creation and no daemon to kick — the agent's `gh` wrapper / git credential
 /// helper read the file live, so the new token takes effect immediately.
@@ -343,11 +338,10 @@ struct GithubAccountStatus {
     present: bool,
 }
 
-/// Whether the agent has a GitHub
-/// PAT provisioned (its `github-token` file exists).
-///
-/// Lets the credentials tab show "token stored" vs "not set" instead of a
-/// black-hole paste field. Never returns the token itself.
+/// `GET /api/github-account?agent=<name>` — whether the agent has a GitHub
+/// PAT provisioned (its `github-token` file exists). Lets the credentials tab
+/// show "token stored" vs "not set" instead of a black-hole paste field.
+/// Never returns the token itself.
 #[utoipa::path(
     get,
     path = "/api/github-account",

hive-c0re/src/dashboard/meta_inputs.rs

@@ -179,12 +179,11 @@ pub(super) struct MetaUpdateForm {
 }
 
 /// Bulk-update selected meta flake inputs, then rebuild the affected
-/// agents in the background.
-///
-/// Idempotent w.r.t. selection — choosing an input that's already at
-/// the latest sha is a no-op (no commit, no rebuild ripple). Returns
-/// immediately after queueing the work; dashboard polls for progress
-/// via container `pending` spinners + the meta-inputs row sha update.
+/// agents in the background. Idempotent w.r.t. selection — choosing
+/// an input that's already at the latest sha is a no-op (no commit,
+/// no rebuild ripple). Returns immediately after queueing the work;
+/// dashboard polls for progress via container `pending` spinners +
+/// the meta-inputs row sha update.
 #[utoipa::path(
     post,
     path = "/api/meta-update",

hive-c0re/src/dashboard/misc_api.rs

@@ -16,7 +16,6 @@ use crate::container_stats::ContainerResource;
 use crate::hive_stats::HiveStats;
 
 /// Unread operator-directed messages for the dashboard's Y3R C4LL inbox.
-///
 /// Returns messages addressed to `"operator"` that haven't been
 /// acked yet (the operator clears them via the existing
 /// `POST /api/agent/operator/mark-all-read`). Newest-first; path-shaped
@@ -73,14 +72,12 @@ pub(super) async fn api_operator_inbox(State(state): State<AppState>) -> Respons
 
 #[derive(Deserialize, IntoParams)]
 pub(super) struct StatsHiveQuery {
-    /// Stats window; defaults to `24h`.
     window: Option<String>,
 }
 
 /// Hive-wide turn-stats rollup for the dashboard swarm-stats view.
-///
 /// Aggregates every agent's `hyperhive-turn-stats.sqlite` read-only
-/// (skips missing/unreadable ones).
+/// (skips missing/unreadable ones). Window defaults to `24h`.
 #[utoipa::path(
     get,
     path = "/api/stats-hive",
@@ -100,10 +97,8 @@ pub(super) async fn api_stats_hive(
     .into_response()
 }
 
-/// Live per-agent-container CPU + memory load from cgroup v2.
-///
-/// Samples CPU over a short interval (~200 ms), so this call briefly
-/// awaits.
+/// Live per-agent-container CPU + memory load from cgroup v2. Samples
+/// CPU over a short interval (~200 ms), so this call briefly awaits.
 #[utoipa::path(
     get,
     path = "/api/container-resources",
@@ -114,10 +109,9 @@ pub(super) async fn api_container_resources() -> Response {
     axum::Json(crate::container_stats::gather().await).into_response()
 }
 
-/// Most-recent agent-initiated privileged-action
-/// audit entries, newest first (server-clamped to 500).
-///
-/// Backs the operator dashboard's audit view. Returns
+/// `GET /api/audit-log` — most-recent agent-initiated privileged-action
+/// audit entries, newest first (server-clamped to 500). Backs the
+/// operator dashboard's audit view. Returns
 /// `{ "entries": [AuditEntry…], "total": N }` so the UI can show
 /// "latest 500 of N" rather than silently capping. `ts_unix` is in
 /// **seconds**.
@@ -144,12 +138,11 @@ pub(super) async fn api_audit_log(State(state): State<AppState>) -> Response {
 }
 
 /// Operator-driven "clear this agent's inbox" — backs the side-panel
-/// "mark all read" button.
-///
-/// Marks every message addressed to the agent as acked (backfilling
-/// `delivered_at` for any still-pending rows so vacuum can collect
-/// them). Returns `{ "marked": N }` so the frontend can show "cleared
-/// N messages" feedback without an extra fetch.
+/// "mark all read" button. Marks every message addressed to the
+/// agent as acked (backfilling `delivered_at` for any still-pending
+/// rows so vacuum can collect them). Returns `{ "marked": N }` so the
+/// frontend can show "cleared N messages" feedback without an extra
+/// fetch.
 #[utoipa::path(
     post,
     path = "/api/agent/{name}/mark-all-read",
@@ -193,7 +186,7 @@ pub(super) struct OpSendForm {
     body: String,
 }
 
-/// Operator compose: drop a message into the
+/// `POST /api/op-send` — operator compose: drop a message into the
 /// broker addressed to `to` (or `*` to broadcast).
 #[utoipa::path(
     post,
@@ -249,7 +242,7 @@ pub(super) struct RequestSpawnForm {
     name: String,
 }
 
-/// Queue a spawn approval for `name`.
+/// `POST /api/request-spawn` — queue a spawn approval for `name`.
 #[utoipa::path(
     post,
     path = "/api/request-spawn",

hive-c0re/src/dashboard/permissions.rs

@@ -37,7 +37,7 @@ pub(super) struct ToolGroupsSnapshot {
     effective: std::collections::BTreeMap<String, Vec<String>>,
 }
 
-/// Every known tool-group name + description,
+/// `GET /api/tool-groups` — every known tool-group name + description,
 /// plus the per-agent explicit/effective assignment maps.
 #[utoipa::path(
     get,
@@ -119,7 +119,7 @@ pub(super) struct SetToolGroupsBody {
     groups: Vec<String>,
 }
 
-/// Replace `agent`'s explicit tool-group
+/// `POST /api/tool-groups/{agent}` — replace `agent`'s explicit tool-group
 /// assignment (JSON body `{"groups": [...]}`).
 #[utoipa::path(
     post,
@@ -187,7 +187,7 @@ pub(super) struct CapabilitiesSnapshot {
     effective: std::collections::BTreeMap<String, Vec<String>>,
 }
 
-/// Every known capability name + description,
+/// `GET /api/capabilities` — every known capability name + description,
 /// plus the per-agent explicit/effective grant maps.
 #[utoipa::path(
     get,
@@ -227,7 +227,7 @@ pub(super) struct SetCapabilitiesBody {
     caps: Vec<String>,
 }
 
-/// Replace `agent`'s explicit capability
+/// `POST /api/capabilities/{agent}` — replace `agent`'s explicit capability
 /// grant set (JSON body `{"caps": [...]}`).
 #[utoipa::path(
     post,
@@ -299,14 +299,13 @@ pub(super) struct BatchPermsBody {
 /// `(logical agent, new groups?, new caps?)`.
 type StagedPerm = (String, Option<Vec<String>>, Option<Vec<String>>);
 
-/// Batch permission apply — `POST /api/permissions`.
-///
-/// The save-all permissions UI sends only the perm-types that actually
-/// changed per agent; each affected agent gets ONE combined
-/// `PermChange`, so the dedup key collapses to `(kind, agent)` and an
-/// agent whose caps AND groups both changed rebuilds once, not twice.
-/// The whole batch is atomic: every change is validated up front and
-/// on any validation error nothing is written or enqueued.
+/// Batch permission apply — `POST /api/permissions`. The save-all
+/// permissions UI sends only the perm-types that actually changed per
+/// agent; each affected agent gets ONE combined `PermChange`, so the
+/// dedup key collapses to `(kind, agent)` and an agent whose caps AND
+/// groups both changed rebuilds once, not twice. The whole batch is
+/// atomic: every change is validated up front and on any validation
+/// error nothing is written or enqueued.
 #[utoipa::path(
     post,
     path = "/api/permissions",
@@ -383,7 +382,7 @@ pub(super) struct StalePermsResponse {
     stale: Vec<String>,
 }
 
-/// Agent names with explicit permission
+/// `GET /api/permissions/stale` — agent names with explicit permission
 /// entries but no matching live container or kept-state dir.
 #[utoipa::path(
     get,
@@ -429,12 +428,11 @@ pub(super) async fn get_stale_permissions(
 }
 
 /// Clear all explicit permission entries for a named agent without
-/// requiring it to exist in the live roster.
-///
-/// Used by the P3RM1SS10NS tab's "remove" button for agents that have
-/// stale explicit entries in `tool-groups.json` / `capabilities.json`
-/// but are no longer running (e.g. an agent that was renamed or
-/// destroyed while its JSON entries persisted).
+/// requiring it to exist in the live roster. Used by the P3RM1SS10NS
+/// tab's "remove" button for agents that have stale explicit entries
+/// in `tool-groups.json` / `capabilities.json` but are no longer
+/// running (e.g. an agent that was renamed or destroyed while its
+/// JSON entries persisted).
 ///
 /// Bypasses `guard_agent_name`'s live-roster check intentionally —
 /// the whole point is to remove entries for non-roster agents. Only

hive-c0re/src/dashboard/questions.rs

@@ -38,7 +38,7 @@ fn with_cors(resp: impl IntoResponse) -> Response {
     resp
 }
 
-/// Record the operator's answer and
+/// `POST /answer-question/{id}` — record the operator's answer and
 /// notify the asker.
 #[utoipa::path(
     post,
@@ -94,14 +94,14 @@ pub(super) async fn post_answer_question(
     with_cors(resp)
 }
 
-/// Resolve a pending question with the
+/// Resolve a pending operator question with a sentinel answer when
+/// the operator decides not to / can't answer. The asker harness
+/// receives a `QuestionAnswered` event with `answer = "[cancelled]"`
+/// so it can fall back on whatever default it had. Same code path as
+/// a real answer — just lets the operator close the loop instead of
+/// letting the question dangle forever.
+/// `POST /cancel-question/{id}` — resolve a pending question with the
 /// `[cancelled]` sentinel answer.
-///
-/// Used when the operator decides not to / can't answer. The asker
-/// harness receives a `QuestionAnswered` event with
-/// `answer = "[cancelled]"` so it can fall back on whatever default
-/// it had. Same code path as a real answer — just lets the operator
-/// close the loop instead of letting the question dangle forever.
 #[utoipa::path(
     post,
     path = "/api/cancel-question/{id}",

hive-c0re/src/dashboard/schedules.rs

@@ -18,11 +18,9 @@ use crate::scheduled_prompts_worker::FireNowReport;
 
 use super::{AppState, error_problem, error_response};
 
-/// Snapshot of every schedule for the
-/// scheduled-prompts tab.
-///
-/// Returns the wire shape directly so the frontend can render
-/// without an extra translation layer.
+/// `GET /api/schedules` — snapshot of every schedule for the
+/// scheduled-prompts tab. Returns the wire shape directly
+/// so the frontend can render without an extra translation layer.
 // `hive_sh4re::WireSchedule` (the actual body) has no `ToSchema` — adding
 // one would pull `utoipa` into the wire-types crate for a single dashboard
 // endpoint. `serde_json::Value` placeholder; see the batch report.
@@ -59,12 +57,11 @@ pub(super) async fn api_schedules(State(state): State<AppState>) -> Response {
     }
 }
 
-/// Operator-direct schedule creation
-/// (mara: "user can add them manually").
-///
-/// Accepts the same `SchedulePromptPayload` shape as the manager
-/// request flow but skips the approval gate — the operator click
-/// *is* the approval. The schedule lands directly with
+/// `POST /api/schedules` — operator-direct schedule creation
+/// (mara: "user can add them manually"). Accepts the same
+/// `SchedulePromptPayload` shape as the manager request flow but
+/// skips the approval gate — the operator click *is* the
+/// approval. The schedule lands directly with
 /// `source = Operator` and the worker picks it up at fire time.
 #[utoipa::path(
     post,
@@ -122,16 +119,14 @@ pub(super) struct FireNowBody {
     reset_timer: bool,
 }
 
-/// Operator-initiated
-/// out-of-band fire of a scheduled prompt.
-///
-/// Runs the per-target fan-out once immediately and reports
-/// per-target outcome counts. One-shot schedules are consumed
-/// (cancelled) by a manual fire — the operator's intent is "send
-/// this now, the scheduled time was wrong." For recurring schedules
-/// the cadence stays intact unless the body carries
-/// `{"reset_timer": true}`, in which case the countdown is re-armed
-/// from now (`next_fire_at = now + interval`).
+/// `POST /api/schedules/{id}/fire-now` — operator-initiated
+/// out-of-band fire of a scheduled prompt. Runs the per-target
+/// fan-out once immediately and reports per-target outcome counts.
+/// One-shot schedules are consumed (cancelled) by a manual fire —
+/// the operator's intent is "send this now, the scheduled time was
+/// wrong." For recurring schedules the cadence stays intact unless
+/// the body carries `{"reset_timer": true}`, in which case the
+/// countdown is re-armed from now (`next_fire_at = now + interval`).
 #[utoipa::path(
     post,
     path = "/api/schedules/{id}/fire-now",
@@ -158,7 +153,7 @@ pub(super) async fn post_schedule_fire_now(
     }
 }
 
-/// Drop still-queued work from the job
+/// `POST /api/rebuild-queue/{id}/cancel` — drop still-queued work from the job
 /// queue.
 ///
 /// `id` is a **node** id. A DAG's root cancels the whole group (the scheduler
@@ -248,20 +243,18 @@ where
     T::deserialize(deserializer).map(Some)
 }
 
-/// Partial update of an existing
-/// schedule.
-///
-/// Mutable fields: `body`, `description`, `interval_seconds`,
-/// `next_fire_at_unix`, plus the target set via `targets_add` /
-/// `targets_remove`. Both target lists are applied in the same
-/// transaction as the scalar fields with removes-before-adds;
-/// re-adding a previously-removed target resets per-target history
-/// (fresh start); draining all targets auto-cancels the parent
-/// schedule. JSON body uses missing-key = "leave alone", explicit
-/// null = "clear" for `description` + `interval_seconds`. Cancelled
-/// schedules are refused — submit a new one instead. Returns the
-/// updated `WireSchedule` so the caller's post-edit refresh has the
-/// new state inline.
+/// `PATCH /api/schedules/{id}` — partial update of an existing
+/// schedule. Mutable fields: `body`, `description`,
+/// `interval_seconds`, `next_fire_at_unix`, plus the target set
+/// via `targets_add` / `targets_remove`. Both target lists
+/// are applied in the same transaction as the scalar fields with
+/// removes-before-adds; re-adding a previously-removed target
+/// resets per-target history (fresh start); draining all targets
+/// auto-cancels the parent schedule. JSON body uses missing-key
+/// = "leave alone", explicit null = "clear" for `description` +
+/// `interval_seconds`. Cancelled schedules are refused — submit
+/// a new one instead. Returns the updated `WireSchedule` so the
+/// caller's post-edit refresh has the new state inline.
 #[utoipa::path(
     patch,
     path = "/api/schedules/{id}",
@@ -299,11 +292,9 @@ pub(super) async fn patch_schedule(
     }
 }
 
-/// Pause a schedule so the worker
-/// skips it until explicitly resumed.
-///
-/// Idempotent; no-op on an already-paused row. Returns 404 when the
-/// schedule is cancelled or not found.
+/// `POST /api/schedules/{id}/pause` — pause a schedule so the worker
+/// skips it until explicitly resumed. Idempotent; no-op on an already-
+/// paused row. Returns 404 when the schedule is cancelled or not found.
 #[utoipa::path(
     post,
     path = "/api/schedules/{id}/pause",
@@ -334,8 +325,7 @@ pub(super) async fn post_schedule_pause(
     }
 }
 
-/// Resume a paused schedule.
-///
+/// `POST /api/schedules/{id}/resume` — resume a paused schedule.
 /// Idempotent; no-op on an already-active row. Returns 404 when the
 /// schedule is cancelled or not found.
 #[utoipa::path(
@@ -368,12 +358,10 @@ pub(super) async fn post_schedule_resume(
     }
 }
 
-/// Operator-side cancel
+/// `POST /api/schedules/{id}/cancel` — operator-side cancel
 /// (whole schedule when no `targets` field, partial when one is
-/// provided).
-///
-/// Operator bypasses the topology check; the manager surface
-/// enforces it for agent callers.
+/// provided). Operator bypasses the topology check; the manager
+/// surface enforces it for agent callers.
 #[utoipa::path(
     post,
     path = "/api/schedules/{id}/cancel",

hive-c0re/src/dashboard/state_files.rs

@@ -18,9 +18,6 @@ use crate::paths::{AGENTS_ROOT, SHARED_ROOT};
 
 #[derive(Deserialize, IntoParams)]
 pub(super) struct StateFileQuery {
-    /// Absolute path under an agent's `state/` dir or under `shared/`;
-    /// checked against the allow-list (`docs/security.md::State-file
-    /// endpoint`).
     path: String,
 }
 
@@ -167,10 +164,10 @@ pub fn scan_validated_paths(body: &str) -> Vec<String> {
     out
 }
 
-/// Serve an allow-listed file.
-///
-/// Raster images get their real content-type; everything else is
-/// served as (possibly truncated) text.
+/// `GET /api/state-file?path=…` — serve an allow-listed per-agent
+/// `state/` or `shared/` file. Raster images get their real
+/// content-type; everything else is served as (possibly truncated)
+/// text.
 #[utoipa::path(
     get,
     path = "/api/state-file",

hive-c0re/src/dashboard/state_snapshot.rs

@@ -293,12 +293,10 @@ where
 /// minutes.
 const CRASH_WARNING_WINDOW: std::time::Duration = std::time::Duration::from_mins(10);
 
-/// Cold-load snapshot of the whole dashboard.
-///
-/// Includes the roster, approvals (+ history), questions (+ history),
-/// tombstones, job queue, meta inputs, and more. Live clients then
-/// follow `/api/dashboard/stream` (SSE) for incremental updates keyed
-/// off `seq`.
+/// `GET /api/state` — cold-load snapshot of the whole dashboard: roster,
+/// approvals (+ history), questions (+ history), tombstones, job queue,
+/// meta inputs, and more. Live clients then follow `/api/dashboard/stream`
+/// (SSE) for incremental updates keyed off `seq`.
 // `StateSnapshot` is a large tree of nested view types (`ContainerView`,
 // `ApprovalView`, `QuestionView`, ...) with no `ToSchema` anywhere in that
 // graph; wiring it up is a schema-modelling project of its own, well past

hive-c0re/src/dashboard/tombstones.rs

@@ -104,7 +104,7 @@ pub(crate) async fn emit_tombstones_snapshot(coord: &Arc<Coordinator>) {
     });
 }
 
-/// Wipe a tombstoned agent's
+/// `POST /api/purge-tombstone/{name}` — wipe a tombstoned agent's
 /// retained state dir + applied config dir entirely.
 #[utoipa::path(
     post,

hive-c0re/src/dashboard/topology.rs

@@ -47,8 +47,7 @@ pub(super) struct SetParentBulkEntry {
     new_parent: Option<String>,
 }
 
-/// Operator-driven parent move.
-///
+/// `POST /api/topology/set-parent` — operator-driven parent move.
 /// Form fields: `child` (required, agent name), `new_parent`
 /// (optional — empty / absent string ⇒ promote to root). Refuses
 /// cycles and unknown agents (surfaced async on the job view — this
@@ -103,13 +102,12 @@ pub(super) async fn post_set_parent(
     Ok((StatusCode::OK, "ok").into_response())
 }
 
-/// Move multiple agents in a
-/// single request, producing **one** git commit.
-///
-/// JSON body: `[{"child":"name", "new_parent":"target-or-null"}, ...]`.
-/// Empty array is a no-op (200 OK). First identifier that fails to
-/// parse aborts the whole batch before anything is submitted — a
-/// partially-invalid bulk move never reaches the queue.
+/// `POST /api/topology/set-parent-bulk` — move multiple agents in a single
+/// request, producing **one** git commit. JSON body: `[{"child":"name",
+/// "new_parent":"target-or-null"}, ...]`. Empty array is a no-op (200 OK).
+/// First identifier that fails to parse aborts the whole batch before
+/// anything is submitted — a partially-invalid bulk move never reaches
+/// the queue.
 #[utoipa::path(
     post,
     path = "/api/topology/set-parent-bulk",

hive-c0re/src/dashboard/webhook.rs

@@ -58,10 +58,8 @@ pub(super) struct PushWebhookRepo {
 }
 
 /// POST `/webhook/knowledge` — Forgejo push webhook for
-/// `internal/knowledge`.
-///
-/// Runs `git pull` on the local clone so agents see up-to-date documents
-/// on their next turn.
+/// `internal/knowledge`. Runs `git pull` on the local clone so
+/// agents see up-to-date documents on their next turn.
 ///
 /// Expected Forgejo webhook configuration:
 /// - URL: `https://<HYPERHIVE_HIVE_DOMAIN>/webhook/knowledge`