@rse/ase 2.0.2 → 2.0.4

package/dst/man/ase-spec-lint.md

@@ -0,0 +1,74 @@
+# ase-spec-lint(1) -- Lint the Project Specification
+
+## SYNOPSIS
+
+`ase spec lint`
+\[`-h`|`--help`\]
+\[`-m`|`--markdown`\]
+\[`-v`|`--verbose`\]
+
+## DESCRIPTION
+
+**ase spec lint** lints the *SpecBook*-based specification Markdown
+files below `project.artifact.spec.basedir` against the *SpecBook*
+schema configuration `project.artifact.spec.schema` (see `ase-spec`(1)),
+and optionally for their generic Markdown formatting via *markdownlint*.
+
+Every diagnostic is logged to standard error as a single message
+`lint: `*linter*`: `*file*`:`*line*`:`*column*`: `*message* of the
+log level `error` resp. `warning` of its severity, where *linter* is
+`specbook` or `markdownlint`, and *file* is relative to the project
+root (a file outside the project, like the bundled standard schema, is
+kept as-is). Without any diagnostic, nothing is logged.
+
+The MCP tool `ase_specbook_lint` provides the same to the skills.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-m`|`--markdown`\]:
+  Additionally lint the specification Markdown files for their generic
+  Markdown formatting via *markdownlint*, with the rules conflicting
+  with the *SpecBook* format (like mixed ATX and Setext headings, free
+  ordered list numbering, padded list markers and headings, unwrapped
+  lines, images without alternate text, and multiple artifacts per file)
+  disabled. Its findings are diagnostics of `warning` severity, so they
+  never fail the linting.
+
+- \[`-v`|`--verbose`\]:
+  Instead of logging each diagnostic, print it to standard output as a
+  multi-line message with the affected source snippet (with an `ERROR`
+  resp. `WARNING` type, and a message prefixed by `markdownlint: ` for a
+  *markdownlint* diagnostic), colorized if standard output is a
+  terminal. If the source file is unreadable or empty, the single-line
+  message *file*`:`*line*`:`*column*`: `*message* is printed instead.
+
+## EXIT STATUS
+
+Exits with status `0` if there is no diagnostic of `error` severity
+(warnings alone do not fail), and with status `1` if there is any
+diagnostic of `error` severity or the linting itself failed (e.g., an
+unreadable schema configuration).
+
+## EXAMPLES
+
+```sh
+# lint the specification
+$ ase spec lint
+
+# lint the specification, showing the affected source snippets
+$ ase spec lint -v
+
+# lint the specification, including its generic Markdown formatting
+$ ase spec lint -m
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-spec`(1), `ase-spec-export`(1), `ase-spec-preview`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-spec-preview.md

@@ -0,0 +1,57 @@
+# ase-spec-preview(1) -- Serve a Live Preview of the Project Specification
+
+## SYNOPSIS
+
+`ase spec preview`
+\[`-h`|`--help`\]
+\[`-a`|`--addr` *ip-addr*\]
+\[`-p`|`--port` *tcp-port*\]
+
+## DESCRIPTION
+
+**ase spec preview** serves the HTML export of the *SpecBook*-based
+specification Markdown files below `project.artifact.spec.basedir` (see
+`ase-spec`(1)) as a live preview on `http://`*ip-addr*`:`*tcp-port*`/`
+(default: `http://127.0.0.1:12345/`). The export is kept in sync with
+its sources exactly like under `ase spec export --watch` (see
+`ase-spec-export`(1)), and every fresh export is pushed into the
+connected browsers as an in-place document update. Before the first
+successful export, a placeholder page is served instead.
+
+The command does not terminate on its own, but runs until it is
+interrupted (e.g., via `CTRL+C`).
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-a`|`--addr` *ip-addr*\]:
+  The IP address to listen on (default: `127.0.0.1`).
+
+- \[`-p`|`--port` *tcp-port*\]:
+  The TCP port to listen on, an integer in the range `1`..`65535`
+  (default: `12345`).
+
+## EXIT STATUS
+
+Runs until interrupted. Exits with status `1` on an invalid TCP port
+or if the server cannot be started.
+
+## EXAMPLES
+
+```sh
+# serve the live preview on the default address and port
+$ ase spec preview
+
+# serve the live preview on all interfaces on port 8080
+$ ase spec preview -a 0.0.0.0 -p 8080
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-spec`(1), `ase-spec-export`(1), `ase-spec-lint`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-spec.md

@@ -0,0 +1,85 @@
+# ase-spec(1) -- Initialize, Lint, Export, and Preview the Project Specification
+
+## SYNOPSIS
+
+`ase spec`
+\[`-h`|`--help`\]
+
+`ase spec init`
+
+`ase spec lint`
+\[`-m`|`--markdown`\]
+\[`-v`|`--verbose`\]
+
+`ase spec export`
+\[`-o`|`--output` \[*format*`:`\]*file*\] \[...\]
+\[`-w`|`--watch`\]
+
+`ase spec preview`
+\[`-a`|`--addr` *ip-addr*\]
+\[`-p`|`--port` *tcp-port*\]
+
+## DESCRIPTION
+
+**ase spec** is the entry point group for initializing, linting,
+exporting, and previewing the *SpecBook*-based project specification
+(SPEC), i.e., the Markdown files (plus their embedded assets) of the
+artifact kind `spec` below the base directory
+`project.artifact.spec.basedir` (default: `docs/specbook`, relative to
+the project root).
+
+The specification is governed by the *SpecBook* YAML schema
+configuration `project.artifact.spec.schema`: a whitespace-separated
+list of schema files, merged in the given order, where the entry `std`
+names the full standard schema bundled with *SpecBook* (not its
+compressed variant `ase-format-specbook.yaml` bundled with the plugin
+for the agents, see `ase-util-meta`(1)) and every other entry is a file
+path relative to the project root. An unset or empty value means `std`.
+
+All reading specification commands honor the Git exclude rules exactly
+like `ase artifact list` does (see `ase-artifact`(1)): an artifact file
+Git excludes from the project counts as an *absent* one, so both
+resolvers always see the very same specification.
+
+The *SpecBook* processing information is logged at the `info` level
+and its tracing details at the `debug` level (see the global option
+`--log-level` of `ase`(1)).
+
+Without a sub-command, the usage information is shown and the command
+exits with status `1`.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## COMMANDS
+
+- `ase spec init`:
+  Initialize the absent specification Markdown files of the schema
+  configuration. See `ase-spec-init`(1).
+
+- `ase spec lint` \[`-m`|`--markdown`\] \[`-v`|`--verbose`\]:
+  Lint the specification against the schema configuration, and
+  optionally for its generic Markdown formatting. See `ase-spec-lint`(1).
+
+- `ase spec export` \[`-o`|`--output` \[*format*`:`\]*file*\] \[...\] \[`-w`|`--watch`\]:
+  Export the specification as JSON, JSON5, YAML, TOON, HTML, PDF, or
+  normalized Markdown. See `ase-spec-export`(1).
+
+- `ase spec preview` \[`-a`|`--addr` *ip-addr*\] \[`-p`|`--port` *tcp-port*\]:
+  Serve the HTML export of the specification as a live preview. See
+  `ase-spec-preview`(1).
+
+## EXIT STATUS
+
+The group command without a sub-command exits with status `1`.
+
+## SEE ALSO
+
+`ase`(1), `ase-spec-init`(1), `ase-spec-lint`(1), `ase-spec-export`(1),
+`ase-spec-preview`(1), `ase-artifact`(1), `ase-config`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-statusline.md

@@ -0,0 +1,330 @@
+# ase-statusline(1) -- Render the Statusline of the Agent Tool
+
+## SYNOPSIS
+
+`ase statusline`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+\[`-w`|`--width` *n*\]
+\[`-m`|`--margin` *n*\]
+\[`-p`|`--padding` *n*\]
+\[`--no-icons`\]
+\[`--no-labels`\]
+\[*line* \[...\]\]
+
+## DESCRIPTION
+
+**ase statusline** renders the statusline of *Anthropic Claude Code
+CLI* or *GitHub Copilot CLI* from the JSON payload the agent tool
+passes on standard input, and writes the ANSI-colored result on
+standard output. It is intended to be configured as the `statusLine`
+command in the `settings.json` of *Anthropic Claude Code CLI* resp. as
+the `statusLine.command` entry of `~/.copilot/settings.json` of
+*GitHub Copilot CLI* (usually via `ase setup statusline activate`, see
+`ase-setup-statusline`(1)), and not to be invoked directly by end users.
+
+The output is composed from one or more template *line* arguments,
+each rendered as one output line (or more, see **WRAPPING**). A *line*
+may contain literal characters, `%`-prefixed placeholders (see
+**PLACEHOLDERS**), and color markup (see **COLORS**). Without any
+*line*, the single default line `%m %e %t` is rendered.
+
+Each placeholder is rendered as an optional icon glyph, an optional
+label followed by `: `, and the value in bold, e.g., `⚙ model:
+`**Opus**. A `%` followed by any other character is emitted literally.
+
+Under `--tool copilot`, the top-level `cwd` field of the payload is
+mapped onto `workspace.current_dir`, and, as *GitHub Copilot CLI*
+passes no `effort` field but embeds the reasoning effort as a ` · `
+separated segment of `model.display_name` (e.g., `gpt-5.4 (2x) · high ·
+1M context`), the segment matching a known effort level (`low`,
+`medium`, `high`, `xhigh`, or `max`) is split off again, so `%m`
+renders the plain model and `%e` the effort.
+
+When run inside a *tmux*(1) pane (i.e., with `TMUX` and `TMUX_PANE`
+set), the resolved task id is additionally published as the per-pane
+user option `@ase_task_id` of the pane, so external tools can pick it
+up via `#{@ase_task_id}`.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-t`|`--tool` *tool*\]:
+  Select the agent tool producing the payload: `claude` (*Anthropic
+  Claude Code CLI*) or `copilot` (*GitHub Copilot CLI*) (default:
+  the value of `ASE_TOOL`, else `claude`). The value `codex` is
+  rejected with an error, as *OpenAI Codex CLI* has no scriptable
+  custom statusline mechanism, and any other value is invalid.
+
+- \[`-w`|`--width` *n*\]:
+  Force the terminal width to *n* characters, a non-negative integer
+  (default: `0`, i.e., auto-detect the width of the controlling
+  terminal via `tput cols` on `/dev/tty`, as standard output is a pipe
+  under the agent tool).
+
+- \[`-m`|`--margin` *n*\]:
+  Reduce the maximum used terminal width by *n* characters on each
+  side, a non-negative integer (default: `2`). The margin only shrinks
+  the width budget and emits no characters.
+
+- \[`-p`|`--padding` *n*\]:
+  Pad each non-empty rendered line with *n* spaces on the left and
+  right side, a non-negative integer (default: `0`). In contrast to the
+  margin, the padding spaces are actually emitted (and hence also
+  shrink the width budget). Empty lines stay unpadded. Under `--tool
+  copilot`, a padded output is prefixed with a zero-width space, so the
+  first line keeps its indentation.
+
+- \[`--no-icons`\]:
+  Disable the leading icon glyph (e.g., `※`, `⚑`, or `⚙`) of each
+  placeholder rendering.
+
+- \[`--no-labels`\]:
+  Disable the textual label (e.g., `user:`, `project:`, or `model:`)
+  in front of the bold value of each placeholder rendering.
+
+## ARGUMENTS
+
+- \[*line* \[...\]\]:
+  The template lines (default: `%m %e %t`). Each argument yields its
+  own output line. Quote each line for the shell.
+
+## PLACEHOLDERS
+
+The following placeholders are recognized. Unless stated otherwise, a
+placeholder is always rendered. A placeholder marked as *suppressed* is
+silently omitted (including its icon and label) if its source is
+missing, e.g., in older agent tool versions or in synthetic payloads.
+
+Scope:
+
+- `%u`:
+  The user (`USER`, else `LOGNAME`, else `unknown`), with icon `※`.
+
+- `%p`:
+  The project id, derived from the basename of the current directory
+  of the workspace (`workspace.current_dir`), with icon `⚑`.
+
+- `%T`:
+  The active task id of the session (from its internal session state),
+  else `ASE_TASK_ID`, else `default`, with icon `◉`.
+
+- `%s`:
+  The session id (`session_id`, else `unknown`), with icon `⏻`.
+
+Model:
+
+- `%m`:
+  The model (`model.display_name`), with icon `⚙`.
+
+- `%e`:
+  The reasoning effort (`effort.level`, else the effort segment of the
+  *GitHub Copilot CLI* model, else `unknown`), with icon `⚒`.
+
+- `%t`:
+  Whether extended thinking is enabled (`thinking.enabled`), as `yes`
+  or `no`, with icon `⚛`.
+
+Output:
+
+- `%O`:
+  The output style (`output_style.name`), with icon `≡`, *suppressed*.
+
+- `%P`:
+  The persona style (`agent.persona`), with icon `☯`, *suppressed* if
+  empty.
+
+- `%h`:
+  The guidance level (`agent.guidance`), with icon `▶`, *suppressed* if
+  empty.
+
+- `%B`:
+  The project boxing transparency (`project.boxing`), with icon `▢`,
+  *suppressed* if empty.
+
+- `%L`:
+  The project task lifecycle model (`project.task.lifecycle`), with
+  icon `⟳`, *suppressed* if empty.
+
+  The values of `%P`, `%h`, `%B`, and `%L` are resolved from the *ASE*
+  configuration cascade of the session (`session:`*id*), falling back
+  to the environment variables `ASE_PERSONA_STYLE`,
+  `ASE_GUIDANCE_LEVEL`, `ASE_PROJECT_BOXING`, and
+  `ASE_PROJECT_TASK_LIFECYCLE`.
+
+Context:
+
+- `%c`:
+  The context usage (`context_window.used_percentage`) as a progress
+  bar of 20 cells (`█` filled, `░` empty) plus the percentage, with
+  icon `◔`.
+
+- `%C`:
+  The current and the maximum context tokens, e.g., `334.0k/1.0M`, with
+  icon `◆`. The current tokens are taken from
+  `context_window.current_context_tokens`, else
+  `last_call_input_tokens`, else `total_input_tokens`; the maximum from
+  `context_window.displayed_context_limit`, else
+  `context_window_size`, else derived from the current tokens and the
+  used percentage. *Suppressed* without a maximum.
+
+Rate limits:
+
+- `%S`:
+  The used percentage of the 5-hour rate-limit window, with icon `⏲`,
+  or `-` if unknown.
+
+- `%D`:
+  The time until the reset of the 5-hour window, e.g., `4hr 27m`, with
+  icon `⏱`, or `-` if unknown.
+
+- `%W`:
+  The used percentage of the 7-day rate-limit window, with icon `⏲`,
+  or `-` if unknown.
+
+- `%Q`:
+  The time until the reset of the 7-day window, e.g., `6d 12hr 7m`,
+  with icon `⏱`, or `-` if unknown.
+
+  The windows are taken from `rate_limits.five_hour` and
+  `rate_limits.seven_day` of the payload. If the payload carries none,
+  the model matches `gpt-*`, and a template references one of these
+  placeholders, the windows are instead fetched from the *ChatGPT*
+  backend with the credential stored by *OpenAI Codex CLI*
+  (`$CODEX_HOME/auth.json`, default `~/.codex/auth.json`), with a
+  timeout of 3 seconds, and cached (also on failure) for 60 seconds.
+
+Costs:
+
+- `%H`:
+  The wall-clock duration of the session (`cost.total_duration_ms`) as
+  hours and minutes, e.g., `92hr 40m`, with icon `⏱`, *suppressed* if
+  zero or missing.
+
+- `%X`:
+  The session costs in USD (`cost.total_cost_usd`), e.g., `$54.44`,
+  with icon `$`, *suppressed*.
+
+Version control:
+
+- `%a`:
+  The lines added in this session (`cost.total_lines_added`, else
+  `0`), with icon `⊕`.
+
+- `%r`:
+  The lines removed in this session (`cost.total_lines_removed`, else
+  `0`), with icon `⊖`.
+
+- `%b`:
+  The Git branch of the workspace directory, or `no git` outside of a
+  Git working tree, with icon `⎇`.
+
+- `%g`:
+  The changed lines of the Git working tree against `HEAD`, e.g.,
+  `+42/-7`, with icon `±`, *suppressed* outside of a Git working tree.
+
+- `%G`:
+  The number of untracked files of the Git working tree, with icon
+  `⁈`, *suppressed* outside of a Git working tree.
+
+- `%d`:
+  The full path of the workspace directory, with icon `▶`,
+  *suppressed*.
+
+Resources and versions:
+
+- `%M`:
+  The used and total memory of the host, e.g., `33.2G/64.0G`, with icon
+  `⛁`.
+
+- `%V`:
+  The agent tool and *ASE* versions (`version` of the payload), e.g.,
+  `claude/2.1.90 ase/1.0.7`, with icon `⎈`.
+
+## COLORS
+
+A *line* may contain the markup `<`*color*`>`...`</`*color*`>` to
+colorize its text (including rendered placeholders), where *color* is
+one of `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`,
+`white`, or `default`. A closing tag (of any recognized color name)
+ends the colored span, returning to the default foreground color.
+Spans do not nest: an opening tag inside a span is removed, but
+ignored. A span still open at the end of a line ends there. A tag with
+an unrecognized color name is kept literally in the output.
+
+## WRAPPING
+
+Each rendered line is automatically wrapped before the next chunk (a
+literal character or a whole placeholder rendering) which would exceed
+the width budget, where the budget is the terminal width (see
+`--width`) reduced by `2 *` (*margin* `+` *padding*) characters. Without
+a known terminal width, no wrapping happens.
+
+## INPUT
+
+The input is the standard statusline JSON payload of the agent tool,
+of which the fields `workspace.current_dir` (resp. `cwd` for *GitHub
+Copilot CLI*), `session_id`, `version`, `model.display_name`,
+`effort.level`, `thinking.enabled`, `output_style.name`,
+`context_window.*`, `rate_limits.five_hour` and
+`rate_limits.seven_day` (each with `used_percentage` and `resets_at`),
+and `cost.total_cost_usd`, `cost.total_duration_ms`,
+`cost.total_lines_added`, and `cost.total_lines_removed` are used.
+
+Invalid JSON is an error.
+
+## ENVIRONMENT
+
+- `ASE_TOOL`:
+  The default of `--tool`.
+
+- `ASE_TASK_ID`, `ASE_PERSONA_STYLE`, `ASE_GUIDANCE_LEVEL`,
+  `ASE_PROJECT_BOXING`, `ASE_PROJECT_TASK_LIFECYCLE`:
+  The fallbacks of `%T`, `%P`, `%h`, `%B`, and `%L`.
+
+- `USER`, `LOGNAME`:
+  The user of `%u`.
+
+- `CODEX_HOME`:
+  The configuration directory of *OpenAI Codex CLI* (default:
+  `~/.codex`), holding the credential `auth.json` for the rate limits
+  of the `gpt-*` models.
+
+- `TMUX`, `TMUX_PANE`:
+  The *tmux* pane to publish the task id `@ase_task_id` to.
+
+## FILES
+
+- *per-user state directory*`/statusline-codex-usage.json`:
+  The cache of the rate-limit windows fetched for the `gpt-*` models.
+
+- *per-user state directory*`/session/`*id*`/config.yaml` and
+  `state.yaml`:
+  The configuration and the internal state (active task) of the
+  session.
+
+## EXIT STATUS
+
+`0` on success, `1` on invalid JSON, an invalid option value, or
+`--tool codex`.
+
+## EXAMPLES
+
+```sh
+# render two lines from a sample payload
+$ echo '{"model":{"display_name":"Opus"},"context_window":{"used_percentage":42}}' | \
+  ase statusline "%m %e %t" "<blue>%c</blue>"
+
+# a compact statusline without icons and labels, padded by one space
+$ ase statusline --no-icons --no-labels -p 1 "%p %T %b %g" "%m %c %X"
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-setup-statusline`(1), `ase-config`(1), `tmux`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-task-assign.md

@@ -0,0 +1,138 @@
+# ase-task-assign(1) -- Assign a Task
+
+## SYNOPSIS
+
+`ase task assign`
+\[`-h`|`--help`\]
+\[`-s`|`--session` *id*\]
+\[*id*\[`:`\]\]
+*assignee*
+
+## DESCRIPTION
+
+**ase task assign** assigns the task plan with the given *id* in the
+task store (see `ase-task`(1)) by setting its `Assignee` frontmatter
+key to *assignee*, where `me` stands for the current user and `none`
+removes the key. The change is done in a conditional save of the task
+plan (retried on a concurrent change of the task), leaving the
+`Modified` key alone, as it tracks the changes of the plan body only.
+The change is logged as `task: assigned "`*id*`" from "`*from*`" to
+"`*to*`"`.
+
+If the configuration key `project.users` (see `ase-config`(1)) lists
+the known users, an *assignee* which is neither `none`, the current
+user, one of these users, nor the name of an agent present at the
+agent relay (see `ase-agent-relay`(1)) is still assigned, but with the
+warning `task: unknown assignee "`*assignee*`" (neither one of the
+users of "project.users" nor a known agent)` (with `--session`
+reported as part of its notice).
+
+With `--session`, the assignment is instead done on behalf of an agent
+tool session through the running `ase service` of the project (see
+`ase-service`(1)), which handles the *AI usage window* of the task, too
+(only if the AI usage accounting is enabled via `telemetry.enabled`,
+else a notice is reported):
+
+- Assigning the task to oneself opens its usage window (or attaches
+  the session to an already open one).
+
+- Assigning the task to anybody else closes its usage window and,
+  after a grace period of 10 seconds for late telemetry, atomically
+  adds the usage accumulated from the OTLP records of its sessions
+  (see `ase-setup-telemetry`(1)) to the YAML data of the usage
+  attachment of the task (`Type: application/yaml; kind="usage"`,
+  created on the first booking): `time.ai` (the AI request time in
+  minutes), `time.hr` (the human time in minutes, i.e., the whole real
+  time of the window), `time.real` (the wall-clock time of the window
+  in minutes), `token.cread`, `token.cwrite`, `token.input`, and
+  `token.output` (the disjoint token counts of the cache reads, cache
+  writes, uncached input, and output), `cost.ai` (the AI costs in USD,
+  as reported by the agent tool, else derived from
+  `telemetry.prices.ai`), and `cost.hr` (the human costs in USD, at the
+  hourly rate of the assignee in `telemetry.prices.hr`).
+
+A usage window also closes when its last session ends, and when the
+`Assignee` of its task is changed elsewhere while the task is the
+active task of an attached session. Conversely, once the `Assignee` of
+a task is changed to oneself elsewhere (e.g., on the task board), the
+service opens its window (starting *paused*) and attaches every session
+of the project whose active task it is.
+
+Unless disabled via `telemetry.implicit`, the service also accounts an
+*unassigned* task *implicitly*: it opens its window (starting
+*paused*) and attaches every interactive session of the project whose
+active task it is, without setting the `Assignee`, but only as long as
+the task stays the active task of the session and unassigned (task
+`default` excluded). Assigning such a task to oneself turns the
+implicit attachment into a regular one, and unassigning a task
+assigned to oneself elsewhere turns its attachments into implicit ones.
+
+Open windows additionally book every `telemetry.service.interval`
+minutes, pause after `telemetry.service.idle` minutes without any AI
+request of an attached session (resumed silently by the next one,
+without accounting the paused gap), and are closed and booked after 7
+days without any activity. The result is logged together with the
+action on the usage window and the booked usage. This is what the
+`ase_task_assign` MCP tool of the `ase-task-assign` skill does for the
+current session.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-s`|`--session` *id*\]:
+  Assign the task on behalf of the agent tool session *id* through the
+  running `ase service` of the project (whose port is read from
+  `.ase/service.yaml`), which additionally handles the AI usage window
+  of the task (see **DESCRIPTION**). The service is not started on
+  demand, so it has to run already.
+
+## ARGUMENTS
+
+- \[*id*\[`:`\]\]:
+  The id of the task (default: `$ASE_TASK_ID`, else `default`). A
+  trailing colon is stripped. If only a single argument is given, it is
+  taken as *assignee*, unless it has a trailing colon (then it is the
+  *id*, and the missing *assignee* is an error).
+
+- *assignee*:
+  The new assignee of the task: `me` for the current user (the value
+  of `$USER`, else `$LOGNAME`, else `unknown`), `none` to remove the
+  `Assignee` key, or any other non-empty single-line name without
+  commas.
+
+## ENVIRONMENT
+
+- `ASE_TASK_ID`:
+  The default task id (default: `default`).
+
+- `USER`, `LOGNAME`:
+  The current user, as substituted for `me`.
+
+## EXIT STATUS
+
+`0` on success, `1` if the *assignee* is missing or invalid, no such
+task exists, or (with `--session`) the service is not reachable.
+
+## EXAMPLES
+
+```sh
+# take the task "json-export"
+$ ase task assign json-export me
+
+# give the task back
+$ ase task assign json-export none
+
+# hand the task of $ASE_TASK_ID over to the implementer agent
+$ ase task assign implementer
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-task`(1), `ase-service`(1), `ase-setup-telemetry`(1),
+`ase-config`(1), `ase-agent`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>