Actions Package

@prox-os/actions is the shared action intent package for Prox OS frontend surfaces. It gives apps, resource cards, toolbars, context menus, command previews, and future AI actions one common language before real execution moves through the OS Shell, app runtime, permissions, audit, or backend services.

The package is not the OS Shell context menu, not the command palette, and not a backend permission system. It defines what a user, system, or AI agent wants to do and provides small React primitives for displaying those intents.

Core Types

OsAction
OsActionId
OsActionTarget
OsActionContext
OsActionSource
OsActionState
OsActionResult
OsActionHandler
OsActionGroup

Core Helpers

groupActions
filterVisibleActions
filterEnabledActions
isActionDisabled
isDestructiveAction
getActionLabel
createActionTarget
createUrlActionTarget
createActionResult
createCommonAction

Common Actions

The package exports reusable examples for common intent categories:

URL actions: Open in OS, Open in New Tab, Copy URL, Copy Markdown.
Resource actions: Inspect, Inspect Metadata, Save to Library, Pin, Share, Archive, Delete.
AI actions: Summarize, Generate, Transform, Run AI Action.

These are templates. The host app still decides if an action is available, how it executes, and whether it needs confirmation.

React Primitives

OsActionButton
OsActionMenu
OsActionToolbar
OsActionList
OsActionCard
OsActionStatusBadge

The primitives use OS design tokens and emit callbacks through onAction. They do not import apps/os-shell internals.

Storybook

Open UI Workshop and look under Actions:

Actions / OsActionButton
Actions / OsActionMenu
Actions / OsActionToolbar
Actions / OsActionList
Actions / OsActionCard
Actions / OsActionStatusBadge
Actions / Integration

The stories show button states, destructive actions, grouped menus, URL actions, resource actions, AI action cards, toolbar actions, and command/media/map integration previews.

Integration Map

Surface	How it should use actions
`@prox-os/media`	Reuse open, copy, save, inspect, transform, and future media-library actions.
`@prox-os/maps`	Reuse shared action shape for copy coordinates, save place, inspect feature, and routing intents.
`@prox-os/data-table`	Reuse record, view, export, inspect, and AI summary actions.
`@prox-os/data-viz`	Reuse open chart, inspect chart, export chart, and AI explanation actions.
Future `@prox-os/command`	Treat a command item as searchable action plus context plus handler.
Future backend packages	Connect action availability to permissions, execution to API contracts, and outcomes to audit.

Current Limitations

No real OS Shell system context menu integration.
No command palette implementation.
No backend execution.
No permission, audit, or AI agent runtime enforcement.
Demo handlers only return local action results.

See docs/platform/architecture/capabilities/actions.md for the architecture boundary and roadmap.