@quantumclaw/quantumclaw 2026.3.22

package/docs/tools/firecrawl.md

@@ -0,0 +1,140 @@
+---
+summary: "Firecrawl search, scrape, and web_fetch fallback"
+read_when:
+  - You want Firecrawl-backed web extraction
+  - You need a Firecrawl API key
+  - You want Firecrawl as a web_search provider
+  - You want anti-bot extraction for web_fetch
+title: "Firecrawl"
+---
+
+# Firecrawl
+
+QuantumClaw can use **Firecrawl** in three ways:
+
+- as the `web_search` provider
+- as explicit plugin tools: `firecrawl_search` and `firecrawl_scrape`
+- as a fallback extractor for `web_fetch`
+
+It is a hosted extraction/search service that supports bot circumvention and caching,
+which helps with JS-heavy sites or pages that block plain HTTP fetches.
+
+## Get an API key
+
+1. Create a Firecrawl account and generate an API key.
+2. Store it in config or set `FIRECRAWL_API_KEY` in the gateway environment.
+
+## Configure Firecrawl search
+
+```json5
+{
+  tools: {
+    web: {
+      search: {
+        provider: "firecrawl",
+      },
+    },
+  },
+  plugins: {
+    entries: {
+      firecrawl: {
+        enabled: true,
+        config: {
+          webSearch: {
+            apiKey: "FIRECRAWL_API_KEY_HERE",
+            baseUrl: "https://api.firecrawl.dev",
+          },
+        },
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- Choosing Firecrawl in onboarding or `quantumclaw configure --section web` enables the bundled Firecrawl plugin automatically.
+- `web_search` with Firecrawl supports `query` and `count`.
+- For Firecrawl-specific controls like `sources`, `categories`, or result scraping, use `firecrawl_search`.
+
+## Configure Firecrawl scrape + web_fetch fallback
+
+```json5
+{
+  plugins: {
+    entries: {
+      firecrawl: {
+        enabled: true,
+      },
+    },
+  },
+  tools: {
+    web: {
+      fetch: {
+        firecrawl: {
+          apiKey: "FIRECRAWL_API_KEY_HERE",
+          baseUrl: "https://api.firecrawl.dev",
+          onlyMainContent: true,
+          maxAgeMs: 172800000,
+          timeoutSeconds: 60,
+        },
+      },
+    },
+  },
+}
+```
+
+Notes:
+
+- `firecrawl.enabled` defaults to `true` unless explicitly set to `false`.
+- Firecrawl fallback attempts run only when an API key is available (`tools.web.fetch.firecrawl.apiKey` or `FIRECRAWL_API_KEY`).
+- `maxAgeMs` controls how old cached results can be (ms). Default is 2 days.
+
+`firecrawl_scrape` reuses the same `tools.web.fetch.firecrawl.*` settings and env vars.
+
+## Firecrawl plugin tools
+
+### `firecrawl_search`
+
+Use this when you want Firecrawl-specific search controls instead of generic `web_search`.
+
+Core parameters:
+
+- `query`
+- `count`
+- `sources`
+- `categories`
+- `scrapeResults`
+- `timeoutSeconds`
+
+### `firecrawl_scrape`
+
+Use this for JS-heavy or bot-protected pages where plain `web_fetch` is weak.
+
+Core parameters:
+
+- `url`
+- `extractMode`
+- `maxChars`
+- `onlyMainContent`
+- `maxAgeMs`
+- `proxy`
+- `storeInCache`
+- `timeoutSeconds`
+
+## Stealth / bot circumvention
+
+Firecrawl exposes a **proxy mode** parameter for bot circumvention (`basic`, `stealth`, or `auto`).
+QuantumClaw always uses `proxy: "auto"` plus `storeInCache: true` for Firecrawl requests.
+If proxy is omitted, Firecrawl defaults to `auto`. `auto` retries with stealth proxies if a basic attempt fails, which may use more credits
+than basic-only scraping.
+
+## How `web_fetch` uses Firecrawl
+
+`web_fetch` extraction order:
+
+1. Readability (local)
+2. Firecrawl (if configured)
+3. Basic HTML cleanup (last fallback)
+
+See [Web tools](/tools/web) for the full web tool setup.

package/docs/tools/index.md

@@ -0,0 +1,137 @@
+---
+summary: "QuantumClaw tools and plugins overview: what the agent can do and how to extend it"
+read_when:
+  - You want to understand what tools QuantumClaw provides
+  - You need to configure, allow, or deny tools
+  - You are deciding between built-in tools, skills, and plugins
+title: "Tools and Plugins"
+---
+
+# Tools and Plugins
+
+Everything the agent does beyond generating text happens through **tools**.
+Tools are how the agent reads files, runs commands, browses the web, sends
+messages, and interacts with devices.
+
+## Tools, skills, and plugins
+
+QuantumClaw has three layers that work together:
+
+<Steps>
+  <Step title="Tools are what the agent calls">
+    A tool is a typed function the agent can invoke (e.g. `exec`, `browser`,
+    `web_search`, `message`). QuantumClaw ships a set of **built-in tools** and
+    plugins can register additional ones.
+
+    The agent sees tools as structured function definitions sent to the model API.
+
+  </Step>
+
+  <Step title="Skills teach the agent when and how">
+    A skill is a markdown file (`SKILL.md`) injected into the system prompt.
+    Skills give the agent context, constraints, and step-by-step guidance for
+    using tools effectively. Skills live in your workspace, in shared folders,
+    or ship inside plugins.
+
+    [Skills reference](/tools/skills) | [Creating skills](/tools/creating-skills)
+
+  </Step>
+
+  <Step title="Plugins package everything together">
+    A plugin is a package that can register any combination of capabilities:
+    channels, model providers, tools, skills, speech, image generation, and more.
+    Some plugins are **core** (shipped with QuantumClaw), others are **external**
+    (published on npm by the community).
+
+    [Install and configure plugins](/tools/plugin) | [Build your own](/plugins/building-plugins)
+
+  </Step>
+</Steps>
+
+## Built-in tools
+
+These tools ship with QuantumClaw and are available without installing any plugins:
+
+| Tool                         | What it does                                             | Page                              |
+| ---------------------------- | -------------------------------------------------------- | --------------------------------- |
+| `exec` / `process`           | Run shell commands, manage background processes          | [Exec](/tools/exec)               |
+| `browser`                    | Control a Chromium browser (navigate, click, screenshot) | [Browser](/tools/browser)         |
+| `web_search` / `web_fetch`   | Search the web, fetch page content                       | [Web](/tools/web)                 |
+| `read` / `write` / `edit`    | File I/O in the workspace                                |                                   |
+| `apply_patch`                | Multi-hunk file patches                                  | [Apply Patch](/tools/apply-patch) |
+| `message`                    | Send messages across all channels                        | [Agent Send](/tools/agent-send)   |
+| `canvas`                     | Drive node Canvas (present, eval, snapshot)              |                                   |
+| `nodes`                      | Discover and target paired devices                       |                                   |
+| `cron` / `gateway`           | Manage scheduled jobs, restart gateway                   |                                   |
+| `image` / `image_generate`   | Analyze or generate images                               |                                   |
+| `sessions_*` / `agents_list` | Session management, sub-agents                           | [Sub-agents](/tools/subagents)    |
+
+### Plugin-provided tools
+
+Plugins can register additional tools. Some examples:
+
+- [Lobster](/tools/lobster) — typed workflow runtime with resumable approvals
+- [LLM Task](/tools/llm-task) — JSON-only LLM step for structured output
+- [Diffs](/tools/diffs) — diff viewer and renderer
+- [OpenProse](/prose) — markdown-first workflow orchestration
+
+## Tool configuration
+
+### Allow and deny lists
+
+Control which tools the agent can call via `tools.allow` / `tools.deny` in
+config. Deny always wins over allow.
+
+```json5
+{
+  tools: {
+    allow: ["group:fs", "browser", "web_search"],
+    deny: ["exec"],
+  },
+}
+```
+
+### Tool profiles
+
+`tools.profile` sets a base allowlist before `allow`/`deny` is applied.
+Per-agent override: `agents.list[].tools.profile`.
+
+| Profile     | What it includes                            |
+| ----------- | ------------------------------------------- |
+| `full`      | All tools (default)                         |
+| `coding`    | File I/O, runtime, sessions, memory, image  |
+| `messaging` | Messaging, session list/history/send/status |
+| `minimal`   | `session_status` only                       |
+
+### Tool groups
+
+Use `group:*` shorthands in allow/deny lists:
+
+| Group              | Tools                                                                          |
+| ------------------ | ------------------------------------------------------------------------------ |
+| `group:runtime`    | exec, bash, process                                                            |
+| `group:fs`         | read, write, edit, apply_patch                                                 |
+| `group:sessions`   | sessions_list, sessions_history, sessions_send, sessions_spawn, session_status |
+| `group:memory`     | memory_search, memory_get                                                      |
+| `group:web`        | web_search, web_fetch                                                          |
+| `group:ui`         | browser, canvas                                                                |
+| `group:automation` | cron, gateway                                                                  |
+| `group:messaging`  | message                                                                        |
+| `group:nodes`      | nodes                                                                          |
+| `group:quantumclaw`   | All built-in QuantumClaw tools (excludes plugin tools)                            |
+
+### Provider-specific restrictions
+
+Use `tools.byProvider` to restrict tools for specific providers without
+changing global defaults:
+
+```json5
+{
+  tools: {
+    profile: "coding",
+    byProvider: {
+      "google-antigravity": { profile: "minimal" },
+    },
+  },
+}
+```

package/docs/tools/llm-task.md

@@ -0,0 +1,119 @@
+---
+summary: "JSON-only LLM tasks for workflows (optional plugin tool)"
+read_when:
+  - You want a JSON-only LLM step inside workflows
+  - You need schema-validated LLM output for automation
+title: "LLM Task"
+---
+
+# LLM Task
+
+`llm-task` is an **optional plugin tool** that runs a JSON-only LLM task and
+returns structured output (optionally validated against JSON Schema).
+
+This is ideal for workflow engines like Lobster: you can add a single LLM step
+without writing custom QuantumClaw code for each workflow.
+
+## Enable the plugin
+
+1. Enable the plugin:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "llm-task": { "enabled": true }
+    }
+  }
+}
+```
+
+2. Allowlist the tool (it is registered with `optional: true`):
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": { "allow": ["llm-task"] }
+      }
+    ]
+  }
+}
+```
+
+## Config (optional)
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "llm-task": {
+        "enabled": true,
+        "config": {
+          "defaultProvider": "openai-codex",
+          "defaultModel": "gpt-5.4",
+          "defaultAuthProfileId": "main",
+          "allowedModels": ["openai-codex/gpt-5.4"],
+          "maxTokens": 800,
+          "timeoutMs": 30000
+        }
+      }
+    }
+  }
+}
+```
+
+`allowedModels` is an allowlist of `provider/model` strings. If set, any request
+outside the list is rejected.
+
+## Tool parameters
+
+- `prompt` (string, required)
+- `input` (any, optional)
+- `schema` (object, optional JSON Schema)
+- `provider` (string, optional)
+- `model` (string, optional)
+- `thinking` (string, optional)
+- `authProfileId` (string, optional)
+- `temperature` (number, optional)
+- `maxTokens` (number, optional)
+- `timeoutMs` (number, optional)
+
+`thinking` accepts the standard QuantumClaw reasoning presets, such as `low` or `medium`.
+
+## Output
+
+Returns `details.json` containing the parsed JSON (and validates against
+`schema` when provided).
+
+## Example: Lobster workflow step
+
+```lobster
+quantumclaw.invoke --tool llm-task --action json --args-json '{
+  "prompt": "Given the input email, return intent and draft.",
+  "thinking": "low",
+  "input": {
+    "subject": "Hello",
+    "body": "Can you help?"
+  },
+  "schema": {
+    "type": "object",
+    "properties": {
+      "intent": { "type": "string" },
+      "draft": { "type": "string" }
+    },
+    "required": ["intent", "draft"],
+    "additionalProperties": false
+  }
+}'
+```
+
+## Safety notes
+
+- The tool is **JSON-only** and instructs the model to output only JSON (no
+  code fences, no commentary).
+- No tools are exposed to the model for this run.
+- Treat output as untrusted unless you validate with `schema`.
+- Put approvals before any side-effecting step (send, post, exec).