docs: the swarm mints agent forge tokens; hive-c0re and tea-login no longer do

credentials.md gains the forge-token row and drops the claim that the
forge token never passes through the store. setup.md says plainly that
an agent spawned on the hive alone, ruth's bootstrap included, now gets
no forge user from anything. CLI references regenerated.

Refs #3782

docs/tools/forge.md

@@ -14,7 +14,8 @@ markdown-docs > docs/tools/forge-cli.md`.
 
 ## Credentials and repo defaults
 
-- Credentials: `$HYPERHIVE_STATE_DIR/forge-token`
+- Credentials: `$HIVE_FORGE_TOKEN_FILE` (the token the agent fetched from
+  the swarm secret store), else `$HYPERHIVE_STATE_DIR/forge-token`
 - Active repo resolves, highest priority first: global `-r/--repo` flag
   > the `origin` remote of the cwd's git checkout > `$HIVE_FORGE_REPO`
   (last-resort override, unset by default) > a hard error.

docs/tools/hivectl-cli.md

@@ -103,22 +103,22 @@ Manual entry point to the same idempotent provisioning c0re runs at boot — for
 
 ###### **Subcommands:**
 
-* `create-user` — Create or refresh the Forgejo account + token for `<name>`
+* `create-user` — Create or refresh a non-agent Forgejo account + token for `<name>`
 * `reconcile-config` — Show + reconcile the divergence between an agent's local applied config checkout and its forge `agent-configs/<agent>` main
 
 
 
 ## `hivectl forge create-user`
 
-Create or refresh the Forgejo account + token for `<name>`.
+Create or refresh a non-agent Forgejo account + token for `<name>`.
 
-For an existing agent, persists the token to its state dir; for a human/other account, prints the token to stdout. Set a password to enable forge web-UI login (otherwise it uses a random throwaway).
+Prints the token to stdout. Set a password to enable forge web-UI login (otherwise it uses a random throwaway). Refused for an existing agent: swarm-controller mints an agent's token (`swarmctl agent mint-forge-token <agent>`).
 
 **Usage:** `hivectl forge create-user [OPTIONS] <NAME>`
 
 ###### **Arguments:**
 
-* `<NAME>` — Forgejo username. For agents: the container/agent name (`<n>` in `h-<n>`; manager uses the literal `manager`). For humans: any forgejo username — `mara`, `damocles`, etc
+* `<NAME>` — Forgejo username of a human/other account — `mara`, `damocles`, etc
 
 ###### **Options:**
 

docs/tools/hivectl.md

@@ -29,7 +29,7 @@ at boot. Useful for recovery, ad-hoc re-provisioning, or fixing a single
 agent without bouncing the daemon.
 
 ```bash
-hivectl forge create-user iris          # provision (or refresh) forge account for agent `iris`
+hivectl forge create-user iris          # refused: `iris` is an agent; use `swarmctl agent mint-forge-token iris`
 hivectl forge create-user mara          # create forge account for a human user; prints token to stdout
 hivectl forge create-user mara --password hunter2  # set a web-login password
 hivectl forge create-user mara --password-stdin    # read password from stdin (safer for scripting)
@@ -40,8 +40,9 @@ hivectl forge reconcile-config iris --verbose      # include the full diff, not
 ```
 
 - For **agents** (name has a state dir under `/var/lib/hyperhive/agents/`):
-  `create-user` persists the token to `<state>/forge-token`. Re-running refreshes the
-  token (idempotent — scope always matches current `TOKEN_SCOPES`).
+  `create-user` refuses. swarm-controller mints an agent's token into
+  the swarm secret store; `swarmctl agent mint-forge-token <agent>` checks
+  and, if needed, re-mints it.
 - For **non-agents** (humans): creates the account and prints the token to
   stdout, creating no state dir. Re-running after account already exists
   re-mints the token and prints it again — safe for password resets.

docs/tools/swarmctl-cli.md

@@ -8,6 +8,7 @@ This document contains the help content for the `swarmctl` command-line program.
 * [`swarmctl agent`↴](#swarmctl-agent)
 * [`swarmctl agent create`↴](#swarmctl-agent-create)
 * [`swarmctl agent mint-identity`↴](#swarmctl-agent-mint-identity)
+* [`swarmctl agent mint-forge-token`↴](#swarmctl-agent-mint-forge-token)
 * [`swarmctl user`↴](#swarmctl-user)
 * [`swarmctl user add`↴](#swarmctl-user-add)
 * [`swarmctl user update`↴](#swarmctl-user-update)
@@ -45,6 +46,7 @@ Manage agents across the swarm
 
 * `create` — Queue creation of a new agent on a hive in this swarm
 * `mint-identity` — Queue a re-mint of an existing agent's identity at the swarm's secret store
+* `mint-forge-token` — Check one agent's forge token, and mint it if it's missing or stale
 
 
 
@@ -104,6 +106,28 @@ Queues and returns, the same way `agent create` does — watch the swarm UI's jo
 
 
 
+## `swarmctl agent mint-forge-token`
+
+Check one agent's forge token, and mint it if it's missing or stale.
+
+swarm-controller does this for every agent with a store identity at start and every five minutes; this is for when waiting isn't an option. It leaves a current token alone.
+
+Queues and returns, the same way `agent create` does — watch the swarm UI's job view for the outcome.
+
+**Usage:** `swarmctl agent mint-forge-token [OPTIONS] <NAME>`
+
+###### **Arguments:**
+
+* `<NAME>` — Name of an agent that already exists
+
+###### **Options:**
+
+* `--controller-socket <PATH>` — swarm-controller's unix socket.
+
+   Supplied by the nix module that installs this binary, from the same `socketPath` option the daemon binds; falls back to `SWARM_CONTROLLER_SOCKET`.
+
+
+
 ## `swarmctl user`
 
 Manage subjects in the swarm's SSO provider