Command Package

@prox-os/command is the shared command surface package for Prox OS. It turns apps, routes, docs, URLs, actions, settings, developer tools, and AI intents into searchable entries that can be previewed, selected, and handed to a host runtime for execution.

It consumes @prox-os/actions; it does not replace it. Actions describe intent. Commands make those intents discoverable and selectable.

Core Types

OsCommand
OsCommandKind
OsCommandScope
OsCommandSource
OsCommandContext
OsCommandResult
OsCommandHandler
OsCommandProvider
OsCommandGroup
OsCommandRegistry

Core Helpers

createActionCommand
createAppCommand
createUrlCommand
groupCommands
filterVisibleCommands
filterEnabledCommands
rankCommands
createCommandResult
createStaticCommandProvider
createCommandRegistry

React Primitives

OsCommandPalette
OsCommandInput
OsCommandList
OsCommandItem
OsCommandGroup
OsCommandEmpty
OsCommandShortcut
OsCommandLauncherButton
OsCommandPreview
OsCommandScopeBadge
OsRecentCommands

Provider Model

Phase 1 only defines a small provider contract:

export interface OsCommandProvider {
  id: string
  label: string
  source: OsCommandSource
  getCommands: (context: OsCommandContext) => OsCommand[] | Promise<OsCommand[]>
}

This is enough for Storybook, app-local commands, and future Shell adapters. It is not a plugin system yet.

Storybook

Open UI Workshop and look under Command:

Command / OsCommandPalette
Command / OsCommandItem
Command / OsCommandLauncherButton
Command / OsCommandShortcut
Command / OsRecentCommands
Command / Integration

The stories show grouped commands, search/filter behavior, preview panels, loading and empty states, disabled commands, recent commands, action commands, app launcher commands, AI commands, and developer commands.

Relationship Map

Package or surface	Relationship
`@prox-os/actions`	Command items can wrap `OsAction` plus `OsActionContext`.
OS Shell	Owns global keyboard listeners, real app opening, routing, and recent persistence.
App registry	Future Shell adapter can convert app manifests to `OsCommand` items.
Future `@prox-os/forms`	Can provide command arguments and quick-create flows.
Future `@prox-os/search`	Can merge resource search results into command palette sections.
Future `@prox-os/ai-ui`	Can provide natural language command entry and AI suggestions.
Backend packages	Permissions, audit, agents runtime, search service, and API contracts can govern real execution later.

Current Limitations

No real global Mod+K listener.
No OS Shell launcher replacement.
No persisted recent commands.
No app-contributed runtime provider loading.
No permission, audit, backend, or AI execution.
Ranking is intentionally lightweight and local.

See docs/platform/architecture/shell/command-system.md for the architecture boundary and phase roadmap.