shortcut

The shortcut surface registers a machine as a Siri Shortcut, making it invocable by voice on iOS, macOS, watchOS, and CarPlay. Say “Hey Siri, {phrase}” and the machine runs through the same governance pipeline as every other surface.

Overview

Voice is a surface, not a separate system. The shortcut surface declares a trigger phrase and optional icon that register the machine with Apple’s Shortcuts framework via the mashin native app. When the user speaks the phrase, the shortcut invokes the machine on the local cell (or tunnels to a remote cell), validates inputs, checks governance, and returns the result as spoken text or a notification.

This surface requires the mashin native app (iOS or macOS) to be installed. The app handles Siri intent registration and bridges voice invocations to the cell’s runtime.

Syntax

expresses
  shortcut
    phrase: "check my orders"
    icon: "bag"

A complete machine with a shortcut surface:

machine order_status

  accepts
    customer_id as text

  responds with
    pending_count as number
    latest_order as text

  ensures
    permissions
      allowed to
        reason, http

  implements
    ask fetch, from: "@mashin/actions/http/get"
      url: "https://api.internal.com/orders/status"
      returns
        pending_count as number
        latest_order as text
      assuming
        pending_count: 3
        latest_order: "ORD-2847 shipped yesterday"

  expresses
    shortcut
      phrase: "check my orders"
      icon: "bag"

Saying “Hey Siri, check my orders” invokes this machine and speaks the result.

Configuration options

Config	Required	Default	Description
`phrase`	Yes	-	The trigger phrase for Siri invocation (without “Hey Siri”)
`icon`	No	`"gear"`	SF Symbol name displayed in the Shortcuts app

Phrase guidelines

Keep phrases short and natural: “check my orders”, “summarize my inbox”, “start the deploy”
Avoid phrases that conflict with built-in Siri commands
The phrase is registered as-is; Siri handles minor pronunciation variations
Phrases must be unique per cell

Icon values

The icon field accepts any SF Symbol name. Common choices:

Icon	Use case
`"bag"`	Orders, shopping
`"envelope"`	Email, messages
`"chart.bar"`	Analytics, metrics
`"server.rack"`	Infrastructure, deploys
`"brain"`	AI, reasoning
`"gear"`	Settings, configuration

Input handling

When a shortcut is invoked by voice, Siri can prompt the user for required inputs. The prompts are derived from the machine’s accepts section. For machines with no required inputs, the shortcut runs immediately.

For machines that accept complex inputs, consider providing defaults or using a companion page surface for the full interface, reserving the shortcut for the quick-check use case.

Governance

Every shortcut invocation is governed:

The voice command is matched to the registered phrase
Required inputs are collected (Siri prompts if needed)
Governance permissions from ensures are checked
The machine executes
A SurfaceAccess event is recorded with :shortcut surface in the behavioral ledger
The result is spoken back or shown as a notification

Denied invocations produce a spoken response: “That action is not allowed by this machine’s governance.”

Example

A machine reachable by both voice and REST API:

machine deploy_status

  responds with
    status as text
    last_deploy as text

  implements
    ask check, from: "@mashin/actions/http/get"
      url: "https://api.internal.com/deploy/status"
      returns
        status as text
        last_deploy as text
      assuming
        status: "healthy"
        last_deploy: "2 hours ago"

  expresses
    shortcut
      phrase: "deploy status"
      icon: "server.rack"
    api
      path: "/api/deploy/status"
      method: "GET"
      authentication: "bearer_token"

“Hey Siri, deploy status” and GET /api/deploy/status invoke the same machine with the same governance.