@toolu/opencode 6.8.0

package/plugins/ast-grep/skills/ast-grep/scripts/ast-grep.sh

@@ -0,0 +1,103 @@
+#!/usr/bin/env bash
+# ast-grep CLI wrapper — structural/AST code search
+# Bakes in --color never to prevent ANSI waste.
+# Auto-detects --lang from file extension if the caller did not pass --lang.
+set -euo pipefail
+
+# Graceful no-op if neither binary is installed.
+if ! command -v sg >/dev/null 2>&1 && ! command -v ast-grep >/dev/null 2>&1; then
+  exit 0
+fi
+
+# Prefer `sg` (shorter), fall back to `ast-grep`.
+if command -v sg >/dev/null 2>&1; then
+  AG=sg
+else
+  AG=ast-grep
+fi
+
+subcmd="${1:-}"
+shift 2>/dev/null || true
+
+usage() {
+  cat <<'USAGE'
+Usage: ast-grep.sh <subcommand> [args...]
+
+Subcommands:
+  search <pattern> [--lang <L>] [flags]  Pattern search (--color never)
+  files <pattern> [--lang <L>] [flags]   File paths only (--files-with-matches)
+  scan <yaml> [flags]                    Rule-based scan (--report-style short --max-results 50)
+  debug <pattern> [--lang <L>]           Debug pattern AST (--debug-query=pattern)
+
+--lang is required for search/files/debug, but is auto-inferred from the
+first path argument's extension if not supplied.
+
+Pass-through flags: --globs <pat>, -A/-B/-C <N>, --max-results N
+USAGE
+  exit 1
+}
+
+# Infer --lang <L> from the first path-like argument if --lang/-l not provided.
+infer_lang_args() {
+  local has_lang=0 first_path=""
+  local arg
+  for arg in "$@"; do
+    case "$arg" in
+      --lang|-l|--lang=*|-l=*) has_lang=1 ;;
+    esac
+    # First arg that exists on disk
+    if [ -z "$first_path" ] && [ -e "$arg" ]; then
+      first_path="$arg"
+    fi
+  done
+  if [ "$has_lang" -eq 0 ] && [ -n "$first_path" ] && [ -f "$first_path" ]; then
+    case "${first_path##*.}" in
+      ts)   echo "--lang typescript" ;;
+      tsx)  echo "--lang tsx" ;;
+      js|mjs|cjs) echo "--lang javascript" ;;
+      jsx)  echo "--lang jsx" ;;
+      rs)   echo "--lang rust" ;;
+      py)   echo "--lang python" ;;
+      go)   echo "--lang go" ;;
+      rb)   echo "--lang ruby" ;;
+      java) echo "--lang java" ;;
+      *)    : ;;
+    esac
+  fi
+}
+
+case "$subcmd" in
+  search)
+    pattern="${1:?search requires a pattern}"
+    shift
+    lang_args=$(infer_lang_args "$@")
+    # shellcheck disable=SC2086  # $lang_args is intentional word-split
+    exec "$AG" run --pattern "$pattern" --color never $lang_args "$@"
+    ;;
+  files)
+    pattern="${1:?files requires a pattern}"
+    shift
+    lang_args=$(infer_lang_args "$@")
+    # shellcheck disable=SC2086  # $lang_args is intentional word-split
+    exec "$AG" run --pattern "$pattern" --files-with-matches --color never $lang_args "$@"
+    ;;
+  scan)
+    rules="${1:?scan requires inline YAML or rule file path}"
+    shift
+    if [[ -f "$rules" ]]; then
+      exec "$AG" scan --rule "$rules" --report-style short --max-results 50 --color never "$@"
+    else
+      exec "$AG" scan --inline-rules "$rules" --report-style short --max-results 50 --color never "$@"
+    fi
+    ;;
+  debug)
+    pattern="${1:?debug requires a pattern}"
+    shift
+    lang_args=$(infer_lang_args "$@")
+    # shellcheck disable=SC2086  # $lang_args is intentional word-split
+    exec "$AG" run --pattern "$pattern" --debug-query=pattern --color never $lang_args "$@"
+    ;;
+  *)
+    usage
+    ;;
+esac

package/plugins/context7/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "context7",
+  "version": "6.8.0",
+  "description": "Library documentation & code-example lookup via Context7 (skill + REST wrapper). Standalone, no dependencies.",
+  "author": {
+    "name": "Falconiere Barbosa",
+    "email": "hello@falconiere.io"
+  },
+  "homepage": "https://github.com/falconiere/toolu",
+  "repository": "https://github.com/falconiere/toolu.git",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "context7",
+    "documentation",
+    "skills"
+  ]
+}

package/plugins/context7/.codex-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "context7",
+  "version": "6.8.0",
+  "description": "Library documentation & code-example lookup via Context7 (skill + REST wrapper). Standalone, no dependencies.",
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json"
+}

package/plugins/context7/README.md

@@ -0,0 +1,19 @@
+# context7
+
+Library documentation & code-example lookup via Context7 — a skill plus a REST wrapper.
+
+## Install
+
+```
+/plugin install context7@toolu
+```
+
+Standalone, no dependencies.
+
+## What it provides
+
+- **`context7` skill** — finds up-to-date documentation and code examples for any programming library or framework: `search` to resolve a library ID, then fetch its docs. Triggers when you need current docs, API references, or usage examples.
+
+## The Context7 API
+
+The skill drives `scripts/search.sh`, a bash wrapper over the Context7 REST API. **No API key required** (rate-limited). For higher limits, export `CONTEXT7_API_KEY=ctx7sk...` in the environment — the script reads it from the environment only, never from a `.env` file.

package/plugins/context7/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/context7/hooks/session-start.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# SessionStart hook — publish the context7 search wrapper at a STABLE,
+# env-independent path.
+#
+# ${CLAUDE_PLUGIN_ROOT} is exported to hook subprocesses only — NOT to the
+# Bash tool's subshell — so SKILL.md's
+#   "${CLAUDE_PLUGIN_ROOT}/skills/context7/scripts/search.sh …"
+# expands to "/skills/.../search.sh: No such file" when an agent pastes it.
+# Mirror the statusline plugin: symlink the wrapper to
+#   ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/context7/search.sh
+# which the Bash subshell CAN expand. Refreshed every session so plugin
+# updates land with no settings change. Silent on success; every step is
+# non-fatal (a failed symlink means the published copy is stale, not that
+# the session breaks).
+
+# Consume stdin so Claude Code's hook IPC never stalls.
+cat > /dev/null 2>&1 || true
+
+# Resolve the plugin dir from this hook's location: hooks/.. = plugin root.
+plugin_dir="$(cd "$(dirname "$0")/.." 2>/dev/null && pwd)"
+src="${plugin_dir:+$plugin_dir/skills/context7/scripts/search.sh}"
+[ -n "$src" ] && [ -f "$src" ] || exit 0
+
+if [ -n "${TOOLU_CONFIG_DIR:-}" ]; then
+  config_root="$TOOLU_CONFIG_DIR"
+elif [ "${TOOLU_HOST_OVERRIDE:-}" = codex ] || { [ -z "${TOOLU_HOST_OVERRIDE:-}" ] && [ -n "${PLUGIN_ROOT:-}" ]; }; then
+  config_root="${CODEX_HOME:-$HOME/.codex}"
+else
+  config_root="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+fi
+reg_root="$config_root/context7"
+mkdir -p "$reg_root" 2>/dev/null || { echo "context7: cannot create $reg_root — wrapper not published" >&2; exit 0; }
+
+# Own the path only when it is already our symlink or absent — never clobber
+# a real file a user may have placed at $reg_root/search.sh. (-L catches a
+# broken/relinked symlink that -e would report as missing.)
+dst="$reg_root/search.sh"
+if [ -L "$dst" ] || [ ! -e "$dst" ]; then
+  ln -sf "$src" "$dst" 2>/dev/null || true
+fi
+
+exit 0

package/plugins/context7/skills/context7/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: context7
+description: "ALWAYS ACTIVE — Library documentation protocol. You MUST use the context7 CLI to look up current docs, API references, and usage examples for any third-party library BEFORE answering from memory or searching the web; web search is a fallback only. Triggers on any library/framework API, usage, docs, or version question."
+---
+# Context7 — Library Documentation Lookup
+Use this skill to find up-to-date documentation and code examples for any programming library or framework.
+## CLI Tool
+
+Invoke at the **stable published path** (a symlink the plugin's SessionStart hook refreshes every session):
+
+```bash
+# Codex
+"${TOOLU_CONFIG_DIR:-${CODEX_HOME:-$HOME/.codex}}/context7/search.sh" <command> [options]
+# Claude Code
+"${TOOLU_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}/context7/search.sh" <command> [options]
+```
+
+Choose the line for the active host. Ordinary shell calls do not inherit
+plugin lifecycle variables, so never collapse these into one ambiguous
+fallback. Use the published path; plugin-root variables are lifecycle-only.
+
+Repo-checkout fallback (for tests/dev when the plugin is not installed): `plugins/context7/skills/context7/scripts/search.sh`.
+```
+search.sh <command> [options]
+Commands:
+  search  Find libraries by name (resolve library ID)
+  docs    Query documentation for a library
+```
+### Workflow
+```
+1. search.sh search <library>    → find the library ID
+2. search.sh docs <id> <query>   → query its docs
+```
+### search (default)
+```bash
+search.sh search <library> [query]
+search.sh <library>                 # bare arg works too
+Options:
+  -l, --library  Library name (required)
+  -q, --query    Context for relevance ranking
+```
+Response includes `id`, `title`, `totalSnippets`, `benchmarkScore` for each match.
+### docs
+```bash
+search.sh docs <library_id> <query>
+Options:
+  -l, --library-id  Context7 library ID, e.g. /vercel/next.js (required)
+  -q, --query       Your question (required)
+  -t, --type        json|txt (default: json; txt is plain-text, LLM-prompt-ready)
+  --fast            Skip LLM reranking — top vector hits, lower latency, lower relevance
+```
+JSON response contains `codeSnippets` and `infoSnippets`. Use `-t txt` for plain-text output with code blocks.
+Library IDs accept version pinning: `/vercel/next.js/v15.1.8` or `/vercel/next.js@v15.1.8`.
+## When to Use
+- User asks about a library's API or usage patterns
+- Need current docs (beyond training cutoff)
+- Looking for code examples with a specific library
+- Checking library version compatibility
+## Tips
+- Be specific in queries: "How to set up JWT auth in Express.js" not "auth"
+- Use `-t txt` for readable output you can paste directly
+- Pipe JSON through jq: `| jq '.codeSnippets[:3] | .[] | {codeTitle, codeLanguage}'`
+- Library IDs use `/org/repo` format — run `search` first to find them
+- No API key required (rate-limited). Export `CONTEXT7_API_KEY=ctx7sk...` in the environment for higher limits — the script reads it from the environment only, never from a `.env` file

package/plugins/context7/skills/context7/scripts/search.sh

@@ -0,0 +1,151 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Context7 CLI — search libraries and query documentation
+# Usage: ./search.sh <command> [options]
+#
+# Reads CONTEXT7_API_KEY from the environment (never from .env).
+
+command -v jq   >/dev/null 2>&1 || { echo "context7: jq required" >&2;   exit 1; }
+command -v curl >/dev/null 2>&1 || { echo "context7: curl required" >&2; exit 1; }
+
+C7_API_KEY="${CONTEXT7_API_KEY:-}"
+C7_URL="https://context7.com/api/v2"
+
+urlencode() {
+  python3 -c "import sys, urllib.parse; print(urllib.parse.quote(sys.argv[1], safe=''))" "$1"
+}
+
+c7_get() {
+  local endpoint="$1"
+  shift
+  local url="$C7_URL/$endpoint"
+
+  # Build query string from remaining args (key=value pairs)
+  local sep="?"
+  for kv in "$@"; do
+    local key="${kv%%=*}"
+    local val="${kv#*=}"
+    url="${url}${sep}${key}=$(urlencode "$val")"
+    sep="&"
+  done
+
+  local headers=(-H "Accept: application/json")
+  if [[ "${C7_API_KEY:-}" == ctx7sk* ]]; then
+    headers+=(-H "Authorization: Bearer $C7_API_KEY")
+  fi
+
+  curl -sS --fail-with-body "${headers[@]}" "$url"
+}
+
+# ── search ──────────────────────────────────────────────────
+cmd_search() {
+  local library="" query=""
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -l|--library) library="$2"; shift 2;;
+      -q|--query)   query="$2"; shift 2;;
+      *)
+        # first bare arg = library, second = query
+        if [[ -z "$library" ]]; then library="$1"; shift
+        elif [[ -z "$query" ]]; then query="$1"; shift
+        else echo "Unknown option: $1" >&2; exit 1; fi
+        ;;
+    esac
+  done
+
+  if [[ -z "$library" ]]; then
+    echo "Usage: search.sh search <library> [query]" >&2
+    echo "  Searches for libraries matching the name" >&2
+    echo "" >&2
+    echo "  -l, --library  Library name (required)" >&2
+    echo "  -q, --query    Context for ranking results" >&2
+    echo "" >&2
+    echo "Examples:" >&2
+    echo "  search.sh search react" >&2
+    echo "  search.sh search tokio \"async runtime for Rust\"" >&2
+    exit 1
+  fi
+
+  # Default query to library name if not provided
+  query="${query:-$library}"
+
+  c7_get "libs/search" "libraryName=$library" "query=$query" | jq '.'
+}
+
+# ── docs ────────────────────────────────────────────────────
+cmd_docs() {
+  local library_id="" query="" output_type="json" fast=""
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      -l|--library-id) library_id="$2"; shift 2;;
+      -q|--query)      query="$2"; shift 2;;
+      -t|--type)       output_type="$2"; shift 2;;
+      --fast)          fast="true"; shift;;
+      *)
+        # first bare arg = library_id, second = query
+        if [[ -z "$library_id" ]]; then library_id="$1"; shift
+        elif [[ -z "$query" ]]; then query="$1"; shift
+        else echo "Unknown option: $1" >&2; exit 1; fi
+        ;;
+    esac
+  done
+
+  if [[ -z "$library_id" || -z "$query" ]]; then
+    echo "Usage: search.sh docs <library_id> <query>" >&2
+    echo "  Retrieves documentation context for a library" >&2
+    echo "" >&2
+    echo "  -l, --library-id  Context7 library ID, e.g. /vercel/next.js (required)" >&2
+    echo "  -q, --query       Your question (required)" >&2
+    echo "  -t, --type        Output format: json|txt (default: json; txt is LLM-prompt-ready)" >&2
+    echo "  --fast            Skip LLM reranking, return top vector-search hits (lower latency)" >&2
+    echo "" >&2
+    echo "Examples:" >&2
+    echo "  search.sh docs /vercel/next.js \"app router file conventions\"" >&2
+    echo "  search.sh docs /tokio-rs/tokio \"spawn async tasks\" -t txt" >&2
+    echo "" >&2
+    echo "Tip: Run 'search.sh search <name>' first to find the library ID." >&2
+    exit 1
+  fi
+
+  local params=("libraryId=$library_id" "query=$query" "type=$output_type")
+  if [[ -n "$fast" ]]; then
+    params+=("fast=true")
+  fi
+
+  c7_get "context" "${params[@]}" | \
+    if [[ "$output_type" == "json" ]]; then jq '.'; else cat; fi
+}
+
+# ── main ────────────────────────────────────────────────────
+usage() {
+  echo "Context7 CLI — Library Documentation Lookup" >&2
+  echo "" >&2
+  echo "Usage: search.sh <command> [options]" >&2
+  echo "" >&2
+  echo "Environment:" >&2
+  echo "  CONTEXT7_API_KEY  Optional. If set and starts with 'ctx7sk', sent as Bearer token." >&2
+  echo "" >&2
+  echo "Commands:" >&2
+  echo "  search  Find libraries by name (resolve library ID)" >&2
+  echo "  docs    Query documentation for a library" >&2
+  echo "" >&2
+  echo "Workflow:" >&2
+  echo "  1. search.sh search <library>    # find the library ID" >&2
+  echo "  2. search.sh docs <id> <query>   # query its docs" >&2
+  echo "" >&2
+  echo "Run 'search.sh <command>' with no args for command-specific help." >&2
+  exit 1
+}
+
+case "${1:-}" in
+  -h|--help|"") usage;;
+  search)  shift; cmd_search "$@";;
+  docs)    shift; cmd_docs "$@";;
+  *)
+    # bare args — default to search
+    cmd_search "$@"
+    ;;
+esac

package/plugins/exa-search/.claude-plugin/plugin.json

@@ -0,0 +1,18 @@
+{
+  "name": "exa-search",
+  "version": "6.8.0",
+  "description": "Web, code, and URL search plus deep research via Exa (skill + REST wrapper). Standalone, no dependencies.",
+  "author": {
+    "name": "Falconiere Barbosa",
+    "email": "hello@falconiere.io"
+  },
+  "homepage": "https://github.com/falconiere/toolu",
+  "repository": "https://github.com/falconiere/toolu.git",
+  "license": "MIT",
+  "keywords": [
+    "claude-code",
+    "exa",
+    "web-search",
+    "skills"
+  ]
+}

package/plugins/exa-search/.codex-plugin/plugin.json

@@ -0,0 +1,7 @@
+{
+  "name": "exa-search",
+  "version": "6.8.0",
+  "description": "Web, code, and URL search plus deep research via Exa (skill + REST wrapper). Standalone, no dependencies.",
+  "skills": "./skills/",
+  "hooks": "./hooks/hooks.json"
+}

package/plugins/exa-search/README.md

@@ -0,0 +1,19 @@
+# exa-search
+
+Web, code, and URL search plus deep research via Exa — a skill plus a REST wrapper.
+
+## Install
+
+```
+/plugin install exa-search@toolu
+```
+
+Standalone, no dependencies.
+
+## What it provides
+
+- **`exa-search` skill** — web search, code-example search, URL crawling, and deep research from the session. Search types range from `instant` / `fast` for low-latency lookups to `deep` / `deep-reasoning` for synthesized research; `crawl` extracts content from one or more URLs.
+
+## The Exa API
+
+The skill drives `scripts/search.sh`, a bash wrapper over the Exa REST API. Set your Exa API key in the environment for the wrapper to authenticate.

package/plugins/exa-search/hooks/hooks.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/exa-search/hooks/session-start.sh

@@ -0,0 +1,34 @@
+#!/usr/bin/env bash
+# SessionStart hook — publish the exa-search wrapper at a STABLE,
+# env-independent path. See context7's session-start.sh for the same fix
+# rationale: ${CLAUDE_PLUGIN_ROOT} is exported to hook subprocesses only —
+# NOT to the agent's Bash tool subshell — so a SKILL.md path of
+# "${CLAUDE_PLUGIN_ROOT}/skills/exa-search/scripts/search.sh" expands to
+# "/skills/.../search.sh: No such file" when an agent pastes it. Mirror the
+# statusline plugin: symlink the wrapper to
+#   ${CLAUDE_CONFIG_DIR:-$HOME/.claude}/exa-search/search.sh
+# Refreshed every session; silent on success; every step non-fatal.
+
+# Consume stdin so Claude Code's hook IPC never stalls.
+cat > /dev/null 2>&1 || true
+
+plugin_dir="$(cd "$(dirname "$0")/.." 2>/dev/null && pwd)"
+src="${plugin_dir:+$plugin_dir/skills/exa-search/scripts/search.sh}"
+[ -n "$src" ] && [ -f "$src" ] || exit 0
+
+if [ -n "${TOOLU_CONFIG_DIR:-}" ]; then
+  config_root="$TOOLU_CONFIG_DIR"
+elif [ "${TOOLU_HOST_OVERRIDE:-}" = codex ] || { [ -z "${TOOLU_HOST_OVERRIDE:-}" ] && [ -n "${PLUGIN_ROOT:-}" ]; }; then
+  config_root="${CODEX_HOME:-$HOME/.codex}"
+else
+  config_root="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
+fi
+reg_root="$config_root/exa-search"
+mkdir -p "$reg_root" 2>/dev/null || { echo "exa-search: cannot create $reg_root — wrapper not published" >&2; exit 0; }
+
+dst="$reg_root/search.sh"
+if [ -L "$dst" ] || [ ! -e "$dst" ]; then
+  ln -sf "$src" "$dst" 2>/dev/null || true
+fi
+
+exit 0

package/plugins/exa-search/skills/exa-search/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: exa-search
+description: ALWAYS ACTIVE — Web search/crawl protocol. You MUST use the exa-search CLI (search / crawl / similar) instead of host-native web tools for web searches, code-example hunts, URL crawling, and topic research whenever EXA_API_KEY is set; native tools are a fallback only. Triggers when searching for external information, looking up docs/APIs, researching technologies, investigating topics, or crawling URLs.
+---
+
+# Exa Search
+
+Use this skill when you need to search the web, find code examples, crawl a URL, investigate a topic, or conduct deep research.
+
+**Trigger phrases:** search for, look up, find examples, investigate about, research about, dive into, crawl URL, what is, how does X work
+
+## CLI Tool
+
+Invoke at the **stable published path** (a symlink the plugin's SessionStart hook refreshes every session):
+
+```bash
+# Codex
+"${TOOLU_CONFIG_DIR:-${CODEX_HOME:-$HOME/.codex}}/exa-search/search.sh" <command> [options]
+# Claude Code
+"${TOOLU_CONFIG_DIR:-${CLAUDE_CONFIG_DIR:-$HOME/.claude}}/exa-search/search.sh" <command> [options]
+```
+
+Choose the line for the active host. Ordinary shell calls do not inherit
+plugin lifecycle variables, so never collapse these into one ambiguous
+fallback. Use the published path; plugin-root variables are lifecycle-only.
+
+Repo-checkout fallback (for tests/dev when the plugin is not installed): `plugins/exa-search/skills/exa-search/scripts/search.sh`.
+
+```
+search.sh <command> [options]
+
+Commands:
+  search   Search the web (default if no command given)
+  crawl    Extract content from URLs via /contents endpoint
+  similar  Find pages similar to a URL via /findSimilar endpoint
+```
+
+### search (default)
+
+```bash
+search.sh search -q "query" [options]
+search.sh "query"               # bare query works too
+
+Options:
+  -q, --query          Search query (required)
+  -n, --num-results    Number of results (default: 10, max: 100)
+  -t, --type           instant|fast|auto|deep-lite|deep|deep-reasoning (default: auto)
+  -c, --category       company|research paper|news|personal site|financial report|people
+  --include-domains    Comma-separated domains to include
+  --exclude-domains    Comma-separated domains to exclude
+  --start-date         Start published date (YYYY-MM-DD)
+  --end-date           End published date (YYYY-MM-DD)
+  --include-text       Text that must appear (single phrase, max 5 words)
+  --exclude-text       Text to exclude (single phrase, max 5 words)
+  --highlights N       Max highlight chars (default: 4000)
+  --with-text          Include full text in results
+  --lean               Strip image/favicon/subpages/entities — AI-prompt-ready output
+```
+
+### crawl
+
+```bash
+search.sh crawl <url> [url...] [-m max_chars]
+
+Options:
+  -m, --max-chars  Max characters per page (default: 3000)
+```
+
+### similar
+
+```bash
+search.sh similar <url> [-n num_results] [--highlights N]
+```
+
+## Key Constraints
+
+| Constraint | Detail |
+|---|---|
+| `--include-text` / `--exclude-text` | **Single phrase ONLY.** Multiple values cause 400 errors. |
+| `company`/`people` categories | Reject `--start-date`, `--end-date`, `--exclude-domains`. Use other categories when those filters matter. |
+| `people` category | `--include-domains` only accepts supported profile domains (LinkedIn et al). |
+| `deep-*` types | Adds synthesis latency (~seconds). Use `instant` or `fast` for low-latency lookups. |
+
+## Query Best Practices
+
+1. **Include language context** in code searches: "Go generics" not just "generics"
+2. **Use exact identifiers** when available: function names, class names, error messages
+3. **Vary query phrasings** for broader coverage: generate 2-3 variations
+4. **Use `--with-text`** when you need full page content, not just highlights
+5. **Pipe through jq** to extract specific fields: `| jq '.results[] | {title, url}'`
+6. **Use `--lean`** when feeding results back to an LLM — strips image/favicon/subpages/entities to keep token count low