@rse/ase 2.0.3 → 2.0.4

package/dst/man/ase-setup-telemetry.md

@@ -0,0 +1,166 @@
+# ase-setup-telemetry(1) -- Activate or Deactivate the ASE Telemetry Export
+
+## SYNOPSIS
+
+`ase setup telemetry`
+\[`-h`|`--help`\]
+
+`ase setup telemetry activate`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+
+`ase setup telemetry deactivate`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+
+## DESCRIPTION
+
+**ase setup telemetry** activates or deactivates the *OpenTelemetry*
+(OTLP/HTTP) export of the agent tool towards the per-user *ASE* OTLP
+ingress `http://127.0.0.1:`*port* (with *port* from the configuration
+`telemetry.service.port`, default `44318`), which feeds the AI usage
+accounting of the task assignments (see `ase-task-assign`(1)).
+Without a sub-command, the usage information is shown and the command
+exits with status `1`.
+
+The export is always user-level, as the agent tools ignore these
+settings on repository level, so a single ingress serves the sessions
+of all projects: every running `ase service` tries to hold its port,
+and the holder routes the records by their session to the service of
+the owning project. Hence, there is no `--scope` option.
+
+Telemetry configured by the user for other receivers is never touched:
+it is preserved with a warning (and the command still exits with
+status `0`), and reported as `foreign` by `ase setup status`.
+
+## COMMANDS
+
+- `ase setup telemetry activate` \[`-t`|`--tool` *tool*\]:
+  Configure the telemetry export of the agent tool. As the AI usage
+  accounting is opt-in, this requires the configuration
+  `telemetry.enabled` to be `true` (e.g., via `ase config set
+  telemetry.enabled true` on scope `user` or `project`), else the
+  command fails with an error. A missing bearer token
+  `telemetry.service.token` is generated (48 hexadecimal digits) and
+  persisted on scope `user`. Per agent tool:
+
+    - `claude`:
+      The variables `CLAUDE_CODE_ENABLE_TELEMETRY=1`,
+      `OTEL_LOGS_EXPORTER=otlp`,
+      `OTEL_EXPORTER_OTLP_PROTOCOL=http/json`,
+      `OTEL_EXPORTER_OTLP_ENDPOINT=`*url*,
+      `OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer `*token*, and
+      `OTEL_LOGS_EXPORT_INTERVAL=5000` are added to (resp. updated in)
+      the `env` object of `~/.claude/settings.json`.
+
+      If any of these variables is already set there, but points
+      neither to the URL nor carries the token of the *ASE* ingress, the
+      configuration is foreign and preserved; a non-object `env` is
+      preserved, too.
+    - `codex`:
+      A marked block (between the lines `# BEGIN ASE telemetry
+      (generated)` and `# END ASE telemetry (generated)`) with an
+      `[otel]` table, exporting via `otlp-http` with protocol `json` to
+      *url*`/v1/logs` with the `authorization` header `Bearer`
+      *token*, is added to (resp. replaced in)
+      `$CODEX_HOME/config.toml` (default: `~/.codex/config.toml`). An
+      `[otel]` table outside of the block is foreign and preserved.
+    - `copilot`:
+      As *GitHub Copilot CLI* is configurable via environment
+      variables only, a marked block with a shell function `copilot`
+      is added to (resp. replaced in) the shell profile of the login
+      shell of `$SHELL` (`$ZDOTDIR/.zshrc`, default `~/.zshrc`, for
+      `zsh`, and `~/.bashrc` for `bash`), which passes the variables
+      `COPILOT_OTEL_ENABLED=true`,
+      `COPILOT_OTEL_EXPORTER_TYPE=otlp-http`,
+      `OTEL_EXPORTER_OTLP_ENDPOINT=`*url*,
+      `OTEL_EXPORTER_OTLP_PROTOCOL=http/json`, and
+      `OTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer `*token* to the
+      `copilot` command only, instead of exporting them to every other
+      program. A new shell session is required for it to take effect.
+
+      For any other shell, the command fails with an error showing the
+      shell function to define manually. An `$OTEL_EXPORTER_OTLP_ENDPOINT`
+      of the environment other than the *ASE* ingress URL, and an
+      assignment of `COPILOT_OTEL_ENABLED` or `OTEL_EXPORTER_OTLP_ENDPOINT`
+      in the profile outside of the block, are foreign and preserved.
+
+- `ase setup telemetry deactivate` \[`-t`|`--tool` *tool*\]:
+  Remove the telemetry export configured by `ase setup telemetry
+  activate` again, preserving any foreign telemetry configuration. It
+  does not require `telemetry.enabled`.
+
+  Per agent tool: for `claude`, the above variables are removed from the
+  `env` of `~/.claude/settings.json` (and the `env` itself, if it became
+  empty); for `codex`, the marked block is removed from
+  `$CODEX_HOME/config.toml`; and for `copilot`, the marked block is
+  removed from all candidate shell profiles (`~/.zshrc`, `~/.bashrc`,
+  and the profile of the login shell). A missing file or configuration
+  is skipped with an informational message.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-t`|`--tool` *tool*\]:
+  Select the target agent tool: `claude`, `copilot`, or `codex`
+  (default: `$ASE_TOOL`, else `claude`).
+
+## ENVIRONMENT
+
+- `ASE_TOOL`:
+  The default of `--tool`.
+
+- `CODEX_HOME`:
+  The configuration directory of *OpenAI Codex CLI* (default:
+  `~/.codex`).
+
+- `SHELL`, `ZDOTDIR`:
+  The login shell, determining the shell profile for `--tool copilot`,
+  and the configuration directory of `zsh`.
+
+- `OTEL_EXPORTER_OTLP_ENDPOINT`:
+  An existing OTLP endpoint for `--tool copilot`, which, if not the
+  *ASE* ingress, is considered a foreign telemetry configuration.
+
+## FILES
+
+- `~/.claude/settings.json`:
+  The user-level settings file of *Anthropic Claude Code CLI*.
+
+- `$CODEX_HOME/config.toml` (default: `~/.codex/config.toml`):
+  The configuration file of *OpenAI Codex CLI*.
+
+- `~/.zshrc`, `~/.bashrc`:
+  The shell profiles receiving the `copilot` shell function.
+
+## EXIT STATUS
+
+`0` on success (including a preserved foreign configuration), `1` on
+any error (e.g., a disabled AI usage accounting on `activate`, an
+unsupported shell for `--tool copilot`, an unterminated marked block,
+and when invoked without a sub-command).
+
+## EXAMPLES
+
+```sh
+# enable the AI usage accounting and activate the export of Claude Code
+$ ase config --scope user set telemetry.enabled true
+$ ase setup telemetry activate
+
+# activate the export of OpenAI Codex CLI
+$ ase setup telemetry activate --tool codex
+
+# deactivate the export of GitHub Copilot CLI
+$ ase setup telemetry deactivate --tool copilot
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-setup`(1), `ase-setup-status`(1), `ase-config`(1),
+`ase-service`(1), `ase-task-assign`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-setup-uninstall.md

@@ -0,0 +1,85 @@
+# ase-setup-uninstall(1) -- Uninstall the ASE Plugin and Tool
+
+## SYNOPSIS
+
+`ase setup uninstall`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+\[`-s`|`--scope` *scope*\]
+\[`-d`|`--dev`\]
+
+## DESCRIPTION
+
+**ase setup uninstall** uninstalls the *ASE* plugin from the agent
+tool selected by `--tool` and the *ASE* tool itself. It requires
+`npm`(1) and the CLI of the agent tool to be found in `$PATH`. The
+steps are:
+
+1. A potentially running `ase service` of the current project is
+   stopped (on a best-effort basis).
+2. For `--tool claude`, the selection of the output style
+   `ase:ase-terse` is removed from the `settings.json` of the
+   installation scope, while a foreign `outputStyle` is preserved with
+   a warning.
+3. The plugin `ase@ase` is uninstalled (`<cli> plugin uninstall
+   ase@ase`, resp. `codex plugin remove ase@ase`) and the plugin
+   marketplace `ase` is removed (`<cli> plugin marketplace remove
+   ase`), where an already absent plugin or marketplace is skipped.
+4. Unless in development mode (`--dev`), the tool is uninstalled via
+   `npm uninstall -g @rse/ase` (prefixed with `sudo`(8) if the global
+   `npm` installation root is not writable by the current user and
+   `sudo` is available).
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-t`|`--tool` *tool*\]:
+  Select the target agent tool: `claude`, `copilot`, or `codex`
+  (default: `$ASE_TOOL`, else `claude`).
+
+- \[`-s`|`--scope` *scope*\]:
+  Select the plugin installation scope: `user`, `project`, or
+  `local`. The default is auto-detected from the existing
+  installation: the scopes `local`, `project`, and `user` are probed
+  in this order, and the first one whose settings file registers the
+  plugin `ase@ase` under `enabledPlugins` is taken, falling back to
+  `user`. Only supported for `--tool claude`; a non-`user` scope for
+  `copilot` or `codex` fails with an error.
+
+- \[`-d`|`--dev`\]:
+  Development mode: uninstall the plugin only, but keep the *ASE*
+  tool, as it is the local working copy (default: `$ASE_SETUP_DEV`).
+
+## ENVIRONMENT
+
+- `ASE_TOOL`:
+  The default of `--tool`.
+
+- `ASE_SETUP_DEV`:
+  The default of `--dev`: any non-empty value other than `0` and
+  `false` (case-insensitive) enables it.
+
+## EXIT STATUS
+
+`0` on success, `1` on any error.
+
+## EXAMPLES
+
+```sh
+# uninstall ASE from Anthropic Claude Code CLI
+$ ase setup uninstall
+
+# uninstall the plugin from GitHub Copilot CLI
+$ ase setup uninstall --tool copilot
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-setup`(1), `ase-setup-install`(1),
+`ase-setup-disable`(1), `npm`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-setup-update.md

@@ -0,0 +1,117 @@
+# ase-setup-update(1) -- Update the ASE Tool and Plugin
+
+## SYNOPSIS
+
+`ase setup update`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+\[`-s`|`--scope` *scope*\]
+\[`-f`|`--force`\]
+\[`-d`|`--dev`\]
+
+## DESCRIPTION
+
+**ase setup update** updates the *ASE* tool and the *ASE* plugin of
+the agent tool selected by `--tool` to their latest versions. It
+requires `npm`(1) and the CLI of the agent tool to be found in
+`$PATH`. First, a potentially running `ase service` of the current
+project is stopped (on a best-effort basis), as it would otherwise
+keep running the old code.
+
+In the regular mode, the current version of the tool is compared with
+the latest version of `@rse/ase` known from the NPM registry (as
+determined by a cached background check, refreshed at most once per
+hour). If both are equal, the command reports that *ASE* is already at
+the latest version and exits without any further action (unless
+`--force` is given).
+
+Otherwise, the tool is updated via `npm update -g @rse/ase` (prefixed
+with `sudo`(8) if the global `npm` installation root is not writable by
+the current user and `sudo` is available), the plugin marketplace
+snapshot is refreshed (`<cli> plugin marketplace update ase`, resp.
+`codex plugin marketplace upgrade ase`), and the plugin is updated
+(`<cli> plugin update ase@ase`, resp. removed and re-added for *OpenAI
+Codex CLI*, which has no plugin update command).
+
+In the development mode (`--dev`), the local *ASE* working copy is
+re-built instead (`npm install` and `npm start build` in its `tool/`
+directory), and the plugin is re-installed (uninstalled and
+installed again), as the local plugin files are already current, but
+carry no version change in the plugin manifest.
+
+Like `ase setup install`, for `--tool claude`, the output style
+`ase:ase-terse` is finally selected in the `settings.json` of the
+installation scope, unless a foreign `outputStyle` is already selected
+there, which is preserved with a warning.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-t`|`--tool` *tool*\]:
+  Select the target agent tool: `claude`, `copilot`, or `codex`
+  (default: `$ASE_TOOL`, else `claude`).
+
+- \[`-s`|`--scope` *scope*\]:
+  Select the plugin installation scope: `user`, `project`, or
+  `local`. The default is auto-detected from the existing
+  installation: the scopes `local`, `project`, and `user` are probed
+  in this order (strongest first), and the first one whose settings
+  file registers the plugin `ase@ase` under `enabledPlugins` (enabled
+  or disabled) is taken, falling back to `user` when no installation
+  is found.
+
+  For tools other than `claude`, the scope is always `user`, and an
+  explicitly given non-`user` scope fails with an error.
+
+- \[`-f`|`--force`\]:
+  Always perform the update, even if the tool is already at the
+  latest version (default: off). Without effect in combination with
+  `--dev`, which always re-builds.
+
+- \[`-d`|`--dev`\]:
+  Development mode: re-build the local *ASE* working copy
+  (`$ASE_SETUP_DEV_BASEDIR`, else the parent directory of the
+  `@rse/ase` package directory) and re-install the plugin from it,
+  instead of updating from the NPM registry (default:
+  `$ASE_SETUP_DEV`).
+
+## ENVIRONMENT
+
+- `ASE_TOOL`:
+  The default of `--tool`.
+
+- `ASE_SETUP_DEV`:
+  The default of `--dev`: any non-empty value other than `0` and
+  `false` (case-insensitive) enables it.
+
+- `ASE_SETUP_DEV_BASEDIR`:
+  The local *ASE* working copy used with `--dev`.
+
+## EXIT STATUS
+
+`0` on success (including an already current version), `1` on any
+error.
+
+## EXAMPLES
+
+```sh
+# update ASE for Anthropic Claude Code CLI
+$ ase setup update
+
+# force the update for OpenAI Codex CLI
+$ ase setup update --tool codex --force
+
+# re-build and re-install from the local working copy
+$ ase setup update --dev
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-setup`(1), `ase-setup-install`(1),
+`ase-setup-uninstall`(1), `ase-service`(1), `npm`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-setup.md

@@ -0,0 +1,156 @@
+# ase-setup(1) -- Install, Update, and Uninstall the ASE Tool and Plugin
+
+## SYNOPSIS
+
+`ase setup`
+\[`-h`|`--help`\]
+*command*
+\[*options* \[...\]\]
+\[*args* \[...\]\]
+
+## DESCRIPTION
+
+**ase setup** is the entry point group for installing, updating,
+uninstalling, enabling, disabling, and reporting the *ASE* tool and its
+companion agent tool plugin, and for activating or deactivating the
+pre-defined foreign MCP servers, the *ASE* statusline, and the *ASE*
+telemetry export towards the AI usage accounting. Without a
+*command*, the usage information is shown and the command exits with
+status `1`.
+
+The target agent tool is either *Anthropic Claude Code CLI*
+(`claude`), *GitHub Copilot CLI* (`copilot`), or *OpenAI Codex CLI*
+(`codex`). All operations are performed through the plugin and MCP
+commands of the respective agent tool CLI (e.g., `claude plugin
+install`), which hence has to be found in `$PATH`, and through direct
+edits of its settings files (for the output style, the statusline,
+and the telemetry). Every sub-process command is logged (with API keys
+masked) and its output is shown only on failure.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information of the command group and exit.
+
+The following options are shared by most sub-commands (see their
+individual manual pages for the exact applicability):
+
+- \[`-t`|`--tool` *tool*\]:
+  Select the target agent tool: `claude` (*Anthropic Claude Code
+  CLI*), `copilot` (*GitHub Copilot CLI*), or `codex` (*OpenAI Codex
+  CLI*). The default is the value of the environment variable
+  `ASE_TOOL`, if set and non-empty, else `claude`. An invalid value
+  is rejected with an error. Accepted by all sub-commands except `ase
+  setup mcp list`.
+
+- \[`-s`|`--scope` *scope*\]:
+  Select the installation scope of the plugin, MCP server, or
+  statusline registration: `user` (registered globally for the
+  current user), `project` (registered in the project and meant to be
+  shared via version control), or `local` (registered in the project,
+  but kept out of version control).
+
+  Only supported for `--tool claude` (and, for the statusline, a `user`
+  scope for `--tool copilot`); a non-`user` scope for any other tool
+  fails with an error, as those agent tools have no scope concept. Not
+  accepted by `ase setup status` (which reports all scopes at once) and
+  `ase setup telemetry` (which is always user-level).
+
+## COMMANDS
+
+- `ase setup install` \[`-t`|`--tool` *tool*\] \[`-s`|`--scope` *scope*\] \[`-d`|`--dev`\]:
+  Install the *ASE* plugin into the agent tool. See
+  `ase-setup-install`(1).
+
+- `ase setup update` \[`-t`|`--tool` *tool*\] \[`-s`|`--scope` *scope*\] \[`-f`|`--force`\] \[`-d`|`--dev`\]:
+  Update the *ASE* tool and the *ASE* plugin to their latest
+  versions. See `ase-setup-update`(1).
+
+- `ase setup uninstall` \[`-t`|`--tool` *tool*\] \[`-s`|`--scope` *scope*\] \[`-d`|`--dev`\]:
+  Uninstall the *ASE* plugin and the *ASE* tool. See
+  `ase-setup-uninstall`(1).
+
+- `ase setup enable` \[`-t`|`--tool` *tool*\] \[`-s`|`--scope` *scope*\]:
+  Enable the already installed *ASE* plugin. See
+  `ase-setup-enable`(1).
+
+- `ase setup disable` \[`-t`|`--tool` *tool*\] \[`-s`|`--scope` *scope*\]:
+  Disable the *ASE* plugin without uninstalling it. See
+  `ase-setup-disable`(1).
+
+- `ase setup status` \[`-t`|`--tool` *tool*\]:
+  Report the plugin, MCP server, output style, statusline, and
+  telemetry registrations of all scopes. See `ase-setup-status`(1).
+
+- `ase setup mcp` `list`|`activate`|`deactivate` \[...\]:
+  List, activate, or deactivate the pre-defined foreign MCP servers.
+  See `ase-setup-mcp`(1).
+
+- `ase setup statusline` `activate`|`deactivate` \[...\]:
+  Activate or deactivate the *ASE* statusline. See
+  `ase-setup-statusline`(1).
+
+- `ase setup telemetry` `activate`|`deactivate` \[...\]:
+  Activate or deactivate the *OpenTelemetry* export of the agent tool
+  towards the *ASE* OTLP ingress. See `ase-setup-telemetry`(1).
+
+## ENVIRONMENT
+
+- `ASE_TOOL`:
+  The default of the `--tool` option (default: `claude`).
+
+- `ASE_SETUP_DEV`:
+  The default of the `--dev` option of `ase setup install`, `ase setup
+  update`, and `ase setup uninstall`: any non-empty value other than
+  `0` and `false` (case-insensitive) enables it.
+
+- `ASE_SETUP_DEV_BASEDIR`:
+  The base directory of the local *ASE* working copy used with
+  `--dev` (default: the parent directory of the installed `@rse/ase`
+  package directory).
+
+- `ASE_MCP_KEY_`*KEY*:
+  The API keys of the pre-defined MCP servers (see `ase-setup-mcp`(1)).
+
+## FILES
+
+- `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`:
+  The settings files of *Anthropic Claude Code CLI* of the scopes
+  `user`, `project`, and `local` (the latter two relative to the
+  current working directory).
+
+- `$COPILOT_HOME/settings.json` (default: `~/.copilot/settings.json`):
+  The single per-user settings file of *GitHub Copilot CLI*.
+
+- `$CODEX_HOME/config.toml` (default: `~/.codex/config.toml`):
+  The per-user configuration file of *OpenAI Codex CLI*.
+
+## EXIT STATUS
+
+`0` on success, `1` on any error, and `1` when invoked without a
+*command*.
+
+## EXAMPLES
+
+```sh
+# install ASE for Anthropic Claude Code CLI globally
+$ ase setup install
+
+# install ASE for OpenAI Codex CLI
+$ ase setup install --tool codex
+
+# report all ASE registrations
+$ ase setup status
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-setup-install`(1), `ase-setup-update`(1),
+`ase-setup-uninstall`(1), `ase-setup-enable`(1),
+`ase-setup-disable`(1), `ase-setup-status`(1), `ase-setup-mcp`(1),
+`ase-setup-statusline`(1), `ase-setup-telemetry`(1),
+`claude`(1), `copilot`(1), `codex`(1), `npm`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

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

@@ -0,0 +1,99 @@
+# ase-spec-export(1) -- Export the Project Specification
+
+## SYNOPSIS
+
+`ase spec export`
+\[`-h`|`--help`\]
+\[`-o`|`--output` \[*format*`:`\]*file*\] \[...\]
+\[`-w`|`--watch`\]
+
+## DESCRIPTION
+
+**ase spec export** exports the *SpecBook*-based specification Markdown
+files below `project.artifact.spec.basedir` (see `ase-spec`(1)) into one
+or more output files. The supported formats are:
+
+- `json`, `json5`, `yaml`, `toon`:
+  The specification object model in the respective serialization.
+- `html`:
+  A self-contained single HTML document.
+- `pdf`:
+  A paginated print document.
+- `md`:
+  A normalized single Markdown document.
+
+The specification is parsed once, and each distinct format is exported
+once, even if requested for multiple outputs. Each written file is
+logged at the `info` level. The export fails on any lint diagnostic
+of `error` severity (see `ase-spec-lint`(1)), while warnings are only
+logged, so a partial or invalid specification is never emitted.
+
+The `pdf` format additionally requires a Chromium-class browser, which
+neither `npm install -g @rse/ase` nor `ase setup install` provides:
+unless a *Google Chrome* is installed system-wide, fetch the
+*Playwright* Chromium once via `npx playwright install chromium`.
+Without any such browser, the export fails before the specification is
+even parsed and reports that very command.
+
+The MCP tool `ase_specbook_export` provides the same to the skills.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-o`|`--output` \[*format*`:`\]*file*\]:
+  Write the export into *file*, or to standard output for `-`. The
+  option is repeatable, so multiple outputs (of the same or different
+  formats) are written in a single run. The *format* is inferred from
+  the filename extension (`json`, `json5`, `yaml` or `yml`, `toon`,
+  `html` or `htm`, `pdf`, and `md` or `markdown`, case-insensitive)
+  unless explicitly given as a prefix of at least two characters (out
+  of the same names), where a plain `-` defaults to `json`.
+
+  The log is written to standard error (see `ase`(1)), so it never
+  mixes into the export on standard output. An unknown format prefix and
+  a not inferable format are errors. A relative *file* is relative to the
+  current working directory. Default: the HTML rendering into
+  `index.html` inside the specification base directory (e.g.,
+  `docs/specbook/index.html`).
+
+- \[`-w`|`--watch`\]:
+  Do not terminate after the initial export, but keep the outputs in
+  sync by re-exporting on every change of a configuration file, an
+  artifact file, or one of its embedded assets (bursts of changes are
+  coalesced). A transiently failing re-export leaves the watch intact.
+  As a re-export has to land somewhere it can be picked up again,
+  `--watch` rejects the `-` standard output. The command then runs
+  until it is interrupted (e.g., via `CTRL+C`).
+
+## EXIT STATUS
+
+Exits with status `0` on success, and with status `1` on any lint
+diagnostic of `error` severity, an invalid output specification, a
+missing browser for `pdf`, an unwritable output file, or `--watch`
+combined with `-`.
+
+## EXAMPLES
+
+```sh
+# export the specification as HTML into its default location
+$ ase spec export
+
+# export the specification as PDF and as JSON in a single run
+$ ase spec export -o spec.pdf -o spec.json
+
+# export the normalized Markdown to standard output
+$ ase spec export -o md:-
+
+# keep an HTML export in sync with the sources
+$ ase spec export -o /tmp/spec.html -w
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-spec`(1), `ase-spec-lint`(1), `ase-spec-preview`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

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

@@ -0,0 +1,57 @@
+# ase-spec-init(1) -- Initialize the Project Specification
+
+## SYNOPSIS
+
+`ase spec init`
+\[`-h`|`--help`\]
+
+## DESCRIPTION
+
+**ase spec init** initializes the *SpecBook*-based specification below
+`project.artifact.spec.basedir` (see `ase-spec`(1)): it creates every
+specification Markdown file which the *SpecBook* schema configuration
+`project.artifact.spec.schema` assigns artifacts onto and which does
+not exist yet, creating the base directory on demand. Each created file
+carries a frontmatter with the `Created` and `Modified` timestamps and
+the level 1 headings of all artifacts assigned onto it, in the order of
+the schema configuration. An already existing file is never touched.
+
+The created files are printed to standard output as a single line
+`initialized artifact file(s): `*file*\[`, `*file*\] \[...\], where each
+*file* is relative to the project root, or as the line `no artifact
+files were created` if all files already exist.
+
+Unlike `specbook init`, no *SpecBook* project configuration file
+`.specbook.yaml` is created, as the base directory and the schema
+configuration are taken from the *ASE* configuration (see
+`ase-config`(1)).
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## EXIT STATUS
+
+Exits with status `0` on success, and with status `1` if the
+initialization failed (e.g., an invalid schema configuration).
+
+## EXAMPLES
+
+```sh
+# initialize the specification
+$ ase spec init
+
+# initialize and then lint the specification
+$ ase spec init && ase spec lint
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-spec`(1), `ase-spec-lint`(1), `ase-spec-export`(1),
+`ase-spec-preview`(1), `ase-config`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>
+