ultimate-pi 0.3.1 → 0.4.1

package/vendor/pi-vcc/tests/recall-expand.test.ts

@@ -0,0 +1,15 @@
+import { describe, it, expect } from "bun:test";
+import { invalidExpandIndices } from "../src/tools/recall";
+
+describe("invalidExpandIndices", () => {
+  it("returns indices that are not in available lineage index set", () => {
+    const available = new Set([0, 2, 5]);
+    expect(invalidExpandIndices([0, 2], available)).toEqual([]);
+    expect(invalidExpandIndices([1, 2, 7], available)).toEqual([1, 7]);
+  });
+
+  it("rejects non-integer indices", () => {
+    const available = new Set([0, 1, 2]);
+    expect(invalidExpandIndices([1.5, 2], available)).toEqual([1.5]);
+  });
+});

package/vendor/pi-vcc/tests/recall-scope.test.ts

@@ -0,0 +1,32 @@
+import { describe, it, expect } from "bun:test";
+import { normalizeRecallScope, parseRecallScope } from "../src/core/recall-scope";
+
+describe("normalizeRecallScope", () => {
+  it("defaults to active lineage", () => {
+    expect(normalizeRecallScope()).toBe("lineage");
+    expect(normalizeRecallScope("lineage")).toBe("lineage");
+    expect(normalizeRecallScope("unknown")).toBe("lineage");
+    expect(normalizeRecallScope(123)).toBe("lineage");
+  });
+
+  it("accepts all scope", () => {
+    expect(normalizeRecallScope("all")).toBe("all");
+    expect(normalizeRecallScope("ALL")).toBe("all");
+  });
+});
+
+describe("parseRecallScope", () => {
+  it("removes scope token from command text", () => {
+    expect(parseRecallScope("license scope:all page:2")).toEqual({
+      scope: "all",
+      text: "license page:2",
+    });
+  });
+
+  it("defaults to lineage when no scope token is present", () => {
+    expect(parseRecallScope("license page:2")).toEqual({
+      scope: "lineage",
+      text: "license page:2",
+    });
+  });
+});

package/vendor/pi-vcc/tests/recall-tool-scope.test.ts

@@ -0,0 +1,67 @@
+import { describe, it, expect } from "bun:test";
+import { mkdtempSync, writeFileSync, rmSync } from "fs";
+import { tmpdir } from "os";
+import { join } from "path";
+import { registerRecallTool } from "../src/tools/recall";
+
+const makeSession = () => {
+  const dir = mkdtempSync(join(tmpdir(), "pi-vcc-recall-scope-"));
+  const file = join(dir, "session.jsonl");
+  const lines = [
+    JSON.stringify({ type: "message", id: "m1", message: { role: "user", content: "active lineage token" } }),
+    JSON.stringify({ type: "message", id: "m2", message: { role: "user", content: "off lineage secret" } }),
+  ];
+  writeFileSync(file, lines.join("\n") + "\n", "utf8");
+  return { dir, file };
+};
+
+const register = () => {
+  let tool: any;
+  registerRecallTool({ registerTool: (t: any) => { tool = t; } } as any);
+  return tool;
+};
+
+const invoke = async (tool: any, file: string, params: Record<string, unknown>) => {
+  const result = await tool.execute("tool-call", params, undefined, undefined, {
+    sessionManager: {
+      getSessionFile: () => file,
+      getBranch: () => [{ id: "m1" }],
+      getEntries: () => [{ id: "m1" }, { id: "m2" }],
+    },
+  });
+  return result.content[0].text as string;
+};
+
+describe("vcc_recall scope", () => {
+  it("defaults to active lineage and opts into all-session search explicitly", async () => {
+    const { dir, file } = makeSession();
+    try {
+      const tool = register();
+
+      const lineage = await invoke(tool, file, { query: "secret" });
+      expect(lineage).toContain("No matches");
+
+      const all = await invoke(tool, file, { query: "secret", scope: "all" });
+      expect(all).toContain("scope: all");
+      expect(all).toContain("off lineage secret");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  it("keeps expand strict by default but allows off-lineage expand with scope all", async () => {
+    const { dir, file } = makeSession();
+    try {
+      const tool = register();
+
+      const lineage = await invoke(tool, file, { expand: [1] });
+      expect(lineage).toContain("Cannot expand indices outside active lineage: 1");
+
+      const all = await invoke(tool, file, { expand: [1], scope: "all" });
+      expect(all).toContain("Scope: all");
+      expect(all).toContain("#1 [user] off lineage secret");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/vendor/pi-vcc/tests/render-entries.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from "bun:test";
+import { renderMessage } from "../src/core/render-entries";
+import type { Message } from "@mariozechner/pi-ai";
+import { userMsg, assistantText, assistantWithToolCall, toolResult } from "./fixtures";
+
+describe("renderMessage", () => {
+  it("renders user message", () => {
+    const r = renderMessage(userMsg("hello"), 0);
+    expect(r).toEqual({ index: 0, role: "user", summary: "hello" });
+  });
+
+  it("renders assistant text", () => {
+    const r = renderMessage(assistantText("done"), 1);
+    expect(r.role).toBe("assistant");
+    expect(r.summary).toBe("done");
+  });
+
+  it("renders tool result", () => {
+    const r = renderMessage(toolResult("Read", "file contents"), 2);
+    expect(r.role).toBe("tool_result");
+    expect(r.summary).toContain("[Read]");
+  });
+
+  it("renders tool call arguments with values", () => {
+    const r = renderMessage(assistantWithToolCall("Read", { path: "a.ts" }), 2);
+    expect(r.summary).toContain("Read(path=a.ts)");
+  });
+
+  it("renders error tool result with prefix", () => {
+    const r = renderMessage(toolResult("bash", "not found", true), 3);
+    expect(r.summary).toStartWith("ERROR");
+  });
+
+  it("truncates long user text", () => {
+    const long = "x".repeat(500);
+    const r = renderMessage(userMsg(long), 0);
+    expect(r.summary.length).toBeLessThanOrEqual(300);
+  });
+
+  it("renders bashExecution message", () => {
+    const msg = { role: "bashExecution", command: "ls -la", output: "total 0\n" } as any;
+    const r = renderMessage(msg, 5);
+    expect(r.role).toBe("bash");
+    expect(r.summary).toContain("$ ls -la");
+    expect(r.summary).toContain("total 0");
+  });
+
+  it("renders bashExecution with missing output", () => {
+    const msg = { role: "bashExecution", command: "exit 1" } as any;
+    const r = renderMessage(msg, 6);
+    expect(r.role).toBe("bash");
+    expect(r.summary).toContain("$ exit 1");
+  });
+
+  it("handles message with undefined content", () => {
+    const msg = { role: "assistant", content: undefined } as any;
+    const r = renderMessage(msg, 3);
+    expect(r.role).toBe("assistant");
+    expect(r.summary).toBe("");
+  });
+});
+

package/vendor/pi-vcc/tests/report.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from "bun:test";
+import { buildCompactReport } from "../src/core/report";
+import {
+  userMsg,
+  assistantText,
+  assistantWithToolCall,
+  toolResult,
+} from "./fixtures";
+
+describe("buildCompactReport", () => {
+  it("includes before and after compact metrics", () => {
+    const report = buildCompactReport({
+      messages: [
+        userMsg("Fix login bug in auth.ts"),
+        assistantWithToolCall("Read", { path: "auth.ts" }),
+        toolResult("Read", "const x = 1;"),
+        assistantText("Found the root cause in auth.ts.\n1. Fix validation\n2. Run tests"),
+      ],
+    });
+    expect(report.before.messageCount).toBe(4);
+    expect(report.before.roleCounts.user).toBe(1);
+    expect(report.before.topFiles).toContain("auth.ts");
+    expect(report.before.preview).toContain("Fix login bug in auth.ts");
+    expect(report.after.sectionCount).toBeGreaterThan(0);
+    expect(report.after.summaryPreview).toContain("[Session Goal]");
+    expect(report.after.summaryPreview).toContain('* Read "auth.ts"');
+    expect(report.after.briefTranscriptLines).toBeGreaterThan(0);
+    expect(report.compression.ratio).toBeGreaterThan(0);
+  });
+
+  it("marks recall probe coverage for goal and file queries", () => {
+    const report = buildCompactReport({
+      messages: [
+        userMsg("Fix login bug in auth.ts"),
+        assistantWithToolCall("Read", { path: "auth.ts" }),
+        toolResult("Read", "code content"),
+        assistantText("Found the root cause"),
+      ],
+    });
+    expect(report.recall.probes.length).toBeGreaterThanOrEqual(1);
+    const goalProbe = report.recall.probes.find((p) => p.label === "goal");
+    expect(goalProbe?.summaryMentioned).toBe(true);
+  });
+});

package/vendor/pi-vcc/tests/sanitize.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect } from "bun:test";
+import { sanitize } from "../src/core/sanitize";
+
+describe("sanitize", () => {
+  it("strips ANSI escape codes", () => {
+    expect(sanitize("\x1b[31mred\x1b[0m")).toBe("red");
+  });
+
+  it("normalizes CRLF to LF", () => {
+    expect(sanitize("a\r\nb\r\n")).toBe("a\nb\n");
+  });
+
+  it("strips bare CR", () => {
+    expect(sanitize("a\rb")).toBe("a\nb");
+  });
+
+  it("strips control characters but preserves newlines and tabs", () => {
+    expect(sanitize("a\x00b\tc\nd")).toBe("ab\tc\nd");
+  });
+
+  it("passes clean text unchanged", () => {
+    expect(sanitize("hello world")).toBe("hello world");
+  });
+});

package/vendor/pi-vcc/tests/search-entries.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect } from "bun:test";
+import { searchEntries } from "../src/core/search-entries";
+import type { RenderedEntry } from "../src/core/render-entries";
+import type { Message } from "@mariozechner/pi-ai";
+
+const entries: RenderedEntry[] = [
+  { index: 0, role: "user", summary: "Fix login bug" },
+  { index: 1, role: "assistant", summary: "Reading auth.ts" },
+  { index: 2, role: "tool_result", summary: "[Read] code here" },
+  { index: 3, role: "assistant", summary: "Found the root cause in auth module" },
+];
+
+const messages: Message[] = [
+  { role: "user", content: "Fix login bug" } as any,
+  { role: "assistant", content: [{ type: "text", text: "Reading auth.ts" }] } as any,
+  { role: "toolResult", content: [{ type: "text", text: "[Read] code here" }] } as any,
+  { role: "assistant", content: [{ type: "text", text: "Found the root cause in auth module" }] } as any,
+];
+
+describe("searchEntries", () => {
+  it("returns all for empty query", () => {
+    expect(searchEntries(entries, messages)).toEqual(entries);
+    expect(searchEntries(entries, messages, "")).toEqual(entries);
+  });
+
+  it("filters by single term", () => {
+    const r = searchEntries(entries, messages, "login");
+    expect(r).toHaveLength(1);
+    expect(r[0].index).toBe(0);
+  });
+
+  it("returns empty for no match", () => {
+    expect(searchEntries(entries, messages, "xyz123")).toEqual([]);
+  });
+
+  it("finds keyword beyond clip boundary in full content", () => {
+    const longText = "A".repeat(400) + " hidden_keyword here";
+    const longEntries: RenderedEntry[] = [
+      { index: 0, role: "user", summary: "A".repeat(300) },
+    ];
+    const longMsgs: Message[] = [
+      { role: "user", content: longText } as any,
+    ];
+    const r = searchEntries(longEntries, longMsgs, "hidden_keyword");
+    expect(r).toHaveLength(1);
+    expect(r[0].snippet).toContain("hidden_keyword");
+  });
+
+  it("returns snippet around matched term", () => {
+    const r = searchEntries(entries, messages, "root");
+    expect(r).toHaveLength(1);
+    expect(r[0].snippet).toBeDefined();
+    expect(r[0].snippet).toContain("root");
+  });
+
+  // ── regex support ──
+
+  it("supports regex pattern: alternation", () => {
+    const r = searchEntries(entries, messages, "login|auth");
+    expect(r).toHaveLength(3); // "login bug", "auth.ts", "auth module"
+    expect(r.map((h) => h.index).sort()).toEqual([0, 1, 3]);
+  });
+
+  it("supports regex pattern: wildcard", () => {
+    const r = searchEntries(entries, messages, "Read.*auth");
+    expect(r).toHaveLength(1);
+    expect(r[0].index).toBe(1);
+  });
+
+  it("falls back to escaped literal for invalid regex", () => {
+    const extraEntries: RenderedEntry[] = [
+      { index: 0, role: "user", summary: "test (foo" },
+      { index: 1, role: "assistant", summary: "no match here" },
+    ];
+    const extraMsgs: Message[] = [
+      { role: "user", content: "error with (foo pattern" } as any,
+      { role: "assistant", content: [{ type: "text", text: "no match here" }] } as any,
+    ];
+    const r = searchEntries(extraEntries, extraMsgs, "(foo");
+    expect(r).toHaveLength(1);
+    expect(r[0].index).toBe(0);
+  });
+
+  it("regex is case-insensitive", () => {
+    const r = searchEntries(entries, messages, "FIX|ROOT");
+    expect(r).toHaveLength(2);
+  });
+
+  // ── natural language queries (OR logic + ranking) ──
+
+  it("natural language query uses OR logic", () => {
+    // "root cause auth" -- matches entries containing ANY of these terms
+    const r = searchEntries(entries, messages, "root cause auth");
+    expect(r.length).toBeGreaterThanOrEqual(2); // #3 has all 3, #1 has auth
+    // Best match (highest BM25) should come first
+    expect(r[0].index).toBe(3); // "Found the root cause in auth module" matches all 3
+  });
+
+  it("natural language ranks by BM25 score", () => {
+    const r = searchEntries(entries, messages, "root cause auth");
+    // Top result has more terms matched = higher BM25 score
+    expect(r[0].matchCount!).toBeGreaterThanOrEqual(r[r.length - 1].matchCount!);
+  });
+
+  it("filters stopwords from queries", () => {
+    // "the root cause of it" → stopwords: the, of, it → meaningful: root, cause
+    const r = searchEntries(entries, messages, "the root cause of it");
+    expect(r).toHaveLength(1);
+    expect(r[0].index).toBe(3);
+  });
+
+  it("keeps all terms if all are stopwords", () => {
+    // When all terms are stopwords, keep them (don't drop everything)
+    // "the" appears in "Found the root cause" so it matches
+    const r = searchEntries(entries, messages, "the");
+    expect(r.length).toBeGreaterThan(0);
+  });
+
+  // ── line-based snippet ──
+
+  it("snippet shows context lines around match", () => {
+    const multiline = "line 0\nline 1\nline 2 TARGET\nline 3\nline 4\nline 5";
+    const e: RenderedEntry[] = [{ index: 0, role: "user", summary: "test" }];
+    const m: Message[] = [{ role: "user", content: multiline } as any];
+    const r = searchEntries(e, m, "TARGET");
+    expect(r).toHaveLength(1);
+    const snip = r[0].snippet!;
+    expect(snip).toContain("line 2 TARGET");
+    expect(snip).toContain("line 0");
+    expect(snip).toContain("line 4");
+    expect(snip).not.toContain("line 5");
+  });
+
+  it("snippet handles match at beginning", () => {
+    const multiline = "TARGET here\nline 1\nline 2\nline 3";
+    const e: RenderedEntry[] = [{ index: 0, role: "user", summary: "test" }];
+    const m: Message[] = [{ role: "user", content: multiline } as any];
+    const r = searchEntries(e, m, "TARGET");
+    const snip = r[0].snippet!;
+    expect(snip).toContain("TARGET here");
+    expect(snip).toContain("line 2");
+    expect(snip).not.toContain("line 3");
+  });
+});

package/vendor/pi-vcc/tests/support/load-session.ts

@@ -0,0 +1,23 @@
+import { buildSessionContext, loadEntriesFromFile } from "../../node_modules/@mariozechner/pi-coding-agent/dist/core/session-manager.js";
+import type { Message } from "@mariozechner/pi-ai";
+
+export interface LoadedSession {
+  messageCount: number;
+  skippedCount: number;
+  messages: Message[];
+}
+
+export const loadSessionMessages = (file: string): LoadedSession => {
+  const entries = loadEntriesFromFile(file);
+  const sessionEntries = entries.filter((entry) => entry.type !== "header");
+  const context = buildSessionContext(sessionEntries as any);
+  const messages = (context.messages as any[]).filter(
+    (msg): msg is Message =>
+      msg && typeof msg.role === "string" && "content" in msg,
+  );
+  return {
+    messageCount: messages.length,
+    skippedCount: context.messages.length - messages.length,
+    messages,
+  };
+};

package/vendor/pi-vcc/tests/support/real-sessions.ts

@@ -0,0 +1,51 @@
+import { mkdir, mkdtemp, copyFile, chmod, readdir, stat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, basename } from "node:path";
+
+const SESSION_ROOT = join(process.env.HOME ?? "", ".pi/agent/sessions");
+
+export interface SessionSample {
+  source: string;
+  copy: string;
+  size: number;
+  mtimeMs: number;
+}
+
+const walk = async (dir: string): Promise<string[]> => {
+  const names = await readdir(dir, { withFileTypes: true });
+  const out: string[] = [];
+  for (const name of names) {
+    const path = join(dir, name.name);
+    if (name.isDirectory()) out.push(...await walk(path));
+    else if (name.isFile() && path.endsWith(".jsonl")) out.push(path);
+  }
+  return out;
+};
+
+const pickLargest = async (limit: number): Promise<string[]> => {
+  const files = await walk(SESSION_ROOT);
+  const sized = await Promise.all(
+    files.map(async (file) => ({ file, size: (await stat(file)).size })),
+  );
+  return sized.sort((a, b) => b.size - a.size).slice(0, limit).map((x) => x.file);
+};
+
+export const prepareSessionSamples = async (limit = 2): Promise<SessionSample[]> => {
+  const selected = await pickLargest(limit);
+  const dir = await mkdtemp(join(tmpdir(), "pi-vcc-sessions-"));
+  await mkdir(dir, { recursive: true });
+  const samples: SessionSample[] = [];
+  for (const source of selected) {
+    const srcStat = await stat(source);
+    const copy = join(dir, basename(source));
+    await copyFile(source, copy);
+    await chmod(copy, 0o444);
+    samples.push({ source, copy, size: srcStat.size, mtimeMs: srcStat.mtimeMs });
+  }
+  return samples;
+};
+
+export const readSourceStat = async (sample: SessionSample) => {
+  const s = await stat(sample.source);
+  return { size: s.size, mtimeMs: s.mtimeMs };
+};

package/.agents/skills/firecrawl/SKILL.md

@@ -1,150 +0,0 @@
----
-name: firecrawl
-description: |
-  Search, scrape, and interact with the web via the Firecrawl CLI. Use this skill whenever the user wants to search the web, find articles, research a topic, look something up online, scrape a webpage, grab content from a URL, get data from a website, crawl documentation, download a site, or interact with pages that need clicks or logins. Also use when they say "fetch this page", "pull the content from", "get the page at https://", or reference external websites. This provides real-time web search with full page content and interact capabilities — beyond what Claude can do natively with built-in tools. Do NOT trigger for local file operations, git commands, deployments, or code editing tasks.
-allowed-tools:
-  - Bash(firecrawl *)
-  - Bash(npx firecrawl *)
----
-
-# Firecrawl CLI
-
-Search, scrape, and interact with the web. Returns clean markdown optimized for LLM context windows.
-
-Run `firecrawl --help` or `firecrawl <command> --help` for full option details.
-
-If the task is to integrate Firecrawl into an application, add `FIRECRAWL_API_KEY` to a project, or choose endpoint usage in product code, use the `firecrawl-build` skills. They are already installed alongside this CLI skill when you run `firecrawl init`.
-
-## Prerequisites
-
-Must be installed and authenticated. Check with `firecrawl --status`.
-
-```
-  🔥 firecrawl cli v1.8.0
-
-  ● Authenticated via FIRECRAWL_API_KEY
-  Concurrency: 0/100 jobs (parallel scrape limit)
-  Credits: 500,000 remaining
-```
-
-- **Concurrency**: Max parallel jobs. Run parallel operations up to this limit.
-- **Credits**: Remaining API credits. Each operation consumes credits.
-
-If not ready, see [rules/install.md](rules/install.md). For output handling guidelines, see [rules/security.md](rules/security.md).
-
-Before doing real work, verify the setup with one small request:
-
-```bash
-mkdir -p .firecrawl
-firecrawl scrape "https://firecrawl.dev" -o .firecrawl/install-check.md
-```
-
-```bash
-firecrawl search "query" --scrape --limit 3
-```
-
-## Workflow
-
-Follow this escalation pattern:
-
-1. **Search** - No specific URL yet. Find pages, answer questions, discover sources.
-2. **Scrape** - Have a URL. Extract its content directly.
-3. **Map + Scrape** - Large site or need a specific subpage. Use `map --search` to find the right URL, then scrape it.
-4. **Crawl** - Need bulk content from an entire site section (e.g., all /docs/).
-5. **Interact** - Scrape first, then interact with the page (pagination, modals, form submissions, multi-step navigation).
-
-| Need                        | Command               | When                                                      |
-| --------------------------- | --------------------- | --------------------------------------------------------- |
-| Find pages on a topic       | `search`              | No specific URL yet                                       |
-| Get a page's content        | `scrape`              | Have a URL, page is static or JS-rendered                 |
-| Find URLs within a site     | `map`                 | Need to locate a specific subpage                         |
-| Bulk extract a site section | `crawl`               | Need many pages (e.g., all /docs/)                        |
-| AI-powered data extraction  | `agent`               | Need structured data from complex sites                   |
-| Interact with a page        | `scrape` + `interact` | Content requires clicks, form fills, pagination, or login |
-| Download a site to files    | `download`            | Save an entire site as local files                        |
-| Parse a local file          | `parse`               | File on disk (PDF, DOCX, XLSX, etc.) — not a URL          |
-
-For detailed command reference, run `firecrawl <command> --help`.
-
-**Scrape vs interact:**
-
-- Use `scrape` first. It handles static pages and JS-rendered SPAs.
-- Use `scrape` + `interact` when you need to interact with a page, such as clicking buttons, filling out forms, navigating through a complex site, infinite scroll, or when scrape fails to grab all the content you need.
-- Never use interact for web searches - use `search` instead.
-
-**Avoid redundant fetches:**
-
-- `search --scrape` already fetches full page content. Don't re-scrape those URLs.
-- Check `.firecrawl/` for existing data before fetching again.
-
-## When to Load References
-
-- **Searching the web or finding sources first** -> [firecrawl-search](../firecrawl-search/SKILL.md)
-- **Scraping a known URL** -> [firecrawl-scrape](../firecrawl-scrape/SKILL.md)
-- **Finding URLs on a known site** -> [firecrawl-map](../firecrawl-map/SKILL.md)
-- **Bulk extraction from a docs section or site** -> [firecrawl-crawl](../firecrawl-crawl/SKILL.md)
-- **AI-powered structured extraction from complex sites** -> [firecrawl-agent](../firecrawl-agent/SKILL.md)
-- **Clicks, forms, login, pagination, or post-scrape browser actions** -> [firecrawl-interact](../firecrawl-interact/SKILL.md)
-- **Downloading a site to local files** -> [firecrawl-download](../firecrawl-download/SKILL.md)
-- **Parsing a local file (PDF, DOCX, XLSX, HTML, etc.)** -> [firecrawl-parse](../firecrawl-parse/SKILL.md)
-- **Install, auth, or setup problems** -> [rules/install.md](rules/install.md)
-- **Output handling and safe file-reading patterns** -> [rules/security.md](rules/security.md)
-- **Integrating Firecrawl into an app, adding `FIRECRAWL_API_KEY` to `.env`, or choosing endpoint usage in product code** -> use the `firecrawl-build` skills (already installed alongside this CLI skill)
-
-## Output & Organization
-
-Unless the user specifies to return in context, write results to `.firecrawl/` with `-o`. Add `.firecrawl/` to `.gitignore`. Always quote URLs - shell interprets `?` and `&` as special characters.
-
-```bash
-firecrawl search "react hooks" -o .firecrawl/search-react-hooks.json --json
-firecrawl scrape "<url>" -o .firecrawl/page.md
-```
-
-Naming conventions:
-
-```
-.firecrawl/search-{query}.json
-.firecrawl/search-{query}-scraped.json
-.firecrawl/{site}-{path}.md
-```
-
-Never read entire output files at once. Use `grep`, `head`, or incremental reads:
-
-```bash
-wc -l .firecrawl/file.md && head -50 .firecrawl/file.md
-grep -n "keyword" .firecrawl/file.md
-```
-
-Single format outputs raw content. Multiple formats (e.g., `--format markdown,links`) output JSON.
-
-## Working with Results
-
-These patterns are useful when working with file-based output (`-o` flag) for complex tasks:
-
-```bash
-# Extract URLs from search
-jq -r '.data.web[].url' .firecrawl/search.json
-
-# Get titles and URLs
-jq -r '.data.web[] | "\(.title): \(.url)"' .firecrawl/search.json
-```
-
-## Parallelization
-
-Run independent operations in parallel. Check `firecrawl --status` for concurrency limit:
-
-```bash
-firecrawl scrape "<url-1>" -o .firecrawl/1.md &
-firecrawl scrape "<url-2>" -o .firecrawl/2.md &
-firecrawl scrape "<url-3>" -o .firecrawl/3.md &
-wait
-```
-
-For interact, scrape multiple pages and interact with each independently using their scrape IDs.
-
-## Credit Usage
-
-```bash
-firecrawl credit-usage
-firecrawl credit-usage --json --pretty -o .firecrawl/credits.json
-```