Global Command Surface

Position

Cmd+K is the Global Command Surface for Prox OS. It is a Shell-level capability, not a feature owned by Desktop Runtime or any other individual Studio Engine. The visible commands depend on the current Studio, active App, AI suggestions, debug providers, and registered app launchers.

Cmd+K is not only a command palette. It is the operating surface for summoning, generating, opening, connecting, and executing apps and agents inside Prox OS.

For Raycast-class positioning, product bars, and anti-copy boundaries, pair this document with command-surface-competitive-analysis.md.

Cmd+K expresses explicit user intent. It is not Alma, and it is not the Slash Menu.

Slash Menu = local insert
Cmd+K = global command
Alma = ambient observer
AI Entry = full-screen agent workflow for Studio creation

Current Implementation

• UI primitive: packages/ui/os-ui/src/shell/CommandSurface.tsx
• Shared command contract: packages/ui/command/src/types.ts
• Shell model: apps/os-shell/src/shell/state/useCommandModel.tsx
• App source: apps/os-shell/src/shell/command/commandPaletteApps.ts
• Launcher wiring: apps/os-shell/src/shell/DesktopScene.tsx
• Shortcut boundary: apps/os-shell/src/shell/GlobalShortcuts.tsx
• Overlay scope: viewport-level Shell overlay that covers Studio content and Alma.

The palette opens from Cmd+K on macOS and Ctrl+K on Windows/Linux. It keeps focus in the search input, supports ArrowUp and ArrowDown navigation, opens registered apps with Enter, and separates Runtime Search from Studio Search. Runtime Search presents Desktop Runtime first and may include app-launching actions. Studio Search presents Studio Engine sessions and scoped Studio commands.

The palette belongs to the Shell, not to an individual Studio surface. It covers the workspace and Alma so explicit user intent always has one global entry point.

Spatial Summoning Verbs

The command surface should organize future capability around five verbs:

Execute-class commands must never become silent automation. Future execution requires permission preview, manual confirmation, audit logs, cost budgets, revocation, and clear failure handling.

Relationship To The Desktop Runtime

Cmd+K should not hardcode app routes outside registry adapters. Open commands must still resolve through registered manifests. Future summon/generate/connect commands should produce reviewable proposals before mutating Spaces, app manifests, connectors, or workflows.

Context Model

The shared v0 contract lives in @prox-os/command:

export type CommandContext = {
  studioId?: string
  studioEngineId: StudioEngineId
  activeAppId?: string
  activeSurfaceId?: string
}

export type CommandProvider = {
  id: string
  label: string
  getCommands: (context: CommandContext) => Command[]
}

The Shell currently builds command sections from:

• Runtime Search results, including Desktop Runtime and app registry launchers;
• recent app results inside Runtime Search;
• global placeholder actions;
• current Studio Engine mock commands;
• Weather commands that demonstrate command versus slash versus Alma roles.

Visible Studio engines expose v0 mock commands in the Shell model so opening Cmd+K under Desktop Runtime, Atlas, Grid, or Ops shows a context change. Local-only engines can expose commands while opened manually under /dev/studios/*, but they should not appear in public Studio switchers.

Shortcut Priority

Default behavior:

• Cmd+K / Ctrl+K opens the Global Command Surface.
• Editors, Slash Menu, iframe apps, and Alma use their own focused shortcuts without intercepting the global Cmd+K contract.
• Editable fields may still own normal typing behavior, but the documented command entry remains the Shell-level global surface.

Relationship To Alma

Alma may suggest commands, explain what a command would do, and present an Action Card that points into the Command Registry. Alma should not silently execute global commands without user confirmation.

Cmd+K is the user's explicit command entry. Alma is the contextual sidecar. Alma can observe active context and suggest next actions; Cmd+K is where the user selects, scopes, previews, and confirms the command.

Example:

• Cmd+K: "Open Weather App" and "Add Weather Widget to Current Studio".
• Slash Menu: "Insert Weather Block Here".
• Alma: "You are planning travel. Add weather context?"

Result Model

The display model is intentionally UI-level:

• app results from the app registry;
• recent app results from local shell preference state;
• Studio Engine commands;
• disabled placeholder actions for AI and OS workflows;
• route, category, status, tags, permission posture, and future capability metadata;
• selected result preview and footer keyboard hints.

Real command execution, permissions, audit, and async status remain future runtime work. The v0 mock commands show local system toasts or open existing registered apps.

Future Path

Future work can connect Cmd+K to:

• engine-owned command providers;
• app-owned scoped command providers;
• window actions and layout presets;
• docs and semantic search;
• prompt templates;
• app contract permissions;
• Activity and audit logs;
• AI action registry entries.
• Space-aware summon/generate/connect proposals;
• Agent Registry entries with scopes, budgets, and run history;
• permission preview and manual confirmation for execute-class commands.

Those additions should preserve registry-driven app launches and should not duplicate app routing logic inside the palette.