From 29bc40a1d7d7531f8485b833eb42ce4e98a92e73 Mon Sep 17 00:00:00 2001
From: damocles <damocles@hyperhive.local>
Date: Thu, 4 Jun 2026 21:48:16 +0200
Subject: [PATCH] docs: document get_host_journal in scheduling.md and
 turn-loop.md

---
 docs/tools/scheduling.md | 23 +++++++++++++++++++++++
 docs/turn-loop.md        |  5 +++++
 2 files changed, 28 insertions(+)

diff --git a/docs/tools/scheduling.md b/docs/tools/scheduling.md
index 358389e1..325b5c64 100644
--- a/docs/tools/scheduling.md
+++ b/docs/tools/scheduling.md
@@ -60,6 +60,29 @@ errors, or any harness issue you can't see from inside the container.
 Pass the plain logical agent name (e.g. `"gui"`) — hive-c0re resolves
 the machine name (`h-<name>`). `lines` defaults to 50, host-capped at 500.
 
+## `read_host_journal` capability
+
+Capability-gated (not a tool group) — the operator enables it in the
+P3RM1SS10NS C4P4B1L1T13S section. Unlike tool groups this is not
+configurable from `agent.nix`.
+
+### `get_host_journal(unit?, container?, lines?, priority?, grep?, since?, until?)`
+
+Fetch recent lines from the **host** journal (requires
+`read_host_journal` capability). Useful when you need visibility
+outside your own container — infrastructure services, hive-c0re
+lifecycle events, or another container's boot log.
+
+- `unit` — filter to a systemd unit (e.g. `hive-c0re.service`).
+- `container` — nspawn machine name verbatim. Agent containers use
+  the `h-<name>` prefix (e.g. `h-iris`); infrastructure containers
+  use their full name (e.g. `hive-ci`, `hive-forge`, `hive-matrix`,
+  `hive-gateway`). Omit for the host journal.
+- `lines` — how many lines to return (default 30, max 100).
+- `priority` — minimum syslog level (`emerg` … `debug`).
+- `grep` — regex matched against log message fields (`journalctl --grep`).
+- `since` / `until` — time bounds (e.g. `-1h`, `2024-01-01 12:00:00`).
+
 ## See also
 
 - `remind` (no-approval self-wake path) — documented in
diff --git a/docs/turn-loop.md b/docs/turn-loop.md
index fa26aa26..f6644d14 100644
--- a/docs/turn-loop.md
+++ b/docs/turn-loop.md
@@ -356,6 +356,11 @@ at_unix_timestamp?)`, `request_next_turn()`.
 - **Scheduling + diagnostics** (`scheduling`, `diagnostics`) —
   scheduled prompts, `get_logs`. See
   [`docs/tools/scheduling.md`](tools/scheduling.md).
+- **Capability-gated** — `get_host_journal` (requires
+  `read_host_journal` capability set via the P3RM1SS10NS tab;
+  orthogonal to tool groups). Full list of capabilities and their
+  effects in [`docs/conventions.md#capabilities`](../docs/conventions.md).
+  Also documented in [`docs/tools/scheduling.md`](tools/scheduling.md).
 - **Matrix MCP + extra servers** — `mcp__matrix__*` tools and
   per-agent extra MCP config. See
   [`docs/tools/matrix.md`](tools/matrix.md).