@rse/ase 0.9.48 → 0.9.49

package/dst/ase-config.js

@@ -22,7 +22,8 @@ export const projectClassification = {
 };
 /*  agent classification taxonomy  */
 export const agentClassification = {
-    persona: ["writer", "engineer", "journalist", "telegrapher", "caveman"]
+    persona: ["writer", "engineer", "journalist", "telegrapher", "caveman"],
+    guidance: ["none", "minimal", "normal", "verbose"]
 };
 /*  classification presets  */
 export const projectClassificationPresets = {
@@ -41,6 +42,7 @@ export const projectClassificationPresets = {
     default: {
         "agent.task": "default",
         "agent.persona": "engineer",
+        "agent.guidance": "normal",
         "project.id": "example",
         "project.name": "Example Project",
         "project.boxing": "white",
@@ -190,6 +192,7 @@ export const configSchema = v.nullish(v.strictObject({
     })),
     agent: v.optional(v.strictObject({
         persona: v.optional(v.picklist(agentClassification.persona)),
+        guidance: v.optional(v.picklist(agentClassification.guidance)),
         task: v.optional(v.pipe(v.string(), v.minLength(1))),
         skill: v.optional(v.pipe(v.string(), v.minLength(1)))
     }))
@@ -768,5 +771,46 @@ export class ConfigMCP {
                 return mcpToolError(err);
             }
         });
+        /*  config list  */
+        mcp.registerTool("ase_config_list", {
+            title: "ASE config list",
+            description: "List all effective configuration entries of the layered configuration, " +
+                "cascading through the default/user/project/task/session chain up to and " +
+                "including the requested `scope`. Returns an `entries` array (in lexicographic " +
+                "`key` order) where each item has the dotted `key`, its effective `value`, and " +
+                "the `scope` label (\"default\", \"user\", \"project\", \"task:<id>\", or " +
+                "\"session:<id>\") that supplied it. For overlapping keys only the value of the " +
+                "strongest scope is reported.",
+            inputSchema: {
+                scope: z.string()
+                    .describe("scope chain (e.g. \"session:<id>\", \"task:<id>\", \"project\", \"user\")")
+            },
+            outputSchema: {
+                entries: z.array(z.object({
+                    key: z.string().describe("dotted configuration key"),
+                    value: z.string().describe("effective configuration value"),
+                    scope: z.string().describe("scope label which supplied the value")
+                })).describe("all effective configuration entries in lexicographic key order")
+            }
+        }, async (args) => {
+            try {
+                const scope = parseScope(args.scope);
+                const cfg = new Config("config", configSchema, this.log, scope);
+                cfg.read();
+                const entries = cfg.entries().map((e) => ({
+                    key: e.key,
+                    value: String(isScalar(e.value) ? e.value.value : e.value),
+                    scope: Config.scopeLabel(e.scope)
+                }));
+                const result = { entries };
+                return {
+                    structuredContent: result,
+                    content: [{ type: "text", text: JSON.stringify(result) }]
+                };
+            }
+            catch (err) {
+                return mcpToolError(err);
+            }
+        });
     }
 }

package/dst/ase-guidance.js

@@ -0,0 +1,89 @@
+/*
+**  Agentic Software Engineering (ASE)
+**  Copyright (c) 2025-2026 Dr. Ralf S. Engelschall <rse@engelschall.com>
+**  Licensed under Apache 2.0 <https://spdx.org/licenses/Apache-2.0>
+*/
+import { isScalar } from "yaml";
+import { z } from "zod";
+import { Config, configSchema, parseScope, agentClassification } from "./ase-config.js";
+/*  reusable functionality: ASE agent guidance level get/set  */
+export class Guidance {
+    /*  allowed guidance level values  */
+    static levels = agentClassification.guidance;
+    /*  get the effective guidance level for an optional session;
+        returns the default "normal" if nothing is configured  */
+    static get(log, session) {
+        const scope = parseScope(session !== undefined ? `session:${session}` : undefined);
+        const cfg = new Config("config", configSchema, log, scope);
+        cfg.read();
+        const val = cfg.get("agent.guidance");
+        if (val === undefined)
+            return "normal";
+        const level = String(isScalar(val) ? val.value : val);
+        return Guidance.levels.find((l) => l === level) ?? "normal";
+    }
+    /*  set the guidance level on the strongest scope of an optional session  */
+    static set(log, level, session) {
+        const scope = parseScope(session !== undefined ? `session:${session}` : undefined);
+        const cfg = new Config("config", configSchema, log, scope);
+        cfg.lock(() => {
+            cfg.read();
+            cfg.set("agent.guidance", level);
+            cfg.write();
+        });
+    }
+}
+/*  MCP registration entry point for guidance tools  */
+export default class GuidanceMCP {
+    log;
+    constructor(log) {
+        this.log = log;
+    }
+    register(mcp) {
+        mcp.registerTool("ase_guidance", {
+            title: "ASE guidance level get/set",
+            description: "Get or set the active ASE agent guidance `level`. " +
+                "If `level` is provided, it sets the guidance level, " +
+                "otherwise it returns the current guidance `level`. " +
+                "If `session` is provided, the operation is scoped to that session, " +
+                "otherwise it operates on the strongest/closest scope (user/project cascade). " +
+                "The guidance level controls the amount of unsolicited help hints -- " +
+                "pointers to the available ASE skills, their options, and the recommended " +
+                "next operations -- the agent emits. " +
+                "Allowed levels: \"none\" (no help hints at all), " +
+                "\"minimal\" (the single most essential help hint only), " +
+                "\"normal\" (the essential help hints only), " +
+                "\"verbose\" (all available help hints).",
+            inputSchema: {
+                level: z.enum(Guidance.levels).optional()
+                    .describe("guidance level to set; if omitted, the current guidance level is returned"),
+                session: z.string().regex(/^[A-Za-z0-9._-]+$/).optional()
+                    .describe("session identifier (allowed characters: A-Z, a-z, 0-9, '.', '_', '-'); " +
+                    "if omitted, the operation is not scoped to a specific session")
+            }
+        }, async (args) => {
+            try {
+                if (args.level !== undefined) {
+                    Guidance.set(this.log, args.level, args.session);
+                    const where = args.session !== undefined ?
+                        ` for session "${args.session}"` : "";
+                    const msg = `OK: set agent.guidance to "${args.level}"${where}`;
+                    return {
+                        content: [{ type: "text", text: msg }]
+                    };
+                }
+                const text = Guidance.get(this.log, args.session);
+                return {
+                    content: [{ type: "text", text }]
+                };
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                return {
+                    isError: true,
+                    content: [{ type: "text", text: `ERROR: ${message}` }]
+                };
+            }
+        });
+    }
+}

package/dst/ase-hook.js

@@ -249,8 +249,9 @@ export default class HookCommand {
             const val = cfg.get(key);
             return typeof val === "string" ? val : (process.env[envVar] ?? dflt);
         };
-        /*  determine agent persona style and project boxing transparency  */
+        /*  determine agent persona style, agent guidance level, and project boxing transparency  */
         const persona = setting("agent.persona", "ASE_PERSONA_STYLE", "engineer");
+        const guidance = setting("agent.guidance", "ASE_GUIDANCE_LEVEL", "normal");
         const boxing = setting("project.boxing", "ASE_PROJECT_BOXING", "white");
         /*  determine headless mode  */
         const headless = (process.env.ASE_HEADLESS ?? "false") === "true" ? "true" : "false";
@@ -281,6 +282,7 @@ export default class HookCommand {
                 `<ase-version-hint>${versionHint}</ase-version-hint>\n` +
                 `<ase-plugin-root>${pluginRoot}</ase-plugin-root>\n` +
                 `<ase-persona-style>${persona}</ase-persona-style>\n` +
+                `<ase-guidance-level>${guidance}</ase-guidance-level>\n` +
                 `<ase-user-id>${userId}</ase-user-id>\n` +
                 `<ase-project-id>${projectId}</ase-project-id>\n` +
                 `<ase-project-boxing>${boxing}</ase-project-boxing>\n` +
@@ -295,11 +297,18 @@ export default class HookCommand {
             agent harness, independent of any model decision, so it is
             guaranteed to appear once in every non-headless session;
             Anthropic Claude Code CLI and OpenAI Codex CLI surface a top-level
-            "systemMessage" field for this -- GitHub Copilot CLI has no equivalent)  */
-        const banner = `\n⧉ ASE: ⎈ version: ${versionCurrentPlugin}${versionHint !== "" ? " " + versionHint.replaceAll(/\*/g, "") : ""}` +
+            "systemMessage" field for this -- GitHub Copilot CLI has no equivalent);
+            the trailing help hint is emitted only if the guidance level asks for it  */
+        const banner = "\n" +
+            `\n⧉ ASE: ⎈ version: ${versionCurrentPlugin}${versionHint !== "" ? " " + versionHint.replaceAll(/\*/g, "") : ""}` +
             `\n⧉ ASE: ※ user: ${userId}, ⚑ project: ${projectId}` +
             `\n⧉ ASE: ◉ task: ${taskId}, ⏻ session: ${sessionId}` +
-            `\n⧉ ASE: ☯ persona: ${persona}, ▢ boxing: ${boxing}`;
+            `\n⧉ ASE: ☯ persona: ${persona}, ▶ guidance: ${guidance}, ▢ boxing: ${boxing}` +
+            (guidance === "normal" || guidance === "verbose" ?
+                "\n" +
+                    "\n⧉ ASE: ▷ hint: use \"/ase-help-intent <intent-description>\" for skill command proposal" +
+                    "\n⧉ ASE: ▷ hint: use \"/ase-help-skill [<skill-name>]\" for skill catalog or skill manpage" : "") +
+            "\n";
         /*  inject markdown into session context.
             Anthropic Claude Code CLI and OpenAI Codex CLI expect the context nested in
             "hookSpecificOutput"; GitHub Copilot CLI expects a flat top-level
@@ -314,8 +323,10 @@ export default class HookCommand {
         };
         /*  attach the deterministic banner as a top-level "systemMessage"
             (only for the harnesses that support it and only when not
-            running headless -- mirroring the constitution box condition)  */
-        if ((tool === "claude" || tool === "codex") && headless !== "true")
+            running headless -- complementing the constitution box condition,
+            which covers exactly the remaining harness GitHub Copilot CLI
+            by letting the model emit the banner itself)  */
+        if ((tool === "claude" || tool === "codex") && headless !== "true" && guidance !== "none")
             payload.systemMessage = banner;
         await writeStdout(JSON.stringify(payload));
         return 0;

package/dst/ase-service.js

@@ -22,7 +22,6 @@ import { TaskMCP } from "./ase-task.js";
 import { MarkdownMCP } from "./ase-markdown.js";
 import { ArtifactMCP } from "./ase-artifact.js";
 import { KVMCP } from "./ase-kv.js";
-import PersonaMCP from "./ase-persona.js";
 import { TimestampMCP } from "./ase-timestamp.js";
 import { GetoptMCP } from "./ase-getopt.js";
 import { SkillsMCP } from "./ase-skills.js";
@@ -243,7 +242,6 @@ export default class ServiceCommand {
             new MarkdownMCP().register(mcp);
             new ArtifactMCP(this.log).register(mcp);
             new KVMCP().register(mcp);
-            new PersonaMCP(this.log).register(mcp);
             new TimestampMCP().register(mcp);
             new GetoptMCP().register(mcp);
             new SkillsMCP().register(mcp);

package/dst/ase-setup.js

@@ -575,7 +575,7 @@ export default class SetupCommand {
     statuslineFormatDflt = [
         "<blue>%u</blue> <red>%p</red> <black>%T</black> %s",
         "%m %e %t",
-        "%P %c"
+        "%P %h %c"
     ];
     /*  resolve the tool settings file for a given installation scope  */
     statuslineSettingsFile(tool, scope) {
@@ -607,8 +607,9 @@ export default class SetupCommand {
     }
     /*  build the "ase statusline ..." command string from the activate
         options and the effective format lines  */
-    statuslineCommand(opts, format) {
-        const parts = ["ase", "statusline", "-w", String(opts.width), "-m", String(opts.margin)];
+    statuslineCommand(tool, opts, format) {
+        const parts = ["ase", "statusline", "--tool", tool, "-w", String(opts.width), "-m", String(opts.margin),
+            "-p", String(opts.padding)];
         if (!opts.icons)
             parts.push("--no-icons");
         if (!opts.labels)
@@ -699,7 +700,7 @@ export default class SetupCommand {
         this.requireStatuslineTool(tool);
         this.requireStatuslineScope(tool, scope);
         const file = this.statuslineSettingsFile(tool, scope);
-        const command = this.statuslineCommand(opts, format);
+        const command = this.statuslineCommand(tool, opts, format);
         const root = await this.statuslineReadAst(file);
         const existing = this.statuslineFindMember(root);
         if (existing !== undefined) {
@@ -923,10 +924,11 @@ export default class SetupCommand {
             .option("-s, --scope <scope>", "target scope (\"user\", \"project\", or \"local\")", "user")
             .option("-w, --width <n>", "force terminal width to <n> characters (0 = auto-detect via /dev/tty)", parseNonNeg("width"), 0)
             .option("-m, --margin <n>", "reduce maximum used terminal width by <n> characters on each side", parseNonNeg("margin"), 2)
+            .option("-p, --padding <n>", "pad each rendered line with <n> spaces on each side", parseNonNeg("padding"), 0)
             .option("--no-icons", "disable icons in placeholder rendering")
             .option("--no-labels", "disable labels in front of bold values")
             .action(async (format, opts) => {
-            process.exit(await this.doStatuslineActivate(this.parseTool(opts.tool), this.parseScope(opts.scope), { width: opts.width, margin: opts.margin, icons: opts.icons, labels: opts.labels }, format ?? []));
+            process.exit(await this.doStatuslineActivate(this.parseTool(opts.tool), this.parseScope(opts.scope), { width: opts.width, margin: opts.margin, padding: opts.padding, icons: opts.icons, labels: opts.labels }, format ?? []));
         });
         /*  register CLI sub-command "ase setup statusline deactivate"  */
         statuslineCmd

package/dst/ase-statusline.js

@@ -189,9 +189,10 @@ export default class StatuslineCommand {
             .option("-t, --tool <tool>", "target tool (\"claude\" or \"copilot\"; \"codex\" is unsupported)", toolDflt)
             .option("-w, --width <n>", "force terminal width to <n> characters (0 = auto-detect via /dev/tty)", parseInteger("--width"), 0)
             .option("-m, --margin <n>", "reduce maximum used terminal width by <n> characters on each side", parseInteger("--margin"), 2)
+            .option("-p, --padding <n>", "pad each rendered line with <n> spaces on each side", parseInteger("--padding"), 0)
             .option("--no-icons", "disable icons in placeholder rendering")
             .option("--no-labels", "disable labels in front of bold values")
-            .argument("[lines...]", "one or more template lines with %u %p %T %s %m %e %t %O %P %c %C %a %r " +
+            .argument("[lines...]", "one or more template lines with %u %p %T %s %m %e %t %O %P %h %c %C %a %r " +
             "%S %D %W %Q %H %X %b %g %G %d %M %V placeholders and <color>...</color> markup " +
             "(color: black, red, green, yellow, blue, magenta, cyan, white, default) " +
             "(default: single line \"%m %e %t\")")
@@ -220,9 +221,11 @@ export default class StatuslineCommand {
                 && typeof data.cwd === "string" && data.cwd !== "") {
                 data.workspace = { ...(data.workspace ?? {}), current_dir: data.cwd };
             }
-            /*  determine effective terminal width and budget  */
+            /*  determine effective terminal width and budget
+                (the padding spaces occupy terminal columns, too,
+                so they have to be subtracted from the budget)  */
             const width = opts.width > 0 ? opts.width : detectTermWidth();
-            const budget = width > 0 ? width - 2 * opts.margin : 0;
+            const budget = width > 0 ? width - 2 * (opts.margin + opts.padding) : 0;
             /*  shared output state and append helper with auto-wrap;
                 the helper itself strips ANSI CSI escape sequences to
                 measure the raw visible width of the chunk  */
@@ -264,20 +267,24 @@ export default class StatuslineCommand {
             const getCfg = memoize(() => {
                 let taskId = process.env.ASE_TASK_ID ?? "";
                 let persona = process.env.ASE_PERSONA_STYLE ?? "";
+                let guidance = process.env.ASE_GUIDANCE_LEVEL ?? "";
                 try {
                     const cfg = new Config("config", configSchema, this.log, parseScope(`session:${getSession()}`));
                     cfg.read("lenient");
                     const t = String(cfg.get("agent.task") ?? "").trim();
                     const p = String(cfg.get("agent.persona") ?? "").trim();
+                    const g = String(cfg.get("agent.guidance") ?? "").trim();
                     if (t !== "")
                         taskId = t;
                     if (p !== "")
                         persona = p;
+                    if (g !== "")
+                        guidance = g;
                 }
                 catch (_e) {
                     /*  cascade unavailable; keep env-var fallbacks  */
                 }
-                return { taskId, persona };
+                return { taskId, persona, guidance };
             });
             const getGit = memoize(() => probeGit(data.workspace?.current_dir ?? ""));
             const getMem = memoize(() => probeMemory());
@@ -323,6 +330,11 @@ export default class StatuslineCommand {
                     if (persona !== "")
                         emit(`${prefix("☯", "persona")}${c.bold(persona)}`);
                 },
+                h: () => {
+                    const { guidance } = getCfg();
+                    if (guidance !== "")
+                        emit(`${prefix("▶", "guidance")}${c.bold(guidance)}`);
+                },
                 /*  ==== CONTEXT ====  */
                 c: () => {
                     const pct = Math.min(100, Math.max(0, Math.floor(data.context_window?.used_percentage ?? 0)));
@@ -462,6 +474,18 @@ export default class StatuslineCommand {
                 out += "\n";
                 col = 0;
             }
+            /*  optionally pad all non-empty lines with spaces on both sides
+                (the trailing empty chunk after the final line break and any
+                intentionally empty line are left untouched, so that no
+                whitespace-only line is produced)  */
+            if (opts.padding > 0) {
+                const pad = " ".repeat(opts.padding);
+                out = out.split("\n").map((line) => line !== "" ? `${pad}${line}${pad}` : line).join("\n");
+                /*  for Copilot, prefix with a zero-width non-breaking space
+                    to prevent the first line to be unindented  */
+                if (tool === "copilot")
+                    out = "\u200B" + out;
+            }
             /*  send output  */
             await writeStdout(out);
             /*  optionally publish task id to the calling tmux pane as a per-pane user

package/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "https://ase.tools",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "https://github.com/rse/ase/issues" },
-    "version":                              "0.9.48",
+    "version":                              "0.9.49",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",

package/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.48",
+    "version":     "0.9.49",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.48",
+    "version":     "0.9.49",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/.github/plugin/plugin.json

@@ -1,6 +1,6 @@
 {
     "name":        "ase",
-    "version":     "0.9.48",
+    "version":     "0.9.49",
     "description": "Agentic Software Engineering (ASE)",
     "keywords":    [ "agentic", "software", "engineering" ],
     "homepage":    "https://ase.tools",

package/plugin/meta/ase-common-task.md

@@ -45,6 +45,15 @@ Task Skill Common Steps
     <template>
     ⧉ **ASE**: ☻ skill: **<arg1/>**, ▶ ERROR: expected single `[<id>]` argument
     </template>
+
+    Directly *after* this error <template/>, and *before* stopping,
+    give the corrective hint by expanding the following (which,
+    depending on the configured <ase-guidance-level/>, may expand into
+    nothing and hence emit no output at all):
+
+    <ase-tpl-hint level="verbose">
+    Run `/<arg1/> --help` for the accepted arguments of this skill, or use `/ase-help-intent` to have a fitting command proposed for a free-text intent.
+    </ase-tpl-hint>
     </elseif>
 
 </define>

package/plugin/meta/ase-constitution.md

@@ -6,17 +6,28 @@ You are an expert-level AI coding assistant.
 You have the **Agentic Software Engineering (ASE)** companion toolkit enabled,
 which boosts you to an expert-level Software Engineering AI agent.
 
-If ((<ase-agent-tool/> is equal to `codex`) *AND* (<ase-headless/> is empty
-or not set)) you *MUST* output the following <template/> *exactly once*
-as the very *first* thing in your *first* response of this session --
-*before* any other text, *before* any tool call, and *before* entering
-any skill flow:
+If ((<ase-agent-tool/> is equal to `copilot`) *AND* (<ase-headless/> is empty
+or not set) *AND* (<ase-guidance-level/> is not equal to `none`)) you *MUST* output
+the following <template/> *exactly once* as the very *first* thing in
+your *first* response of this session -- *before* any other text,
+*before* any tool call, and *before* entering any skill flow:
 
 <template>
 ⧉ **ASE**: ⎈ version: **<ase-version/>** <ase-version-hint/>
 ⧉ **ASE**: ※ user: **<ase-user-id/>**, ⚑ project: **<ase-project-id/>**
 ⧉ **ASE**: ◉ task: **<ase-task-id/>**, ⏻ session: **<ase-session-id/>**
-⧉ **ASE**: ☯ persona: **<ase-persona-style/>**, ▢ boxing: **<ase-project-boxing/>**
+⧉ **ASE**: ☯ persona: **<ase-persona-style/>**, ▶ guidance: **<ase-guidance-level/>**, ▢ boxing: **<ase-project-boxing/>**
+</template>
+
+If ((<ase-agent-tool/> is equal to `copilot`) *AND* (<ase-headless/> is
+empty or not set) *AND* (<ase-guidance-level/> is equal to `normal` or
+`verbose`)) you *MUST* output the following <template/> *exactly once*
+as the very *second* thing in your *first* response of this session,
+too:
+
+<template>
+⧉ **ASE**: ▷ hint: use "/ase-help-intent *intent-description*" for skill command proposal
+⧉ **ASE**: ▷ hint: use "/ase-help-skill [*skill-name*]" for skill catalog or skill manpage
 </template>
 
 Prohibitions

package/plugin/meta/ase-getopt.md

@@ -76,6 +76,15 @@ set placeholders into the context as a side-effect.
     ⧉ **ASE**: ✪ skill: **<getopt-skill/>**, ▶ ERROR: option parsing failed: **<text/>**
     </template>
 
+    Directly *after* this error <template/>, and *before* stopping, give
+    the corrective hint by expanding the following (which, depending on
+    the configured <ase-guidance-level/>, may expand into nothing and
+    hence emit no output at all):
+
+    <ase-tpl-hint level="verbose">
+    Run `/<getopt-skill/> --help` for the accepted options and arguments of this skill.
+    </ase-tpl-hint>
+
 5.  **Parsing JSON Result**:
     The tool returned a single `text` content payload containing JSON.
     Parse this JSON in <text/> now into <getopt-result/> by recognizing
@@ -100,7 +109,8 @@ set placeholders into the context as a side-effect.
     whose long name starts with `int-`.
 
 7.  **Display Results**:
-    Just output the following <template/>:
+    If <ase-guidance-level/> is equal to `normal` or `verbose`,
+    output the following <template/>:
 
     <template>
     ⧉ **ASE**: ✪ skill: **<getopt-skill/>**, ▶ options: <getopt-info/>

package/plugin/meta/ase-skill.md

@@ -214,15 +214,17 @@ Skill Identification
 
     In case <skill/> later becomes *not* empty by defining it as <skill
     name="<name/>"><body/></skill>, set <skill-name><name/></skill-name>
-    (set skill name to name), and then (but only if `$1` is *NOT* equal
-    to `-h` or `--help`) you *MUST* once output the following output
+    (set skill name to name), and then (but only if ((`$1` is *NOT* equal
+    to `-h` or `--help`) *AND* (<ase-guidance-level/> is equal to `normal`
+    or `verbose`))) you *MUST* once output the following output
     <template/>:
 
     <template>
     ⧉ **ASE**: ✪ skill: **<skill-name/>**, ✦ purpose: **<skill/>**, ▶ status: **skill started**
     </template>
 
-    Later (but only if `$1` is *NOT* equal to `-h` or `--help`), once
+    Later (but only if ((`$1` is *NOT* equal to `-h` or `--help`) *AND*
+    (<ase-guidance-level/> is equal to `normal` or `verbose`))), once
     this skill finally will stop processing, you *MUST* once output the
     following output <template/>:
 
@@ -231,7 +233,8 @@ Skill Identification
     </template>
 
 -   *IMPORTANT*: Set <objective></objective> (set to empty).
-    Then, in case <objective/> later becomes *not* empty,
+    Then, in case <objective/> later becomes *not* empty
+    (but only if <ase-guidance-level/> is equal to `normal` or `verbose`),
     you *MUST* once output the following output <template/>:
 
     <template>
@@ -292,6 +295,65 @@ Artifact Boxing Transparency
     deterministically skip or suppress and *win* over the implicit decisions
     above. Where no such branches exist, the decisions above apply.
 
+Guidance Hint Level
+-------------------
+
+-   *IMPORTANT*: The *guidance* of the agent (indicated by
+    <ase-guidance-level/> configuration) classifies how many
+    *unsolicited hints* -- pointers to the available *ASE* skills, to
+    their options, and to the recommended next operations, which the
+    user did *not* explicitly ask for -- you *MUST* emit in addition to
+    the requested result.
+
+-   *IMPORTANT*: Guidance modulates only the *hints*, per the four
+    levels below. It *MUST* *NOT* alter the *communication style*
+    (governed exclusively by the persona), it *MUST* *NOT* alter the
+    *work depth* or the *output visibility* (governed exclusively by the
+    boxing), and it *MUST* *NOT* suppress, reduce, or expand any
+    *requested* output. In particular, guidance *MUST* *NOT* apply to:
+
+    -   the *manual page* emitted for `-h`/`--help`, which is
+        explicitly requested,
+    -   the *skill catalog*, *manual page*, and *command proposal*
+        results of the `ase-help-skill` and `ase-help-intent` skills,
+        which are explicitly requested,
+    -   the *option affordance* lines of a user dialog (e.g. `Please
+        choose *one* option by typing ...`), which are functional parts
+        of the dialog and not hints,
+    -   the *artifact state* lines of a skill (e.g. `plan loaded`, `plan
+        created`, `task given`) and every `ERROR:` line, which carry
+        state rather than pointers.
+
+    The *skill identification* chrome (the `skill started`, `skill
+    finished`, and `objective` lines) is the sole exception: it is
+    *decoration* rather than result, so it is gated on `normal` and
+    `verbose` directly in the `Skill Identification` section above.
+
+-   *IMPORTANT*: Every hint carries a *level* -- `minimal`, `normal`,
+    or `verbose` -- and is emitted only if the configured
+    <ase-guidance-level/> *includes* that level:
+
+    -   If <ase-guidance-level/> is `none`:
+        -   Hints emitted: *none*
+    -   If <ase-guidance-level/> is `minimal`:
+        -   Hints emitted: `minimal` -- the *essential* pointers only,
+            i.e. those without which the just-produced result cannot be
+            consumed at all (such as the follow-up command that turns
+            persisted findings into actual changes)
+    -   If <ase-guidance-level/> is `normal`:
+        -   Hints emitted: `minimal` *and* `normal` -- additionally the
+            *canonical next step* of the finished skill
+    -   If <ase-guidance-level/> is `verbose`:
+        -   Hints emitted: `minimal`, `normal`, *and* `verbose` --
+            additionally the *unused options* of the current skill, the
+            *related* skills, and the *configuration* skills
+    -   If <ase-guidance-level/> is empty or not set:
+        -   Treat it as `normal`
+
+-   *IMPORTANT*: A hint *MUST* be emitted *exclusively* through the
+    `<ase-tpl-hint/>` template pattern below, and *never* as free-text
+    prose, so that its suppression is uniform across all skills.
+
 Template Patterns
 -----------------
 
@@ -347,6 +409,32 @@ Template Patterns
 
     </template>
 
+-   When `<ase-tpl-hint level="<level/>"><content/></ase-tpl-hint>`
+    should be expanded, first determine whether the hint passes the
+    configured guidance level (see `Guidance Hint Level` above):
+
+    -   Set <emit>false</emit>.
+    -   If <ase-guidance-level/> is `minimal` and <level/> is `minimal`,
+        set <emit>true</emit>.
+    -   If <ase-guidance-level/> is `normal` and <level/> is `minimal`
+        or `normal`, set <emit>true</emit>.
+    -   If <ase-guidance-level/> is `verbose` and <level/> is `minimal`,
+        `normal`, or `verbose`, set <emit>true</emit>.
+    -   If <ase-guidance-level/> is empty or not set, treat it as
+        `normal` and apply the corresponding decision above.
+
+    Then dispatch on <emit/>:
+
+    <if condition="<emit/> is `true`">
+        <template>
+        ⧉ **ASE**: ▷ hint [<level/>]: **<content/>**
+        </template>
+    </if>
+    <else>
+        This construct is expanded into *nothing*.
+        Do not output anything.
+    </else>
+
 -   When `<ase-tpl-boxline><line/></ase-tpl-boxline>` should be expanded, use:
 
     <if condition="<line/> is not empty">

package/plugin/package.json

@@ -6,7 +6,7 @@
     "homepage":                             "https://ase.tools",
     "repository":                           { "url": "git+https://github.com/rse/ase.git", "type": "git" },
     "bugs":                                 { "url": "https://github.com/rse/ase/issues" },
-    "version":                              "0.9.48",
+    "version":                              "0.9.49",
     "license":                              "Apache-2.0",
     "author": {
         "name":                             "Dr. Ralf S. Engelschall",

package/plugin/skills/ase-arch-analyze/SKILL.md

@@ -465,14 +465,16 @@ interface quality, quality attributes, and architecture governance.
       "<title/>: <description/>" }` entry per reported PROBLEM and one
       `{ command: "set", key: "ase-issue-T<n/>", val: "<title/>:
       <description/>" }` entry per reported TRADEOFF.
-    </step>
 
-4.  <step id="STEP 4: Give Final Hint">
-    Finally, output the following <template/> to give a final hint:
+    Finally, give a final hint by expanding the following (which,
+    depending on the configured <ase-guidance-level/>, may expand into
+    nothing and hence emit no output at all):
+
+    <ase-tpl-hint level="minimal">
+    For deeper analysis, suggestions on solution approaches and then final source code changes, use `/ase-code-resolve P{n}` or `/ase-code-resolve T{n}` in the same or even a different session.
+    </ase-tpl-hint>
 
-    <template>
-    ⧉ **ASE**: ↪ hint: **For deeper analysis, suggestions on solution approaches and then final source code changes, use `/ase-code-resolve P{n}` or `/ase-code-resolve T{n}` in the same or even a different session.**
-    </template>
     </step>
+
 </flow>