@rse/ase 2.0.2 → 2.0.4

package/dst/man/ase-agent-rebooter.md

@@ -0,0 +1,384 @@
+# ase-agent-rebooter(1) -- Plan Rebooting Agent
+
+## SYNOPSIS
+
+`ase agent rebooter start`
+\[`-n`|`--name` *name*\]
+\[`-t`|`--tool` `claude`|`copilot`|`codex`\]
+\[`-p`|`--parallel` *num*\]
+\[`-T`|`--timeout` *duration*\]
+\[`-o`|`--one-shot`\]
+\[`--agent-relay` *url*\]
+\[`--`*group*`-`*item* *value* \[...\]\]
+\[`-f`|`--foreground`\]
+
+`ase agent rebooter status`
+\[`-n`|`--name` *name*\]
+
+`ase agent rebooter log`
+\[`-f`|`--follow`\]
+\[`-n`|`--lines` *n*\]
+\[`--name` *name*\]
+
+`ase agent rebooter stop`
+\[`-n`|`--name` *name*\]
+
+## DESCRIPTION
+
+**ase agent rebooter** re-creates the plans of tasks in the `Planning`
+phase of the `enterprise` task lifecycle model (refused for any other
+model) from scratch.
+
+As a plan is re-created only on the explicit request of a human, the
+rebooter claims only the tasks in the state `DRAFTED` whose `Assignee:`
+frontmatter key already is its agent name (default: `rebooter`), i.e.,
+which a human assigned to the rebooter. Such a task is claimed
+immediately, without waiting for its `After:` predecessors (and, for an
+explicit epic, its group members), except for a predecessor still being
+processed by a rebooter or a cancelled `After:` predecessor.
+
+The rebooter moves each claimed task into `PLANNING`, tags it with
+`ase-agent-rebooter:active`, and reboots its plan via the skill
+invocation `ase-task-reboot --next DONE` *id*. The skill itself resets a
+successfully rebooted plan into `DRAFTED` (the processing succeeds only
+then). Afterwards, on success as well as on failure, the rebooter puts
+the task back into `DRAFTED` (for its review and its promotion into
+`PLANNED` by a human), removes its tag, and unassigns it. As the task is
+no longer assigned to the rebooter, it is not claimed again, while
+assigning it to the rebooter again requests another reboot.
+
+On an interrupt, a task being processed is put back, untagged and with
+its previous assignee (i.e., still assigned to the rebooter), into
+`DRAFTED`. The rebooter works in the project root only, so it
+neither requires a Git working copy nor `git`, and it accepts no
+`--repo` and `--tempdir`. See `ase-agent`(1) for the common mechanics of
+all agents.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]: Show usage information of `ase agent rebooter` (or
+  of the given sub-command) only.
+
+All other options belong to the sub-commands (see **COMMANDS**).
+
+## COMMANDS
+
+- `ase agent rebooter start` \[*options*\]: Start the rebooter agent in
+  the background, logging into `.ase/agent/`*name*`.log`. The agent is
+  validated and initialized (e.g., its agent tool is looked up and the
+  task lifecycle model is checked) before the command returns (waiting
+  up to 30 seconds), so a failing agent is reported together with the
+  tail of its log. An agent of the same name already running is left
+  alone. The options are:
+
+    - \[`-n`|`--name` *name*\]: The name of the agent (default:
+      `rebooter`): up to 64 letters, digits, underscores, and dashes,
+      starting with a letter or digit, other than the name of another
+      agent kind, `relay`, or `fleet`.
+
+      It names the agent in its log lines (also in the shared processing
+      log attachment `agent`), the `Assignee:` of the tasks it
+      processes, and its process files `.ase/agent/`*name*`.yaml` and
+      `.ase/agent/`*name*`.log`. Agents of the kind `rebooter` under
+      different names form a pool, competing for the same tasks, but each
+      claims only the tasks explicitly assigned to its own name.
+
+    - \[`-t`|`--tool` *tool*\]: The headless agent tool processing the
+      tasks: `claude` (*Anthropic Claude Code CLI*), `copilot` (*GitHub
+      Copilot CLI*), or `codex` (*OpenAI Codex CLI*) (default:
+      `$ASE_TOOL`, else `claude`). Its command has to be found in
+      `$PATH`.
+
+    - \[`-p`|`--parallel` *num*\]: The maximum number of tasks processed
+      in parallel by this agent (default: `1`), a positive integer.
+
+    - \[`-T`|`--timeout` *duration*\]: The maximum duration of
+      processing a task (the run of the agent tool), as *number* *unit*
+      (without a space) with *unit* `s` (seconds), `m` (minutes), or `h`
+      (hours) (default: `60m`). A processing exceeding it is aborted and
+      counts as failed.
+
+    - \[`-o`|`--one-shot`\]: Terminate the agent, instead of observing
+      for further tasks, once a check of the task store finds no
+      dispatchable task while the agent processes no task anymore --
+      intended for CI contexts like GitHub Actions, and not allowed in a
+      fleet. A task still waiting for its predecessors at that time is
+      left for a later run. A check of the task store failing three
+      times in a row then terminates the agent with a non-zero exit
+      status (instead of being retried endlessly after a growing delay).
+
+    - \[`--agent-relay` *url*\]: The agent relay to pass the live
+      presence of the agent to, as `ase://`*addr*`:`*port*\[`/`*token*\]
+      resp. `ases://`*addr*`:`*port*\[`/`*token*\]\[`?insecure`\] for
+      HTTPS (default: the configured `project.relay.url`, else none).
+      See **AGENT RELAY** in `ase-agent`(1).
+
+    - \[`--title` *text*\]: The one-line title of the operation of the
+      agent (at most 80 characters), shown on the task boards. Built-in:
+      `Reboot the plans of assigned tasks`.
+
+    - \[`--description` *text*\]: The brief description of the operation
+      of the agent (about 3-6 lines, at most 600 characters, with its
+      whitespace collapsed), shown on the task boards. Built-in: a
+      description of the operation.
+
+    - \[`--type` `phase`|`request`\]: The processing type: `phase`
+      claims the tasks by their lifecycle status, `request` processes
+      the prompt requests attached to the tasks. Generic default:
+      `phase`. Built-in: `phase`.
+
+    - \[`--workdir` *kind*\]: The working directory of the agent tool:
+      `project`, `source`, `changeset`, `changeset-read`, or `target`.
+      Generic default: `project`. Built-in: `project`.
+
+    - \[`--lifecycle` *model*\]: A supported task lifecycle model
+      (`solo`, `team`, or `enterprise`, repeatable). Generic default:
+      every model containing all given states, resp. all models for
+      `request` and with `--unclaimed`. Built-in: `enterprise`.
+
+    - \[`--serial`\]: Process the tasks serially only, ignoring
+      `--parallel`. Built-in: not set.
+
+    - \[`--unclaimed`\]: Process the tasks of the incoming states
+      without claiming them, independent of their assignee and
+      predecessors, and without ever changing their status and assignee
+      (`phase` only). Built-in: not set. Not allowed, as the rebooter
+      claims the tasks into its activity state.
+
+    - \[`--params` *name*`=`*value*\]: The value of a parameter
+      declared by the definition (repeatable). Built-in: none declared.
+
+    - \[`--state-incoming` *state*\]: A state of the tasks to claim
+      (mandatory for `phase`, repeatable with `--unclaimed` or
+      `--state-activity` only). Built-in: `DRAFTED`.
+
+    - \[`--state-activity` *state*\]: The state of a task during its
+      processing. Generic default: the incoming state. Built-in:
+      `PLANNING`.
+
+    - \[`--state-success` *state*\]: The target state on success, or
+      `previous` for the incoming state of the claim. Generic default:
+      the incoming state. Built-in: `DRAFTED`.
+
+    - \[`--state-failure` *state*\]: The target state on failure, or
+      `previous` for the incoming state of the claim. Generic default:
+      the incoming state. Built-in: `DRAFTED`.
+
+    - \[`--state-phase` *state*\]: The phase success state, into which
+      the skill itself can move a task. Generic default: the success
+      state, resp. the activity state for a `previous` success state.
+      Built-in: not set (hence `DRAFTED`, the default state, into which
+      the skill resets a rebooted plan).
+
+    - \[`--state-passed` *state*\]: The first state from which on a task
+      has passed the phase for its `After:` successors. Generic default:
+      the phase success state. Built-in: not set (hence `DRAFTED`, the
+      first state, so the predecessors impose no gate).
+
+    - \[`--state-verdict` *VERDICT*`=`*state*\]: The target state per
+      verdict (repeatable). Built-in: not set.
+
+    - \[`--tag-name` *tag*\]: The tag of the processed tasks
+      (`ase-agent-`*word*). Generic default: `ase-agent-`*name*, resp.
+      for `request` always `ase-agent-`*request-name*. Built-in: not set.
+
+    - \[`--tag-success` *tag*\]: The tag on success: *tag-name*,
+      *tag-name*`:`*value*, or `none` (`phase` only). Generic default:
+      *tag-name*. Built-in: `none`.
+
+    - \[`--tag-failure` *tag*\]: The tag on failure: *tag-name*,
+      *tag-name*`:`*value*, or `none` (`phase` only). Generic default:
+      *tag-name*. Built-in: `none`.
+
+    - \[`--tag-require` *tag*\]: A tag a claimable task has to carry
+      (repeatable). Built-in: not set.
+
+    - \[`--tag-exclude` *tag*\]: A tag a claimable task must not carry
+      (repeatable). Built-in: not set.
+
+    - \[`--tag-retry`\]: A shorthand for `--tag-failure none`, so a
+      failed task is claimed again after a growing delay (`phase` only).
+      Built-in: not set.
+
+    - \[`--assign-name` *who*\]: The assignee under which the tasks are
+      claimed, held, recognized, and released, and which names the
+      agent-owned worktrees. Generic default: the agent name. Built-in:
+      not set.
+
+    - \[`--assign-required`\]: Claim only the tasks explicitly assigned
+      to *who* of `--assign-name` (`phase` only). Built-in: enabled.
+
+    - \[`--assign-success` *who*\]: The assignee of a task after its
+      successful processing: a name, `none`, or `previous`. Generic
+      default: `none` for `phase`, `previous` for `request`. Built-in:
+      not set.
+
+    - \[`--assign-failure` *who*\]: The assignee of a task after its
+      failed processing: a name, `none`, or `previous`. Generic default:
+      `none` for `phase`, `previous` for `request`. Built-in: not set.
+
+    - \[`--request-name` *name*\]: The name of the processed requests
+      (`request` only). Generic default: the agent name. Built-in: not
+      set. Not allowed, as the rebooter is of type `phase`.
+
+    - \[`--request-done` *word*\]: The word naming a processed task in
+      the log lines (`request` only). Generic default: `processed`.
+      Built-in: not set. Not allowed, as the rebooter is of type `phase`.
+
+    - \[`--prompt-skill` *name*\]: The skill to invoke (mutually
+      exclusive with `--prompt-text` and `--prompt-file`). Built-in:
+      `ase-task-reboot`.
+
+    - \[`--prompt-args` *template*\]: The argument template of the
+      skill. Generic default: `{id}` for `phase`, `{id}: {prompt}` for
+      `request`. Built-in: `--next DONE {id}`.
+
+    - \[`--prompt-text` *template*\]: The prompt text template to invoke
+      instead of a skill. Built-in: not set.
+
+    - \[`--prompt-file` *file*\]: The file with the prompt text template
+      to invoke instead of a skill. Built-in: not set.
+
+    - \[`--prepare-run` *cmd*\]: A shell command run in the working
+      directory before the prompt (repeatable). Built-in: not set.
+
+    - \[`--success-criterion` *criterion*\]: A success criterion:
+      `exit`, `clean`, `changed`, `verdict`, `attachment`, or `status`
+      (repeatable). Generic default: `exit` and `clean` for `phase`,
+      `clean` and `changed` for `request`. Built-in: `status`.
+
+    - \[`--success-match` *regex*\]: A regular expression an output line
+      has to match (repeatable). Built-in: not set.
+
+    - \[`--verdict-label` *label*\]: The label after which the verdict
+      is given in the output. Built-in: not set.
+
+    - \[`--verdict-allow` *VERDICT*\]: An accepted verdict (repeatable).
+      Generic default: the verdicts of `--state-verdict`, else any.
+      Built-in: not set.
+
+    - \[`--attach-output` *kind*\]: The kind of the attachment storing
+      the output lines of the prompt. Built-in: not set.
+
+    - \[`--attach-expect` *spec*\]: The attachment
+      \[*mime-type*`;`\]*kind* to be created or changed by the
+      processing for the success criterion `attachment`. Built-in: not
+      set.
+
+    - \[`--attach-skip` *spec*\]: The attachment
+      \[*mime-type*`;`\]*kind* leaving a task unclaimed (`phase` only).
+      Built-in: not set.
+
+    - \[`--attach-changeset` *kind*\]: The kind of the attachment
+      `text/x-diff;`*kind* storing the change set snapshot of the task
+      (with `--workdir changeset` or `target` only). Built-in: not set.
+
+    - \[`--finish-commit`\]: Commit the work onto a `branch:` changeset
+      and publish it (with `--workdir changeset` only). Built-in: not
+      set. Not allowed, as the rebooter works in the project root.
+
+    - \[`--finish-success` *cmd*\]: A shell command run in the working
+      directory after a successful processing. Built-in: not set.
+
+    - \[`--finish-failure` *cmd*\]: A shell command run in the working
+      directory after a failed processing. Built-in: not set.
+
+    - \[`-f`|`--foreground`\]: Run the agent in the current process
+      instead, logging to the terminal, until it is interrupted (e.g.,
+      via `CTRL+C`) or stopped, where an agent of the same name already
+      running is an error.
+
+    - \[`-h`|`--help`\]: Show the usage information of the sub-command
+      only.
+
+  The options `--`*group*`-`*item* above override the built-in
+  definition of the agent (where an option also replaces its mutually
+  exclusive alternatives, e.g., `--prompt-text` replaces the skill of
+  `--prompt-skill`), while the agent keeps the identity of its kind (its
+  runs, its presence, and its agent-owned worktrees are named after
+  `rebooter`). See `ase-agent-adhoc`(1) for their full semantics.
+
+- `ase agent rebooter status` \[`-n`|`--name` *name*\]: Report whether
+  the rebooter agent of the name *name* (default: `rebooter`) is
+  running, as `agent` *name*`: running (pid` *pid*`)` resp. `agent`
+  *name*`: not running` (exit status 1).
+
+- `ase agent rebooter log` \[`-f`|`--follow`\] \[`-n`|`--lines` *n*\]
+  \[`--name` *name*\]: Show the log `.ase/agent/`*name*`.log` of the
+  rebooter agent of the name *name* (default: `rebooter`) run in the
+  background, where an agent of a fleet logs into the log of the fleet
+  instead (see `ase-agent-fleet`(1)). Without a log file, an
+  informational message is shown only. The options are:
+
+    - \[`-f`|`--follow`\]: Show the last *n* lines (default: 10) and
+      then follow all newly appended lines, in the style of `tail -f`,
+      until interrupted.
+
+    - \[`-n`|`--lines` *n*\]: Show the last *n* lines only (default:
+      all, or 10 with `--follow`).
+
+    - \[`--name` *name*\]: The name of the agent (default: `rebooter`),
+      given in its long form only, as `-n` is the short form of
+      `--lines`.
+
+- `ase agent rebooter stop` \[`-n`|`--name` *name*\]: Stop the rebooter
+  agent of the name *name* (default: `rebooter`) by `SIGTERM`, waiting
+  (up to 5 minutes) until it aborted its running processings and put
+  their tasks back. An agent not running is reported informationally
+  only.
+
+## ENVIRONMENT
+
+- `ASE_TOOL`: The default agent tool of `--tool` (default: `claude`).
+
+- `ASE_AGENT_RELAY_TOKEN`: The bearer token of the agent relay, if not
+  embedded in the URL of `--agent-relay` resp. `project.relay.url`.
+
+- `ASE_HEADLESS`: Set to `true` for the agent tool processes spawned by
+  the agent.
+
+## FILES
+
+- `.ase/agent/`*name*`.yaml`: The process state (kind, process id, and
+  process start time) of the agent, existing while it runs.
+
+- `.ase/agent/`*name*`.log`: The log of the agent run in the background.
+
+- *per-user state
+  directory*`/agent-rebooter/`*store-hash*`/`*run-id*`.lock` and `.json`:
+  The run lock and the run record of each rebooter agent process, used
+  to recover the tasks of terminated agent processes (see **INTERRUPTS
+  AND RECOVERY** in `ase-agent`(1)).
+
+## EXIT STATUS
+
+`ase agent rebooter start` exits with status `0` once the agent started
+(or was already running), resp. once a foreground agent terminated
+regularly, and with status `1` on any error (e.g., an invalid option, a
+task lifecycle model other than `enterprise`, or a missing agent tool).
+`ase agent rebooter status` exits with status `1` if the agent is not
+running.
+
+## EXAMPLES
+
+```sh
+# start the rebooter, rebooting the plans of the tasks assigned to it
+$ ase agent rebooter start
+
+# request the reboot of a drafted task by assigning it to the rebooter
+$ ase task assign FOO-42 rebooter
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-agent`(1), `ase-agent-condenser`(1),
+`ase-agent-researcher`(1), `ase-agent-implementer`(1),
+`ase-agent-qualifier`(1), `ase-agent-integrator`(1),
+`ase-agent-editor`(1), `ase-agent-estimator`(1), `ase-agent-adhoc`(1),
+`ase-agent-fleet`(1), `ase-agent-relay`(1), `ase-task`(1),
+`ase-task-board`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>
+

package/dst/man/ase-agent-relay.md

@@ -0,0 +1,262 @@
+# ase-agent-relay(1) -- Manage the Agent Relay Server
+
+## SYNOPSIS
+
+`ase agent relay start`
+\[`-a`|`--address` *host*\]
+\[`-p`|`--port` *port*\]
+\[`-t`|`--token` *token*\]
+\[`-c`|`--cors` *origin*\]
+\[`--tls-cert` *file* `--tls-key` *file*\]
+\[`-f`|`--foreground`\]
+
+`ase agent relay status`
+
+`ase agent relay log`
+\[`-f`|`--follow`\]
+\[`-n`|`--lines` *n*\]
+
+`ase agent relay stop`
+
+## DESCRIPTION
+
+`ase agent relay` manages the per-user *agent relay* server, which
+passes the live presence of the agents (see `ase-agent`(1)) to the
+task boards (see `ase-task-board`(1)) without any external
+infrastructure. It can run locally or on a central host, as long as
+both the agents and the task boards reach it, and serves any number of
+projects (by their `project.id`).
+
+The agent relay holds the presence of the agents in memory only: per
+agent its kind, name, mode, the title and description of its operation
+(for the agent logs view of `ase-task-board`(1)), request name, the lifecycle states it
+operates on (of a phase agent: its incoming, activity, written, and
+gate states, for the agent graph of `ase-task-board`(1)), host,
+process id, current working directory, user name and user id, start time, state (`waiting` or `busy`), the ids of the
+tasks it is busy with, its usage of the agent tool (in total and by its
+last job), the time since which it is in its state, the time of its
+latest announcement (its heartbeat), and its most recent 100
+processing log lines (each message truncated to 500 characters).
+
+An agent without heartbeat for 30 seconds is removed (checked every 5
+seconds), and a project exists only while it has agents.
+
+The agents announce their presence (see `--agent-relay` of
+`ase-agent`(1)) on every change of their state, after each finished
+job, with their new processing log lines, and as a heartbeat every 10
+seconds, and remove it on their termination. The task boards subscribe
+to the agents of their project.
+
+Alternatively, `ase task store start --with-agent-relay` (see
+`ase-task-store`(1)) co-hosts the agent relay in the task store server
+under the same address, port, and token, so a central host needs a
+single server process only. A fleet with the section `relay` owns the
+agent relay instead (see `ase-agent-fleet`(1)).
+
+The agent relay is selected by the agents and task boards via the
+configuration `project.relay.url` (or their option `--agent-relay`),
+as `ase://`*addr*`:`*port*\[`/`*token*\] for HTTP, resp.
+`ases://`*addr*`:`*port*\[`/`*token*\]\[`?insecure`\] for HTTPS
+(verifying the server certificate against the Node.js CA store,
+extendable via `$NODE_EXTRA_CA_CERTS`, or, with `?insecure`, without
+certificate verification). The relay requires an
+explicit `project.id`.
+
+The bearer token of a client is the one embedded in the URL (warned about
+if configured on the `project` or a `task` scope, as it might be
+committed), else `$ASE_AGENT_RELAY_TOKEN`, else `project.relay.token`
+(intended for the `user` scope, and warned about on any other scope),
+else the token of the locally started agent relay (resp. of the locally
+started task store co-hosting it), but only if the URL addresses exactly
+this server. Sending a token to a non-loopback host selected by a
+repository-supplied scope is warned about.
+
+## COMMANDS
+
+- `ase agent relay start` \[*options*\]:
+  Start the agent relay server in the background (spawning a detached
+  process logging into `relay.log`) and wait until it responds (up to
+  10 seconds), or with `--foreground` run it in the current process.
+
+  The configuration of the server is resolved from the options, the
+  environment, and the per-user `relay.yaml`, and its effective values
+  (address, port, token, CORS origins, TLS certificate and key, and
+  process id) are persisted in `relay.yaml` (readable by the current
+  user only). The start is idempotent: an already running server is left
+  alone, unless an explicitly given option (`--address`, `--port`,
+  `--token`, `--cors`, `--tls-cert`, or `--tls-key`) deviates from its
+  configuration, in which case the server is restarted to apply it.
+
+  With `--foreground`, an already running server with an unchanged
+  configuration is an error. A configured port held by a foreign service
+  is re-allocated (with a warning). Binding to a non-loopback address
+  without TLS is warned about, as the bearer token then travels
+  unencrypted. All options are described under **OPTIONS** below.
+
+- `ase agent relay status`:
+  Report whether the agent relay server is running, as `relay: running
+  on` *url* `(pid` *pid*`)`, after probing it on its configured address
+  and port with its configured token. Exits with status 1 if it is not
+  running (no port configured, the port not responding, or the port in
+  use by a foreign service), or if it rejects the configured token.
+
+- `ase agent relay log` \[`-f`|`--follow`\] \[`-n`|`--lines` *n*\]:
+  Show the log `relay.log` of the agent relay server run in the
+  background. With `-n`|`--lines` *n*, only the last *n* lines are shown
+  (default: all). With `-f`|`--follow`, the last *n* lines (default:
+  10) are shown and then, in the style of `tail -f`, all newly appended
+  lines are followed until interrupted. If no log file exists, this is
+  just reported (at log level `info`). The server logs its requests at
+  log level `debug` only, as the agents announce frequently.
+
+- `ase agent relay stop`:
+  Stop the agent relay server by sending it `SIGTERM` and waiting (up
+  to 5 seconds) until it is gone, closing all subscriptions of the task
+  boards. A not running server is reported as such, without an error.
+
+## OPTIONS
+
+The following options exist for `ase agent relay start`:
+
+- \[`-a`|`--address` *host*\]:
+  The address to bind to (default: the configured `address` of
+  `relay.yaml`, else `127.0.0.1`), e.g., `0.0.0.0` for all IPv4
+  interfaces of a central host.
+
+- \[`-p`|`--port` *port*\]:
+  The TCP port to bind to, `1`..`65535` (default: the configured `port`
+  of `relay.yaml`, else a randomly allocated free port in the range
+  `42000`..`44000`).
+
+- \[`-t`|`--token` *token*\]:
+  The bearer token to expect from all clients (default:
+  `$ASE_AGENT_RELAY_TOKEN`, else the configured `token` of
+  `relay.yaml`, else a generated random token).
+
+- \[`-c`|`--cors` *origin*\]:
+  (repeatable) Allow cross-origin browser requests from *origin*, or
+  from any origin with `*` (default: the configured `cors` origins of
+  `relay.yaml`, else none).
+
+- \[`--tls-cert` *file*\]:
+  Serve HTTPS with the PEM certificate (chain) in *file*, which
+  requires `--tls-key`, too (default: the configured `project.relay.crt`
+  (unless `project.relay.url` selects HTTP via `ase://` on this host),
+  else the configured `tls.cert` of `relay.yaml`, else plain HTTP). A
+  relative path of a configuration is relative to its configuration
+  file.
+
+- \[`--tls-key` *file*\]:
+  Serve HTTPS with the PEM private key in *file*, which requires
+  `--tls-cert`, too (default: the configured `project.relay.key`
+  (unless `project.relay.url` selects HTTP via `ase://` on this host),
+  else the configured `tls.key` of `relay.yaml`).
+
+- \[`-f`|`--foreground`\]:
+  Run the server in the current process, logging to the terminal
+  instead of `relay.log`, until it is interrupted (e.g., via `CTRL+C`)
+  or stopped via `ase agent relay stop`.
+
+- \[`-h`|`--help`\]:
+  Show the usage information of the command and exit.
+
+## PROTOCOL
+
+All requests have to carry the bearer token in the `Authorization:
+Bearer` *token* header (the WebSocket handshake alternatively in the
+query parameter `token`), else they are rejected with status 401 and
+an `application/problem+json` problem details response. The REST
+endpoints are:
+
+- `GET /agents`:
+  The projects with agents, as `{ "projects": [ { "id":` *id*`,
+  "agents":` *count* `} ] }`.
+
+- `GET /projects/`*id*`/agents`:
+  All agents of the project *id*, as `{ "agents": [` ... `] }`.
+
+- `PUT /projects/`*id*`/agents/`*agent*:
+  The announcement of the agent *agent* (also its heartbeat), as a JSON
+  payload with its presence and only its processing log lines added
+  since its previous announcement (at most 100), answered with status
+  204.
+
+- `DELETE /projects/`*id*`/agents/`*agent*:
+  The removal of the agent *agent* (on its termination), answered with
+  status 204.
+
+The WebSocket event endpoint `/projects/`*id*`/agents/events` first
+sends a snapshot frame of all agents of the project (with `reset:
+true`) and then a frame on each change (the added or updated agents,
+and the removed ones), where the processing log lines of an agent are
+always to be appended to the already received ones.
+
+Subscribers are pinged every 15 seconds and terminated if they did not
+answer the previous ping, resp. if they cannot keep up (more than 1 MB
+of not yet transmitted data). A plain HTTP request onto the event
+endpoint is answered with status 426.
+
+The project ids have to match `[A-Za-z0-9_-]+` and the agent ids
+`[A-Za-z0-9][A-Za-z0-9_.-]*` (at most 128 characters), else the request
+is rejected with status 422. To bound its memory, the relay holds at
+most 128 projects with agents, 64 agents per project, and 1024 agents
+in total, and accepts at most 64 subscribers per project and 1024
+subscribers in total, where a request beyond these limits is rejected
+with status 429.
+
+## ENVIRONMENT
+
+- `ASE_AGENT_RELAY_TOKEN`:
+  The default of `--token` of `ase agent relay start`, and the bearer
+  token of the agents and task boards connecting to the relay (if not
+  embedded in its URL).
+
+## FILES
+
+- *per-user configuration directory*`/relay.yaml`:
+  The configuration and runtime state of the agent relay server: the
+  keys `address`, `port`, `token`, `cors` (a list of origins),
+  `tls.cert`, `tls.key`, and `pid` (of the running server). It is
+  written by `ase agent relay start` (readable by the current user
+  only), and can be edited by hand to configure the defaults.
+
+- *per-user configuration directory*`/relay.log`:
+  The log of the agent relay server run in the background.
+
+The *per-user configuration directory* is `~/Library/Application
+Support/ase` on macOS, `%APPDATA%\ase` on Windows, and
+`$XDG_CONFIG_HOME/ase` (falling back to `~/.config/ase`) on Linux and
+other Unix systems.
+
+## EXIT STATUS
+
+`start` and `stop` exit with status 0 on success (also for a server
+already running resp. not running) and 1 on any error. `status` exits
+with status 1 if the server is not running or rejects the configured
+token. `log` exits with status 0.
+
+## EXAMPLES
+
+```sh
+# start the agent relay locally and let the agents and task boards follow it
+$ ase agent relay start -p 4711
+$ ase config --scope project set project.id myproject
+$ ase config --scope project set project.relay.url ase://127.0.0.1:4711
+
+# start the agent relay on a central host via HTTPS
+$ ase agent relay start -a 0.0.0.0 -p 4711 --tls-cert relay.crt --tls-key relay.key
+$ ase config --scope user set project.relay.token <token>
+
+# check and follow the agent relay
+$ ase agent relay status
+$ ase agent relay log -f
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-agent`(1), `ase-agent-fleet`(1), `ase-task-board`(1),
+`ase-task-store`(1), `ase-config`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>