@rse/ase 0.9.63 → 0.9.65

package/plugin/skills/ase-help-intent/help.md

@@ -1,7 +1,7 @@
 
 ##  NAME
 
-`ase-help-intent` - Match an Intent to an ASE Command
+`ase-help-intent` - Match an Intent to ASE Commands
 
 ##  SYNOPSIS
 
@@ -14,18 +14,22 @@
 The `ase-help-intent` skill matches a free-text *intent* against the
 *accumulated help* of all ASE skills -- the concatenation of every
 skill's `help.md` file into `skills/ase-help-intent/data.md`, built by
-`npm start build` in `plugin/` -- and generates the *single* best-fitting
-`/ase:ase-xxx-xxx` command that realizes the intent, complete with
-concrete option flags and positional arguments derived from the selected
-skill's `SYNOPSIS`, `OPTIONS`, and `ARGUMENTS`.
-
-The generated command is presented together with a brief rationale in an
-interactive dialog. The dialog lets the user *execute* the command (which
-dispatches the target skill via its generated arguments), *cancel* the
-operation, or *refine* the intent by typing any free-text instruction --
-the instruction is folded into the intent and the best-fitting command is
-re-matched and re-rendered. If no skill confidently matches the intent, a
-warning is emitted and the user is prompted to refine or clarify it.
+`npm start build` in `plugin/` -- and generates *all* adequately fitting
+`/ase:ase-xxx-xxx` commands that realize the intent, ranked best-fitting
+first and limited to the eight best ones. The fit is judged primarily
+against each skill's `SCENARIOS` ("You want ...") and `DESCRIPTION`
+sections, and each command is complete with concrete option flags and
+positional arguments derived from the skill's `SYNOPSIS`, `OPTIONS`,
+and `ARGUMENTS`.
+
+The generated commands are presented together with a brief per-command
+rationale in an interactive dialog. The dialog lets the user *execute*
+one of the commands `C1`...`C8` (which dispatches the target skill via
+its generated arguments), *cancel* the operation, or *refine* the intent
+by typing any free-text instruction -- the instruction is folded into
+the intent and the fitting commands are re-matched and re-rendered. If
+no skill confidently matches the intent, a warning is emitted and the
+user is prompted to refine or clarify it.
 
 The skill exposes *no* option flags beyond `--help`/`-h`; it is driven
 entirely through the intent argument and the interactive dialog.
@@ -34,18 +38,25 @@ entirely through the intent argument and the interactive dialog.
 
 *intent*:
     The free-text intent to be realized. It describes *what* the user
-    wants to achieve; the skill determines *which* ASE skill and *which*
+    wants to achieve; the skill determines *which* ASE skills and *which*
     options and arguments realize it.
 
+##  SCENARIOS
+
+-   You want to know which ASE skills realize what you have in mind
+-   You want free text turned into concrete slash commands with options
+-   You want all matching commands proposed, ranked best-fitting first
+-   You want to refine an intent in a dialog until a command fits
+
 ##  EXAMPLES
 
-Route an intent to the matching command and pick from the dialog:
+Route an intent to the matching commands and pick one from the dialog:
 
 ```text
 ❯ /ase-help-intent lint the TypeScript sources for high-severity issues only
 ```
 
-Route a planning intent to the matching command:
+Route a planning intent to the matching commands:
 
 ```text
 ❯ /ase-help-intent explain how the authentication module works

package/plugin/skills/ase-help-skill/help.md

@@ -46,6 +46,13 @@ The skill exposes *no* option flags beyond `--help`/`-h`.
     description of its purpose. If omitted, the entire skill catalog is
     listed.
 
+##  SCENARIOS
+
+-   You want the manual page of an ASE skill
+-   You want to know what a certain `ase-xxx-xxx` skill does
+-   You want a skill found by an abbreviation or a purpose description
+-   You want to browse the whole catalog of ASE skills
+
 ##  EXAMPLES
 
 Show the manual page of `ase-code-lint` via its shortest abbreviation:

package/plugin/skills/ase-meta-brainstorm/help.md

@@ -61,6 +61,14 @@ the highest-ranked option or a principled synthesis of the shortlist.
     The subject to brainstorm - a feature, component, behavior, or
     design question to explore *what* to build before *how*.
 
+##  SCENARIOS
+
+-   You want to get fresh ideas for an open-ended question
+-   You want to explore what to build before deciding how to build it
+-   You want to widen a solution space that holds a single candidate
+-   You want to get a shortlist of distinct directions with a recommendation
+-   You want to ideate on a feature, component, or design question
+
 ##  EXAMPLES
 
 Brainstorm an approach for a new feature:

package/plugin/skills/ase-meta-changelog/help.md

@@ -23,6 +23,12 @@ comma-separated *artifact class* tags out of `spec`, `arch`, `code`,
 prefix. The date in the section header is also updated to the current
 date.
 
+##  SCENARIOS
+
+-   You want the `CHANGELOG.md` brought up to date with recent commits
+-   You want changelog entries completed, consolidated, and sorted
+-   You want a tidy changelog section before a release
+
 ##  EXAMPLES
 
 Update the most recent ChangeLog section:

package/plugin/skills/ase-meta-chat/help.md

@@ -26,6 +26,12 @@ without any further interpretation.
 *query*:
     The chat message to send to the foreign LLM.
 
+##  SCENARIOS
+
+-   You want a single question answered by one specific foreign LLM
+-   You want an answer from ChatGPT, Gemini, DeepSeek, Grok, GLM, or Qwen
+-   You want a second opinion from exactly one other model, verbatim
+
 ##  EXAMPLES
 
 Ask ChatGPT a quick question:

package/plugin/skills/ase-meta-commit/help.md

@@ -18,6 +18,12 @@ the form `<type>: <summary>` where *type* is one of `FEATURE`,
 *summary* is a 60-80 character imperative-mood summary without
 trailing period or Markdown formatting.
 
+##  SCENARIOS
+
+-   You want a commit message for the currently staged changes
+-   You want a typed one-line summary derived from the staged diff
+-   You want to commit but cannot phrase what changed
+
 ##  EXAMPLES
 
 Craft a commit message for the currently staged changes:

package/plugin/skills/ase-meta-compat/help.md

@@ -54,6 +54,12 @@ The `ase-meta-compat` skill takes no arguments (besides `--help`|`-h`). It
 always runs the most rigorous self-test, with 6 *probes per category*
 (7 for *Regex Matching*), for 25 probes in total.
 
+##  SCENARIOS
+
+-   You want to know how faithfully the current model runs ASE skills
+-   You want a 0-100% compatibility rating of the LLM and its harness
+-   You want the core interpreter primitives checked before relying on ASE
+
 ##  EXAMPLES
 
 Run the compatibility self-test:

package/plugin/skills/ase-meta-config/help.md

@@ -94,6 +94,13 @@ preset-bootstrapping operation that stays a shell concern next to
     The operands of the operation: none for `list`, a dotted *key* for
     `get` and `delete`, and a dotted *key* plus a *value* for `set`.
 
+##  SCENARIOS
+
+-   You want the ASE configuration inspected or changed
+-   You want the persona, guidance, or boxing switched for a session
+-   You want a configuration value persisted at user or project scope
+-   You want to see which scope supplies each effective value
+
 ##  EXAMPLES
 
 List all effective configuration entries:

package/plugin/skills/ase-meta-diaboli/help.md

@@ -51,6 +51,13 @@ contrarian.
     It may be technical, factual, or opinion-based; the skill attacks
     its strongest ("steelman") interpretation.
 
+##  SCENARIOS
+
+-   You want a thesis relentlessly challenged with counter-arguments
+-   You want a decision stress-tested before you commit to it
+-   You want the strongest anti-theses ranked plus a synthesis
+-   You want a devil's advocate against a claim or plan
+
 ##  EXAMPLES
 
 Challenge a technology-choice claim:

package/plugin/skills/ase-meta-diff/help.md

@@ -73,6 +73,13 @@ giving a visual sense of *what a diff endangers* before a deeper review.
     *reverse dependencies* - plus a *brief impact summary* of what
     depends on the touched code and how far the blast reaches.
 
+##  SCENARIOS
+
+-   You want a readable, intent-grouped summary of the staged changes
+-   You want a diff checked for scope creep and stray debug leftovers
+-   You want a graded risk report of a change before committing
+-   You want a blast-radius map of what depends on the touched code
+
 ##  EXAMPLES
 
 Summarize the currently staged changes:

package/plugin/skills/ase-meta-eli5/help.md

@@ -42,6 +42,12 @@ knowledge.
     phenomenon, or any other subject; the skill explains it in a
     child-friendly way.
 
+##  SCENARIOS
+
+-   You want a topic explained so simply a child could follow
+-   You want a jargon-free summary with an everyday analogy
+-   You want a simple explanation grounded in current Internet/Web facts
+
 ##  EXAMPLES
 
 Explain a technical concept from model knowledge:

package/plugin/skills/ase-meta-evaluate/help.md

@@ -31,6 +31,13 @@ all alternatives rate negatively.
     A description of what should be evaluated, including the
     alternatives and, optionally, the criteria to consider.
 
+##  SCENARIOS
+
+-   You want alternatives compared and the best one named
+-   You want a weighted multi-criteria decision matrix
+-   You want a defensible, criteria-based technology choice
+-   You want to know which option out of a list wins and by how much
+
 ##  EXAMPLES
 
 Compare logging libraries for a TypeScript project:

package/plugin/skills/ase-meta-proximity/help.md

@@ -59,6 +59,13 @@ the `ase-meta-proximity` sub-agent before its proximity is re-determined.
     a technical concept, a phenomenon, or any other subject; the skill
     determines its parent, sibling, and child topics.
 
+##  SCENARIOS
+
+-   You want the conceptual neighborhood of a topic explored
+-   You want the parent, sibling, and child topics of a subject
+-   You want a topic taxonomy navigated interactively
+-   You want related topics grounded in Internet/Web facts
+
 ##  EXAMPLES
 
 Determine the proximity of a topic from model knowledge:

package/plugin/skills/ase-meta-quorum/help.md

@@ -40,6 +40,12 @@ complete, unmodified individual responses.
 *question*:
     The question to ask all available AIs.
 
+##  SCENARIOS
+
+-   You want a consensus answer from multiple AIs
+-   You want to know whether different models agree on a question
+-   You want the individual responses plus a consensus rate
+
 ##  EXAMPLES
 
 Ask the quorum a factual question:

package/plugin/skills/ase-meta-quotes/help.md

@@ -90,6 +90,13 @@ the attribution of the quote.
     search query and as the keyword set of the *literalness* dimension of
     the matrix.
 
+##  SCENARIOS
+
+-   You want quotes, sayings, or aphorisms on a topic
+-   You want citations arranged by attribution and literalness
+-   You want quote wording and attribution verified against the Web
+-   You want the quote harvest widened to related topics
+
 ##  EXAMPLES
 
 Find quotes from model knowledge:

package/plugin/skills/ase-meta-review/help.md

@@ -69,6 +69,13 @@ before it is committed.
 The `ase-meta-review` skill takes no positional arguments; it always
 reviews the currently *staged* Git changes.
 
+##  SCENARIOS
+
+-   You want the staged changes reviewed like a human reviewer would
+-   You want an approve or reject verdict before committing
+-   You want severity-tagged, line-cited findings on a diff
+-   You want a holistic judgment instead of a mechanical lint
+
 ##  EXAMPLES
 
 Review the currently staged changes before committing:

package/plugin/skills/ase-meta-search/help.md

@@ -34,6 +34,12 @@ Brave, or `WebSearch` individually.
 *query*:
     The search query to dispatch to the search services.
 
+##  SCENARIOS
+
+-   You want the Internet/Web searched for a query
+-   You want results from several search backends consolidated
+-   You want current facts which model knowledge may lack
+
 ##  EXAMPLES
 
 Search the Web for a topic across all backends:

package/plugin/skills/ase-meta-steelman/help.md

@@ -68,6 +68,12 @@ cheerleading.
     It may be technical, factual, or opinion-based; the skill defends
     its strongest ("steelman") interpretation.
 
+##  SCENARIOS
+
+-   You want the strongest possible case built for a thesis
+-   You want supporting arguments ranked plus a fortification
+-   You want a charitable defense before pitching a decision
+
 ##  EXAMPLES
 
 Strengthen a technology-choice claim:

package/plugin/skills/ase-meta-why/help.md

@@ -56,6 +56,13 @@ source code changes.
     whose root cause should be investigated. The skill implicitly
     prepends "Why" to form the initial question.
 
+##  SCENARIOS
+
+-   You want the root cause of a problem, not just its symptom
+-   You want a Five-Whys causality chain walked for an observed fact
+-   You want candidate causes weighed with backtracking
+-   You want a solution proposed which addresses the root cause
+
 ##  EXAMPLES
 
 Investigate the root cause of a build failure:

package/plugin/skills/ase-meta-workflow/help.md

@@ -96,6 +96,13 @@ agent tool:
     dispatched "in a sub-agent", or naming concrete `ase-xxx-xxx` skills
     steers the derived structure accordingly.
 
+##  SCENARIOS
+
+-   You want a recurring multi-step procedure automated as its own skill
+-   You want several ASE skills orchestrated or chained into one command
+-   You want sequential and parallel actions woven into a generated skill
+-   You want a new agent tool skill generated in the style of ASE skills
+
 ##  EXAMPLES
 
 Generate a project-local skill which analyzes the code and then resolves

package/plugin/skills/ase-spec-edit/help.md

@@ -104,6 +104,13 @@ timestamp refreshed.
     skill asks for the query via an interactive `Edit Query` dialog,
     carrying the fixed `STOP SKILL` option plus free-text input.
 
+##  SCENARIOS
+
+-   You want the specification edited in one shot from a description
+-   You want `SPEC` changes without the task plan ceremony
+-   You want the query stress-tested by grilling before the spec is edited
+-   You want specification edits validated by SpecBook linting
+
 ##  EXAMPLES
 
 Edit in one shot, without any questions or validation:

package/plugin/skills/ase-sync-export/SKILL.md

@@ -104,8 +104,9 @@ Procedure
         `ase_specbook_export(output: "<output/>")` tool of the `ase` MCP
         server, which infers the format from the `[<format>:]<file>`
         entry, writes the rendering to the file, and returns a
-        confirmation `text` carrying the written byte size. Do not
-        output anything.
+        confirmation `text` carrying the written byte size plus a
+        `notices` array of environment notices. Set <notices/> to the
+        *distinct* notices of all calls. Do not output anything.
 
     2.  Report the exported files with the following <template/>,
         listing one bullet line per written file (with <file/> its
@@ -118,7 +119,21 @@ Procedure
         [...]
         </template>
 
-    3.  Finally, give the closing hints by expanding the following
+    3.  <if condition="<notices/> is not empty">
+
+        Report the environment notices *verbatim* with the following
+        <template/>, listing one bullet line per notice:
+
+        <template>
+        <ase-tpl-bullet-signal/> **ENVIRONMENT NOTICES**:
+
+        -   <notice/>
+        [...]
+        </template>
+
+        </if>
+
+    4.  Finally, give the closing hints by expanding the following
         (which, depending on the configured <ase-guidance-level/>, may
         each expand into nothing and hence emit no output at all):
 

package/plugin/skills/ase-sync-export/help.md

@@ -29,6 +29,15 @@ search, and light/dark theme), `pdf` (paginated print document), or `md`
 filename extension unless it is explicitly given as a prefix. The
 standard output sentinel `-` is not supported.
 
+The `pdf` format is the only one with an external prerequisite: it
+prints the rendering through a Chromium-class browser. Neither `npm
+install -g @rse/ase` nor `ase setup install` downloads one, so unless a
+*Google Chrome* is installed system-wide, the Playwright Chromium has to
+be fetched once via `npx playwright install chromium`. Without any such
+browser the export fails up-front, before the specification is parsed,
+and reports that very command; when it falls back onto a system-installed
+*Google Chrome*, the skill reports this as an environment notice.
+
 ##  OPTIONS
 
 `--output`|`-o` *output*[,...]:
@@ -37,6 +46,12 @@ standard output sentinel `-` is not supported.
     single HTML rendering `index.html` inside the `SPEC` base directory
     (e.g. `docs/specbook/index.html`).
 
+##  SCENARIOS
+
+-   You want the specification rendered as HTML, PDF, Markdown, or JSON
+-   You want a shareable, ready-to-consume export of the `SPEC` artifacts
+-   You want the specification validated and then materialized into files
+
 ##  EXAMPLES
 
 Export the specification to its default HTML rendering:

package/plugin/skills/ase-sync-import/help.md

@@ -57,6 +57,13 @@ at most three rounds; any remaining diagnostics are surfaced.
     from (e.g. a file path, directory, URL, or pasted text). The skill
     errors out on an empty hint.
 
+##  SCENARIOS
+
+-   You want external sources brought into the project artifacts
+-   You want a foreign document, URL, or pasted text reflected in the `SPEC`
+-   You want requirements from outside imported into a task plan
+-   You want legacy material ingested into the specification
+
 ##  EXAMPLES
 
 Import a foreign requirements document into the specification:

package/plugin/skills/ase-sync-reconcile/help.md

@@ -62,6 +62,13 @@ in at most three rounds; any remaining diagnostics are surfaced.
     target artifacts, or the aspects of those artifacts to take into
     account during reconciliation.
 
+##  SCENARIOS
+
+-   You want one artifact set updated to reflect another one
+-   You want code and docs aligned with the specification
+-   You want the specification recovered from the code base
+-   You want spec and code bidirectionally synchronized
+
 ##  EXAMPLES
 
 Reconcile the code and documentation

package/plugin/skills/ase-task-condense/help.md

@@ -57,6 +57,12 @@ After condensing, the user is asked whether to stop or hand off to
     The unique identifier of the task whose plan should be condensed.
     If omitted, the *current* task id is used.
 
+##  SCENARIOS
+
+-   You want a task plan shortened without losing meaning
+-   You want plan wording compressed for faster reading
+-   You want fluff removed from a plan while keeping all semantics
+
 ##  EXAMPLES
 
 Condense the current task plan:

package/plugin/skills/ase-task-delete/help.md

@@ -23,6 +23,12 @@ switched back to `default`.
     The unique identifier of the task plan to delete. If omitted,
     the current task id is used.
 
+##  SCENARIOS
+
+-   You want a task plan removed
+-   You want a finished or obsolete task cleared
+-   You want a plan discarded, falling back to the default task
+
 ##  EXAMPLES
 
 Delete the current task plan:

package/plugin/skills/ase-task-dissect/help.md

@@ -76,6 +76,13 @@ The epic plan itself always stays *untouched*.
     A free-text hint telling *how* the epic should be split. If omitted,
     the parts are derived from the plan alone.
 
+##  SCENARIOS
+
+-   You want a large task plan split into cohesive sub-tasks
+-   You want an epic decomposed into independently implementable parts
+-   You want a preview of how a plan would be divided
+-   You want each part of a plan persisted as its own separate plan
+
 ##  EXAMPLES
 
 Dissect the current task plan:

package/plugin/skills/ase-task-edit/help.md

@@ -65,6 +65,13 @@ for the changed plan.
     Optionally, *instruction* either gives instructions for creating a
     new task or gives instructions for refining an existing task.
 
+##  SCENARIOS
+
+-   You want a task planned through chat-driven refinement
+-   You want a plan created or refined round by round
+-   You want a plan iterated on before implementing it
+-   You want plan refinement with hand-off to preflight or implementation
+
 ##  EXAMPLES
 
 Edit the current task:

package/plugin/skills/ase-task-grill/help.md

@@ -73,6 +73,13 @@ offered a hand-off to editing, implementation, or preflight.
     The skill accepts *only* an optional *id* argument and never a
     free-text instruction.
 
+##  SCENARIOS
+
+-   You want to be interviewed about your plan until it is watertight
+-   You want the open decisions of a plan resolved question by question
+-   You want fuzzy language and conflicts flushed out of a plan
+-   You want shared understanding before the implementation starts
+
 ##  EXAMPLES
 
 Grill the current task plan:

package/plugin/skills/ase-task-id/help.md

@@ -22,6 +22,12 @@ task id via the `ase_task_id` MCP tool.
     The new task id to activate. If omitted, the currently active
     task id is reported.
 
+##  SCENARIOS
+
+-   You want to know which task is currently active
+-   You want the session switched to another task
+-   You want to work on a certain task
+
 ##  EXAMPLES
 
 Show the current task id:

package/plugin/skills/ase-task-implement/help.md

@@ -79,6 +79,13 @@ delete the task plan, unless `--next` pre-selects this choice.
     The unique identifier of the task whose plan should be
     implemented. If omitted, the *current* task id is used.
 
+##  SCENARIOS
+
+-   You want a task plan turned into actual changes
+-   You want the planned change set applied and verified
+-   You want a reviewed implementation draft applied 1:1
+-   You want the implementation isolated in a Git worktree
+
 ##  EXAMPLES
 
 Implement the current task plan:

package/plugin/skills/ase-task-list/help.md

@@ -54,6 +54,12 @@ REJECTED  DEFERRED  BLOCKED  CANCELLED
     `COMPLETED,CANCELLED`; pass `--exclude none` to suppress the
     default and list task plans in every state.
 
+##  SCENARIOS
+
+-   You want an overview of all task plans
+-   You want task ids listed with status and timestamps
+-   You want the unfinished or in-progress tasks found
+
 ##  EXAMPLES
 
 List all unfinished task ids:

package/plugin/skills/ase-task-preflight/help.md

@@ -55,6 +55,13 @@ unless `--next` pre-selects this choice.
     The unique identifier of the task whose plan should be
     preflighted. If omitted, the *current* task id is used.
 
+##  SCENARIOS
+
+-   You want a dry-run of a plan's implementation
+-   You want the change set previewed as a unified diff before applying
+-   You want an implementation draft to review before committing to it
+-   You want a plan test-driven without touching any source files
+
 ##  EXAMPLES
 
 Preflight the current task plan:

package/plugin/skills/ase-task-reboot/help.md

@@ -43,6 +43,12 @@ unless `--next` pre-selects this choice.
     The unique identifier of the task whose plan should be rebooted.
     If omitted, the *current* task id is used.
 
+##  SCENARIOS
+
+-   You want a task plan re-created from scratch
+-   You want a fresh plan from the original WHAT and WHY
+-   You want planning restarted after a plan degraded
+
 ##  EXAMPLES
 
 Reboot the current task plan:

package/plugin/skills/ase-task-rename/help.md

@@ -24,6 +24,12 @@ task id is automatically switched to *new*.
     If only one token is given, *old* defaults to the current
     task id.
 
+##  SCENARIOS
+
+-   You want a task plan renamed
+-   You want a task given a better id
+-   You want the current task moved to a new id
+
 ##  EXAMPLES
 
 Rename the current task:

package/plugin/skills/ase-task-view/help.md

@@ -36,6 +36,12 @@ the plan in full, without any truncation or summarization.
     The unique identifier of the task plan to view. If omitted,
     the current task id is used.
 
+##  SCENARIOS
+
+-   You want the current or a given task plan shown
+-   You want a plan rendered before deciding the next steps
+-   You want a plan inspected including its implementation draft
+
 ##  EXAMPLES
 
 View the current task plan: