@rse/ase 2.0.3 → 2.0.4

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

@@ -0,0 +1,116 @@
+# ase-setup-install(1) -- Install the ASE Plugin into an Agent Tool
+
+## SYNOPSIS
+
+`ase setup install`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+\[`-s`|`--scope` *scope*\]
+\[`-d`|`--dev`\]
+
+## DESCRIPTION
+
+**ase setup install** installs the *ASE* plugin into the agent tool
+selected by `--tool`. It requires `npm`(1) and the CLI of the agent
+tool (`claude`, `copilot`, or `codex`) to be found in `$PATH`.
+
+The installation is performed in two steps through the plugin
+commands of the agent tool CLI: first, the *ASE* plugin marketplace is
+registered from a local directory (`<cli> plugin marketplace add`
+*dir*), and then the plugin `ase@ase` is installed from it (`<cli>
+plugin install ase@ase`, resp. `codex plugin add ase@ase` for *OpenAI
+Codex CLI*), retried up to three times with a delay of one second.
+
+The marketplace directory is the installed `@rse/ase` package
+itself, which bundles the plugin, or, with `--dev`, the local *ASE*
+working copy.
+
+For `--tool claude`, the plugin-shipped output style `ase:ase-terse`
+is additionally selected by writing `"outputStyle": "ase:ase-terse"`
+into the `settings.json` of the installation scope, unless an
+`outputStyle` is already selected there: an *ASE* one is left as is,
+and a foreign one is preserved with a warning. For `--tool copilot`
+and `--tool codex`, which have no output style concept, the `ase hook
+session-start` handler injects the identical style instructions into
+the session context instead (see `ase-hook`(1)).
+
+The *ASE* tool itself is not installed by this command, as it is
+already installed when running it (e.g., via `npm install -g
+@rse/ase`).
+
+## 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` (default; registered
+  globally for the current user in `~/.claude/settings.json`),
+  `project` (registered in `.claude/settings.json` of the current
+  project, meant to be shared via version control), or `local`
+  (registered in `.claude/settings.local.json` of the current
+  project, kept out of version control).
+
+  A non-`user` scope is passed as `--scope` *scope* to the agent tool
+  CLI. Only supported for `--tool claude`; a non-`user` scope for
+  `copilot` or `codex` fails with an error.
+
+- \[`-d`|`--dev`\]:
+  Development mode: register the plugin marketplace from the local
+  *ASE* working copy (`$ASE_SETUP_DEV_BASEDIR`, else the parent
+  directory of the `@rse/ase` package directory) instead of the
+  bundled plugin of the installed package (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`.
+
+## FILES
+
+- `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`:
+  The settings file of the `user`, `project`, resp. `local` scope,
+  receiving the `outputStyle` selection for `--tool claude`.
+
+## EXIT STATUS
+
+`0` on success, `1` on any error (e.g., a missing `npm` or agent tool
+CLI, an invalid option value, or a failing agent tool command, whose
+output is then shown).
+
+## EXAMPLES
+
+```sh
+# install for Anthropic Claude Code CLI, globally for the current user
+$ ase setup install
+
+# install for Anthropic Claude Code CLI, for the current project only
+$ ase setup install --scope project
+
+# install for GitHub Copilot CLI
+$ ase setup install --tool copilot
+
+# install from the local working copy
+$ ase setup install --dev
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-setup`(1), `ase-setup-update`(1),
+`ase-setup-uninstall`(1), `ase-setup-status`(1), `ase-hook`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

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

@@ -0,0 +1,213 @@
+# ase-setup-mcp(1) -- Manage the Pre-Defined Foreign MCP Servers
+
+## SYNOPSIS
+
+`ase setup mcp`
+\[`-h`|`--help`\]
+
+`ase setup mcp list`
+\[`-h`|`--help`\]
+
+`ase setup mcp activate`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+\[`-s`|`--scope` *scope*\]
+\[*servers*\]
+
+`ase setup mcp deactivate`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+\[`-s`|`--scope` *scope*\]
+\[*servers*\]
+
+## DESCRIPTION
+
+**ase setup mcp** manages the pre-defined *foreign MCP servers* which
+*ASE* skills can *optionally* leverage for improved quality: the
+*chat* servers (leveraged by the skills `ase-meta-chat` and
+`ase-meta-quorum`) and the *search* servers (leveraged by the skills
+`ase-meta-search`, `ase-meta-evaluate`, and `ase-arch-discover`).
+Without a sub-command, the usage information is shown and the command
+exits with status `1`.
+
+The currently pre-defined servers are (by their *id*, followed by the
+registered MCP server name):
+
+- `openai-chatgpt` (`chat-openai-chatgpt`):
+  *OpenAI ChatGPT*, key `ASE_MCP_KEY_OPENAI_CHATGPT` or
+  `ASE_MCP_KEY_OPENROUTER`.
+
+- `google-gemini` (`chat-google-gemini`):
+  *Google Gemini*, key `ASE_MCP_KEY_GOOGLE_GEMINI` or
+  `ASE_MCP_KEY_OPENROUTER`.
+
+- `deepseek` (`chat-deepseek`):
+  *DeepSeek*, key `ASE_MCP_KEY_DEEPSEEK` or `ASE_MCP_KEY_OPENROUTER`.
+
+- `xai-grok` (`chat-xai-grok`):
+  *xAI Grok*, key `ASE_MCP_KEY_XAI_GROK` or `ASE_MCP_KEY_OPENROUTER`.
+
+- `alibaba-qwen` (`chat-alibaba-qwen`):
+  *Alibaba Qwen*, key `ASE_MCP_KEY_ALIBABA_QWEN` or
+  `ASE_MCP_KEY_OPENROUTER`.
+
+- `zai-glm` (`chat-zai-glm`):
+  *Z.AI GLM*, key `ASE_MCP_KEY_ZAI_GLM` or `ASE_MCP_KEY_OPENROUTER`.
+
+- `anthropic-claude` (`chat-anthropic-claude`):
+  *Anthropic Claude* via the locally installed *Anthropic Claude Code
+  CLI*, variable `ASE_MCP_KEY_ANTHROPIC_CLAUDE`.
+
+- `openai-codex` (`chat-openai-codex`):
+  *OpenAI Codex* via the locally installed *OpenAI Codex CLI*,
+  variable `ASE_MCP_KEY_OPENAI_CODEX`.
+
+- `github-copilot` (`chat-github-copilot`):
+  *GitHub Copilot* via the locally installed *GitHub Copilot CLI*,
+  variable `ASE_MCP_KEY_GITHUB_COPILOT`.
+
+- `brave` (`search-brave`):
+  *Brave* search, key `ASE_MCP_KEY_BRAVE`.
+
+- `perplexity` (`search-perplexity`):
+  *Perplexity* search, key `ASE_MCP_KEY_PERPLEXITY`.
+
+- `exa` (`search-exa`):
+  *Exa* search, key `ASE_MCP_KEY_EXA`.
+
+The API-based *chat* servers are registered as stdio servers running
+`npx -y mcp-to-openai`, which bridges to the OpenAI-compatible API of
+the LLM vendor, or, with the key `ASE_MCP_KEY_OPENROUTER` of an
+*OpenRouter* account as a common alternative, to the *OpenRouter*
+proxy API.
+
+The harness-based *chat* servers (`anthropic-claude`, `openai-codex`,
+and `github-copilot`) are registered as stdio servers running
+`npx -y mcp-to-harness`, which bridges to the locally installed agent
+tool CLI, authenticating via its own configured credentials: their
+variable carries no API key at all, but the model identifier of the
+harness, with the special value `default` selecting the default model
+of the harness.
+
+The *search* servers are registered as stdio servers running
+`npx -y @brave/brave-search-mcp-server` resp.
+`npx -y @perplexity-ai/mcp-server`, resp. as an HTTP server on
+`https://mcp.exa.ai/mcp` for `exa`.
+
+## COMMANDS
+
+- `ase setup mcp list`:
+  List all pre-defined MCP servers known to *ASE*, rendered as a
+  table with the columns `ID` (the server id), `NAME` (the service
+  name), `VERS` (the pinned model version, or `latest`), `MCP` (the
+  registered MCP server name), `KEY` (the accepted suffixes *KEY* of
+  the environment variables `ASE_MCP_KEY_`*KEY*, in order of
+  preference), and `SKILLS` (the *ASE* skills leveraging the server).
+
+  It accepts no options besides `-h`|`--help` and does not require any
+  agent tool.
+
+- `ase setup mcp activate` \[`-t`|`--tool` *tool*\] \[`-s`|`--scope` *scope*\] \[*servers*\]:
+  Register one or more pre-defined MCP servers with the agent tool
+  (via `<cli> mcp add`). The environment variables `ASE_MCP_KEY_`*KEY*
+  are first additionally sourced from a `.env` file in the current
+  directory (if existing). Each selected server takes its key from the
+  first of its variables (see `KEY` of `ase setup mcp list`) which is
+  set and non-empty.
+
+  A server none of whose variables is set is silently skipped when it
+  was selected implicitly (via an empty *servers* or `all`), but causes
+  a hard error when it was given explicitly. A prior registration of
+  the same server is removed first, so it is re-created cleanly.
+
+- `ase setup mcp deactivate` \[`-t`|`--tool` *tool*\] \[`-s`|`--scope` *scope*\] \[*servers*\]:
+  Unregister one or more pre-defined MCP servers from the agent tool
+  (via `<cli> mcp remove`). A server which is not currently
+  registered is skipped. No API keys are required.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-t`|`--tool` *tool*\] (`activate` and `deactivate` only):
+  Select the target agent tool: `claude`, `copilot`, or `codex`
+  (default: `$ASE_TOOL`, else `claude`). Its CLI has to be found in
+  `$PATH`.
+
+- \[`-s`|`--scope` *scope*\] (`activate` and `deactivate` only):
+  Select the MCP server registration scope: `user` (default;
+  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).
+
+  The scope is always passed explicitly to *Anthropic Claude Code CLI*,
+  as it would otherwise default to `local`. Only supported for
+  `--tool claude`; a non-`user` scope for `copilot` or `codex` fails
+  with an error.
+
+## ARGUMENTS
+
+- \[*servers*\] (`activate` and `deactivate` only):
+  A comma-separated list of server ids (see above). When omitted,
+  empty, or given as the literal `all`, every pre-defined server is
+  selected. An unknown server id fails with an error listing all
+  known ids.
+
+## ENVIRONMENT
+
+- `ASE_MCP_KEY_`*KEY*:
+  The API key (resp., for the harness-based servers, the harness model
+  identifier or `default`) of the pre-defined MCP servers, where *KEY*
+  is one of the suffixes shown in the `KEY` column of `ase setup mcp
+  list`, e.g., `ASE_MCP_KEY_OPENAI_CHATGPT` for `openai-chatgpt`. The
+  key is passed to the registered server (e.g., as its environment
+  variable `OPENAI_KEY`, `BRAVE_API_KEY`, or `PERPLEXITY_API_KEY`) and
+  masked in the logged commands.
+
+- `ASE_MCP_KEY_OPENROUTER`:
+  The *OpenRouter* API key, accepted by all API-based *chat* servers
+  as an alternative to the native API key of the LLM vendor.
+
+- `ASE_TOOL`:
+  The default of `--tool`.
+
+## FILES
+
+- `.env`:
+  An optional file in the current directory, from which the
+  `ASE_MCP_KEY_`*KEY* variables are additionally sourced on `ase setup
+  mcp activate`.
+
+## EXIT STATUS
+
+`0` on success, `1` on any error (and when invoked without a
+sub-command).
+
+## EXAMPLES
+
+```sh
+# list all pre-defined MCP servers
+$ ase setup mcp list
+
+# activate all servers whose keys are available
+$ ase setup mcp activate
+
+# activate two search servers for the current project only
+$ ASE_MCP_KEY_BRAVE=... ASE_MCP_KEY_EXA=... \
+  ase setup mcp activate --scope project brave,exa
+
+# activate the harness-based Anthropic Claude server with its default model
+$ ASE_MCP_KEY_ANTHROPIC_CLAUDE=default ase setup mcp activate anthropic-claude
+
+# deactivate all servers in GitHub Copilot CLI
+$ ase setup mcp deactivate --tool copilot all
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-setup`(1), `ase-setup-status`(1), `npx`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

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

@@ -0,0 +1,101 @@
+# ase-setup-status(1) -- Report the ASE Registrations of an Agent Tool
+
+## SYNOPSIS
+
+`ase setup status`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+
+## DESCRIPTION
+
+**ase setup status** reports where *ASE* is currently registered with
+the agent tool selected by `--tool`, rendered as a table with the
+columns `KIND`, `ID`, `SCOPE`, and `STATUS`. It requires the CLI of
+the agent tool to be found in `$PATH`. The rows are:
+
+- `PLUGIN`:
+  One row per registration of the plugin `ase@ase` (as scraped from
+  the output of `<cli> plugin list`), with its registration scope and
+  its state (e.g., `enabled` or `disabled` for *Anthropic Claude Code
+  CLI*, `installed` for *GitHub Copilot CLI*, and the installation
+  status of *OpenAI Codex CLI*), or a single row with the status `not
+  installed`.
+
+- `MCP`:
+  One row per *currently registered* server of the pre-defined MCP
+  servers (see `ase-setup-mcp`(1)), with its MCP server name and its
+  registration scope (as reported by `<cli> mcp get`), and the status
+  `registered`. Unregistered servers are omitted entirely.
+
+- `OUTPUTSTYLE` (`--tool claude` only):
+  One row per settings file (of the scopes `user`, `project`, and
+  `local`) carrying an `outputStyle` entry, with the status `selected`
+  (the *ASE* output style `ase:ase-terse`) or `foreign`
+  (hand-selected).
+
+- `STATUSLINE` (`--tool claude` and `--tool copilot` only):
+  One row per settings file carrying a `statusLine` entry, with the
+  status `activated` (its command starts with `ase statusline`, i.e.,
+  it is owned by *ASE*) or `foreign` (hand-crafted).
+
+- `TELEMETRY`:
+  One row per configuration file carrying a telemetry export, with the
+  status `activated` (towards the *ASE* OTLP ingress) or `foreign`:
+  for `claude`, the `env` of `~/.claude/settings.json`; for `codex`,
+  `$CODEX_HOME/config.toml`; for `copilot`, the shell profiles
+  `~/.zshrc` and `~/.bashrc` (plus the profile of the login shell), and
+  an `$OTEL_EXPORTER_OTLP_ENDPOINT` of the environment not pointing to
+  the *ASE* ingress.
+
+Files below the home directory are shown abbreviated with `~`, and an
+unparsable settings file is silently skipped. The command is purely
+read-only and always exits with status `0`, so a missing registration
+is reported rather than signalled through the exit code.
+
+It takes no `--scope`, since it deliberately reports *all* scopes at
+once -- that is exactly what makes an unintentionally leaked
+registration visible. Scope information is only available for
+`--tool claude` (and, for MCP servers, `--tool copilot`); everywhere
+else the scope is reported as `(n/a)`.
+
+## 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`.
+
+- `COPILOT_HOME`, `CODEX_HOME`:
+  The configuration directories of *GitHub Copilot CLI* (default:
+  `~/.copilot`) and *OpenAI Codex CLI* (default: `~/.codex`).
+
+## EXIT STATUS
+
+`0` in all regular cases, `1` only on an error like an invalid option
+value or a missing agent tool CLI.
+
+## EXAMPLES
+
+```sh
+# report the ASE registrations for Anthropic Claude Code CLI
+$ ase setup status
+
+# report the ASE registrations for OpenAI Codex CLI
+$ ase setup status --tool codex
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-setup`(1), `ase-setup-install`(1), `ase-setup-mcp`(1),
+`ase-setup-statusline`(1), `ase-setup-telemetry`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

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

@@ -0,0 +1,162 @@
+# ase-setup-statusline(1) -- Activate or Deactivate the ASE Statusline
+
+## SYNOPSIS
+
+`ase setup statusline`
+\[`-h`|`--help`\]
+
+`ase setup statusline activate`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+\[`-s`|`--scope` *scope*\]
+\[`-w`|`--width` *n*\]
+\[`-m`|`--margin` *n*\]
+\[`-p`|`--padding` *n*\]
+\[`--no-icons`\]
+\[`--no-labels`\]
+\[*format* \[...\]\]
+
+`ase setup statusline deactivate`
+\[`-h`|`--help`\]
+\[`-t`|`--tool` *tool*\]
+\[`-s`|`--scope` *scope*\]
+
+## DESCRIPTION
+
+**ase setup statusline** activates or deactivates the *ASE*
+statusline, i.e., the `ase statusline` renderer (see
+`ase-statusline`(1)) configured as the `statusLine` command in the
+settings file of the agent tool. Without a sub-command, the usage
+information is shown and the command exits with status `1`.
+
+The statusline is supported for *Anthropic Claude Code CLI* (`claude`)
+and *GitHub Copilot CLI* (`copilot`) only, while *OpenAI Codex CLI*
+(`codex`) has no scriptable statusline mechanism, so `--tool codex`
+fails with an error.
+
+The settings file is, for `claude`, `~/.claude/settings.json` (scope
+`user`), `.claude/settings.json` (scope `project`), resp.
+`.claude/settings.local.json` (scope `local`) relative to the current
+working directory, and, for `copilot`, the single per-user
+`$COPILOT_HOME/settings.json` (default: `~/.copilot/settings.json`).
+The settings file is edited in place (preserving its formatting and
+all other entries) and written atomically, and a missing settings file
+(and its directory) is created.
+
+A `statusLine` entry counts as owned by *ASE* if its `command` starts
+with `ase statusline`. A foreign, hand-crafted `statusLine` entry is
+never touched by either sub-command: it is preserved with a warning,
+and the command still exits with status `0`.
+
+## COMMANDS
+
+- `ase setup statusline activate` \[*options*\] \[*format* \[...\]\]:
+  Add the `statusLine` entry of *ASE* to the settings file, or update
+  an existing one of *ASE* in place.
+
+  The entry is the object
+  `{ "type": "command", "command": "ase statusline ...", "padding": 0 }`,
+  whose command is `ase statusline --tool` *tool* `-w` *width* `-m`
+  *margin* `-p` *padding*, followed by `--no-icons` and `--no-labels`
+  if given, and the *format* lines, each one single-quoted for the
+  shell (resp. double-quoted for `copilot` on Windows, which spawns
+  the command via `cmd.exe`).
+
+- `ase setup statusline deactivate` \[*options*\]:
+  Remove the `statusLine` entry of *ASE* from the settings file. A
+  missing settings file or a missing `statusLine` entry is skipped
+  with an informational message.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-t`|`--tool` *tool*\]:
+  Select the target agent tool: `claude` or `copilot` (default:
+  `$ASE_TOOL`, else `claude`). `codex` is rejected with an error.
+
+- \[`-s`|`--scope` *scope*\]:
+  Select the settings file of the scope `user` (default), `project`,
+  or `local` (see above). Only supported for `--tool claude`; a
+  non-`user` scope for `copilot`, which has a single per-user settings
+  file, fails with an error.
+
+- \[`-w`|`--width` *n*\] (`activate` only):
+  Force the terminal width of the statusline rendering to *n*
+  characters, where `0` (default) auto-detects it via `/dev/tty`.
+  Has to be a non-negative integer.
+
+- \[`-m`|`--margin` *n*\] (`activate` only):
+  Reduce the maximum used terminal width by *n* characters on each
+  side (default: `2`). Has to be a non-negative integer.
+
+- \[`-p`|`--padding` *n*\] (`activate` only):
+  Pad each rendered line with *n* spaces on the left and right side
+  (default: `0`). Has to be a non-negative integer.
+
+- \[`--no-icons`\] (`activate` only):
+  Disable the leading icon glyph in front of each placeholder
+  rendering.
+
+- \[`--no-labels`\] (`activate` only):
+  Disable the textual label in front of the bold value of each
+  placeholder rendering.
+
+## ARGUMENTS
+
+- \[*format* \[...\]\] (`activate` only):
+  One or more statusline template lines of literal text,
+  `%`-prefixed placeholders, and `<`*color*`>`...`</`*color*`>`
+  markup (see `ase-statusline`(1) for all placeholders and colors).
+  Without any *format*, the following three default lines are used:
+  `<blue>%u</blue> <red>%p</red> <black>%T</black> %s` (user, project,
+  task, and session), `%m %e %t` (model, effort, and thinking), and
+  `%P %h %B %c` (persona, guidance level, boxing, and context usage).
+
+## ENVIRONMENT
+
+- `ASE_TOOL`:
+  The default of `--tool`.
+
+- `COPILOT_HOME`:
+  The configuration directory of *GitHub Copilot CLI* (default:
+  `~/.copilot`).
+
+## 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`.
+
+- `$COPILOT_HOME/settings.json` (default: `~/.copilot/settings.json`):
+  The settings file of *GitHub Copilot CLI*.
+
+## EXIT STATUS
+
+`0` on success (including a preserved foreign `statusLine` entry),
+`1` on any error (and when invoked without a sub-command).
+
+## EXAMPLES
+
+```sh
+# activate the ASE statusline with its default lines
+$ ase setup statusline activate
+
+# activate a single custom line for the current project only
+$ ase setup statusline activate --scope project "%p %T %m %c"
+
+# activate the ASE statusline in GitHub Copilot CLI without icons
+$ ase setup statusline activate --tool copilot --no-icons
+
+# deactivate the ASE statusline again
+$ ase setup statusline deactivate
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-setup`(1), `ase-statusline`(1), `ase-setup-status`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>