Consolidate Alexandria discovery and execution in one skill

beta-skills/firecrawl-alexandria/SKILL.md

@@ -11,15 +11,75 @@ Use `FIRECRAWL_API_KEY` or existing Firecrawl login credentials. Never print cre
 
 ## Discover Before Executing
 
+Default to search with domain-tool discovery enabled. In this beta, plain `search` sends both `web` and `alexandria` sources with `domainTools: true`. Use `--domain-tools` explicitly in agent examples so this remains clear, including when selecting only web results.
+
+### Semantic search with domain discovery
+
+Start with a capability query and keep domain-tool discovery enabled. Default search combines semantic Alexandria tool matches with web results and tools for those result domains:
+
 ```sh
-npx firecrawl-cli@alexandria search "GDP" --json
-npx firecrawl-cli@alexandria find-tools --options '{"providers":["fred"]}' --pretty
-npx firecrawl-cli@alexandria find-tools https://example.com --pretty
+npx firecrawl-cli@alexandria search "Search homes for sale and retrieve property price history" --domain-tools --json
 ```
 
-Search defaults to web results plus Alexandria tools and domain-tool discovery. Inspect both; discovery does not execute the returned provider tools. Use `--sources web` for web-only search or `--sources alexandria` for tool-only discovery. Search itself can consume credits. For URL scraping with related tool discovery, use `scrape https://example.com --domain-tools --json` after the same beta prefix.
+If the user names a website, include that context in the same discovery workflow and look up its URL directly when you need its tool contracts:
+
+```sh
+npx firecrawl-cli@alexandria search "Zillow homes for sale and property price history" --domain-tools --json
+npx firecrawl-cli@alexandria find-tools https://www.zillow.com --pretty
+```
+
+The domain in the query provides context; it is not a strict provider filter. `--domain-tools` discovers tools for domains in the web results. Use `find-tools` with the known URL to inspect that domain even if it does not appear in those results. Inspect the returned matches before making another discovery call; skip the URL lookup when search already returned the needed contract.
+
+Describe the data capability in the discovery query; keep exact street addresses, record IDs, and other execution arguments for the selected tool. For example, discover "residential property prices near an address", then resolve the user's address using the returned lookup contract. Do not claim rental support if the contract only supports for-sale listings.
+
+When only semantic tool matches are needed, narrow the same search to the Alexandria source:
+
+```sh
+npx firecrawl-cli@alexandria search "Search homes for sale and retrieve property price history" --sources alexandria --json
+```
+
+If selecting only web results, use `--sources web --domain-tools` to retain domain discovery; `--sources web` alone opts out. `find-tools` accepts URLs and catalogue selectors, not a natural-language search phrase. Both semantic and domain discovery return tool information without executing provider tools. Read the returned providers and capabilities rather than guessing a provider from a keyword.
+
+### Progressive catalogue discovery
+
+When the provider is unknown or a result exposes more groups/tools, narrow the catalogue progressively instead of loading every contract:
+
+```sh
+npx firecrawl-cli@alexandria find-tools --options '{"level":"providers"}' --json
+```
+
+Inspect the compact results and follow the relevant returned `next` request with `find-tools --request '<returned request JSON>'`. Pass the complete request object unchanged, including its provider, capability, and options. Continue through the relevant provider, group, and tool results; use returned pagination requests when needed. Do not combine `--request` with URL or filter arguments.
+
+Once a capability fits the task, request only its contract with `--options`, including the returned provider/capability IDs, `"level":"tools"`, and `"expand":["options","response"]`. Add `"examples"` only if the schema needs clarification. Progressive discovery is catalogue navigation, not semantic search or provider execution; use `search --sources alexandria` when starting from a natural-language capability.
+
+### Optional tool discovery alongside a scrape
+
+```sh
+npx firecrawl-cli@alexandria scrape https://www.zillow.com --domain-tools --json
+```
+
+Enable `--domain-tools` when a URL scrape should also return related tool contracts and the team has access. If the API refuses the feature, report the access requirement; do not repeatedly retry. A normal URL scrape does not enable this automatically. Inspect the complete JSON for both scraped content and tool metadata; discovering a tool does not execute it. Search and URL scraping can consume credits.
+
+Read returned tool contracts and any tool metadata before choosing a provider/capability; search and URL-scrape responses expose these as `data.tools`, while `find-tools` responses are under `data.alexandria`. Use their exact input schema, pricing and access requirements; never invent options or assume a provider is free. Follow returned Find Tools requests with `find-tools --request '<returned request JSON>'`. This accepts only the `firecrawl/find-tools` discovery call, not arbitrary provider execution.
+
+## Search → Inspect → Scrape
+
+Use semantic search with domain discovery as the shared entry point, incorporating any known website as described above. Continue with progressive discovery when the returned catalogue needs narrowing, then inspect and execute the selected tool.
+
+1. Search once and inspect the returned tool identities and descriptions. A related topic alone does not mean the tool can answer the question.
+2. Fetch only the selected provider's or capability's contract with `find-tools`. Omit `expand` for compact results; request `"expand":["options","response"]` only for the selected capability. Load examples only when needed.
+3. Check coverage, required inputs, credits, and terms. Use the provider's lookup tool to obtain IDs; never invent an ASIN, zpid, store ID, or opportunity ID.
+4. Execute the chosen tool through `scrape --alexandria`, using the exact capability and options returned by discovery. Check per-call errors and receipts before describing the result as successful.
+5. If no tool covers the task, stop catalogue execution and use ordinary web search or URL scraping. Do not make a paid call merely to see whether an unrelated tool might work.
+
+For example, after discovery confirms Zillow's address lookup contract:
+
+```sh
+npx firecrawl-cli@alexandria find-tools --options '{"providers":["zillow"],"capabilities":["properties/locations"],"level":"tools","expand":["options","response"]}' --json
+npx firecrawl-cli@alexandria scrape --alexandria zillow/properties/locations --options '{"query":"800 Haight Street San Francisco","count":3}' --json
+```
 
-Read the returned `data.tools` contracts before choosing a provider/capability. Use their exact input schema, pricing and access requirements; never invent options or assume a provider is free. Follow returned Find Tools requests with `find-tools --request '<returned request JSON>'`. This accepts only the `firecrawl/find-tools` discovery call, not arbitrary provider execution.
+This resolves an address; it does not itself return nearby rental prices. Continue only with supported capabilities and identifiers actually returned by the tool. If a prerequisite lookup is unavailable, explain the missing input instead of guessing it.
 
 ## Execute Within The User's Budget
 
@@ -28,10 +88,10 @@ Obtain approval before paid execution unless the user has already authorized the
 Once the discovered contract confirms the capability and options:
 
 ```sh
-npx firecrawl-cli@alexandria scrape --alexandria fred/series/observations --options '{"series_id":"GDP"}' --request-id gdp-beta-1 --json
+npx firecrawl-cli@alexandria scrape --alexandria fred/series/observations --options '{"series_id":"GDP"}' --json
 ```
 
-Choose a new unique request ID for each new logical execution; the ID above is only an example. Preserve the ID printed on stderr and reuse it only for identical retries, including options and call order. For batches, repeat `--alexandria` and pair each call with a positional `--options` object (maximum 10 calls).
+The CLI generates request IDs automatically. Preserve the ID printed on stderr and reuse it only for identical retries, including options and call order. For batches, repeat `--alexandria` and pair each call with a positional `--options` object (maximum 10 calls).
 
 Inspect the full response, including `data.alexandria`, per-call errors and any credit/charge receipt. A successful HTTP response does not guarantee every call succeeded. Preserve receipts and request IDs in the result summary.
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "firecrawl-cli",
-  "version": "1.23.4-alexandria-beta.2",
+  "version": "1.23.4-alexandria-beta.4",
   "publishConfig": {
     "tag": "alexandria"
   },