@shrkcrft/cli 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/surface/surface-layer.js

@@ -0,0 +1,11 @@
+/**
+ * Which layer of the `surface{}` composition declared a selector: the
+ * project's own `sharkcraft.config.ts`, or the active surface profile it
+ * selects. Config wins over the profile — an explicit `surface.enabled`
+ * overrides a PROFILE's deny, never a config deny.
+ */
+export var SurfaceLayer;
+(function (SurfaceLayer) {
+    SurfaceLayer["Config"] = "config";
+    SurfaceLayer["Profile"] = "profile";
+})(SurfaceLayer || (SurfaceLayer = {}));

package/dist/surface/surface-refusal-reason.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Why the surface gate refused a command (exit 78). One gate, three reasons:
+ *
+ *   - `experimental`      — an experimental command not in `surface.enabled`
+ *   - `tool-maintenance`  — a command that maintains SharkCraft itself, run
+ *                           outside SharkCraft's own repository
+ *   - `disabled`          — denied by a `surface.disabled` selector
+ *
+ * None of them is a check failure.
+ */
+export declare enum SurfaceRefusalReason {
+    Experimental = "experimental",
+    ToolMaintenance = "tool-maintenance",
+    Disabled = "disabled"
+}
+//# sourceMappingURL=surface-refusal-reason.d.ts.map

package/dist/surface/surface-refusal-reason.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-refusal-reason.d.ts","sourceRoot":"","sources":["../../src/surface/surface-refusal-reason.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,oBAAY,oBAAoB;IAC9B,YAAY,iBAAiB;IAC7B,eAAe,qBAAqB;IACpC,QAAQ,aAAa;CACtB"}

package/dist/surface/surface-refusal-reason.js

@@ -0,0 +1,16 @@
+/**
+ * Why the surface gate refused a command (exit 78). One gate, three reasons:
+ *
+ *   - `experimental`      — an experimental command not in `surface.enabled`
+ *   - `tool-maintenance`  — a command that maintains SharkCraft itself, run
+ *                           outside SharkCraft's own repository
+ *   - `disabled`          — denied by a `surface.disabled` selector
+ *
+ * None of them is a check failure.
+ */
+export var SurfaceRefusalReason;
+(function (SurfaceRefusalReason) {
+    SurfaceRefusalReason["Experimental"] = "experimental";
+    SurfaceRefusalReason["ToolMaintenance"] = "tool-maintenance";
+    SurfaceRefusalReason["Disabled"] = "disabled";
+})(SurfaceRefusalReason || (SurfaceRefusalReason = {}));

package/dist/surface/surface-selector.d.ts

@@ -0,0 +1,26 @@
+/**
+ * THE surface selector matcher (round 11 §5.1#3) — the one answer to "does
+ * this `surface.hidden` / `surface.enabled` / `surface.disabled` entry name
+ * this command?". The tier resolver, the surface summary (flags + the
+ * unknown-selector warnings) and `surface deny` all read it, so a selector can
+ * never hide a command in one place and miss it in another.
+ *
+ *   - an exact command path, or one of its alias spellings: `bundle list`
+ *   - a GROUP selector — a path followed by ` *`: `bundle *` names `bundle`
+ *     itself and every command below it (`bundle list`, `bundle replay …`)
+ *
+ * Back-compat is exact: no pre-round-11 selector ends in ` *`, and an exact
+ * selector still names exactly one path. A bare `*` is not a group selector
+ * (it names no command, so the summary warns `unknown-command`).
+ */
+export declare const GROUP_SELECTOR_SUFFIX = " *";
+/** True for `<path> *` (a non-empty path followed by ` *`). */
+export declare function isGroupSelector(selector: string): boolean;
+/** Does `selector` name `command` (a path or an alias spelling)? */
+export declare function matchesSurfaceSelector(selector: string, command: string): boolean;
+/**
+ * The first selector in `selectors` that names any of `names` (a command path
+ * plus its alias spellings), or `undefined`.
+ */
+export declare function firstMatchingSelector(selectors: readonly string[] | undefined, names: readonly string[]): string | undefined;
+//# sourceMappingURL=surface-selector.d.ts.map

package/dist/surface/surface-selector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"surface-selector.d.ts","sourceRoot":"","sources":["../../src/surface/surface-selector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,+DAA+D;AAC/D,wBAAgB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAGzD;AAED,oEAAoE;AACpE,wBAAgB,sBAAsB,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAQjF;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EACxC,KAAK,EAAE,SAAS,MAAM,EAAE,GACvB,MAAM,GAAG,SAAS,CAKpB"}

package/dist/surface/surface-selector.js

@@ -0,0 +1,42 @@
+/**
+ * THE surface selector matcher (round 11 §5.1#3) — the one answer to "does
+ * this `surface.hidden` / `surface.enabled` / `surface.disabled` entry name
+ * this command?". The tier resolver, the surface summary (flags + the
+ * unknown-selector warnings) and `surface deny` all read it, so a selector can
+ * never hide a command in one place and miss it in another.
+ *
+ *   - an exact command path, or one of its alias spellings: `bundle list`
+ *   - a GROUP selector — a path followed by ` *`: `bundle *` names `bundle`
+ *     itself and every command below it (`bundle list`, `bundle replay …`)
+ *
+ * Back-compat is exact: no pre-round-11 selector ends in ` *`, and an exact
+ * selector still names exactly one path. A bare `*` is not a group selector
+ * (it names no command, so the summary warns `unknown-command`).
+ */
+export const GROUP_SELECTOR_SUFFIX = ' *';
+/** True for `<path> *` (a non-empty path followed by ` *`). */
+export function isGroupSelector(selector) {
+    const s = selector.trim();
+    return s.endsWith(GROUP_SELECTOR_SUFFIX) && s.slice(0, -GROUP_SELECTOR_SUFFIX.length).trim().length > 0;
+}
+/** Does `selector` name `command` (a path or an alias spelling)? */
+export function matchesSurfaceSelector(selector, command) {
+    const want = selector.trim();
+    const name = command.trim();
+    if (isGroupSelector(want)) {
+        const group = want.slice(0, -GROUP_SELECTOR_SUFFIX.length).trim();
+        return name === group || name.startsWith(`${group} `);
+    }
+    return name === want;
+}
+/**
+ * The first selector in `selectors` that names any of `names` (a command path
+ * plus its alias spellings), or `undefined`.
+ */
+export function firstMatchingSelector(selectors, names) {
+    for (const selector of selectors ?? []) {
+        if (names.some((n) => matchesSurfaceSelector(selector, n)))
+            return selector;
+    }
+    return undefined;
+}

package/dist/surface/surface-summary.d.ts

@@ -1,20 +1,48 @@
-import { CommandTier, type ICommandCatalogEntry } from '../commands/command-catalog.js';
+import { CommandAudience, CommandTier, type ICommandCatalogEntry } from '../commands/command-catalog.js';
+import { CommandDispatchKind } from './command-dispatch-kind.js';
+import type { ICommandIndex } from './i-command-index.js';
+import type { ISurfaceDenial } from './i-surface-denial.js';
 import { TierSource, type ITierResolution, type ITierResolverContext } from './tier.js';
-export declare const SURFACE_SUMMARY_SCHEMA = "sharkcraft.surface.v1";
+/**
+ * v2 (round 11): the summary iterates the COMMAND INDEX — every dispatchable
+ * verb, subverb and meta flag — instead of the catalog, and each row carries
+ * its real description, usage, dispatch kind, audience and folded flag
+ * variants. v1 listed catalog rows only (75 registered verbs were missing) and
+ * printed one placeholder sentence for every extended row.
+ */
+export declare const SURFACE_SUMMARY_SCHEMA = "sharkcraft.surface.v2";
 /** Per-command snapshot used in {@link ISurfaceSummary}. */
 export interface ISurfaceCommandView {
     command: string;
     tier: CommandTier;
     source: TierSource;
     detail?: string;
+    /** One-line description (catalog ?? declared subverb ?? handler). */
+    description: string;
+    /** Usage line, when the handler or a declared subverb carries one. */
+    usage?: string;
+    /** How the command dispatches (trie handler, internal subverb, meta flag). */
+    dispatch: CommandDispatchKind;
+    /** True when a catalog row documents the command. */
+    catalogued: boolean;
+    audience: readonly CommandAudience[];
+    /** Catalog rows folded in because they only add flags / placeholders. */
+    variants: readonly string[];
     /** Whether the command is callable in this project's surface configuration. */
     callable: boolean;
-    /** Whether the command shows in default `--help` output. */
+    /**
+     * Whether the command shows in `--full-help`. THE answer — `--full-help`
+     * renders exactly the views that say `true` (round 11 §5.1#3).
+     */
     visibleInHelp: boolean;
-    /** True if `surface.hidden[]` contains the command. */
+    /** True if a `surface.hidden[]` selector names the command. */
     hidden: boolean;
-    /** True if `surface.enabled[]` contains the command. */
+    /** True if a `surface.enabled[]` selector names the command. */
     enabled: boolean;
+    /** True if a `surface.disabled[]` selector DENIES the command (source `disabled`). */
+    disabled: boolean;
+    /** The deny selector and its layer, when `disabled`. */
+    deniedBy?: ISurfaceDenial;
     /** Pack contribution source, if any. */
     pack?: string;
 }
@@ -22,13 +50,21 @@ export interface ISurfaceTotals {
     core: number;
     extended: number;
     experimental: number;
-    /** Sum of (core + extended visibleInHelp). */
+    /** Rows visible in `--full-help` (core + extended visibleInHelp). */
     visible: number;
-    /** Sum of all callable commands (core + extended). */
+    /** Every callable row (core + extended + enabled experimental). */
     callable: number;
+    /** Dispatchable rows no catalog row documents (`commands doctor` warns on each). */
+    uncatalogued: number;
 }
 export interface ISurfaceSummary {
     schema: typeof SURFACE_SUMMARY_SCHEMA;
+    /**
+     * True when the rows are the dispatch table (built from the command
+     * registry). False only for a registry-less engine call, where the rows are
+     * the catalog relabelled — a partial inventory, and said so.
+     */
+    registryBacked: boolean;
     tiers: {
         core: readonly ISurfaceCommandView[];
         extended: readonly ISurfaceCommandView[];
@@ -37,29 +73,36 @@ export interface ISurfaceSummary {
     totals: ISurfaceTotals;
     /**
      * Warnings — e.g. a `surface.enabled` entry that doesn't match any
-     * catalog command, or an attempt to hide a core command.
+     * command, or an attempt to hide or disable a core command.
      */
     warnings: readonly ISurfaceWarning[];
-    /** Stable hash of (catalog + context). Used in test snapshots. */
+    /** Stable hash of (index + context). Used in test snapshots. */
     hash: string;
 }
 export interface ISurfaceWarning {
     command: string;
-    code: 'unknown-command' | 'cannot-hide-core' | 'cannot-disable-core' | 'enable-noop' | 'tier-override-conflict';
+    code: 'unknown-command' | 'cannot-hide-core' | 'cannot-disable-core' | 'enable-noop' | 'enable-disable-conflict' | 'tier-override-conflict';
     message: string;
 }
 /**
  * Build the canonical surface summary used by `shrk surface list`
- * (text + JSON), the `--about` landing, the help renderer's hidden-set,
- * and the MCP gating layer.
+ * (text + JSON), the `--about` landing, `--help` / `--full-help`, the CLI
+ * surface gate and the MCP gating layer.
+ *
+ * `index` defaults to the ACTIVE command index (the registry this CLI run
+ * dispatches from). Outside `runCli` it falls back to the catalog, relabelled
+ * (`registryBacked: false`).
  *
- * Implementation note: deterministic. Same context + catalog → same
- * summary, byte-for-byte. The `hash` field is the SHA-256 prefix of
- * the canonical JSON form (sans the hash itself) — useful for cache
- * keys and snapshot tests.
+ * Deterministic: same context + index → same summary, byte-for-byte. The
+ * `hash` field is the SHA-256 prefix of the canonical JSON form (sans the
+ * hash itself) — useful for cache keys and snapshot tests.
+ */
+export declare function buildSurfaceSummary(context: ITierResolverContext, index?: ICommandIndex): ISurfaceSummary;
+/**
+ * Look up a single command's view from a summary. Accepts the command path,
+ * a folded flag variant (`architecture violations --changed-only`) or an alias
+ * spelling — the shapes callers (the surface gate, MCP `cliCommand`) hold.
  */
-export declare function buildSurfaceSummary(context: ITierResolverContext): ISurfaceSummary;
-/** Look up a single command's tier resolution from a summary. */
 export declare function findCommandInSummary(summary: ISurfaceSummary, command: string): ISurfaceCommandView | undefined;
 /** Resolve a single tier given a context (no summary needed). */
 export declare function resolveTierForCommand(entry: ICommandCatalogEntry, context: ITierResolverContext): ITierResolution;

package/dist/surface/surface-summary.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surface-summary.d.ts","sourceRoot":"","sources":["../../src/surface/surface-summary.ts"],"names":[],"mappings":"AACA,OAAO,EACL,WAAW,EAGX,KAAK,oBAAoB,EAC1B,MAAM,gCAAgC,CAAC;AACxC,OAAO,EAKL,UAAU,EACV,KAAK,eAAe,EACpB,KAAK,oBAAoB,EAC1B,MAAM,WAAW,CAAC;AAEnB,eAAO,MAAM,sBAAsB,0BAA0B,CAAC;AAE9D,4DAA4D;AAC5D,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,WAAW,CAAC;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,QAAQ,EAAE,OAAO,CAAC;IAClB,4DAA4D;IAC5D,aAAa,EAAE,OAAO,CAAC;IACvB,uDAAuD;IACvD,MAAM,EAAE,OAAO,CAAC;IAChB,wDAAwD;IACxD,OAAO,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAC;IAChB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,OAAO,sBAAsB,CAAC;IACtC,KAAK,EAAE;QACL,IAAI,EAAE,SAAS,mBAAmB,EAAE,CAAC;QACrC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,CAAC;QACzC,YAAY,EAAE,SAAS,mBAAmB,EAAE,CAAC;KAC9C,CAAC;IACF,MAAM,EAAE,cAAc,CAAC;IACvB;;;OAGG;IACH,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,iBAAiB,GAAG,kBAAkB,GAAG,qBAAqB,GAAG,aAAa,GAAG,wBAAwB,CAAC;IAChH,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,GAC5B,eAAe,CAoFjB;AAkFD,iEAAiE;AACjE,wBAAgB,oBAAoB,CAClC,OAAO,EAAE,eAAe,EACxB,OAAO,EAAE,MAAM,GACd,mBAAmB,GAAG,SAAS,CAMjC;AAED,iEAAiE;AACjE,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,oBAAoB,EAC3B,OAAO,EAAE,oBAAoB,GAC5B,eAAe,CAEjB"}
+{"version":3,"file":"surface-summary.d.ts","sourceRoot":"","sources":["../../src/surface/surface-summary.ts"],"names":[],"mappings":"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"}

package/dist/surface/surface-summary.js

@@ -1,45 +1,68 @@
 import { createHash } from 'node:crypto';
-import { CommandTier, COMMAND_CATALOG, defaultShowInHelp, } from "../commands/command-catalog.js";
-import { BOOTSTRAP_COMMANDS, isCallable, isVisibleInDefaultHelp, resolveTier, TierSource, } from "./tier.js";
-export const SURFACE_SUMMARY_SCHEMA = 'sharkcraft.surface.v1';
+import { CommandAudience, CommandTier, defaultShowInHelp, isExplainFamily, } from "../commands/command-catalog.js";
+import { CommandDispatchKind } from "./command-dispatch-kind.js";
+import { buildCommandIndex, cleanCommandPath, getActiveCommandIndex } from "./command-index.js";
+import { SurfaceLayer } from "./surface-layer.js";
+import { firstMatchingSelector, matchesSurfaceSelector } from "./surface-selector.js";
+import { BOOTSTRAP_COMMANDS, isBootstrapFamily, isCallable, isVisibleInDefaultHelp, resolveTier, resolveTierForPath, TierSource, } from "./tier.js";
+/**
+ * v2 (round 11): the summary iterates the COMMAND INDEX — every dispatchable
+ * verb, subverb and meta flag — instead of the catalog, and each row carries
+ * its real description, usage, dispatch kind, audience and folded flag
+ * variants. v1 listed catalog rows only (75 registered verbs were missing) and
+ * printed one placeholder sentence for every extended row.
+ */
+export const SURFACE_SUMMARY_SCHEMA = 'sharkcraft.surface.v2';
+/** The `surface{}` lists every selector warning is checked against, in report order. */
+const SELECTOR_FIELDS = ['enabled', 'hidden', 'disabled'];
 /**
  * Build the canonical surface summary used by `shrk surface list`
- * (text + JSON), the `--about` landing, the help renderer's hidden-set,
- * and the MCP gating layer.
+ * (text + JSON), the `--about` landing, `--help` / `--full-help`, the CLI
+ * surface gate and the MCP gating layer.
  *
- * Implementation note: deterministic. Same context + catalog → same
- * summary, byte-for-byte. The `hash` field is the SHA-256 prefix of
- * the canonical JSON form (sans the hash itself) — useful for cache
- * keys and snapshot tests.
+ * `index` defaults to the ACTIVE command index (the registry this CLI run
+ * dispatches from). Outside `runCli` it falls back to the catalog, relabelled
+ * (`registryBacked: false`).
+ *
+ * Deterministic: same context + index → same summary, byte-for-byte. The
+ * `hash` field is the SHA-256 prefix of the canonical JSON form (sans the
+ * hash itself) — useful for cache keys and snapshot tests.
  */
-export function buildSurfaceSummary(context) {
+export function buildSurfaceSummary(context, index = getActiveCommandIndex() ?? buildCommandIndex()) {
     const core = [];
     const extended = [];
     const experimental = [];
     const warnings = [];
-    const hiddenSet = new Set(context.surfaceConfig?.hidden ?? []);
-    const enabledSet = new Set(context.surfaceConfig?.enabled ?? []);
-    const knownCommands = new Set();
-    for (const entry of COMMAND_CATALOG) {
-        knownCommands.add(entry.command);
-        const view = makeCommandView(entry, context, hiddenSet, enabledSet, warnings);
+    // Every spelling a selector may name: paths, alias spellings, flag variants.
+    const knownNames = [...BOOTSTRAP_COMMANDS];
+    for (const entry of index.entries) {
+        knownNames.push(entry.path, ...entry.variants, ...entry.aliases);
+        const view = makeCommandView(entry, context, warnings);
         pushIntoBucket(view, core, extended, experimental);
     }
-    // Surface bootstrap meta-flags (e.g. `--about`) that aren't
-    // ordinary catalog entries. They sit in core for visibility but have
-    // no catalog row.
+    // Bootstrap names the index does not list (defensive: every bootstrap
+    // command is a registered handler or a meta flag today).
+    const indexed = new Set(knownNames);
     for (const bootstrap of BOOTSTRAP_COMMANDS) {
-        if (knownCommands.has(bootstrap))
+        if (index.entries.some((e) => e.path === bootstrap || e.aliases.includes(bootstrap)))
+            continue;
+        if (!indexed.has(bootstrap))
             continue;
         core.push({
             command: bootstrap,
             tier: CommandTier.Core,
             source: TierSource.Bootstrap,
             detail: 'bootstrap meta-flag',
+            description: 'Bootstrap meta flag.',
+            dispatch: CommandDispatchKind.Meta,
+            catalogued: false,
+            audience: [CommandAudience.Human],
+            variants: [],
             callable: true,
             visibleInHelp: true,
             hidden: false,
             enabled: false,
+            disabled: false,
         });
     }
     // Sort each bucket alphabetically for stable output.
@@ -47,36 +70,32 @@ export function buildSurfaceSummary(context) {
     core.sort(sortByName);
     extended.sort(sortByName);
     experimental.sort(sortByName);
-    // Audit warnings for config keys that don't correspond to anything.
-    for (const name of enabledSet) {
-        if (!knownCommands.has(name) && !BOOTSTRAP_COMMANDS.includes(name)) {
-            warnings.push({
-                command: name,
-                code: 'unknown-command',
-                message: `surface.enabled[] references unknown command: ${name}`,
-            });
-        }
-    }
-    for (const name of hiddenSet) {
-        if (!knownCommands.has(name) && !BOOTSTRAP_COMMANDS.includes(name)) {
-            warnings.push({
-                command: name,
-                code: 'unknown-command',
-                message: `surface.hidden[] references unknown command: ${name}`,
-            });
+    // A selector that names nothing is a silent no-op — say so. Group selectors
+    // (`bundle *`) go through the same matcher the resolver uses.
+    for (const field of SELECTOR_FIELDS) {
+        for (const selector of new Set(context.surfaceConfig?.[field] ?? [])) {
+            if (!knownNames.some((name) => matchesSurfaceSelector(selector, name))) {
+                warnings.push({
+                    command: selector,
+                    code: 'unknown-command',
+                    message: `surface.${field}[] references unknown command: ${selector}`,
+                });
+            }
         }
     }
+    const all = [...core, ...extended, ...experimental];
     const totals = {
         core: core.length,
         extended: extended.length,
         experimental: experimental.length,
         visible: core.length + extended.filter((c) => c.visibleInHelp).length,
-        callable: core.length +
-            extended.length +
-            experimental.filter((c) => c.callable).length,
+        callable: all.filter((c) => c.callable).length,
+        uncatalogued: all.filter((c) => !c.catalogued && c.dispatch !== CommandDispatchKind.Meta)
+            .length,
     };
     const summaryWithoutHash = {
         schema: SURFACE_SUMMARY_SCHEMA,
+        registryBacked: index.registryBacked,
         tiers: { core, extended, experimental },
         totals,
         warnings,
@@ -87,56 +106,115 @@ export function buildSurfaceSummary(context) {
         .slice(0, 16);
     return { ...summaryWithoutHash, hash };
 }
-function makeCommandView(entry, context, hiddenSet, enabledSet, warnings) {
-    const resolution = resolveTier(entry, context);
-    const isHidden = hiddenSet.has(entry.command);
-    const isEnabled = enabledSet.has(entry.command);
+function makeCommandView(entry, context, warnings) {
+    const name = entry.path;
+    const names = [name, ...entry.aliases];
+    const catalogRow = entry.catalogEntry;
+    const resolution = entry.dispatch === CommandDispatchKind.Meta
+        ? { tier: CommandTier.Core, source: TierSource.Bootstrap, detail: 'bootstrap meta-flag' }
+        : resolveTierForPath(name, catalogRow, context, entry.aliases);
+    const isHidden = firstMatchingSelector(context.surfaceConfig?.hidden, names) !== undefined;
+    const isEnabled = firstMatchingSelector(context.surfaceConfig?.enabled, names) !== undefined;
+    const denySelector = firstMatchingSelector(context.surfaceConfig?.disabled, names);
     // Cross-check the config against the derived tier.
     if (resolution.tier === CommandTier.Core) {
         if (isHidden) {
             warnings.push({
-                command: entry.command,
+                command: name,
                 code: 'cannot-hide-core',
-                message: `Cannot hide core command: ${entry.command}. Remove from surface.hidden.`,
+                message: `Cannot hide core command: ${name}. Remove from surface.hidden.`,
             });
         }
         if (isEnabled) {
             // Enabling a core command is harmless but pointless.
             warnings.push({
-                command: entry.command,
+                command: name,
                 code: 'enable-noop',
-                message: `Enabling a core command is a no-op: ${entry.command}`,
+                message: `Enabling a core command is a no-op: ${name}`,
+            });
+        }
+    }
+    // A deny that could not apply: a core command, or a bootstrap command's
+    // subverb (the verbs that undo a deny must stay reachable).
+    if (denySelector !== undefined &&
+        resolution.source !== TierSource.Disabled &&
+        (resolution.tier === CommandTier.Core || isBootstrapFamily(name))) {
+        warnings.push({
+            command: name,
+            code: 'cannot-disable-core',
+            message: `Cannot disable core command: ${name} (surface.disabled '${denySelector}'). It stays callable.`,
+        });
+    }
+    // A config deny and a config enable naming the same command: the deny wins.
+    if (resolution.deniedBy?.origin === SurfaceLayer.Config) {
+        const explicit = context.explicitSurface ?? context.surfaceConfig;
+        if (firstMatchingSelector(explicit?.enabled, names) !== undefined) {
+            warnings.push({
+                command: name,
+                code: 'enable-disable-conflict',
+                message: `surface.disabled ('${resolution.deniedBy.selector}') and surface.enabled both name ${name} — disabled wins.`,
             });
         }
     }
     // Cross-check explicit override against the resolver. If the catalog
     // says Experimental but the resolver promoted to Core (spine /
     // bootstrap), surface a warning so the override is corrected.
-    if (entry.tier !== undefined &&
-        entry.tier !== resolution.tier &&
-        resolution.source !== TierSource.Override) {
+    if (catalogRow?.tier !== undefined &&
+        catalogRow.tier !== resolution.tier &&
+        resolution.source !== TierSource.Override &&
+        resolution.source !== TierSource.Disabled &&
+        resolution.source !== TierSource.ToolMaintenance) {
         warnings.push({
-            command: entry.command,
+            command: name,
             code: 'tier-override-conflict',
-            message: `Catalog declares tier=${entry.tier} but mechanical derivation resolved to ${resolution.tier} (${resolution.source}). Remove the override.`,
+            message: `Catalog declares tier=${catalogRow.tier} but mechanical derivation resolved to ${resolution.tier} (${resolution.source}). Remove the override.`,
         });
     }
     const view = {
-        command: entry.command,
+        command: name,
         tier: resolution.tier,
         source: resolution.source,
+        description: entry.description,
+        ...(entry.usage ? { usage: entry.usage } : {}),
+        dispatch: entry.dispatch,
+        catalogued: entry.catalogued,
+        audience: entry.audience,
+        variants: entry.variants,
         callable: isCallable(resolution),
-        visibleInHelp: isVisibleInDefaultHelp(resolution, isHidden) && defaultShowInHelp(entry),
+        visibleInHelp: visibleInHelp(entry, catalogRow, resolution, isHidden),
         hidden: isHidden,
         enabled: isEnabled,
+        disabled: resolution.source === TierSource.Disabled,
     };
+    if (resolution.deniedBy)
+        view.deniedBy = resolution.deniedBy;
     if (resolution.detail)
         view.detail = resolution.detail;
-    const pack = context.packContributions.get(entry.command);
+    const pack = context.packContributions.get(name);
     if (pack)
         view.pack = pack;
     return view;
 }
+/**
+ * THE `--help` visibility rule. `--full-help` lists exactly the views this
+ * returns `true` for: the rent-paying catalog surface (`defaultShowInHelp`)
+ * plus the explain / dry-run family `--full-help` lists in its own section —
+ * both subject to the tier (experimental is never listed) and to
+ * `surface.hidden`. Help used to decide from the catalog alone, so
+ * `surface.hidden` / profiles / gating never reached it and `surface explain`
+ * disagreed with the actual help output.
+ */
+function visibleInHelp(entry, catalogRow, resolution, isHidden) {
+    if (entry.dispatch === CommandDispatchKind.Meta)
+        return true;
+    // Help listings are catalog-curated: an uncatalogued command runs, but has
+    // no row for `--help` to surface.
+    if (!catalogRow)
+        return false;
+    if (!isVisibleInDefaultHelp(resolution, isHidden))
+        return false;
+    return defaultShowInHelp(catalogRow) || isExplainFamily(catalogRow);
+}
 function pushIntoBucket(view, core, extended, experimental) {
     switch (view.tier) {
         case CommandTier.Core:
@@ -150,11 +228,20 @@ function pushIntoBucket(view, core, extended, experimental) {
             break;
     }
 }
-/** Look up a single command's tier resolution from a summary. */
+/**
+ * Look up a single command's view from a summary. Accepts the command path,
+ * a folded flag variant (`architecture violations --changed-only`) or an alias
+ * spelling — the shapes callers (the surface gate, MCP `cliCommand`) hold.
+ */
 export function findCommandInSummary(summary, command) {
-    return (summary.tiers.core.find((c) => c.command === command) ??
-        summary.tiers.extended.find((c) => c.command === command) ??
-        summary.tiers.experimental.find((c) => c.command === command));
+    const views = [...summary.tiers.core, ...summary.tiers.extended, ...summary.tiers.experimental];
+    const want = command.trim();
+    const exact = views.find((c) => c.command === want);
+    if (exact)
+        return exact;
+    const clean = cleanCommandPath(want);
+    return ((clean.length > 0 ? views.find((c) => c.command === clean) : undefined) ??
+        views.find((c) => c.variants.includes(want)));
 }
 /** Resolve a single tier given a context (no summary needed). */
 export function resolveTierForCommand(entry, context) {