## §OIP SYSTEM ARTICLE — Mac — local shell + files (40 operations)
A generated article for one OIP shelf. It lists every operation in this API/CLI/MCP/device/model/core subsystem, links each leaf article, and gives the ledger path for proof.

### Read Order
- scan operations
- open a leaf doc
- run via run_now or POST /api/dispatch
- open receipt
- repair/replay if needed

### Operations
- **LOCAL_CAFFEINATE** — Keep Mac awake for N seconds (caffeinate -dimsu).
  when: "keep my mac awake", "caffeinate for N seconds", "don't let my mac sleep"
  args: seconds
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_CAFFEINATE&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_CAFFEINATE&body=%3Cseconds%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_CAFFEINATE
- **LOCAL_CLIPBOARD_GET** — Read the Mac's clipboard (pbpaste).
  when: "what's on my clipboard", "read my clipboard", "clipboard contents"
  args: (none)
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_CLIPBOARD_GET&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_CLIPBOARD_GET&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_CLIPBOARD_GET
- **LOCAL_CLIPBOARD_SET** — Put text on the Mac's clipboard (pbcopy).
  when: "copy X to my clipboard", "put X on my clipboard", "set my clipboard to"
  args: the text
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_CLIPBOARD_SET&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_CLIPBOARD_SET&body=%3Cthe%20text%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_CLIPBOARD_SET
- **LOCAL_DOWNLOAD** — Download a URL to a local path on the Mac.
  when: "download X to my mac", "curl X to", "grab this URL to disk"
  args: url | path
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_DOWNLOAD&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_DOWNLOAD&body=%3Curl%3E%7C%3Cpath%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_DOWNLOAD
- **LOCAL_EDIT** — Exact-string replace in a file (python str.replace, all occurrences). Prints count.
  when: "edit X in <file>", "replace X with Y in <file>", "change <pattern> to <pattern> in"
  args: path | old | new
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_EDIT&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_EDIT&body=%3Cpath%3E%7C%3Cold%3E%7C%3Cnew%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_EDIT
- **LOCAL_EXEC** — Run a shell command on Cyrus Mac.
  when: any file operation, git command, system check, or script execution.
  args: $1 = the shell command (pipes, &&, redirects allowed).
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_EXEC&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_EXEC&body=ls%20-la%20~%2FDesktop&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_EXEC
- **LOCAL_GREP** — ripgrep on the Mac with line numbers (50 hits per file max).
  when: "grep for X in", "find where X is in", "search <pattern> in <path>"
  args: pattern | path
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_GREP&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_GREP&body=%3Cpattern%3E%7C%3Cpath%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_GREP
- **LOCAL_HEALTH** — Bridge liveness {ok, ts, installed_cli, deny_globs, ...}.
  when: "is the bridge alive", "is my mac reachable", "what's installed on my mac", "bridge health"
  args: (none)
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_HEALTH&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_HEALTH&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_HEALTH
- **LOCAL_LAUNCHD** — launchctl on the Mac. Inspect/restart launch agents.
  when: "restart the bridge", "launchctl X", "kickstart <service>"
  args: launchctl arguments
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_LAUNCHD&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_LAUNCHD&body=%3Claunchctl%20arguments%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_LAUNCHD
- **LOCAL_LIST** — ls -la a path on the Mac.
  when: "list <dir>", "what's in <dir>", "ls <path>"
  args: path (empty = home)
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_LIST&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_LIST&body=%3Cpath%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_LIST
- **LOCAL_OCR** — OCR an image (tesseract). Local path or https URL.
  when: "read text from this image", "ocr this", "extract text from <image>"
  args: path or https URL
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_OCR&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_OCR&body=%3Cpath%20or%20https%20URL%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_OCR
- **LOCAL_OPEN** — macOS `open` — launch an app, file, or URL on the Mac.
  when: "open X on my mac", "launch <app>", "open this URL on my mac"
  args: target (URL, file path, or `-a AppName`)
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_OPEN&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_OPEN&body=%3Ctarget%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_OPEN
- **LOCAL_OSASCRIPT** — Run one line of AppleScript on the Mac (osascript -e).
  when: "applescript: <line>", "tell <app> to <action>", "run osascript"
  args: the AppleScript line
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_OSASCRIPT&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_OSASCRIPT&body=%3Cthe%20AppleScript%20line%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_OSASCRIPT
- **LOCAL_PORTS** — Listening TCP ports on the Mac (lsof).
  when: "what's listening on my mac", "listening ports", "ports in use"
  args: (none)
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_PORTS&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_PORTS&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_PORTS
- **LOCAL_PS** — Running processes filtered by string. Empty filter = first 50.
  when: "what's running on my mac", "is X running", "ps for <name>"
  args: filter (empty = first 50)
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_PS&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_PS&body=%3Cfilter%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_PS
- **LOCAL_SAY** — Speak text aloud on the Mac (say).
  when: "say X out loud", "speak X on my mac", "make my mac say"
  args: the text
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_SAY&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_SAY&body=%3Cthe%20text%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_SAY
- **LOCAL_SCREENSHOT** — Screenshot the screen, upload to R2, return a stable URL.
  when: "screenshot my mac", "take a screenshot", "what's on my screen right now"
  args: (none)
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_SCREENSHOT&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_SCREENSHOT&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_SCREENSHOT
- **LOCAL_WRITE** — Overwrite a file on the Mac. Echoes the content back.
  when: "write this to <file>", "create <file> with", "drop this in <file>"
  args: path | content
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_WRITE&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_WRITE&body=%3Cpath%3E%7C%3Ccontent%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_WRITE
- **LOCAL_APPS** — List running GUI apps on the Mac (foreground processes).
  when: "what apps are open", "list running apps", "what is running on my mac"
  args: none
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_APPS&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_APPS&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_APPS
- **LOCAL_FRONTMOST** — Name of the frontmost (active) app on the Mac.
  when: "what app is in front", "what am I looking at", "frontmost app"
  args: none
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_FRONTMOST&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_FRONTMOST&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_FRONTMOST
- **LOCAL_WINDOWS** — List window titles of the frontmost app.
  when: "what windows are open", "list windows of the front app"
  args: none
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_WINDOWS&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_WINDOWS&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_WINDOWS
- **LOCAL_ACTIVATE** — Bring an app to the front (focus it).
  when: "open X", "switch to X", "focus X" (X = app name)
  args: app name (e.g. Safari)
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_ACTIVATE&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_ACTIVATE&body=%3Capp%20name%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_ACTIVATE
- **LOCAL_KEYSTROKE** — Type text into the focused field on the Mac (System Events keystroke).
  when: "type X", "enter X into the focused field"
  args: the text to type
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_KEYSTROKE&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_KEYSTROKE&body=%3Cthe%20text%20to%20type%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_KEYSTROKE
- **LOCAL_KEYCODE** — Send a macOS key code to the focused app (36=return 53=esc 48=tab 123-126=arrows).
  when: "press enter", "hit escape", "press the down arrow"
  args: key code number
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_KEYCODE&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_KEYCODE&body=%3Ckey%20code%20number%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_KEYCODE
- **LOCAL_UI_SNAPSHOT** — Accessibility snapshot of the frontmost window — role+name+description of each top-level UI element. Semantic,
  when: "what is on screen", "list the buttons", "snapshot the UI" — run before clicking by name
  args: none
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_UI_SNAPSHOT&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_UI_SNAPSHOT&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_UI_SNAPSHOT
- **LOCAL_UI_CLICK** — Click a UI element by NAME in the frontmost app (semantic, not blind x/y). Pair with LOCAL_UI_SNAPSHOT to find
  when: "click the X button", "press X" where X is an on-screen element name
  args: element name
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_UI_CLICK&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_UI_CLICK&body=%3Celement%20name%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_UI_CLICK
- **LOCAL_NOTIFY** — post a macOS Notification Center banner. ARGS: title|message|sound (optional).
  when: bring eyes back to the Mac when something async finishes.
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_NOTIFY&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_NOTIFY&body=%3Carg1%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_NOTIFY
- **LOCAL_NETWORK** — dump current network state (Wi-Fi SSID, IP, gateway). ARGS: none.
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_NETWORK&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_NETWORK&body=%3Carg1%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_NETWORK
- **LOCAL_BATTERY** — read battery % and AC power state on the Mac. ARGS: none.
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_BATTERY&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_BATTERY&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_BATTERY
- **LOCAL_FOCUS** — read current Focus mode (do not disturb / work / etc) from defaults.
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_FOCUS&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_FOCUS&body=%3Carg1%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_FOCUS
- **LOCAL_OPEN_URL** — open a URL in the default browser. ARGS: $1 = url.
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_OPEN_URL&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_OPEN_URL&body=%3Carg1%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_OPEN_URL
- **LOCAL_OPEN_APP** — open a macOS app by name. ARGS: $1 = app name (e.g. "Safari", "Cursor", "Messages").
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_OPEN_APP&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_OPEN_APP&body=%3Carg1%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_OPEN_APP
- **LOCAL_VOICE_RECORD** — record N seconds of mic to /tmp/voice-<ts>.m4a using ffmpeg, return path.
  args: seconds (default 10).
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_VOICE_RECORD&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_VOICE_RECORD&body=%3Cseconds%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_VOICE_RECORD
- **LOCAL_SHORTCUTS_RUN** — run a macOS/iOS Shortcut by name (`shortcuts run "Name"`). ARGS: $1 = name, $2 = input (optional).
  when: invoke any shortcut Cyrus saved (cross-syncs with iOS).
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_SHORTCUTS_RUN&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_SHORTCUTS_RUN&body=%3Carg1%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_SHORTCUTS_RUN
- **LOCAL_SHORTCUTS_LIST** — list all Shortcuts on the Mac (`shortcuts list`).
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_SHORTCUTS_LIST&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_SHORTCUTS_LIST&body=%3Carg1%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_SHORTCUTS_LIST
- **LOCAL_PASTEBOARD_PUSH_PHONE** — push text into Mac clipboard so Universal Clipboard syncs it to the iPhone. ARGS: $1 = text.
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_PASTEBOARD_PUSH_PHONE&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_PASTEBOARD_PUSH_PHONE&body=%3Carg1%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_PASTEBOARD_PUSH_PHONE
- **LOCAL_AIRDROP** — AirDrop a file from the Mac via osascript. ARGS: $1 = absolute file path.
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_AIRDROP&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_AIRDROP&body=%3Carg1%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_AIRDROP
- **LOCAL_DICTATE_TO_PHONE** — TTS the text via macOS say(1) at the Mac speakers. ARGS: $1 = text, $2 = voice (optional, default Samantha).
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_DICTATE_TO_PHONE&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_DICTATE_TO_PHONE&body=%3Carg1%3E&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_DICTATE_TO_PHONE
- **LOCAL_HELP** — Print the --help / -h / man page of a binary on the Mac. Args: binary name.
  when: "how do I use X", "what flags does X have", "X --help".
  args: $1
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_HELP&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_HELP&body=claude&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_HELP
- **LOCAL_READ** — Read a file on Cyrus Mac.
  when: the user says "show me", "read", "what is in", "display".
  args: $1 = absolute path.
  doc: https://miscsubjects.com/api/dispatch?key=LOCAL_READ&format=markdown
  run: https://miscsubjects.com/api/dispatch?invoke=LOCAL_READ&body=%2FUsers%2Fcyrusmassoumi%2FSTATE.md&share=<TOKEN>
  history: https://miscsubjects.com/api/invocations?object_id=LOCAL_READ

### Troubleshooting
- If a row's example has placeholders, replace only the placeholder values and preserve separators.
- If a call fails, open its receipt and repair it with POST /api/dispatch {key, body, repairs:'inv_ID'}.
- If token scope denies this system, ask the owner for a row:/rows:/pfx: token scoped to the exact operation set.

Back to the tree: https://miscsubjects.com/api/dispatch?map=1&format=markdown