@rse/ase 2.0.5 → 2.0.7

package/dst/ase-task-store-plugin-gitea.js

@@ -3,7 +3,7 @@
 **  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
 **  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
 */
-import { giteaApi } from "gitea-js";
+import { giteaApi, ContentType } from "gitea-js";
 import { LRUCache } from "lru-cache";
 import * as TaskFormat from "./ase-task-format.js";
 import * as TaskIssues from "./ase-task-store-issues.js";
@@ -396,7 +396,7 @@ class GiteaTaskStoragePlugin extends TaskIssues.IssueTaskStoragePlugin {
         for (const blocker of after) {
             if (have.has(blocker.number))
                 continue;
-            await this.call(loc, this.gt.repos.issueCreateIssueDependencies(loc.owner, loc.repo, String(issue.number), meta(blocker)))
+            await this.call(loc, this.gt.repos.issueCreateIssueDependencies(loc.owner, loc.repo, String(issue.number), meta(blocker), { type: ContentType.Json }))
                 .catch((err) => {
                 if (statusOf(err) === 404)
                     throw new Error(`Gitea rejected the dependency of issue #${issue.number} on issue #${blocker.number} ` +
@@ -406,7 +406,7 @@ class GiteaTaskStoragePlugin extends TaskIssues.IssueTaskStoragePlugin {
         }
         for (const blocker of current)
             if (!want.has(blocker.number))
-                await found(this.call(loc, this.gt.repos.issueRemoveIssueDependencies(loc.owner, loc.repo, String(issue.number), meta(blocker))));
+                await found(this.call(loc, this.gt.repos.issueRemoveIssueDependencies(loc.owner, loc.repo, String(issue.number), meta(blocker), { type: ContentType.Json })));
     }
     /*  synchronize the comments with the attachments, touching changed ones only
         (see the common issue tracker parts)  */

package/dst/man/ase-agent-adhoc.md

@@ -19,6 +19,7 @@
 \[`--lifecycle` *model*\]
 \[`--serial`\]
 \[`--unclaimed`\]
+\[`-M`|`--model` *model*\]
 \[`--params` *name*`=`*value*\]
 \[`--state-`*item* *state*\]
 \[`--tag-`*item* *tag*\]
@@ -169,12 +170,12 @@ tags (except the request state tag) and, by default, gets its previous
 assignee back. An agent consumes the request prompts if its prompt
 template references `{prompt}` (except within the conditional
 `{?prompt:`*text*`}` only, which makes the prompt *optional*) or it
-has a hook `prepare`, `prompt`, or `finish` (which receive the request
-prompt in their *job*), where it then refuses a request with an empty
-prompt as failed, else it accepts requests with an empty prompt (which
-an agent with an optional prompt still passes on if non-empty), and
-announces this to the agent relay, so the task boards accept an empty
-prompt for its requests, too.
+has a hook `prepare`, `prompt`, `model`, or `finish` (which receive
+the request prompt in their *job*), where it then refuses a request
+with an empty prompt as failed, else it accepts requests with an empty
+prompt (which an agent with an optional prompt still passes on if
+non-empty), and announces this to the agent relay, so the task boards
+accept an empty prompt for its requests, too.
 
 Only the prompt (and `--state-incoming` for `--type phase`) is
 mandatory, while all other options default to the safe *annotate*
@@ -431,6 +432,16 @@ and `--prompt-skill` with `--prompt-args`, and `--tag-retry` and
   `passes`, and `--workdir changeset` resp. `target` (as the task can
   be claimed by another agent meanwhile).
 
+- \[`-M`|`--model` *model*\]:
+  The model of the agent tool, passed to it as `--model` *model*
+  verbatim (e.g., an alias like `sonnet` or a full model name), either a
+  *model* for all tasks, or comma-separated *size*`=`*model* pairs per
+  `Effort:` size of the task (`XS`, `S`, `M`, `L`, `XL`, or `*` for all
+  other tasks, e.g., `XS=haiku,S=haiku,M=sonnet,*=opus`), where a task
+  without a matching pair gets the default model of the agent tool (the
+  default for all tasks). The hook `model` can override it per task (see
+  **HOOKS**).
+
 - \[`--params` *name*`=`*value*\]:
   (repeatable) The value of the parameter *name* declared by the
   definition (see **PARAMETERS**), where a later value of the same
@@ -986,6 +997,14 @@ invocation:
   `{ text }`, a plain prompt text, or `undefined` to keep the
   configured one, where a thrown error fails the processing.
 
+- `model(task, model, job, ctx)`:
+  The model of the agent tool for the job, given the configured *model*
+  of `--model` for the `Effort:` size of the task (empty for the default
+  model of the agent tool): a model (empty for the default one), or
+  `undefined` to keep the configured one, where a thrown error fails the
+  processing. This allows choosing the model per task by any means,
+  e.g., by asking a cheap model via `ctx.exec`.
+
 - `verdict(task, result, ctx)`:
   (after a successful agent tool only) The verdict of the result (an
   upper-case word, accepted only if listed by `--verdict-allow`), an

package/dst/man/ase-agent-condenser.md

@@ -9,6 +9,7 @@
 \[`-T`|`--timeout` *duration*\]
 \[`-o`|`--one-shot`\]
 \[`--agent-relay` *url*\]
+\[`-M`|`--model` *model*\]
 \[`--`*group*`-`*item* *value* \[...\]\]
 \[`-f`|`--foreground`\]
 
@@ -145,6 +146,12 @@ All other options belong to the sub-commands (see **COMMANDS**).
       (`phase` only). Built-in: not set. Not allowed, as the condenser
       claims the tasks into its activity state.
 
+    - \[`-M`|`--model` *model*\]: The model of the agent tool: a model
+      for all tasks, or comma-separated *size*`=`*model* pairs per
+      `Effort:` size (`XS`, `S`, `M`, `L`, `XL`, or `*` for all other
+      tasks), see `ase-agent-adhoc`(1). Generic default: the default
+      model of the agent tool. Built-in: none.
+
     - \[`--params` *name*`=`*value*\]: The value of a parameter
       declared by the definition (repeatable). Built-in: none declared.
 

package/dst/man/ase-agent-editor.md

@@ -11,6 +11,7 @@
 \[`--agent-relay` *url*\]
 \[`-r`|`--repo` *url*\]
 \[`-d`|`--tempdir` *dir*\]
+\[`-M`|`--model` *model*\]
 \[`--`*group*`-`*item* *value* \[...\]\]
 \[`-f`|`--foreground`\]
 
@@ -192,6 +193,12 @@ All other options belong to the sub-commands (see **COMMANDS**).
       (`phase` only). Built-in: not set. Not allowed, as the editor is
       of type `request`.
 
+    - \[`-M`|`--model` *model*\]: The model of the agent tool: a model
+      for all tasks, or comma-separated *size*`=`*model* pairs per
+      `Effort:` size (`XS`, `S`, `M`, `L`, `XL`, or `*` for all other
+      tasks), see `ase-agent-adhoc`(1). Generic default: the default
+      model of the agent tool. Built-in: none.
+
     - \[`--params` *name*`=`*value*\]: The value of a parameter
       declared by the definition (repeatable). Built-in: none declared.
 

package/dst/man/ase-agent-estimator.md

@@ -10,6 +10,7 @@
 \[`-o`|`--one-shot`\]
 \[`--agent-relay` *url*\]
 \[`-m`|`--mode` `phase`|`request`\]
+\[`-M`|`--model` *model*\]
 \[`--`*group*`-`*item* *value* \[...\]\]
 \[`-f`|`--foreground`\]
 
@@ -204,6 +205,12 @@ All other options belong to the sub-commands (see **COMMANDS**).
       (`phase` only). Built-in: enabled (mode `phase`) resp. not set
       (mode `request`).
 
+    - \[`-M`|`--model` *model*\]: The model of the agent tool: a model
+      for all tasks, or comma-separated *size*`=`*model* pairs per
+      `Effort:` size (`XS`, `S`, `M`, `L`, `XL`, or `*` for all other
+      tasks), see `ase-agent-adhoc`(1). Generic default: the default
+      model of the agent tool. Built-in: none.
+
     - \[`--params` *name*`=`*value*\]: The value of a parameter
       declared by the definition (repeatable). Built-in: none declared.
 

package/dst/man/ase-agent-fleet.md

@@ -79,7 +79,7 @@ members) or `ase agent fleet stop`.
   (with all its options commented out, so they fall back to
   `project.relay.url`, `project.relay.crt`, and `project.relay.key`),
   the section `default` (with `tool`, `parallel: 1`, and `timeout: 60m`,
-  plus `repo` and `tempdir` commented out), the edit request agent
+  plus `model`, `repo`, and `tempdir` commented out), the edit request agent
   `editor`, the effort estimation agent `estimator` (mode `phase`,
   estimating the planned tasks, i.e., the `OPEN` tasks for `solo`, the
   `PLANNING` tasks for `team`, and the `PLANNED` tasks for `enterprise`,
@@ -201,8 +201,9 @@ value omits an option, and a list repeats an option:
   `project.relay.url` selecting HTTPS requires both.
 
 - `default`:
-  (optional) The default options of all agents: `tool`, `parallel`,
-  `timeout`, `repo`, `tempdir`, and `agent-relay` (see `ase-agent`(1)),
+  (optional) The default options of all agents: `tool`, `model`,
+  `parallel`, `timeout`, `repo`, `tempdir`, and `agent-relay` (see
+  `ase-agent`(1) and `ase-agent-adhoc`(1)),
   each one applied only to the agents supporting it (e.g., `repo` not to
   `rebooter`), and overridden by the section of an agent. The option
   `agent-relay` is not allowed together with the section `relay`.
@@ -315,7 +316,8 @@ $ ase agent fleet stop
 ```
 
 A configuration `.ase/fleet.yaml` with the agent relay, the built-in
-agents, two editors of different agent tools, an agent of the
+agents (with an implementer using cheaper models for smaller tasks),
+two editors of different agent tools, an agent of the
 definition file `.ase/agents/reviewer.mts`, and an ad-hoc request
 agent:
 
@@ -329,6 +331,7 @@ default:
 rebooter:
 implementer:
     parallel: 2
+    model:    XS=haiku,S=haiku,*=sonnet
 editor-claude:
     kind:     editor
 editor-codex:

package/dst/man/ase-agent-implementer.md

@@ -12,6 +12,7 @@
 \[`-r`|`--repo` *url*\]
 \[`-d`|`--tempdir` *dir*\]
 \[`-m`|`--mode` `implement`|`draft`\]
+\[`-M`|`--model` *model*\]
 \[`--`*group*`-`*item* *value* \[...\]\]
 \[`-f`|`--foreground`\]
 
@@ -260,6 +261,12 @@ All other options belong to the sub-commands (see **COMMANDS**).
       (`phase` only). Built-in: not set. Not allowed, as the implementer
       claims the tasks into its activity state.
 
+    - \[`-M`|`--model` *model*\]: The model of the agent tool: a model
+      for all tasks, or comma-separated *size*`=`*model* pairs per
+      `Effort:` size (`XS`, `S`, `M`, `L`, `XL`, or `*` for all other
+      tasks), see `ase-agent-adhoc`(1). Generic default: the default
+      model of the agent tool. Built-in: none.
+
     - \[`--params` *name*`=`*value*\]: The value of a parameter
       declared by the definition (repeatable). Built-in: `effort-wait`
       (`true` or `false`, default: `true`), whether to wait for the

package/dst/man/ase-agent-integrator.md

@@ -12,6 +12,7 @@
 \[`-r`|`--repo` *url*\]
 \[`-d`|`--tempdir` *dir*\]
 \[`-m`|`--mode` `merge`|`rebase`|`squash`\]
+\[`-M`|`--model` *model*\]
 \[`--`*group*`-`*item* *value* \[...\]\]
 \[`-f`|`--foreground`\]
 
@@ -206,6 +207,12 @@ All other options belong to the sub-commands (see **COMMANDS**).
       (`phase` only). Built-in: not set. Not allowed, as the integrator
       claims the tasks into its activity state.
 
+    - \[`-M`|`--model` *model*\]: The model of the agent tool: a model
+      for all tasks, or comma-separated *size*`=`*model* pairs per
+      `Effort:` size (`XS`, `S`, `M`, `L`, `XL`, or `*` for all other
+      tasks), see `ase-agent-adhoc`(1). Generic default: the default
+      model of the agent tool. Built-in: none.
+
     - \[`--params` *name*`=`*value*\]: The value of a parameter
       declared by the definition (repeatable). Built-in: none declared.
 

package/dst/man/ase-agent-qualifier.md

@@ -12,6 +12,7 @@
 \[`-r`|`--repo` *url*\]
 \[`-d`|`--tempdir` *dir*\]
 \[`-m`|`--mode` `judge`|`qualify`\]
+\[`-M`|`--model` *model*\]
 \[`--`*group*`-`*item* *value* \[...\]\]
 \[`-f`|`--foreground`\]
 
@@ -187,6 +188,12 @@ All other options belong to the sub-commands (see **COMMANDS**).
       (`phase` only). Built-in: not set. Not allowed, as the qualifier
       claims the tasks into its activity state.
 
+    - \[`-M`|`--model` *model*\]: The model of the agent tool: a model
+      for all tasks, or comma-separated *size*`=`*model* pairs per
+      `Effort:` size (`XS`, `S`, `M`, `L`, `XL`, or `*` for all other
+      tasks), see `ase-agent-adhoc`(1). Generic default: the default
+      model of the agent tool. Built-in: none.
+
     - \[`--params` *name*`=`*value*\]: The value of a parameter
       declared by the definition (repeatable). Built-in: none declared.
 

package/dst/man/ase-agent-rebooter.md

@@ -9,6 +9,7 @@
 \[`-T`|`--timeout` *duration*\]
 \[`-o`|`--one-shot`\]
 \[`--agent-relay` *url*\]
+\[`-M`|`--model` *model*\]
 \[`--`*group*`-`*item* *value* \[...\]\]
 \[`-f`|`--foreground`\]
 
@@ -145,6 +146,12 @@ All other options belong to the sub-commands (see **COMMANDS**).
       (`phase` only). Built-in: not set. Not allowed, as the rebooter
       claims the tasks into its activity state.
 
+    - \[`-M`|`--model` *model*\]: The model of the agent tool: a model
+      for all tasks, or comma-separated *size*`=`*model* pairs per
+      `Effort:` size (`XS`, `S`, `M`, `L`, `XL`, or `*` for all other
+      tasks), see `ase-agent-adhoc`(1). Generic default: the default
+      model of the agent tool. Built-in: none.
+
     - \[`--params` *name*`=`*value*\]: The value of a parameter
       declared by the definition (repeatable). Built-in: none declared.
 

package/dst/man/ase-agent-researcher.md

@@ -12,6 +12,7 @@
 \[`-r`|`--repo` *url*\]
 \[`-d`|`--tempdir` *dir*\]
 \[`-m`|`--mode` `phase`|`request`\]
+\[`-M`|`--model` *model*\]
 \[`--`*group*`-`*item* *value* \[...\]\]
 \[`-f`|`--foreground`\]
 
@@ -246,6 +247,12 @@ All other options belong to the sub-commands (see **COMMANDS**).
     - \[`--unclaimed`\]: Process the tasks of the incoming states
       without claiming them (`phase` only). Built-in: not set.
 
+    - \[`-M`|`--model` *model*\]: The model of the agent tool: a model
+      for all tasks, or comma-separated *size*`=`*model* pairs per
+      `Effort:` size (`XS`, `S`, `M`, `L`, `XL`, or `*` for all other
+      tasks), see `ase-agent-adhoc`(1). Generic default: the default
+      model of the agent tool. Built-in: none.
+
     - \[`--params` *name*`=`*value*\]: The value of a parameter
       declared by the definition (repeatable). Built-in: none declared.
 

package/dst/man/ase-artifact.md

@@ -21,7 +21,7 @@ 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}`).
+  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

package/dst/man/ase-config.md

@@ -259,12 +259,14 @@ glob). See `ase-artifact`(1):
 
 - `project.artifact.spec.basedir`, `project.artifact.spec.files`:
   The specification files (default: `docs/specbook` and
-  `*.{md,txt,svg,png,jpg}`).
+  `**/*.{md,txt,svg,png,jpg}`).
 
 - `project.artifact.spec.schema` (*string*):
   The whitespace-separated list of *SpecBook* schema configuration
-  files, where `std` names the bundled standard one and every other
-  entry is a file relative to the project root (default: empty, i.e.,
+  files, where `std`, `meta`, and `pm` name the bundled standard, meta,
+  and project management ones, `npm:`, `github:`, `http:`, and
+  `https:` references name remote ones, and every other entry is a file
+  or glob pattern relative to the project root (default: empty, i.e.,
   `std`). See `ase-spec`(1).
 
 - `project.artifact.code.basedir`, `project.artifact.code.files`:

package/dst/man/ase-mcp.md

@@ -53,7 +53,7 @@ The service provides the `ase_*` MCP tools of the skills, e.g.,
 `ase_config_list`, `ase_state_get`, `ase_state_set`,
 `ase_state_delete`, `ase_kv_get`, `ase_kv_set`, `ase_kv_delete`,
 `ase_kv_clear`, `ase_kv_batch`, the `ase_task_*` tools, `ase_artifact_list`,
-`ase_artifact_name`, `ase_specbook_lint`, `ase_specbook_export`,
+`ase_artifact_name`, `ase_specbook_lint`, `ase_specbook_export`, `ase_specbook_query`,
 `ase_diagram`, `ase_worktree_path`, `ase_mint`, `ase_text_metric`,
 `ase_getopt`, `ase_markdown_prepare`, `ase_timestamp`, `ase_sleep`,
 `ase_compat`, `ase_component_info`, and `ase_decision_matrix`.

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

@@ -34,6 +34,14 @@ 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)).
 
+For `--tool claude`, the function hooks of the plugin-shipped
+*Claude Code* mods (e.g., the clickable grilling table and the help
+bands above the prompt) are additionally enabled by writing
+`"CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1"` into the `env` of the
+`settings.json` of the installation scope, unless the variable is
+already present there: an *ASE* one (value `1`) is left as is, and a
+foreign one (any other value) is preserved with a warning.
+
 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`).
@@ -82,7 +90,8 @@ already installed when running it (e.g., via `npm install -g
 
 - `~/.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`.
+  receiving the `outputStyle` selection and the
+  `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` variable for `--tool claude`.
 
 ## EXIT STATUS
 

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

@@ -33,6 +33,12 @@ the agent tool to be found in `$PATH`. The rows are:
   (the *ASE* output style `ase:ase-terse`) or `foreign`
   (hand-selected).
 
+- `FUNCTIONHOOKS` (`--tool claude` only):
+  One row per settings file (of the scopes `user`, `project`, and
+  `local`) carrying a `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS` variable in
+  its `env`, with the status `enabled` (value `1`) or `foreign` (any
+  other value).
+
 - `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.,

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

@@ -20,7 +20,9 @@ steps are:
 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.
+   a warning. Likewise, the variable `CLAUDE_CODE_ENABLE_FUNCTION_HOOKS`
+   (value `1`) is removed from its `env` (together with an `env` which
+   became empty), while a foreign value 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

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

@@ -42,6 +42,9 @@ 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, and the function hooks are
+enabled through `"CLAUDE_CODE_ENABLE_FUNCTION_HOOKS": "1"` in its
+`env`, unless a foreign value of the variable is already present
 there, which is preserved with a warning.
 
 ## OPTIONS

package/dst/man/ase-setup.md

@@ -23,8 +23,8 @@ The target agent tool is either *Anthropic Claude Code 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
+edits of its settings files (for the output style, the function
+hooks, the statusline, and the telemetry). Every sub-process command is logged (with API keys
 masked) and its output is shown only on failure.
 
 ## OPTIONS
@@ -79,8 +79,8 @@ individual manual pages for the exact applicability):
   `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).
+  Report the plugin, MCP server, output style, function hooks,
+  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.

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

@@ -6,6 +6,7 @@
 \[`-h`|`--help`\]
 \[`-o`|`--output` \[*format*`:`\]*file*\] \[...\]
 \[`-w`|`--watch`\]
+\[`-S`|`--schema`\]
 
 ## DESCRIPTION
 
@@ -55,8 +56,10 @@ The MCP tool `ase_specbook_export` provides the same to the skills.
   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`).
+  `index.html` (resp. `schema.html` under `--schema`) inside the
+  specification base directory (e.g., `docs/specbook/index.html`).
+  A `md` output inside the specification base directory is refused,
+  as it would be parsed as a specification file itself.
 
 - \[`-w`|`--watch`\]:
   Do not terminate after the initial export, but keep the outputs in
@@ -67,6 +70,10 @@ The MCP tool `ase_specbook_export` provides the same to the skills.
   `--watch` rejects the `-` standard output. The command then runs
   until it is interrupted (e.g., via `CTRL+C`).
 
+- \[`-S`|`--schema`\]:
+  Export the effective schema configuration `project.artifact.spec.schema`
+  itself, rendered as a *SpecBook* document, instead of the specification.
+
 ## EXIT STATUS
 
 Exits with status `0` on success, and with status `1` on any lint
@@ -88,11 +95,15 @@ $ ase spec export -o md:-
 
 # keep an HTML export in sync with the sources
 $ ase spec export -o /tmp/spec.html -w
+
+# export the schema configuration as PDF
+$ ase spec export -S -o schema.pdf
 ```
 
 ## SEE ALSO
 
-`ase`(1), `ase-spec`(1), `ase-spec-lint`(1), `ase-spec-preview`(1).
+`ase`(1), `ase-spec`(1), `ase-spec-lint`(1), `ase-spec-query`(1),
+`ase-spec-preview`(1).
 
 ## AUTHOR
 

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

@@ -4,6 +4,7 @@
 
 `ase spec init`
 \[`-h`|`--help`\]
+\[`-s`|`--sample`\]
 
 ## DESCRIPTION
 
@@ -31,6 +32,11 @@ configuration are taken from the *ASE* configuration (see
 - \[`-h`|`--help`\]:
   Show usage information and exit.
 
+- \[`-s`|`--sample`\]:
+  Additionally scaffold one lint-clean sample object per allowed object
+  kind into the created files, with placeholder values satisfying the
+  schema configuration, so the format is learnable from them.
+
 ## EXIT STATUS
 
 Exits with status `0` on success, and with status `1` if the
@@ -44,12 +50,15 @@ $ ase spec init
 
 # initialize and then lint the specification
 $ ase spec init && ase spec lint
+
+# initialize the specification with sample objects
+$ ase spec init -s
 ```
 
 ## SEE ALSO
 
 `ase`(1), `ase-spec`(1), `ase-spec-lint`(1), `ase-spec-export`(1),
-`ase-spec-preview`(1), `ase-config`(1).
+`ase-spec-query`(1), `ase-spec-preview`(1), `ase-config`(1).
 
 ## AUTHOR
 

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

@@ -67,7 +67,8 @@ $ ase spec lint -m
 
 ## SEE ALSO
 
-`ase`(1), `ase-spec`(1), `ase-spec-export`(1), `ase-spec-preview`(1).
+`ase`(1), `ase-spec`(1), `ase-spec-export`(1), `ase-spec-query`(1),
+`ase-spec-preview`(1).
 
 ## AUTHOR
 

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

@@ -6,6 +6,7 @@
 \[`-h`|`--help`\]
 \[`-a`|`--addr` *ip-addr*\]
 \[`-p`|`--port` *tcp-port*\]
+\[`-S`|`--schema`\]
 
 ## DESCRIPTION
 
@@ -33,6 +34,10 @@ interrupted (e.g., via `CTRL+C`).
   The TCP port to listen on, an integer in the range `1`..`65535`
   (default: `12345`).
 
+- \[`-S`|`--schema`\]:
+  Preview the effective schema configuration `project.artifact.spec.schema`
+  itself, rendered as a *SpecBook* document, instead of the specification.
+
 ## EXIT STATUS
 
 Runs until interrupted. Exits with status `1` on an invalid TCP port
@@ -46,11 +51,15 @@ $ ase spec preview
 
 # serve the live preview on all interfaces on port 8080
 $ ase spec preview -a 0.0.0.0 -p 8080
+
+# serve the live preview of the schema configuration
+$ ase spec preview -S
 ```
 
 ## SEE ALSO
 
-`ase`(1), `ase-spec`(1), `ase-spec-export`(1), `ase-spec-lint`(1).
+`ase`(1), `ase-spec`(1), `ase-spec-export`(1), `ase-spec-lint`(1),
+`ase-spec-query`(1).
 
 ## AUTHOR
 

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

@@ -0,0 +1,96 @@
+# ase-spec-query(1) -- Query the Project Specification
+
+## SYNOPSIS
+
+`ase spec query`
+\[`-h`|`--help`\]
+\[`-P`|`--param` *name*`=`*value*\] \[...\]
+\[`-f`|`--format` *format*\]
+\[`-o`|`--output` \[*format*`:`\]*file*\]
+\[`-S`|`--schema`\]
+*selector*
+
+## DESCRIPTION
+
+**ase spec query** loads the *SpecBook*-based specification Markdown
+files below `project.artifact.spec.basedir` (see `ase-spec`(1)),
+strictly validated like for `ase spec export` (see `ase-spec-export`(1)),
+and queries its Abstract Syntax Tree (AST) with the XPath-like *ASTq*
+*selector*, e.g., `// USE-CASE [ @STATUS == 'Done' ]`. The matched
+nodes are written as a JSON, JSON5, YAML, or TOON array, their subtrees
+included and the embedded file contents dropped.
+
+The queried tree consists of:
+
+- the root node of type `specification`,
+- its children of type `artifact`, with the attributes `created`,
+  `modified`, and `file`, and
+- the objects below, typed by their kind (with whitespace dashed),
+  with the attributes `kind`, `id`, `anchor`, `paren`, `name`,
+  `primary`, `description`, `rationale`, `elaboration`, and one per
+  property key.
+
+The query function `refs()` yields the objects the references of the
+current object resolve to, e.g., `// USE-CASE [ count(refs()) == 0 ]`.
+
+The query 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 queried.
+
+The MCP tool `ase_specbook_query` provides the same to the skills.
+
+## OPTIONS
+
+- \[`-h`|`--help`\]:
+  Show usage information and exit.
+
+- \[`-P`|`--param` *name*`=`*value*\]:
+  Substitute the value *value* for the parameter `{`*name*`}` of the
+  *selector*. The option is repeatable, one per parameter.
+
+- \[`-f`|`--format` *format*\]:
+  The output format `json`, `json5`, `yaml`, or `toon` (default:
+  inferred from the *file* of `--output` like for `ase spec export`,
+  else `json`).
+
+- \[`-o`|`--output` \[*format*`:`\]*file*\]:
+  Write the result into *file*, or to standard output for `-`
+  (default: `-`). A relative *file* is relative to the current working
+  directory.
+
+- \[`-S`|`--schema`\]:
+  Query the effective schema configuration `project.artifact.spec.schema`
+  itself, described as a *SpecBook* document of the bundled meta schema
+  configuration, instead of the specification.
+
+## EXIT STATUS
+
+Exits with status `0` on success, and with status `1` on any lint
+diagnostic of `error` severity, an invalid *selector* or parameter, an
+unsupported output format, or an unwritable output file.
+
+## EXAMPLES
+
+```sh
+# list all use cases as JSON
+$ ase spec query "// USE-CASE"
+
+# list the finished use cases as YAML
+$ ase spec query -f yaml "// USE-CASE [ @STATUS == 'Done' ]"
+
+# list the objects of a given kind into a TOON file
+$ ase spec query -P kind=ROLE -o roles.toon "// * [ @kind == {kind} ]"
+
+# list the artifacts of the schema configuration itself
+$ ase spec query -S "/ artifact"
+```
+
+## SEE ALSO
+
+`ase`(1), `ase-spec`(1), `ase-spec-lint`(1), `ase-spec-export`(1),
+`ase-spec-preview`(1).
+
+## AUTHOR
+
+Dr. Ralf S. Engelschall <rse@engelschall.com>
+