Merge pull request #493 from webbrain-one/docs/simplify-readmes

docs: simplify the three READMEs and split reference material into docs

Author: esokullu

README.fr.md

@@ -0,0 +1,156 @@
+# Agent Tools
+
+WebBrain separates **model tier** from **conversation mode**.
+
+- **Tier** (`compact`, `mid`, `full`) is a per-provider setting. It controls how
+  many normal browser-agent tools a model sees.
+- **Mode** (`ask`, `act`, `dev`) is chosen per conversation. It controls what
+  kind of task the user is allowing.
+
+| Mode | What it allows |
+|---|---|
+| **Ask** | Read-only. No clicking, typing, navigating, or downloading. |
+| **Act** | The selected tier's normal browser tools. |
+| **Dev** | Requires a Mid or Full provider. Adds a source/style/debug appendix, including deeper DOM/frame inspection for Mid-tier Dev runs. Compact Dev is blocked before an LLM request is sent. |
+
+| Tier | Intended model class | Normal tool surface |
+|---|---|---|
+| `compact` | very small local models | Shortest prompt and a small normal Act tool set. No scheduling, iframe, download-resource, or advanced DOM/UI fallbacks. |
+| `mid` | capable local models | Common task tools: downloads, scheduling, iframe tools, form verification. No Full-only advanced fallbacks. |
+| `full` | frontier/cloud or large local models | Everything, including hover, drag-drop, frames, and shadow DOM. |
+
+Tier defaults and resolution rules are documented in
+[providers and models](providers-and-models.md#prompttool-tiers-and-modes).
+
+## Tool matrix
+
+Legend: **Yes** = available · **-** = not available · **C** = Chrome only ·
+**Dev** = Dev-mode add-on (Mid/Full providers; not Compact).
+
+| Tool | Ask | Compact | Mid | Full | Dev |
+|------|:---:|:-------:|:---:|:----:|:---:|
+| `get_accessibility_tree` | Yes | Yes | Yes | Yes | - |
+| `read_page` | Yes | Yes | Yes | Yes | - |
+| `read_pdf` | Yes | No | Yes | Yes | - |
+| `list_webmcp_tools` | C | No | C | C | - |
+| `execute_webmcp_tool` | No | No | C | C | - |
+| `read_page_source` | No | No | No | No | Yes |
+| `get_window_info` | Yes | Yes | Yes | Yes | - |
+| `get_interactive_elements` | Yes | No | Yes | Yes | - |
+| `scroll` | Yes | Yes | Yes | Yes | - |
+| `extract_data` | Yes | Yes | Yes | Yes | - |
+| `inspect_element_styles` | No | No | No | No | Yes |
+| `wait_for_stable` | Yes | No | Yes | Yes | - |
+| `get_selection` | Yes | Yes | Yes | Yes | - |
+| `done` | Yes | Yes | Yes | Yes | - |
+| `clarify` | No | Yes | Yes | Yes | - |
+| `fetch_url` | Yes | Yes | Yes | Yes | - |
+| `research_url` | Yes | No | Yes | Yes | - |
+| `list_downloads` | Yes | No | Yes | Yes | - |
+| `click_ax` | No | Yes | Yes | Yes | - |
+| `type_ax` | No | Yes | Yes | Yes | - |
+| `set_field` | No | Yes | Yes | Yes | - |
+| `resize_window` | No | No | No | Yes | - |
+| `click` | No | Yes | Yes | Yes | - |
+| `type_text` | No | Yes | Yes | Yes | - |
+| `press_keys` | No | Yes | Yes | Yes | - |
+| `navigate` | No | Yes | Yes | Yes | - |
+| `wait_for_element` | No | Yes | Yes | Yes | - |
+| `new_tab` | No | Yes | Yes | Yes | - |
+| `scratchpad_write` | No | Yes | Yes | Yes | - |
+| `progress_update` | No | Yes | Yes | Yes | - |
+| `progress_read` | No | Yes | Yes | Yes | - |
+| `download_social_media` | No | No | Yes | Yes | - |
+| `solve_captcha` | No | No | Yes | Yes | - |
+| `go_back` | No | No | Yes | Yes | - |
+| `go_forward` | No | No | Yes | Yes | - |
+| `schedule_resume` | No | No | Yes | Yes | - |
+| `schedule_task` | No | No | Yes | Yes | - |
+| `iframe_read` | No | No | Yes | Yes | - |
+| `iframe_click` | No | No | Yes | Yes | - |
+| `iframe_type` | No | No | Yes | Yes | - |
+| `read_downloaded_file` | No | No | Yes | Yes | - |
+| `download_files` | No | No | Yes | Yes | - |
+| `download_resource_from_page` | No | No | Yes | Yes | - |
+| `upload_file` | No | No | C | C | - |
+| `verify_form` | No | No | Yes | Yes | - |
+| `hover` | No | No | No | Yes | - |
+| `drag_drop` | No | No | No | Yes | - |
+| `get_shadow_dom` | No | No | No | Yes | Yes |
+| `shadow_dom_query` | No | No | No | C | C |
+| `get_frames` | No | No | No | Yes | Yes |
+| `inject_css` | No | No | No | No | C |
+| `remove_injected_css` | No | No | No | No | C |
+| `patch_element` | No | No | No | No | C |
+| `revert_patch` | No | No | No | No | C |
+| `execute_js` | No | No | No | No | Yes |
+| `read_console` | No | No | No | No | C |
+| `inspect_network_requests` | No | No | No | No | C |
+| `inspect_event_listeners` | No | No | No | No | C |
+| `highlight_element` | No | No | No | No | C |
+
+> **Shadow DOM note:** The accessibility tree only traverses light DOM. On Web
+> Component-heavy pages (Stripe, Salesforce, Shopify), use
+> `get_interactive_elements` first; in Full Act or Dev mode, use
+> `get_shadow_dom` / `shadow_dom_query` for targeted reads.
+
+## Tools that are not in the table
+
+**Skill tools.** Loaded skills can append tool schemas for the current run. The
+bundled FreeSkillz.xyz skill, for example, can expose `read_youtube_transcript`
+plus `resolve_public_media` / `download_public_media`. These are not hard-coded:
+before the skill is loaded (or if it is removed), the tools are absent. Ask mode
+still filters out mutating and download tools even when their owning skill is
+loaded. See [skills](skills.md).
+
+**WebMCP (experimental, opt-in).** The `list_webmcp_tools` /
+`execute_webmcp_tool` rows apply only when **Experimental WebMCP** is enabled
+under Settings → General → Advanced. The setting is off by default; while off,
+the tools and their prompt guidance are omitted from model requests. WebMCP
+annotations such as `readOnly` are page-authored hints, not a security boundary.
+Every invocation requires Act or Dev, fresh per-call confirmation, and the
+normal capability × registration-frame-origin permission. WebMCP currently
+requires a supporting Chrome build/page configuration; Firefox does not expose
+these tools.
+
+## Dev-mode page editing and diagnostics
+
+Dev tools are only exposed in Dev mode, and Dev mode is blocked for
+Compact-tier providers. Chrome's reversible editing tools return patch IDs:
+`inject_css` pairs with `remove_injected_css`, and `patch_element` pairs with
+`revert_patch`.
+
+- **`inject_css` / `remove_injected_css`** apply and undo temporary CSS by
+  `patchId`. Each patch is unique and bound to the exact page document, and its
+  metadata is kept in session storage so a service-worker restart does not lose
+  the undo handle. Navigating invalidates the old handle instead of letting it
+  affect a replacement page.
+- **`patch_element` / `revert_patch`** make structured inline-style, class, and
+  attribute changes with exact before/after values. Browser-equivalent style and
+  HTML attribute names are canonicalized before the undo record is created,
+  contradictory set/remove operations are rejected, and executable URL
+  attributes reject `javascript:` values (including form `action`).
+  `highlight_element` provides a temporary pointer-transparent target overlay;
+  because it inserts live DOM, it uses the temporary Dev-patch permission.
+- **`execute_js`** runs an async JavaScript function body in the page main
+  world. Chrome uses CDP `Runtime.evaluate` with a 15-second execution limit;
+  Firefox uses its MV2 content-script evaluator. The tool is host-permission
+  gated and receives a fresh submit confirmation.
+- **`read_console`, `inspect_network_requests`, `inspect_event_listeners`**
+  provide bounded diagnostics on Chrome. Capture starts before either streaming
+  or non-streaming Dev runs and stops when the tab leaves Dev mode or its
+  conversation is cleared; leaving Dev drains every tab with active capture even
+  if the panel switched tabs, removes handlers and buffers, and disables the
+  matching CDP domains. Listener inspection briefly adds and restores an
+  internal target attribute, follows open-shadow hosts when collecting
+  ancestors, and therefore uses the same host permission as temporary Dev
+  patches. Network headers and bodies are omitted by default, sensitive header
+  names (including common API/subscription-key variants) are redacted before
+  buffering, and page-derived diagnostic output is treated as untrusted content.
+
+## See also
+
+- [Adding a tool](adding-a-tool.md) — the checklist for new or changed tools
+- [Accessibility tree and refs](accessibility-tree-and-refs.md)
+- [Security model](security-model.md) and
+  [prompt-injection defense](prompt-injection-defense.md)

README.md

@@ -0,0 +1,166 @@
+# Outils de l'agent
+
+WebBrain sépare le **niveau du modèle** du **mode de conversation**.
+
+- **Niveau** (`compact`, `mid`, `full`) est un réglage par fournisseur. Il
+  contrôle le nombre d'outils navigateur normaux que le modèle voit.
+- **Mode** (`ask`, `act`, `dev`) est choisi par conversation. Il contrôle le type
+  de tâche que l'utilisateur autorise.
+
+| Mode | Ce qu'il autorise |
+|---|---|
+| **Ask** | Lecture seule. Pas de clic, de saisie, de navigation ni de téléchargement. |
+| **Act** | Les outils navigateur normaux du niveau sélectionné. |
+| **Dev** | Exige un fournisseur Mid ou Full. Ajoute une annexe source/style/debug, y compris une inspection DOM/frame plus profonde pour les exécutions Dev en Mid. Le mode Dev en Compact est bloqué avant l'envoi d'une requête au LLM. |
+
+| Niveau | Classe de modèle visée | Surface d'outils normaux |
+|---|---|---|
+| `compact` | très petits modèles locaux | Prompt le plus court et petit ensemble d'outils Act normaux. Pas de planification, d'iframe, de téléchargement de ressource ni de repli DOM/UI avancé. |
+| `mid` | modèles locaux capables | Outils de tâche courants : téléchargements, planification, outils iframe, vérification de formulaires. Sans les replis avancés réservés à Full. |
+| `full` | modèles frontière/cloud ou grands modèles locaux | Tout, y compris hover, drag-drop, frames et shadow DOM. |
+
+Les valeurs par défaut et les règles de résolution des niveaux sont documentées
+dans [fournisseurs et modèles](providers-and-models.md#niveaux-de-promptoutils-et-modes).
+
+## Matrice des outils
+
+Légende : **Oui** = disponible · **-** = indisponible · **C** = Chrome
+uniquement · **Dev** = module Dev (fournisseurs Mid/Full ; pas Compact).
+
+| Outil | Ask | Compact | Mid | Full | Dev |
+|-------|:---:|:-------:|:---:|:----:|:---:|
+| `get_accessibility_tree` | Oui | Oui | Oui | Oui | - |
+| `read_page` | Oui | Oui | Oui | Oui | - |
+| `read_pdf` | Oui | Non | Oui | Oui | - |
+| `list_webmcp_tools` | C | Non | C | C | - |
+| `execute_webmcp_tool` | Non | Non | C | C | - |
+| `read_page_source` | Non | Non | Non | Non | Oui |
+| `get_window_info` | Oui | Oui | Oui | Oui | - |
+| `get_interactive_elements` | Oui | Non | Oui | Oui | - |
+| `scroll` | Oui | Oui | Oui | Oui | - |
+| `extract_data` | Oui | Oui | Oui | Oui | - |
+| `inspect_element_styles` | Non | Non | Non | Non | Oui |
+| `wait_for_stable` | Oui | Non | Oui | Oui | - |
+| `get_selection` | Oui | Oui | Oui | Oui | - |
+| `done` | Oui | Oui | Oui | Oui | - |
+| `clarify` | Non | Oui | Oui | Oui | - |
+| `fetch_url` | Oui | Oui | Oui | Oui | - |
+| `research_url` | Oui | Non | Oui | Oui | - |
+| `list_downloads` | Oui | Non | Oui | Oui | - |
+| `click_ax` | Non | Oui | Oui | Oui | - |
+| `type_ax` | Non | Oui | Oui | Oui | - |
+| `set_field` | Non | Oui | Oui | Oui | - |
+| `resize_window` | Non | Non | Non | Oui | - |
+| `click` | Non | Oui | Oui | Oui | - |
+| `type_text` | Non | Oui | Oui | Oui | - |
+| `press_keys` | Non | Oui | Oui | Oui | - |
+| `navigate` | Non | Oui | Oui | Oui | - |
+| `wait_for_element` | Non | Oui | Oui | Oui | - |
+| `new_tab` | Non | Oui | Oui | Oui | - |
+| `scratchpad_write` | Non | Oui | Oui | Oui | - |
+| `progress_update` | Non | Oui | Oui | Oui | - |
+| `progress_read` | Non | Oui | Oui | Oui | - |
+| `download_social_media` | Non | Non | Oui | Oui | - |
+| `solve_captcha` | Non | Non | Oui | Oui | - |
+| `go_back` | Non | Non | Oui | Oui | - |
+| `go_forward` | Non | Non | Oui | Oui | - |
+| `schedule_resume` | Non | Non | Oui | Oui | - |
+| `schedule_task` | Non | Non | Oui | Oui | - |
+| `iframe_read` | Non | Non | Oui | Oui | - |
+| `iframe_click` | Non | Non | Oui | Oui | - |
+| `iframe_type` | Non | Non | Oui | Oui | - |
+| `read_downloaded_file` | Non | Non | Oui | Oui | - |
+| `download_files` | Non | Non | Oui | Oui | - |
+| `download_resource_from_page` | Non | Non | Oui | Oui | - |
+| `upload_file` | Non | Non | C | C | - |
+| `verify_form` | Non | Non | Oui | Oui | - |
+| `hover` | Non | Non | Non | Oui | - |
+| `drag_drop` | Non | Non | Non | Oui | - |
+| `get_shadow_dom` | Non | Non | Non | Oui | Oui |
+| `shadow_dom_query` | Non | Non | Non | C | C |
+| `get_frames` | Non | Non | Non | Oui | Oui |
+| `inject_css` | Non | Non | Non | Non | C |
+| `remove_injected_css` | Non | Non | Non | Non | C |
+| `patch_element` | Non | Non | Non | Non | C |
+| `revert_patch` | Non | Non | Non | Non | C |
+| `execute_js` | Non | Non | Non | Non | Oui |
+| `read_console` | Non | Non | Non | Non | C |
+| `inspect_network_requests` | Non | Non | Non | Non | C |
+| `inspect_event_listeners` | Non | Non | Non | Non | C |
+| `highlight_element` | Non | Non | Non | Non | C |
+
+> **Note Shadow DOM :** L'arbre d'accessibilité ne traverse que le light DOM.
+> Sur les pages riches en Web Components (Stripe, Salesforce, Shopify), utilisez
+> d'abord `get_interactive_elements` ; en Full Act ou Dev, utilisez
+> `get_shadow_dom` / `shadow_dom_query` pour des lectures ciblées.
+
+## Outils absents du tableau
+
+**Outils de compétence.** Les compétences chargées peuvent ajouter des schémas
+d'outils pour l'exécution en cours. La compétence FreeSkillz.xyz intégrée, par
+exemple, peut exposer `read_youtube_transcript` ainsi que
+`resolve_public_media` / `download_public_media`. Ces outils ne sont pas codés en
+dur : avant le chargement de la compétence (ou si elle est retirée), ils sont
+absents. Le mode Ask filtre toujours les outils de mutation et de téléchargement,
+même lorsque la compétence propriétaire est chargée. Voir
+[compétences](skills.md).
+
+**WebMCP (expérimental, sur activation).** Les lignes `list_webmcp_tools` /
+`execute_webmcp_tool` ne s'appliquent que lorsque **WebMCP expérimental** est
+activé dans Paramètres → Général → Avancé. Le réglage est désactivé par défaut ;
+tant qu'il l'est, les outils et leurs consignes de prompt sont omis des requêtes
+au modèle. Les annotations WebMCP telles que `readOnly` sont des indications
+écrites par la page, pas une frontière de sécurité. Chaque invocation exige Act
+ou Dev, une confirmation fraîche à chaque appel, et la permission normale
+capacité × origine de la frame d'enregistrement. WebMCP nécessite actuellement
+un build/une configuration de page Chrome compatible ; Firefox n'expose pas ces
+outils.
+
+## Édition et diagnostics en mode Dev
+
+Les outils Dev ne sont exposés qu'en mode Dev, et le mode Dev est bloqué pour les
+fournisseurs de niveau Compact. Les outils d'édition réversible de Chrome
+renvoient des patch IDs : `inject_css` va avec `remove_injected_css`, et
+`patch_element` avec `revert_patch`.
+
+- **`inject_css` / `remove_injected_css`** appliquent et annulent du CSS
+  temporaire par `patchId`. Chaque patch est unique et lié au document exact de
+  la page, et ses métadonnées sont conservées en session storage pour qu'un
+  redémarrage du service worker ne perde pas la poignée d'annulation. La
+  navigation invalide l'ancienne poignée au lieu de la laisser affecter une page
+  de remplacement.
+- **`patch_element` / `revert_patch`** effectuent des modifications structurées
+  de styles inline, de classes et d'attributs avec des valeurs avant/après
+  exactes. Les noms de styles et d'attributs HTML équivalents sont canonicalisés
+  avant la création de l'enregistrement d'annulation, les opérations
+  set/remove contradictoires sont rejetées, et les attributs d'URL exécutables
+  rejettent les valeurs `javascript:` (y compris `action` de formulaire).
+  `highlight_element` fournit une surcouche de cible temporaire transparente aux
+  pointeurs ; comme elle insère du DOM vivant, elle utilise la permission de
+  patch Dev temporaire.
+- **`execute_js`** exécute un corps de fonction JavaScript asynchrone dans le
+  monde principal de la page. Chrome utilise CDP `Runtime.evaluate` avec une
+  limite d'exécution de 15 secondes ; Firefox utilise son évaluateur de script de
+  contenu MV2. L'outil est soumis à une permission d'hôte et reçoit une
+  confirmation de soumission fraîche.
+- **`read_console`, `inspect_network_requests`, `inspect_event_listeners`**
+  fournissent des diagnostics bornés sur Chrome. La capture démarre avant les
+  exécutions Dev streamées ou non, et s'arrête quand l'onglet quitte le mode Dev
+  ou que sa conversation est effacée ; quitter Dev vide tous les onglets ayant
+  une capture active même si le panneau a changé d'onglet, retire les
+  gestionnaires et les tampons, et désactive les domaines CDP correspondants.
+  L'inspection des écouteurs ajoute et restaure brièvement un attribut de cible
+  interne, suit les hôtes shadow ouverts lors de la collecte des ancêtres, et
+  utilise donc la même permission d'hôte que les patchs Dev temporaires. Les
+  en-têtes et corps réseau sont omis par défaut, les noms d'en-têtes sensibles
+  (y compris les variantes courantes de clés d'API/d'abonnement) sont caviardés
+  avant la mise en tampon, et la sortie de diagnostic issue de la page est
+  traitée comme du contenu non fiable.
+
+## Voir aussi
+
+- [Ajouter un outil](adding-a-tool.md) — la checklist pour les outils nouveaux ou
+  modifiés
+- [Arbre d'accessibilité et refs](accessibility-tree-and-refs.md)
+- [Modèle de sécurité](security-model.md) et
+  [défense contre l'injection de prompt](prompt-injection-defense.md)

README.zh-CN.md

@@ -126,6 +126,31 @@ serveur local a été démarré avec authentification :
 
 Les sept ont `supportsVision: true` par défaut car la plupart des modèles chargés localement en 2026 sont multimodaux.
 
+#### Relais de lancement Ollama (préversion)
+
+<p align="center">
+  <img src="../../web/assets/webbrain-ollama-heart.png" alt="WebBrain adore le relais de lancement Ollama" width="720">
+</p>
+
+WebBrain prend aujourd'hui en charge Ollama via le fournisseur local compatible
+OpenAI. Un nouveau relais `ollama launch webbrain --model <model>` peut aussi
+configurer WebBrain automatiquement, mais il n'est pas encore intégré à Ollama
+en amont. Pour l'instant, essayez-le depuis la [branche
+`codex/ollama-webbrain-launch-handoff` de
+`esokullu/ollama`](https://github.com/esokullu/ollama/tree/codex/ollama-webbrain-launch-handoff) ;
+nous espérons qu'Ollama l'intégrera en amont.
+
+```bash
+git clone https://github.com/esokullu/ollama.git
+cd ollama
+git switch codex/ollama-webbrain-launch-handoff
+cmake -S . -B build -G Ninja -DOLLAMA_MLX_BACKENDS=
+cmake --build build --parallel 8
+
+OLLAMA_ORIGINS="chrome-extension://*,moz-extension://*" ./ollama serve
+./ollama launch webbrain --model <model>
+```
+
 **Fenêtre de contexte.** Chargez les modèles locaux avec **au moins une fenêtre de contexte de 16k tokens** pour des exécutions d'agent fiables — c'est le minimum utilisable. 8k peut fonctionner avec le niveau Compact sélectionné ; 4k est trop petit pour contenir le prompt système + les schémas d'outils. L'agent lit la fenêtre depuis `provider.contextWindow` (`providers/base.js`) pour piloter l'auto-compaction ; quand une configuration de fournisseur ne définit pas `contextWindow`, les fournisseurs locaux utilisent par défaut une valeur prudente de **16k** (cloud/routeur par défaut à 128k). **Tester la connexion** / **Charger les modèles** détectent pour **llama.cpp**, **Ollama** et **LM Studio** quand c'est rapporté (llama.cpp `GET /props` `n_ctx`, Ollama `GET /api/ps` puis `/api/show` `num_ctx`, LM Studio `/api/v0/models` `loaded_context_length`). La détection rafraîchit le 16k par défaut ; elle réduit une surcharge manuelle plus grande seulement depuis le contexte live/runtime (pas depuis Ollama `/api/show` seul). Jan / vLLM / SGLang / LocalAI ne détectent pas encore. Vous pouvez toujours définir `config.contextWindow` explicitement, et le serveur de modèle doit effectivement être démarré avec cette taille de contexte (par exemple `llama-server -c 16384`).
 
 ### Niveaux de prompt/outils et modes