feat(actions): add a shared action picker, action details, and usage references

[xcv58]

Summary

Improve action discovery and configuration by introducing:

• A shared action-query and picker model
• An expandable action-detail experience
• A unified “Use This Action” menu
• References showing where an action is currently used
• Repair flows for unavailable or missing actions

Adopt the shared components incrementally in Actions & Shortcuts and the workflow editor before expanding to Action Grid, Trackpad Gestures, and other surfaces. This is an enhancement of the current action UI, not a replacement of the canonical action system.

Current State

MacTools already provides:

• Canonical action definitions and references
• Action availability
• Unified Search execution
• Global action shortcuts
• Provider grouping
• Shortcut-state filters
• Shortcut conflict handling
• Run Link presentation
• Workflow action selection and execution
• Workflow history

However, users still need to understand separate settings surfaces to answer:

• What exactly does this action do?
• Why is it unavailable?
• Which permissions does it require?
• Can it be used in a workflow?
• Is it already assigned to a shortcut?
• Which workflows or grids reference it?
• How do I add it to another surface?
• What should I do when its provider is missing?

Goals

• Give every canonical action one understandable detail presentation.
• Reuse one search and filtering model across action-selection surfaces.
• Let users move from discovery to configuration without navigating manually through several pages.
• Show availability and repair information before selection.
• Show where an action is already used.
• Make broken action references repairable.
• Preserve existing action identity, execution, permission, and conflict policy.
• Improve keyboard and VoiceOver navigation.

Non-goals

• Replacing Unified Search
• Replacing the action registry
• Redesigning the entire Settings window
• Implementing uninstalled capability search in this issue
• Adding a general recommendation engine
• Building a visual node-based workflow editor
• Automatically changing user shortcuts or workflows
• Exposing sensitive parameter values
• Migrating every action surface in the first pull request

---

Shared Action-Query Model

Introduce a reusable action-query layer that can filter and rank catalog entries by:

• Text
• Provider
• Installed state
• Current availability
• Permission state
• Risk
• Parameter requirements
• Background support
• Automatic-execution eligibility
• External-invocation eligibility
• Target surface compatibility

The model should operate on canonical action definitions, catalog entries, availability, permission metadata, and host surface policy. It must not reimplement provider-specific action discovery.

Shared Action Picker

Build one host-owned picker that can be configured for a target surface.

Examples of target surfaces:

• Shortcut assignment
• Workflow step
• Automatic workflow step
• Action Grid slot
• Trackpad gesture
• Run Link preset

The target surface supplies eligibility requirements. Examples:

• An automatic rule requires .automatic capability and no confirmation-required risk.
• A Run Link requires external-invocation eligibility.
• A workflow may permit a foreground-interactive action when manually run but reject it for unattended execution.
• A shortcut may permit an interactive action but should show its required permissions.

Picker Row Content

Each row should show:

• Action title
• Provider title
• Short description
• Current availability
• Required permission or setup
• Relevant parameter summary
• Risk indicator where needed
• Compatibility with the current target surface

Note: Unavailable actions may remain visible when repair is possible. The row should explain why rather than silently disappearing.

---

Action-Detail Presentation

Selecting or expanding an action should show:

Primary information

• Title
• Provider
• Plain-language description
• Current status
• Primary repair or run action

Availability

• Available
• Permission required
• Provider missing
• Dynamic target missing
• Plugin disabled
• Configuration incomplete
• Unsupported by this surface
• Temporarily busy

Supported surfaces
Display only the surfaces relevant to the installed MacTools configuration:

• Search
• Shortcut
• Workflow
• Automatic rule
• Action Grid
• Gesture
• Run Link
• App Intent
• CLI, when implemented

Parameters
Show:

• Parameter title
• Type
• Required or optional
• Portable or local-only
• Sensitive classification
• Current configured value only when it is safe to display

Usage
Show references such as:

• Shortcut assignment
• Workflow and step
• Automatic rule
• Action Grid page and slot
• Gesture mapping
• Run Link preset
• App Intent exposure where relevant

Advanced details (Under disclosure)

• Provider ID
• Action ID
• Schema version
• Execution capabilities
• Concurrency policy
• Timeout
• External policy
• Redacted parameter names

Critical Constraint: Do not expose sensitive parameter values.

---

“Use This Action” Menu

Provide one contextual menu whose available entries are computed from the action and installed surfaces. Possible entries:

• Run
• Assign Shortcut
• Add to Workflow
• Create New Workflow with This Action
• Add to Action Grid
• Assign Gesture
• Create or Copy Run Link
• Open Provider Settings
• View Recent Result

The first implementation only needs to wire:

• Run
• Assign Shortcut
• Add to existing or new workflow
• Create or copy Run Link
• Open provider settings

Action Grid and gesture integration may follow after their editing APIs are made reusable.

---

Usage Index

Introduce a host-owned read-only index of action references used by:

• Action shortcut assignments
• Workflows
• Automation rules
• Action Grid
• Trackpad Gestures
• Run Link presets

Each usage reference should contain:

• Owning surface
• Owning item ID
• User-facing owner name
• Navigation destination
• Whether the reference is currently valid

The index must not contain action parameter values beyond what the owning surface already persists.

---

Broken-Reference Repair

When an action reference cannot resolve, show an explicit repair state.

Missing provider

• Message: This step requires Window Layouts, which is not installed.
• Actions: View plugin, Install plugin, Choose replacement, Remove step

Missing dynamic target

• Message: The selected audio application is no longer available.
• Actions: Choose another application, Keep unavailable reference, Remove step

Schema migration unavailable

• Message: This action changed after a plugin update.
• Actions: Review current action, Choose replacement, Remove reference

Rule: Never silently delete a missing reference from workflows, grids, gestures, or shortcut assignments.

---

Workflow-Browser Improvements In Scope

For the initial adoption:

• Use the shared picker for adding and replacing workflow steps.
• Show exact step availability before running.
• Deep-link failed run results to the relevant step.
• Show usage references for workflows published as actions.
• Provide replacement and provider-install flows for broken steps.
• Preserve the current workflow list/detail layout.

Workflow searching, tags, folders, and a visual graph editor are separate follow-ups.

---

Information Hierarchy

Apply progressive disclosure consistently.

Always visible:

• Action title
• Provider
• Availability
• Current assignment or usage summary
• Primary action

Visible on selection:

• Description
• Permissions
• Surface eligibility
• Parameters
• Usage references

Advanced only:

• Stable IDs
• Schema version
• Timeout
• Concurrency
• Redacted policy details

---

Architecture

Suggested host components:

• ActionQuery
• ActionQueryEvaluator
• ActionSurfaceEligibility
• ActionPickerModel
• ActionUsageIndex
• ActionUsageReference
• ActionDetailPresentation
• ActionRepairDestination

The implementation should reuse:

• ActionRegistry
• ActionDefinition
• ActionCatalogEntry
• ActionAvailability
• Existing permission lookups
• Existing shortcut conflict management
• Existing settings navigation

No new execution path should be introduced.

---

Implementation Phases

• Phase 1: Query and picker foundation
  • Define reusable query and eligibility models.
  • Build shared picker UI.
  • Adopt it in the workflow step editor.
  • Preserve existing parameter-editing behavior.
  • Add keyboard and VoiceOver support.
• Phase 2: Action details
  • Add expandable or selectable action details in Actions & Shortcuts.
  • Show availability and repair actions.
  • Show surface eligibility.
  • Show safe parameter metadata.
  • Add Advanced Details disclosure.
• Phase 3: Usage references
  • Index shortcut usage.
  • Index workflow and rule usage.
  • Index Run Link presets.
  • Add navigation to each usage.
  • Add Action Grid and gesture usage when reusable navigation exists.
• Phase 4: “Use This Action”
  • Run action.
  • Assign shortcut.
  • Add to workflow.
  • Create Run Link.
  • Open provider settings.
  • Add later surface integrations incrementally.
• Phase 5: Repair
  • Repair missing provider references.
  • Repair dynamic-target references.
  • Repair failed schema migration.
  • Add deep links from workflow history.

---

Testing

Include tests for:

• Text matching
• Provider filtering
• Availability filtering
• Permission-required state
• Automatic-rule eligibility
• Run Link eligibility
• Foreground-only actions
• Dynamic action entries
• Sensitive parameters
• Local-only parameters
• Usage indexing
• Missing provider
• Missing dynamic target
• Schema mismatch
• Duplicate references
• Navigation to owner
• Keyboard selection
• VoiceOver labels
• No sensitive-value disclosure

---

Acceptance Criteria

• Actions & Shortcuts can show a detail presentation for every installed catalog action.
• The workflow editor uses the shared action picker.
• The picker explains repairable unavailability.
• Target-surface eligibility is computed centrally.
• Users can run, assign a shortcut, add to a workflow, create a Run Link, or open provider settings from one action context.
• Shortcut, workflow, rule, and Run Link usage references are visible.
• Missing references remain present and are repairable.
• Stable IDs and policy details are hidden under Advanced Details.
• Sensitive parameter values are never exposed.
• Existing action execution and shortcut-conflict semantics remain unchanged.
• Keyboard and VoiceOver navigation are covered by tests.