# Example: Cross-Context Disambiguation

## User Query
> /docs skills

## Skill Reasoning
- User names a specific topic: "skills"
- Strategy: Direct manifest lookup
- Multiple product contexts expected

## Actions
1. Query the manifest:
   ```bash
   jq -r '.pages[] | select(.filename | test("skills")) | [.filename, .category] | @tsv' ~/.claude-code-docs/paths_manifest.json
   ```
2. Results span several product contexts (and both doc hosts):
   - `claude-code__skills.md` → **Claude Code** (code.claude.com)
   - `claude-code__agent-sdk__skills.md` → **Agent SDK** (code.claude.com)
   - `docs__en__api__beta__skills.md` and related → **Claude API** (platform.claude.com)
   - `docs__en__agents-and-tools__agent-skills__overview.md` and related → **Agents & Tools** (platform.claude.com)
3. Different contexts → ASK the user

## Output Format
"Skills exist across several Claude products with different purposes:

1. **Claude Code** — Install and run pre-built skills in the CLI
2. **Agent SDK** — Build custom agent capabilities in Python/TypeScript
3. **Claude API** — Programmatic skill management endpoints
4. **Agents & Tools** — Agent skill patterns and best practices

Which are you working with?"

[After user selects, e.g., "1. Claude Code"]

→ Read `~/.claude-code-docs/cache/claude-code__skills.md` (on a cache miss:
`~/.claude-code-docs/plugin/scripts/fetch-docs.sh get "claude-code__skills.md"` first),
synthesize, present with the manifest's source link
([Extend Claude with skills](https://code.claude.com/docs/en/skills)).

---

## User Query (with SDK context)
> /docs how do I create messages in Python?

## Skill Reasoning
- User mentions "Python" → SDK language disambiguation applies
- Topic: "messages" + "create" + Python client SDK

## Actions
1. Run: `bash ~/.claude-code-docs/plugin/skills/claude-docs/scripts/content-search.sh "python" "sdk"`
   → top hits include `docs__en__cli-sdks-libraries__sdks__python.md` (Python client SDK)
2. Fetch and read it, plus the API reference page `docs__en__api__messages__create.md`
   for the endpoint parameters
3. Present the Python SDK example
4. Note: "TypeScript equivalent: [TypeScript SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/typescript)"

Sources:
- [Python SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/sdks/python)
- [Create a Message](https://platform.claude.com/docs/en/api/messages/create)

# Example: Direct Lookup

## User Query
> /docs hooks

## Skill Reasoning
- User names a specific topic: "hooks"
- Strategy: Direct manifest lookup (exact topic named)
- No product context specified — search broadly

## Actions
1. Query the manifest:
   ```bash
   jq -r '.pages[] | select(.filename | test("hooks")) | .filename' ~/.claude-code-docs/paths_manifest.json
   ```
2. Results:
   - `claude-code__hooks.md` (Claude Code CLI — "Hooks reference")
   - `claude-code__hooks-guide.md` (Claude Code CLI — "Automate actions with hooks")
   - `claude-code__agent-sdk__hooks.md` (Agent SDK — "Intercept and control agent behavior with hooks")
   - `docs__en__api__beta__webhooks.md` (matched "hooks" but is webhooks — irrelevant, drop it)
3. Read `~/.claude-code-docs/cache/claude-code__hooks.md` and `~/.claude-code-docs/cache/claude-code__hooks-guide.md`.
   On a cache miss, fetch first: `~/.claude-code-docs/plugin/scripts/fetch-docs.sh get "claude-code__hooks.md"`, then read.
4. Both CLI files are same context → synthesize
5. Agent SDK file is different context → note but include since "hooks" is unambiguous enough
6. Get exact source URLs from the manifest (never reconstruct from filenames):
   ```bash
   jq -r '.pages[] | select(.filename=="claude-code__hooks.md") | .url' ~/.claude-code-docs/paths_manifest.json
   ```

## Output Format
"Claude Code hooks allow you to run shell commands at specific points in Claude's workflow...

[Synthesized explanation from both CLI docs]

For Agent SDK hooks, see also the [Agent SDK hooks guide](https://code.claude.com/docs/en/agent-sdk/hooks).

Sources:
- [Hooks reference](https://code.claude.com/docs/en/hooks)
- [Automate actions with hooks](https://code.claude.com/docs/en/hooks-guide)
- [Intercept and control agent behavior with hooks](https://code.claude.com/docs/en/agent-sdk/hooks)"

# Example: Semantic Search

## User Query
> /docs best practices for extended thinking

## Skill Reasoning
- User asks a question — no exact filename match for "best practices for extended thinking"
- Strategy: Content search (default for questions and topics)
- **Keyword extraction:** Strip filler words → `"extended"` `"thinking"`
- Check synonym table: "thinking" → also try "extended thinking", "adaptive thinking"

## Actions
1. Run:
   ```bash
   bash ~/.claude-code-docs/plugin/skills/claude-docs/scripts/content-search.sh "extended" "thinking"
   ```
2. Output is `filename<TAB>title<TAB>score`, best first:
   ```
   docs__en__build-with-claude__extended-thinking.md	Extended thinking (legacy)	81.97
   docs__en__build-with-claude__thinking.md	Overview	51
   docs__en__build-with-claude__thinking-troubleshooting.md	Troubleshooting	44.91
   docs__en__build-with-claude__thinking-steering-and-cost.md	Steering and cost control	37.97
   docs__en__build-with-claude__thinking-tool-workflows.md	Tool and multi-turn workflows	34.28
   ```
3. All are platform docs (same context) → read the top 2-3 from
   `~/.claude-code-docs/cache/<filename>`; on a cache miss, fetch first:
   `~/.claude-code-docs/plugin/scripts/fetch-docs.sh get "docs__en__build-with-claude__thinking.md"`
4. Note the top hit is titled "(legacy)" — lead with the current overview page, cite both
5. Get exact URLs from the manifest:
   ```bash
   jq -r '.pages[] | select(.filename=="docs__en__build-with-claude__thinking.md") | .url' ~/.claude-code-docs/paths_manifest.json
   ```

## Output Format
"Extended thinking lets Claude work through complex problems step by step before responding...

[Synthesized best practices from the matched docs]

Sources:
- [Thinking overview](https://platform.claude.com/docs/en/build-with-claude/thinking)
- [Extended thinking (legacy)](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)
- [Steering and cost control](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost)"

#!/usr/bin/env bash
# content-search.sh — full-text keyword search over the v2 search index.
# Usage: content-search.sh <keyword> [keyword2 ...]
#
# Scores each page (BM25-lite in jq): title x10 + filename-slug x10 + matched
# headings (capped 3) x3 + sqrt(stemmed-term freq) x2. Falls back to grep over
# the cache when the index or jq is unavailable. Uniform output on BOTH paths:
# filename<TAB>title<TAB>score, sorted by score descending (top 20).
#
# STEMMING must match scripts/build_search_index.py exactly (strip first of
# ing/ed/es/s if >=3 chars remain). See tests/unit/test_stem_parity.py.

set -uo pipefail
trap '' PIPE

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
CLONE_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
INDEX="${CLAUDE_DOCS_INDEX:-$CLONE_ROOT/search_index.json}"
CACHE_DIR="${CLAUDE_DOCS_CACHE_DIR:-${DOCS_DIR:-$CLONE_ROOT/cache}}"

if [ $# -eq 0 ]; then
    echo "Usage: content-search.sh <keyword> [keyword2 ...]" >&2
    exit 1
fi

# Sanitize + tokenize like the Python indexer: split on every non-alphanumeric char
# so a compound query fans into the same tokens the index holds ("agent-sdk" ->
# "agent" "sdk", "node.js" -> "node" "js"). Keeping hyphens made a hyphenated query
# match no index field and score 0 (build_search_index.py:100-106 splits on non-alpha).
keywords=()
for arg in "$@"; do
    clean=$(printf '%s' "$arg" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/ /g')
    read -ra toks <<< "$clean"
    for w in "${toks[@]}"; do
        [ -n "$w" ] && keywords+=("$w")
    done
done
if [ ${#keywords[@]} -eq 0 ]; then
    echo "No valid keywords provided" >&2
    exit 1
fi

# Strategy 1: v2 index + jq (BM25-lite scoring, stemming mirrored from Python).
if [ -f "$INDEX" ] && command -v jq >/dev/null 2>&1; then
    results=$(jq -r --args '
        def stem:
          ascii_downcase as $w
          | if   ($w|endswith("ing")) and (($w|length) >= 6) then $w[0:-3]
            elif ($w|endswith("ed"))  and (($w|length) >= 5) then $w[0:-2]
            elif ($w|endswith("es"))  and (($w|length) >= 5) then $w[0:-2]
            elif ($w|endswith("s"))   and (($w|length) >= 4) then $w[0:-1]
            else $w end;
        ($ARGS.positional | map(stem)) as $q
        | .pages[] | . as $p
        | ($p.filename | ascii_downcase | gsub("[_-]+"; " ")) as $fn
        | ( [ $q[] as $t
              | (if (($p.title // "")|ascii_downcase|contains($t)) then 10 else 0 end)
              + (if ($fn|contains($t)) then 10 else 0 end)
              + (([ $p.headings[]? | select(.text|ascii_downcase|contains($t)) ] | length | if . > 3 then 3 else . end) * 3)
              + ((($p.terms[$t] // 0) | sqrt) * 2)
            ] | add ) as $score
        | select($score > 0)
        | [$p.filename, ($p.title // ""), ($score|tostring)] | @tsv
    ' "${keywords[@]}" < "$INDEX" 2>/dev/null \
        | sort -t$'\t' -k3 -rn \
        | head -20)

    if [ -n "$results" ]; then
        printf '%s\n' "$results"
        exit 0
    fi
fi

# Strategy 2: grep fallback over the cache (uniform 3-column output, empty title).
if [ -d "$CACHE_DIR" ]; then
    tmp=$(mktemp); trap 'rm -f "$tmp"' EXIT
    for kw in "${keywords[@]}"; do
        grep -rli -- "$kw" "$CACHE_DIR"/*.md 2>/dev/null || true
    done | sort | uniq -c | sort -rn | head -20 \
        | while read -r count filepath; do
            printf '%s\t\t%s\n' "$(basename "$filepath")" "$count"
        done > "$tmp"
    cat "$tmp"
    exit 0
fi

echo "No search index or cache found (expected $INDEX or $CACHE_DIR)" >&2
echo "Run: fetch-docs.sh sync" >&2
exit 1

#!/usr/bin/env bash
# fuzzy-search.sh — fuzzy filename/title matching over the v2 manifest.
# Usage: fuzzy-search.sh <query>
#
# Reads filenames + titles from paths_manifest.json (not the cache), so it works
# before any page is fetched. Output: ranked filenames (top 10), one per line.

set -uo pipefail
trap '' PIPE

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")" && pwd)"
CLONE_ROOT="$(cd "$SCRIPT_DIR/../../../.." && pwd)"
MANIFEST="${CLAUDE_DOCS_MANIFEST:-$CLONE_ROOT/paths_manifest.json}"

if [ $# -eq 0 ]; then
    echo "Usage: fuzzy-search.sh <query>" >&2
    exit 1
fi

query=$(printf '%s' "$*" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9 -]//g' | xargs)
[ -n "$query" ] || { echo "No valid query provided" >&2; exit 1; }
[ -f "$MANIFEST" ] || { echo "Manifest not found: $MANIFEST" >&2; exit 1; }
command -v jq >/dev/null 2>&1 || { echo "jq is required" >&2; exit 1; }
# Validate the manifest BEFORE the pipeline: a malformed/truncated manifest must
# fail loudly here, not surface as "no results, exit 0". (jq -e alone is not
# enough — jq 1.6 exits 0 on empty input; the type test rejects that too.)
[ "$(jq -r '.pages | type' "$MANIFEST" 2>/dev/null)" = "array" ] \
    || { echo "Manifest has no .pages array (malformed?): $MANIFEST" >&2; exit 1; }

# Single awk pass over the whole manifest. The old per-page shell loop forked
# grep up to ~10 times per page (~7,000 processes, ~17s per query); awk's
# index() gives the same fixed-substring semantics (the query is sanitized to
# [a-z0-9 -] above, so the old grep patterns had no live regex metacharacters)
# in one process. Scoring is unchanged: query in filename +100, space-normalized
# hyphen variant +90, query in title +80, per-token +15/+10 (>=6 chars scores
# 15), all-tokens bonus +50. (The old loop also scored a hyphenated variant of
# the query against the filename, but the filename haystack has every hyphen
# converted to a space, so that branch could never match — dropped, not ported.)
jq -r '.pages[] | [.filename, (.title // "")] | @tsv' "$MANIFEST" \
| awk -F'\t' -v query="$query" '
    BEGIN {
        ntok = split(query, tok, " ")
        qs = query; gsub(/-/, " ", qs)
    }
    $1 != "" {
        fname = $1
        title = tolower($2)
        base = fname; sub(/\.md$/, "", base)
        fl = tolower(base); gsub(/[_-]/, " ", fl)

        score = 0
        if (index(fl, query)) score += 100
        if (qs != query && index(fl, qs)) score += 90
        if (title != "" && index(title, query)) score += 80

        matched = 0
        for (i = 1; i <= ntok; i++) {
            t = tok[i]
            ts = t; gsub(/-/, " ", ts)
            if (index(fl, t) || index(fl, ts) || (title != "" && index(title, t))) {
                score += (length(t) >= 6 ? 15 : 10)
                matched++
            }
        }
        if (matched == ntok && ntok > 1) score += 50

        if (score > 0) printf "%d\t%s\n", score, fname
    }' \
| sort -t$'\t' -k1,1nr -k2,2 | head -10 | cut -f2
# exit 0 is deliberate: with pipefail, `head -10` closing the pipe early makes
# sort exit 2 (EPIPE under our `trap '' PIPE`) whenever there are >10 matches —
# a benign race, not a failure. Real input errors fail loudly at the manifest
# validation above, before this pipeline runs.
exit 0