@rse/ase 2.0.3 → 2.0.5

package/dst/man/ase-task.md

@@ -0,0 +1,335 @@
+# ase-task(1) -- Manage Persisted Task Plans
+
+## SYNOPSIS
+
+`ase task`
+\[`-h`|`--help`\]
+*command*
+\[*options* \[...\]\]
+\[*args* \[...\]\]
+
+## DESCRIPTION
+
+**ase task** manages the persisted *task plans* of the current project.
+A task plan is a Markdown document in the textual *ASE* task format
+(see `ase util meta format-task`): a frontmatter block with the keys
+`Type`, `Id`, `Created`, `Modified`, `Group`, `Phase`, `After`,
+`Status`, `Assignee`, `Kind`, `Effort`, `Tags`, `Source`, `Changeset`,
+and `Target`, followed by the plan body and optional attachment blocks.
+
+The optional `Effort` key carries the estimated effort of the task as
+*size* *hash*, with *size* one of the T-shirt sizes `XS`, `S`, `M`, `L`,
+or `XL` (see `project.task.effort.scale` in `ase-config`(1)) and *hash*
+the content hash of the plan body the size was given for. The task
+store drops a *stale* `Effort` (whose *hash* no longer matches the
+body, ignoring checkboxes, whitespace, and cancelled or deferred
+bullet-points) on load and save, and stamps an `Effort` given without
+*hash* with the content hash of the body on save.
+
+All commands are forwarded to the *task store* selected by the
+`project.task.store.url` configuration (see **TASK STORES** below). The
+project is identified in the task store by `project.id` (default: the
+sanitized basename of the project root, i.e., the Git top-level
+directory, or the current working directory outside a Git working
+tree).
+
+The `Status` of the task plans follows the *task lifecycle model* of
+the project (see **TASK LIFECYCLE MODELS** below), and new task ids
+are generated after the *task id scheme* of the project (see
+**TASK ID SCHEMES** below).
+
+Without a *command*, the usage information is shown and the command
+exits with status `1`.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information of `ase task`, including the list of all
+  sub-commands, and exit.
+
+## COMMANDS
+
+- `ase task list` \[`-v`|`--verbose`\] \[`-i`|`--include` *states*\] \[`-e`|`--exclude` *states*\]:
+  List the persisted task ids. See `ase-task-list`(1).
+
+- `ase task status` \[*id*\[`:`\]\] \[*status*\]:
+  Get or set the lifecycle status of a task. See `ase-task-status`(1).
+
+- `ase task request` *id* *name* \[*prompt* ...\]:
+  Request the processing of a task by a prompt. See
+  `ase-task-request`(1).
+
+- `ase task assign` \[`-s`|`--session` *id*\] \[*id*\[`:`\]\] *assignee*:
+  Assign a task (and handle the AI usage window of a session). See
+  `ase-task-assign`(1).
+
+- `ase task load` *id*:
+  Write a task plan to standard output. See `ase-task-load`(1).
+
+- `ase task view` *id*:
+  Show a task plan in the pager. See `ase-task-view`(1).
+
+- `ase task edit` *id*:
+  Edit a task plan in the editor. See `ase-task-edit`(1).
+
+- `ase task save` \[`-c`|`--create`\] *id*:
+  Save a task plan read from standard input. See `ase-task-save`(1).
+
+- `ase task delete` *id*:
+  Delete a task plan. See `ase-task-delete`(1).
+
+- `ase task rename` *old-id* *new-id*:
+  Rename a task plan and its references. See `ase-task-rename`(1).
+
+- `ase task newid` \[`-p`|`--proposal` *id*\] \[`-t`|`--taken` *ids*\] \[`-v`|`--verbose`\] \[*title*\]:
+  Print the next free task id. See `ase-task-newid`(1).
+
+- `ase task purge` \[*age*\]:
+  Remove all task plans older than an age. See `ase-task-purge`(1).
+
+- `ase task lifecycle` \[*name*\]:
+  Get or set the task lifecycle model of the project. See
+  `ase-task-lifecycle`(1).
+
+- `ase task idscheme` \[*scheme*\]:
+  Get or set the task id scheme of the project. See
+  `ase-task-idscheme`(1).
+
+- `ase task store` *command* \[...\]:
+  Manage the per-user task store REST API server. See
+  `ase-task-store`(1).
+
+- `ase task board` \[*options*\]:
+  Show the interactive task board in the terminal or the browser. See
+  `ase-task-board`(1).
+
+## TASK IDS
+
+A task id consists of the characters `A-Z`, `a-z`, `0-9`, `#`, `_`,
+and `-`, where it has to start with a letter, a digit, or `#`, i.e.,
+it has to match `[A-Za-z0-9#][A-Za-z0-9#_-]*`. The id `default` is the
+reserved id of the default task of a session. As `#` starts a comment
+in the shell, an id containing `#` has to be quoted on the command
+line, e.g., `ase task view "#7"`.
+
+## TASK STORES
+
+The task store is selected by the `project.task.store.url`
+configuration URL (see `ase-config`(1)):
+
+- `ase:`*path*:
+  The built-in file-based storage plugin, running in-process, storing
+  each plan as a file `TASK-`*id*`.md` directly in the directory
+  *path*, which is resolved relative to the project root (default:
+  `ase:./.ase/task`).
+
+  On the `project` and `task:`*id* scopes, *path* must not escape the
+  project root (also not through symbolic links), as a cloned
+  repository could otherwise direct task writes anywhere; a directory
+  outside of it is accepted on the `user` or `session` scope only. The
+  lifecycle model and task id scheme of a local task store always
+  follow `project.task.lifecycle` and `project.task.idscheme`.
+
+- `ase://`*addr*`:`*port*\[`/`*token*\]:
+  A remote task store server (see `ase-task-store`(1)), connected via
+  HTTP. It requires an explicitly configured `project.id`, as a
+  basename-derived one likely collides on a shared server.
+
+  On first use, the project is registered in the task store under the
+  configured `project.task.lifecycle` and `project.task.idscheme`;
+  afterwards the registered model and scheme apply to all clients of
+  the project, and a deviating configuration is warned about once per
+  deviation only (see `ase-task-lifecycle`(1)).
+
+  The bearer token is the embedded *token* (warned about if the URL is
+  configured on the `project` or a `task:`*id* scope, as it might be
+  committed), else `$ASE_TASK_STORE_TOKEN`, else
+  `project.task.store.token` (warned about if not configured on the
+  `user` scope), else the `token` of the per-user `store.yaml` of a
+  locally started task store server (only if the URL addresses exactly
+  this server). Sending a token to a non-loopback host selected on the
+  `project` or a `task:`*id* scope is warned about.
+
+- `ases://`*addr*`:`*port*\[`/`*token*\]\[`?insecure`\]:
+  The same as `ase://`, but connecting via HTTPS, verifying the server
+  certificate against the Node.js CA store (extendable via
+  `$NODE_EXTRA_CA_CERTS`). With the suffix `?insecure`, the
+  verification of the server certificate is skipped.
+
+- `github:`*owner*`/`*repo*, `github+https://`*host*`/`*owner*`/`*repo*, or `github+http://`*host*`/`*owner*`/`*repo*:
+  The built-in GitHub storage plugin, running in-process, storing the
+  plans as the issues of the repository *owner*`/`*repo* on GitHub
+  resp. on the GitHub (Enterprise) instance *host*. It requires a `seq`
+  task id scheme (e.g., `seq:#%d`), as the task ids are the issue
+  numbers. The GitHub token is `project.task.store.token`, else
+  `$GITHUB_TOKEN`, else `$GH_TOKEN`.
+
+- `gitlab:`*namespace*`/`*project*, `gitlab://`*host*`/`*namespace*`/`*project*, `gitlab+https://`*host*`/`*namespace*`/`*project*, or `gitlab+http://`*host*`/`*namespace*`/`*project*:
+  The built-in GitLab storage plugin, running in-process, storing the
+  plans as the issues of the GitLab project *namespace*`/`*project*
+  (with nested groups allowed) on the GitLab instance *host*, else
+  `$GITLAB_HOST`, else `gitlab.com`. It also requires a `seq` task id
+  scheme. The GitLab token is `project.task.store.token`, else
+  `$GITLAB_TOKEN`.
+
+- `gitea+https://`*host*`/`*owner*`/`*repo* or `gitea+http://`*host*`/`*owner*`/`*repo*:
+  The built-in Gitea storage plugin, running in-process, storing the
+  plans as the issues of the repository *owner*`/`*repo* on the Gitea
+  instance *host*. It also requires a `seq` task id scheme. The Gitea
+  token is `project.task.store.token`, else `$GITEA_TOKEN`.
+
+For the GitHub, GitLab, and Gitea task stores, a repository selected
+on the `project` or a `task:`*id* scope is warned about once per
+project and repository only (remembered in the *per-user state
+directory* as `task-github.json`, `task-gitlab.json`, resp.
+`task-gitea.json`), and a `project.task.store.token` not configured on
+the `user` scope is warned about.
+
+## TASK LIFECYCLE MODELS
+
+The `Status` frontmatter key of a task plan holds a state of the task
+lifecycle model of the project, selected by `project.task.lifecycle`
+for a local task store resp. registered in a remote task store (see
+`ase-task-lifecycle`(1)). A plan without a `Status` key reads as the
+*initial* state of the model.
+
+A status change has to be reachable from the current state via one or
+more transitions of the model (a status foreign to the model can be
+changed to any state, to allow its correction). The *finished* states
+end the lifecycle, and in the *activity* states a task is actively
+worked on (by a human or an agent), so its plan must not be changed
+concurrently.
+
+- `solo`:
+  The single-phase lifecycle for a local solo developer (default).
+  States: `OPEN` (initial), `SHELVED`, `CLOSED` (finished), and
+  `CANCELLED` (finished); no activity states. Transitions: `OPEN` to
+  `SHELVED`, `CLOSED`, or `CANCELLED`; `SHELVED` to `OPEN` or
+  `CANCELLED`.
+
+- `team`:
+  The two-phase lifecycle for a distributed small team. States:
+  `PLANNING` (initial), `SHELVED`, `IMPLEMENTING` (activity),
+  `STALLED`, `IMPLEMENTED` (finished), and `CANCELLED` (finished).
+  Transitions: `PLANNING` to `SHELVED`, `IMPLEMENTING`, or
+  `CANCELLED`; `SHELVED` to `PLANNING` or `CANCELLED`; `IMPLEMENTING`
+  to `PLANNING`, `STALLED`, `IMPLEMENTED`, or `CANCELLED`; `STALLED`
+  to `IMPLEMENTING` or `CANCELLED`.
+
+- `enterprise`:
+  The four-phase lifecycle (planning, implementation, qualification, and
+  integration) for a gated enterprise pipeline, driven headless by the
+  agents of `ase-agent`(1). States: `DRAFTED` (initial), `SHELVED`,
+  `PLANNING` (activity), `PLANNED`, `STALLED`, `IMPLEMENTING`
+  (activity), `IMPLEMENTED`, `DECLINED`, `QUALIFYING` (activity),
+  `QUALIFIED`, `DEFERRED`, `INTEGRATING` (activity), `INTEGRATED`
+  (finished), and `CANCELLED` (finished).
+
+  Transitions: `DRAFTED` to `SHELVED`, `PLANNING`, or `CANCELLED`;
+  `SHELVED` to `DRAFTED` or `CANCELLED`; `PLANNING` to `DRAFTED`,
+  `SHELVED`, `PLANNED`, or `CANCELLED`; `PLANNED` to `STALLED`,
+  `IMPLEMENTING`, or `CANCELLED`; `STALLED` to `PLANNED` or
+  `CANCELLED`; `IMPLEMENTING` to `DRAFTED`, `PLANNED`, `STALLED`,
+  `IMPLEMENTED`, or `CANCELLED`; `IMPLEMENTED` to `DECLINED`,
+  `QUALIFYING`, or `CANCELLED`; `DECLINED` to `IMPLEMENTED` or
+  `CANCELLED`; `QUALIFYING` to `DRAFTED`, `PLANNED`, `IMPLEMENTED`,
+  `DECLINED`, `QUALIFIED`, or `CANCELLED`; `QUALIFIED` to `DEFERRED`,
+  `INTEGRATING`, or `CANCELLED`; `DEFERRED` to `QUALIFIED` or
+  `CANCELLED`; `INTEGRATING` to `DRAFTED`, `PLANNED`, `QUALIFIED`,
+  `DEFERRED`, `INTEGRATED`, or `CANCELLED`.
+
+In all models, no transition leaves a finished state.
+
+## TASK ID SCHEMES
+
+New task ids are generated by `ase-task-newid`(1) after the task id
+scheme of the project, selected by `project.task.idscheme` for a local
+task store resp. registered in a remote task store (see
+`ase-task-idscheme`(1)):
+
+- `slug`\[`:`*words*\]:
+  The slug of the first *words* (`1`-`16`, default: `2`) words of the
+  task title, starting with the first word beginning with a letter,
+  with diacritics stripped, lower-cased, and joined with `-`, e.g.,
+  `json-export` (default scheme). Conforming ids match
+  `^[a-z][a-z0-9]*(?:-[a-z0-9]+){0,`*words-1*`}(?:-[0-9]+)?$`.
+
+- `seq`\[`:`*template*\]:
+  A continuously increasing sequence number, rendered through the
+  sprintf-style *template* (default: `%d`) with exactly one `%d` or
+  `%0`*width*`d` (*width* `0`-`16`) and otherwise only the characters
+  `A-Z`, `a-z`, `#`, `_`, and `-` (but not starting with `_` or `-`),
+  e.g., `FOO-%03d` (`FOO-007`) or `#%d` (`#7`). Conforming ids match
+  *prefix*`([0-9]+)`*suffix* (resp. with at least *width* digits).
+
+- `any`:
+  An arbitrary id, as proposed by the caller. Conforming ids match
+  `^[A-Za-z0-9#][A-Za-z0-9#_-]*$`.
+
+An id not conforming to the scheme is accepted, but warned about on
+`ase task save`, `ase task edit`, and `ase task rename` (the reserved
+id `default` always conforms).
+
+## ENVIRONMENT
+
+- `ASE_TASK_ID`:
+  The default task id of `ase task status` and `ase task assign`
+  (default: `default`).
+
+- `ASE_TASK_STORE_TOKEN`:
+  The bearer token of a remote (`ase://` or `ases://`) task store.
+
+- `GITHUB_TOKEN`, `GH_TOKEN`, `GITLAB_TOKEN`, `GITLAB_HOST`, `GITEA_TOKEN`:
+  The tokens resp. the default host of the GitHub, GitLab, and Gitea
+  task stores (see **TASK STORES**).
+
+## FILES
+
+- `.ase/task/TASK-`*id*`.md`:
+  The persisted task plans of the default local task store
+  `ase:./.ase/task`, relative to the project root.
+
+- `.ase/config.yaml`:
+  The `project` scope configuration with the `project.id`,
+  `project.task.store.url`, `project.task.lifecycle`, and
+  `project.task.idscheme` keys.
+
+- *per-user state directory*`/task-lifecycle.json`:
+  The deviations of the configured lifecycle model and task id scheme
+  from the ones of a remote task store already warned about.
+
+- *per-user state directory*`/task-github.json`, `task-gitlab.json`, `task-gitea.json`:
+  The repositories of the issue tracker task stores already warned
+  about.
+
+## EXAMPLES
+
+```sh
+# list all unfinished tasks with their status, time, effort, and title
+$ ase task list -v
+
+# create a new task from a title and a plan file
+$ id=$(ase task newid "Export as JSON")
+$ ase task save --create "$id" <plan.md
+
+# move the task forward in the lifecycle
+$ ase task status "$id" CLOSED
+
+# use a shared remote task store
+$ ase config --scope project set project.id myproject
+$ ase config --scope project set project.task.store.url ase://127.0.0.1:4711
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-task-list`(1), `ase-task-status`(1),
+`ase-task-request`(1), `ase-task-assign`(1), `ase-task-load`(1),
+`ase-task-view`(1), `ase-task-edit`(1), `ase-task-save`(1),
+`ase-task-delete`(1), `ase-task-rename`(1), `ase-task-newid`(1),
+`ase-task-purge`(1), `ase-task-lifecycle`(1), `ase-task-idscheme`(1),
+`ase-task-store`(1), `ase-task-board`(1), `ase-config`(1),
+`ase-agent`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-util-compat.md

@@ -0,0 +1,38 @@
+# ase-util-compat(1) -- Output Expected Probe Values of the Compatibility Self-Test
+
+## SYNOPSIS
+
+`ase util compat`
+\[`-h`|`--help`\]
+
+## DESCRIPTION
+
+**ase util compat** writes the canonical expected values of all probes
+of the `ase-meta-compat` self-test skill to standard output, one probe
+per line as *id*`: `*value*, where *id* is
+*category*`/`*probe-name*. The probe categories are `xml-placeholders`,
+`control-flow`, `regex`, and `arithmetic`, which check whether the
+model of the agent tool correctly interprets the pseudo-code
+constructs the *ASE* skills are written in.
+
+This command is intended to be invoked by the skill only after it has
+recorded all actual probe results (so the model cannot see the
+expected values beforehand), and not directly by end users. The MCP
+tool `ase_compat` provides the same.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## EXIT STATUS
+
+Exits with status `0`.
+
+## SEE ALSO
+
+`ase`(1), `ase-util`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-util-diagram.md

@@ -0,0 +1,140 @@
+# ase-util-diagram(1) -- Render Mermaid or D2 Diagrams as Unicode/ASCII Art or SVG
+
+## SYNOPSIS
+
+`ase util diagram`
+\[`-h`|`--help`\]
+\[`-i`|`--input` *file*\]
+\[`-l`|`--lang` `mermaid`|`d2`\]
+\[`-f`|`--format` `ascii`|`svg`\]
+\[`-a`|`--ascii`\]
+\[`-c`|`--color-mode` `none`|`ansi16`|`ansi256`\]
+\[`--node-margin-x` *n*\]
+\[`--node-margin-y` *n*\]
+\[`--node-padding` *n*\]
+\[`--diagram-clip-x` *n*\]
+\[`--diagram-clip-y` *n*\]
+\[`--terminal-width` *n*\]
+\[`--terminal-height` *n*\]
+
+## DESCRIPTION
+
+**ase util diagram** renders a diagram specification, written in the
+*Mermaid* or *D2* diagram language and read from standard input or a
+file, as Unicode box-drawing (or plain ASCII) art for the terminal, or
+as a self-contained SVG document. The *Mermaid* diagrams are rendered
+via *beautiful-mermaid* (supporting, e.g., flowcharts, UML state,
+sequence, and class diagrams, ER diagrams, and XY-charts), and the
+*D2* diagrams via the WebAssembly build of *D2*.
+
+For the `ascii` format, the rendering is optionally clipped to the
+terminal dimensions (reduced by the extra clipping amounts): lines
+wider than the width budget are truncated (preserving and properly
+terminating any ANSI color sequences), and lines beyond the height
+budget are dropped.
+
+A clipped rendering is followed by a warning paragraph which states
+the overflow and advises how to regenerate the diagram source to fit
+(e.g., by preferring a portrait orientation, reducing siblings per
+row, abbreviating node labels, or nesting). The output always ends
+with a newline.
+
+The MCP tool `ase_diagram` provides the same to the skills.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-i`|`--input` *file*\]:
+  Read the diagram specification from *file* instead of standard
+  input. An empty (or whitespace-only) specification is an error.
+
+- \[`-l`|`--lang` `mermaid`|`d2`\]:
+  The diagram language: `mermaid` for *Mermaid* (default) or `d2` for
+  *D2*.
+
+- \[`-f`|`--format` `ascii`|`svg`\]:
+  The output format: `ascii` for Unicode/ASCII art (default) or `svg`
+  for an SVG document. The clipping options apply to `ascii` only.
+
+- \[`-a`|`--ascii`\]:
+  Emit plain ASCII characters (`+`, `-`, `|`) instead of the Unicode
+  box-drawing characters (for both languages).
+
+- \[`-c`|`--color-mode` `none`|`ansi16`|`ansi256`\]:
+  The color mode of the ANSI escape sequences in the rendered art
+  (*Mermaid* and `ascii` only): `none` for no colors, `ansi16` for 16
+  colors, or `ansi256` for 256 colors, where colors render the diagram
+  in gray shades. Default: `$ASE_TERM_COLORS` if set to one of these
+  values, else derived from the color depth of standard output if it is
+  a terminal (`ansi256` for at least 8 bits, `ansi16` for at least 4
+  bits), else `none`.
+
+- \[`--node-margin-x` *n*\]:
+  The horizontal margin between nodes in characters (*Mermaid* only,
+  default: `3`).
+
+- \[`--node-margin-y` *n*\]:
+  The vertical margin between nodes in lines (*Mermaid* only, default:
+  `3`).
+
+- \[`--node-padding` *n*\]:
+  The horizontal and vertical inner padding of each node in characters
+  (*Mermaid* only, default: `1`).
+
+- \[`--diagram-clip-x` *n*\]:
+  The extra horizontal clipping: the width budget is the terminal width
+  minus *n* characters (default: `0`).
+
+- \[`--diagram-clip-y` *n*\]:
+  The extra vertical clipping: the height budget is the terminal height
+  minus *n* lines (default: `0`).
+
+- \[`--terminal-width` *n*\]:
+  The terminal width in characters for the clipping, where `0` disables
+  the horizontal clipping. Default: `$ASE_TERM_WIDTH` if a positive
+  integer, else the width of standard output if it is a terminal, else
+  `0`.
+
+- \[`--terminal-height` *n*\]:
+  The terminal height in lines for the clipping, where `0` disables the
+  vertical clipping. Default: `$ASE_TERM_HEIGHT` if a positive integer,
+  else the height of standard output if it is a terminal, else `0`.
+
+All numeric values *n* have to be non-negative integers.
+
+## ENVIRONMENT
+
+- `ASE_TERM_COLORS`:
+  The default of `--color-mode` (`none`, `ansi16`, or `ansi256`).
+
+- `ASE_TERM_WIDTH`, `ASE_TERM_HEIGHT`:
+  The defaults of `--terminal-width` and `--terminal-height`.
+
+## EXIT STATUS
+
+Exits with status `0` on success, and with status `1` on an invalid
+option value, an unreadable input file, an empty specification, or a
+rendering failure (e.g., a syntax error in the specification).
+
+## EXAMPLES
+
+```sh
+# render a Mermaid flowchart as Unicode art
+$ printf 'flowchart LR\n    A --> B --> C\n' | ase util diagram
+
+# render a D2 diagram from a file as plain ASCII art without colors
+$ ase util diagram -l d2 -i arch.d2 -a -c none
+
+# render a Mermaid diagram as an SVG document
+$ ase util diagram -i flow.mmd -f svg >flow.svg
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-util`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-util-meta.md

@@ -0,0 +1,68 @@
+# ase-util-meta(1) -- Output Plugin Meta Files
+
+## SYNOPSIS
+
+`ase util meta`
+\[`-h`|`--help`\]
+*name* \[...\]
+
+## DESCRIPTION
+
+**ase util meta** writes the contents of one or more *meta files* of
+the *ASE* plugin to standard output, concatenated in the given order
+and without any separator.
+
+The meta files are the shared instructions and format conventions of
+the *ASE* skills, e.g., the constitution (`ase-constitution.md`), the
+tenets (`ase-tenets.md`), the persona (`ase-persona.md`), the dialog
+conventions (`ase-dialog.md`), the option parsing conventions
+(`ase-getopt.md`), and the artifact format conventions
+(`ase-format-*.md`, plus the standard *SpecBook* schema configuration
+`ase-format-specbook.yaml`).
+
+The meta files are read from the `plugin/meta/` directory bundled with
+the tool package itself, independent of any environment variables. All
+requested files are read before any output is written, so a failing
+name produces no output at all.
+
+This command is intended to be leveraged by the *ASE* skills, and not
+typically invoked directly by end users.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## ARGUMENTS
+
+- *name* \[...\]:
+  One or more meta file names. Each *name* is reduced to its base name
+  (so no directory traversal or absolute path is possible), the
+  extension `.md` is appended if it has no extension, and the prefix
+  `ase-` is prepended if missing, so `tenets`, `ase-tenets`, and
+  `tenets.md` all select `ase-tenets.md`, while `format-specbook.yaml`
+  selects `ase-format-specbook.yaml`. An empty name, `.`, and `..` are
+  invalid.
+
+## EXIT STATUS
+
+Exits with status `0` on success, and with status `1` if a name is
+invalid or a meta file cannot be read.
+
+## EXAMPLES
+
+```sh
+# output the ASE constitution
+$ ase util meta constitution
+
+# output the tenets and the persona definition
+$ ase util meta tenets persona
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-util`(1), `ase-spec`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-util-metric.md

@@ -0,0 +1,74 @@
+# ase-util-metric(1) -- Measure the Length Metrics of a Text
+
+## SYNOPSIS
+
+`ase util metric`
+\[`-h`|`--help`\]
+\[`-f`|`--file` *file*\]
+\[*text* \[...\]\]
+
+## DESCRIPTION
+
+**ase util metric** measures the length metrics of a text, given either
+as the content of a *file* or as the *text* formed by the remaining
+arguments (joined by single spaces), which are mutually exclusive and
+of which exactly one has to be given. The metrics are printed to
+standard output as a single-line JSON object with the fields:
+
+- `words`:
+  The number of whitespace-separated tokens.
+
+- `lines`:
+  The number of newline-separated lines, where a trailing line without
+  a final newline still counts as one line (and an empty text has `0`
+  lines).
+
+- `chars`:
+  The number of Unicode characters, i.e., code points.
+
+- `bytes`:
+  The number of octets: the raw file size for a *file* (as its
+  encoding is not necessarily UTF-8), resp. the UTF-8 length for a
+  *text*.
+
+A *file* is decoded as UTF-8 for the other metrics. This backs the
+MCP tool `ase_text_metric`, which the skills use instead of estimating
+a text length themselves.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-f`|`--file` *file*\]:
+  Measure the content of *file* instead of the *text* arguments.
+
+## ARGUMENTS
+
+- \[*text* \[...\]\]:
+  The text to measure, formed by all arguments joined by single spaces
+  (mutually exclusive with `--file`).
+
+## EXIT STATUS
+
+Exits with status `0` on success, and with status `1` if both or none
+of *file* and *text* are given, or *file* cannot be read.
+
+## EXAMPLES
+
+```sh
+# measure a document
+$ ase util metric -f README.md
+
+# measure a text
+$ ase util metric "Hello, World!"
+{"words":2,"lines":1,"chars":13,"bytes":13}
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-util`(1), `wc`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>