@tiny-fish/cli 0.41.2-next.326 → 0.41.2-next.328

package/dist/lib/bundled-skill.d.ts

@@ -0,0 +1,2 @@
+/** Two levels up from dist/lib/ is the package root; tsc mirrors src/. */
+export declare function bundledSkillDir(): string;

package/dist/lib/bundled-skill.js

@@ -0,0 +1,8 @@
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { WEB_SKILL_NAME } from './constants.js';
+/** Two levels up from dist/lib/ is the package root; tsc mirrors src/. */
+export function bundledSkillDir() {
+    const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+    return path.join(packageRoot, 'skill', WEB_SKILL_NAME);
+}

package/dist/lib/constants.d.ts

@@ -4,6 +4,8 @@ export declare const CLI_INVOCATION_ID: string;
 /** Unversioned: the install site appends `@latest`, the version read must not. */
 export declare const TINYFISH_CLI_PACKAGE = "@tiny-fish/cli";
 export declare const CLI_AGENT_IDENTITY = "tinyfish-cli";
+/** Names the bundled dir, every install target dir, and the lock entry. */
+export declare const WEB_SKILL_NAME = "use-tinyfish";
 /** The descriptor hands this name to harnesses; the probes resolve it. */
 export declare const TINYFISH_API_KEY_VAR = "TINYFISH_API_KEY";
 export declare const BASE_URL: string;

package/dist/lib/constants.js

@@ -9,6 +9,8 @@ export const CLI_INVOCATION_ID = randomUUID();
 export const TINYFISH_CLI_PACKAGE = '@tiny-fish/cli';
 // How we identify ourselves to other tools; `skills` echoes it back.
 export const CLI_AGENT_IDENTITY = 'tinyfish-cli';
+/** Names the bundled dir, every install target dir, and the lock entry. */
+export const WEB_SKILL_NAME = 'use-tinyfish';
 /** The descriptor hands this name to harnesses; the probes resolve it. */
 export const TINYFISH_API_KEY_VAR = 'TINYFISH_API_KEY';
 /** Base URL for the TinyFish API. Override with TINYFISH_API_URL for staging/self-hosted. */

package/dist/lib/notice.js

@@ -3,7 +3,9 @@ import { detectHumanInitiated } from './harness.js';
 import { err, sanitizeLine, warnLine } from './output.js';
 const NOTICE_HEADER = 'x-tf-notice';
 const LEVEL_HEADER = 'x-tf-notice-level';
+const LATEST_HEADER = 'x-tf-notice-latest';
 const MAX_LENGTH = 300;
+const PLAIN_VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
 const VALID_LEVELS = new Set(['required', 'recommended']);
 let captured;
 let printed = false;
@@ -24,26 +26,33 @@ export function captureNotice(headers) {
     if (!message)
         return;
     const rawLevel = headers.get(LEVEL_HEADER)?.trim().toLowerCase();
+    const rawLatest = headers.get(LATEST_HEADER)?.trim() ?? '';
     // Spread rather than `level: undefined`, which exactOptionalPropertyTypes rejects.
-    captured = { message, ...(rawLevel && VALID_LEVELS.has(rawLevel) ? { level: rawLevel } : {}) };
+    captured = {
+        message,
+        ...(rawLevel && VALID_LEVELS.has(rawLevel) ? { level: rawLevel } : {}),
+        ...(PLAIN_VERSION.test(rawLatest) ? { latest: rawLatest } : {}),
+    };
 }
 /** Built here, not by the server, so nothing it sends can reach an agent's context as instructions. */
-function agentMessage(level) {
+function agentMessage({ level, latest }) {
+    // Latest is the registry version, not the required floor; only the soft level names it.
+    const target = latest ? ` (latest ${latest})` : '';
     return level === 'required'
         ? `This TinyFish CLI (${CLI_VERSION}) is below the required minimum. Run: tinyfish upgrade`
-        : `A TinyFish CLI update is available (you have ${CLI_VERSION}). Run: tinyfish upgrade`;
+        : `A TinyFish CLI update is available${target} (you have ${CLI_VERSION}). Run: tinyfish upgrade`;
 }
 /** Advisory only, never changes stdout, the exit code, or control flow. */
 export function emitNotice() {
     if (printed || !captured)
         return;
     printed = true;
-    const { message, level } = captured;
+    const { message, ...rest } = captured;
     if (detectHumanInitiated()) {
         warnLine(message);
         return;
     }
-    err({ notice: agentMessage(level), ...(level ? { level } : {}) });
+    err({ notice: agentMessage(rest), ...rest });
 }
 /** For commands that are the fix themselves, such as `upgrade`, where the nudge is noise. */
 export function suppressNotice() {

package/dist/lib/skill-install.js

@@ -1,5 +1,4 @@
 import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
 import spawn from 'cross-spawn';
 import { loadConfig } from './auth.js';
@@ -8,6 +7,7 @@ import { CURSOR_SKILL_TARGET, NATIVE_MCP_CLIENTS, OPENCLAW, openclawSkillInstall
 import { ConnectInterruptedError, ConnectStepError, probeSupportVariant, spawnStepError, throwIfInterrupted, } from './connect-runtime.js';
 import { CLI_AGENT_IDENTITY } from './constants.js';
 import { errLine, sanitizeLine } from './output.js';
+import { skillTargetDir } from './skill-paths.js';
 // Supports Hermes without node:util.styleText, so the installer still runs on Node 20.11.
 export const SKILLS_CLI_PACKAGE = 'skills@1.5.15';
 const TINYFISH_WEB_SKILL_SOURCE = 'tinyfish-io/tinyfish-cookbook';
@@ -45,28 +45,10 @@ const SKILL_ALREADY_CURRENT_PATTERN = /All global skills are up to date/;
 // A lock entry with no recorded hash is untrackable, so `skills` reports it as skipped rather
 // than failed. Left undetected that reads as "up to date" while nothing was refreshed.
 const SKILL_UNCHECKABLE_PATTERN = /cannot be checked automatically/;
-// `skills` writes here for the universal agents, whose own config dirs it never touches.
-function canonicalSkillsDir() {
-    return path.join(os.homedir(), '.agents', 'skills'); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
-}
-// Where the harness reads. Both of the modes `add` picks land the skill here.
-const SKILL_DIR_BY_AGENT = {
-    'claude-code': () => path.join(agentHome('CLAUDE_CONFIG_DIR', '.claude'), 'skills'),
-    // The env value, not resolveHermesHome(): the child we spawn reads the env.
-    'hermes-agent': () => path.join(agentHome('HERMES_HOME', '.hermes'), 'skills'),
-    codex: canonicalSkillsDir,
-    cursor: canonicalSkillsDir,
-    opencode: canonicalSkillsDir,
-    // `skills` writes pi's here whatever PI_CODING_AGENT_DIR says.
-    pi: () => path.join(os.homedir(), '.pi', 'agent', 'skills'), // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
-};
-function agentHome(override, fallback) {
-    return process.env[override]?.trim() || path.join(os.homedir(), fallback); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
-}
 /** `add` exits 0 on per-agent failure, so the file it should have written is the verdict. */
 function skillOnDisk(agent) {
     // SKILL.md, not the dir: `skills` mkdirs before it copies, so a failed copy leaves one.
-    return fs.existsSync(path.join(SKILL_DIR_BY_AGENT[agent](), TINYFISH_WEB_SKILL, 'SKILL.md'));
+    return fs.existsSync(path.join(skillTargetDir(agent), 'SKILL.md'));
 }
 // The route tail-slices to 500, so an over-long tail would cut the tag off the front.
 const SKILL_DETAIL_TAIL_MAX_CHARS = 425;

package/dist/lib/skill-paths.d.ts

@@ -0,0 +1,5 @@
+import type { SkillAgent } from './harness-spec.js';
+/** The skill's own dir under where skills@1.5.15 wrote for this agent. */
+export declare function skillTargetDir(agent: SkillAgent): string;
+/** Mirrors skills@1.5.15 getSkillLockPath(); missing the XDG branch strands entries. */
+export declare function skillLockPath(): string;

package/dist/lib/skill-paths.js

@@ -0,0 +1,33 @@
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { WEB_SKILL_NAME } from './constants.js';
+// Mirrors skills@1.5.15 exactly: it trims and falls back on empty values.
+function agentHome(override, fallback) {
+    return process.env[override]?.trim() || path.join(os.homedir(), fallback); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
+}
+// `skills` writes here for the universal agents, whose own config dirs it never touches.
+function canonicalSkillsDir() {
+    return path.join(os.homedir(), '.agents', 'skills'); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
+}
+// Where the harness reads. Both of the modes `add` picks land the skill here.
+const SKILL_DIR_BY_AGENT = {
+    'claude-code': () => path.join(agentHome('CLAUDE_CONFIG_DIR', '.claude'), 'skills'),
+    // The env value, not resolveHermesHome(): skills@1.5.15 reads $HERMES_HOME directly.
+    'hermes-agent': () => path.join(agentHome('HERMES_HOME', '.hermes'), 'skills'),
+    codex: canonicalSkillsDir,
+    cursor: canonicalSkillsDir,
+    opencode: canonicalSkillsDir,
+    // `skills` writes pi's here whatever PI_CODING_AGENT_DIR says.
+    pi: () => path.join(os.homedir(), '.pi', 'agent', 'skills'), // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
+};
+/** The skill's own dir under where skills@1.5.15 wrote for this agent. */
+export function skillTargetDir(agent) {
+    return path.join(SKILL_DIR_BY_AGENT[agent](), WEB_SKILL_NAME);
+}
+/** Mirrors skills@1.5.15 getSkillLockPath(); missing the XDG branch strands entries. */
+export function skillLockPath() {
+    const xdgStateHome = process.env.XDG_STATE_HOME?.trim();
+    if (xdgStateHome)
+        return path.join(xdgStateHome, 'skills', '.skill-lock.json');
+    return path.join(os.homedir(), '.agents', '.skill-lock.json');
+}

package/dist/lib/skill-vendor.d.ts

@@ -0,0 +1,13 @@
+import type { SkillAgent } from './harness-spec.js';
+/**
+ * Writes the bundled skill where each agent reads it; true iff bytes changed.
+ *
+ * Synchronous on purpose: connect flows are sync, a new await breaks them.
+ */
+export declare function writeWebSkill(agents: SkillAgent[], opts?: {
+    sourceDir?: string;
+}): boolean;
+/** Best effort: a lock cleanup failure must never fail an install. */
+export declare function clearSkillLockEntry(opts?: {
+    verbose?: boolean;
+}): void;

package/dist/lib/skill-vendor.js

@@ -0,0 +1,187 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { bundledSkillDir } from './bundled-skill.js';
+import { WEB_SKILL_NAME } from './constants.js';
+import { ConnectStepError } from './connect-runtime.js';
+import { errLine } from './output.js';
+import { skillLockPath, skillTargetDir } from './skill-paths.js';
+// A younger staging dir may belong to a live concurrent connect.
+const STAGING_SWEEP_MIN_AGE_MS = 5 * 60_000;
+// Under the route's 500-char tail-slice; margin for caller prefixes.
+const FAILURE_DETAIL_MAX_CHARS = 425;
+/**
+ * Writes the bundled skill where each agent reads it; true iff bytes changed.
+ *
+ * Synchronous on purpose: connect flows are sync, a new await breaks them.
+ */
+export function writeWebSkill(agents, opts) {
+    const sourceDir = opts?.sourceDir ?? bundledSkillDir();
+    const targetDirs = [...new Set(agents.map(skillTargetDir))];
+    let changed = false;
+    for (const targetDir of targetDirs) {
+        try {
+            changed = writeSkillDir(sourceDir, targetDir) || changed;
+        }
+        catch (error) {
+            throw skillWriteError(error, targetDir);
+        }
+    }
+    return changed;
+}
+function writeSkillDir(sourceDir, targetDir) {
+    const parent = path.dirname(targetDir);
+    fs.mkdirSync(parent, { recursive: true });
+    sweepStaleStaging(parent);
+    if (matchesSource(sourceDir, targetDir))
+        return false;
+    // Stage-then-swap: an early rm would strand the user skill-less on failure.
+    const stagingDir = path.join(parent, `${WEB_SKILL_NAME}.tmp-${process.pid}`);
+    fs.rmSync(stagingDir, { recursive: true, force: true });
+    fs.mkdirSync(stagingDir);
+    for (const name of fs.readdirSync(sourceDir)) {
+        fs.copyFileSync(path.join(sourceDir, name), path.join(stagingDir, name));
+    }
+    swapIntoPlace(stagingDir, targetDir, sourceDir);
+    return true;
+}
+// The old copy survives as a sibling backup until the new dir lands.
+function swapIntoPlace(stagingDir, targetDir, sourceDir) {
+    const backupDir = moveAsideExisting(targetDir);
+    try {
+        try {
+            fs.renameSync(stagingDir, targetDir);
+        }
+        catch (error) {
+            // A concurrent connect can recreate the target mid-swap.
+            if (!isErrnoCode(error, 'ENOTEMPTY') && !isErrnoCode(error, 'EEXIST'))
+                throw error;
+            if (matchesSource(sourceDir, targetDir)) {
+                // The concurrent writer already landed these bytes; ours can go.
+                fs.rmSync(stagingDir, { recursive: true, force: true });
+            }
+            else {
+                removeExistingEntry(targetDir);
+                fs.renameSync(stagingDir, targetDir);
+            }
+        }
+    }
+    catch (error) {
+        fs.rmSync(stagingDir, { recursive: true, force: true });
+        restoreBackup(backupDir, targetDir);
+        throw error;
+    }
+    if (backupDir)
+        removeExistingEntry(backupDir);
+}
+// Sweep-prefixed name, so an orphaned backup is eventually cleaned.
+function moveAsideExisting(targetDir) {
+    try {
+        fs.lstatSync(targetDir);
+    }
+    catch {
+        return null;
+    }
+    const backupDir = `${targetDir}.tmp-${process.pid}-prev`;
+    removeExistingEntry(backupDir);
+    fs.renameSync(targetDir, backupDir);
+    return backupDir;
+}
+function restoreBackup(backupDir, targetDir) {
+    if (!backupDir)
+        return;
+    try {
+        fs.renameSync(backupDir, targetDir);
+    }
+    catch {
+        // A concurrent writer owns the target now; leave its copy in place.
+    }
+}
+/** Only a real dir with the bundle's exact file set and bytes skips. */
+function matchesSource(sourceDir, targetDir) {
+    let stat;
+    try {
+        stat = fs.lstatSync(targetDir);
+    }
+    catch {
+        return false;
+    }
+    if (!stat.isDirectory())
+        return false;
+    const sourceFiles = fs.readdirSync(sourceDir).sort();
+    const targetFiles = fs.readdirSync(targetDir).sort();
+    if (sourceFiles.join('\n') !== targetFiles.join('\n'))
+        return false;
+    return sourceFiles.every((name) => fs.readFileSync(path.join(sourceDir, name)).equals(fs.readFileSync(path.join(targetDir, name))));
+}
+/** lstat first: a skills-CLI symlink must be unlinked, never followed. */
+function removeExistingEntry(targetDir) {
+    let stat;
+    try {
+        stat = fs.lstatSync(targetDir);
+    }
+    catch {
+        return;
+    }
+    if (stat.isDirectory()) {
+        fs.rmSync(targetDir, { recursive: true });
+        return;
+    }
+    try {
+        fs.unlinkSync(targetDir);
+    }
+    catch (error) {
+        // Windows junctions: unlink is EPERM there, rmdir removes the link.
+        if (isErrnoCode(error, 'EPERM') || isErrnoCode(error, 'EISDIR'))
+            fs.rmdirSync(targetDir);
+        else
+            throw error;
+    }
+}
+function sweepStaleStaging(parent) {
+    let entries;
+    try {
+        entries = fs.readdirSync(parent);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (!name.startsWith(`${WEB_SKILL_NAME}.tmp-`))
+            continue;
+        try {
+            const staged = path.join(parent, name);
+            if (Date.now() - fs.lstatSync(staged).mtimeMs < STAGING_SWEEP_MIN_AGE_MS)
+                continue;
+            fs.rmSync(staged, { recursive: true, force: true });
+        }
+        catch {
+            // Best effort; a sweep failure must never fail the install.
+        }
+    }
+}
+// Reason stays in the closed enum; the errno rides failure_detail instead.
+function skillWriteError(error, targetDir) {
+    const code = error?.code ?? 'unknown';
+    return new ConnectStepError('Could not write the TinyFish web skill', 'unexpected_error', {
+        cause: error,
+        failureDetail: `skill_write_failed ${code} ${targetDir}`.slice(0, FAILURE_DETAIL_MAX_CHARS),
+    });
+}
+function isErrnoCode(error, code) {
+    return error?.code === code;
+}
+/** Best effort: a lock cleanup failure must never fail an install. */
+export function clearSkillLockEntry(opts) {
+    const lockPath = skillLockPath();
+    try {
+        const lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+        if (!lock.skills || !(WEB_SKILL_NAME in lock.skills))
+            return;
+        delete lock.skills[WEB_SKILL_NAME];
+        fs.writeFileSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`);
+    }
+    catch {
+        if (opts?.verbose)
+            errLine('Skipped cleaning the skills lock file.');
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.41.2-next.326",
+  "version": "0.41.2-next.328",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist/",
+    "skill/",
     "README.md",
     "LICENSE"
   ],

package/skill/.source-commit

@@ -0,0 +1 @@
+8615317f6db58ae776dd53817ac30668c1db5ef8

package/skill/use-tinyfish/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: use-tinyfish
+description: Use TinyFish for web search, fetching URLs, reading pages, current information, source-backed answers, research, docs, pricing/product pages, extraction, scraping, and browser automation. Use whenever the user asks to search, find, look up, research, compare, get information from the web, summarize a URL, fetch page content, or automate a website.
+---
+
+# TinyFish CLI
+
+You have access to the TinyFish CLI (`tinyfish`) — a suite of web tools you can call from the terminal.
+
+If not installed: `npm install -g @tiny-fish/cli`
+If not authenticated: `tinyfish auth login --source openclaw` or set `TINYFISH_API_KEY` env var.
+
+---
+
+## When This Skill Should Trigger
+
+Use TinyFish whenever a request depends on live web information or page content. Do not wait for the user to say "TinyFish" or "scrape".
+
+Strong triggers include:
+
+- Search or discovery: search, find, look up, research, compare, latest, current, news, docs, pricing, product details, best options.
+- URL/page reading: fetch, read, summarize, extract from this page, inspect this URL, get the content, pull links or metadata.
+- Source-backed answers: answer using web sources, verify a fact, check whether something changed, gather information from the web.
+- Website work: interact with a site, click through pages, fill forms, log in, collect structured data, handle bot-protected pages.
+
+Default to the lightest tool that can answer:
+
+- No URL and the user needs web information: `search`, then `fetch` the best result(s) if more detail is needed.
+- URL provided and only content is needed: `fetch`.
+- Page interaction or dynamic extraction is needed: `agent`.
+- Raw CDP/Playwright-style control is needed: `browser`.
+
+---
+
+## Picking the Right Tool
+
+TinyFish has four tools. Start with the lightest one that can do the job and escalate only when needed.
+
+```
+search  →  fetch  →  agent  →  browser
+lightest                        heaviest
+```
+
+| Tool | When to use | Speed | Cost |
+|------|-------------|-------|------|
+| **search** | You need to find URLs, current facts, docs, pricing, product details, or a quick source-backed answer | Fastest | Lowest |
+| **fetch** | You have URLs and need clean page content, summaries, article text, docs, product pages, links, or metadata | Fast | Low |
+| **agent** | You need to interact with a page — click, fill forms, navigate, extract structured data from dynamic sites | Slower | Higher |
+| **browser** | Agent isn't enough — you need raw programmatic browser control via CDP | Slowest | Highest |
+
+### Common Patterns
+
+**Research: search → fetch**
+Search for a topic, then fetch the best results to read their full content.
+
+```bash
+# 1. Find URLs
+tinyfish search query "best React state management libraries 2026"
+
+# 2. Read the top results
+tinyfish fetch content get --format markdown "https://result1.com" "https://result2.com"
+```
+
+**Deep extraction: search → agent**
+Search to find the right site, then use agent to interact with it and extract structured data.
+
+```bash
+# 1. Find the site
+tinyfish search query "Nike running shoes official store"
+
+# 2. Automate extraction on it
+tinyfish agent run --url "https://nike.com/running" \
+  "Extract all running shoes as JSON: [{\"name\": str, \"price\": str, \"colors\": [str]}]"
+```
+
+**Escalation: fetch → agent**
+Try fetch first. If the page is dynamic/JS-heavy and fetch returns empty or incomplete content, escalate to agent.
+
+**Full control: agent → browser**
+If agent can't handle a complex multi-step workflow, spin up a raw browser session and automate it yourself via CDP.
+
+---
+
+## Commands
+
+### `tinyfish search query`
+
+Web search. Returns ranked results with titles, URLs, and snippets.
+
+```bash
+tinyfish search query "<query>" [--location <hint>] [--language <hint>] [--pretty]
+```
+
+- Returns 10 results by default
+- Use `--location` and `--language` for geo-targeted results
+- Default output is JSON; `--pretty` for human-readable
+
+```bash
+tinyfish search query "best pho in Ho Chi Minh City" --location "Vietnam" --language "en"
+```
+
+---
+
+### `tinyfish fetch content get`
+
+Fetch clean, extracted content from one or more URLs. Strips ads, nav, boilerplate — returns just the content.
+
+```bash
+tinyfish fetch content get <urls...> [--format markdown|html|json] [--links] [--image-links] [--pretty]
+```
+
+- Accepts **multiple URLs** in a single call — they are fetched in parallel server-side
+- `--format markdown` (default) — clean readable text
+- `--format json` — structured document tree
+- `--links` — include all extracted links from the page
+- `--image-links` — include extracted image URLs
+- Response includes: `url`, `final_url`, `title`, `language`, `author`, `published_date`, `text`, `latency_ms`
+
+```bash
+# Fetch one page as markdown
+tinyfish fetch content get --format markdown "https://example.com/article"
+
+# Fetch multiple pages with links
+tinyfish fetch content get --links "https://site-a.com" "https://site-b.com" "https://site-c.com"
+```
+
+---
+
+### `tinyfish agent run`
+
+Run a browser automation using a natural language goal. The agent opens a real browser, navigates, clicks, fills forms, and extracts data.
+
+```bash
+tinyfish agent run --url <url> "<goal>" [--sync] [--async] [--pretty]
+```
+
+| Flag | Purpose |
+|------|---------|
+| `--url <url>` | Target URL (bare hostnames get `https://` auto-prepended) |
+| `--sync` | Wait for full result without streaming steps |
+| `--async` | Submit and return immediately |
+| `--pretty` | Human-readable output |
+
+**Output:** Default streams `data: {...}` SSE lines. The final result is the event where `type == "COMPLETE"` and `status == "COMPLETED"` — the extracted data is in the `resultJson` field. Read the raw output directly; no script-side parsing is needed.
+
+**Always specify the JSON structure you want in the goal:**
+
+```bash
+tinyfish agent run --url "https://example.com/products" \
+  "Extract all products as JSON array: [{\"name\": str, \"price\": str, \"url\": str}]"
+
+tinyfish agent run --url "https://example.com/search" \
+  "Search for 'wireless headphones', filter under $50, extract top 5 as JSON: [{\"name\": str, \"price\": str, \"rating\": str}]"
+```
+
+**Parallel extraction — when hitting multiple independent sites, make separate calls. Do NOT combine into one goal.**
+
+Good — parallel calls (run simultaneously):
+```bash
+tinyfish agent run --url "https://pizzahut.com" \
+  "Extract pizza prices as JSON: [{\"name\": str, \"price\": str}]"
+
+tinyfish agent run --url "https://dominos.com" \
+  "Extract pizza prices as JSON: [{\"name\": str, \"price\": str}]"
+```
+
+Bad — single combined call:
+```bash
+# Don't do this — less reliable and slower
+tinyfish agent run --url "https://pizzahut.com" \
+  "Extract prices from Pizza Hut and also go to Dominos..."
+```
+
+**Managing runs:**
+
+```bash
+tinyfish agent run list [--status PENDING|RUNNING|COMPLETED|FAILED|CANCELLED] [--limit N]
+tinyfish agent run get <run_id>
+tinyfish agent run cancel <run_id>
+```
+
+**Batch operations** — submit many runs from a CSV file (`url,goal` columns):
+
+```bash
+tinyfish agent batch run --input runs.csv
+tinyfish agent batch list
+tinyfish agent batch get <batch_id>
+tinyfish agent batch cancel <batch_id>
+```
+
+---
+
+### `tinyfish browser session create`
+
+Spin up a remote browser instance. Returns a CDP WebSocket URL for programmatic control.
+
+```bash
+tinyfish browser session create [--url <url>] [--pretty]
+```
+
+- `--url` optionally navigates to a page after creation
+- Returns `session_id`, `cdp_url` (WebSocket), and `base_url`
+- Use the `cdp_url` with Playwright, Puppeteer, or any CDP client
+
+```bash
+tinyfish browser session create --url "https://example.com"
+# Returns: { session_id, cdp_url: "wss://...", base_url: "https://..." }
+```
+
+---
+
+## General Notes
+
+- **Match the user's language**: Respond in whatever language the user writes in.
+- All commands support `--pretty` for human-readable output. Default is JSON.
+- Use `--debug` on the root command or set `TINYFISH_DEBUG=1` to log HTTP requests to stderr.