Dash Docset Search

Overview

Use this skill to search Dash content with a strict fallback order:

1. dash-mcp-server tools first
2. local Dash HTTP API second
3. Dash URL scheme and macOS Service guidance last

Use references/dash_mcp_tools.md, references/dash_http_api.md, and references/dash_url_and_service.md for exact details.

Automation Prompting

• Codex App automation fit: Strong. Suitable for recurring search and reporting workflows.
• Codex CLI automation fit: Strong. Suitable for non-interactive probe/search tasks with fallback handling.
• Use references/automation-prompts.md for Codex App and Codex CLI templates, placeholders, and output shapes.
• Keep install and generation actions out of this skill's automation prompts; hand off to $dash-docset-install-generate when needed.

Workflow

1) Establish access path

1. If Dash MCP tools are available, use them first.
2. If Dash MCP tools are unavailable, run:
   • uv run python scripts/dash_api_probe.py
3. If probe indicates local API healthy, use /docsets/list, /search, and /docsets/enable_fts.
4. If local API is unavailable, provide dash:// and Service fallback guidance.

2) List installed docsets

• Preferred:
  • list_installed_docsets
• HTTP fallback:
  • GET {base_url}/docsets/list

Normalize and present:

• display name
• identifier
• platform
• full-text status

3) Search one or many docsets

• Preferred:
  • search_documentation(query, docset_identifiers, search_snippets, max_results)
• HTTP fallback:
  • GET /search?query=...&docset_identifiers=...

Rules:

• Use explicit identifiers from installed docsets.
• Disable snippet search if user asks for docset-only results.
• For multi-docset searches, pass comma-separated identifiers in one query.

4) Enable FTS when requested

• Preferred:
  • enable_docset_fts(identifier)
• HTTP fallback:
  • GET /docsets/enable_fts?identifier=...

Handle full_text_search status:

• enabled: continue searching
• disabled: enable then retry search
• indexing: explain indexing in progress
• not supported: skip FTS path

5) Missing docset recommendation

Use catalog snapshots and matcher:

1. uv run python scripts/dash_catalog_match.py --query "<text>"
2. classify top results into:
   • built-in
   • user-contributed
   • cheatsheet
3. if no strong hit, suggest generator flow
4. suggest GitHub or Stack Overflow generation only as last resort

When installation or generation is needed, hand off to $dash-docset-install-generate.

Fallback Search Guidance

When no API path is usable, provide direct commands:

• AppleScript:
  • open location "dash://?query={query}"
  • open location "dash://?query=python:{query}"
• Terminal:
  • open "dash://?query={query}"
• macOS Service:
  • select text, then Services > Look Up in Dash

Scripts

• scripts/dash_api_probe.py
  • Probe local Dash API state and schema path availability.
• scripts/dash_catalog_refresh.py
  • Refresh built-in, contributed, and cheatsheet snapshots.
• scripts/dash_catalog_match.py
  • Rank candidate docsets and cheatsheets for a query.
• scripts/dash_url_search.py
  • Launch dash:// query URLs.
• scripts/dash_url_install.py
  • Confirm-first launcher for dash-install://.

References

• references/dash_mcp_tools.md
• references/dash_http_api.md
• references/dash_url_and_service.md
• references/automation-prompts.md
• references/catalog_built_in_docsets.json
• references/catalog_user_contrib_docsets.json
• references/catalog_cheatsheets.json

Optional Visual Troubleshooting

If Dash UI behavior needs visual confirmation, use the $screenshot skill if it is available in the user's environment.

Interactive Customization Flow

1. Load current effective customization settings first:

• uv run python scripts/customization_config.py effective

2. Ask targeted customization questions:

• Use references/customization-flow.md to drive knob-by-knob questions.
• Confirm desired behavior changes and safety constraints.

3. Map requested changes to implementation files:

• Update SKILL.md, references/*, and any runtime script files listed in references/customization-flow.md.

4. Persist durable customization state:

• Start from customization.template.yaml defaults.
• Apply approved overrides with uv run python scripts/customization_config.py apply --input <yaml-file>.
• Durable path: ~/.config/gaelic-ghost/apple-dev-skills/<skill-name>/customization.yaml.
• Optional override root: APPLE_DEV_SKILLS_CONFIG_HOME.

5. Report resulting effective configuration:

• Re-run uv run python scripts/customization_config.py effective and summarize final active settings.
• If the user asks to remove customization state, run uv run python scripts/customization_config.py reset.

Use references/customization-flow.md for skill-specific knobs, file mapping, guardrails, validation checks, and example requests.