@rse/ase 1.0.7 → 2.0.0

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

@@ -0,0 +1,92 @@
+.TH "ASE-SETUP-TELEMETRY" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-setup-telemetry\fR - Activate or Deactivate the ASE Telemetry Export
+.SH "SYNOPSIS"
+.P
+\fBase setup telemetry\fR \[lB]\fB-h\fR|\fB--help\fR\[rB]
+.P
+\fBase setup telemetry activate\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB]
+.P
+\fBase setup telemetry deactivate\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase setup telemetry\fR activates or deactivates the \fIOpenTelemetry\fR (OTLP/HTTP) export of the agent tool towards the per-user \fIASE\fR OTLP ingress \fBhttp://127.0.0.1:\fR\fIport\fR (with \fIport\fR from the configuration \fBtelemetry.service.port\fR, default \fB44318\fR), which feeds the AI usage accounting of the task assignments (see \fBase-task-assign\fR(1)). Without a sub-command, the usage information is shown and the command exits with status \fB1\fR.
+.P
+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 \fBase service\fR 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 \fB--scope\fR option.
+.P
+Telemetry configured by the user for other receivers is never touched: it is preserved with a warning (and the command still exits with status \fB0\fR), and reported as \fBforeign\fR by \fBase setup status\fR.
+.SH "COMMANDS"
+.RS 0
+.IP \(bu 4
+\fBase setup telemetry activate\fR \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB]: Configure the telemetry export of the agent tool. As the AI usage accounting is opt-in, this requires the configuration \fBtelemetry.enabled\fR to be \fBtrue\fR (e.g., via \fBase config set
+telemetry.enabled true\fR on scope \fBuser\fR or \fBproject\fR), else the command fails with an error. A missing bearer token \fBtelemetry.service.token\fR is generated (48 hexadecimal digits) and persisted on scope \fBuser\fR. Per agent tool:
+.RS 4
+.IP \(bu 4
+\fBclaude\fR: The variables \fBCLAUDE_CODE_ENABLE_TELEMETRY=1\fR, \fBOTEL_LOGS_EXPORTER=otlp\fR, \fBOTEL_EXPORTER_OTLP_PROTOCOL=http/json\fR, \fBOTEL_EXPORTER_OTLP_ENDPOINT=\fR\fIurl\fR, \fBOTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer \fR\fItoken\fR, and \fBOTEL_LOGS_EXPORT_INTERVAL=5000\fR are added to (resp. updated in) the \fBenv\fR object of \fB~/.claude/settings.json\fR.
+.sp
+If any of these variables is already set there, but points neither to the URL nor carries the token of the \fIASE\fR ingress, the configuration is foreign and preserved; a non-object \fBenv\fR is preserved, too.
+.IP \(bu 4
+\fBcodex\fR: A marked block (between the lines \fB# BEGIN ASE telemetry
+(generated)\fR and \fB# END ASE telemetry (generated)\fR) with an \fB\[lB]otel\[rB]\fR table, exporting via \fBotlp-http\fR with protocol \fBjson\fR to \fIurl\fR\fB/v1/logs\fR with the \fBauthorization\fR header \fBBearer\fR \fItoken\fR, is added to (resp. replaced in) \fB$CODEX_HOME/config.toml\fR (default: \fB~/.codex/config.toml\fR). An \fB\[lB]otel\[rB]\fR table outside of the block is foreign and preserved.
+.IP \(bu 4
+\fBcopilot\fR: As \fIGitHub Copilot CLI\fR is configurable via environment variables only, a marked block with a shell function \fBcopilot\fR is added to (resp. replaced in) the shell profile of the login shell of \fB$SHELL\fR (\fB$ZDOTDIR/.zshrc\fR, default \fB~/.zshrc\fR, for \fBzsh\fR, and \fB~/.bashrc\fR for \fBbash\fR), which passes the variables \fBCOPILOT_OTEL_ENABLED=true\fR, \fBCOPILOT_OTEL_EXPORTER_TYPE=otlp-http\fR, \fBOTEL_EXPORTER_OTLP_ENDPOINT=\fR\fIurl\fR, \fBOTEL_EXPORTER_OTLP_PROTOCOL=http/json\fR, and \fBOTEL_EXPORTER_OTLP_HEADERS=Authorization=Bearer \fR\fItoken\fR to the \fBcopilot\fR command only, instead of exporting them to every other program. A new shell session is required for it to take effect.
+.sp
+For any other shell, the command fails with an error showing the shell function to define manually. An \fB$OTEL_EXPORTER_OTLP_ENDPOINT\fR of the environment other than the \fIASE\fR ingress URL, and an assignment of \fBCOPILOT_OTEL_ENABLED\fR or \fBOTEL_EXPORTER_OTLP_ENDPOINT\fR in the profile outside of the block, are foreign and preserved.
+.RE 0
+.IP \(bu 4
+\fBase setup telemetry deactivate\fR \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB]: Remove the telemetry export configured by \fBase setup telemetry
+activate\fR again, preserving any foreign telemetry configuration. It does not require \fBtelemetry.enabled\fR.
+.sp
+Per agent tool: for \fBclaude\fR, the above variables are removed from the \fBenv\fR of \fB~/.claude/settings.json\fR (and the \fBenv\fR itself, if it became empty); for \fBcodex\fR, the marked block is removed from \fB$CODEX_HOME/config.toml\fR; and for \fBcopilot\fR, the marked block is removed from all candidate shell profiles (\fB~/.zshrc\fR, \fB~/.bashrc\fR, and the profile of the login shell). A missing file or configuration is skipped with an informational message.
+.RE 0
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information and exit.
+.IP \(bu 4
+\[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB]: Select the target agent tool: \fBclaude\fR, \fBcopilot\fR, or \fBcodex\fR (default: \fB$ASE_TOOL\fR, else \fBclaude\fR).
+.RE 0
+.SH "ENVIRONMENT"
+.RS 0
+.IP \(bu 4
+\fBASE_TOOL\fR: The default of \fB--tool\fR.
+.IP \(bu 4
+\fBCODEX_HOME\fR: The configuration directory of \fIOpenAI Codex CLI\fR (default: \fB~/.codex\fR).
+.IP \(bu 4
+\fBSHELL\fR, \fBZDOTDIR\fR: The login shell, determining the shell profile for \fB--tool copilot\fR, and the configuration directory of \fBzsh\fR.
+.IP \(bu 4
+\fBOTEL_EXPORTER_OTLP_ENDPOINT\fR: An existing OTLP endpoint for \fB--tool copilot\fR, which, if not the \fIASE\fR ingress, is considered a foreign telemetry configuration.
+.RE 0
+.SH "FILES"
+.RS 0
+.IP \(bu 4
+\fB~/.claude/settings.json\fR: The user-level settings file of \fIAnthropic Claude Code CLI\fR.
+.IP \(bu 4
+\fB$CODEX_HOME/config.toml\fR (default: \fB~/.codex/config.toml\fR): The configuration file of \fIOpenAI Codex CLI\fR.
+.IP \(bu 4
+\fB~/.zshrc\fR, \fB~/.bashrc\fR: The shell profiles receiving the \fBcopilot\fR shell function.
+.RE 0
+.SH "EXIT STATUS"
+.P
+\fB0\fR on success (including a preserved foreign configuration), \fB1\fR on any error (e.g., a disabled AI usage accounting on \fBactivate\fR, an unsupported shell for \fB--tool copilot\fR, an unterminated marked block, and when invoked without a sub-command).
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# 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
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-setup\fR(1), \fBase-setup-status\fR(1), \fBase-config\fR(1), \fBase-service\fR(1), \fBase-task-assign\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

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

@@ -0,0 +1,59 @@
+.TH "ASE-SETUP-UNINSTALL" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-setup-uninstall\fR - Uninstall the ASE Plugin and Tool
+.SH "SYNOPSIS"
+.P
+\fBase setup uninstall\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB] \[lB]\fB-s\fR|\fB--scope\fR \fIscope\fR\[rB] \[lB]\fB-d\fR|\fB--dev\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase setup uninstall\fR uninstalls the \fIASE\fR plugin from the agent tool selected by \fB--tool\fR and the \fIASE\fR tool itself. It requires \fBnpm\fR(1) and the CLI of the agent tool to be found in \fB$PATH\fR. The steps are:
+.RS 0
+.IP 1. 4
+A potentially running \fBase service\fR of the current project is stopped (on a best-effort basis).
+.IP 2. 4
+For \fB--tool claude\fR, the selection of the output style \fBase:ase-terse\fR is removed from the \fBsettings.json\fR of the installation scope, while a foreign \fBoutputStyle\fR is preserved with a warning.
+.IP 3. 4
+The plugin \fBase@ase\fR is uninstalled (\fB<cli> plugin uninstall
+ase@ase\fR, resp. \fBcodex plugin remove ase@ase\fR) and the plugin marketplace \fBase\fR is removed (\fB<cli> plugin marketplace remove
+ase\fR), where an already absent plugin or marketplace is skipped.
+.IP 4. 4
+Unless in development mode (\fB--dev\fR), the tool is uninstalled via \fBnpm uninstall -g @rse/ase\fR (prefixed with \fBsudo\fR(8) if the global \fBnpm\fR installation root is not writable by the current user and \fBsudo\fR is available).
+.RE 0
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information and exit.
+.IP \(bu 4
+\[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB]: Select the target agent tool: \fBclaude\fR, \fBcopilot\fR, or \fBcodex\fR (default: \fB$ASE_TOOL\fR, else \fBclaude\fR).
+.IP \(bu 4
+\[lB]\fB-s\fR|\fB--scope\fR \fIscope\fR\[rB]: Select the plugin installation scope: \fBuser\fR, \fBproject\fR, or \fBlocal\fR. The default is auto-detected from the existing installation: the scopes \fBlocal\fR, \fBproject\fR, and \fBuser\fR are probed in this order, and the first one whose settings file registers the plugin \fBase@ase\fR under \fBenabledPlugins\fR is taken, falling back to \fBuser\fR. Only supported for \fB--tool claude\fR; a non-\fBuser\fR scope for \fBcopilot\fR or \fBcodex\fR fails with an error.
+.IP \(bu 4
+\[lB]\fB-d\fR|\fB--dev\fR\[rB]: Development mode: uninstall the plugin only, but keep the \fIASE\fR tool, as it is the local working copy (default: \fB$ASE_SETUP_DEV\fR).
+.RE 0
+.SH "ENVIRONMENT"
+.RS 0
+.IP \(bu 4
+\fBASE_TOOL\fR: The default of \fB--tool\fR.
+.IP \(bu 4
+\fBASE_SETUP_DEV\fR: The default of \fB--dev\fR: any non-empty value other than \fB0\fR and \fBfalse\fR (case-insensitive) enables it.
+.RE 0
+.SH "EXIT STATUS"
+.P
+\fB0\fR on success, \fB1\fR on any error.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# uninstall ASE from Anthropic Claude Code CLI
+$ ase setup uninstall
+
+# uninstall the plugin from GitHub Copilot CLI
+$ ase setup uninstall --tool copilot
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-setup\fR(1), \fBase-setup-install\fR(1), \fBase-setup-disable\fR(1), \fBnpm\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

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

@@ -0,0 +1,64 @@
+.TH "ASE-SETUP-UPDATE" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-setup-update\fR - Update the ASE Tool and Plugin
+.SH "SYNOPSIS"
+.P
+\fBase setup update\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB] \[lB]\fB-s\fR|\fB--scope\fR \fIscope\fR\[rB] \[lB]\fB-f\fR|\fB--force\fR\[rB] \[lB]\fB-d\fR|\fB--dev\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase setup update\fR updates the \fIASE\fR tool and the \fIASE\fR plugin of the agent tool selected by \fB--tool\fR to their latest versions. It requires \fBnpm\fR(1) and the CLI of the agent tool to be found in \fB$PATH\fR. First, a potentially running \fBase service\fR of the current project is stopped (on a best-effort basis), as it would otherwise keep running the old code.
+.P
+In the regular mode, the current version of the tool is compared with the latest version of \fB@rse/ase\fR 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 \fIASE\fR is already at the latest version and exits without any further action (unless \fB--force\fR is given).
+.P
+Otherwise, the tool is updated via \fBnpm update -g @rse/ase\fR (prefixed with \fBsudo\fR(8) if the global \fBnpm\fR installation root is not writable by the current user and \fBsudo\fR is available), the plugin marketplace snapshot is refreshed (\fB<cli> plugin marketplace update ase\fR, resp. \fBcodex plugin marketplace upgrade ase\fR), and the plugin is updated (\fB<cli> plugin update ase@ase\fR, resp. removed and re-added for \fIOpenAI Codex CLI\fR, which has no plugin update command).
+.P
+In the development mode (\fB--dev\fR), the local \fIASE\fR working copy is re-built instead (\fBnpm install\fR and \fBnpm start build\fR in its \fBtool/\fR 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.
+.P
+Like \fBase setup install\fR, for \fB--tool claude\fR, the output style \fBase:ase-terse\fR is finally selected in the \fBsettings.json\fR of the installation scope, unless a foreign \fBoutputStyle\fR is already selected there, which is preserved with a warning.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information and exit.
+.IP \(bu 4
+\[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB]: Select the target agent tool: \fBclaude\fR, \fBcopilot\fR, or \fBcodex\fR (default: \fB$ASE_TOOL\fR, else \fBclaude\fR).
+.IP \(bu 4
+\[lB]\fB-s\fR|\fB--scope\fR \fIscope\fR\[rB]: Select the plugin installation scope: \fBuser\fR, \fBproject\fR, or \fBlocal\fR. The default is auto-detected from the existing installation: the scopes \fBlocal\fR, \fBproject\fR, and \fBuser\fR are probed in this order (strongest first), and the first one whose settings file registers the plugin \fBase@ase\fR under \fBenabledPlugins\fR (enabled or disabled) is taken, falling back to \fBuser\fR when no installation is found.
+.sp
+For tools other than \fBclaude\fR, the scope is always \fBuser\fR, and an explicitly given non-\fBuser\fR scope fails with an error.
+.IP \(bu 4
+\[lB]\fB-f\fR|\fB--force\fR\[rB]: Always perform the update, even if the tool is already at the latest version (default: off). Without effect in combination with \fB--dev\fR, which always re-builds.
+.IP \(bu 4
+\[lB]\fB-d\fR|\fB--dev\fR\[rB]: Development mode: re-build the local \fIASE\fR working copy (\fB$ASE_SETUP_DEV_BASEDIR\fR, else the parent directory of the \fB@rse/ase\fR package directory) and re-install the plugin from it, instead of updating from the NPM registry (default: \fB$ASE_SETUP_DEV\fR).
+.RE 0
+.SH "ENVIRONMENT"
+.RS 0
+.IP \(bu 4
+\fBASE_TOOL\fR: The default of \fB--tool\fR.
+.IP \(bu 4
+\fBASE_SETUP_DEV\fR: The default of \fB--dev\fR: any non-empty value other than \fB0\fR and \fBfalse\fR (case-insensitive) enables it.
+.IP \(bu 4
+\fBASE_SETUP_DEV_BASEDIR\fR: The local \fIASE\fR working copy used with \fB--dev\fR.
+.RE 0
+.SH "EXIT STATUS"
+.P
+\fB0\fR on success (including an already current version), \fB1\fR on any error.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# 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
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-setup\fR(1), \fBase-setup-install\fR(1), \fBase-setup-uninstall\fR(1), \fBase-service\fR(1), \fBnpm\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

package/dst/man/ase-setup.1

@@ -0,0 +1,93 @@
+.TH "ASE-SETUP" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-setup\fR - Install, Update, and Uninstall the ASE Tool and Plugin
+.SH "SYNOPSIS"
+.P
+\fBase setup\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \fIcommand\fR \[lB]\fIoptions\fR \[lB]...\[rB]\[rB] \[lB]\fIargs\fR \[lB]...\[rB]\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase setup\fR is the entry point group for installing, updating, uninstalling, enabling, disabling, and reporting the \fIASE\fR tool and its companion agent tool plugin, and for activating or deactivating the pre-defined foreign MCP servers, the \fIASE\fR statusline, and the \fIASE\fR telemetry export towards the AI usage accounting. Without a \fIcommand\fR, the usage information is shown and the command exits with status \fB1\fR.
+.P
+The target agent tool is either \fIAnthropic Claude Code CLI\fR (\fBclaude\fR), \fIGitHub Copilot CLI\fR (\fBcopilot\fR), or \fIOpenAI Codex CLI\fR (\fBcodex\fR). All operations are performed through the plugin and MCP commands of the respective agent tool CLI (e.g., \fBclaude plugin
+install\fR), which hence has to be found in \fB$PATH\fR, 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.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information of the command group and exit.
+.RE 0
+.P
+The following options are shared by most sub-commands (see their individual manual pages for the exact applicability):
+.RS 0
+.IP \(bu 4
+\[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB]: Select the target agent tool: \fBclaude\fR (\fIAnthropic Claude Code CLI\fR), \fBcopilot\fR (\fIGitHub Copilot CLI\fR), or \fBcodex\fR (\fIOpenAI Codex CLI\fR). The default is the value of the environment variable \fBASE_TOOL\fR, if set and non-empty, else \fBclaude\fR. An invalid value is rejected with an error. Accepted by all sub-commands except \fBase
+setup mcp list\fR.
+.IP \(bu 4
+\[lB]\fB-s\fR|\fB--scope\fR \fIscope\fR\[rB]: Select the installation scope of the plugin, MCP server, or statusline registration: \fBuser\fR (registered globally for the current user), \fBproject\fR (registered in the project and meant to be shared via version control), or \fBlocal\fR (registered in the project, but kept out of version control).
+.sp
+Only supported for \fB--tool claude\fR (and, for the statusline, a \fBuser\fR scope for \fB--tool copilot\fR); a non-\fBuser\fR scope for any other tool fails with an error, as those agent tools have no scope concept. Not accepted by \fBase setup status\fR (which reports all scopes at once) and \fBase setup telemetry\fR (which is always user-level).
+.RE 0
+.SH "COMMANDS"
+.RS 0
+.IP \(bu 4
+\fBase setup install\fR \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB] \[lB]\fB-s\fR|\fB--scope\fR \fIscope\fR\[rB] \[lB]\fB-d\fR|\fB--dev\fR\[rB]: Install the \fIASE\fR plugin into the agent tool. See \fBase-setup-install\fR(1).
+.IP \(bu 4
+\fBase setup update\fR \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB] \[lB]\fB-s\fR|\fB--scope\fR \fIscope\fR\[rB] \[lB]\fB-f\fR|\fB--force\fR\[rB] \[lB]\fB-d\fR|\fB--dev\fR\[rB]: Update the \fIASE\fR tool and the \fIASE\fR plugin to their latest versions. See \fBase-setup-update\fR(1).
+.IP \(bu 4
+\fBase setup uninstall\fR \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB] \[lB]\fB-s\fR|\fB--scope\fR \fIscope\fR\[rB] \[lB]\fB-d\fR|\fB--dev\fR\[rB]: Uninstall the \fIASE\fR plugin and the \fIASE\fR tool. See \fBase-setup-uninstall\fR(1).
+.IP \(bu 4
+\fBase setup enable\fR \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB] \[lB]\fB-s\fR|\fB--scope\fR \fIscope\fR\[rB]: Enable the already installed \fIASE\fR plugin. See \fBase-setup-enable\fR(1).
+.IP \(bu 4
+\fBase setup disable\fR \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB] \[lB]\fB-s\fR|\fB--scope\fR \fIscope\fR\[rB]: Disable the \fIASE\fR plugin without uninstalling it. See \fBase-setup-disable\fR(1).
+.IP \(bu 4
+\fBase setup status\fR \[lB]\fB-t\fR|\fB--tool\fR \fItool\fR\[rB]: Report the plugin, MCP server, output style, statusline, and telemetry registrations of all scopes. See \fBase-setup-status\fR(1).
+.IP \(bu 4
+\fBase setup mcp\fR \fBlist\fR|\fBactivate\fR|\fBdeactivate\fR \[lB]...\[rB]: List, activate, or deactivate the pre-defined foreign MCP servers. See \fBase-setup-mcp\fR(1).
+.IP \(bu 4
+\fBase setup statusline\fR \fBactivate\fR|\fBdeactivate\fR \[lB]...\[rB]: Activate or deactivate the \fIASE\fR statusline. See \fBase-setup-statusline\fR(1).
+.IP \(bu 4
+\fBase setup telemetry\fR \fBactivate\fR|\fBdeactivate\fR \[lB]...\[rB]: Activate or deactivate the \fIOpenTelemetry\fR export of the agent tool towards the \fIASE\fR OTLP ingress. See \fBase-setup-telemetry\fR(1).
+.RE 0
+.SH "ENVIRONMENT"
+.RS 0
+.IP \(bu 4
+\fBASE_TOOL\fR: The default of the \fB--tool\fR option (default: \fBclaude\fR).
+.IP \(bu 4
+\fBASE_SETUP_DEV\fR: The default of the \fB--dev\fR option of \fBase setup install\fR, \fBase setup
+update\fR, and \fBase setup uninstall\fR: any non-empty value other than \fB0\fR and \fBfalse\fR (case-insensitive) enables it.
+.IP \(bu 4
+\fBASE_SETUP_DEV_BASEDIR\fR: The base directory of the local \fIASE\fR working copy used with \fB--dev\fR (default: the parent directory of the installed \fB@rse/ase\fR package directory).
+.IP \(bu 4
+\fBASE_MCP_KEY_\fR\fIKEY\fR: The API keys of the pre-defined MCP servers (see \fBase-setup-mcp\fR(1)).
+.RE 0
+.SH "FILES"
+.RS 0
+.IP \(bu 4
+\fB~/.claude/settings.json\fR, \fB.claude/settings.json\fR, \fB.claude/settings.local.json\fR: The settings files of \fIAnthropic Claude Code CLI\fR of the scopes \fBuser\fR, \fBproject\fR, and \fBlocal\fR (the latter two relative to the current working directory).
+.IP \(bu 4
+\fB$COPILOT_HOME/settings.json\fR (default: \fB~/.copilot/settings.json\fR): The single per-user settings file of \fIGitHub Copilot CLI\fR.
+.IP \(bu 4
+\fB$CODEX_HOME/config.toml\fR (default: \fB~/.codex/config.toml\fR): The per-user configuration file of \fIOpenAI Codex CLI\fR.
+.RE 0
+.SH "EXIT STATUS"
+.P
+\fB0\fR on success, \fB1\fR on any error, and \fB1\fR when invoked without a \fIcommand\fR.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# 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
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-setup-install\fR(1), \fBase-setup-update\fR(1), \fBase-setup-uninstall\fR(1), \fBase-setup-enable\fR(1), \fBase-setup-disable\fR(1), \fBase-setup-status\fR(1), \fBase-setup-mcp\fR(1), \fBase-setup-statusline\fR(1), \fBase-setup-telemetry\fR(1), \fBclaude\fR(1), \fBcopilot\fR(1), \fBcodex\fR(1), \fBnpm\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

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

@@ -0,0 +1,62 @@
+.TH "ASE-SPEC-EXPORT" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-spec-export\fR - Export the Project Specification
+.SH "SYNOPSIS"
+.P
+\fBase spec export\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-o\fR|\fB--output\fR \[lB]\fIformat\fR\fB:\fR\[rB]\fIfile\fR\[rB] \[lB]...\[rB] \[lB]\fB-w\fR|\fB--watch\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase spec export\fR exports the \fISpecBook\fR-based specification Markdown files below \fBproject.artifact.spec.basedir\fR (see \fBase-spec\fR(1)) into one or more output files. The supported formats are:
+.RS 0
+.IP \(bu 4
+\fBjson\fR, \fBjson5\fR, \fByaml\fR, \fBtoon\fR: The specification object model in the respective serialization.
+.IP \(bu 4
+\fBhtml\fR: A self-contained single HTML document.
+.IP \(bu 4
+\fBpdf\fR: A paginated print document.
+.IP \(bu 4
+\fBmd\fR: A normalized single Markdown document.
+.RE 0
+.P
+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 \fBinfo\fR level. The export fails on any lint diagnostic of \fBerror\fR severity (see \fBase-spec-lint\fR(1)), while warnings are only logged, so a partial or invalid specification is never emitted.
+.P
+The \fBpdf\fR format additionally requires a Chromium-class browser, which neither \fBnpm install -g @rse/ase\fR nor \fBase setup install\fR provides: unless a \fIGoogle Chrome\fR is installed system-wide, fetch the \fIPlaywright\fR Chromium once via \fBnpx playwright install chromium\fR. Without any such browser, the export fails before the specification is even parsed and reports that very command.
+.P
+The MCP tool \fBase_specbook_export\fR provides the same to the skills.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information and exit.
+.IP \(bu 4
+\[lB]\fB-o\fR|\fB--output\fR \[lB]\fIformat\fR\fB:\fR\[rB]\fIfile\fR\[rB]: Write the export into \fIfile\fR, or to standard output for \fB-\fR. The option is repeatable, so multiple outputs (of the same or different formats) are written in a single run. The \fIformat\fR is inferred from the filename extension (\fBjson\fR, \fBjson5\fR, \fByaml\fR or \fByml\fR, \fBtoon\fR, \fBhtml\fR or \fBhtm\fR, \fBpdf\fR, and \fBmd\fR or \fBmarkdown\fR, case-insensitive) unless explicitly given as a prefix of at least two characters (out of the same names), where a plain \fB-\fR defaults to \fBjson\fR.
+.sp
+The log is written to standard error (see \fBase\fR(1)), so it never mixes into the export on standard output. An unknown format prefix and a not inferable format are errors. A relative \fIfile\fR is relative to the current working directory. Default: the HTML rendering into \fBindex.html\fR inside the specification base directory (e.g., \fBdocs/specbook/index.html\fR).
+.IP \(bu 4
+\[lB]\fB-w\fR|\fB--watch\fR\[rB]: 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, \fB--watch\fR rejects the \fB-\fR standard output. The command then runs until it is interrupted (e.g., via \fBCTRL+C\fR).
+.RE 0
+.SH "EXIT STATUS"
+.P
+Exits with status \fB0\fR on success, and with status \fB1\fR on any lint diagnostic of \fBerror\fR severity, an invalid output specification, a missing browser for \fBpdf\fR, an unwritable output file, or \fB--watch\fR combined with \fB-\fR.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# 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
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-spec\fR(1), \fBase-spec-lint\fR(1), \fBase-spec-preview\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

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

@@ -0,0 +1,40 @@
+.TH "ASE-SPEC-LINT" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-spec-lint\fR - Lint the Project Specification
+.SH "SYNOPSIS"
+.P
+\fBase spec lint\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-v\fR|\fB--verbose\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase spec lint\fR lints the \fISpecBook\fR-based specification Markdown files below \fBproject.artifact.spec.basedir\fR against the \fISpecBook\fR schema configuration \fBproject.artifact.spec.schema\fR (see \fBase-spec\fR(1)).
+.P
+Every diagnostic is printed to standard output as a single line \fIfile\fR\fB:\fR\fIline\fR\fB:\fR\fIcolumn\fR\fB: \fR\fImessage\fR, where \fIfile\fR is relative to the project root (a file outside the project, like the bundled standard schema, is kept as-is), and \fImessage\fR is prefixed with \fBwarning: \fR for a diagnostic of \fBwarning\fR severity. Without any diagnostic, nothing is printed.
+.P
+The MCP tool \fBase_specbook_lint\fR provides the same to the skills.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information and exit.
+.IP \(bu 4
+\[lB]\fB-v\fR|\fB--verbose\fR\[rB]: Print each diagnostic as a multi-line message with the affected source snippet (with an \fBERROR\fR resp. \fBWARNING\fR type), colorized if standard output is a terminal. If the source file is unreadable or empty, the single-line message is printed instead.
+.RE 0
+.SH "EXIT STATUS"
+.P
+Exits with status \fB0\fR if there is no diagnostic of \fBerror\fR severity (warnings alone do not fail), and with status \fB1\fR if there is any diagnostic of \fBerror\fR severity or the linting itself failed (e.g., an unreadable schema configuration).
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# lint the specification
+$ ase spec lint
+
+# lint the specification, showing the affected source snippets
+$ ase spec lint -v
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-spec\fR(1), \fBase-spec-export\fR(1), \fBase-spec-preview\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

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

@@ -0,0 +1,40 @@
+.TH "ASE-SPEC-PREVIEW" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-spec-preview\fR - Serve a Live Preview of the Project Specification
+.SH "SYNOPSIS"
+.P
+\fBase spec preview\fR \[lB]\fB-h\fR|\fB--help\fR\[rB] \[lB]\fB-a\fR|\fB--addr\fR \fIip-addr\fR\[rB] \[lB]\fB-p\fR|\fB--port\fR \fItcp-port\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase spec preview\fR serves the HTML export of the \fISpecBook\fR-based specification Markdown files below \fBproject.artifact.spec.basedir\fR (see \fBase-spec\fR(1)) as a live preview on \fBhttp://\fR\fIip-addr\fR\fB:\fR\fItcp-port\fR\fB/\fR (default: \fBhttp://127.0.0.1:12345/\fR). The export is kept in sync with its sources exactly like under \fBase spec export --watch\fR (see \fBase-spec-export\fR(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.
+.P
+The command does not terminate on its own, but runs until it is interrupted (e.g., via \fBCTRL+C\fR).
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information and exit.
+.IP \(bu 4
+\[lB]\fB-a\fR|\fB--addr\fR \fIip-addr\fR\[rB]: The IP address to listen on (default: \fB127.0.0.1\fR).
+.IP \(bu 4
+\[lB]\fB-p\fR|\fB--port\fR \fItcp-port\fR\[rB]: The TCP port to listen on, an integer in the range \fB1\fR..\fB65535\fR (default: \fB12345\fR).
+.RE 0
+.SH "EXIT STATUS"
+.P
+Runs until interrupted. Exits with status \fB1\fR on an invalid TCP port or if the server cannot be started.
+.SH "EXAMPLES"
+.P
+.RS 2
+.nf
+# 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
+.fi
+.RE
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-spec\fR(1), \fBase-spec-export\fR(1), \fBase-spec-lint\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR

package/dst/man/ase-spec.1

@@ -0,0 +1,46 @@
+.TH "ASE-SPEC" "1" "October 2026" "2.0.0" "Agentic Software Engineering (ASE)"
+.SH "NAME"
+\fBase-spec\fR - Lint, Export, and Preview the Project Specification
+.SH "SYNOPSIS"
+.P
+\fBase spec\fR \[lB]\fB-h\fR|\fB--help\fR\[rB]
+.P
+\fBase spec lint\fR \[lB]\fB-v\fR|\fB--verbose\fR\[rB]
+.P
+\fBase spec export\fR \[lB]\fB-o\fR|\fB--output\fR \[lB]\fIformat\fR\fB:\fR\[rB]\fIfile\fR\[rB] \[lB]...\[rB] \[lB]\fB-w\fR|\fB--watch\fR\[rB]
+.P
+\fBase spec preview\fR \[lB]\fB-a\fR|\fB--addr\fR \fIip-addr\fR\[rB] \[lB]\fB-p\fR|\fB--port\fR \fItcp-port\fR\[rB]
+.SH "DESCRIPTION"
+.P
+\fBase spec\fR is the entry point group for linting, exporting, and previewing the \fISpecBook\fR-based project specification (SPEC), i.e., the Markdown files (plus their embedded assets) of the artifact kind \fBspec\fR below the base directory \fBproject.artifact.spec.basedir\fR (default: \fBdocs/specbook\fR, relative to the project root).
+.P
+The specification is governed by the \fISpecBook\fR YAML schema configuration \fBproject.artifact.spec.schema\fR: a whitespace-separated list of schema files, merged in the given order, where the entry \fBstd\fR names the standard schema \fBase-format-specbook.yaml\fR bundled with the plugin (see \fBase-util-meta\fR(1)) and every other entry is a file path relative to the project root. An unset or empty value means \fBstd\fR.
+.P
+All specification commands honor the Git exclude rules exactly like \fBase artifact list\fR does (see \fBase-artifact\fR(1)): an artifact file Git excludes from the project counts as an \fIabsent\fR one, so both resolvers always see the very same specification.
+.P
+The \fISpecBook\fR processing information is logged at the \fBinfo\fR level and its tracing details at the \fBdebug\fR level (see the global option \fB--log-level\fR of \fBase\fR(1)).
+.P
+Without a sub-command, the usage information is shown and the command exits with status \fB1\fR.
+.SH "OPTIONS"
+.RS 0
+.IP \(bu 4
+\[lB]\fB-h\fR|\fB--help\fR\[rB]: Show usage information and exit.
+.RE 0
+.SH "COMMANDS"
+.RS 0
+.IP \(bu 4
+\fBase spec lint\fR \[lB]\fB-v\fR|\fB--verbose\fR\[rB]: Lint the specification against the schema configuration. See \fBase-spec-lint\fR(1).
+.IP \(bu 4
+\fBase spec export\fR \[lB]\fB-o\fR|\fB--output\fR \[lB]\fIformat\fR\fB:\fR\[rB]\fIfile\fR\[rB] \[lB]...\[rB] \[lB]\fB-w\fR|\fB--watch\fR\[rB]: Export the specification as JSON, JSON5, YAML, TOON, HTML, PDF, or normalized Markdown. See \fBase-spec-export\fR(1).
+.IP \(bu 4
+\fBase spec preview\fR \[lB]\fB-a\fR|\fB--addr\fR \fIip-addr\fR\[rB] \[lB]\fB-p\fR|\fB--port\fR \fItcp-port\fR\[rB]: Serve the HTML export of the specification as a live preview. See \fBase-spec-preview\fR(1).
+.RE 0
+.SH "EXIT STATUS"
+.P
+The group command without a sub-command exits with status \fB1\fR.
+.SH "SEE ALSO"
+.P
+\fBase\fR(1), \fBase-spec-lint\fR(1), \fBase-spec-export\fR(1), \fBase-spec-preview\fR(1), \fBase-artifact\fR(1), \fBase-config\fR(1).
+.SH "AUTHOR"
+.P
+Dr. Ralf S. Engelschall \fI\(larse@engelschall.com\(ra\fR