docs: update turn-loop get_loose_ends, add hive-forge and cp gotchas

docs/gotchas.md

@@ -106,3 +106,29 @@ If state dirs are wiped out from under a pending approval (test
 scripts, manual `rm -rf`), the dashboard's next render marks them
 `failed` with note `"agent state dir missing"` so they fall out of
 `pending`. They stay in sqlite for audit.
+
+## Nix store `cp -r` preserves read-only bits
+
+Copying a nix store path with `cp -r src/. $out/` inside a
+`pkgs.runCommand` derivation preserves the read-only permissions of
+store files. Any subsequent write into the copied tree (adding new
+files in subdirectories) fails with `EPERM`. Fix: pass
+`--no-preserve=mode,ownership` so the output tree is writable.
+
+## `hive-forge`: prefer over raw curl pipelines
+
+Every agent container has `hive-forge` in PATH (installed via
+`harness-base.nix`). Use it instead of ad-hoc curl pipelines:
+
+```bash
+hive-forge view 42          # title + body + comments
+hive-forge comment 42 "..."  # post comment
+hive-forge assign 42 damocles
+hive-forge close 42
+hive-forge labels 42 add feature
+hive-forge pr 42            # PR metadata as JSON
+hive-forge branches deployed/  # filter branches by pattern
+```
+
+Credentials come from `$HYPERHIVE_STATE_DIR/forge-token`;
+default repo from `$HIVE_FORGE_REPO`.

docs/turn-loop.md

@@ -303,10 +303,10 @@ meta's.
   hive-c0re resolves the machine name (`h-<name>`, manager
   `hm1nd`). `lines` defaults to 50, host-capped at 500.
 - `remind` / `get_loose_ends` / `cancel_loose_end` / `whoami` —
-  same as the sub-agent tools above, but `get_loose_ends` is
+  same as the sub-agent tools above. `get_loose_ends` scopes to
-  hive-wide (every agent's pending questions + reminders, not
+  the manager's own items by default; pass `agent: "*"` for a
-  just the manager's) and `cancel_loose_end` may cancel any
+  hive-wide view, or `agent: "<name>"` to inspect one agent.
-  agent's row.
+  `cancel_loose_end` may cancel any agent's row.
 
 The boundary: lifecycle ops on *existing* sub-agents
 (`kill`/`start`/`restart`) are at the manager's discretion — no