Apple Dash Docsets

Apple Dash Docsets

Purpose

Manage Dash docsets and cheatsheets on macOS with one top-level entry point. scripts/run_workflow.py is the authoritative runtime path for stage selection, fallback order, source priority, approval gating, and structured generation guidance; it does not replace the agent's own Dash access methods.

When To Use

• Use this skill for Dash search and discovery requests.
• Use this skill for Dash installation requests after search has identified a missing docset.
• Use this skill for Dash generation guidance when installation cannot complete.
• Use this skill when the user needs the exact fallback path between agent-side Dash MCP usage, local HTTP, and URL or Service integration.
• Recommend apple-xcode-workflow when the user needs Apple or Swift execution, diagnostics, build or test work, or Apple docs reasoning outside Dash management.
• Recommend apple-swift-package-bootstrap when the user is starting a brand new Swift package rather than managing Dash content.

Single-Path Workflow

1. Classify the request into one stage:
   • search
   • install
   • generate
2. If no stage is explicit, start at search.
3. Run scripts/run_workflow.py with the selected stage:
   • search: applies configured fallback order and returns a structured access-path decision
   • install: applies configured source priority and approval gating
   • generate: returns structured automation-first guidance
4. If the selected stage cannot complete, hand off forward through references/stage-handoff-contract.md:
   • search -> install
   • install -> generate
5. Return one status, one path_type, and one output contract for the stage that ran.

Inputs

• stage: search, install, or generate
• query: required for search
• docset_identifiers: optional for search; use installed identifiers only
• docset_request: required for install and generate
• approval: required before side-effectful install actions
• Defaults:
  • runtime entrypoint: python3 scripts/run_workflow.py
  • search access order is mcp -> http -> url-service
  • install source priority is built-in,user-contributed,cheatsheet
  • default search result limit is 20
  • default search snippets setting is true

Outputs

• status
  • success: the selected stage completed on its primary or fallback path
  • blocked: prerequisites, approval, or usable access paths are missing
  • handoff: the current stage is handing off to the next Dash stage
• path_type
  • primary: the selected stage completed normally
  • fallback: the selected stage completed through its documented fallback path
• output
  • stage
  • access_path or source_path
  • matches
  • install result or generation guidance when applicable
  • one next step when follow-up is required

Guards and Stop Conditions

• Do not run install actions without explicit user approval.
• Do not invent docset identifiers or catalog matches.
• Stop with blocked when agent-side Dash MCP usage, HTTP, and URL or Service paths are all unusable for search.
• Stop with blocked when install or generate lacks a concrete docset request.
• Keep search, install, and generate in forward stage order; do not blend them into competing primary workflows.

Fallbacks and Handoffs

• search falls back in this order: agent-side Dash MCP usage, local HTTP API, then URL or Service guidance.
• install hands off to generate when no installable catalog match exists.
• generate falls back from stable automation to deterministic manual guidance.
• Use references/stage-handoff-contract.md when search transitions to install or install transitions to generate.
• Recommend apple-xcode-workflow directly when the user’s task shifts from docs management to Apple or Swift execution work.
• Recommend apple-swift-package-bootstrap directly when the user needs new Swift package scaffolding.
• scripts/run_workflow.py is the only local runtime entrypoint for stage behavior; helper scripts remain implementation details behind it.

Customization

• Use references/customization-flow.md.
• scripts/customization_config.py stores and reports customization state.
• scripts/run_workflow.py loads and enforces the runtime-safe knobs documented in references/customization-flow.md.

References

Workflow References

• references/dash_mcp_tools.md
• references/dash_http_api.md
• references/dash_url_and_service.md

Contract References

• references/stage-handoff-contract.md
• references/automation-prompts.md
• references/customization-flow.md

Support References

• Recommend references/snippets/apple-swift-core.md when the user needs a reusable Apple and Swift baseline snippet in their own repo alongside Dash-based docs workflows.
• references/catalog_built_in_docsets.json
• references/catalog_user_contrib_docsets.json
• references/catalog_cheatsheets.json
• references/snippets/apple-swift-core.md

Script Inventory

• scripts/run_workflow.py
• scripts/dash_api_probe.py
• scripts/dash_catalog_match.py
• scripts/dash_catalog_refresh.py
• scripts/dash_url_search.py
• scripts/dash_url_install.py