@mrciphersmith/keryx 0.3.44 → 0.3.48

package/README.md

@@ -73,9 +73,15 @@ keryx health run --changed   # normalized health report
 keryx dash                   # human admin dashboard
 ```
 
-`keryx init` creates the `.metaproject/` workspace and connects your existing
-`AGENTS.md` / `CLAUDE.md` entrypoints to it, so agents are routed to the right
-module automatically.
+`keryx init` creates the `.metaproject/` workspace and connects your agents to
+it, so they are routed to the right module automatically. It imports your
+`AGENTS.md` / `CLAUDE.md` as project rules and writes its routing block and
+Claude hooks to per-developer, gitignored files (`CLAUDE.local.md`,
+`AGENTS.override.md`, `.claude/settings.local.json`, ignore rules in
+`.git/info/exclude`), so the files your team tracks stay untouched and
+`git pull` never meets an edit made by keryx. A team that wants the block committed opts
+into `scope: "shared"`; see
+[where the block goes](docs/docs/workspace-and-lifecycle.md#where-the-block-goes-local-and-shared-scope).
 
 ### Connect a model provider
 
@@ -123,6 +129,9 @@ described [below](#the-agent-harness). A few commands worth knowing from the
 first session:
 
 - `/theme [name]` opens the theme picker; a choice applies immediately.
+- `/settings` opens one modal with the permission mode, plan, guards, routing,
+  reasoning, theme and external switches, each with its On/Off or value
+  buttons; `/mode` and `/plan` are marked `session`, the rest `saved`.
 - `/mode [ask|trust|auto]` shows or switches the permission mode for the rest
   of the session — see [permission modes](docs/docs/guides/permission-modes.md).
 - `/help` lists every slash command available in the current mode.
@@ -736,13 +745,16 @@ enabled. Nine modules are on after `init`; `mcp` is opt-in.
 
 | Runtime | Integration |
 |---------|-------------|
-| Claude Code | `CLAUDE.md` routing, orientation hook, security hooks, MCP server |
-| Codex | `AGENTS.md` routing and orientation hook |
+| Claude Code | `CLAUDE.local.md` routing, orientation hook, security hooks, MCP server |
+| Codex | `AGENTS.override.md` routing and orientation hook |
 | Cursor | Rules/orientation, security hooks, MCP server |
 | Any other agent | Repository-local Markdown/JSON artifacts under `.metaproject/` |
 
-After `init`, agents follow the root `AGENTS.md`/`CLAUDE.md` pointer to
-`.metaproject/index.md`, which routes them to the right capability. Two commands
+After `init`, agents follow the routing block — in `CLAUDE.local.md` and
+`AGENTS.override.md` by default, in the shared `CLAUDE.md`/`AGENTS.md` under
+`scope: "shared"` — to `.metaproject/index.md`, which routes them to the right
+capability. Those local files exist per checkout: run `keryx update` in a new
+worktree to give it the block and hooks. Two commands
 sharpen that routing:
 
 `keryx orient` emits a bounded excerpt of the launch project's own
@@ -930,7 +942,7 @@ flags too much for your rule set; lower it only if you have evidence the
 agent is actually acting on the extra flags.
 
 ```bash
-keryx review jev-edit-guard install   # merge-safe: writes .claude/settings.json
+keryx review jev-edit-guard install   # merge-safe: writes .claude/settings.local.json
 ```
 
 Then opt in per project — the hook is installed but stays silent until this is set:
@@ -988,6 +1000,26 @@ compared at startup, and a weaker profile refuses to bind at all. See
 [drive keryx remotely](docs/docs/guides/drive-keryx-remotely.md) for routes and
 setup.
 
+### Remote control from Telegram (opt-in, off by default)
+
+`/remote-control` in a running shell mirrors that session into its own topic of a
+Telegram supergroup: you send a line from your phone and it runs as if typed
+there, the reply and any approval question come back to the topic. Nothing
+happens until you set three things up: a separate bot made with BotFather, its
+token in `remote/bot-token` in the global keryx directory with mode 600; the
+Telegram user id that may use it, in the allowlist file `remote/config.json`; and
+a supergroup with topics enabled where that bot is an admin with the manage topics
+right. The Telegram transport is the single poller inside `keryx serve` — shells
+talk to `serve` over loopback with a local shell token (new on every `serve`
+start, and never sent to an endpoint whose `serve` is gone), they never poll
+Telegram themselves, and a second `keryx serve` does not poll while the first one
+runs. At most 500 lines wait per topic, and turning it off tells the topic which
+queued lines will not run.
+Without the config files `serve` starts as before, with remote control off. This
+has been verified against a fake Bot API only; no run against real Telegram has
+been done yet. Setup and limits:
+[drive keryx remotely](docs/docs/guides/drive-keryx-remotely.md#remote-control-from-telegram).
+
 ## CI integration
 
 CI can publish normalized, committable artifacts that humans and agents read