@jamolpe88/dsh-free-websearch 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 jamolpe88
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.es.md

@@ -0,0 +1,276 @@
+# dsh-free-websearch
+
+[![npm](https://img.shields.io/npm/v/@jamolpe88/dsh-free-websearch?style=flat-square&logo=npm&label=npm)](https://www.npmjs.com/package/@jamolpe88/dsh-free-websearch)
+[![npm downloads](https://img.shields.io/npm/dm/@jamolpe88/dsh-free-websearch?style=flat-square&logo=npm&label=downloads)](https://www.npmjs.com/package/@jamolpe88/dsh-free-websearch)
+[![GitHub release](https://img.shields.io/github/v/release/JaMoLpE88/dsh-free-websearch?style=flat-square&logo=github&label=release)](https://github.com/JaMoLpE88/dsh-free-websearch/releases)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+[![DSH](https://img.shields.io/badge/DSH-%3E%3D0.2.1--rc.3-4B8BBE?style=flat-square)](#compatibilidad)
+[![node](https://img.shields.io/badge/node-%3E%3D20.3-5FA04E?style=flat-square&logo=node.js&logoColor=white)](#compatibilidad)
+[![sin clave](https://img.shields.io/badge/API%20key-ninguna-3FB950?style=flat-square)](#por-qué-no-hay-ajustes)
+[![dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/jamolpe88/dsh-free-websearch)
+
+**Búsqueda web y lectura de páginas gratis para DeepSeek Harness.** Cinco motores sin
+clave detrás de las propias herramientas `web_search` y `web_fetch` del harness, con
+failover automático y con los proveedores de pago de DeepSeek apagados. Instálalo y la
+plataforma de DeepSeek queda fuera del circuito, uses el modelo que uses.
+
+Cero configuración. Sin registro, sin clave, sin página de ajustes y sin respaldo de pago:
+si todos los carriles gratuitos fallan, la búsqueda devuelve un informe en vez de gastar
+un crédito.
+
+**English** → [README.md](README.md)
+
+![Cómo se colocan los carriles gratuitos detrás de las herramientas del harness](assets/how-it-works.png)
+
+*Las herramientas no cambian. La costura `ctx.web` elige un proveedor por llamada, este
+bundle fija el suyo y detrás responden cinco carriles sin clave. El mismo parche desactiva
+los proveedores de búsqueda y lectura de DeepSeek, así que no hay camino de vuelta a la API
+de pago por accidente.*
+
+![Failover entre carriles](assets/failover.png)
+
+*Una búsqueda, un carril. La primera respuesta corta la cadena, así que las demás cuotas
+quedan intactas; un carril bloqueado entra en cuarentena y responde el siguiente.*
+
+![Capacidad de los carriles gratuitos](assets/coverage.png)
+
+*Dos carriles no tienen tope publicado, y por eso son el suelo de la cadena y no la cabeza.
+Las cuotas anónimas se comparten por IP, así que los ilimitados cubren una red ocupada.*
+
+![La tarjeta de citas que ve el modelo](assets/tool-card.png)
+
+*La misma tarjeta de citas que pinta el proveedor de pago: títulos, URLs y fragmentos,
+sin una sola clave de API.*
+
+## Qué hace
+
+- Sirve **`web_search`** a través de cinco motores gratuitos: Keenable, Firecrawl keyless, Bing, DuckDuckGo y You.com.
+- Sirve **`web_fetch`** en local primero (el proveedor HTTP del propio harness) y escala al scrape keyless de Firecrawl sólo cuando la página es un muro, viene vacía o es un shell de JavaScript.
+- **Desactiva los proveedores de pago de DeepSeek** (`deepseek-official`, `deepseek-search-api`, `deepseek-fetch-api`), de modo que ningún ajuste, cadena de respaldo ni interruptor de la UI pueda alcanzarlos.
+- Salta al siguiente carril en orden y se detiene en el primero que responde: una búsqueda gasta la cuota de un carril, no de cinco.
+- Cachea resultados **5 minutos** (50 entradas), así que repetir una pregunta no cuesta nada.
+- Pone en cuarentena un carril tras un muro (5 min) o una cuota mensual agotada (el resto del proceso) en lugar de martillearlo.
+- Nombra todos los carriles que probó cuando se rinde, y avisa de que no se envió nada a una API de pago.
+- Devuelve el comportamiento original de DeepSeek al desactivar o desinstalar el bundle.
+
+## Qué no hace
+
+- No añade herramientas. Ni `x_search`, ni `read_page`, ni `multi_search`, ni pipeline de investigación.
+- No lee credenciales. Ni las de DeepSeek ni las de nadie: el plugin no importa el servicio de credenciales, así que no puede gastar una clave guardada.
+- No llama a `api.deepseek.com` bajo ninguna circunstancia.
+- No raspa cookies, no guarda historial y no envía telemetría.
+- No renderiza JavaScript en local. Escala, y sólo para destinos públicos.
+
+## Por qué no hay ajustes
+
+No hay nada que decidir. El orden de carriles es el mismo para todos, todos son sin clave y
+las cuotas son anónimas. Una página de ajustes sólo te pediría elegir un carril cuya cuota
+no puedes ver y cuyo fallo la cadena ya resuelve.
+
+La única decisión que importa —"¿esto me puede costar dinero?"— no es una preferencia: la
+responde el parche del bundle. Los proveedores de pago están desactivados, así que la
+respuesta es no.
+
+## Qué sustituye
+
+| Ruta de pago del harness | Proveedor | Cómo queda |
+|---|---|---|
+| Búsqueda por Messages (`web_search_20250305`) | `deepseek-official` | Desactivada. `web_search` usa la cadena gratuita |
+| Search API (`/v1/tools/search`) | `deepseek-search-api` | Desactivada, mismo sustituto |
+| Fetch API (`/v1/tools/fetch`) | `deepseek-fetch-api` | Desactivada. `web_fetch` usa local → scrape keyless |
+| Lectura local | `http` | Se conserva, y se delega en ella en vez de reimplementarla |
+
+Todo lo demás que hace el harness —títulos de sesión, compactación, subagentes, workflows—
+va por **tu modelo**, no por un endpoint de DeepSeek. No hay un tercer sitio que arreglar.
+
+## Los cinco carriles
+
+Se prueban en este orden. Un carril se salta mientras está en cuarentena.
+
+| Carril | Endpoint | Cuota anónima | Papel |
+|---|---|---|---|
+| `keenable` | `api.keenable.ai/v1/search/public` | 1.000 peticiones/hora por IP | Absorbe casi todo: JSON, ~0,4 s |
+| `firecrawl` | `api.firecrawl.dev/v2/search` | 1.000 créditos/mes | Mejores fragmentos; escaso, por eso va segundo |
+| `bing` | `www.bing.com/search?format=rss` | Sin tope publicado | El suelo, ~0,3 s, URLs directas |
+| `ddg` | `html.duckduckgo.com/html/` | Sin tope publicado | El otro suelo |
+| `you` | `api.you.com/v1/agents/search` | 100 búsquedas/día por IP | Último recurso |
+
+Presupuestos: **7 s por carril**, **30 s por búsqueda**, cadena de cinco y caché de 5 minutos.
+Sin reintentos dentro de un carril: un fallo pasa al siguiente, que es más barato que esperar
+a un servidor que ya ha dicho que no.
+
+## Requisitos
+
+- **DSH Desktop** `>= 0.2.1-rc.3`, perfil `desktop` (probado en `0.2.1-rc.3`, Windows 11).
+- Salida HTTPS. Nada más.
+- Node 22+ (DSH trae el suyo; el paquete sólo necesita 20.3).
+
+Sin clave de DeepSeek. Sin proveedor configurado. Sin cuenta.
+
+## Instalar
+
+Desde la app de escritorio: **Plugins → Añadir plugin**, y escribe `@jamolpe88/dsh-free-websearch`.
+
+Desde npm:
+
+```bash
+dsh plugin --profile desktop add @jamolpe88/dsh-free-websearch
+```
+
+El perfil `web` instala el mismo paquete:
+
+```bash
+dsh plugin --profile web add @jamolpe88/dsh-free-websearch
+```
+
+Desde el repositorio:
+
+```bash
+dsh plugin --profile desktop add github:JaMoLpE88/dsh-free-websearch
+```
+
+Desde una copia local, mientras desarrollas:
+
+```bash
+dsh plugin --profile desktop add link:C:\ruta\a\dsh-free-websearch
+```
+
+Refresca la ventana de DSH. En un perfil vivo el bundle se aplica sin reiniciar; la página
+de Plugins lista **Free Web Search** y la tarjeta oficial **Web search** deja de aparecer,
+porque sus dos proveedores ya no están montados.
+
+## Uso
+
+1. Pregunta lo que necesite web, como siempre. El modelo llama a `web_search`; las fuentes vuelven con su tarjeta de citas.
+2. Pega un enlace o pregunta por una página. `web_fetch` la lee en local y sólo escala si la página necesita un navegador.
+3. Nada más. No hay comando, ni píldora, ni panel.
+
+Si una búsqueda falla, el error nombra los carriles probados y el motivo, por ejemplo
+`keenable: HTTP 429; bing: no results`. Reintenta, o comprueba si una VPN está reescribiendo
+tu IP de salida.
+
+## Cómo funciona
+
+El plugin registra dos proveedores en la costura que ya existe, y el parche del bundle los
+selecciona:
+
+```js
+ctx.web.registerSearchProvider({ id: 'freeweb', available: () => true, search })
+ctx.web.registerFetchProvider({ id: 'freeweb-fetch', available: () => true, fetch })
+```
+
+```yaml
+- id: web
+  config:
+    searchProvider: freeweb
+    fetchProvider: freeweb-fetch
+- id: web-search-deepseek
+  disabled: true
+- id: web-deepseek-api
+  disabled: true
+```
+
+- **La selección va fijada de forma declarativa.** Un parche reemplaza toda la config de la fila objetivo, así que se reescriben las dos claves de la costura. Desinstalar el bundle retira juntos el pin y las desactivaciones; el harness vuelve a `deepseek-official` / `http`.
+- **Un respaldo en runtime cubre la instalación manual.** Si el parche del bundle no llegó a aplicarse (dependencia suelta, perfil antiguo), el plugin escribe la misma selección con `settings.mutate` cuando el servicio de ajustes está montado, y sólo si el valor actual es el de fábrica. Nunca pisa una elección deliberada, y al descargarse escribe de vuelta los ids originales.
+- **`available()` es barato y offline.** El veredicto honesto pertenece a la ejecución, cuyo error lleva cada intento; responder `false` por adelantado convertiría un problema de red pasajero en un error de configuración de la costura.
+- **La cadena de fetch reutiliza el harness.** `freeweb-fetch` delega primero en el proveedor `http` registrado, así que la validación de URL, el anclaje de direcciones, las reglas de redirección y la conversión HTML→markdown siguen siendo del harness. Sólo cuando ese resultado es un muro, está vacío o es un shell de JavaScript, el plugin llama al scrape keyless de Firecrawl.
+- **La divulgación se comprueba antes de ocurrir.** Todas las direcciones resueltas del destino tienen que ser públicas antes de enviar la URL a Firecrawl. `localhost`, rangos privados, CGNAT y link-local no salen de la máquina, y un host que no resuelve tampoco se divulga.
+
+## Verificarlo
+
+```bash
+npm test        # 16 pruebas: parsers, failover, cuarentena, caché, guarda SSRF, takeover
+npm run probe   # comprobación real de los cinco endpoints y del escalado de fetch
+```
+
+El probe imprime el estado HTTP de cada carril, lanza búsquedas reales por la cadena con su
+latencia y sus fuentes, y demuestra que un destino privado bloqueado nunca escala. Usa la red;
+las pruebas no.
+
+## Desinstalar y revertir
+
+Quita el bundle (Plugins → Remove, o `dsh plugin --profile desktop remove @jamolpe88/dsh-free-websearch`).
+La capa de parche desaparece con él:
+
+- `web` vuelve a `searchProvider: deepseek-official` / `fetchProvider: http`,
+- los dos proveedores de DeepSeek se reactivan,
+- no quedan ficheros del plugin, ni ajustes propios, ni estado.
+
+Desactivar el bundle tiene el mismo efecto. Si se instaló como dependencia suelta, el plugin
+además escribe los ids originales al descargarse.
+
+## Compatibilidad
+
+| | |
+|---|---|
+| DSH | `>= 0.2.1-rc.3` (la única versión probada por el autor) |
+| Node | `>= 20.3` (el paquete); DSH trae 22+ |
+| SO | Windows 11 (probado); el código es Node puro, macOS y Linux sin probar |
+| Perfil | `desktop` (probado); `web` arranca y busca por la misma costura |
+| Costura | proveedores de search + fetch de `ctx.web` |
+| Catálogo | [listado en dsh-plugin.org](https://dsh-plugin.org/plugins/jamolpe88/dsh-free-websearch) |
+
+Estado de validación: **probado en Windows 11 con DSH Desktop 0.2.1-rc.3** (2026-10-28). El
+bundle se aplicó en caliente, los dos proveedores de pago salieron de la composición,
+`web_search` devolvió ocho fuentes citadas desde la cadena gratuita, `web_fetch` devolvió el
+texto de la página y un destino privado bloqueado fue rechazado sin petición a la nube.
+
+Sin validar: macOS, Linux, otras versiones de DSH y el perfil `web`.
+
+## Límites
+
+- **Los carriles son cortesía de terceros.** Las cuotas anónimas pueden cambiar, encogerse o empezar a pedir CAPTCHA sin avisar. Por eso hay cinco y por eso hay failover.
+- **Una VPN puede romper los tramos keyless.** Firecrawl filtra su tramo anónimo por IP de salida y puede responder 403; Keenable y Bing mantienen la búsqueda viva.
+- **Bing a veces sirve un SERP vacío a IPs de datacenter o proxy.** DuckDuckGo es el segundo carril ilimitado para ese caso.
+- **Sin búsqueda de X/Twitter.** No hay camino gratis que no exija una cuenta de pago, así que el plugin no lo finge.
+- **Sin render de JavaScript propio.** El escalado a un scraper en la nube es la única vía tipo navegador, y sólo para páginas públicas.
+- **Las cuotas anónimas se comparten por IP.** Una red de oficina ocupada ve los topes keyless antes que una conexión doméstica.
+
+## Privacidad
+
+- La consulta va al carril que responde, y a cada carril probado antes que él. Nada más.
+- La URL de una página sale de la máquina sólo por el escalado de `web_fetch`, y sólo después de comprobar que todas las direcciones resueltas son públicas.
+- Sin cookies, sin clave, sin cuenta, sin almacenamiento local, sin telemetría.
+- El plugin nunca lee el almacén de credenciales, así que ninguna clave de API puede filtrarse por él.
+
+Política corta en [SECURITY.md](SECURITY.md).
+
+## Problemas
+
+**Las búsquedas fallan con "every free search lane failed".**
+El mensaje lista cada carril y su error. `HTTP 429` en keenable significa que la reserva
+horaria compartida se agotó; `bot wall` en ddg significa que pide CAPTCHA. Reintenta en unos
+minutos o desactiva la VPN.
+
+**`web_fetch` devuelve una página con muy poco texto.**
+La lectura local funcionó pero el sitio se renderiza con JavaScript y el escalado no encontró
+nada mejor. No está roto: es lo que sirve el sitio.
+
+**La tarjeta oficial "Web search" ha desaparecido de Plugins.**
+Es lo esperado: sólo existe mientras `web-search-deepseek` sirve su namespace, y este bundle
+lo desactiva. Desinstálalo para recuperarla.
+
+**Una página se rechaza como destino privado.**
+La guarda del escalado se negó a enviarla a la nube. La lectura local sí funcionó; sólo se
+bloquea el camino a la nube.
+
+## Desarrollo
+
+```bash
+npm test        # node --test
+npm run probe   # comprobación real de carriles
+python tools/make-assets.py   # regenera las imágenes de assets/
+```
+
+El paquete es JavaScript plano sin build y sin dependencias de ejecución. Las pruebas
+sustituyen `fetch`, así que corren offline y nunca tocan un endpoint real.
+
+## Marcas de terceros
+
+DeepSeek, Bing, DuckDuckGo, Firecrawl, Keenable y You.com son marcas de sus respectivos
+propietarios. Se nombran sólo para describir a qué servicio habla cada carril; no se incluye
+ningún logotipo y no se implica afiliación.
+
+## Licencia
+
+[MIT](LICENSE) © 2026 JaMoLpE88

package/README.md

@@ -1,3 +1,238 @@
-# Temporary Holding Version
+# dsh-free-websearch
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/@jamolpe88/dsh-free-websearch?style=flat-square&logo=npm&label=npm)](https://www.npmjs.com/package/@jamolpe88/dsh-free-websearch)
+[![npm downloads](https://img.shields.io/npm/dm/@jamolpe88/dsh-free-websearch?style=flat-square&logo=npm&label=downloads)](https://www.npmjs.com/package/@jamolpe88/dsh-free-websearch)
+[![GitHub release](https://img.shields.io/github/v/release/JaMoLpE88/dsh-free-websearch?style=flat-square&logo=github&label=release)](https://github.com/JaMoLpE88/dsh-free-websearch/releases)
+[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)
+[![DSH](https://img.shields.io/badge/DSH-%3E%3D0.2.1--rc.3-4B8BBE?style=flat-square)](#compatibility)
+[![node](https://img.shields.io/badge/node-%3E%3D20.3-5FA04E?style=flat-square&logo=node.js&logoColor=white)](#compatibility)
+[![no key](https://img.shields.io/badge/API%20key-none-3FB950?style=flat-square)](#why-there-is-no-settings)
+[![dsh-plugin.org](https://dsh-plugin.org/badges/listed.svg)](https://dsh-plugin.org/plugins/jamolpe88/dsh-free-websearch)
+
+**Free web search and page fetch for the DeepSeek Harness.** Five keyless engines sit behind the harness's own `web_search` and `web_fetch`, with automatic failover, and the paid DeepSeek search and fetch providers are switched off. Install it and the DeepSeek platform is out of the loop — whatever model you are running.
+
+Zero configuration. No signup, no API key, no settings page, no paid fallback: if every free lane is down the search fails with a report instead of spending a credit.
+
+**Español** → [README.es.md](README.es.md)
+
+![How the free lanes sit behind the harness tools](assets/how-it-works.png)
+
+*The tools do not change. The `ctx.web` seam picks a provider per call, this bundle pins its own, and five keyless lanes answer behind it. The DeepSeek search and fetch providers are disabled by the same patch, so there is no path back to the paid API by accident.*
+
+![Failover between lanes](assets/failover.png)
+
+*One search, one lane. The first answer stops the chain, so the other quotas stay unspent; a walled lane cools down and the next one takes over.*
+
+![Capacity of the free lanes](assets/coverage.png)
+
+*Two lanes have no published cap, which is why they are the floor of the chain rather than the head. The anonymous pools are shared per IP, so the unlimited ones catch a busy network.*
+
+![The citation card the model sees](assets/tool-card.png)
+
+*The same citation card the paid provider renders: titles, URLs and snippets, produced without an API key.*
+
+## What it does
+
+- Serves the harness's **`web_search`** through five free engines: Keenable, Firecrawl keyless, Bing, DuckDuckGo and You.com.
+- Serves **`web_fetch`** locally first (the harness's own HTTP provider) and escalates to Firecrawl's keyless scrape only when the page is a wall, empty, or a JavaScript shell.
+- **Disables DeepSeek's paid search and fetch providers** (`deepseek-official`, `deepseek-search-api`, `deepseek-fetch-api`), so no setting, fallback chain or UI switch can reach them.
+- Fails over in order and stops at the first lane that answers: one search spends one lane's quota, not five.
+- Caches results for **5 minutes** (50 entries), so a repeated question costs nothing.
+- Cools a lane down after a wall (5 min) or a spent monthly pool (for the rest of the process) instead of hammering it.
+- Names every lane it tried when it gives up, and says that nothing was sent to a paid API.
+- Restores the shipped DeepSeek behaviour when the bundle is disabled or removed.
+
+## What it does not do
+
+- It does not add tools. No `x_search`, no `read_page`, no `multi_search`, no research pipeline.
+- It does not read credentials. Not DeepSeek's, not anyone's: the plugin never imports the credential service, so it cannot spend a key that is stored.
+- It does not call `api.deepseek.com` under any circumstance.
+- It does not scrape cookies, keep history, or send telemetry.
+- It does not render JavaScript locally. It escalates instead, and only for public targets.
+
+## Why there is no settings
+
+There is nothing to decide. The lane order is the same for everyone, every lane is keyless, and the quotas are anonymous. A settings page would only ask you to pick a lane whose quota you cannot see and whose failure the chain already handles.
+
+The one knob that matters — "may this cost me money?" — is not a preference. It is answered by the bundle patch: the paid providers are disabled, so the answer is no.
+
+## What it replaces
+
+| Paid route in the harness | Provider id | How it ends up |
+|---|---|---|
+| Search through Messages (`web_search_20250305`) | `deepseek-official` | Disabled. `web_search` runs the free chain |
+| Search API (`/v1/tools/search`) | `deepseek-search-api` | Disabled, same replacement |
+| Fetch API (`/v1/tools/fetch`) | `deepseek-fetch-api` | Disabled. `web_fetch` runs local → keyless scrape |
+| Local fetch | `http` | Kept, and delegated to rather than reimplemented |
+
+Everything else the harness does — session titles, compaction, subagents, workflows — runs through **your model**, not through a DeepSeek endpoint. There is no third place to fix.
+
+## The five lanes
+
+Tried in this order. A lane is skipped while it is cooling down.
+
+| Lane | Endpoint | Anonymous quota | Role |
+|---|---|---|---|
+| `keenable` | `api.keenable.ai/v1/search/public` | 1,000 requests/hour per IP | Absorbs most traffic: JSON, ~0.4 s |
+| `firecrawl` | `api.firecrawl.dev/v2/search` | 1,000 credits/month | Best snippets; scarce, so second |
+| `bing` | `www.bing.com/search?format=rss` | No published cap | The floor, ~0.3 s, direct URLs |
+| `ddg` | `html.duckduckgo.com/html/` | No published cap | The other floor |
+| `you` | `api.you.com/v1/agents/search` | 100 searches/day per IP | Last resort |
+
+Budgets: **7 s per lane**, **30 s per search**, five-lane chain, 5-minute result cache. No retries inside a lane: a failure moves on immediately, which is cheaper than waiting for a server that already said no.
+
+## Requirements
+
+- **DSH Desktop** `>= 0.2.1-rc.3`, profile `desktop` (tested on `0.2.1-rc.3`, Windows 11).
+- Outbound HTTPS. That is all.
+- Node 22+ (DSH ships its own runtime; the package itself only needs 20.3).
+
+No DeepSeek API key. No provider configured. No account.
+
+## Install
+
+From the desktop app: **Plugins → Add plugin**, then `@jamolpe88/dsh-free-websearch`.
+
+From npm:
+
+```bash
+dsh plugin --profile desktop add @jamolpe88/dsh-free-websearch
+```
+
+The `web` profile takes the same package:
+
+```bash
+dsh plugin --profile web add @jamolpe88/dsh-free-websearch
+```
+
+From the repository:
+
+```bash
+dsh plugin --profile desktop add github:JaMoLpE88/dsh-free-websearch
+```
+
+From a local checkout, while developing:
+
+```bash
+dsh plugin --profile desktop add link:C:\path\to\dsh-free-websearch
+```
+
+Refresh the DSH window. In a live profile the bundle applies without a restart; the Plugins page lists **Free Web Search** and the official **Web search** card stops appearing, because its two providers are no longer mounted.
+
+## Usage
+
+1. Ask anything that needs the web, as usual. The model calls `web_search`; sources come back with a citation card.
+2. Paste a link or ask about a page. `web_fetch` reads it locally and escalates only if the page needs a browser.
+3. Nothing else. There is no command, no pill, no panel.
+
+If a search fails, the error names the lanes that were tried and why, for example `keenable: HTTP 429; bing: no results`. Retry, or check whether a VPN is rewriting your egress IP.
+
+## How it works
+
+The plugin registers two providers into the harness's existing seam, then the bundle patch selects them:
+
+```js
+ctx.web.registerSearchProvider({ id: 'freeweb', available: () => true, search })
+ctx.web.registerFetchProvider({ id: 'freeweb-fetch', available: () => true, fetch })
+```
+
+```yaml
+- id: web
+  config:
+    searchProvider: freeweb
+    fetchProvider: freeweb-fetch
+- id: web-search-deepseek
+  disabled: true
+- id: web-deepseek-api
+  disabled: true
+```
+
+- **Selection is pinned declaratively.** A patch row replaces the targeted row's whole config, so both seam keys are restated. Uninstalling the bundle removes the pin and the disables together; the harness returns to `deepseek-official` / `http`.
+- **A runtime fallback covers manual installs.** If the bundle patch did not land (a plain dependency, or an older profile), the plugin writes the same selection through `settings.mutate` once the settings service is mounted, and only when the current value is the shipped default. It never overrides a deliberate choice, and it writes the shipped ids back when it unloads.
+- **`available()` is cheap and offline.** The honest verdict belongs to execution, whose error carries every attempt; answering `false` up front would turn a transient network problem into a seam-misconfiguration error.
+- **The fetch chain reuses the harness.** `freeweb-fetch` delegates to the registered `http` provider first, so URL validation, address pinning, redirect rules and HTML→markdown conversion stay the harness's. Only when that result is a wall, empty, or a JavaScript shell does the plugin call Firecrawl's keyless scrape.
+- **Disclosure is checked before it happens.** The target's every resolved address must be public before the URL is sent to Firecrawl. `localhost`, private ranges, CGNAT and link-local addresses never leave the machine, and an unresolvable host is not disclosed either.
+
+## Verifying it
+
+```bash
+npm test        # 16 tests: parsers, failover, cooldown, cache, SSRF guard, takeover
+npm run probe   # live check of the five endpoints and the fetch escalation
+```
+
+The probe prints each lane's HTTP status, runs real searches through the chain with their latency and sources, and proves that a blocked private target is never escalated. It uses the network; the tests do not.
+
+## Uninstall and revert
+
+Remove the bundle (Plugins → Remove, or `dsh plugin --profile desktop remove @jamolpe88/dsh-free-websearch`). The patch layer disappears with it:
+
+- `web` returns to the shipped `searchProvider: deepseek-official` / `fetchProvider: http`,
+- both DeepSeek providers re-enable,
+- no plugin files, no settings of its own, no state left behind.
+
+Disabling the bundle has the same effect. If it was installed as a plain dependency, the plugin also writes the shipped ids back when it unloads.
+
+## Compatibility
+
+| | |
+|---|---|
+| DSH | `>= 0.2.1-rc.3` (the only version tested by the author) |
+| Node | `>= 20.3` (the package); DSH ships 22+ |
+| OS | Windows 11 (tested); the code is plain Node, macOS and Linux untested |
+| Profile | `desktop` (tested); `web` boots and searches through the same seam |
+| Seam | `ctx.web` search + fetch providers |
+| Catalog | [listed on dsh-plugin.org](https://dsh-plugin.org/plugins/jamolpe88/dsh-free-websearch) |
+
+Validation status: **tested on Windows 11 with DSH Desktop 0.2.1-rc.3** (2026-10-28). The bundle applied live, both paid providers left the composition, `web_search` returned eight cited sources from the free chain, `web_fetch` returned page text, and a blocked private target was refused without a cloud request.
+
+Not validated: macOS, Linux, other DSH versions, and the `web` profile.
+
+## Limits
+
+- **The lanes are third-party goodwill.** Anonymous quotas can change, shrink or start asking for a CAPTCHA without notice. That is why there are five and why the chain fails over.
+- **A VPN can break the keyless tiers.** Firecrawl gates its anonymous tier by egress IP and may answer 403; Keenable and Bing keep the search working.
+- **Bing occasionally serves an empty SERP to data-centre or proxy IPs.** DuckDuckGo is the second unlimited lane for that case.
+- **No X/Twitter search.** There is no free path that does not require a paid account, so the plugin does not pretend otherwise.
+- **No JavaScript rendering of its own.** Escalation to a cloud scraper is the only browser-like path, and only for public pages.
+- **Anonymous pools are shared per IP.** A busy office network sees the keyless ceilings sooner than a home connection.
+
+## Privacy
+
+- The query goes to the lane that answers, and to each lane tried before it. Nothing else is sent.
+- A page URL leaves the machine only through `web_fetch`'s escalation, only after every resolved address is proven public.
+- No cookies, no key, no account, no local storage, no telemetry.
+- The plugin never reads the credential store, so no API key can leak through it.
+
+See [SECURITY.md](SECURITY.md) for the short policy.
+
+## Troubleshooting
+
+**Searches fail with "every free search lane failed".**
+The message lists each lane and its error. `HTTP 429` on keenable means the shared hourly pool is spent; `bot wall` on ddg means it wants a CAPTCHA. Retry after a few minutes, or disable the VPN.
+
+**`web_fetch` returns a page with very little text.**
+The local fetch worked but the site renders with JavaScript and the escalation found nothing better. Nothing is wrong: that is what the site serves.
+
+**The official "Web search" card disappeared from Plugins.**
+Expected: it exists only while `web-search-deepseek` serves its namespace, and this bundle disables it. Uninstall the bundle to bring it back.
+
+**A page is refused as a private target.**
+The escalation guard declined to send it to the cloud. Local fetch still worked; only the cloud path is blocked.
+
+## Development
+
+```bash
+npm test        # node --test
+npm run probe   # live lane check
+python tools/make-assets.py   # regenerate the artwork in assets/
+```
+
+The package is plain JavaScript with no build step and no runtime dependencies. The tests stub `fetch`, so they run offline and never touch a real endpoint.
+
+## Third-party marks
+
+DeepSeek, Bing, DuckDuckGo, Firecrawl, Keenable and You.com are trademarks of their respective owners. They are named only to describe which service a lane talks to; no logo is bundled and no affiliation is implied.
+
+## License
+
+[MIT](LICENSE) © 2026 JaMoLpE88

package/SECURITY.md

@@ -0,0 +1,36 @@
+# Security policy
+
+## Reporting
+
+Open a private advisory on GitHub, or an issue if the report contains no sensitive detail.
+Please include the DSH version, the plugin version, and the lane involved.
+
+## What this plugin handles
+
+- **No credentials.** The plugin never imports `ctx.credentials` and never reads
+  `DEEPSEEK_API_KEY`, `TAVILY_API_KEY`, `EXA_API_KEY`, `FIRECRAWL_API_KEY` or any other key.
+  It cannot spend one, and it cannot leak one.
+- **No stored state.** No config file, no cache on disk, no history, no cookies, no local
+  storage. The result cache lives in memory and dies with the process.
+- **Queries leave the machine** to the search lane that answers, and to each lane tried
+  before it: `api.keenable.ai`, `api.firecrawl.dev`, `www.bing.com`, `html.duckduckgo.com`,
+  `api.you.com`. All over HTTPS.
+- **Page URLs** are read locally first. A URL reaches `api.firecrawl.dev` only when the local
+  read produced a wall, an empty body or a JavaScript shell, **and** every resolved address
+  of the host is public. Loopback, private (10/8, 172.16/12, 192.168/16), CGNAT (100.64/10),
+  link-local (169.254/16, fe80::/10), unique-local (fc00::/7) and `localhost`-style hostnames
+  are never disclosed. An unresolvable host is not disclosed either.
+- **Responses are treated as untrusted.** Search results are data: they are normalized to
+  URL, title, snippet and date, stripped of markup, and capped in length. The plugin does not
+  execute, evaluate or fetch anything a result suggests.
+
+## What it deliberately does not do
+
+- No background requests, no telemetry, no analytics, no update check.
+- No remote code, no dynamic import of a URL, no shell.
+- No writes outside the harness's own settings document when the bundle patch did not apply.
+
+## Supply chain
+
+The package has **zero runtime dependencies**. `lib/` is plain JavaScript with no build step,
+so what the registry serves is exactly what runs.

package/cordis.patch.yml

@@ -0,0 +1,27 @@
+# dsh-free-websearch — bundle layer for DeepSeek Harness.
+#
+# Three declarative facts, so uninstalling restores the shipped behaviour
+# exactly: this whole file lives in the package, so removing the bundle
+# removes the takeover, the pin, and the disables in one step.
+#
+# 1. Point the web seam at this plugin's providers.
+#    A patch row replaces the targeted row's whole config, so every key the
+#    base row owns is restated here (it owns only these two).
+# 2. Close the paid door. Without these rows the harness can silently fall
+#    back to DeepSeek's paid search/fetch when a free lane is down, and the
+#    "Use the new Web Search API" switch can flip the seam back at any time.
+# 3. Mount the plugin.
+- id: web
+  config:
+    searchProvider: freeweb
+    fetchProvider: freeweb-fetch
+
+- id: web-search-deepseek
+  disabled: true
+
+- id: web-deepseek-api
+  disabled: true
+
+- insert:
+    - id: freeweb
+      name: '@jamolpe88/dsh-free-websearch'