1. Official Docs Retrieval: Find authoritative answers from Salesforce documentation first
2. Local-First Search: Use a local qmd index when available for speed and accuracy
3. Salesforce-Aware Fallback: When qmd is unavailable or weak, use Salesforce-specific retrieval patterns instead of generic web fetch
4. Source Grounding: Return answers with exact source URLs, guide names, and retrieval notes
5. Cross-Skill Support: Serve as the documentation lookup layer for other

   sf-*

   skills

1. Detect qmd availability
2. Query qmd first
3. Evaluate result quality
4. If results are strong, answer from local docs
5. If results are weak or missing, fall back to Salesforce-aware scraping

1. Identify the most likely Salesforce doc family
2. Use Salesforce-aware discovery and retrieval patterns
3. Prefer official URLs over summaries from third-party blogs
4. Fall back to official PDFs when web pages are unstable or shell-rendered
5. Return grounded findings with source links and any uncertainty called out

sf-docs

python3 ~/.claude/skills/sf-docs/scripts/cli.py retrieve \
  --query "<user question>" \
  --mode no_qmd

help.salesforce.com

sf-docs

1. Check whether the

   qmd

   CLI is available on

   PATH

2. Check whether a local Salesforce docs corpus exists
3. If qmd exists but the local corpus/index is missing or effectively empty, treat the request as no-qmd mode
4. If qmd exists and the corpus is populated, use qmd-enabled mode

Reference: references/local-corpus-layout.md

• No results returned
• Results are clearly from the wrong Salesforce product or guide family
• Results lack the exact concept, API name, CLI command, or error term requested
• Results are too fragmentary to answer confidently
• Results appear stale and the query is obviously release-sensitive

Rule: Prefer a reliable Salesforce-specific fallback over confidently answering from a poor local hit.

• A specific guide root
• A specific article or page
• A guide PDF when page-level retrieval is unstable

• Modern platform guide:

  developer.salesforce.com/docs/platform/...

• Legacy Atlas guide:

  developer.salesforce.com/docs/atlas.en-us.<book>.meta/...

• Guide PDF candidate: derive

  <book>

  and try the matching official PDF URL

1. the guide root
2. the legacy Atlas variant if known
3. the official PDF

• Prefer exact

  help.salesforce.com/s/articleView?id=...

  URLs or article identifiers when available
• If you only have a product/topic query, start from a targeted official hub and discover linked Help articles from there
  • Agentforce queries: start from the Agentforce developer guide and follow linked Help articles
  • Messaging / Enhanced Web Chat queries: start from the Enhanced Web Chat docs or landing Help article, then follow one hop to child setup/security articles
• Expect navigation shell noise and incomplete body extraction
• Focus on retrieving the actual article body, not the rendered header/footer shell
• Reject shell or soft-404 pages such as "We looked high and low but couldn't find that page"
• Cross-check titles, product area, and article body before trusting a result

• The guide has a stable official PDF
• HTML extraction is inconsistent
• A long-form developer guide is easier to search locally after normalization

sf-docs

1. Source type — qmd local hit, official HTML page, or official PDF
2. Guide/article name
3. Exact official URL
4. Any retrieval caveat — for example, if fallback scraping was needed or if the content appeared partially rendered

• sf-docs

  is part of the core skill suite
• qmd remains an optional external dependency
• Downloaded PDFs, scraped markdown, manifests, and indexes should live on the user's machine
• Official Salesforce docs content should not be stored in this public Git repository

~/.sf-docs/

• ~/.sf-docs/manifest/

  — discovery manifests and fetch/index status

• ~/.sf-docs/raw/pdf/

  — downloaded official PDFs

• ~/.sf-docs/raw/html/

  — optional raw HTML captures

• ~/.sf-docs/normalized/md/

  — canonical markdown corpus for qmd indexing

• ~/.sf-docs/qmd/

  — qmd-specific config notes

• ~/.sf-docs/logs/

  — optional diagnostics and fetch logs

Full reference: references/local-corpus-layout.md

1. qmd-first when available
2. Sequential fallback to Salesforce-aware scraping
3. Targeted retrieval, not broad crawling, during normal lookups
4. Grounded responses with official source links

1. Detect qmd and local corpus availability
2. Run qmd lookup if available
3. Evaluate hit quality
4. On weak/missing results, use Salesforce-specific HTML/PDF fallback
5. Answer with source grounding and retrieval caveats when needed

Full runtime guide: references/runtime-workflow.md

sf-docs

• Finds the right Salesforce page or PDF more often
• Avoids failed fetches on

  help.salesforce.com

• Reduces hallucinations by grounding on official sources
• Improves the documentation quality available to the rest of the

  sf-*

  skills