@jackwener/opencli 1.7.12 → 1.7.13

package/dist/src/browser/cdp.js

@@ -202,16 +202,58 @@ class CDPPage extends BasePage {
             : cookies;
     }
     async screenshot(options = {}) {
-        const result = await this.bridge.send('Page.captureScreenshot', {
-            format: options.format ?? 'png',
-            quality: options.format === 'jpeg' ? (options.quality ?? 80) : undefined,
-            captureBeyondViewport: options.fullPage ?? false,
-        });
-        const base64 = isRecord(result) && typeof result.data === 'string' ? result.data : '';
-        if (options.path) {
-            await saveBase64ToFile(base64, options.path);
+        const fullPage = options.fullPage === true;
+        const overrideWidth = options.width && options.width > 0 ? Math.ceil(options.width) : undefined;
+        // height is ignored under fullPage so the captureBeyondViewport path stays unchanged for users who pass --height alongside --full-page.
+        const overrideHeight = !fullPage && options.height && options.height > 0 ? Math.ceil(options.height) : undefined;
+        const needsOverride = overrideWidth !== undefined || overrideHeight !== undefined;
+        if (needsOverride) {
+            if (overrideWidth !== undefined && fullPage) {
+                await this.bridge.send('Emulation.setDeviceMetricsOverride', {
+                    mobile: false,
+                    width: overrideWidth,
+                    height: 0,
+                    deviceScaleFactor: 1,
+                });
+            }
+            let finalWidth = overrideWidth ?? 0;
+            let finalHeight = overrideHeight ?? 0;
+            if (fullPage) {
+                const metrics = await this.bridge.send('Page.getLayoutMetrics');
+                const m = isRecord(metrics) ? metrics : {};
+                const css = isRecord(m.cssContentSize) ? m.cssContentSize : undefined;
+                const fb = isRecord(m.contentSize) ? m.contentSize : undefined;
+                const size = css ?? fb;
+                if (size && typeof size.width === 'number' && typeof size.height === 'number') {
+                    if (finalWidth === 0)
+                        finalWidth = Math.ceil(size.width);
+                    finalHeight = Math.ceil(size.height);
+                }
+            }
+            await this.bridge.send('Emulation.setDeviceMetricsOverride', {
+                mobile: false,
+                width: finalWidth,
+                height: finalHeight,
+                deviceScaleFactor: 1,
+            });
+        }
+        try {
+            const result = await this.bridge.send('Page.captureScreenshot', {
+                format: options.format ?? 'png',
+                quality: options.format === 'jpeg' ? (options.quality ?? 80) : undefined,
+                captureBeyondViewport: !needsOverride && fullPage,
+            });
+            const base64 = isRecord(result) && typeof result.data === 'string' ? result.data : '';
+            if (options.path) {
+                await saveBase64ToFile(base64, options.path);
+            }
+            return base64;
+        }
+        finally {
+            if (needsOverride) {
+                await this.bridge.send('Emulation.clearDeviceMetricsOverride').catch(() => { });
+            }
         }
-        return base64;
     }
     async startNetworkCapture(pattern = '') {
         // Always update the filter pattern

package/dist/src/browser/daemon-client.d.ts

@@ -20,6 +20,10 @@ export interface DaemonCommand {
     format?: 'png' | 'jpeg';
     quality?: number;
     fullPage?: boolean;
+    /** Override viewport width in CSS pixels for screenshot (0 / undefined = use current) */
+    width?: number;
+    /** Override viewport height in CSS pixels for screenshot (0 / undefined = use current; ignored when fullPage) */
+    height?: number;
     /** Local file paths for set-file-input action */
     files?: string[];
     /** CSS selector for file input element (set-file-input action) */

package/dist/src/browser/errors.js

@@ -65,7 +65,7 @@ export function isTransientBrowserError(err) {
 export function formatBrowserConnectError(kind, detail) {
     switch (kind) {
         case 'daemon-not-running':
-            return new BrowserConnectError('Cannot connect to opencli daemon.' + (detail ? `\n\n${detail}` : ''), `The daemon should auto-start. If it keeps failing, make sure port ${DEFAULT_DAEMON_PORT} is available.`, kind);
+            return new BrowserConnectError('Cannot connect to opencli daemon.' + (detail ? `\n\n${detail}` : ''), `Run \`opencli doctor\` to diagnose, or \`opencli daemon restart\` to force a fresh daemon. Default port is ${DEFAULT_DAEMON_PORT}.`, kind);
         case 'extension-not-connected':
             return new BrowserConnectError('Browser Bridge extension is not connected.' + (detail ? `\n\n${detail}` : ''), 'Install the extension from GitHub Releases, then reload.', kind);
         case 'command-failed':

package/dist/src/browser/page.d.ts

@@ -41,7 +41,7 @@ export declare class Page extends BasePage {
         domain?: string;
         url?: string;
     }): Promise<BrowserCookie[]>;
-    /** Close the automation window in the extension */
+    /** Release the current automation tab lease in the extension */
     closeWindow(): Promise<void>;
     tabs(): Promise<unknown[]>;
     newTab(url?: string): Promise<string | undefined>;

package/dist/src/browser/page.js

@@ -143,7 +143,7 @@ export class Page extends BasePage {
         const result = await sendCommand('cookies', { ...this._wsOpt(), ...opts });
         return Array.isArray(result) ? result : [];
     }
-    /** Close the automation window in the extension */
+    /** Release the current automation tab lease in the extension */
     async closeWindow() {
         try {
             await sendCommand('close-window', { ...this._wsOpt() });
@@ -205,6 +205,8 @@ export class Page extends BasePage {
             format: options.format,
             quality: options.quality,
             fullPage: options.fullPage,
+            width: options.width,
+            height: options.height,
         });
         if (options.path) {
             await saveBase64ToFile(base64, options.path);

package/dist/src/browser/page.test.js

@@ -216,3 +216,32 @@ describe('Page active target tracking', () => {
         expect(evalCall?.[1]).not.toHaveProperty('page');
     });
 });
+describe('Page.screenshot', () => {
+    beforeEach(() => {
+        sendCommandMock.mockReset();
+        sendCommandFullMock.mockReset();
+        warnMock.mockReset();
+    });
+    it('forwards width / height / fullPage options to the bridge', async () => {
+        sendCommandMock.mockResolvedValueOnce('BASE64');
+        const page = new Page('browser:default');
+        const data = await page.screenshot({ fullPage: true, width: 1080 });
+        expect(data).toBe('BASE64');
+        expect(sendCommandMock).toHaveBeenCalledWith('screenshot', expect.objectContaining({
+            workspace: 'browser:default',
+            fullPage: true,
+            width: 1080,
+        }));
+    });
+    it('omits viewport overrides when none are set', async () => {
+        sendCommandMock.mockResolvedValueOnce('BASE64');
+        const page = new Page('browser:default');
+        await page.screenshot();
+        const call = sendCommandMock.mock.calls.at(-1);
+        expect(call?.[0]).toBe('screenshot');
+        const args = call?.[1];
+        expect(args.width).toBeUndefined();
+        expect(args.height).toBeUndefined();
+        expect(args.fullPage).toBeUndefined();
+    });
+});

package/dist/src/browser/target-errors.d.ts

@@ -15,8 +15,9 @@
  *   - selector_not_found:     0 matches
  *   - selector_ambiguous:     >1 matches for a write op without --nth
  *   - selector_nth_out_of_range: --nth beyond matches_n
+ *   - not_editable:           target exists but cannot accept text input
  */
-export type TargetErrorCode = 'not_found' | 'stale_ref' | 'invalid_selector' | 'selector_not_found' | 'selector_ambiguous' | 'selector_nth_out_of_range';
+export type TargetErrorCode = 'not_found' | 'stale_ref' | 'invalid_selector' | 'selector_not_found' | 'selector_ambiguous' | 'selector_nth_out_of_range' | 'not_editable';
 export interface TargetErrorInfo {
     code: TargetErrorCode;
     message: string;

package/dist/src/browser/target-errors.js

@@ -15,6 +15,7 @@
  *   - selector_not_found:     0 matches
  *   - selector_ambiguous:     >1 matches for a write op without --nth
  *   - selector_nth_out_of_range: --nth beyond matches_n
+ *   - not_editable:           target exists but cannot accept text input
  */
 export class TargetError extends Error {
     code;

package/dist/src/browser/target-resolver.d.ts

@@ -79,6 +79,25 @@ export declare function clickResolvedJs(opts?: {
  * Generate JS for type that uses the unified resolver.
  */
 export declare function typeResolvedJs(text: string): string;
+export type FillResolvedResult = {
+    ok: true;
+    actual: string;
+    expected: string;
+    length: number;
+    mode: 'input' | 'textarea' | 'contenteditable';
+} | {
+    ok: false;
+    actual: string;
+    expected: string;
+    length: number;
+    mode: 'input' | 'textarea' | 'contenteditable';
+} | {
+    ok: false;
+    reason: string;
+    tag?: string;
+    type?: string;
+    role?: string;
+};
 /**
  * Prepare the resolved element for native CDP Input.insertText.
  *
@@ -90,6 +109,12 @@ export declare function prepareNativeTypeResolvedJs(opts?: {
     skipScroll?: boolean;
     skipFocus?: boolean;
 }): string;
+/**
+ * Verify the exact value/text currently held by the resolved editable target.
+ * Assumes resolveTargetJs and prepareNativeTypeResolvedJs have already set
+ * `window.__resolved` to the normalized editable host.
+ */
+export declare function verifyFilledResolvedJs(expected: string): string;
 /**
  * Generate JS for scrollTo that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.

package/dist/src/browser/target-resolver.js

@@ -411,6 +411,49 @@ export function prepareNativeTypeResolvedJs(opts = {}) {
     })()
   `;
 }
+/**
+ * Verify the exact value/text currently held by the resolved editable target.
+ * Assumes resolveTargetJs and prepareNativeTypeResolvedJs have already set
+ * `window.__resolved` to the normalized editable host.
+ */
+export function verifyFilledResolvedJs(expected) {
+    const safeText = JSON.stringify(expected);
+    return `
+    (() => {
+      const el = window.__resolved;
+      if (!el) return { ok: false, reason: 'no_resolved_element' };
+
+      const tag = el.tagName ? el.tagName.toLowerCase() : '';
+      const isInput = el instanceof HTMLInputElement;
+      const isTextarea = el instanceof HTMLTextAreaElement;
+      const mode = el.isContentEditable
+        ? 'contenteditable'
+        : isTextarea
+          ? 'textarea'
+          : isInput
+            ? 'input'
+            : '';
+
+      if (!mode) {
+        return {
+          ok: false,
+          reason: 'not_editable',
+          tag,
+          role: el.getAttribute ? (el.getAttribute('role') || '') : '',
+        };
+      }
+
+      const actual = mode === 'contenteditable' ? (el.innerText || '') : String(el.value || '');
+      return {
+        ok: actual === ${safeText},
+        actual,
+        expected: ${safeText},
+        length: actual.length,
+        mode,
+      };
+    })()
+  `;
+}
 /**
  * Generate JS for scrollTo that uses the unified resolver.
  * Assumes resolveTargetJs has been called and __resolved is set.

package/dist/src/build-manifest.js

@@ -32,7 +32,13 @@ const PACKAGE_ROOT = findPackageRoot(fileURLToPath(import.meta.url));
 const CLIS_DIR = path.join(PACKAGE_ROOT, 'clis');
 // Write manifest next to clis/ so both dev and installed runtime can find it.
 const OUTPUT = getCliManifestPath(CLIS_DIR);
-const CLI_MODULE_PATTERN = /\bcli\s*\(/;
+// Module is treated as a CLI command source if it either:
+//   1. Calls `cli(...)` directly (the common case), or
+//   2. Calls a factory `make<Pascal>Command(...)` from clis/_shared/ that
+//      wraps `cli(...)`. Without (2), shared-factory adapters
+//      (codex/cursor/chatwise new/status/dump/screenshot) match no `cli(`
+//      token at the top level and silently drop out of the manifest.
+const CLI_MODULE_PATTERN = /\bcli\s*\(|\bmake[A-Z]\w*Command\s*\(/;
 /**
  * Thrown by `loadManifestEntries` when an adapter file looks like a CLI
  * module (matches CLI_MODULE_PATTERN) but cannot be imported. Callers
@@ -91,13 +97,12 @@ function toManifestEntry(cmd, modulePath, sourceFile) {
         browser: cmd.browser ?? true,
         args: toManifestArgs(cmd.args),
         columns: cmd.columns,
-        timeout: cmd.timeoutSeconds,
-        deprecated: cmd.deprecated,
-        replacedBy: cmd.replacedBy,
+        defaultFormat: cmd.defaultFormat,
         type: 'js',
         modulePath,
         sourceFile,
         navigateBefore: cmd.navigateBefore,
+        browserSession: cmd.browserSession,
     };
 }
 /**

package/dist/src/build-manifest.test.js

@@ -46,8 +46,7 @@ describe('manifest helper rules', () => {
                 ],
                 domain: 'localhost',
                 navigateBefore: 'https://example.com/session',
-                deprecated: 'legacy command',
-                replacedBy: 'opencli demo new',
+                defaultFormat: 'plain',
             }),
         }));
         expect(entries).toMatchObject([
@@ -74,8 +73,7 @@ describe('manifest helper rules', () => {
                 type: 'js',
                 modulePath: `${site}/${site}.js`,
                 navigateBefore: 'https://example.com/session',
-                deprecated: 'legacy command',
-                replacedBy: 'opencli demo new',
+                defaultFormat: 'plain',
             },
         ]);
         // Verify sourceFile is included and stable for manifest consumers.
@@ -96,8 +94,6 @@ describe('manifest helper rules', () => {
                 name: 'legacy',
                 access: 'read',
                 description: 'legacy command',
-                deprecated: 'legacy is deprecated',
-                replacedBy: 'opencli demo new',
             });
             return {};
         });
@@ -112,8 +108,6 @@ describe('manifest helper rules', () => {
                 args: [],
                 type: 'js',
                 modulePath: `${site}/${site}.js`,
-                deprecated: 'legacy is deprecated',
-                replacedBy: 'opencli demo new',
             },
         ]);
         // Verify sourceFile is included

package/dist/src/capabilityRouting.d.ts

@@ -1,4 +1,19 @@
 import type { CliCommand } from './registry.js';
-/** Pipeline steps that require a live browser session. */
+/**
+ * Pipeline steps that require a live browser session.
+ *
+ * Note: this is the *subset* of registered pipeline steps that need a page;
+ * non-browser steps (fetch, select, map, filter, sort, limit, download)
+ * deliberately stay out. The full registered-step list lives in
+ * `src/pipeline/registry.ts` and is re-derived elsewhere via
+ * `getRegisteredStepNames()` (e.g. in `validate.ts`). When you add a new
+ * pipeline step, decide whether it belongs here based on whether its handler
+ * touches the IPage object — and `src/capabilityRouting.test.ts` verifies the
+ * subset relationship is intact.
+ */
 export declare const BROWSER_ONLY_STEPS: Set<string>;
+/** Internal helper: ensure BROWSER_ONLY_STEPS is a subset of registered pipeline steps. */
+export declare function _validateBrowserOnlyStepsAgainstRegistry(): {
+    extras: string[];
+};
 export declare function shouldUseBrowserSession(cmd: CliCommand): boolean;

package/dist/src/capabilityRouting.js

@@ -1,8 +1,21 @@
-/** Pipeline steps that require a live browser session. */
+import { getRegisteredStepNames } from './pipeline/registry.js';
+/**
+ * Pipeline steps that require a live browser session.
+ *
+ * Note: this is the *subset* of registered pipeline steps that need a page;
+ * non-browser steps (fetch, select, map, filter, sort, limit, download)
+ * deliberately stay out. The full registered-step list lives in
+ * `src/pipeline/registry.ts` and is re-derived elsewhere via
+ * `getRegisteredStepNames()` (e.g. in `validate.ts`). When you add a new
+ * pipeline step, decide whether it belongs here based on whether its handler
+ * touches the IPage object — and `src/capabilityRouting.test.ts` verifies the
+ * subset relationship is intact.
+ */
 export const BROWSER_ONLY_STEPS = new Set([
     'navigate',
     'click',
     'type',
+    'fill',
     'wait',
     'press',
     'snapshot',
@@ -10,6 +23,16 @@ export const BROWSER_ONLY_STEPS = new Set([
     'intercept',
     'tap',
 ]);
+/** Internal helper: ensure BROWSER_ONLY_STEPS is a subset of registered pipeline steps. */
+export function _validateBrowserOnlyStepsAgainstRegistry() {
+    const registered = new Set(getRegisteredStepNames());
+    const extras = [];
+    for (const step of BROWSER_ONLY_STEPS) {
+        if (!registered.has(step))
+            extras.push(step);
+    }
+    return { extras };
+}
 function pipelineNeedsBrowserSession(pipeline) {
     return pipeline.some((step) => {
         if (!step || typeof step !== 'object')

package/dist/src/capabilityRouting.test.js

@@ -1,6 +1,7 @@
 import { describe, expect, it } from 'vitest';
 import { Strategy } from './registry.js';
-import { shouldUseBrowserSession } from './capabilityRouting.js';
+import { BROWSER_ONLY_STEPS, _validateBrowserOnlyStepsAgainstRegistry, shouldUseBrowserSession } from './capabilityRouting.js';
+import { getRegisteredStepNames } from './pipeline/registry.js';
 function makeCmd(partial) {
     return {
         site: 'test',
@@ -42,4 +43,21 @@ describe('shouldUseBrowserSession', () => {
             func: async () => [],
         }))).toBe(true);
     });
+    it('routes pipelines containing the fill step into a browser session', () => {
+        expect(shouldUseBrowserSession(makeCmd({
+            browser: true,
+            strategy: Strategy.PUBLIC,
+            pipeline: [{ navigate: 'https://example.com' }, { fill: { ref: '#q', text: 'hello' } }],
+        }))).toBe(true);
+    });
+});
+describe('BROWSER_ONLY_STEPS / pipeline registry alignment', () => {
+    it('is a subset of registered pipeline step names', () => {
+        const { extras } = _validateBrowserOnlyStepsAgainstRegistry();
+        expect(extras).toEqual([]);
+    });
+    it('includes fill (DOM-touching step added in PR #1222)', () => {
+        expect(BROWSER_ONLY_STEPS.has('fill')).toBe(true);
+        expect(getRegisteredStepNames()).toContain('fill');
+    });
 });

package/dist/src/cli.js

@@ -8,7 +8,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { Command } from 'commander';
+import { Command, InvalidArgumentError } from 'commander';
 import { styleText } from 'node:util';
 import { findPackageRoot, getBuiltEntryCandidates } from './package-paths.js';
 import { fullName, getRegistry, strategyLabel } from './registry.js';
@@ -18,7 +18,7 @@ import { PKG_VERSION } from './version.js';
 import { printCompletionScript } from './completion.js';
 import { loadExternalClis, executeExternalCli, installExternalCli, registerExternalCli, isBinaryInstalled } from './external.js';
 import { registerAllCommands } from './commanderAdapter.js';
-import { formatRootAdapterHelpText, installStructuredHelp, rootHelpData } from './help.js';
+import { classifyAdapter, formatRootAdapterHelpText, installStructuredHelp, rootHelpData } from './help.js';
 import { EXIT_CODES, getErrorMessage, BrowserConnectError } from './errors.js';
 import { TargetError } from './browser/target-errors.js';
 import { resolveTargetJs, getTextResolvedJs, getValueResolvedJs, getAttributesResolvedJs, selectResolvedJs, isAutocompleteResolvedJs } from './browser/target-resolver.js';
@@ -316,7 +316,9 @@ async function resolveStoredBrowserTarget(page, scope = DEFAULT_BROWSER_WORKSPAC
 async function getBrowserPage(targetPage, workspace = DEFAULT_BROWSER_WORKSPACE, contextId) {
     const { BrowserBridge } = await import('./browser/index.js');
     const bridge = new BrowserBridge();
-    const envTimeout = process.env.OPENCLI_BROWSER_TIMEOUT;
+    // Idle timeout: how long the browser workspace lease stays alive between commands
+    // (controls when the automation tab is released). Not the per-command runtime timeout.
+    const envTimeout = process.env.OPENCLI_BROWSER_IDLE_TIMEOUT;
     const idleTimeout = envTimeout ? parseInt(envTimeout, 10) : undefined;
     const page = await bridge.connect({
         timeout: 30,
@@ -389,6 +391,16 @@ function parsePositiveIntOption(val, label, fallback) {
     }
     return parsed;
 }
+function parseScreenshotDim(val, label) {
+    if (!/^\d+$/.test(val)) {
+        throw new InvalidArgumentError(`--${label} must be a positive integer (got "${val}")`);
+    }
+    const parsed = parseInt(val, 10);
+    if (parsed <= 0) {
+        throw new InvalidArgumentError(`--${label} must be a positive integer (got "${val}")`);
+    }
+    return parsed;
+}
 function applyVerbose(opts) {
     if (opts.verbose)
         process.env.OPENCLI_VERBOSE = '1';
@@ -888,14 +900,22 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
         console.log(JSON.stringify(frames, null, 2));
     }));
     addBrowserTabOption(browser.command('screenshot').argument('[path]', 'Save to file (base64 if omitted)'))
+        .option('--full-page', 'Capture the full scrollable page, not just the viewport', false)
+        .option('--width <n>', 'Override viewport width in CSS pixels for this screenshot only', (v) => parseScreenshotDim(v, 'width'))
+        .option('--height <n>', 'Override viewport height in CSS pixels for this screenshot only (ignored with --full-page)', (v) => parseScreenshotDim(v, 'height'))
         .description('Take screenshot')
-        .action(browserAction(async (page, path) => {
+        .action(browserAction(async (page, path, opts) => {
+        const shotOpts = {
+            fullPage: opts.fullPage === true,
+            width: opts.width,
+            height: opts.height,
+        };
         if (path) {
-            await page.screenshot({ path });
+            await page.screenshot({ ...shotOpts, path });
             console.log(`Screenshot saved to: ${path}`);
         }
         else {
-            console.log(await page.screenshot({ format: 'png' }));
+            console.log(await page.screenshot({ ...shotOpts, format: 'png' }));
         }
     }));
     addBrowserTabOption(browser.command('console'))
@@ -1313,6 +1333,33 @@ export function createProgram(BUILTIN_CLIS, USER_CLIS) {
             autocomplete: !!isAutocomplete,
         }, null, 2));
     }));
+    addBrowserTabOption(browser.command('fill')
+        .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector')
+        .argument('<text>', 'Text to set exactly')
+        .option('--nth <n>', 'When <target> is a multi-match CSS selector, pick the nth match (0-based)')
+        .description('Set input/textarea/contenteditable text exactly and verify the value — JSON envelope {filled, verified, text, actual}'))
+        .action(browserAction(async (page, target, text, opts) => {
+        const parsed = nthToResolveOpts(opts?.nth);
+        if ('error' in parsed) {
+            console.log(JSON.stringify({ error: { code: 'usage_error', message: parsed.error } }, null, 2));
+            process.exitCode = EXIT_CODES.USAGE_ERROR;
+            return;
+        }
+        const result = await page.fillText(String(target), String(text), parsed.opts);
+        if (!result.verified)
+            process.exitCode = EXIT_CODES.GENERIC_ERROR;
+        console.log(JSON.stringify({
+            filled: result.filled,
+            verified: result.verified,
+            target: String(target),
+            text: String(text),
+            actual: result.actual,
+            length: result.length,
+            matches_n: result.matches_n,
+            match_level: result.match_level,
+            ...(result.mode ? { mode: result.mode } : {}),
+        }, null, 2));
+    }));
     addBrowserTabOption(browser.command('select')
         .argument('<target>', 'Numeric ref (from browser state / find) or CSS selector of a <select> element')
         .argument('<option>', 'Option text (or value) to select')
@@ -2036,10 +2083,10 @@ cli({
         }
     });
     // ── Session ──
-    browser.command('close').description('Close the automation window')
+    browser.command('close').description('Release the current automation tab lease')
         .action(browserAction(async (page) => {
         await page.closeWindow?.();
-        console.log('Automation window closed');
+        console.log('Automation tab lease released');
     }));
     // ── Built-in: doctor / completion ──────────────────────────────────────────
     program
@@ -2539,11 +2586,29 @@ cli({
     siteGroups.set('antigravity', antigravityCmd);
     const siteNames = registerAllCommands(program, siteGroups);
     applyRootSubcommandSummaries(program);
-    const siteNameSet = new Set(siteNames);
+    // ── Help-text grouping: External CLIs / App adapters / Site adapters ──
+    // Classification derives from each adapter's `domain` field — see classifyAdapter.
+    // External CLIs are taken from the externalClis registry (passthrough binaries).
+    const externalNames = externalClis.map(ext => ext.name);
+    const siteDomains = new Map();
+    for (const [, cmd] of getRegistry()) {
+        if (!siteDomains.has(cmd.site))
+            siteDomains.set(cmd.site, cmd.domain);
+    }
+    const apps = [];
+    const sites = [];
+    for (const site of siteNames) {
+        if (classifyAdapter(siteDomains.get(site)) === 'app')
+            apps.push(site);
+        else
+            sites.push(site);
+    }
+    const adapterGroups = { external: externalNames, apps, sites };
+    const adapterNameSet = new Set([...externalNames, ...siteNames]);
     program.configureHelp({
-        visibleCommands: (command) => command.commands.filter(child => command !== program || !siteNameSet.has(child.name())),
+        visibleCommands: (command) => command.commands.filter(child => command !== program || !adapterNameSet.has(child.name())),
     });
-    installStructuredHelp(program, () => rootHelpData(program, siteNames), () => formatRootAdapterHelpText(siteNames));
+    installStructuredHelp(program, () => rootHelpData(program, adapterGroups), () => formatRootAdapterHelpText(adapterGroups));
     // ── Unknown command fallback ──────────────────────────────────────────────
     // Security: do NOT auto-discover and register arbitrary system binaries.
     // Only explicitly registered external CLIs are allowed.