@rse/ase 2.0.3 → 2.0.5

package/dst/man/ase-artifact-name.md

@@ -0,0 +1,56 @@
+# ase-artifact-name(1) -- Resolve a Filename within an Artifact Kind
+
+## SYNOPSIS
+
+`ase artifact name`
+\[`-h`|`--help`\]
+\[`--kind` *kind*\]
+*filename*
+
+## DESCRIPTION
+
+**ase artifact name** resolves a *filename*, given relative to the base
+directory of an artifact *kind*, to a project-relative (POSIX-style)
+path by prefixing it with the configured base directory
+`project.artifact.`*kind*`.basedir` (see `ase-artifact`(1)), and prints
+it. The file does not have to exist. The skills use it to name a new
+file of a kind, e.g., a new specification or source code file.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`--kind` *kind*\]:
+  The artifact kind whose base directory is used: `spec`, `code`,
+  `docs`, or `infr` (default: `code`). The implicit catch-all kind
+  `othr` has no base directory and is rejected.
+
+## ARGUMENTS
+
+- *filename*:
+  The filename, relative to the base directory of the kind. Backslashes
+  are converted to slashes and leading slashes are stripped. It must
+  not be empty and must not contain any `..` segment.
+
+## EXIT STATUS
+
+Exits with status `0` on success, and with status `1` on an unknown
+or unsupported kind, an empty filename, or a filename with a `..`
+segment.
+
+## EXAMPLES
+
+```sh
+# resolve a source file name (with the default "project.artifact.code.basedir" of "src")
+$ ase artifact name --kind code lib/util.ts
+src/lib/util.ts
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-artifact`(1), `ase-artifact-list`(1), `ase-config`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-artifact.md

@@ -0,0 +1,92 @@
+# ase-artifact(1) -- Resolve Project Artifact Kinds to File Lists
+
+## SYNOPSIS
+
+`ase artifact`
+\[`-h`|`--help`\]
+
+`ase artifact list`
+\[`--kind` *kinds*\]
+
+`ase artifact name`
+\[`--kind` *kind*\]
+*filename*
+
+## DESCRIPTION
+
+**ase artifact** is the entry point group for resolving the *artifact
+kinds* of a project to project-relative file lists. The *ASE* skills
+use it (and the MCP tools `ase_artifact_list` and `ase_artifact_name`,
+which provide the same) to locate the files of a kind. The recognized
+kinds are:
+
+- `spec`: the specification (by default below `docs/specbook`,
+  the files `*.{md,txt,svg,png,jpg}`).
+- `code`: the source code (by default below `src`, all files
+  except `**/etc/**` and `**/{.gitignore,.npmignore,package.json}`).
+- `docs`: the documentation (by default below `doc`, all files plus
+  `**/{README,LICENSE,CHANGELOG}.{md,txt}`, except `{spec,arch}/**`).
+- `infr`: the infrastructure (by default below the project root, the
+  files `**/{.github,.claude*,etc}/**` and
+  `**/{AGENTS.md,{package,tsconfig*}.json,.{git,npm}ignore}`).
+- `othr`: the implicit catch-all of all other files.
+
+The first four kinds are configured by the configuration keys
+`project.artifact.`*kind*`.basedir` (the base directory, relative to
+the project root, where an empty value denotes the project root itself,
+and which must not escape the project root via `..`) and
+`project.artifact.`*kind*`.files` (a *miniglob* specification, resolved
+relative to the base directory), with the defaults given above (see
+`ase-config`(1)).
+
+A *miniglob* specification is a whitespace-separated list of glob
+patterns (in the syntax of *picomatch*, with dot files matched), each
+optionally negated by a `!` prefix. The tokens are applied in order:
+the resulting set starts empty (or with all files, if the first token
+is negated), a plain pattern adds all files matching it, and a negated
+pattern removes all files matching it.
+
+The file universe is the set of all files below the project root (the
+Git top-level directory, else the current working directory), except
+the `.git` directories and all files excluded by the Git exclude rules:
+the global excludes file (`core.excludesFile`, else
+`$XDG_CONFIG_HOME/git/ignore`, falling back to
+`~/.config/git/ignore`), the repository-local `info/exclude`, and the
+`.gitignore` files from the project root downwards, with the last
+matching rule winning.
+
+The universe is partitioned among the kinds by descending precedence
+`spec`, `code`, `docs`, and `infr`: a file matched by multiple kinds
+belongs to the first one only, and every file matched by none of them
+belongs to `othr`.
+
+Without a sub-command, the usage information is shown and the command
+exits with status `1`.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+## COMMANDS
+
+- `ase artifact list` \[`--kind` *kinds*\]:
+  Resolve one or more artifact kinds to project-relative file paths.
+  See `ase-artifact-list`(1).
+
+- `ase artifact name` \[`--kind` *kind*\] *filename*:
+  Resolve a base-relative filename within an artifact kind to a
+  project-relative path. See `ase-artifact-name`(1).
+
+## EXIT STATUS
+
+The group command without a sub-command exits with status `1`.
+
+## SEE ALSO
+
+`ase`(1), `ase-artifact-list`(1), `ase-artifact-name`(1),
+`ase-config`(1), `ase-spec`(1), `gitignore`(5).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-config-delete.md

@@ -0,0 +1,74 @@
+# ase-config-delete(1) -- Delete a Configuration Value
+
+## SYNOPSIS
+
+`ase config`
+\[`--scope` *scope*\]
+`delete`
+\[`-h`|`--help`\]
+*key*
+
+## DESCRIPTION
+
+**ase config delete** deletes the configuration *key* from the
+configuration file of the target scope (the strongest scope of the
+scope chain, by default `project` inside a project, else `user`) and
+writes the file back. Weaker scopes are never modified, so a value of
+the same key on a weaker scope (or the built-in default) becomes
+effective again.
+
+Deleting a key which is not set on the target scope is no error. As
+for `ase config set`, a key which is not writable on the target scope
+cannot be deleted there either, and a target file which carries invalid
+content is not overwritten.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`--scope` *scope*\]:
+  Select the scope chain, whose strongest scope is the target scope
+  written by this command. As an option of `ase config`, it has to be
+  given *before* `delete`. The *scope* value is a comma-separated list
+  of the terms `user`, `project`, `task:`*id*, and `session:`*id* (with
+  *id* matching `[A-Za-z0-9._-]+`), at most one per kind and in any
+  order, canonicalized into the order `user` < `project` < `task` <
+  `session`.
+
+  `user` is always added implicitly, and `project` is added implicitly
+  whenever a project context (a Git working tree or a `.ase` directory
+  at or above the current directory) exists, but never above the
+  strongest explicitly requested term. An explicit `project` without a
+  project context is an error. Default: `project` inside a project
+  context, else `user`. See `ase-config`(1) for details.
+
+## ARGUMENTS
+
+- *key*:
+  The dotted configuration key, e.g., `agent.persona`, or any
+  unambiguous trailing part of a known key, e.g., `persona`.
+
+## EXIT STATUS
+
+`0` on success, `1` on a *key* not writable on the target scope, an
+ambiguous *key*, an invalid *scope*, or a target file carrying invalid
+content.
+
+## EXAMPLES
+
+```sh
+# fall back to the default persona again
+$ ase config delete agent.persona
+
+# remove the task store token of the user
+$ ase config --scope user delete project.task.store.token
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-config`(1), `ase-config-set`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-config-edit.md

@@ -0,0 +1,83 @@
+# ase-config-edit(1) -- Edit the Configuration File with an Editor
+
+## SYNOPSIS
+
+`ase config`
+\[`--scope` *scope*\]
+`edit`
+\[`-h`|`--help`\]
+
+## DESCRIPTION
+
+**ase config edit** opens the configuration file of the target scope
+(the strongest scope of the scope chain, by default `project` inside a
+project, else `user`) in a text editor. The file and its parent
+directories are created if missing (a new `user` scope file with file
+mode `0600`).
+
+After the editor exits, the file is re-read and strictly validated
+against the configuration schema. If it carries invalid YAML or
+invalid entries, the error is reported and the question `re-edit? [Y/n]`
+is asked on standard error: any answer other than `n` or `no` opens the
+editor again, while `n` or `no` lets the command fail (leaving the
+invalid file as is).
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`--scope` *scope*\]:
+  Select the scope chain, whose strongest scope is the target scope
+  whose file is edited. As an option of `ase config`, it has to be
+  given *before* `edit`. The *scope* value is a comma-separated list
+  of the terms `user`, `project`, `task:`*id*, and `session:`*id*
+  (with *id* matching `[A-Za-z0-9._-]+`), at most one per kind and in
+  any order, canonicalized into the order `user` < `project` < `task`
+  < `session`.
+
+  `user` is always added implicitly, and `project` is added implicitly
+  whenever a project context (a Git working tree or a `.ase` directory
+  at or above the current directory) exists, but never above the
+  strongest explicitly requested term. An explicit `project` without a
+  project context is an error. Default: `project` inside a project
+  context, else `user`. See `ase-config`(1) for details.
+
+## ENVIRONMENT
+
+- `VISUAL`, `EDITOR`:
+  The editor command, taken from the first non-empty one of `VISUAL`
+  and `EDITOR`, falling back to `vi`. The value is split on whitespace
+  into the command and its arguments (it is not run through a shell),
+  and the file name is appended as the last argument.
+
+## FILES
+
+The configuration file of the target scope: *per-user configuration
+directory*`/config.yaml` (`user`), `.ase/config.yaml` (`project`),
+`.ase/task/`*id*`/config.yaml` (`task:`*id*), or *per-user state
+directory*`/session/`*id*`/config.yaml` (`session:`*id*). See
+`ase-config`(1).
+
+## EXIT STATUS
+
+`0` once the edited file is valid, `1` if the editor could not be run,
+or if the file stayed invalid and re-editing was declined.
+
+## EXAMPLES
+
+```sh
+# edit the project configuration with Vim
+$ EDITOR=vim ase config edit
+
+# edit the user configuration
+$ ase config --scope user edit
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-config`(1), `ase-config-set`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-config-get.md

@@ -0,0 +1,70 @@
+# ase-config-get(1) -- Print a Configuration Value
+
+## SYNOPSIS
+
+`ase config`
+\[`--scope` *scope*\]
+`get`
+\[`-h`|`--help`\]
+*key*
+
+## DESCRIPTION
+
+**ase config get** prints the effective value of the configuration
+*key*, followed by a newline, on standard output. The value is looked
+up from the strongest scope of the scope chain down to the built-in
+`default` scope, and the first defined value wins. In contrast to `ase
+config list`, secret values are printed unmasked.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`--scope` *scope*\]:
+  Select the scope chain whose values are cascaded. As an option of
+  `ase config`, it has to be given *before* `get`. The *scope* value is
+  a comma-separated list of the terms `user`, `project`, `task:`*id*,
+  and `session:`*id* (with *id* matching `[A-Za-z0-9._-]+`), at most one
+  per kind and in any order, canonicalized into the order `user` <
+  `project` < `task` < `session`.
+
+  `user` is always added implicitly, and `project` is added implicitly
+  whenever a project context (a Git working tree or a `.ase` directory
+  at or above the current directory) exists, but never above the
+  strongest explicitly requested term. An explicit `project` without a
+  project context is an error. Default: `project` inside a project
+  context, else `user`. See `ase-config`(1) for details.
+
+## ARGUMENTS
+
+- *key*:
+  The dotted configuration key, e.g., `agent.persona`, or any
+  unambiguous trailing part of a known key, e.g., `persona`. See
+  `ase-config`(1) for all keys.
+
+## EXIT STATUS
+
+`0` on success, `1` if *key* is not set on any scope, if *key* does not
+address a leaf value (e.g., `project.task`), if *key* is ambiguous, or
+on an invalid *scope*.
+
+## EXAMPLES
+
+```sh
+# print the effective task lifecycle model
+$ ase config get project.task.lifecycle
+solo
+
+# print the user-level persona via its abbreviated key
+$ ase config --scope user get persona
+engineer
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-config`(1), `ase-config-list`(1), `ase-config-set`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

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

@@ -0,0 +1,110 @@
+# ase-config-init(1) -- Initialize Configuration with Preset Values
+
+## SYNOPSIS
+
+`ase config`
+\[`--scope` *scope*\]
+`init`
+\[`-h`|`--help`\]
+*type*
+
+## DESCRIPTION
+
+**ase config init** initializes the configuration file of the target
+scope (the strongest scope of the scope chain, by default `project`
+inside a project, else `user`) with the preset values of *type*. The
+file (and its parent directories) are created if missing. Already
+existing keys of the file which the preset does not cover are kept,
+while those covered by the preset are overwritten.
+
+Keys of the preset which are not writable on the target scope (e.g.,
+all `project.task.*`, `project.artifact.*`, and `board.*` keys on a
+`task` or `session` scope, or `telemetry.prices.ai` on the `project`
+scope) are silently skipped. The file is written under an advisory
+file lock and atomically.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`--scope` *scope*\]:
+  Select the scope chain, whose strongest scope is the target scope
+  written by this command. As an option of `ase config`, it has to be
+  given *before* `init`. The *scope* value is a comma-separated list
+  of the terms `user`, `project`, `task:`*id*, and `session:`*id*
+  (with *id* matching `[A-Za-z0-9._-]+`), at most one per kind and in
+  any order, canonicalized into the order `user` < `project` < `task`
+  < `session`.
+
+  `user` is always added implicitly, and `project` is added implicitly
+  whenever a project context (a Git working tree or a `.ase` directory
+  at or above the current directory) exists, but never above the
+  strongest explicitly requested term. An explicit `project` without a
+  project context is an error. Default: `project` inside a project
+  context, else `user`. See `ase-config`(1) for details.
+
+## ARGUMENTS
+
+- *type*:
+  The preset to apply, one of:
+
+    - `default`:
+      The complete baseline of the built-in `default` scope:
+      `agent.persona` `engineer`, `agent.guidance` `normal`,
+      `project.name` `Example Project`, `project.boxing` `white`,
+      `project.task.lifecycle` `solo`, `project.task.idscheme` `slug`,
+      `project.task.store.url` `ase:./.ase/task`,
+      `project.task.default.source` `worktree`,
+      `project.task.default.changeset` `worktree`,
+      `project.task.default.target` `source`,
+      `project.task.effort.scale` `15,60,240,960`,
+      `project.task.effort.factor` `1`, `project.task.effort.file` `1`,
+      `project.task.effort.line` `0.025`,
+      `project.task.effort.iteration` `2.5`, the full set of
+      `project.artifact.*` globs, the `board.tui.color.*`,
+      `board.web.color.*`, and `board.web.editor.keymap` defaults, and
+      `telemetry.enabled` `false`, `telemetry.prices.ai`
+      `*=4.00/20.00/0.20/5.00`, and `telemetry.prices.hr` `*=110`.
+    - `vibe`:
+      `agent.persona` `writer`, `project.name` `Example Project`, and
+      `project.boxing` `black`.
+    - `pro`:
+      `agent.persona` `engineer`, `project.name` `Example Project`, and
+      `project.boxing` `white`.
+    - `industry`:
+      `agent.persona` `engineer`, `project.name` `Example Project`, and
+      `project.boxing` `grey`.
+
+  Any other *type* is an error.
+
+## FILES
+
+The configuration file of the target scope: *per-user configuration
+directory*`/config.yaml` (`user`), `.ase/config.yaml` (`project`),
+`.ase/task/`*id*`/config.yaml` (`task:`*id*), or *per-user state
+directory*`/session/`*id*`/config.yaml` (`session:`*id*). See
+`ase-config`(1).
+
+## EXIT STATUS
+
+`0` on success, `1` on an unknown *type*, an invalid *scope*, or a
+target file carrying invalid content.
+
+## EXAMPLES
+
+```sh
+# initialize the project configuration for an industrial project
+$ ase config init industry
+
+# write the entire baseline into the user configuration
+$ ase config --scope user init default
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-config`(1), `ase-config-list`(1), `ase-config-set`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-config-list.md

@@ -0,0 +1,68 @@
+# ase-config-list(1) -- List the Effective Configuration
+
+## SYNOPSIS
+
+`ase config`
+\[`--scope` *scope*\]
+`list`
+\[`-h`|`--help`\]
+
+## DESCRIPTION
+
+**ase config list** lists all configuration keys known to the
+configuration schema, plus all further leaf keys found in the files of
+the scope chain, with their effective values, rendered as a table with
+the three columns `KEY`, `VALUE`, and `SCOPE`, sorted by key.
+
+The `SCOPE` column names the scope which supplied the value: `default`
+(the built-in defaults), `user`, `project`, `task:`*id*, or
+`session:`*id*. For a key set on multiple scopes, only the value of the
+strongest scope is shown. A key which is not set on any scope is shown
+with an empty `VALUE` and the `SCOPE` `-`. The values of the secret keys
+`project.task.store.token`, `project.relay.token`, and
+`telemetry.service.token` are masked as `***`.
+
+Invalid entries of the configuration files are warned about and
+skipped.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`--scope` *scope*\]:
+  Select the scope chain whose values are cascaded. As an option of
+  `ase config`, it has to be given *before* `list`. The *scope* value
+  is a comma-separated list of the terms `user`, `project`, `task:`*id*,
+  and `session:`*id* (with *id* matching `[A-Za-z0-9._-]+`), at most
+  one per kind and in any order, canonicalized into the order `user` <
+  `project` < `task` < `session`.
+
+  `user` is always added implicitly, and `project` is added implicitly
+  whenever a project context (a Git working tree or a `.ase` directory
+  at or above the current directory) exists, but never above the
+  strongest explicitly requested term. An explicit `project` without a
+  project context is an error. Default: `project` inside a project
+  context, else `user`. See `ase-config`(1) for details.
+
+## EXIT STATUS
+
+`0` on success, `1` on an invalid *scope*.
+
+## EXAMPLES
+
+```sh
+# list the effective project configuration
+$ ase config list
+
+# list the configuration as seen by a particular task
+$ ase config --scope task:json-export list
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-config`(1), `ase-config-get`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>

package/dst/man/ase-config-set.md

@@ -0,0 +1,92 @@
+# ase-config-set(1) -- Set a Configuration Value
+
+## SYNOPSIS
+
+`ase config`
+\[`--scope` *scope*\]
+`set`
+\[`-h`|`--help`\]
+*key*
+*value*
+
+## DESCRIPTION
+
+**ase config set** sets the configuration *key* to *value* in the
+configuration file of the target scope (the strongest scope of the
+scope chain, by default `project` inside a project, else `user`),
+creating the file, its parent directories, and the intermediate maps
+of the dotted key as needed. Weaker and intermediate scopes are never
+modified.
+
+The *value* is validated against the configuration schema before the
+file is written, and an invalid value is an error. Some keys are
+writable on particular scopes only (e.g., `project.task.*` on `user`
+and `project`, the token keys on `user`): setting such a key on any
+other scope is an error naming the permitted scopes. See
+`ase-config`(1) for all keys, their values, and their scopes. A target
+file which already carries invalid content is not overwritten, as this
+content would be lost.
+
+The file is written under an advisory file lock and atomically, with
+file mode `0600` for the `user` scope and for any file carrying a
+secret key.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`--scope` *scope*\]:
+  Select the scope chain, whose strongest scope is the target scope
+  written by this command. As an option of `ase config`, it has to be
+  given *before* `set`. The *scope* value is a comma-separated list
+  of the terms `user`, `project`, `task:`*id*, and `session:`*id*
+  (with *id* matching `[A-Za-z0-9._-]+`), at most one per kind and in
+  any order, canonicalized into the order `user` < `project` < `task`
+  < `session`.
+
+  `user` is always added implicitly, and `project` is added implicitly
+  whenever a project context (a Git working tree or a `.ase` directory
+  at or above the current directory) exists, but never above the
+  strongest explicitly requested term, so an explicit `--scope user`
+  is never silently retargeted to `project`. An explicit `project`
+  without a project context is an error. Default: `project` inside a
+  project context, else `user`. See `ase-config`(1) for details.
+
+## ARGUMENTS
+
+- *key*:
+  The dotted configuration key, e.g., `agent.persona`, or any
+  unambiguous trailing part of a known key, e.g., `persona`.
+
+- *value*:
+  The value to set, stored as a string (e.g., `true` for
+  `telemetry.enabled` or `44318` for `telemetry.service.port`).
+
+## EXIT STATUS
+
+`0` on success, `1` on an invalid *value*, a *key* not writable on the
+target scope, an ambiguous *key*, an intermediate path of *key* which is
+not a map, an invalid *scope*, or a target file carrying invalid
+content.
+
+## EXAMPLES
+
+```sh
+# switch the project to the enterprise task lifecycle model
+$ ase config set project.task.lifecycle enterprise
+
+# enable the AI usage accounting for the current user
+$ ase config --scope user set telemetry.enabled true
+
+# set the persona for a single session only
+$ ase config --scope session:4711 set agent.persona caveman
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-config`(1), `ase-config-get`(1), `ase-config-delete`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>