feat(#2554): add hivectl forge reconcile-config to reconcile local applied config against forge main

docs/tools/hivectl-cli.md

@@ -7,6 +7,7 @@ This document contains the help content for the `hivectl` command-line program.
 * [`hivectl`↴](#hivectl)
 * [`hivectl forge`↴](#hivectl-forge)
 * [`hivectl forge create-user`↴](#hivectl-forge-create-user)
+* [`hivectl forge reconcile-config`↴](#hivectl-forge-reconcile-config)
 * [`hivectl matrix`↴](#hivectl-matrix)
 * [`hivectl matrix create-user`↴](#hivectl-matrix-create-user)
 * [`hivectl matrix sync-admin`↴](#hivectl-matrix-sync-admin)
@@ -99,6 +100,7 @@ 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>`
+* `reconcile-config` — Show + reconcile the divergence between an agent's local applied config checkout and its forge `agent-configs/<agent>` main
 
 
 
@@ -121,6 +123,32 @@ For an existing agent, persists the token to its state dir; for a human/other ac
 
 
 
+## `hivectl forge reconcile-config`
+
+Show + reconcile the divergence between an agent's local applied config checkout and its forge `agent-configs/<agent>` main.
+
+Always prints the diff first. `--from forge` resets the local checkout to forge main (effective on the next deploy); `--from local` is not supported yet. With no `--from`, prompts for the direction.
+
+**Usage:** `hivectl forge reconcile-config [OPTIONS] <AGENT>`
+
+###### **Arguments:**
+
+* `<AGENT>` — Agent whose config branches to reconcile
+
+###### **Options:**
+
+* `--from <FROM>` — Which side to reconcile from. Omit to be prompted after the diff
+
+  Possible values:
+  - `forge`:
+    Reset the local applied checkout to forge main
+  - `local`:
+    Advance forge main from local — not supported yet
+
+* `--verbose` — Include the full diff (not just `--stat`) in the report
+
+
+
 ## `hivectl matrix`
 
 matrix-tuwunel user provisioning.

docs/tools/hivectl.md

@@ -28,6 +28,10 @@ hivectl forge create-user iris          # provision (or refresh) forge account f
 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)
+
+hivectl forge reconcile-config iris             # show local-applied <-> forge config divergence, then prompt
+hivectl forge reconcile-config iris --from forge   # reset local applied checkout to forge main (effective next deploy)
+hivectl forge reconcile-config iris --verbose      # include the full diff, not just --stat
 ```
 
 - For **agents** (name has a state dir under `/var/lib/hyperhive/agents/`):
@@ -38,6 +42,12 @@ hivectl forge create-user mara --password-stdin    # read password from stdin (s
   re-mints the token and prints it again — safe for password resets.
 - Without `--password` / `--password-stdin` a random throwaway password
   is used (fine for agents — they auth by token).
+- `reconcile-config <agent>` shows the divergence between the agent's local
+  applied config checkout and its forge `agent-configs/<agent>` `main`, then
+  reconciles. `--from forge` resets the local checkout to forge `main` (takes
+  effect on the next deploy — it does not auto-rebuild). `--from local` is not
+  supported yet (forge `main` is core-only branch-protected; resolve via a
+  config PR). With no `--from` it prompts for the direction after the diff.
 
 ## Matrix