docs: add Firecrawl integration design spec

AGENTS.md

@@ -0,0 +1,25 @@
+# AGENTS.md
+
+## Project overview
+- `pi-web-search` is a Pi extension package that exposes `web_search` and `web_fetch`.
+- Entry point: `index.ts`.
+- Runtime/provider selection: `src/runtime.ts`.
+- Config/schema: `src/config.ts`, `src/schema.ts`.
+- Provider adapters and provider-specific tests: `src/providers/`.
+- Tool adapters: `src/tools/`.
+- Interactive config command: `src/commands/web-search-config.ts`.
+
+## Commands
+- Install deps: `npm install`
+- Run tests: `npm test`
+
+## Working conventions
+- Keep the public tool contract stable unless the current design/spec explicitly changes it.
+- Add provider-specific request controls in nested blocks (for example `tavily`, `firecrawl`) instead of new top-level params.
+- Normalize provider responses through `src/providers/types.ts` before formatting/output.
+- Prefer focused tests next to the changed modules.
+- Update `README.md`, config examples, and command flows when provider/config schema changes.
+
+## Docs
+- Design specs live under `docs/superpowers/specs/`.
+- Use `YYYY-MM-DD-<topic>-design.md` naming for design specs.