durar-ai 2026.4.4

package/docs/cli/gateway.md

@@ -0,0 +1,307 @@
+---
+summary: "Durar Gateway CLI (`Durar gateway`) — run, query, and discover gateways"
+read_when:
+  - Running the Gateway from the CLI (dev or servers)
+  - Debugging Gateway auth, bind modes, and connectivity
+  - Discovering gateways via Bonjour (local + wide-area DNS-SD)
+title: "gateway"
+---
+
+# Gateway CLI
+
+The Gateway is Durar’s WebSocket server (channels, nodes, sessions, hooks).
+
+Subcommands in this page live under `Durar gateway …`.
+
+Related docs:
+
+- [/gateway/bonjour](/gateway/bonjour)
+- [/gateway/discovery](/gateway/discovery)
+- [/gateway/configuration](/gateway/configuration)
+
+## Run the Gateway
+
+Run a local Gateway process:
+
+```bash
+Durar gateway
+```
+
+Foreground alias:
+
+```bash
+Durar gateway run
+```
+
+Notes:
+
+- By default, the Gateway refuses to start unless `gateway.mode=local` is set in `~/.Durar/Durar.json`. Use `--allow-unconfigured` for ad-hoc/dev runs.
+- `Durar onboard --mode local` and `Durar setup` are expected to write `gateway.mode=local`. If the file exists but `gateway.mode` is missing, treat that as a broken or clobbered config and repair it instead of assuming local mode implicitly.
+- If the file exists and `gateway.mode` is missing, the Gateway treats that as suspicious config damage and refuses to “guess local” for you.
+- Binding beyond loopback without auth is blocked (safety guardrail).
+- `SIGUSR1` triggers an in-process restart when authorized (`commands.restart` is enabled by default; set `commands.restart: false` to block manual restart, while gateway tool/config apply/update remain allowed).
+- `SIGINT`/`SIGTERM` handlers stop the gateway process, but they don’t restore any custom terminal state. If you wrap the CLI with a TUI or raw-mode input, restore the terminal before exit.
+
+### Options
+
+- `--port <port>`: WebSocket port (default comes from config/env; usually `18789`).
+- `--bind <loopback|lan|tailnet|auto|custom>`: listener bind mode.
+- `--auth <token|password>`: auth mode override.
+- `--token <token>`: token override (also sets `Durar_GATEWAY_TOKEN` for the process).
+- `--password <password>`: password override. Warning: inline passwords can be exposed in local process listings.
+- `--password-file <path>`: read the gateway password from a file.
+- `--tailscale <off|serve|funnel>`: expose the Gateway via Tailscale.
+- `--tailscale-reset-on-exit`: reset Tailscale serve/funnel config on shutdown.
+- `--allow-unconfigured`: allow gateway start without `gateway.mode=local` in config. This bypasses the startup guard for ad-hoc/dev bootstrap only; it does not write or repair the config file.
+- `--dev`: create a dev config + workspace if missing (skips BOOTSTRAP.md).
+- `--reset`: reset dev config + credentials + sessions + workspace (requires `--dev`).
+- `--force`: kill any existing listener on the selected port before starting.
+- `--verbose`: verbose logs.
+- `--cli-backend-logs`: only show CLI backend logs in the console (and enable stdout/stderr).
+- `--claude-cli-logs`: deprecated alias for `--cli-backend-logs`.
+- `--ws-log <auto|full|compact>`: websocket log style (default `auto`).
+- `--compact`: alias for `--ws-log compact`.
+- `--raw-stream`: log raw model stream events to jsonl.
+- `--raw-stream-path <path>`: raw stream jsonl path.
+
+## Query a running Gateway
+
+All query commands use WebSocket RPC.
+
+Output modes:
+
+- Default: human-readable (colored in TTY).
+- `--json`: machine-readable JSON (no styling/spinner).
+- `--no-color` (or `NO_COLOR=1`): disable ANSI while keeping human layout.
+
+Shared options (where supported):
+
+- `--url <url>`: Gateway WebSocket URL.
+- `--token <token>`: Gateway token.
+- `--password <password>`: Gateway password.
+- `--timeout <ms>`: timeout/budget (varies per command).
+- `--expect-final`: wait for a “final” response (agent calls).
+
+Note: when you set `--url`, the CLI does not fall back to config or environment credentials.
+Pass `--token` or `--password` explicitly. Missing explicit credentials is an error.
+
+### `gateway health`
+
+```bash
+Durar gateway health --url ws://127.0.0.1:18789
+```
+
+### `gateway usage-cost`
+
+Fetch usage-cost summaries from session logs.
+
+```bash
+Durar gateway usage-cost
+Durar gateway usage-cost --days 7
+Durar gateway usage-cost --json
+```
+
+Options:
+
+- `--days <days>`: number of days to include (default `30`).
+
+### `gateway status`
+
+`gateway status` shows the Gateway service (launchd/systemd/schtasks) plus an optional RPC probe.
+
+```bash
+Durar gateway status
+Durar gateway status --json
+Durar gateway status --require-rpc
+```
+
+Options:
+
+- `--url <url>`: add an explicit probe target. Configured remote + localhost are still probed.
+- `--token <token>`: token auth for the probe.
+- `--password <password>`: password auth for the probe.
+- `--timeout <ms>`: probe timeout (default `10000`).
+- `--no-probe`: skip the RPC probe (service-only view).
+- `--deep`: scan system-level services too.
+- `--require-rpc`: exit non-zero when the RPC probe fails. Cannot be combined with `--no-probe`.
+
+Notes:
+
+- `gateway status` stays available for diagnostics even when the local CLI config is missing or invalid.
+- `gateway status` resolves configured auth SecretRefs for probe auth when possible.
+- If a required auth SecretRef is unresolved in this command path, `gateway status --json` reports `rpc.authWarning` when probe connectivity/auth fails; pass `--token`/`--password` explicitly or resolve the secret source first.
+- If the probe succeeds, unresolved auth-ref warnings are suppressed to avoid false positives.
+- Use `--require-rpc` in scripts and automation when a listening service is not enough and you need the Gateway RPC itself to be healthy.
+- `--deep` adds a best-effort scan for extra launchd/systemd/schtasks installs. When multiple gateway-like services are detected, human output prints cleanup hints and warns that most setups should run one gateway per machine.
+- Human output includes the resolved file log path plus the CLI-vs-service config paths/validity snapshot to help diagnose profile or state-dir drift.
+- On Linux systemd installs, service auth drift checks read both `Environment=` and `EnvironmentFile=` values from the unit (including `%h`, quoted paths, multiple files, and optional `-` files).
+- Drift checks resolve `gateway.auth.token` SecretRefs using merged runtime env (service command env first, then process env fallback).
+- If token auth is not effectively active (explicit `gateway.auth.mode` of `password`/`none`/`trusted-proxy`, or mode unset where password can win and no token candidate can win), token-drift checks skip config token resolution.
+
+### `gateway probe`
+
+`gateway probe` is the “debug everything” command. It always probes:
+
+- your configured remote gateway (if set), and
+- localhost (loopback) **even if remote is configured**.
+
+If you pass `--url`, that explicit target is added ahead of both. Human output labels the
+targets as:
+
+- `URL (explicit)`
+- `Remote (configured)` or `Remote (configured, inactive)`
+- `Local loopback`
+
+If multiple gateways are reachable, it prints all of them. Multiple gateways are supported when you use isolated profiles/ports (e.g., a rescue bot), but most installs still run a single gateway.
+
+```bash
+Durar gateway probe
+Durar gateway probe --json
+```
+
+Interpretation:
+
+- `Reachable: yes` means at least one target accepted a WebSocket connect.
+- `RPC: ok` means detail RPC calls (`health`/`status`/`system-presence`/`config.get`) also succeeded.
+- `RPC: limited - missing scope: operator.read` means connect succeeded but detail RPC is scope-limited. This is reported as **degraded** reachability, not full failure.
+- Exit code is non-zero only when no probed target is reachable.
+
+JSON notes (`--json`):
+
+- Top level:
+  - `ok`: at least one target is reachable.
+  - `degraded`: at least one target had scope-limited detail RPC.
+  - `primaryTargetId`: best target to treat as the active winner in this order: explicit URL, SSH tunnel, configured remote, then local loopback.
+  - `warnings[]`: best-effort warning records with `code`, `message`, and optional `targetIds`.
+  - `network`: local loopback/tailnet URL hints derived from current config and host networking.
+  - `discovery.timeoutMs` and `discovery.count`: the actual discovery budget/result count used for this probe pass.
+- Per target (`targets[].connect`):
+  - `ok`: reachability after connect + degraded classification.
+  - `rpcOk`: full detail RPC success.
+  - `scopeLimited`: detail RPC failed due to missing operator scope.
+
+Common warning codes:
+
+- `ssh_tunnel_failed`: SSH tunnel setup failed; the command fell back to direct probes.
+- `multiple_gateways`: more than one target was reachable; this is unusual unless you intentionally run isolated profiles, such as a rescue bot.
+- `auth_secretref_unresolved`: a configured auth SecretRef could not be resolved for a failed target.
+- `probe_scope_limited`: WebSocket connect succeeded, but detail RPC was limited by missing `operator.read`.
+
+#### Remote over SSH (Mac app parity)
+
+The macOS app “Remote over SSH” mode uses a local port-forward so the remote gateway (which may be bound to loopback only) becomes reachable at `ws://127.0.0.1:<port>`.
+
+CLI equivalent:
+
+```bash
+Durar gateway probe --ssh user@gateway-host
+```
+
+Options:
+
+- `--ssh <target>`: `user@host` or `user@host:port` (port defaults to `22`).
+- `--ssh-identity <path>`: identity file.
+- `--ssh-auto`: pick the first discovered gateway host as SSH target from the resolved
+  discovery endpoint (`local.` plus the configured wide-area domain, if any). TXT-only
+  hints are ignored.
+
+Config (optional, used as defaults):
+
+- `gateway.remote.sshTarget`
+- `gateway.remote.sshIdentity`
+
+### `gateway call <method>`
+
+Low-level RPC helper.
+
+```bash
+Durar gateway call status
+Durar gateway call logs.tail --params '{"sinceMs": 60000}'
+```
+
+Options:
+
+- `--params <json>`: JSON object string for params (default `{}`)
+- `--url <url>`
+- `--token <token>`
+- `--password <password>`
+- `--timeout <ms>`
+- `--expect-final`
+- `--json`
+
+Notes:
+
+- `--params` must be valid JSON.
+- `--expect-final` is mainly for agent-style RPCs that stream intermediate events before a final payload.
+
+## Manage the Gateway service
+
+```bash
+Durar gateway install
+Durar gateway start
+Durar gateway stop
+Durar gateway restart
+Durar gateway uninstall
+```
+
+Command options:
+
+- `gateway status`: `--url`, `--token`, `--password`, `--timeout`, `--no-probe`, `--require-rpc`, `--deep`, `--json`
+- `gateway install`: `--port`, `--runtime <node|bun>`, `--token`, `--force`, `--json`
+- `gateway uninstall|start|stop|restart`: `--json`
+
+Notes:
+
+- `gateway install` supports `--port`, `--runtime`, `--token`, `--force`, `--json`.
+- When token auth requires a token and `gateway.auth.token` is SecretRef-managed, `gateway install` validates that the SecretRef is resolvable but does not persist the resolved token into service environment metadata.
+- If token auth requires a token and the configured token SecretRef is unresolved, install fails closed instead of persisting fallback plaintext.
+- For password auth on `gateway run`, prefer `Durar_GATEWAY_PASSWORD`, `--password-file`, or a SecretRef-backed `gateway.auth.password` over inline `--password`.
+- In inferred auth mode, shell-only `Durar_GATEWAY_PASSWORD` does not relax install token requirements; use durable config (`gateway.auth.password` or config `env`) when installing a managed service.
+- If both `gateway.auth.token` and `gateway.auth.password` are configured and `gateway.auth.mode` is unset, install is blocked until mode is set explicitly.
+- Lifecycle commands accept `--json` for scripting.
+
+## Discover gateways (Bonjour)
+
+`gateway discover` scans for Gateway beacons (`_Durar-gw._tcp`).
+
+- Multicast DNS-SD: `local.`
+- Unicast DNS-SD (Wide-Area Bonjour): choose a domain (example: `Durar.internal.`) and set up split DNS + a DNS server; see [/gateway/bonjour](/gateway/bonjour)
+
+Only gateways with Bonjour discovery enabled (default) advertise the beacon.
+
+Wide-Area discovery records include (TXT):
+
+- `role` (gateway role hint)
+- `transport` (transport hint, e.g. `gateway`)
+- `gatewayPort` (WebSocket port, usually `18789`)
+- `sshPort` (optional; clients default SSH targets to `22` when it is absent)
+- `tailnetDns` (MagicDNS hostname, when available)
+- `gatewayTls` / `gatewayTlsSha256` (TLS enabled + cert fingerprint)
+- `cliPath` (remote-install hint written to the wide-area zone)
+
+### `gateway discover`
+
+```bash
+Durar gateway discover
+```
+
+Options:
+
+- `--timeout <ms>`: per-command timeout (browse/resolve); default `2000`.
+- `--json`: machine-readable output (also disables styling/spinner).
+
+Examples:
+
+```bash
+Durar gateway discover --timeout 4000
+Durar gateway discover --json | jq '.beacons[].wsUrl'
+```
+
+Notes:
+
+- The CLI scans `local.` plus the configured wide-area domain when one is enabled.
+- `wsUrl` in JSON output is derived from the resolved service endpoint, not from TXT-only
+  hints such as `lanHost` or `tailnetDns`.
+- On `local.` mDNS, `sshPort` and `cliPath` are only broadcast when
+  `discovery.mdns.mode` is `full`. Wide-area DNS-SD still writes `cliPath`; `sshPort`
+  stays optional there too.

package/docs/cli/health.md

@@ -0,0 +1,36 @@
+---
+summary: "CLI reference for `Durar health` (gateway health snapshot via RPC)"
+read_when:
+  - You want to quickly check the running Gateway’s health
+title: "health"
+---
+
+# `Durar health`
+
+Fetch health from the running Gateway.
+
+Options:
+
+- `--json`: machine-readable output
+- `--timeout <ms>`: connection timeout in milliseconds (default `10000`)
+- `--verbose`: verbose logging
+- `--debug`: alias for `--verbose`
+
+Examples:
+
+```bash
+Durar health
+Durar health --json
+Durar health --timeout 2500
+Durar health --verbose
+Durar health --debug
+```
+
+Notes:
+
+- Default `Durar health` asks the running gateway for its health snapshot. When the
+  gateway already has a fresh cached snapshot, it can return that cached payload and
+  refresh in the background.
+- `--verbose` forces a live probe, prints gateway connection details, and expands the
+  human-readable output across all configured accounts and agents.
+- Output includes per-agent session stores when multiple agents are configured.

package/docs/cli/hooks.md

@@ -0,0 +1,337 @@
+---
+summary: "CLI reference for `Durar hooks` (agent hooks)"
+read_when:
+  - You want to manage agent hooks
+  - You want to inspect hook availability or enable workspace hooks
+title: "hooks"
+---
+
+# `Durar hooks`
+
+Manage agent hooks (event-driven automations for commands like `/new`, `/reset`, and gateway startup).
+
+Running `Durar hooks` with no subcommand is equivalent to `Durar hooks list`.
+
+Related:
+
+- Hooks: [Hooks](/automation/hooks)
+- Plugin hooks: [Plugin hooks](/plugins/architecture#provider-runtime-hooks)
+
+## List All Hooks
+
+```bash
+Durar hooks list
+```
+
+List all discovered hooks from workspace, managed, extra, and bundled directories.
+
+**Options:**
+
+- `--eligible`: Show only eligible hooks (requirements met)
+- `--json`: Output as JSON
+- `-v, --verbose`: Show detailed information including missing requirements
+
+**Example output:**
+
+```
+Hooks (4/4 ready)
+
+Ready:
+  🚀 boot-md ✓ - Run BOOT.md on gateway startup
+  📎 bootstrap-extra-files ✓ - Inject extra workspace bootstrap files during agent bootstrap
+  📝 command-logger ✓ - Log all command events to a centralized audit file
+  💾 session-memory ✓ - Save session context to memory when /new or /reset command is issued
+```
+
+**Example (verbose):**
+
+```bash
+Durar hooks list --verbose
+```
+
+Shows missing requirements for ineligible hooks.
+
+**Example (JSON):**
+
+```bash
+Durar hooks list --json
+```
+
+Returns structured JSON for programmatic use.
+
+## Get Hook Information
+
+```bash
+Durar hooks info <name>
+```
+
+Show detailed information about a specific hook.
+
+**Arguments:**
+
+- `<name>`: Hook name or hook key (e.g., `session-memory`)
+
+**Options:**
+
+- `--json`: Output as JSON
+
+**Example:**
+
+```bash
+Durar hooks info session-memory
+```
+
+**Output:**
+
+```
+💾 session-memory ✓ Ready
+
+Save session context to memory when /new or /reset command is issued
+
+Details:
+  Source: Durar-bundled
+  Path: /path/to/Durar/hooks/bundled/session-memory/HOOK.md
+  Handler: /path/to/Durar/hooks/bundled/session-memory/handler.ts
+  Homepage: https://docs.Durar.ai/automation/hooks#session-memory
+  Events: command:new, command:reset
+
+Requirements:
+  Config: ✓ workspace.dir
+```
+
+## Check Hooks Eligibility
+
+```bash
+Durar hooks check
+```
+
+Show summary of hook eligibility status (how many are ready vs. not ready).
+
+**Options:**
+
+- `--json`: Output as JSON
+
+**Example output:**
+
+```
+Hooks Status
+
+Total hooks: 4
+Ready: 4
+Not ready: 0
+```
+
+## Enable a Hook
+
+```bash
+Durar hooks enable <name>
+```
+
+Enable a specific hook by adding it to your config (`~/.Durar/Durar.json` by default).
+
+**Note:** Workspace hooks are disabled by default until enabled here or in config. Hooks managed by plugins show `plugin:<id>` in `Durar hooks list` and can’t be enabled/disabled here. Enable/disable the plugin instead.
+
+**Arguments:**
+
+- `<name>`: Hook name (e.g., `session-memory`)
+
+**Example:**
+
+```bash
+Durar hooks enable session-memory
+```
+
+**Output:**
+
+```
+✓ Enabled hook: 💾 session-memory
+```
+
+**What it does:**
+
+- Checks if hook exists and is eligible
+- Updates `hooks.internal.entries.<name>.enabled = true` in your config
+- Saves config to disk
+
+If the hook came from `<workspace>/hooks/`, this opt-in step is required before
+the Gateway will load it.
+
+**After enabling:**
+
+- Restart the gateway so hooks reload (menu bar app restart on macOS, or restart your gateway process in dev).
+
+## Disable a Hook
+
+```bash
+Durar hooks disable <name>
+```
+
+Disable a specific hook by updating your config.
+
+**Arguments:**
+
+- `<name>`: Hook name (e.g., `command-logger`)
+
+**Example:**
+
+```bash
+Durar hooks disable command-logger
+```
+
+**Output:**
+
+```
+⏸ Disabled hook: 📝 command-logger
+```
+
+**After disabling:**
+
+- Restart the gateway so hooks reload
+
+## Notes
+
+- `Durar hooks list --json`, `info --json`, and `check --json` write structured JSON directly to stdout.
+- Plugin-managed hooks cannot be enabled or disabled here; enable or disable the owning plugin instead.
+
+## Install Hook Packs
+
+```bash
+Durar plugins install <package>        # Durar Gateway first, then npm
+Durar plugins install <package> --pin  # pin version
+Durar plugins install <path>           # local path
+```
+
+Install hook packs through the unified plugins installer.
+
+`Durar hooks install` still works as a compatibility alias, but it prints a
+deprecation warning and forwards to `Durar plugins install`.
+
+Npm specs are **registry-only** (package name + optional **exact version** or
+**dist-tag**). Git/URL/file specs and semver ranges are rejected. Dependency
+installs run with `--ignore-scripts` for safety.
+
+Bare specs and `@latest` stay on the stable track. If npm resolves either of
+those to a prerelease, Durar stops and asks you to opt in explicitly with a
+prerelease tag such as `@beta`/`@rc` or an exact prerelease version.
+
+**What it does:**
+
+- Copies the hook pack into `~/.Durar/hooks/<id>`
+- Enables the installed hooks in `hooks.internal.entries.*`
+- Records the install under `hooks.internal.installs`
+
+**Options:**
+
+- `-l, --link`: Link a local directory instead of copying (adds it to `hooks.internal.load.extraDirs`)
+- `--pin`: Record npm installs as exact resolved `name@version` in `hooks.internal.installs`
+
+**Supported archives:** `.zip`, `.tgz`, `.tar.gz`, `.tar`
+
+**Examples:**
+
+```bash
+# Local directory
+Durar plugins install ./my-hook-pack
+
+# Local archive
+Durar plugins install ./my-hook-pack.zip
+
+# NPM package
+Durar plugins install @Durar/my-hook-pack
+
+# Link a local directory without copying
+Durar plugins install -l ./my-hook-pack
+```
+
+Linked hook packs are treated as managed hooks from an operator-configured
+directory, not as workspace hooks.
+
+## Update Hook Packs
+
+```bash
+Durar plugins update <id>
+Durar plugins update --all
+```
+
+Update tracked npm-based hook packs through the unified plugins updater.
+
+`Durar hooks update` still works as a compatibility alias, but it prints a
+deprecation warning and forwards to `Durar plugins update`.
+
+**Options:**
+
+- `--all`: Update all tracked hook packs
+- `--dry-run`: Show what would change without writing
+
+When a stored integrity hash exists and the fetched artifact hash changes,
+Durar prints a warning and asks for confirmation before proceeding. Use
+global `--yes` to bypass prompts in CI/non-interactive runs.
+
+## Bundled Hooks
+
+### session-memory
+
+Saves session context to memory when you issue `/new` or `/reset`.
+
+**Enable:**
+
+```bash
+Durar hooks enable session-memory
+```
+
+**Output:** `~/.Durar/workspace/memory/YYYY-MM-DD-slug.md`
+
+**See:** [session-memory documentation](/automation/hooks#session-memory)
+
+### bootstrap-extra-files
+
+Injects additional bootstrap files (for example monorepo-local `AGENTS.md` / `TOOLS.md`) during `agent:bootstrap`.
+
+**Enable:**
+
+```bash
+Durar hooks enable bootstrap-extra-files
+```
+
+**See:** [bootstrap-extra-files documentation](/automation/hooks#bootstrap-extra-files)
+
+### command-logger
+
+Logs all command events to a centralized audit file.
+
+**Enable:**
+
+```bash
+Durar hooks enable command-logger
+```
+
+**Output:** `~/.Durar/logs/commands.log`
+
+**View logs:**
+
+```bash
+# Recent commands
+tail -n 20 ~/.Durar/logs/commands.log
+
+# Pretty-print
+cat ~/.Durar/logs/commands.log | jq .
+
+# Filter by action
+grep '"action":"new"' ~/.Durar/logs/commands.log | jq .
+```
+
+**See:** [command-logger documentation](/automation/hooks#command-logger)
+
+### boot-md
+
+Runs `BOOT.md` when the gateway starts (after channels start).
+
+**Events**: `gateway:startup`
+
+**Enable**:
+
+```bash
+Durar hooks enable boot-md
+```
+
+**See:** [boot-md documentation](/automation/hooks#boot-md)