@mrciphersmith/keryx 0.2.155 → 0.2.156

package/README.md

@@ -439,8 +439,13 @@ Grouped by what you are trying to do, not by internal module layout.
   human **owner** (`flow init --owner`/`flow owner set`, never inferred), and
   `ac confirm`/`complete` append an honest, append-only **signature** — who
   acted, when, and what was signed, with its basis (`stated`/`derived`/
-  `unknown`) stated rather than assumed. See
-  [TM-02](docs/decisions/keryx-harness/TM-02-flow-owner-and-signed-completion.md).
+  `unknown`) stated rather than assumed. A flow can also require a
+  terminal-minted **confirmation token** (`flow init --require-confirmation`,
+  `flow confirm`) that no agent tool can mint. It adds friction for an agent
+  but does not prove a person was present. `flow recover` returns a flow left
+  in `completing` by an interrupted run. See
+  [TM-02](docs/decisions/keryx-harness/TM-02-flow-owner-and-signed-completion.md)
+  and [TM-03](docs/decisions/keryx-harness/TM-03-terminal-confirmation-token.md).
 - **triggers** — declared automation over `.metaproject/triggers.json` (a
   repository event or a cron/systemd schedule): `reconcile`/`rebuild` keep the
   graph and wiki current, `open-flow` opens Task Manager work, and `flow-next`
@@ -453,9 +458,45 @@ Grouped by what you are trying to do, not by internal module layout.
   USD recorded, and a per-trigger spend ceiling on top of the project-wide one.
   `keryx trigger install` extends the same hook files `sync install-hooks` and
   `update` already write into; `keryx trigger schedule` prints a cron line or
-  systemd unit pair and runs no daemon of its own. Triggered runs and a manual
+  systemd unit pair (with a real `OnCalendar=`) and runs no daemon of its own. Triggered runs and a manual
   `sync --apply`/`gdgraph build` share one maintenance lock (manual waits,
-  triggered refuses). See the [CLI reference](docs/docs/cli-reference.md#trigger).
+  triggered refuses). In the TUI, the sidebar's **Triggers** section lists the
+  event-fired triggers. Each row shows the last outcome and its age, and a `NET`
+  marker when the agent gets the host network. The section also shows project
+  trigger spend and any open spend reservations. `/triggers` (or a click)
+  opens a list+detail modal with the full unattended posture. There, `r` then
+  `y` runs one now as `keryx trigger run <name>` in a child process of the same
+  build, bound by the same locks, budgets and refusals as the CLI. See the
+  [CLI reference](docs/docs/cli-reference.md#trigger).
+- **schedule**: scheduled agent tasks in the background. Say it in the shell ("schedule a task every
+  4 hours to check my open PRs"), use `/schedule`, or run `keryx schedule add`. keryx shows a
+  **confirmation card** listing the cadence and next runs, the prompt, the runner and its budget,
+  the network mode, and every granted tool with the account it acts as. It also shows exactly what
+  will be installed. Nothing is written until you say yes. After that, keryx stores the schedule in a
+  per-machine, gitignored store and installs a `systemd --user` timer (launchd on macOS, cron
+  elsewhere) that runs `keryx trigger run <name>` unattended. The run leaves a report in
+  `.metaproject/data/trigger/reports/`.
+  - **Granted tools** (`gh pr list/view/checks`, `gh issue list/view`, `gh run list`) run
+    **outside** the sandbox with your credentials. The model sees only redacted output, and the
+    token never enters the sandbox, the model context or the report.
+  - **Network:** the agent's shell network is `off`, `full`, or `allowlist` (Linux
+    only) — reaches only the domains you name, through a loopback proxy keryx runs
+    outside the sandbox; it governs only the agent's own shell commands, never the
+    model call or a granted tool. See the [CLI reference](docs/docs/cli-reference.md#schedule).
+  - **Refusals:** the unattended floor is unchanged, and an entry edited after you confirmed it is
+    refused (`grants-changed`).
+  - **Tracking:** every run is spend-bounded and appears in `keryx trigger status` and
+    `keryx governance report`.
+  - **Management:** `keryx schedule list|show|pause|resume|run|remove`. In `keryx shell`:
+    - the sidebar's **Schedules** section shows each schedule's next run and last outcome;
+    - `/schedules` (or a click) opens the detail: Overview, Grants, Runs, Report;
+    - `p` pauses or resumes, `r` then `y` runs it now, `d` then `y` deletes it;
+    - a run finished in the background shows up without a restart.
+  - **Limits:** the machine must be on. systemd and launchd catch up one missed run after a boot or
+    wake; cron does not. Without linger, a user timer does not run while you are logged out, and
+    keryx never enables linger for you. The hardened sandbox is Linux-only.
+
+  See the [CLI reference](docs/docs/cli-reference.md#schedule).
 - **governance** — `keryx governance report`, one read-only report unifying what
   is already recorded: review-round spend per flow (USD and tokens, with a
   rounds-with-cost/rounds-total count for partial coverage), project-wide
@@ -465,7 +506,14 @@ Grouped by what you are trying to do, not by internal module layout.
   outcomes. A figure nobody recorded is reported as "not recorded", never as
   zero. Writes `.metaproject/data/governance/artifacts/latest.{md,json}`, the
   same convention `keryx health run` uses; `--all-projects` also covers every
-  project in the user-global registry. See the
+  project in the user-global registry. In the TUI, the sidebar's
+  **Governance** row shows `no report — click to run`,
+  `unreadable — click for reason`, `running…`, `last report <date>` or
+  `failed — click to retry`. With no report, a click
+  (or `/governance`) runs the report in the background, and the row updates
+  when it finishes. With a report, a click opens it in a scrollable modal,
+  where `r` re-runs it. Sessions written by `keryx agents external run` appear
+  in `/sessions` marked `acp:<agent>`. See the
   [CLI reference](docs/docs/cli-reference.md#governance).
 - **security** — deterministic secrets / PII / prompt-injection / egress
   scanning, redaction, and a policy gate at agent write seams, with a committed
@@ -478,7 +526,8 @@ Grouped by what you are trying to do, not by internal module layout.
   (Facts / Work / Know-how) overview, evidence-linked wrap-up proposals with owner
   review, and a fail-closed runtime policy guard. Driven by `keryx workspace`
   (`keryx modules enable sac` to turn it on); accepting a proposal into real
-  project knowledge always passes through a human `confirm-review`, which
+  project knowledge always passes through an approval-gated `confirm-review`
+  (friction for an agent, not proof of a person — see TM-03), which
   refuses a security-flagged proposal until `--acknowledge-security` records
   that someone read the findings. The TUI's `/review` modal offers the same
   acknowledgement as an explicit `[s]` action, never as an automatic fallback