fix(agent): validate Alexandria flags locally and fix the exchange docs

[mogery]

Follow-up to #305, which merged while its review findings were still open. This PR addresses all five.

What changed

• Local checks. These cases now exit 1 with an Error: message before any request, the same way the existing approval checks work:
  • --max-calls that is not a whole number from 1 to 30. Before, parseInt('12o') produced NaN, which JSON turned into maxCalls: null.
  • --toolkits with more than 5 slugs.
  • --call-ids or --always without --approve. Before, the CLI dropped them silently, for example when they were passed with --decline.
• Terms approvals. The human-readable output now lists each provider as Name (slug): url. It also says terms can be accepted with firecrawl alexandria terms accept <provider> or in the dashboard, where it previously named only the dashboard.
• README. The agent options table now has the --thread and --mode rows that the Alexandria examples rely on.
• skills/firecrawl-agent/SKILL.md. The approval follow-up now includes the required prompt (firecrawl agent "<follow-up prompt>" --thread ...). The terms sentence now describes both ways to accept terms, and the CLI route still requires the user's explicit agreement.

Tests

The new checks are added to src/__tests__/alexandria-beta.test.ts:

• --max-calls with 12o, 0, 31 and 2.5.
• --toolkits with 6 slugs.
• --decline together with --call-ids.
• The updated terms approval output.

Each rejected case asserts that no request was made. Local runs: format:check, type-check and build pass, and pnpm test passes 683/683.

Release

This bumps package.json to 1.26.3. #305 cut 1.26.2, so merging this publishes firecrawl-cli@1.26.3 and the v1.26.3 binaries.

---

Summary by cubic

Follow-up to #305, fixing all five review findings from that merge.

• Rejects invalid Alexandria flags locally before any request: --max-calls values that aren't whole numbers from 1 to 30, --toolkits with more than 5 slugs, and --call-ids (including empty) or --always without --approve. These previously reached the API or were silently dropped, and now exit 1 with an Error: message.
• Terms approval output lists each provider as Name: url beside a firecrawl alexandria terms show <provider> command, and points to accepting in the dashboard or via firecrawl alexandria terms accept <provider> --terms-version <version> --digest <digest> --confirm.
• Adds the missing --thread and --mode rows to the README agent options table.
• Updates skills/firecrawl-agent/SKILL.md to include the follow-up prompt in the approval command and describe both ways to accept terms.
• Bumps package.json to 1.26.3.

^{Written for commit 448aa83. Summary will update on new commits.}

[cubic-dev-ai]

2 issues found across 6 files

<sub>Shadow auto-approve: would not auto-approve because issues were found.

Fix all with cubic | Turn on auto-fix | Re-trigger cubic</sub>

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/index.ts">

<violation number="1" location="src/index.ts:1769">
P2: Check whether `--call-ids` was supplied rather than whether its value is truthy; `--call-ids=` can bypass this guard and let the request proceed. Use `options.callIds !== undefined` in the condition.</violation>
</file>

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

<violation number="1" location="src/commands/agent.ts:526">
P3: This advice is not actionable as printed: `firecrawl alexandria terms accept <provider>` fails unless `--terms-version`, `--digest` (64 lowercase hex), and `--confirm` are supplied. `requestTerms` in src/commands/terms.ts throws "Review the terms, then supply --terms-version, --digest (64 lowercase hex characters), and --confirm." when `accept` is true and any of those is missing. The pending-approval gates already carry the version/digest values, so either print the full command with the gate's values or point users to `firecrawl alexandria terms show <provider>` first (the flow SKILL.md and the guidance in src/commands/alexandria.ts line 245 both require showing terms and getting explicit user consent before accepting).</violation>
</file>

[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. Fixes invalid Alexandria flag handling with local pre-request validation and clarifies terms/approval docs; focused bug fix backed by tests, with no rollout, contract, or config changes.

Turn on auto-fix | Re-trigger cubic</sub>