@rse/ase 2.0.2 → 2.0.4

package/dst/man/ase-hook-session-persona.md

@@ -0,0 +1,65 @@
+# ase-hook-session-persona(1) -- Handle the SessionStart Hook Event for the Persona
+
+## SYNOPSIS
+
+`ase hook session-persona`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+
+## DESCRIPTION
+
+**ase hook session-persona** handles the `SessionStart` hook event of
+*Anthropic Claude Code CLI* and *OpenAI Codex CLI*, resp. the
+`sessionStart` hook event of *GitHub Copilot CLI*, in addition to
+`ase hook session-start`.
+It is intended to be invoked by the agent tool internally as a
+configured hook handler only, and not directly by end users.
+
+The handler determines the plugin root directory (see
+`ase-hook-session-start`(1)), reads the persona rules
+`meta/ase-persona.md` from it, and writes them as the hook output
+payload to standard output, as `hookSpecificOutput.additionalContext`
+(`claude` and `codex`), resp. as the top-level field
+`additionalContext` (`copilot`).
+
+The persona rules are injected by this separate handler, as agent tools
+like *Anthropic Claude Code CLI* show only a preview of a hook output
+beyond 10,000 characters, which otherwise would cut off the persona
+rules from the output of `ase hook session-start`. The rules refer to
+the persona style `<ase-persona-style>` injected by `ase hook
+session-start`, but only by name, so both handlers are independent of
+each other and their execution order does not matter.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-t`|`--tool` *tool*\]:
+  The agent tool whose hook output format is written: `claude`
+  (*Anthropic Claude Code CLI*), `copilot` (*GitHub Copilot CLI*), or
+  `codex` (*OpenAI Codex CLI*). Default: `$ASE_TOOL`, else `claude`.
+
+## ENVIRONMENT
+
+- `CLAUDE_PLUGIN_ROOT`, `COPILOT_PLUGIN_ROOT`, `PLUGIN_ROOT`:
+  The plugin root directory, provided by the agent tool. The handler
+  fails if the variable of the selected tool is unset or empty.
+
+- `ASE_TOOL`:
+  The default of `--tool`.
+
+## EXIT STATUS
+
+Exits with status `0` on success, and with status `1` if the plugin
+root directory cannot be determined, the persona file cannot be read,
+or `--tool` is invalid.
+
+## SEE ALSO
+
+`ase`(1), `ase-hook`(1), `ase-hook-session-start`(1), `ase-config`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>
+

package/dst/man/ase-hook-session-start.md

@@ -0,0 +1,184 @@
+# ase-hook-session-start(1) -- Handle the SessionStart Hook Event
+
+## SYNOPSIS
+
+`ase hook session-start`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+
+## DESCRIPTION
+
+**ase hook session-start** handles the `SessionStart` hook event of
+*Anthropic Claude Code CLI* and *OpenAI Codex CLI*, resp. the
+`sessionStart` hook event of *GitHub Copilot CLI*. It is intended to be
+invoked by the agent tool internally as a configured hook handler only,
+and not directly by end users.
+
+The handler reads the event payload from standard input, a JSON object
+with the session id (field `session_id`, resp. `sessionId` for *GitHub
+Copilot CLI*) and the working directory (field `cwd`), and performs the
+following steps:
+
+1. It determines the plugin root directory from the environment
+   variable `CLAUDE_PLUGIN_ROOT` (`claude`), `COPILOT_PLUGIN_ROOT`
+   (`copilot`), resp. `PLUGIN_ROOT` or `CLAUDE_PLUGIN_ROOT` (`codex`),
+   and reads the plugin manifest `.claude-plugin/plugin.json` (for the
+   plugin version), the constitution `meta/ase-constitution.md`, and the
+   output style `output-styles/ase-terse.md` from it.
+
+2. It determines a version hint: a warning on a version mismatch
+   between the tool and the plugin, a notice on a newer tool version
+   available in the NPM registry (checked in the background at most
+   once per hour), and a notice on a development setup (environment
+   variable `ASE_SETUP_DEV` set).
+
+3. For `--tool copilot` only, it changes into the project directory
+   `cwd` of the payload, as *GitHub Copilot CLI* runs its hooks in the
+   plugin installation directory.
+
+4. It removes all session state directories below the *per-user state
+   directory*`/session/` (except the one of the current session) which
+   were not modified for more than 7 days, i.e., the leftovers of agent
+   tool sessions which ended without running `ase hook session-end`.
+
+5. It determines the project directory (the Git top-level directory of
+   `cwd`, else `cwd` itself) and, for a valid session id (matching
+   `[A-Za-z0-9._-]+`), persists the active task id (`$ASE_TASK_ID`,
+   else `default`) and the project directory into the internal session
+   state *per-user state directory*`/session/`*id*`/state.yaml`.
+
+6. Inside a *tmux* pane, it sets the per-pane user option
+   `@ase_agent_status` to `⏸` (ready).
+
+7. It resolves the session information from the configuration
+   cascade (with the scope `session:`*id* for a valid session id):
+   the project id (a valid configured `project.id`, else derived from
+   the project directory), the user id (`$USER`, else `$LOGNAME`, else
+   `unknown`), the persona style `agent.persona`, the guidance level
+   `agent.guidance`, the boxing transparency `project.boxing`, the task
+   lifecycle model `project.task.lifecycle`, the defaults
+   `project.task.default.source`, `project.task.default.changeset`, and
+   `project.task.default.target`, the specification base directory
+   `project.artifact.spec.basedir`, and the schema configuration
+   `project.artifact.spec.schema`.
+
+   A setting not explicitly configured in any scope falls back to the
+   environment variables `ASE_PERSONA_STYLE`, `ASE_GUIDANCE_LEVEL`,
+   `ASE_PROJECT_BOXING`, `ASE_PROJECT_TASK_LIFECYCLE`,
+   `ASE_PROJECT_TASK_DEFAULT_SOURCE`,
+   `ASE_PROJECT_TASK_DEFAULT_CHANGESET`, and
+   `ASE_PROJECT_TASK_DEFAULT_TARGET`, and finally to the defaults
+   `engineer`, `normal`, `white`, `solo`, `worktree`, `worktree`, and
+   `source`.
+
+8. For `--tool claude` only, it appends `export` statements of the
+   variables `ASE_VERSION`, `ASE_PLUGIN_ROOT`, `ASE_USER_ID`,
+   `ASE_PROJECT_ID`, `ASE_PROJECT_BOXING`, `ASE_PROJECT_TASK_LIFECYCLE`,
+   `ASE_PROJECT_TASK_DEFAULT_SOURCE`,
+   `ASE_PROJECT_TASK_DEFAULT_CHANGESET`,
+   `ASE_PROJECT_TASK_DEFAULT_TARGET`, `ASE_SPEC_BASEDIR`,
+   `ASE_SPEC_SCHEMA`, `ASE_TASK_ID`, `ASE_SESSION_ID`, `ASE_HEADLESS`,
+   and `ASE_AGENT_TOOL` to the file of the environment variable
+   `CLAUDE_ENV_FILE` (if set), so they are available to all shell
+   commands of the session.
+
+9. It writes the hook output payload to standard output: the session
+   information as XML-style tags (`<ase-version>`, `<ase-version-hint>`,
+   `<ase-plugin-root>`, `<ase-persona-style>`, `<ase-guidance-level>`,
+   `<ase-user-id>`, `<ase-project-id>`, `<ase-project-boxing>`,
+   `<ase-project-task-lifecycle>`,
+   `<ase-project-task-default-source>`,
+   `<ase-project-task-default-changeset>`,
+   `<ase-project-task-default-target>`, `<ase-spec-basedir>`,
+   `<ase-spec-schema>`, `<ase-task-id>`, `<ase-session-id>`,
+   `<ase-headless>`, and `<ase-agent-tool>`), followed by the
+   constitution, with all `@`*file* references expanded recursively
+   (relative to the referencing file, `~/` denoting the home
+   directory).
+
+   The persona rules are not part of this output, but are injected
+   separately by `ase hook session-persona`, as agent tools like
+   *Anthropic Claude Code CLI* show only a preview of a hook output
+   beyond 10,000 characters.
+
+   For `--tool copilot` and `--tool codex` only, the instructions of the
+   output style `ase-terse` (with its YAML frontmatter stripped) are
+   appended, as these agent tools have no output style concept, whereas
+   *Anthropic Claude Code CLI* applies the plugin output style natively.
+   The context is emitted as `hookSpecificOutput.additionalContext`
+   (`claude` and `codex`), resp. as the top-level field
+   `additionalContext` (`copilot`).
+
+   Additionally, for `claude` and `codex`, unless running headless
+   (`ASE_HEADLESS` is `true`) or with guidance level `none`, a
+   deterministic *ASE* banner (version, user, project, task, session,
+   persona, guidance, and boxing, plus usage hints for guidance level
+   `normal` and `verbose`) is emitted as the top-level field
+   `systemMessage`.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-t`|`--tool` *tool*\]:
+  The agent tool whose event payload is read and whose hook output
+  format is written: `claude` (*Anthropic Claude Code CLI*), `copilot`
+  (*GitHub Copilot CLI*), or `codex` (*OpenAI Codex CLI*). Default:
+  `$ASE_TOOL`, else `claude`.
+
+## ENVIRONMENT
+
+- `CLAUDE_PLUGIN_ROOT`, `COPILOT_PLUGIN_ROOT`, `PLUGIN_ROOT`:
+  The plugin root directory, provided by the agent tool. The handler
+  fails if the variable of the selected tool is unset or empty.
+
+- `CLAUDE_ENV_FILE`:
+  The environment file of *Anthropic Claude Code CLI*, receiving the
+  exported session information.
+
+- `ASE_TOOL`:
+  The default of `--tool`.
+
+- `ASE_TASK_ID`:
+  The active task id of the session (default: `default`).
+
+- `ASE_HEADLESS`:
+  If `true`, the session runs headless, and no banner is emitted.
+
+- `ASE_SETUP_DEV`:
+  If set, the version hint notes a development setup.
+
+- `ASE_PERSONA_STYLE`, `ASE_GUIDANCE_LEVEL`, `ASE_PROJECT_BOXING`,
+  `ASE_PROJECT_TASK_LIFECYCLE`, `ASE_PROJECT_TASK_DEFAULT_SOURCE`,
+  `ASE_PROJECT_TASK_DEFAULT_CHANGESET`,
+  `ASE_PROJECT_TASK_DEFAULT_TARGET`:
+  The fallbacks of the settings not explicitly configured.
+
+- `USER`, `LOGNAME`:
+  The user id.
+
+- `TMUX`, `TMUX_PANE`:
+  The *tmux* pane whose user option `@ase_agent_status` is set.
+
+## FILES
+
+- *per-user state directory*`/session/`*id*`/state.yaml`:
+  The internal session state, holding the active task id and the
+  project directory of the session.
+
+## EXIT STATUS
+
+Exits with status `0` on success, and with status `1` if the plugin
+root directory cannot be determined, a plugin file cannot be read, or
+`--tool` is invalid.
+
+## SEE ALSO
+
+`ase`(1), `ase-hook`(1), `ase-hook-session-persona`(1),
+`ase-hook-session-end`(1), `ase-config`(1),
+`ase-statusline`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-hook-stop.md

@@ -0,0 +1,52 @@
+# ase-hook-stop(1) -- Handle the Stop Hook Event
+
+## SYNOPSIS
+
+`ase hook stop`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+
+## DESCRIPTION
+
+**ase hook stop** handles the `Stop` hook event of *Anthropic Claude
+Code CLI* and *OpenAI Codex CLI*, resp. the `agentStop` hook event of
+*GitHub Copilot CLI*, which the agent tool fires when the agent
+finished responding. It is intended to be invoked by the agent tool
+internally as a configured hook handler only, and not directly by end
+users.
+
+The handler reads and discards the event payload on standard input
+and, when running inside a *tmux* pane, sets the per-pane user option
+`@ase_agent_status` to `⏸` (ready), so a *tmux* status line can render
+the live activity of the agent via `#{@ase_agent_status}`. It writes
+nothing to standard output.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-t`|`--tool` *tool*\]:
+  The agent tool which fires the event: `claude`, `copilot`, or
+  `codex`. Default: `$ASE_TOOL`, else `claude`.
+
+## ENVIRONMENT
+
+- `TMUX`, `TMUX_PANE`:
+  The *tmux* pane whose user option `@ase_agent_status` is set (only if
+  both are set and non-empty).
+
+- `ASE_TOOL`:
+  The default of `--tool`.
+
+## EXIT STATUS
+
+Exits with status `0`, unless `--tool` is invalid (status `1`).
+
+## SEE ALSO
+
+`ase`(1), `ase-hook`(1), `ase-hook-user-prompt-submit`(1), `tmux`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-hook-user-prompt-submit.md

@@ -0,0 +1,54 @@
+# ase-hook-user-prompt-submit(1) -- Handle the UserPromptSubmit Hook Event
+
+## SYNOPSIS
+
+`ase hook user-prompt-submit`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+
+## DESCRIPTION
+
+**ase hook user-prompt-submit** handles the `UserPromptSubmit` hook
+event of *Anthropic Claude Code CLI* and *OpenAI Codex CLI*, resp. the
+`userPromptSubmitted` hook event of *GitHub Copilot CLI*, which the
+agent tool fires when the user submits a prompt. It is intended to be
+invoked by the agent tool internally as a configured hook handler only,
+and not directly by end users.
+
+The handler reads and discards the event payload on standard input
+and, when running inside a *tmux* pane, sets the per-pane user option
+`@ase_agent_status` to `▶` (busy), so a *tmux* status line can render
+the live activity of the agent via `#{@ase_agent_status}`
+(independent of the statusline of the agent tool, which is not
+repainted during the agent processing). It writes nothing to standard
+output.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-t`|`--tool` *tool*\]:
+  The agent tool which fires the event: `claude`, `copilot`, or
+  `codex`. Default: `$ASE_TOOL`, else `claude`.
+
+## ENVIRONMENT
+
+- `TMUX`, `TMUX_PANE`:
+  The *tmux* pane whose user option `@ase_agent_status` is set (only if
+  both are set and non-empty).
+
+- `ASE_TOOL`:
+  The default of `--tool`.
+
+## EXIT STATUS
+
+Exits with status `0`, unless `--tool` is invalid (status `1`).
+
+## SEE ALSO
+
+`ase`(1), `ase-hook`(1), `ase-hook-stop`(1), `tmux`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-hook.md

@@ -0,0 +1,93 @@
+# ase-hook(1) -- Handle the Hook Events of the Agent Tool
+
+## SYNOPSIS
+
+`ase hook`
+\[`-h`|`--help`\]
+
+`ase hook`
+*event*
+\[`-t`|`--tool` *tool*\]
+
+## DESCRIPTION
+
+**ase hook** is the entry point group of the hook handlers which the
+*ASE* plugin configures in the agent tool: in `hooks/hooks.json` for
+*Anthropic Claude Code CLI*, in `hooks/hooks-copilot.json` for *GitHub
+Copilot CLI* (with `--tool copilot`), and in `hooks/hooks-codex.json`
+for *OpenAI Codex CLI* (with `--tool codex`). The agent tool invokes a
+handler on the corresponding event, passes the event payload as a JSON
+object on standard input, and interprets the JSON object a handler
+optionally writes to standard output.
+
+The handlers are intended to be invoked by the agent tool internally
+only, and not directly by end users. Without a sub-command, the usage
+information is shown and the command exits with status `1`.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information, including the list of all event handlers,
+  and exit.
+
+## COMMANDS
+
+The following event handlers exist, each accepting the option
+\[`-t`|`--tool` *tool*\] (`claude`, `copilot`, or `codex`, default:
+`$ASE_TOOL`, else `claude`) to select the agent tool whose payload
+format is read and written:
+
+- `ase hook session-start`:
+  Handle the `SessionStart` (resp. `sessionStart`) event: inject the
+  *ASE* constitution and session information into the session context.
+  See `ase-hook-session-start`(1).
+
+- `ase hook session-persona`:
+  Handle the `SessionStart` (resp. `sessionStart`) event a second time:
+  inject the *ASE* persona rules into the session context.
+  See `ase-hook-session-persona`(1).
+
+- `ase hook session-end`:
+  Handle the `SessionEnd` (resp. `sessionEnd`) event: remove the
+  session state and detach the session from its AI usage window. See
+  `ase-hook-session-end`(1).
+
+- `ase hook pre-tool-use`:
+  Handle the `PreToolUse` (resp. `preToolUse`) event: auto-approve the
+  invocations of *ASE* tools. See `ase-hook-pre-tool-use`(1).
+
+- `ase hook permission-request`:
+  Handle the `PermissionRequest` event of *OpenAI Codex CLI*:
+  auto-approve the invocations of *ASE* tools. See
+  `ase-hook-permission-request`(1).
+
+- `ase hook user-prompt-submit`:
+  Handle the `UserPromptSubmit` (resp. `userPromptSubmitted`) event:
+  mark the agent as busy. See `ase-hook-user-prompt-submit`(1).
+
+- `ase hook stop`:
+  Handle the `Stop` (resp. `agentStop`) event: mark the agent as
+  ready. See `ase-hook-stop`(1).
+
+## ENVIRONMENT
+
+- `ASE_TOOL`:
+  The default of the `--tool` option of all event handlers. An invalid
+  value is reported only once a handler actually runs.
+
+## EXIT STATUS
+
+Each event handler exits with status `0` on success, and with status
+`1` on an invalid `--tool` value or a fatal error. The group command
+without a sub-command exits with status `1`.
+
+## SEE ALSO
+
+`ase`(1), `ase-hook-session-start`(1), `ase-hook-session-persona`(1),
+`ase-hook-session-end`(1),
+`ase-hook-pre-tool-use`(1), `ase-hook-permission-request`(1),
+`ase-hook-user-prompt-submit`(1), `ase-hook-stop`(1), `ase-setup`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-man.md

@@ -0,0 +1,195 @@
+# ase-man(1) -- Browse the internally shipped manual pages
+
+## SYNOPSIS
+
+`ase man`
+\[`-h`|`--help`\]
+\[`-l`|`--list`\]
+\[*page* \[...\]\]
+
+## DESCRIPTION
+
+**ase man** shows the manual pages shipped internally with the **ase**
+tool: the manual pages of all **ase** commands *and* the manual pages
+of all **ASE** skills of the bundled agent tool plugin.
+
+The manual pages of the commands are shipped as Markdown in the
+directory `dst/man/` of the tool package. There is one manual page per
+command and command group, named after the command path with dashes,
+e.g., `ase-task`(1) for `ase task` and `ase-agent-fleet`(1) for `ase
+agent fleet`. The commands of the third level (e.g. `ase task store
+start`) are covered by the manual page of their group (e.g.
+`ase-task-store`(1)).
+
+On a terminal (and without `--list`), **ase man** opens the
+interactive, full-screen *manual page browser*. If standard input or
+standard output is not a terminal, it instead prints the manual page
+*page* (or `ase`(1)) as plain text, wrapped to 80 columns, onto
+standard output. The browser consists of two pages:
+
+- The *start page* shows a search field on top of a catalog of all AI
+  skills and all CLI commands, grouped like the catalog of the website
+  and laid out in up to five columns, depending on the terminal width
+  (reduced to the matching manual pages while a search is active).
+  Selecting a manual page or submitting a search opens the browser page.
+  The browser starts on the start page if no *page* is given.
+
+- The *browser page* shows the master on the left, with the search
+  field on top of the grouped list of all manual pages (reduced to the
+  matching manual pages while a search is active), and the detail on
+  the right, with the selected manual page as rendered and
+  syntax-highlighted Markdown (with the matches of an active search
+  highlighted). References to other manual pages within the detail,
+  like `ase-task`(1) or `ase-task-edit`, can be followed. The browser
+  starts on the browser page if a *page* is given: with the manual page
+  fitting exactly onto *page* selected, else with *page* as the search.
+
+A search consists of whitespace-separated keywords, which *all* have to
+occur (case-insensitively) in a manual page. Only if no manual page
+matches the keywords literally, they are matched fuzzily against the
+words of the manual pages, so a misspelled keyword still finds its
+manual pages. On both pages, the catalog resp. the master is filtered
+live while typing, and the header shows the counts of the matching
+manual pages.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show program usage information only.
+
+- \[`-l`|`--list`\]:
+  Instead of showing a manual page, list the names of all shipped
+  manual pages of the commands, one per line, in natural order. Any
+  *page* is ignored.
+
+## ARGUMENTS
+
+- \[*page* \[...\]\]:
+  The manual page to show (default: the start page of the interactive
+  manual page browser on a terminal, else `ase`). It is given either by
+  its name (e.g. `ase-agent-fleet` or `ase-task-edit`) or by the words
+  of the command path (e.g. `agent fleet`), which are joined with
+  dashes, where the leading `ase` is optional and the name is
+  case-insensitive.
+
+  In the manual page browser, the manual page fitting exactly onto
+  *page* is selected. Of a skill and a command of the same name (e.g.
+  `ase-task-edit` and `ase-task-edit`(1)), a single name with dashes
+  (e.g. `task-edit`) selects the skill, while the words of a command
+  path (e.g. `task edit`) select the command. If no manual page fits
+  exactly, the words of *page* are
+  placed into the search field instead, so the master shows only the
+  matching manual pages, with the first of them selected.
+
+  When printed as plain text, the manual page fitting exactly onto
+  *page* is printed likewise. If no manual page fits exactly, a command
+  path deeper than the shipped manual pages (e.g. `task store start`)
+  falls back to the manual page of its nearest parent group (e.g.
+  `ase-task-store`), but never to the top-level page `ase`(1), and a
+  *page* consisting of anything other than letters, digits, and dashes
+  is refused.
+
+## KEYS
+
+The following keys and mouse actions are supported by the interactive
+manual page browser.
+
+### Start Page
+
+- `Up`, `Down`, `Left`, `Right`: Select the manual page above, below,
+  left, or right of the selected one in the catalog (at the end of a
+  column, `Up` and `Down` continue in the nearest other column).
+- `Home`, `End`: Select the first or last manual page of the catalog
+  (not within the search field).
+- `Return`: Open the selected manual page on the browser page (keeping
+  an active search).
+- `/`: Enter the search field, whose search filters the catalog live.
+  Within it, `Return` submits the search (opening the browser page
+  with the selected, i.e. initially the first, matching manual page),
+  `Left`, `Right`, `Home`, and `End` move the cursor, `Backspace` and
+  `Delete` delete the character before resp. at the cursor, and
+  `Escape` leaves the search field again.
+- `Escape`: Clear a non-empty search (not within the search field).
+- `q`, `Ctrl`+`C`: Quit (`q` not within the search field).
+- Left-Click: Open the clicked manual page (keeping an active search),
+  resp. enter the clicked search field (clearing the search on its
+  trailing `✕` symbol).
+- Wheel: Select the manual page above or below the selected one.
+
+### Browser Page
+
+- `Up`, `Down`: Select the previous or next manual page of the master,
+  resp. the previous or next reference within the detail (while a
+  reference is selected).
+- `Right`, `Left`: Enter the references of the detail (selecting the
+  first shown reference), resp. leave them again towards the master.
+- `Page Up`, `Page Down`, `Space`: Scroll the detail by a page
+  (`Space` not within the search field).
+- `Home`, `End`: Scroll the detail to its top or bottom (not within
+  the search field).
+- `Tab`, `Shift`+`Tab`: Select the next or previous reference to
+  another manual page within the detail.
+- `Return`: Follow the selected reference (leaving a search the
+  referenced manual page does not match), resp. leave the search
+  field.
+- `/`: Enter the search field, whose search filters the master live.
+  Within it, `Left`, `Right`, `Home`, and `End` move the cursor, and
+  `Backspace` and `Delete` delete the character before resp. at the
+  cursor.
+- `Escape`: Step back: first clear a non-empty search, then leave the
+  search field, and finally return to the start page.
+- `q`, `Ctrl`+`C`: Quit (`q` not within the search field).
+- Left-Click: Select the clicked manual page of the master, follow the
+  clicked reference of the detail, resp. enter the clicked search field
+  (clearing the search on its trailing `✕` symbol).
+- Wheel: Select the previous or next manual page (over the master),
+  resp. scroll the detail (over the detail).
+
+## FILES
+
+- *package directory*`/dst/man/ase{,-`*command*`{,-`*sub-command*`}}.md`:
+  The internally shipped manual pages of the commands.
+
+- *package directory*`/plugin/skills/`*skill*`/help.md`:
+  The manual pages of the skills of the bundled agent tool plugin.
+
+## EXIT STATUS
+
+The command exits with status `0` on success, and with status `1` if
+no manual page is found for *page* when printing it as plain text.
+
+## EXAMPLES
+
+```sh
+# browse all manual pages of the commands and skills interactively
+$ ase man
+
+# show the manual page of the "ase" command itself
+$ ase man ase
+
+# show the manual page of "ase agent fleet" (all equivalent, as no skill has this name)
+$ ase man ase-agent-fleet
+$ ase man agent-fleet
+$ ase man agent fleet
+
+# show the manual page of the skill "ase-task-edit" resp. of "ase task edit"
+$ ase man task-edit
+$ ase man task edit
+
+# browse the manual pages matching the keywords "worktree" and "merge"
+$ ase man worktree merge
+
+# print the manual page covering "ase task store start" as plain text
+$ ase man task store start | less
+
+# list all shipped manual pages of the commands
+$ ase man --list
+```
+
+## SEE ALSO
+
+`ase`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>