@timurproko/a1 0.1.8-dev.563 → 0.1.8-dev.572

package/README.md

@@ -24,13 +24,15 @@ npm install -g @timurproko/a1@0.1.8-dev.107
 
 ```sh
 a1                                      # launch A1 (profile: ~/.a1/agent)
-a1 --help                               # show all commands (short form: a1 -h)
-a1 --version                            # show the version (short form: a1 -v)
+a1 help                                 # show all commands
+a1 version                              # show the version
 a1 update                               # install the newest stable release
 a1 update --develop                     # install the current development preview
 a1 update --develop 107                 # install numbered preview 107
 a1 update --develop 0.1.8-dev.107       # install that exact preview
 a1 update --models                      # refresh A1's model catalogs
+a1 update --extensions                  # update every installed package
+a1 update npm:pi-mcp-adapter            # update one package
 ```
 
 Stable builds print only their installed version. Development builds also show the
@@ -47,17 +49,17 @@ Unsupported commands exit quietly without launching anything. The removed
 
 ## Extensions
 
-Pi extension packages install into A1's own profile (`~/.a1/agent`), so bare `a1`
-loads them and `a1 pi` does not. Sources are Pi's: `npm:`, git, or a
-local path.
+Pi-compatible extension packages install into A1's own profile (`~/.a1/agent`), so
+bare `a1` loads them and the `a1 pi` comparison profile does not. Sources use Pi's
+`npm:`, git, or local-path grammar.
 
 ```sh
-a1 pi install npm:pi-mcp-adapter   # install a package
-a1 pi remove npm:pi-mcp-adapter    # remove it (alias: a1 pi uninstall)
-a1 pi list                         # list installed packages
-a1 pi update --extensions          # update every installed package
-a1 pi update npm:pi-mcp-adapter    # update one
-a1 pi update --models              # refresh A1's model catalogs
+a1 install npm:pi-mcp-adapter      # install a package
+a1 remove npm:pi-mcp-adapter       # remove it (alias: a1 uninstall)
+a1 list                            # list installed packages
+a1 update --extensions             # update every installed package
+a1 update npm:pi-mcp-adapter       # update one
+a1 update --models                 # refresh A1's model catalogs
 ```
 
 A1 pins the Pi runtime carried by each release, so Pi self-update forms are refused.

package/dist/app/session-shell/session-shell-root.js

@@ -3,7 +3,7 @@ import { caretCell } from "../../ui/components/line-input.js";
 import { PromptInput, promptArrow } from "../../ui/components/prompt-input.js";
 import { composeSubmittedPromptRows, formatSubmittedPromptTime, submittedPromptLayout, } from "../../ui/components/submitted-prompt.js";
 import { backgroundSgrSpan, heldNativeHyperlinkStyle, hyperlinkSgrSpan, nativeHyperlinkStyle, overlaySpan, } from "../../ui/components/spans.js";
-import { progressStatusText } from "../../ui/components/progress-status.js";
+import { progressStatusFrame, progressStatusText } from "../../ui/components/progress-status.js";
 import { displayWidth, faint, stripAnsi } from "../../ui/components/text.js";
 import { PINNED_PI_HIDDEN_COMMAND_NAMES, PINNED_PI_WORKFLOW_COMMAND_NAMES } from "../../integrations/pi/engine/workflows.js";
 import { createPiExtensionUiBridge } from "../../integrations/pi/components/shell-extension-ui.js";
@@ -106,10 +106,12 @@ export class OwnedUiSessionShellRoot {
             ...(this.#customViewport ? { getKeybindings: () => this.editor.keybindingConfig() } : {}),
         });
         this.resources = createPiShellLoadedResources(startup.resources ?? [], startup.expanded ?? false);
-        this.#status = createPiShellStatus(view, progressStatusText, handlers);
+        this.#status = createPiShellStatus(view, {
+            text: (message, mode) => progressStatusText(message, mode === "custom-viewport" ? "…" : "..."),
+            frame: progressStatusFrame,
+        }, handlers);
         this.#status.setProgressPresentation(this.#customViewport ? "custom-viewport" : "pinned");
         this.#footer = createPiShellFooter(this.#viewWithExtensionStatuses(view), cwd, this.#customViewport ? "a1" : "pi", () => this.#footerLevel);
-        this.#queued = createPiQueuedInputStatus(view.editor.queuedSubmissions, this.#customViewport ? "custom-viewport" : "pinned");
         this.editor = createPiShellEditor({
             ...handlers,
             keybindingProfile: this.#customViewport ? "a1" : "pi",
@@ -183,6 +185,7 @@ export class OwnedUiSessionShellRoot {
             },
             ...(handlers.onPromptSuggestionAccepted === undefined ? {} : { onPromptSuggestionAccepted: handlers.onPromptSuggestionAccepted }),
         });
+        this.#queued = createPiQueuedInputStatus(view.editor.queuedSubmissions, this.#customViewport ? "custom-viewport" : "pinned", this.#customViewport ? () => this.editor.keybindingConfig() : undefined);
         this.#viewportController = new SessionViewportController({
             enabled: this.#customViewport,
             editor: this.editor,

package/dist/app/session-shell/session-shell.js

@@ -356,7 +356,13 @@ export class OwnedUiSessionShell {
                 }
                 const routed = this.root.handleViewportPreInput(data, true, Date.now(), this.root.usesDefaultInputSurface() && !this.runtime.hasFocusedOverlay());
                 if (routed.copySelection !== undefined) {
-                    void this.#responseCopy?.submit(routed.copySelection, pendingClipboardWrite);
+                    const snapshot = routed.copySelection;
+                    void this.#responseCopy?.submit(snapshot, pendingClipboardWrite).then(result => {
+                        if (this.#disposed || !runtime.active
+                            || result.outcome !== "delivered" && result.outcome !== "submitted-unverified")
+                            return;
+                        runtime.showFlash(`Copied ${snapshot.sourceUnits} character${snapshot.sourceUnits === 1 ? "" : "s"} to clipboard`);
+                    });
                 }
                 if (!routed.consumed)
                     return routed.data === data ? undefined : { data: routed.data };

package/dist/app/session-shell/session-viewport-controller.js

@@ -28,12 +28,14 @@ export class SessionViewportController {
     #inputSurfacePending = false;
     #overlays = [];
     #pointerOwner;
-    // Invariant: a left-button sequence begun in dock chrome remains owned by the dock.
+    // Invariant: a right-click editor gesture remains owned by the dock.
     #dockPointerSuppressed = false;
-    // Invariant: a left-button sequence begun in non-selectable transcript tail chrome is held there.
+    // Invariant: a gesture begun on an explicit control remains owned by that control.
     #tailPointerSuppressed = false;
     // Invariant: editor selection remains true only while its left button is held.
     #editorPointerSelecting = false;
+    // Invariant: no-drag editor presses replay on release; distinct motion promotes frame selection.
+    #pendingEditorClick;
     // Invariant: pointer routing uses the most recently composed editor rows.
     #editorPointerFrame;
     #selectionAutoScrollTimer;
@@ -112,9 +114,19 @@ export class SessionViewportController {
             this.#cancelGesture();
         this.#viewport.setConfig(this.#config);
         const selectionRevision = this.#viewport.selectionRevision;
+        const coveredSurfaces = [
+            ...(this.#overlays ?? []),
+            ...(this.#inputSurface === undefined ? [] : [this.#inputSurface]),
+        ];
+        const coveredCells = coveredSurfaces.flatMap(surface => Array.from({ length: Math.max(0, surface.rowEnd - surface.rowStart + 1) }, (_value, index) => ({
+            row: surface.rowStart + index,
+            columnStart: surface.columnStart,
+            columnEnd: surface.columnEnd,
+        })));
         const frame = this.#viewport.compose({
             ...input,
             ...(this.#pointerPosition === undefined ? {} : { pointerPosition: this.#pointerPosition }),
+            ...(coveredCells.length === 0 ? {} : { coveredCells }),
         });
         // Concurrency: if selection changed during composition, this frame truthfully carries
         // the older revision and exactly one ordinary follow-up render publishes the latest.
@@ -167,6 +179,7 @@ export class SessionViewportController {
         this.#clearActivityTimer();
         this.#stopSelectionAutoScroll();
         this.#editorPointerSelecting = false;
+        this.#pendingEditorClick = undefined;
         this.#editorPointerFrame = undefined;
         this.#pointerPosition = undefined;
         this.#hoveredHyperlinkKey = undefined;
@@ -183,6 +196,7 @@ export class SessionViewportController {
         this.#dockPointerSuppressed = false;
         this.#tailPointerSuppressed = false;
         this.#editorPointerSelecting = false;
+        this.#pendingEditorClick = undefined;
         this.#editorPointerFrame = undefined;
         this.#pointerPosition = undefined;
         this.#hoveredHyperlinkKey = undefined;
@@ -302,6 +316,7 @@ export class SessionViewportController {
         let repaint = false;
         let forceRepaint = false;
         let activity = false;
+        let completedCopy;
         const routed = routeMouseInput(data, (event, report) => {
             const hits = frame.hits;
             const overModal = this.#modalAt(event.column, event.row);
@@ -375,6 +390,10 @@ export class SessionViewportController {
                     return true;
                 if (this.#viewport.selectionActive) {
                     this.#viewport.extendSelection(event.column, event.row, now, false);
+                    if (this.#pendingEditorClick !== undefined
+                        && (event.column !== this.#pendingEditorClick.column || event.row !== this.#pendingEditorClick.row)) {
+                        this.#pendingEditorClick = undefined;
+                    }
                     this.#updateSelectionAutoScroll(event.column, event.row, hits.viewportHeight);
                     activity = true;
                     return true;
@@ -415,17 +434,20 @@ export class SessionViewportController {
                     return false;
                 this.#dockPointerSuppressed = false;
                 this.#tailPointerSuppressed = false;
+                this.#pendingEditorClick = undefined;
                 this.#stopSelectionAutoScroll();
                 if (this.#viewport.clearSelection())
                     repaint = true;
                 if (overBottom) {
                     this.#viewport.scrollToEnd(now);
+                    this.#tailPointerSuppressed = true;
                     activity = true;
                     repaint = true;
                     return true;
                 }
                 if (overSticky && hits.sticky !== null) {
                     this.#viewport.scrollTo(hits.sticky.target, now);
+                    this.#tailPointerSuppressed = true;
                     activity = true;
                     repaint = true;
                     return true;
@@ -439,35 +461,19 @@ export class SessionViewportController {
                     }
                     else {
                         this.#viewport.scrollTo(scrollForTrackPage(geometry, trackRow, frame.scrollTop, hits.viewportHeight), now);
+                        this.#tailPointerSuppressed = true;
                     }
                     activity = true;
                     repaint = true;
                     return true;
                 }
-                if (editorFrame !== undefined && event.row >= editorFrame.rowStart && event.row <= editorFrame.rowEnd) {
-                    const handled = this.#editor.handlePointer({
-                        kind: "press",
-                        button: event.button,
-                        column: event.column,
-                        row: event.row - editorFrame.rowStart + 1,
-                    });
-                    if (!handled)
-                        this.#dockPointerSuppressed = true;
-                    this.#editorPointerSelecting = handled;
-                    repaint = true;
-                    return true;
-                }
-                if (event.row > hits.viewportHeight) {
-                    this.#dockPointerSuppressed = true;
-                    return true;
-                }
-                if (event.row >= 1 && event.row <= hits.viewportHeight && event.column <= frame.contentWidth) {
-                    if (!this.#viewport.pressSelection(event.column, event.row, now)) {
-                        // Invariant: empty rows and transient tail rows must never start Pi selection.
-                        this.#tailPointerSuppressed = true;
-                        repaint = true;
-                        return true;
+                if (event.row >= 1 && event.row <= frame.rows.length && event.column <= frame.descriptor.width) {
+                    if (editorFrame !== undefined && event.row >= editorFrame.rowStart && event.row <= editorFrame.rowEnd) {
+                        this.#pendingEditorClick = { column: event.column, row: event.row };
                     }
+                    // Invariant: frame selection includes transient and dock rows without changing
+                    // semantic ownership; no-drag editor presses replay on release.
+                    this.#viewport.pressSelection(event.column, event.row, now);
                     repaint = true;
                     return true;
                 }
@@ -490,6 +496,17 @@ export class SessionViewportController {
                 }
                 if (this.#viewport.releaseSelection()) {
                     this.#stopSelectionAutoScroll();
+                    const pendingEditorClick = this.#pendingEditorClick;
+                    this.#pendingEditorClick = undefined;
+                    if (pendingEditorClick !== undefined && this.#editorPointerFrame !== undefined) {
+                        this.#viewport.clearSelection();
+                        const editorRow = pendingEditorClick.row - this.#editorPointerFrame.rowStart + 1;
+                        this.#editor.handlePointer({ kind: "press", button: 0, column: pendingEditorClick.column, row: editorRow });
+                        this.#editor.handlePointer({ kind: "release", button: 0, column: pendingEditorClick.column, row: editorRow });
+                    }
+                    else {
+                        completedCopy = this.#viewport.captureSelectedText() ?? undefined;
+                    }
                     // Platform: restore OSC 8 links only after the held-button selection paint has
                     // ended, then overwrite any terminal-cached hover cells immediately.
                     forceRepaint = true;
@@ -519,7 +536,7 @@ export class SessionViewportController {
             this.#lastRequestedSelectionRevision = this.#viewport.selectionRevision;
             this.#requestRender(forceRepaint);
         }
-        return routed;
+        return completedCopy === undefined ? routed : { ...routed, copySelection: completedCopy };
     }
     #modalAt(column, row) {
         const contains = (surface) => column >= surface.columnStart && column <= surface.columnEnd
@@ -534,13 +551,13 @@ export class SessionViewportController {
             .find(candidate => column - 1 >= candidate.from && column - 1 < candidate.to);
         return range === undefined ? undefined : JSON.stringify([row, range]);
     }
-    #updateSelectionAutoScroll(column, row, viewportHeight) {
-        const beyondEdge = row <= 1 || row > viewportHeight;
+    #updateSelectionAutoScroll(column, row, frameHeight) {
+        const beyondEdge = row <= 1 || row >= frameHeight;
         if (!beyondEdge) {
             this.#stopSelectionAutoScroll();
             return;
         }
-        this.#selectionAutoScrollPointer = { column, row };
+        this.#selectionAutoScrollPointer = { column, row, direction: row <= 1 ? -1 : 1 };
         if (this.#selectionAutoScrollTimer !== undefined)
             return;
         this.#selectionAutoScrollTimer = setTimeout(() => this.#selectionAutoScrollTick(), SELECTION_AUTO_SCROLL_INTERVAL_MS);
@@ -557,7 +574,8 @@ export class SessionViewportController {
         const rowsPerTick = scrollbarSelectionRows(this.#config.scrollbarSpeed);
         for (let row = 0; row < rowsPerTick; row += 1) {
             const previous = this.#viewport.scrollTop;
-            this.#viewport.extendSelection(pointer.column, pointer.row);
+            this.#viewport.scrollBy(pointer.direction);
+            this.#viewport.extendSelection(pointer.column, pointer.row, undefined, false);
             if (this.#viewport.scrollTop === previous)
                 break;
         }

package/dist/cli/dispatch.d.ts

@@ -2,7 +2,7 @@ import { type InteractiveLaunchIntent, type LaunchProfileId, type SessionSelecti
 import type { CliCapabilities } from "./capabilities.js";
 import type { PackageCommandRequest } from "./packages.js";
 import type { SessionContextRequest } from "./session-context.js";
-import { type PackageCliVerb, type PackageSyntaxDiagnostic } from "./package-messages.js";
+import { type PackageCliVerb, type PackageCommandNamespace, type PackageSyntaxDiagnostic } from "./package-messages.js";
 export type UpdateChannel = "stable" | "next";
 export interface CliHandlers {
     readonly launch: (intent: InteractiveLaunchIntent) => Promise<number>;
@@ -25,9 +25,11 @@ export type CliCommand = {
 } | {
     readonly kind: "package-help";
     readonly verb: PackageCliVerb;
+    readonly namespace: PackageCommandNamespace;
 } | {
     readonly kind: "package-error";
     readonly diagnostic: PackageSyntaxDiagnostic;
+    readonly namespace: PackageCommandNamespace;
 } | {
     readonly kind: "launch";
     readonly profileId: LaunchProfileId;

package/dist/cli/dispatch.js

@@ -1,5 +1,5 @@
 import { interactiveLaunchIntent, parseSessionSelection } from "../features/launch/index.js";
-import { packageCommandHelp, renderPackageSyntax } from "./package-messages.js";
+import { packageCommandHelp, renderPackageSyntax, } from "./package-messages.js";
 import { PRODUCT_TEXT } from "../product-identity.js";
 export function cliUsage(capabilities) {
     return PRODUCT_TEXT.usage([
@@ -7,22 +7,19 @@ export function cliUsage(capabilities) {
         "--session <path|id>",
         "--session-dir <dir> --session <path|id>",
         ...(capabilities.developmentComparison ? ["pi"] : []),
-        "--help",
-        "-h",
-        "--version",
-        "-v",
+        "help",
+        "version",
         "update",
         "update --develop [preview-or-version]",
         "update --models",
+        "update --extensions",
+        "update <source>",
+        "install <source>",
+        "remove <source>",
+        "uninstall <source>",
+        "list",
         "session link-worktree <path>",
         "session unlink-worktree",
-        "pi install <source>",
-        "pi remove <source>",
-        "pi uninstall <source>",
-        "pi list",
-        "pi update --extensions",
-        "pi update --models",
-        "pi update <source>",
     ]);
 }
 export function cliHelp(capabilities) {
@@ -33,29 +30,26 @@ export function cliHelp(capabilities) {
         `  ${command} --session <path|id>`,
         `  ${command} --session-dir <dir> --session <path|id>`,
         ...(capabilities.developmentComparison ? [`  ${command} pi`] : []),
-        `  ${command} --help`,
-        `  ${command} -h`,
-        `  ${command} --version`,
-        `  ${command} -v`,
+        `  ${command} help`,
+        `  ${command} version`,
         "",
         "Update:",
         `  ${command} update`,
         `  ${command} update --develop [preview-or-version]`,
         `  ${command} update --models`,
+        `  ${command} update --extensions`,
+        `  ${command} update <source>`,
+        "",
+        "Packages:",
+        `  ${command} install <source>`,
+        `  ${command} remove <source>`,
+        `  ${command} uninstall <source>`,
+        `  ${command} list`,
         "",
         "Session context:",
         `  ${command} session link-worktree <path>`,
         `  ${command} session unlink-worktree`,
         "",
-        "Pi-compatible packages:",
-        `  ${command} pi install <source>`,
-        `  ${command} pi remove <source>`,
-        `  ${command} pi uninstall <source>`,
-        `  ${command} pi list`,
-        `  ${command} pi update --extensions`,
-        `  ${command} pi update --models`,
-        `  ${command} pi update <source>`,
-        "",
     ].join("\n");
 }
 const PROFILE_WORDS = new Set(["pi"]);
@@ -68,11 +62,11 @@ export async function dispatchCli(arguments_, handlers, output, capabilities) {
         return 0;
     }
     if (command.kind === "package-help") {
-        output.stdout(packageCommandHelp(command.verb));
+        output.stdout(packageCommandHelp(command.verb, command.namespace));
         return 0;
     }
     if (command.kind === "package-error") {
-        output.stderr(renderPackageSyntax(command.diagnostic));
+        output.stderr(renderPackageSyntax(command.diagnostic, command.namespace));
         return 2;
     }
     if (command.kind === "error") {
@@ -102,13 +96,16 @@ export function parseCliCommand(arguments_, capabilities) {
             return { kind: "error", message: PRODUCT_TEXT.diagnostic(`could not parse session launch: ${error instanceof Error ? error.message : String(error)}`) };
         }
     }
-    if (command === "--help" || command === "-h")
+    if (command === "help" || command === "--help" || command === "-h")
         return withoutArguments(rest, { kind: "help" });
-    if (command === "--version" || command === "-v")
+    if (command === "version" || command === "--version" || command === "-v")
         return withoutArguments(rest, { kind: "version" });
+    if (command === "install" || command === "remove" || command === "uninstall" || command === "list") {
+        return parsePackageCommand(arguments_, "direct");
+    }
     if (command === "pi") {
         if (rest.length > 0)
-            return parsePiPackageCommand(rest);
+            return parsePackageCommand(rest, "pi");
         return capabilities.developmentComparison ? { kind: "launch", profileId: "pi" } : { kind: "noop" };
     }
     if (command === "update")
@@ -143,6 +140,9 @@ function parseSessionContext(rest) {
  * operation that cannot be combined with either update channel.
  */
 function parseUpdate(rest) {
+    if (rest.some(value => value === "--help" || value === "-h")) {
+        return { kind: "package-help", verb: "update", namespace: "direct" };
+    }
     if (rest.length === 0)
         return { kind: "update", channel: "stable" };
     const [selector, ...values] = rest;
@@ -167,10 +167,9 @@ function parseUpdate(rest) {
     }
     if (selector === "pi")
         return pinnedPiUpdateError();
-    if (selector !== undefined && selector.startsWith("-"))
+    if (selector === "--self" || selector === "--all")
         return unknownOption(selector, "update");
-    // Rationale: positional update targets are reserved for a future A1-native plugin model.
-    return { kind: "noop" };
+    return parsePackageUpdate(rest, "direct");
 }
 function isDevelopmentTarget(target) {
     return /^[1-9]\d*$/.test(target) || /^\d+\.\d+\.\d+-dev\.[1-9]\d*$/.test(target);
@@ -178,48 +177,49 @@ function isDevelopmentTarget(target) {
 function updateGrammarError(detail) {
     return { kind: "error", message: PRODUCT_TEXT.diagnostic(`could not parse update: ${detail}`) };
 }
-function parsePiPackageCommand(arguments_) {
+function parsePackageCommand(arguments_, namespace) {
     const [verb, ...rest] = arguments_;
     if ((verb === "install" || verb === "remove" || verb === "uninstall" || verb === "list" || verb === "update")
         && rest.some(value => value === "--help" || value === "-h")) {
-        return { kind: "package-help", verb: verb === "uninstall" ? "remove" : verb };
+        return { kind: "package-help", verb: verb === "uninstall" ? "remove" : verb, namespace };
     }
     if (verb === "install" || verb === "remove" || verb === "uninstall") {
-        return parseSourceCommand(verb === "install" ? "install" : "remove", rest);
+        return parseSourceCommand(verb === "install" ? "install" : "remove", rest, namespace);
     }
     if (verb === "list") {
         const flag = rest.find(argument => argument.startsWith("-"));
         if (flag !== undefined)
-            return packageOptionError(flag, "list");
+            return packageOptionError(flag, "list", namespace);
         if (rest[0] !== undefined)
-            return packageSyntax({ verb: "list", kind: "unexpected-argument", value: rest[0] });
+            return packageSyntax({ verb: "list", kind: "unexpected-argument", value: rest[0] }, namespace);
         return { kind: "packages", request: { verb: "list", source: null } };
     }
     if (verb === "update")
-        return parsePiPackageUpdate(rest);
+        return parsePackageUpdate(rest, namespace);
     return { kind: "noop" };
 }
-function parsePiPackageUpdate(rest) {
+function parsePackageUpdate(rest, namespace) {
     if (rest.length === 0)
         return pinnedPiUpdateError();
     if (rest.length > 1) {
         const unknown = rest.find(value => value.startsWith("-") && !["--extensions", "--models", "--self", "--all"].includes(value));
         if (unknown !== undefined)
-            return packageOptionError(unknown, "update");
+            return packageOptionError(unknown, "update", namespace);
         if (rest.includes("--self") || rest.includes("--all") || rest.includes("self") || rest.includes("pi"))
             return pinnedPiUpdateError();
         if (rest.every(value => value === rest[0]) && rest[0]?.startsWith("-")) {
-            return { kind: "error", message: PRODUCT_TEXT.diagnostic("pi update accepts one target.") };
+            const command = namespace === "direct" ? "update" : "pi update";
+            return { kind: "error", message: PRODUCT_TEXT.diagnostic(`${command} accepts one target.`) };
         }
         const sources = rest.filter(value => !value.startsWith("-"));
         if (sources[1] !== undefined)
-            return packageSyntax({ verb: "update", kind: "unexpected-argument", value: sources[1] });
+            return packageSyntax({ verb: "update", kind: "unexpected-argument", value: sources[1] }, namespace);
         const message = rest.includes("--models")
             ? rest.includes("--extensions")
                 ? "--models cannot be combined with --self, --extensions, --all, or --extension"
                 : "--models cannot be combined with a positional source"
             : "positional update targets cannot be combined with --self, --extensions, or --all";
-        return packageSyntax({ verb: "update", kind: "conflict", message });
+        return packageSyntax({ verb: "update", kind: "conflict", message }, namespace);
     }
     const [target] = rest;
     if (target === "--extensions")
@@ -229,7 +229,7 @@ function parsePiPackageUpdate(rest) {
     if (target === "--self" || target === "--all" || target === "self" || target === "pi")
         return pinnedPiUpdateError();
     if (target === undefined || target.startsWith("-"))
-        return packageOptionError(target ?? "", "update");
+        return packageOptionError(target ?? "", "update", namespace);
     return { kind: "packages", request: { verb: "update", source: target } };
 }
 function pinnedPiUpdateError() {
@@ -239,35 +239,35 @@ function pinnedPiUpdateError() {
             PRODUCT_TEXT.diagnostic("pins its certified Pi runtime and cannot update it independently."),
             "Use:",
             `  ${PRODUCT_TEXT.commandName} update                    Update a1`,
-            `  ${PRODUCT_TEXT.commandName} pi update --extensions    Update Pi-compatible packages`,
-            `  ${PRODUCT_TEXT.commandName} pi update --models        Refresh model catalogs`,
+            `  ${PRODUCT_TEXT.commandName} update --extensions       Update Pi-compatible packages`,
+            `  ${PRODUCT_TEXT.commandName} update --models           Refresh model catalogs`,
         ].join("\n"),
     };
 }
-function parseSourceCommand(verb, rest) {
+function parseSourceCommand(verb, rest, namespace) {
     const flag = rest.find(argument => argument.startsWith("-"));
     if (flag !== undefined)
-        return packageOptionError(flag, verb);
+        return packageOptionError(flag, verb, namespace);
     const [source, extra] = rest;
     if (extra !== undefined)
-        return packageSyntax({ verb, kind: "unexpected-argument", value: extra });
+        return packageSyntax({ verb, kind: "unexpected-argument", value: extra }, namespace);
     if (source === undefined)
-        return packageSyntax({ verb, kind: "missing-source" });
+        return packageSyntax({ verb, kind: "missing-source" }, namespace);
     if (PROFILE_WORDS.has(source))
         return profileRejection(verb);
     return { kind: "packages", request: { verb, source } };
 }
-function packageSyntax(diagnostic) {
-    return { kind: "package-error", diagnostic };
+function packageSyntax(diagnostic, namespace) {
+    return { kind: "package-error", diagnostic, namespace };
 }
-function packageOptionError(option, verb) {
+function packageOptionError(option, verb, namespace) {
     if (option.startsWith("--profile") || option === "-l" || option === "--local")
         return profileRejection(verb);
     // Compatibility: these recognized Pi flags remain outside A1's supported subset.
     if (["--extension", "--approve", "--no-approve", "-a", "-na", "--force"].includes(option)) {
-        return unknownOption(option, `pi ${verb}`);
+        return unknownOption(option, namespace === "direct" ? verb : `pi ${verb}`);
     }
-    return packageSyntax({ verb, kind: "unknown-option", value: option });
+    return packageSyntax({ verb, kind: "unknown-option", value: option }, namespace);
 }
 function withoutArguments(rest, command) {
     if (rest.length === 0)

package/dist/cli/package-messages.d.ts

@@ -1,6 +1,7 @@
 import chalk from "chalk";
 /** Supported subset of pinned Pi's package-manager CLI presentation. */
 export type PackageCliVerb = "install" | "remove" | "list" | "update";
+export type PackageCommandNamespace = "direct" | "pi";
 export type PackageSyntaxDiagnostic = {
     readonly verb: PackageCliVerb;
     readonly kind: "missing-source";
@@ -18,9 +19,9 @@ export type PackageSyntaxDiagnostic = {
     readonly message: string;
 };
 type MessageStyle = Pick<typeof chalk, "red" | "dim" | "bold">;
-export declare function packageCommandUsage(verb: PackageCliVerb): string;
+export declare function packageCommandUsage(verb: PackageCliVerb, namespace?: PackageCommandNamespace): string;
 /** Diagnostic facts stay unstyled until the terminal boundary decides color support. */
-export declare function renderPackageSyntax(diagnostic: PackageSyntaxDiagnostic, style?: MessageStyle): string;
+export declare function renderPackageSyntax(diagnostic: PackageSyntaxDiagnostic, namespace?: PackageCommandNamespace, style?: MessageStyle): string;
 /** Pi's help layout, with unsupported options and examples deliberately absent. */
-export declare function packageCommandHelp(verb: PackageCliVerb, style?: MessageStyle): string;
+export declare function packageCommandHelp(verb: PackageCliVerb, namespace?: PackageCommandNamespace, style?: MessageStyle): string;
 export {};

package/dist/cli/package-messages.js

@@ -2,21 +2,26 @@
 // at 914cf1472e715297caa30db4b9535d534a9eb718 (MIT); grammar is restricted to A1's supported subset.
 import chalk from "chalk";
 import { PRODUCT_TEXT } from "../product-identity.js";
-export function packageCommandUsage(verb) {
-    const command = `${PRODUCT_TEXT.commandName} pi ${verb}`;
+export function packageCommandUsage(verb, namespace = "pi") {
+    const command = namespace === "direct"
+        ? `${PRODUCT_TEXT.commandName} ${verb}`
+        : `${PRODUCT_TEXT.commandName} pi ${verb}`;
     if (verb === "install" || verb === "remove")
         return `${command} <source>`;
+    if (verb === "update" && namespace === "direct") {
+        return `${command} [--develop [preview-or-version]|--models|--extensions|source]`;
+    }
     if (verb === "update")
         return `${command} [source|--extensions|--models]`;
     return command;
 }
 /** Diagnostic facts stay unstyled until the terminal boundary decides color support. */
-export function renderPackageSyntax(diagnostic, style = chalk) {
-    const usage = packageCommandUsage(diagnostic.verb);
+export function renderPackageSyntax(diagnostic, namespace = "pi", style = chalk) {
+    const usage = packageCommandUsage(diagnostic.verb, namespace);
     let message;
     if (diagnostic.kind === "unknown-option") {
         return `${style.red(`Unknown option ${diagnostic.value} for "${diagnostic.verb}".`)}\n`
-            + `${style.dim(`Use "${PRODUCT_TEXT.commandName} --help" or "${usage}".`)}\n`;
+            + `${style.dim(`Use "${PRODUCT_TEXT.commandName} help" or "${usage}".`)}\n`;
     }
     if (diagnostic.kind === "missing-source")
         message = `Missing ${diagnostic.verb} source.`;
@@ -27,9 +32,16 @@ export function renderPackageSyntax(diagnostic, style = chalk) {
     return `${style.red(message)}\n${style.dim(`Usage: ${usage}`)}\n`;
 }
 /** Pi's help layout, with unsupported options and examples deliberately absent. */
-export function packageCommandHelp(verb, style = chalk) {
-    const command = `${PRODUCT_TEXT.commandName} pi`;
-    const header = `${style.bold("Usage:")}\n  ${packageCommandUsage(verb)}\n\n`;
+export function packageCommandHelp(verb, namespace = "pi", style = chalk) {
+    const command = namespace === "direct" ? PRODUCT_TEXT.commandName : `${PRODUCT_TEXT.commandName} pi`;
+    const header = verb === "update" && namespace === "direct"
+        ? `${style.bold("Usage:")}\n`
+            + `  ${command} update\n`
+            + `  ${command} update --develop [preview-or-version]\n`
+            + `  ${command} update --models\n`
+            + `  ${command} update --extensions\n`
+            + `  ${command} update <source>\n\n`
+        : `${style.bold("Usage:")}\n  ${packageCommandUsage(verb, namespace)}\n\n`;
     switch (verb) {
         case "install":
             return header + `Install a package and add it to settings.
@@ -55,14 +67,14 @@ Examples:
         case "list":
             return header + "List installed packages from user settings.\n\n";
         case "update":
-            return header + `Update installed packages or model catalogs.
+            return header + `${namespace === "direct" ? "Update A1, installed packages, or model catalogs." : "Update installed packages or model catalogs."}
 
 Options:
-  --extensions            Update installed packages only
+${namespace === "direct" ? "  --develop [target]     Update to the development channel or one preview\n" : ""}  --extensions            Update installed packages only
   --models                Refresh model catalogs only
 
 Short forms:
-  ${command} update --extensions   Update installed packages only
+${namespace === "direct" ? `  ${command} update                Update A1 to the stable release\n  ${command} update --develop      Update A1 to the development preview\n` : ""}  ${command} update --extensions   Update installed packages only
   ${command} update --models       Refresh model catalogs only
   ${command} update <source>       Update one package