feat(cli): preserve and display API agent hints

[ericciarla]

Problem and result

CLI commands currently drop optional response guidance when rebuilding API envelopes or unwrapping SDK results. Preserve agent_hints across Search, Scrape, Parse, Map, and Alexandria so an agent can see result-dependent next steps, including on empty results and failures.

• Hints are capped at two, matching the API contract after feedback guidance was removed from response hints.
• JSON retains hints and available operation/error metadata. Empty Search results still emit their JSON envelope. A keyless success:false response remains a failure even when HTTP succeeds.
• Readable/raw modes print hints to stderr, keeping page content, pipes, and content files clean. Explicit JSON takes precedence over query-answer-only output so metadata is retained.
• --no-agent-hints suppresses guidance locally, including JSON. It does not alter the server request or feedback preferences.
• The CLI neither generates hints nor executes suggested actions. Static feedback instructions are not injected into hints; the existing feedback commands remain separate.

API opt-in and rollout

The API leaves response hints disabled by default. CLI requests explicitly opt in with:

X-Firecrawl-Agent-Hints: true

This is applied to authenticated SDK requests, keyless requests, and the raw Parse transport.

Companion API/SDK PR: firecrawl/firecrawl#4641.

Search and Parse read raw response envelopes; keyless Scrape also preserves outer metadata directly. Authenticated Scrape, Map, and Alexandria depend on a published SDK containing the metadata preservation in that PR. The current pinned firecrawl@4.40.0 drops those fields. Keep this draft until that release can be pinned and validated; this PR does not invent a future version or publish packages.

Separate from skill-routing PR #226; no skills or release identity are changed here.

Validation

• Merged current main with a normal merge commit and resolved the Alexandria failure-envelope conflict while preserving both receipts/retry metadata and error hints.
• Full CLI suite: 563/563 tests passed.
• TypeScript build/typecheck, formatting, and git diff --check passed.
• New local HTTP transport tests verify the opt-in header on both authenticated SDK and keyless requests.
• No paid or production API calls.