shortcuts-playground 1.2.1

package/skills/shortcuts-playground/SKILL.md

@@ -0,0 +1,459 @@
+---
+name: shortcuts-playground
+description: Build, validate, sign, archive, and remix macOS/iOS Shortcuts in OpenCode by creating plist files. Use when asked to create, modify, or remix shortcuts; automate workflows; build .shortcut files; or generate Shortcuts plists. Covers WF actions, AppIntents, third-party actions, HealthKit, variable references, and control flow using bundled target-gated ToolKit snapshots.
+---
+
+# Shortcuts Playground
+
+Generate valid `.shortcut` files that can be signed and imported into Apple's Shortcuts app. This OpenCode plugin supports two workflows: building new shortcuts from scratch and remixing existing unsigned XML shortcuts with a natural-language diff.
+
+## OpenCode Compatibility
+
+OpenCode plugins do not expose Claude Code's PATH wrapper commands from the Claude package. In OpenCode, use this skill directly and call the bundled scripts by path, or use the `/build-shortcut` and `/remix-shortcut` commands which delegate to the specialized subagents.
+
+The OpenCode package also bundles a `tool.execute.after` auto-validation hook (PostToolUse-equivalent) via `plugin/validator.ts`. It validates changed `.xml`/`.shortcut` files that contain `WFWorkflowActions` after every `write`/`edit` tool call.
+
+Resolve the skill directory as the folder containing this `SKILL.md`. In examples below, `SKILL_DIR` means that directory.
+
+| Task | OpenCode command pattern |
+|------|-----------------------|
+| Resolve icon/color | `python3 "$SKILL_DIR/scripts/select_shortcut_icon_color.py" --prompt "$USER_PROMPT"` |
+| Validate XML | `python3 "$SKILL_DIR/scripts/validate_shortcut.py" /path/to/Shortcut.xml` |
+| Archive + sign | `"$SKILL_DIR/scripts/sign_shortcut.sh" /path/to/Shortcut.xml --name "Shortcut Name"` |
+
+`sign_shortcut.sh` defaults to `SHORTCUTS_PLAYGROUND_OUTPUT_DIR` or `~/Documents/Shortcuts Playground`, and `SHORTCUTS_PLAYGROUND_SIGNING_MODE` or `anyone`. It requires macOS and Apple's `shortcuts` CLI. The validator only requires Python 3.10+.
+
+**Mandatory**: Follow the guidelines in [BEST_PRACTICES.md](BEST_PRACTICES.md) for every shortcut.
+If guidance here conflicts with [BEST_PRACTICES.md](BEST_PRACTICES.md), follow `BEST_PRACTICES.md`.
+
+**Definition of done**: a new build is not complete when XML validation passes. It is complete only after `scripts/sign_shortcut.sh` archives the unsigned XML, writes the signed `.shortcut`, and you verify the signed file exists with non-zero size.
+
+**Pipeline-first rule**: write the smallest complete shortcut that implements the request, validate it, sign it, and verify the signed file before spending turns on cosmetic polish. Comments only need to be concise and repair-oriented. A valid XML draft without a signed `.shortcut` is not a useful stopping point.
+
+## Recommended Reading Order
+
+1. [BEST_PRACTICES.md](BEST_PRACTICES.md) for mandatory rules and validation expectations
+2. [PLIST_FORMAT.md](PLIST_FORMAT.md) for plist structure and serialization details
+3. [ACTIONS.md](ACTIONS.md), [APPINTENTS.md](APPINTENTS.md), [AUTOMATION_TRIGGERS.md](AUTOMATION_TRIGGERS.md), and [THIRD_PARTY_ACTIONS.md](THIRD_PARTY_ACTIONS.md) for action IDs, AppIntent parameters, and OS 27 trigger metadata
+4. [HEALTHKIT.md](HEALTHKIT.md) when building or remixing Health actions
+5. [VARIABLES.md](VARIABLES.md), [CONTROL_FLOW.md](CONTROL_FLOW.md), and [FILTERS.md](FILTERS.md) for wiring patterns
+6. [ICONS_AND_COLORS.md](ICONS_AND_COLORS.md), [PARAMETER_TYPES.md](PARAMETER_TYPES.md), and [EXAMPLES.md](EXAMPLES.md) for implementation details
+
+## Quick Start
+
+A shortcut is an XML plist that gets signed into a binary package. Generate the XML form:
+
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>WFWorkflowActions</key>
+    <array>
+        <!-- Actions go here -->
+    </array>
+    <key>WFWorkflowClientVersion</key>
+    <string>2700.0.4</string>
+    <key>WFWorkflowHasOutputFallback</key>
+    <false/>
+    <key>WFWorkflowIcon</key>
+    <dict>
+        <key>WFWorkflowIconGlyphNumber</key>
+        <integer>61440</integer>
+        <key>WFWorkflowIconStartColor</key>
+        <integer>431817727</integer>
+    </dict>
+    <key>WFWorkflowImportQuestions</key>
+    <array/>
+    <key>WFWorkflowInputContentItemClasses</key>
+    <array/>
+    <key>WFWorkflowMinimumClientVersion</key>
+    <integer>900</integer>
+    <key>WFWorkflowMinimumClientVersionString</key>
+    <string>900</string>
+    <key>WFWorkflowName</key>
+    <string>My Shortcut</string>
+    <key>WFWorkflowOutputContentItemClasses</key>
+    <array/>
+    <key>WFWorkflowTypes</key>
+    <array/>
+</dict>
+</plist>
+```
+
+### Minimal Hello World
+
+```xml
+<dict>
+    <key>WFWorkflowActionIdentifier</key>
+    <string>is.workflow.actions.gettext</string>
+    <key>WFWorkflowActionParameters</key>
+    <dict>
+        <key>UUID</key>
+        <string>A1B2C3D4-E5F6-7890-ABCD-EF1234567890</string>
+        <key>WFTextActionText</key>
+        <string>Hello World!</string>
+    </dict>
+</dict>
+<dict>
+    <key>WFWorkflowActionIdentifier</key>
+    <string>is.workflow.actions.showresult</string>
+    <key>WFWorkflowActionParameters</key>
+    <dict>
+        <key>Text</key>
+        <dict>
+            <key>Value</key>
+            <dict>
+                <key>attachmentsByRange</key>
+                <dict>
+                    <key>{0, 1}</key>
+                    <dict>
+                        <key>OutputName</key>
+                        <string>Text</string>
+                        <key>OutputUUID</key>
+                        <string>A1B2C3D4-E5F6-7890-ABCD-EF1234567890</string>
+                        <key>Type</key>
+                        <string>ActionOutput</string>
+                    </dict>
+                </dict>
+                <key>string</key>
+                <string></string>
+            </dict>
+            <key>WFSerializationType</key>
+            <string>WFTextTokenString</string>
+        </dict>
+    </dict>
+</dict>
+```
+
+## Core Concepts
+
+### 1. Actions
+Every action has:
+- **Identifier**: `is.workflow.actions.<name>` (e.g., `is.workflow.actions.showresult`)
+- **Parameters**: Action-specific configuration in `WFWorkflowActionParameters`
+- **UUID**: Unique identifier for referencing this action's output
+
+### 2. Variable References
+To use output from a previous action:
+1. The source action needs a `UUID` parameter
+2. Reference it using `OutputUUID` in an `attachmentsByRange` dictionary
+3. Use `` (U+FFFC) as placeholder in the string where the variable goes
+4. Set `WFSerializationType` to `WFTextTokenString`
+
+### 3. Control Flow
+Control flow actions (repeat, conditional, menu) use:
+- `GroupingIdentifier`: UUID linking start/middle/end actions
+- `WFControlFlowMode`: 0=start, 1=middle (else/case), 2=end
+
+## Common Actions Quick Reference
+
+| Action | Identifier | Key Parameters |
+|--------|------------|----------------|
+| Text | `is.workflow.actions.gettext` | `WFTextActionText` |
+| Show Result | `is.workflow.actions.showresult` | `Text` |
+| Ask for Input | `is.workflow.actions.ask` | `WFAskActionPrompt`, `WFInputType` |
+| Use AI Model | `is.workflow.actions.askllm` | `WFLLMPrompt`, `WFLLMModel`, `WFGenerativeResultType`, `WFAllowWebSearch`, `FollowUp` (OS 27+) |
+| Comment | `is.workflow.actions.comment` | `WFCommentActionText` |
+| URL | `is.workflow.actions.url` | `WFURLActionURL` |
+| Get Contents of URL | `is.workflow.actions.downloadurl` | `WFURL`, `WFHTTPMethod` |
+| Get Weather | `is.workflow.actions.weather.currentconditions` | (none required) |
+| Open App | `is.workflow.actions.openapp` | `WFAppIdentifier` |
+| Open URL | `is.workflow.actions.openurl` | `WFInput` |
+| Alert | `is.workflow.actions.alert` | `WFAlertActionTitle`, `WFAlertActionMessage` |
+| Notification | `is.workflow.actions.notification` | `WFNotificationActionTitle`, `WFNotificationActionBody` |
+| Set Variable | `is.workflow.actions.setvariable` | `WFVariableName`, `WFInput` |
+| Get Variable | `is.workflow.actions.getvariable` | `WFVariable` |
+| Number | `is.workflow.actions.number` | `WFNumberActionNumber` |
+| List | `is.workflow.actions.list` | `WFItems` |
+| Dictionary | `is.workflow.actions.dictionary` | `WFItems` |
+| Repeat (count) | `is.workflow.actions.repeat.count` | `WFRepeatCount`, `GroupingIdentifier`, `WFControlFlowMode` |
+| Repeat (each) | `is.workflow.actions.repeat.each` | `WFInput`, `GroupingIdentifier`, `WFControlFlowMode` |
+| If/Otherwise | `is.workflow.actions.conditional` | `WFInput`, `WFCondition`, `GroupingIdentifier`, `WFControlFlowMode` |
+| Choose from Menu | `is.workflow.actions.choosefrommenu` | `WFMenuPrompt`, `WFMenuItems`, `GroupingIdentifier`, `WFControlFlowMode` |
+| Find Photos | `is.workflow.actions.filter.photos` | `WFContentItemFilter` (see FILTERS.md) |
+| Delete Photos | `is.workflow.actions.deletephotos` | `photos` (**NOT** `WFInput`!) |
+
+## Detailed Reference Files
+
+For complete documentation, see:
+- [PLIST_FORMAT.md](PLIST_FORMAT.md) - Complete plist structure
+- [ICONS_AND_COLORS.md](ICONS_AND_COLORS.md) - Icon glyph + color selection (explicit and inferred)
+- [ACTIONS.md](ACTIONS.md) - WF*Action identifiers and parameters
+- [APPINTENTS.md](APPINTENTS.md) - AppIntent actions (ToolKit + backups)
+- [AUTOMATION_TRIGGERS.md](AUTOMATION_TRIGGERS.md) - OS 27 ToolKit automation trigger metadata for research and future automation support
+- [PARAMETER_TYPES.md](PARAMETER_TYPES.md) - All parameter value types and serialization formats
+- [HEALTHKIT.md](HEALTHKIT.md) - iOS/iPadOS Health actions, bundled anonymized XML examples, and HealthKit value coverage
+- [URL_SCHEMES.md](URL_SCHEMES.md) - Apple-documented Shortcuts URL schemes and x-callback-url patterns
+- [JAVASCRIPT_WEBPAGE.md](JAVASCRIPT_WEBPAGE.md) - Run JavaScript on Webpage runtime requirements and script rules
+- [DATE_TIME.md](DATE_TIME.md) - Apple-aligned date/time recipes, UNIX timestamps, ISO 8601, RFC 2822, and custom formats
+- [VARIABLES.md](VARIABLES.md) - Variable reference system
+- [CONTROL_FLOW.md](CONTROL_FLOW.md) - Repeat, Conditional, Menu patterns
+- [FILTERS.md](FILTERS.md) - Content filters for Find/Filter actions (photos, files, etc.)
+- [EXAMPLES.md](EXAMPLES.md) - Complete working examples
+- [BEST_PRACTICES.md](BEST_PRACTICES.md) - Mandatory build guidelines
+- [THIRD_PARTY_ACTIONS.md](THIRD_PARTY_ACTIONS.md) - Third-party actions (ToolKit + backups)
+- [TOOLKIT_SNAPSHOT.md](TOOLKIT_SNAPSHOT.md) - Bundled ToolKit action-ID allowlists
+- [CHANGELOG.md](CHANGELOG.md) - Change history: autoresearch findings, documentation updates, and version notes
+
+When you need to verify an unfamiliar action identifier, check the packaged `data/toolkit-v*-tool-ids.json` snapshots, then `ACTIONS.md`, `APPINTENTS.md`, and `THIRD_PARTY_ACTIONS.md` before inventing anything.
+
+## Golden Example Library (On-Demand)
+
+A curated set of shortcut XMLs is available for on-demand reference. Use the index first; only load XML sources that match the current task.
+
+- Index: `golden-shortcuts/index.jsonl` (token-efficient metadata: title, purpose, tags, xml path)
+- XMLs: `golden-shortcuts/xml/<shortcut_id>.xml`
+- Note: Golden XMLs are pattern references and may predate current validator/comment standards; treat them as wiring examples, not pass/fail baselines.
+
+Workflow:
+1) Read `golden-shortcuts/index.jsonl` to find relevant examples by tags/purpose.
+2) Load only the single XML file(s) needed for the current task.
+3) Do **not** bulk-load the entire library.
+
+## Icon and Color Resolver (Required)
+
+For every generated shortcut, choose icon and color using the resolver unless the user gave explicit integer values already:
+
+```bash
+python3 "$SKILL_DIR/scripts/select_shortcut_icon_color.py" --prompt "${USER_PROMPT}"
+```
+
+Optional explicit overrides:
+
+```bash
+python3 "$SKILL_DIR/scripts/select_shortcut_icon_color.py" --prompt "${USER_PROMPT}" --icon "robot" --color "purple"
+```
+
+Then set:
+- `WFWorkflowIconGlyphNumber = icon.glyph_number`
+- `WFWorkflowIconStartColor = color.value`
+
+The resolver supports natural-language icon requests (e.g. `paper airplane icon`, `terminal icon`, `expense icon`) and automatic icon selection when no icon is requested.
+
+## Preflight Validator — Craig Loop (Required)
+
+After generating a shortcut, run the validator in a **fix loop** (Craig Loop). Each iteration: read the errors, make a targeted fix, re-validate. Do not re-run without changing something. If the OpenCode `tool.execute.after` hook reports validator feedback after an edit, treat that as the current validator run and fix the reported errors before signing.
+
+```bash
+python3 "$SKILL_DIR/scripts/validate_shortcut.py" /path/to/Shortcut.xml
+```
+
+### Craig Loop Protocol
+
+1. **Run the validator.** If it passes, proceed to signing.
+2. **Read ALL error messages.** The validator prints every error it finds — fix as many as possible in one pass, not just the first one.
+3. **Make targeted fixes** in the plist XML based on the error messages. Each error includes the action index and identifier so you know exactly where to edit.
+4. **Re-run the validator.** Repeat from step 1.
+5. **Exit conditions** (stop looping and report to the user):
+   - **Max 5 iterations.** If the validator still fails after 5 fix attempts, stop. Summarize the remaining errors and ask the user for guidance.
+   - **Same errors repeating.** If the same error persists across 2 consecutive iterations despite attempted fixes, stop. The fix approach is wrong — do not keep trying the same thing.
+   - **Known validator gaps.** Only waive validator failures if `BEST_PRACTICES.md` lists a current, runtime-verified false positive. Otherwise fix the shortcut or stop and report the exact remaining errors.
+
+### Anti-patterns (do NOT do these)
+- **Chatting the validator**: Running the validator repeatedly without making meaningful code changes between runs. Every re-run must follow a real edit.
+- **Cosmetic fixes**: Rearranging comments or renaming variables to "try something" when the error is about wiring or missing parameters.
+- **Regenerating from scratch** when only 1-2 specific actions need fixing. Targeted edits preserve working wiring.
+
+### Data sources
+The validator uses bundled ToolKit snapshot IDs from packaged `data/toolkit-v*-tool-ids.json` files, filtered by target OS version and target platform, then augments with [`ACTIONS.md`](ACTIONS.md), [`APPINTENTS.md`](APPINTENTS.md), and [`THIRD_PARTY_ACTIONS.md`](THIRD_PARTY_ACTIONS.md). The default OS target is `auto` (`sw_vers` on macOS, macOS 26 when the host cannot be detected). The default platform target is `macos`. Use `--target-macos 27` or `SHORTCUTS_PLAYGROUND_TARGET_MACOS=27` only when building OS 27-era shortcuts that need target-gated macOS v78 identifiers or OS 27-only parameters such as `WFAllowWebSearch` / `FollowUp` on Use Model, `interpretAsMarkdown`, `WFAvoidTolls`, and Safari Tab Group `contents`. Use `--target-platform ios` / `SHORTCUTS_PLAYGROUND_TARGET_PLATFORM=ios` only for iPhone/iPad authoring, and `--target-platform all` only for intentional cross-platform metadata audits. For OS 27 targets, the validator also uses `data/toolkit-v78-first-party-parameter-keys.json` to reject unknown top-level keys on first-party `com.apple.*` AppIntent-style actions. It does not read the user's live ToolKit SQLite database during normal validation.
+
+For reviewed Apple-derived macOS 27 schema grounding and automation trigger metadata, use the static catalogs only:
+
+```bash
+python3 "$SKILL_DIR/scripts/lookup_action_grounding.py" --identifier additemtolist --target-macos 27
+python3 "$SKILL_DIR/scripts/lookup_action_grounding.py" --python-name when_app_opened --target-macos 27
+python3 "$SKILL_DIR/scripts/lookup_action_grounding.py" --identifier com.apple.HearingApp.MuteVolumeIntent --target-macos 27 --target-platform ios
+```
+
+`data/macos27-shortpy-grounding.json` may improve parameter/schema confidence, `data/toolkit-v78-first-party-enum-cases.json` may improve picker-value selection, `data/toolkit-v78-trigger-parameter-keys.json` may improve automation-trigger discovery, and `data/macos27-workflow-trigger-samples.json` may show sanitized exported `WFWorkflowTriggers` shapes for observed OS 27 automation headers. None of them overrides validator target gating. The lookup helper reports target-platform availability notes for iOS-only/macOS-only ToolKit rows. Exported automation-bearing shortcuts are the authority for portable automation-header authoring; do not infer that carrier from ToolKit metadata alone.
+
+### Escape-hatch comments
+If a request explicitly requires vCard/VCF formatting or file-based token loading, add a Comment containing `ALLOW_VCARD` or `ALLOW_TOKEN_FILE` so the validator can allow it. Other escape hatches: `ALLOW_MANUAL_UNIT_CONVERSION`, `ALLOW_DATETIME_FORMAT`.
+
+### Wiring Regression Suite (Recommended)
+
+When changing wiring logic or validator rules for Weather/Location actions, run the bulk regression suite:
+
+```bash
+python3 "$SKILL_DIR/scripts/test_wiring_regressions.py" --write-fixtures /tmp/shortcuts-wiring-regressions
+```
+
+The suite generates and validates:
+- 43 Weather Detail cases (21 valid + 22 invalid)
+- 40 Location parameter cases (20 valid + 20 invalid)
+- 16 Set Name/Rename File cases (8 valid + 8 invalid)
+
+It exits non-zero if any case behavior regresses.
+
+### Random Mixed-Action Stress Suite (Recommended)
+
+For broad randomized coverage (brand-new shortcuts, 10+ distinct actions each), run:
+
+```bash
+python3 "$SKILL_DIR/scripts/test_random_mixed_shortcuts.py" --count 50 --min-actions 10
+```
+
+Behavior:
+- Generates brand-new random shortcuts under `--output-dir` when provided, otherwise `SHORTCUTS_PLAYGROUND_OUTPUT_DIR/<YYYY-MM-DD>/random-mixed-actions-<runid>/` or `~/Documents/Shortcuts Playground/<YYYY-MM-DD>/random-mixed-actions-<runid>/`.
+- Enforces a minimum distinct action count per shortcut (`--min-actions`, default `10`).
+- Runs validate/retry loops per case (`--max-attempts`, default `20`).
+- Writes `manifest.json`, `results.json`, and `summary.md` for documentation.
+
+Optional:
+
+```bash
+python3 "$SKILL_DIR/scripts/test_random_mixed_shortcuts.py" --count 50 --min-actions 10 --sign
+```
+
+For OS 27 coverage, opt in explicitly so older users and CI jobs do not validate Golden Gate-only actions by accident:
+
+```bash
+python3 "$SKILL_DIR/scripts/test_random_mixed_shortcuts.py" --count 50 --min-actions 10 --target-macos 27 --include-os27-actions --sign
+```
+
+The OS 27 module adds Stored Content, Add Item to List, Otherwise If, Get Selected Text, Get What's On Screen, and Get Current VPN to every generated shortcut.
+
+Use this suite when you need randomized multi-action regression coverage beyond targeted wiring tests.
+
+## Signing Shortcuts
+
+Shortcuts MUST be signed before they can be imported. This skill ships `scripts/sign_shortcut.sh`, which combines **archive + sign** into a single command:
+
+```bash
+# Archives the unsigned XML under $output_dir/$(date +%F)/ and writes a signed .shortcut to $output_dir.
+"$SKILL_DIR/scripts/sign_shortcut.sh" /path/to/MyShortcut.xml --name "My Shortcut"
+
+# Override the signing mode (default is SHORTCUTS_PLAYGROUND_SIGNING_MODE, falling back to 'anyone').
+"$SKILL_DIR/scripts/sign_shortcut.sh" /path/to/MyShortcut.xml --name "My Shortcut" --mode people-who-know-me
+```
+
+The underlying pipeline is still the macOS `shortcuts` CLI:
+
+```bash
+shortcuts sign --mode anyone --input MyShortcut.shortcut --output MyShortcut.shortcut
+```
+
+The signing process:
+1. Write your plist as XML to a `.shortcut` file by default.
+2. Run `scripts/sign_shortcut.sh` (or `shortcuts sign` directly) to add the cryptographic signature (~19KB added). The wrapper archives the XML, then retries a validator-clean format failure after binary plist conversion when Apple's XML signer chokes.
+3. Keep the signed output filename equal to the intended display name (no `_signed` suffix).
+4. The signed file can be opened/imported into Shortcuts.app.
+
+Signing gotchas:
+- If `shortcuts sign` reports `Error: The file doesn't exist.` but the file exists, copy the XML plist directly to a clean `.shortcut` path and retry (example: `cp source.xml /tmp/MyShortcut.shortcut`).
+- If `shortcuts sign` reports `Error: The file couldn't be opened because it isn't in the correct format.` while `validate_shortcut.py` and `plutil -lint` pass, retry after `plutil -convert binary1` on the final `.shortcut` copy before blaming the plist. `scripts/sign_shortcut.sh` performs this retry automatically; if both attempts fail, suspect sandbox restrictions before treating the XML as malformed.
+- `ERROR: Unrecognized attribute string flag '?'` warnings are noisy but can be non-fatal if the output file is produced.
+- The `shortcuts` CLI supports `run`, `list`, `view`, and `sign`; do not assume `delete`, `rename`, or `import` subcommands.
+
+## Archive Raw XML (Required)
+
+Before signing, **archive the unsigned XML** in a date/time folder for inspection. `scripts/sign_shortcut.sh` does this for you, but the rules below still apply when you invoke `shortcuts sign` directly.
+
+Folder structure rule:
+- The archive root is `SHORTCUTS_PLAYGROUND_OUTPUT_DIR` (falls back to `~/Documents/Shortcuts Playground/` when unset).
+- Inside the archive root, create a **date folder** for the current day (`YYYY-MM-DD`) if it doesn't exist.
+- Copy the unsigned XML into that date folder with a time-stamped filename.
+
+Example (output dir = `~/Documents/Shortcuts Playground`):
+- Archive folder: `~/Documents/Shortcuts Playground/2026-02-03/`
+- Archive file: `My Shortcut-142355.xml`
+
+Command pattern (the one-liner `scripts/sign_shortcut.sh` wraps):
+```bash
+OUTPUT_DIR="${SHORTCUTS_PLAYGROUND_OUTPUT_DIR:-$HOME/Documents/Shortcuts Playground}"
+ARCHIVE_ROOT="$OUTPUT_DIR/$(date +%F)"
+mkdir -p "$ARCHIVE_ROOT"
+cp "/path/to/My Shortcut.xml" "$ARCHIVE_ROOT/My Shortcut-$(date +%H%M%S).xml"
+```
+
+The archive copy must be the **unsigned, raw XML** (not the signed `.shortcut`).
+
+## Workflow for Creating Shortcuts
+
+0. **Research external APIs** - For complex/unfamiliar APIs, read the latest official docs before drafting request code.
+1. **Define actions** - List what the shortcut should do
+2. **Generate UUIDs** - Each action that produces output needs a unique UUID
+3. **Build action array** - Create each action dictionary with identifier and parameters
+4. **Wire variable references** - Connect outputs to inputs using `OutputUUID`
+5. **Resolve icon and color** - Run `scripts/select_shortcut_icon_color.py` with the full user prompt (plus any explicit icon/color hints) and use the returned values
+6. **Wrap in plist** - Add the root structure with icon, name, version
+7. **Write to file** - Save as `.shortcut` (XML plist format is fine)
+8. **Preflight validation** - Run the Craig Loop (see above): validate → fix → re-validate, max 5 iterations.
+9. **Archive + Sign (required)** - Run `"$SKILL_DIR/scripts/sign_shortcut.sh" /path/to/file.xml --name "Final Name"`. This script archives the unsigned XML to `SHORTCUTS_PLAYGROUND_OUTPUT_DIR/$(date +%F)/` or `~/Documents/Shortcuts Playground/$(date +%F)/` and writes the signed `.shortcut` alongside it. Never leave the signing output filename with a `_signed` suffix.
+10. **Verify signed output (required)** - Confirm the signed `.shortcut` path reported by `sign_shortcut.sh` exists and has non-zero size before reporting done. Stopping at "validation passed" is a failed build.
+
+After step 8 succeeds, go directly to step 9. Any edit after validation, including comment or wording polish, requires another validation and another signing pass.
+
+## Comment Blocks (Repair-Oriented)
+
+Because variable wiring can require manual fixes, add a **concise Comment before each major block** with a **bulleted list** describing which variables must be connected. Keep it short, specific, and focused on wiring (e.g., “Use Repeat Item 2 inside inner loop”).
+Write comments with Shortcuts UI wording (for example, `Input`, `Date`, `Provided Input`, `Repeat Item`, `Text`) and readable action names (`Ask for Input`, `Text`, `Save File`). Do **not** use plist key jargon like `WFInput` / `WFDate` / `WFImage` in Comment text. **NEVER include UUIDs, OutputUUID references, or technical plist details in Comment text** — comments must be descriptive natural language only.
+Prefer wording like `- Input uses the text output from the Text action above` and `• Date uses the user's answer from Ask for Input` instead of `WF*` field names or UUID references.
+
+## Key Rules
+
+1. **UUIDs must be uppercase and generated via `uuidgen`, not hand-picked.** Before emitting a shortcut, run a single Bash call to generate all the UUIDs you'll need:
+    ```bash
+    for i in $(seq 1 <N>); do uuidgen | tr '[:lower:]' '[:upper:]'; done
+    ```
+    Where `<N>` is the number of action UUIDs the shortcut requires (one per action that produces output or is referenced by downstream actions). Assign each output line to a specific action in your working map, then paste them into the plist. **Never use sequential placeholders** like `11111111-1111-1111-1111-111111111111`, `AAAAAAAA-AAAA-AAAA-AAAA-AAAAAAAAAAAA`, or any other pattern where every hex character is the same — the validator rejects repeating-hex UUIDs as a hard error. Valid example shape: `7F3A4E91-C2D8-4B56-BE5A-0242AC120002`.
+2. **WFControlFlowMode is an integer**: Use `<integer>0</integer>` not `<string>0</string>`
+3. **Range keys use format**: `{position, length}` - e.g., `{0, 1}` for first character
+4. **The placeholder character**: `` (U+FFFC) marks where variables are inserted
+5. **Control flow needs matching ends**: Every repeat/if/menu start needs an end action with same `GroupingIdentifier`
+6. **Match placeholder positions**: `attachmentsByRange` must point to the exact index of each `` in the final string
+7. **No out-of-bounds ranges**: `attachmentsByRange` positions beyond string length can crash Shortcuts on import
+8. **Avoid empty placeholders**: Omit unused keys or fields; do not leave empty values where the action expects data
+9. **WFURL serialization**: For `WFURL` parameters (especially `downloadurl`), use `WFTextTokenString` with `` placeholders even when the URL is entirely a variable; reserve `WFTextTokenAttachment` for parameters that are explicitly variable-only (e.g., `WFVariable`, `WFRequestVariable`)
+10. **Form file fields and WFRequestVariable**: For `WFHTTPBodyType = Form`, file fields (`WFItemType = 5`) must wrap the file reference in `WFTokenAttachmentParameterState` with an inner `WFTextTokenAttachment` so the UI shows the connected file variable. Set `WFRequestVariable` only when body type is `File` (JSON Text fallback pattern)
+11. **Array fields**: For `WFDictionaryFieldValue` items with `WFItemType = 2`, use `WFArrayParameterState` with a list of items (`WFItemType` + `WFValue`), not numeric keys inside another dictionary
+12. **Format Date input**: Set `WFDate` (not `WFInput`) as a `WFTextTokenString` placeholder wired to a Date output; never leave `WFDate` empty
+13. **Repeat loops**: Inside **Repeat with Each**, use **Repeat Item** for per-item extraction; avoid **Repeat Results** inside the loop
+14. **Reuse extractions**: If you extract multiple fields from a dictionary/API response, reuse each value later or remove the unused extraction
+15. **Variable placeholders**: When composing strings or URLs with variables (Ask for Input, Track/Artist, etc.), insert a placeholder for every variable and align `attachmentsByRange` positions
+16. **Dictionary dot notation**: Use dot notation (with 1-based indexes) in `WFDictionaryKey` to access nested keys (e.g., `results.tracks.items`, `artists.1.name`), but guard optional parents first (avoid direct `error.message` on raw API responses)
+17. **Conditional inputs (verified against Apple-built samples)**: For `is.workflow.actions.conditional` with `WFControlFlowMode = 0`, **every** condition code requires an explicit `WFInput` set as `{ Type: "Variable", Variable: { Value: <ActionOutput or Variable>, WFSerializationType: "WFTextTokenAttachment" } }`. There is no implicit-input mode. Per-code literal field requirements: string codes `4`/`5`/`8`/`9`/`99`/`999` need `WFConditionalActionString`; numeric codes `0`/`1`/`2`/`3` need `WFNumberValue`; numeric `1003` (`is between`) needs both `WFNumberValue` (lower) and `WFAnotherNumber` (upper, attachment); existence codes `100`/`101` need neither literal field. Code `0` is `is less than` (NOT equals); codes `0`–`3` are inequalities. Multi-condition Ifs use `WFConditions` with `WFContentPredicateTableTemplate` serialization; do not mix `WFConditions` with top-level `WFCondition`. macOS 27 `Otherwise If` is the same conditional identifier with `WFControlFlowMode = 1` plus condition fields. Plain Otherwise is mode 1 with no condition fields; End If is mode 2. For JSON booleans, compare numerically (`1`/`0`); treat JSON `null` as empty. See `CONTROL_FLOW.md` "Condition Codes" and "Multi-condition If" for the complete reference and templates.
+18. **Workflow icon keys are mandatory**: Always set both `WFWorkflowIconGlyphNumber` and `WFWorkflowIconStartColor` in `WFWorkflowIcon` (use resolver output)
+19. **Runtime file picking**: If the user needs to choose a file, use `is.workflow.actions.file.select` and connect its output
+20. **Text token validation**: Run a final validation pass over every `WFTextTokenString` and refuse to output if any `attachmentsByRange` key does not map to a placeholder position or if counts mismatch
+21. **No unrequested services**: Do not introduce third-party APIs, external CDNs, or extra import questions unless the user explicitly requests them
+22. **Notion image uploads**: Default to Notion `file_uploads` + `file_upload` block type; avoid `external` image blocks unless the user supplies a URL or asks for external hosting
+23. **Notion title filters**: Use the Notion `title` property name unless the user explicitly says their database uses a different title property name (e.g., `Name`)
+24. **API research and endpoint accuracy**: For complex or unfamiliar external APIs, verify auth, endpoints, parameters, and payload formats against the latest official docs before assembling the shortcut. Validate endpoint strings exactly (underscore vs hyphen matters)
+25. **API string sanity checks**: Before output, scan API strings for `//` (beyond protocol) and empty JSON fields where variables are expected (e.g., `equals:””`, `id:””`, `url:””`, `filename:””`), and fix them
+26. **JSON request bodies**: For `WFHTTPBodyType = JSON`, use `WFJSONValues` for flat key/value payloads so the body is preserved in Shortcuts UI
+27. **Format Date custom style**: When `WFDateFormatStyle` is `Custom`, set `WFDateFormat=Custom` and put the pattern in `WFDateFormatString` (e.g., `MMMM d, yyyy`, `yyyy-MM-dd`, `yyyy-MM-dd'T'HH:mm:ssXXXXX`). See DATE_TIME.md for UNIX timestamp, ISO 8601, RFC 2822, and Unicode TR35 guidance
+28. **Complex JSON fallback**: If the JSON body includes arrays of objects or deep nesting and the UI renders it as `Number 0`/empty rows, use a JSON Text action and set `WFRequestVariable` to that text with `WFHTTPBodyType = File` and `Content-Type: application/json`
+29. **Filename extensions**: When using **Get Name** for file uploads, append the correct extension in the JSON payload (e.g., `.png`) and do not rely on the base name alone
+30. **Count input visibility**: For `is.workflow.actions.count`, set both `WFInput` and `Input` to the same variable so the UI shows the selected list
+31. **Get Name web titles**: For file names, set **Get Web Page Title** to **Off** in **Get Name** so the action returns the file name, not a URL title
+32. **String If workaround**: If validator rules conflict on string conditionals, use `Match Text` + `Count` + numeric `If` instead of direct string `If`
+33. **Replace Text empty replacement**: For delete-match patterns, prefer omitting `WFReplaceTextReplace`; an explicit empty string is allowed, but omission is cleaner and more portable
+34. **Base64 input wiring**: Always set `WFInput` for `is.workflow.actions.base64encode`; implicit input can import as an empty field and break runtime
+35. **Replace Text input visibility**: For `is.workflow.actions.text.replace`, use a `WFTextTokenString` placeholder (or wrapped variable input), not a bare `WFTextTokenAttachment`
+36. **Adjust Date reliability**: Use `WFDate` + non-empty `WFDuration` for `is.workflow.actions.adjustdate` (optionally mirror with `WFInput`); include `WFAdjustOperation` when explicit Add/Subtract is required. Offset-picker-only payloads can import as `Add 0 seconds` on iOS
+37. **Convert Image wiring**: For `is.workflow.actions.image.convert`, always set `WFInput` explicitly; do not rely on implicit input chaining
+38. **Weather detail wiring**: For `is.workflow.actions.properties.weather.conditions`, set both `WFInput` and `WFContentItemPropertyName`, keep `WFContentItemPropertyName` concrete (never placeholder `Detail`), and wire `WFInput` directly to an ActionOutput from `is.workflow.actions.weather.currentconditions` / `is.workflow.actions.weather.forecast` (no named-variable hop). Supported detail names are `Date`, `Location`, `Temperature`, `Low`, `High`, `Feels Like`, `Condition`, `Visibility`, `Dewpoint`, `Humidity`, `Pressure`, `Precipitation Amount`, `Precipitation Chance`, `Wind Speed`, `Wind Direction`, `UV Index`, `Sunrise Time`, `Sunset Time`, `Air Quality Index`, `Air Quality Category`, `Air Pollutants`, and `Name`. `Sunrise Time` and `Sunset Time` from Daily forecasts are lists: insert `Get Item from List` before `Format Date`, using First Item for sunrise and Last Item for sunset
+39. **Time Between Dates input wiring**: For `is.workflow.actions.gettimebetweendates`, set `WFInput` and exactly one non-empty date operand (`WFDate` or `WFTimeUntilCustomDate` or `WFTimeUntilFromDate`) as `WFTextTokenString` placeholders. To compare with now, first add a Date action set to Current Date and reference that action output; never put a direct `CurrentDate` magic token in the action. `WFTimeUntilUnit` may be omitted only when intentionally using the default unit. Never emit empty unused date keys
+40. **Extract from Image input wiring**: For `is.workflow.actions.extracttextfromimage`, set exactly one non-empty image input key. On OS 27+, prefer `imageFile`; older exported shortcuts may use `WFImage` or, when intentionally required by an existing pattern, `WFInput`.
+41. **API error extraction safety**: Do not read `error.message` directly from a raw response; extract `error`, guard it with `If Has Any Value`, then read `message`
+42. **Continuation JSON array closure**: When appending to a JSON array via `Replace Text` on `\]$`, the replacement must end with `]`; missing the closing bracket corrupts JSON and causes `Detect Dictionary` to return empty
+43. **No raw object/list tokens inside JSON text**: Do not inject Dictionary/List outputs (for example, raw API `content` arrays) directly into JSON Text templates; Shortcuts may stringify them as newline-separated blocks rather than valid JSON
+44. **Continuation payload safe pattern**: For multi-turn handoff payloads, append assistant text from a plain text variable (for example, `Response Text`) and keep `messages_json` as valid JSON before rerunning the shortcut
+45. **JSON string interpolation safety**: Before inserting freeform text into JSON Text templates (`”content”:””`), sanitize it first (at minimum handle backslashes, double quotes, and control whitespace/newlines) or the next `Detect Dictionary` step will fail
+46. **Shortcuts URL schemes**: Only use Apple-documented `shortcuts://` routes from URL_SCHEMES.md. URL-encode every query value; do not invent import/install routes or extra parameters
+47. **Run JavaScript on Webpage**: Use `is.workflow.actions.runjavascriptonwebpage` only for Safari webpage share-sheet shortcuts. Include `ActionExtension`, scope input to `WFSafariWebPageContentItem`, call `completion(...)` or `completion()`, return JSON-compatible values, and avoid synchronous dialogs/long timers
+46. **API response parse stability**: For `downloadurl` JSON APIs, keep `ShowHeaders` off unless explicitly needed and run `Detect Dictionary` on `Contents of URL` before any `Get Dictionary Value` extraction
+47. **Action input keys matter**: `Replace Text` uses `WFInput`, while `Change Case` and `Split Text` use `text`; wrong keys import but show empty inputs in the editor
+48. **Split Text custom separator**: If `WFTextSeparator` is `Custom`, always include `WFTextCustomSeparator` (a single space `” “` is valid)
+49. **Find Notes filter state**: `WFContentItemFilter` must be `WFContentPredicateTableTemplate` with non-empty templates; for `Folder` filters use `WFLinkDynamicOptionSubstitutableState` wrapping a tokenized variable
+50. **Direct variable wiring**: Prefer inserting named variables directly into action input fields; avoid redundant `Get Variable → next action` hops unless there is a clear transformation need
+51. **Location parameter wiring**: Never emit empty location parameters. For `WFLocation`, `WFWeatherCustomLocation`, and `WFWeatherLocation`, use `WFTextTokenAttachment` (not token strings) and reference a Get Current Location/Location output (directly or via a variable sourced from those outputs). `is.workflow.actions.location` must include a non-empty `WFLocation` attachment; missing/blank payloads import as empty “Location” fields
+52. **Set Name vs Rename File**: Use **Set Name** as `is.workflow.actions.setitemname` with `WFInput` (source file/item) and `WFName` (target filename, for example `Test.txt`) when a workflow needs a renamed file object to save or share elsewhere. Its output is **Renamed Item**. Do not confuse this with **Rename File** (`is.workflow.actions.file.rename` with `WFFile` and `WFNewFilename`), which renames the original file in place at its existing path. For "rename, save/share elsewhere, then delete original" workflows, store the picked file as **Original File**, run Set Name on **Original File**, save/share **Renamed Item**, then delete **Original File** only after the save/share step if requested
+53. **⚠️ WFMathOperation syntax (verified against Shortcuts app)**: For `is.workflow.actions.math`: (a) **Addition**: OMIT the `WFMathOperation` key entirely — no key means addition; (b) **Subtraction**: `-` (ASCII minus, U+002D); (c) **Multiplication**: `×` (U+00D7, ord 215, Unicode MULTIPLICATION SIGN) — NEVER `*`; (d) **Division**: `÷` (U+00F7, ord 247, Unicode DIVISION SIGN) — NEVER `/`; (e) **Scientific ops** (Modulus, Power, etc.): `WFMathOperation='…'` (U+2026 horizontal ellipsis) as placeholder, with real op in `WFScientificMathOperation` and operand in `WFScientificMathOperand`. **Literal operands** (`WFMathOperand`) must be plain strings like `"10"`, not wrapped dicts. Shortcuts silently renders ASCII `/` as `+` in the UI with no error. See PARAMETER_TYPES.md "Math and Counting Operations" for verified examples.
+54. **Never inspect the user's local system for authoring discovery unless the user explicitly asks for that local evidence.** If an action identifier is allowlisted in `data/toolkit-v*-tool-ids.json` but its parameter schema is not documented in the bundled reference files (`ACTIONS.md`, `APPINTENTS.md`, `PARAMETER_TYPES.md`, `FILTERS.md`, `EXAMPLES.md`, `BEST_PRACTICES.md`, `HEALTHKIT.md`, static `data/macos27-shortpy-grounding.json`, or the `golden-shortcuts/` library), **stop and ask the user** - do not try to reverse-engineer the schema by reading local databases, inspecting system binaries, querying Shortcuts.app internals, or searching cloud-backup folders without explicit permission. Escalate to the user with three options: (a) best-effort guess + iterate after they import, (b) use a simpler alternative action you propose, or (c) they paste a working example for you to mirror. When the user explicitly supplies or requests local exported XML, prefer that evidence over web references.
+55. **Automation triggers are sample-gated.** `AUTOMATION_TRIGGERS.md`, `data/toolkit-v78-trigger-parameter-keys.json`, and `data/macos27-workflow-trigger-samples.json` document OS 27 ToolKit trigger IDs, Python names, parameter keys, output types, and sanitized exported `WFWorkflowTriggers` payloads. Use exported automation-bearing shortcuts as the source of truth for portable authoring. Do not invent trigger plists from ToolKit metadata alone. Do not write live Shortcuts database rows; generate shortcut XML with a top-level `WFWorkflowTriggers` array, fresh `WFTriggerUUID` values, and `--target-macos 27` validation.
+56. **Bottom-align in Combine Images via the flip trick**: `is.workflow.actions.image.combine` in horizontal mode top-aligns images. To bottom-align without transparent canvas padding: (1) flip each input image upside-down before Combine, (2) run Combine (now "top" is the original bottom), (3) flip the combined result upside-down. ⚠️ **`is.workflow.actions.image.flip` behaves OPPOSITELY on iOS vs macOS — this is a genuine Apple bug across platforms**: on **iOS/iPadOS**, `WFImageFlipDirection='Vertical'` produces upside-down (direction-of-motion naming); on **macOS**, `WFImageFlipDirection='Horizontal'` produces upside-down (axis-of-reflection naming). The same plist value renders differently. **Workaround**: wrap the flip in an If block checking `Device Model is Mac` → Flip Horizontally / Otherwise → Flip Vertically. Do this for BOTH flips in the trick (per-image and combined result). Proven on Apple Frames 4 proportional scaling — worked on iOS but silently failed on macOS until the device check was added
+57. **Reminders: always use `is.workflow.actions.setters.reminders` for editing, never `UpdateReminderAppIntent`.** For every property of an existing reminder (Due Date, Title, Notes, Priority, Is Completed, Is Flagged, List, Subtasks, URL, Tags, Images, Parent Reminder, When Messaging Person), use one `setters.reminders` action per property with `Mode="Set"`, `WFContentItemPropertyName=<property name>`, and the matching `WFReminderContentItem<CamelCaseProperty>` value key. Chain multiple setters by pointing each one's `WFInput` at the previous setter's `ActionOutput` (`OutputName="Edited Reminder"`) so the "Edited Reminder" variable propagates. The `List` property is the only one that takes a plain string (the list name), not a token attachment. For date filtering in `filter.reminders`, operator `1002` ("is today") takes empty `Values`, operator `1003` ("is between") takes `Values.Date` (literal ISO `<date>`) + `Values.AnotherDate` (token attachment, typically `{Type: "CurrentDate"}`). See [PARAMETER_TYPES.md → Reminders — Filter & Setter Schemas](PARAMETER_TYPES.md#reminders--filter--setter-schemas-definitive) for the complete verified schema, the per-property value-key table, and verbatim templates.
+58. **HealthKit actions are iOS/iPadOS-only and must use `HEALTHKIT.md`.** For `filter.health.quantity`, put the Health sample kind in a non-removable `WFContentItemFilter` `Type` predicate row backed by `Values.Enumeration` / `WFStringSubstitutableState`; never use obsolete top-level `WFHealthQuantityType`, and never use `Property = Value` with a plain string such as `Step Count`. For summaries, use observed picker labels such as `Sleep`, `Exercise Minutes`, and `Active Calories`; do not emit `Sleep Analysis`, `Active Energy`, `Active Energy Burned`, `Apple Exercise Time`, or `Exercise Time` for HealthKit actions. Treat Sleep `Duration` math as seconds if coerced through Math: divide by `3600` for decimal hours, not `60`. For `properties.health.quantity`, `health.quantity.log`, and `health.workout.log`, use the bundled anonymized iOS XML examples and `data/healthkit-ios26.2-reference.json`. Do not guess the Log Health Sample schema: use `WFQuantitySampleType` plus `WFQuantitySampleQuantity` (`WFQuantityFieldValue`), allow unit-only `WFQuantitySampleAdditionalQuantity`, and add `WFCategorySampleEnumeration` only when a category picker value is needed. Do not run Health-writing shortcuts just to test syntax.

package/skills/shortcuts-playground/THIRD_PARTY_ACTIONS.md

@@ -0,0 +1,77 @@
+# Third-Party Actions Reference
+
+This file lists third-party actions discovered from:
+- macOS Shortcuts ToolKit database (installed apps)
+- Local shortcut backup exports
+
+Installed third-party actions (ToolKit): 11
+
+## Third-Party Actions (ToolKit)
+- `io.tailscale.ipn.macsys.ConnectIntent`
+- `io.tailscale.ipn.macsys.DeviceAppEntity`
+- `io.tailscale.ipn.macsys.DisconnectIntent`
+- `io.tailscale.ipn.macsys.PingAppIntent`
+- `io.tailscale.ipn.macsys.ProfileAppEntity`
+- `io.tailscale.ipn.macsys.SetDNSAppIntent`
+- `io.tailscale.ipn.macsys.StopUsingExitNodeIntent`
+- `io.tailscale.ipn.macsys.SwitchProfileIntent`
+- `io.tailscale.ipn.macsys.TaildropAppIntent`
+- `io.tailscale.ipn.macsys.ToggleAppIntent`
+- `is.workflow.actions.lightroom.import`
+
+Third-party actions referenced in backups: 49
+
+## Third-Party Actions (Backups)
+- `betamagic.News-Explorer.mobile.ArticleBySelection`
+- `betamagic.News-Explorer.mobile.ArticleEntity`
+- `co.montanafloss.Shareshot.FrameScreenshotsIntent`
+- `co.zottmann.ActionsForObsidian.CreateNote`
+- `co.zottmann.ActionsForObsidian.GetNoteLink`
+- `co.zottmann.ActionsForObsidian.SetNoteProperties`
+- `com.agiletortoise.Drafts-OSX.CaptureIntent`
+- `com.alexhay.ToolboxProForShortcuts.FindAlbumsIntent`
+- `com.alexhay.ToolboxProForShortcuts.FindSongsIntent`
+- `com.alexhay.ToolboxProForShortcuts.PlayMusicIntent`
+- `com.alexhay.nautomate.AddValuesToDatabaseIntent`
+- `com.alexhay.nautomate.CreateBookmarkBlockIntent`
+- `com.alexhay.nautomate.CreateDividerBlockIntent`
+- `com.alexhay.nautomate.CreateListBlockIntent`
+- `com.alexhay.nautomate.CreateSmartBlocksFromTextIntent`
+- `com.alexhay.nautomate.CreateTextBlockIntent`
+- `com.culturedcode.ThingsMac.TAIAddTodo2`
+- `com.culturedcode.ThingsMac.TAIItemEntity`
+- `com.finnvoorhees.ShortcutButtons.NewButtonForShortcutIntent`
+- `com.google.gemini.TypeToGeminiIntent`
+- `com.gtrigonakis.TextWorkflow.TransformTextIntent`
+- `com.gtrigonakis.TextWorkflowIOS.TransformTextIntent`
+- `com.joehribar.toggl.StopTimeEntryIntent`
+- `com.lireapp.smilingAlpaca.LIREGetArticleIdentifiersIntent`
+- `com.lireapp.smilingAlpaca.LIREGetArticlePropertyIntent`
+- `com.lireapp.smilingAlpaca.LIREGetCurrentArticleIdentifierIntent`
+- `com.ngocluu.goodlinks.AddLinkIntent`
+- `com.ngocluu.goodlinks.AddTags`
+- `com.ngocluu.goodlinks.GetCurrentLink`
+- `com.ngocluu.goodlinks.GetCurrentSelection`
+- `com.ngocluu.goodlinks.GetTagsIntent`
+- `com.ngocluu.goodlinks.HighlightEntity`
+- `com.ngocluu.goodlinks.LinkEntity`
+- `com.ngocluu.goodlinks.OpenHighlight`
+- `com.ngocluu.goodlinks.OpenLinkIntent`
+- `com.openai.chat.OpenVoiceModeIntent`
+- `com.sindresorhus.AI-Actions.AskClaudeIntent`
+- `com.sindresorhus.Actions.GenerateUUIDIntent`
+- `com.sindresorhus.Actions.GetAudioPlaybackDestinationIntent`
+- `com.sindresorhus.Actions.GetFilePathIntent`
+- `com.sindresorhus.Actions.GetTitleOfURLIntent`
+- `com.sindresorhus.Actions.TruncateNumber`
+- `com.sindresorhus.Shortcutie.SetDefaultSoundDevice`
+- `com.todoist.ios.OpenRambleAppIntent`
+- `dk.simonbs.Jayson.ViewJSONIntent`
+- `net.matrixteo.app.Collections.IntentsAddArrayValue`
+- `net.matrixteo.app.Collections.IntentsAddDocument`
+- `net.matrixteo.app.Collections.IntentsDocumentEntity`
+- `net.matrixteo.app.Collections.IntentsUpdateValue`
+
+Notes:
+- Backup-only entries may come from apps not installed on this Mac.
+- WF-style third-party actions can still use the `is.workflow.actions.*` prefix (e.g., Lightroom).

package/skills/shortcuts-playground/TOOLKIT_SNAPSHOT.md

@@ -0,0 +1,62 @@
+# Action ID Snapshots
+
+This skill bundles precomputed action-ID allowlists so it can be shared without requiring any extra setup on the user's machine.
+
+## Bundled files
+
+- `data/toolkit-v63-tool-ids.json` - flat list of 1,794 action/intent identifiers from the original ToolKit snapshot.
+- `data/toolkit-v78-tool-ids.json` - flat list of 2,731 action/intent identifiers from macOS 27 Golden Gate build 26A5353q.
+- `data/toolkit-v78-ios27-tool-ids.json` - flat list of 1,206 action/intent identifiers from an iOS 27.0 Simulator ToolKit v78 database.
+- `data/toolkit-v78-first-party-parameter-keys.json` - compact first-party ToolKit v78 parameter-key/name/type catalog with per-parameter platform provenance, used by `lookup_action_grounding.py` for broad AppIntent/schema discovery.
+- `data/toolkit-v78-first-party-enum-cases.json` - compact first-party ToolKit v78 enum-case catalog for action and automation-trigger parameter type names.
+- `data/toolkit-v78-trigger-parameter-keys.json` - compact ToolKit v78 automation trigger catalog with trigger IDs, Python names, parameter keys, and output type identifiers.
+- `data/macos27-workflow-trigger-samples.json` - sanitized exported OS 27 `WFWorkflowTriggers` samples for automation headers that have been observed in real shortcut exports.
+- `data/macos27-shortpy-grounding.json` - reviewed static Apple-derived macOS 27 grounding catalog with ToolKit `pythonName`, Apple Shortpy keyword, ToolRenderer utility, and ShortcutsLanguage syntax evidence.
+
+Only the identifiers and compact parameter/enum metadata needed for validation and lookup are bundled. This keeps the plugin lightweight compared with the full ToolKit SQLite metadata.
+
+## Validator behavior
+
+`scripts/validate_shortcut.py` loads packaged `data/toolkit-v*-tool-ids.json` files according to the target OS version and target platform, then augments those snapshots with the markdown references (`ACTIONS.md`, `APPINTENTS.md`, `THIRD_PARTY_ACTIONS.md`). OS 27 snapshots include both macOS 27 and iOS 27 Simulator ToolKit evidence, but iOS-only snapshot rows are rejected for the default macOS platform target. It also target-gates the reviewed Automators OS 26 to 27 parameter deltas, so OS 27-only parameter keys are rejected on macOS 26 targets even when the action identifier itself predates OS 27.
+
+For macOS/iOS 27 targets, the validator also loads `data/toolkit-v78-first-party-parameter-keys.json` as a schema check for first-party `com.apple.*` AppIntent-style actions. If a known AppIntent carries a top-level parameter key that does not appear in the active target's ToolKit v78 schema, validation fails. The catalog is filtered at the parameter level, so a field observed only in the iOS 27 Simulator ToolKit is rejected for the default macOS target even if the action row itself exists on both platforms. The validator also loads `data/toolkit-v78-first-party-enum-cases.json` and rejects invalid simple literal enum values for single-enum AppIntent parameters. It intentionally skips dynamic token values and multi-type parameters, and it does not apply broad unknown-key checks to regular `is.workflow.actions.*` actions because legacy WF actions can include valid plist/UI state keys that are absent from ToolKit parameter metadata.
+
+The default OS target is `auto`: on macOS it reads `sw_vers -productVersion`; when the host cannot be detected it falls back to macOS 26 rather than latest. Override with `--target-macos 26`, `--target-macos 27`, or `--target-macos latest`. The same override is available via `SHORTCUTS_PLAYGROUND_TARGET_MACOS`.
+
+The default platform target is `macos`. Override with `--target-platform ios` / `SHORTCUTS_PLAYGROUND_TARGET_PLATFORM=ios` for iPhone/iPad authoring, or `--target-platform all` only when intentionally validating every packaged platform.
+
+This keeps validation portable and self-contained while avoiding false compatibility on machines that do not have macOS 27 installed.
+
+## macOS 27 scope
+
+The v78 snapshot expands validation coverage for shortcuts created on macOS 27. It is only active when the target is macOS 27+ or `latest`. The action-ID snapshots are identifier allowlists, not complete authoring schemas. For first-party `com.apple.*` AppIntent-style actions, the v78 parameter catalog can reject unknown top-level keys, but it does not prove full value serialization, requiredness, picker state, or runtime behavior. If a v78-only action identifier is present but its parameter serialization is not documented in the reference files or a golden XML, do not guess the payload. Ask for an exported XML sample or use a documented fallback.
+
+OS 27-era parameter keys are also target-gated. Examples include `WFAllowWebSearch` and `FollowUp` on Use Model, `interpretAsMarkdown` on Notes actions, `WFAvoidTolls`/`WFAvoidHighways` on Maps route actions, `WFAppsExcept` on Hide/Quit App, `imageFile` on Scan QR or Barcode / Extract from Image, and `contents` on Safari Create Tab Group.
+
+## iOS 27 simulator scope
+
+The iOS 27 Simulator v78 snapshot adds iOS-only AppIntents that are not present in the macOS ToolKit database, such as `com.apple.HearingApp.MuteVolumeIntent` and iOS Settings/Wallet/Health/Fitness identifiers. These identifiers are included for iOS/iPadOS shortcut authoring and are also target-gated to OS 27+. They do not validate for the default macOS target; use `--target-platform ios` only when authoring for iPhone/iPad. Do not use them for macOS shortcuts unless a macOS ToolKit snapshot or exported shortcut confirms runtime support.
+
+## Apple-derived grounding catalog
+
+`data/macos27-shortpy-grounding.json` is a portable metadata catalog generated from local macOS 27 Shortcuts ToolKit, ToolRenderer, WorkflowKit source-export, and installed sample evidence. It is static package data: normal validation does not read the user's live Shortcuts database and does not load private frameworks.
+
+Use `scripts/lookup_action_grounding.py` to inspect it:
+
+```bash
+python3 scripts/lookup_action_grounding.py --identifier additemtolist --target-macos 27
+python3 scripts/lookup_action_grounding.py --python-name com_apple_shortcuts_add_item_to_list --json
+python3 scripts/lookup_action_grounding.py --identifier com.apple.HearingApp.MuteVolumeIntent --target-macos 27 --target-platform ios --json
+```
+
+The grounding catalog can improve authoring confidence, but it does not override target availability. `lookup_action_grounding.py` reports the requested target macOS and target platform, including a target-platform availability note when an entry is only observed in the opposite platform's ToolKit rows. If `validate_shortcut.py --target-macos 26` rejects a v78-only identifier or parameter key, the static grounding entry is only a note that the action or parameter exists in OS 27-era ToolKit metadata.
+
+`lookup_action_grounding.py` computes per-action availability from the packaged ToolKit snapshots, not from the grounding catalog's source OS. Older actions that appear in the macOS 27 grounding catalog still remain available to older targets when they are present in `toolkit-v63`.
+
+The lookup helper also reads `data/toolkit-v78-first-party-enum-cases.json` and attaches `enumCases` / `enumTypes` to ToolKit parameter summaries. This exposes concrete picker values such as Add Item to List `Beginning` / `End` / `Index`, Find Places `Relevance` / `Distance`, Set Multitasking Mode `fullScreenApps` / `windowedApps` / `stageManager`, VPN operations, and trigger state values. Dynamic user-local picker cases, such as personal Reminders list names or Contacts groups, are intentionally redacted from the packaged enum catalog. These cases improve authoring and catalog review, but they still do not prove full plist serialization for complex picker states.
+
+## Automation trigger metadata
+
+`data/toolkit-v78-trigger-parameter-keys.json` packages the 42 automation triggers exposed in local macOS 27 and iOS 27 Simulator ToolKit v78 databases. This includes identifiers such as `com.apple.shortcuts.WFTimeOfDayTrigger.at_time_on_recurring_day`, Apple Shortpy-style names such as `when_app_opened`, trigger parameter keys, and raw output type identifiers.
+
+ToolKit trigger metadata is discovery metadata only. Portable automation headers must come from exported shortcut evidence: use `data/macos27-workflow-trigger-samples.json` and [AUTOMATION_TRIGGERS.md](AUTOMATION_TRIGGERS.md) for sanitized `WFWorkflowTriggers` payload shapes. The validator checks top-level `WFWorkflowTriggers` for OS 27 targets, rejects placeholder values, and target-gates automation headers away from macOS 26/iOS 26 output. Do not infer trigger payloads from ToolKit rows alone.