@aria_asi/cli 0.2.40 → 0.2.41

package/skills/firecrawl-build-onboarding/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: firecrawl-build-onboarding
+description: Get Firecrawl credentials and SDK setup into a project. Use when an application needs `FIRECRAWL_API_KEY`, when an agent should add Firecrawl to `.env`, when the user wants to authenticate Firecrawl for app code, or when choosing the first SDK and docs for a new Firecrawl integration. This skill includes its own browser auth flow, so it does not depend on the website onboarding skill.
+license: ISC
+metadata:
+  author: firecrawl
+  version: "0.1.0"
+  homepage: https://www.firecrawl.dev
+  source: https://github.com/firecrawl/skills
+inputs:
+  - name: FIRECRAWL_API_KEY
+    description: Firecrawl API key used for hosted Firecrawl API requests.
+    required: true
+  - name: FIRECRAWL_API_URL
+    description: Optional base URL for self-hosted Firecrawl deployments.
+    required: false
+references:
+  - references/auth-flow.md
+  - references/sdk-installation.md
+  - references/project-setup.md
+---
+
+# Firecrawl Build Onboarding
+
+Use this skill for the application-integration path from Firecrawl's onboarding flow.
+
+## Install
+
+If you haven't installed yet, one command sets up both the CLI tools
+(for live web work) and the build skills (for app integration):
+
+```bash
+npx -y firecrawl-cli@latest init --all --browser
+```
+
+This installs the Firecrawl CLI, the CLI skills, and these build skills
+together. It also opens browser auth so the human can sign in or create
+an account. No separate `npx skills add` step is needed.
+
+## Use This When
+
+- a project needs `FIRECRAWL_API_KEY`
+- the user wants Firecrawl wired into `.env`
+- you are adding Firecrawl to an app for the first time
+- you need to choose the first SDK or REST path
+
+If the human still needs to sign up, sign in, or authorize access in the browser, use the auth flow reference in this skill.
+
+## Quick Start
+
+If the user already has an API key, place it in `.env`:
+
+```dotenv
+FIRECRAWL_API_KEY=fc-...
+```
+
+If the project is self-hosted, also set:
+
+```dotenv
+FIRECRAWL_API_URL=https://your-firecrawl-instance.example.com
+```
+
+Then decide which integration path applies:
+
+- **Fresh project** -> choose the target stack, install the SDK, add the first Firecrawl call, and run a smoke test
+- **Existing project** -> inspect the repo first, then integrate Firecrawl where the project already handles third-party APIs and env vars
+
+## What Do You Need?
+
+| Task | Reference |
+|---|---|
+| **Run the browser auth flow and save `FIRECRAWL_API_KEY`** | [references/auth-flow.md](references/auth-flow.md) |
+| **Install the right SDK** | [references/sdk-installation.md](references/sdk-installation.md) |
+| **Put credentials into `.env` or project config** | [references/project-setup.md](references/project-setup.md) |
+| **Choose the right endpoint after setup** | [firecrawl-build](../firecrawl-build/SKILL.md) |
+| **Need live web tooling during this task** | The CLI skills are already installed from the same command |
+| **Start implementation from a known URL** | [firecrawl-build-scrape](../firecrawl-build-scrape/SKILL.md) |
+| **Start implementation from a query** | [firecrawl-build-search](../firecrawl-build-search/SKILL.md) |
+
+## Docs (Source of Truth)
+
+Read the source-of-truth page for your project language for SDK usage, schemas, and examples:
+
+- **Node / TypeScript**: [docs.firecrawl.dev/agent-source-of-truth/node](https://docs.firecrawl.dev/agent-source-of-truth/node)
+- **Python**: [docs.firecrawl.dev/agent-source-of-truth/python](https://docs.firecrawl.dev/agent-source-of-truth/python)
+- **Rust**: [docs.firecrawl.dev/agent-source-of-truth/rust](https://docs.firecrawl.dev/agent-source-of-truth/rust)
+- **Java**: [docs.firecrawl.dev/agent-source-of-truth/java](https://docs.firecrawl.dev/agent-source-of-truth/java)
+- **Elixir**: [docs.firecrawl.dev/agent-source-of-truth/elixir](https://docs.firecrawl.dev/agent-source-of-truth/elixir)
+- **cURL / REST**: [docs.firecrawl.dev/agent-source-of-truth/curl](https://docs.firecrawl.dev/agent-source-of-truth/curl)
+
+## After Setup
+
+Once the key is present:
+
+1. decide whether this is a fresh project or an existing codebase
+2. ask what Firecrawl should do in the product
+3. pick the narrowest endpoint that matches that behavior
+4. read the source-of-truth page for the project language before writing code
+5. add the SDK or REST call in code
+6. run a smoke test that proves one real Firecrawl request succeeds
+7. use the endpoint-specific skills in this repo for implementation guidance
+8. if you also need live web tooling during the current task, the CLI skills are already installed — use `firecrawl/cli`
+## Trigger
+
+Use when the owner asks for this skill's described Firecrawl capability, when the current task needs web discovery/extraction/interaction beyond local files, or when a URL/query/data-extraction flow would otherwise be guessed from memory. Do not use for local repo edits unless the product code is explicitly integrating Firecrawl.
+
+## Workflow
+
+1. Classify the request as search, scrape, crawl, map, download, interact, clone, or product integration before taking action.
+2. Preserve the owner goal and scope: target URL/query, depth, output format, auth/profile needs, and what must not be touched.
+3. Use the real Firecrawl runtime/CLI/API path for the selected capability; do not fabricate page content, screenshots, links, or structured fields.
+4. Validate the result against the requested shape: markdown/content quality, URL coverage, schema fields, pagination/auth interaction, local files, or product integration behavior.
+5. If the result is incomplete, emit a redo contract: missing data, next Firecrawl action, re-test command/probe, and architect/ARIA console escalation if the same failure repeats.
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.

package/skills/firecrawl-build-onboarding/references/auth-flow.md

@@ -0,0 +1,39 @@
+# Auth Flow
+
+Use this browser flow when the user does not already have a Firecrawl API key.
+
+## Step 1: Generate auth parameters
+
+```bash
+SESSION_ID=$(openssl rand -hex 32)
+CODE_VERIFIER=$(openssl rand -base64 32 | tr '+/' '-_' | tr -d '=\n' | head -c 43)
+CODE_CHALLENGE=$(printf '%s' "$CODE_VERIFIER" | openssl dgst -sha256 -binary | openssl base64 -A | tr '+/' '-_' | tr -d '=')
+```
+
+## Step 2: Ask the user to open this URL
+
+```text
+https://www.firecrawl.dev/cli-auth?code_challenge=$CODE_CHALLENGE&source=coding-agent#session_id=$SESSION_ID
+```
+
+The user completes the browser authorization flow. If successful, the API key becomes available through the polling endpoint.
+
+## Step 3: Poll for completion
+
+```http
+POST https://www.firecrawl.dev/api/auth/cli/status
+Content-Type: application/json
+
+{"session_id":"$SESSION_ID","code_verifier":"$CODE_VERIFIER"}
+```
+
+Responses:
+
+- `{"status":"pending"}` - continue polling
+- `{"status":"complete","apiKey":"fc-...","teamName":"..."}`
+
+## Step 4: Save the key
+
+```bash
+echo "FIRECRAWL_API_KEY=fc-..." >> .env
+```

package/skills/firecrawl-build-onboarding/references/project-setup.md

@@ -0,0 +1,20 @@
+# Project Setup
+
+For hosted Firecrawl, add this to `.env`:
+
+```dotenv
+FIRECRAWL_API_KEY=fc-...
+```
+
+For self-hosted Firecrawl, add:
+
+```dotenv
+FIRECRAWL_API_KEY=fc-...
+FIRECRAWL_API_URL=https://your-firecrawl-instance.example.com
+```
+
+Project setup guidance:
+
+- Keep the key in environment variables or the platform secret manager.
+- Do not hardcode credentials in source files.
+- If the app has separate environments, mirror the key setup across development, preview, and production as needed.

package/skills/firecrawl-build-onboarding/references/sdk-installation.md

@@ -0,0 +1,17 @@
+# SDK Installation
+
+Install the SDK that matches the project stack after `FIRECRAWL_API_KEY` is available.
+
+## JavaScript / TypeScript
+
+```bash
+npm install @mendable/firecrawl-js
+```
+
+## Python
+
+```bash
+pip install firecrawl-py
+```
+
+If the project already has a preferred HTTP client abstraction, direct REST calls are also fine.

package/skills/firecrawl-build-scrape/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: firecrawl-build-scrape
+description: Integrate Firecrawl `/scrape` into product code for single-page extraction. Use when an app already has a URL and needs markdown, HTML, links, screenshots, metadata, or structured page output. Prefer this skill over broader crawl patterns when the feature is page-level.
+license: ISC
+metadata:
+  author: firecrawl
+  version: "0.1.0"
+  homepage: https://www.firecrawl.dev
+  source: https://github.com/firecrawl/skills
+inputs:
+  - name: FIRECRAWL_API_KEY
+    description: Firecrawl API key for hosted Firecrawl requests.
+    required: true
+  - name: FIRECRAWL_API_URL
+    description: Optional base URL for self-hosted Firecrawl deployments.
+    required: false
+---
+
+# Firecrawl Build Scrape
+
+Use this when the application already has the URL and needs content from one page.
+
+## Use This When
+
+- the feature starts from a known URL
+- you need page content for retrieval, summarization, enrichment, or monitoring
+- you want the default extraction primitive before considering `/interact`
+
+## Default Recommendations
+
+- Return `markdown` unless the feature truly needs another format.
+- Use `onlyMainContent` for article-like pages where nav and chrome add noise.
+- Add waits or other rendering options only when the page needs them.
+
+## Common Product Patterns
+
+- knowledge ingestion from known URLs
+- enrichment from a company, product, or docs page
+- pricing, changelog, and documentation extraction
+- page-level quality checks or monitoring
+
+## Escalation Rules
+
+- If you do not have the URL yet, start with [firecrawl-build-search](../firecrawl-build-search/SKILL.md).
+- If content requires clicks, typing, or multi-step navigation, escalate to [firecrawl-build-interact](../firecrawl-build-interact/SKILL.md).
+
+## Implementation Notes
+
+- Keep the integration narrow: one feature, one URL, one extraction contract.
+- Treat `/scrape` as the default primitive for downstream LLM or indexing pipelines.
+- Request richer formats only when the consumer needs them, such as links, screenshots, or branding data.
+
+## Docs (Source of Truth)
+
+Read the source-of-truth page for your project language before writing integration code:
+
+- **Node / TypeScript**: [docs.firecrawl.dev/agent-source-of-truth/node](https://docs.firecrawl.dev/agent-source-of-truth/node)
+- **Python**: [docs.firecrawl.dev/agent-source-of-truth/python](https://docs.firecrawl.dev/agent-source-of-truth/python)
+- **Rust**: [docs.firecrawl.dev/agent-source-of-truth/rust](https://docs.firecrawl.dev/agent-source-of-truth/rust)
+- **Java**: [docs.firecrawl.dev/agent-source-of-truth/java](https://docs.firecrawl.dev/agent-source-of-truth/java)
+- **Elixir**: [docs.firecrawl.dev/agent-source-of-truth/elixir](https://docs.firecrawl.dev/agent-source-of-truth/elixir)
+- **cURL / REST**: [docs.firecrawl.dev/agent-source-of-truth/curl](https://docs.firecrawl.dev/agent-source-of-truth/curl)
+
+## See Also
+
+- [firecrawl-build](../firecrawl-build/SKILL.md)
+- [firecrawl-build-search](../firecrawl-build-search/SKILL.md)
+- [firecrawl-build-interact](../firecrawl-build-interact/SKILL.md)
+## Trigger
+
+Use when the owner asks for this skill's described Firecrawl capability, when the current task needs web discovery/extraction/interaction beyond local files, or when a URL/query/data-extraction flow would otherwise be guessed from memory. Do not use for local repo edits unless the product code is explicitly integrating Firecrawl.
+
+## Workflow
+
+1. Classify the request as search, scrape, crawl, map, download, interact, clone, or product integration before taking action.
+2. Preserve the owner goal and scope: target URL/query, depth, output format, auth/profile needs, and what must not be touched.
+3. Use the real Firecrawl runtime/CLI/API path for the selected capability; do not fabricate page content, screenshots, links, or structured fields.
+4. Validate the result against the requested shape: markdown/content quality, URL coverage, schema fields, pagination/auth interaction, local files, or product integration behavior.
+5. If the result is incomplete, emit a redo contract: missing data, next Firecrawl action, re-test command/probe, and architect/ARIA console escalation if the same failure repeats.
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.

package/skills/firecrawl-build-search/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: firecrawl-build-search
+description: Integrate Firecrawl `/search` into product code and agent workflows. Use when an app needs discovery before extraction, when the feature starts with a query instead of a URL, or when the system should search the web and optionally hydrate result content.
+license: ISC
+metadata:
+  author: firecrawl
+  version: "0.1.0"
+  homepage: https://www.firecrawl.dev
+  source: https://github.com/firecrawl/skills
+inputs:
+  - name: FIRECRAWL_API_KEY
+    description: Firecrawl API key for hosted Firecrawl requests.
+    required: true
+  - name: FIRECRAWL_API_URL
+    description: Optional base URL for self-hosted Firecrawl deployments.
+    required: false
+---
+
+# Firecrawl Build Search
+
+Use this when the application starts with a query, not a URL.
+
+## Use This When
+
+- the user asks a question and the product must discover sources first
+- the feature needs current web results
+- you want to turn a search query into a shortlist of pages for later scraping
+
+## Default Recommendations
+
+- Use `/search` first when URL discovery is part of the product behavior.
+- Keep search and extraction conceptually separate unless scraping search results is clearly required.
+- Prefer selective follow-up extraction over broad hydration when cost or latency matters.
+
+## Common Product Patterns
+
+- answer generation with cited sources
+- company, competitor, or topic discovery
+- research workflows that produce a shortlist before deeper extraction
+- query-to-URL pipelines for later `/scrape` or `/interact`
+
+## Escalation Rules
+
+- If you already have the URL, use [firecrawl-build-scrape](../firecrawl-build-scrape/SKILL.md).
+- If the result page then requires clicks or form interaction, escalate to [firecrawl-build-interact](../firecrawl-build-interact/SKILL.md).
+
+## Implementation Notes
+
+- Treat `/search` as discovery, ranking, and source selection.
+- Be explicit about whether the product needs snippets, URLs, or full result content.
+- Keep the query contract stable so downstream scraping logic stays predictable.
+
+## Docs (Source of Truth)
+
+Read the source-of-truth page for your project language before writing integration code:
+
+- **Node / TypeScript**: [docs.firecrawl.dev/agent-source-of-truth/node](https://docs.firecrawl.dev/agent-source-of-truth/node)
+- **Python**: [docs.firecrawl.dev/agent-source-of-truth/python](https://docs.firecrawl.dev/agent-source-of-truth/python)
+- **Rust**: [docs.firecrawl.dev/agent-source-of-truth/rust](https://docs.firecrawl.dev/agent-source-of-truth/rust)
+- **Java**: [docs.firecrawl.dev/agent-source-of-truth/java](https://docs.firecrawl.dev/agent-source-of-truth/java)
+- **Elixir**: [docs.firecrawl.dev/agent-source-of-truth/elixir](https://docs.firecrawl.dev/agent-source-of-truth/elixir)
+- **cURL / REST**: [docs.firecrawl.dev/agent-source-of-truth/curl](https://docs.firecrawl.dev/agent-source-of-truth/curl)
+
+## See Also
+
+- [firecrawl-build](../firecrawl-build/SKILL.md)
+- [firecrawl-build-scrape](../firecrawl-build-scrape/SKILL.md)
+- [firecrawl-build-interact](../firecrawl-build-interact/SKILL.md)
+## Trigger
+
+Use when the owner asks for this skill's described Firecrawl capability, when the current task needs web discovery/extraction/interaction beyond local files, or when a URL/query/data-extraction flow would otherwise be guessed from memory. Do not use for local repo edits unless the product code is explicitly integrating Firecrawl.
+
+## Workflow
+
+1. Classify the request as search, scrape, crawl, map, download, interact, clone, or product integration before taking action.
+2. Preserve the owner goal and scope: target URL/query, depth, output format, auth/profile needs, and what must not be touched.
+3. Use the real Firecrawl runtime/CLI/API path for the selected capability; do not fabricate page content, screenshots, links, or structured fields.
+4. Validate the result against the requested shape: markdown/content quality, URL coverage, schema fields, pagination/auth interaction, local files, or product integration behavior.
+5. If the result is incomplete, emit a redo contract: missing data, next Firecrawl action, re-test command/probe, and architect/ARIA console escalation if the same failure repeats.
+
+## First-Class Production Contract
+
+This skill must deepen the work, not decorate it. When loaded, apply it as a production requirement:
+
+- no placeholders, no fake fallbacks, no vague future wiring, and no cosmetic compliance
+- real proof from the repo, runtime, tests, logs, endpoint, or owner instruction before any completion claim
+- a redo contract whenever the skill blocks or finds a gap: what failed, what to change, how to re-test, and when to re-submit
+- architect/ARIA console escalation when the same failure repeats twice, crosses system boundaries, or cannot be verified locally
+- owner-visible output that states the exact state of the work: changed, verified, blocked, or needing a decision
+## Self-Executing Recovery Contract
+
+When this skill blocks, fails verification, or finds a gap, the agent must execute recovery rather than hand work back as a user-only decision.
+
+- Make exactly one self-executed recovery attempt using the strongest safe local, repository, runtime, test, log, endpoint, or owner-provided evidence available.
+- If the same failure repeats after that one recovery attempt, switch to architect execution mode: operate under the architect/ARIA harness to diagnose, choose the next action, execute the repair path, and verify the result.
+- If Aria or the architect service is unavailable, fall back to the strongest available client LLM under the architect harness or strongest available local harness substrate; mark the fallback explicitly and continue recovery instead of stopping.
+- Do not end with user-handoff-only behavior. If blocked after the recovery path, report the executed recovery attempt, evidence, remaining blocker, and the next concrete action or owner decision needed; do not merely ask the user to take over.