Add discovery detail controls and search/scrape guidance

[developersdigest]

Integrates tool discovery and execution into the search and scrape skills, with progressive catalogue inspection and guidance for large retained results.

Search defaults to compact tool identities and descriptions. --tool-detail summary adds metadata; full includes contracts. URL Scrape keeps its summary default. Inspect selected tools with list. Requires the corresponding API deployment.

Validation: build and focused CLI tests. Production skill changes remain here; beta skill updates are separate in #266.

[cubic-dev-ai]

0 issues found across 5 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would auto-approve. Updates Firecrawl skill documentation to integrate Alexandria tool discovery into search/scrape guidance and add large-result recovery instructions via bounded remote Bash reads; docs-only change with CLI behavior unchanged and safety guidance included.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 4 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would auto-approve. This PR only changes Firecrawl agent-skill and reference docs: it integrates Alexandria discovery into search/scrape guidance and adds bounded remote-Bash recovery instructions; any remaining risk is ordinary doc correctness, not runtime behavior.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would auto-approve. Documentation-only update to Firecrawl agent skills making search/scrape the reference workflow for Alexandria tool discovery and adding remote-Bash large-result recovery guidance; runtime and CLI are unchanged, so remaining risk is doc correctness.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 12 files (changes from recent commits).

<sub>Shadow auto-approve: would not auto-approve because issues were found.
Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would not auto-approve. Auto-approval blocked by 1 unresolved issue from previous reviews.

Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would auto-approve. Adds an optional --tool-detail summary|full flag to search and scrape discovery with local validation, forwards it to the API when set, and expands skill guidance. Default behavior is unchanged, so risk is bounded to opt-in use.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 10 files (changes from recent commits).

<sub>Shadow auto-approve: would not auto-approve because issues were found.
Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 2 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would auto-approve. Adds an opt-in --tool-detail compact mode to search/scrape discovery and expands skill/reference guidance; default summary behavior is unchanged and tests cover forwarding and local validation, keeping risk limited to explicit opt-in use.

Re-trigger cubic</sub>

[cubic-dev-ai]

All reported issues were addressed across 5 files (changes from recent commits).

<sub>Shadow auto-approve: would not auto-approve because issues were found.
Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would require human review. Adds --tool-detail controls to search/scrape and changes search's default tool detail from summary to compact, changing output for all users and always sending a new API parameter; default change requires human review.

Re-trigger cubic</sub>

[cubic-dev-ai]

2 issues found across 5 files (changes from recent commits).

Confidence score: 3/5

• skills/firecrawl-agent/SKILL.md documents firecrawl scrape without the --alexandria <provider>/<tool> form, so users may try to execute catalog tools as URLs and fail — document the required Alexandria invocation.
• src/commands/alexandria.ts removes “meta tool” from the description, causing src/__tests__/alexandria-beta.test.ts:418 to fail and potentially changing the established help contract — restore the phrase or update the test intentionally.

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="skills/firecrawl-agent/SKILL.md">

<violation number="1" location="skills/firecrawl-agent/SKILL.md:14">
P2: `execute through `scrape`` omits how to actually run a discovered Alexandria tool. A plain `firecrawl scrape` treats the argument as a URL; executing a catalog tool requires `firecrawl scrape --alexandria <provider>/<capability> --options '<input JSON>'`, which is the exact invocation this CLI emits (see `firecrawl list --help` examples and `src/commands/list.ts` "Execute after filling the inputs"). For an autonomous agent this guidance is a trap: it will either try to scrape a provider ID as a URL or burn a `scrape --help` round trip. Spell the full invocation in the guidance.</violation>
</file>

<file name="src/commands/alexandria.ts">

<violation number="1" location="src/commands/alexandria.ts:197">
P2: The new description drops the phrase "meta tool", which breaks the existing help-output test `src/__tests__/alexandria-beta.test.ts:418` (`expect(findHelp.stdout).toContain('meta tool')`). `find-tools --help` output is built only from this description and its option strings (no addHelpText is attached at src/index.ts:2224), and none of the remaining strings contain "meta tool", so the assertion now fails. Either keep "meta tool" in the description or update the test assertion to match the new wording.</violation>
</file>

<sub>Shadow auto-approve: would not auto-approve because issues were found.
Tip: Review your code locally with the cubic CLI to iterate faster.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

P2: execute through scrape`` omits how to actually run a discovered Alexandria tool. A plain firecrawl scrape treats the argument as a URL; executing a catalog tool requires `firecrawl scrape --alexandria / --options ''`, which is the exact invocation this CLI emits (see `firecrawl list --help` examples and `src/commands/list.ts` "Execute after filling the inputs"). For an autonomous agent this guidance is a trap: it will either try to scrape a provider ID as a URL or burn a `scrape --help` round trip. Spell the full invocation in the guidance.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At skills/firecrawl-agent/SKILL.md, line 14:

<comment>`execute through `scrape`` omits how to actually run a discovered Alexandria tool. A plain `firecrawl scrape` treats the argument as a URL; executing a catalog tool requires `firecrawl scrape --alexandria <provider>/<capability> --options '<input JSON>'`, which is the exact invocation this CLI emits (see `firecrawl list --help` examples and `src/commands/list.ts` "Execute after filling the inputs"). For an autonomous agent this guidance is a trap: it will either try to scrape a provider ID as a URL or burn a `scrape --help` round trip. Spell the full invocation in the guidance.</comment>

<file context>
@@ -11,6 +11,8 @@ allowed-tools:
 
 AI-powered autonomous extraction. The agent navigates sites and extracts structured data (takes 2-5 minutes).
 
+Before starting autonomous extraction for structured records or listings, check `firecrawl search alexandria '<data you need>'` for a ready-made workflow or data provider. Inspect a matching contract with `firecrawl list <provider> <capability> --pretty` and execute through `scrape` if it covers the task. Continue with Agent when no suitable tool exists or the task requires autonomous navigation.
+
 ## Quick start
</file context>

Suggested change

Before starting autonomous extraction for structured records or listings, check `firecrawl search alexandria '<data you need>'` for a ready-made workflow or data provider. Inspect a matching contract with `firecrawl list <provider> <capability> --pretty` and execute through `scrape` if it covers the task. Continue with Agent when no suitable tool exists or the task requires autonomous navigation.

Before starting autonomous extraction for structured records or listings, check `firecrawl search alexandria '<data you need>'` for a ready-made workflow or data provider. Inspect a matching contract with `firecrawl list <provider> <capability> --pretty` and execute through `firecrawl scrape --alexandria <provider>/<capability> --options '<input JSON>'` if it covers the task. Continue with Agent when no suitable tool exists or the task requires autonomous navigation.

[cubic-dev-ai]

P2: The new description drops the phrase "meta tool", which breaks the existing help-output test src/__tests__/alexandria-beta.test.ts:418 (expect(findHelp.stdout).toContain('meta tool')). find-tools --help output is built only from this description and its option strings (no addHelpText is attached at src/index.ts:2224), and none of the remaining strings contain "meta tool", so the assertion now fails. Either keep "meta tool" in the description or update the test assertion to match the new wording.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At src/commands/alexandria.ts, line 197:

<comment>The new description drops the phrase "meta tool", which breaks the existing help-output test `src/__tests__/alexandria-beta.test.ts:418` (`expect(findHelp.stdout).toContain('meta tool')`). `find-tools --help` output is built only from this description and its option strings (no addHelpText is attached at src/index.ts:2224), and none of the remaining strings contain "meta tool", so the assertion now fails. Either keep "meta tool" in the description or update the test assertion to match the new wording.</comment>

<file context>
@@ -194,7 +194,7 @@ export function parseFindToolsRequest(raw: string): Call {
   return new Command('find-tools')
     .description(
-      'Discover tool sets and contracts through the firecrawl/find-tools meta tool on Scrape; never executes discovered tools'
+      'Find workflows, data APIs, and indexes for structured records and listings. Match URLs or use --options for semantic queries; discovery does not execute providers'
     )
     .argument('[urls...]', 'Known HTTP(S) URLs to find tools for')
</file context>

Suggested change

	'Find workflows, data APIs, and indexes for structured records and listings. Match URLs or use --options for semantic queries; discovery does not execute providers'
	'Find workflows, data APIs, and indexes for structured records and listings through the find-tools meta tool. Match URLs or use --options for semantic queries; discovery does not execute providers'

[cubic-dev-ai]

0 issues found across 5 files (changes from recent commits).

Confidence score: 5/5

• Automated review surfaced no issues in the provided summaries.
• No files require special attention.

<sub>Shadow auto-approve: would not auto-approve. Auto-approval blocked by 2 unresolved issues from previous reviews.

Re-trigger cubic</sub>