dallay · yacosta738 · May 13, 2026
diff --git a/.agents/journal/scribe-journal.md b/.agents/journal/scribe-journal.md
@@ -113,3 +113,14 @@ All three identified issues have been fixed:
 - Improved `cron_runs` and `cron_update` parameter documentation in `automation.md` (en/es).
 **Validation:** Results of `make docs-check` and `make docs-build` passed (84 pages built).
 **Notes:** Maintaining bilingual parity between root (English) and `es/` directory.
+
+## 2026-05-13 - Tool Documentation Audit & Plan Mode Synchronization - Complete
+
+**Verification:** Cross-referenced tool implementations in `clients/agent-runtime/src/tools/` and `clients/agent-runtime/src/peripherals/` with existing documentation. Verified Plan Mode safety list in `security/policy.rs`.
+**Changes:**
+- Added `pdf_inspect` documentation to `media.md` and `es/media.md` (Read-Only, 50MB limit, requires `pdf-inspect` feature).
+- Updated `index.mdx` and `es/index.mdx` to include missing tools: `pdf_inspect`, `hardware_memory_map`, `hardware_capabilities`, `gpio_read`, and `memory_forget`.
+- Added Plan Mode safety indicators (✅ Safe for Plan Mode) to all 8 safe tools (`code_search`, `Glob`, `Grep`, `file_read`, `web_search_tool`, `WebFetch`, `image_info`, `memory_recall`) across English and Spanish files.
+- Synchronized `lastReviewed` date to 2026-05-13 for all touched files.
+**Validation:** Results of `make docs-web-check` and `make docs-web-build` pending pre-commit.
+**Notes:** 1:1 bilingual parity maintained. `HardwareMemoryMapTool` and `HardwareCapabilitiesTool` were identified as missing from the top-level index despite being implemented.
@@ -3,7 +3,7 @@ title: Core Tools
 description: Reference for system command execution and filesystem tools in Corvus.
 owner: team-runtime
 status: canonical
-lastReviewed: 2026-05-06
+lastReviewed: 2026-05-13
 appliesTo: main
 docType: reference
 ---
@@ -15,6 +15,7 @@ Core tools provide the foundation for agent autonomy, allowing interaction with
 Searches workspace files for literal or regex matches and returns both human-readable output and structured match data.
 
 - **Security Tier:** Read-Only (Safe).
+- **Plan Mode:** ✅ Safe for Plan Mode (`--plan`).
 - **Execution:** Native runtime tool with optional literal-query index narrowing and mandatory live verification against current file contents.
 - **Current limitation:** Regex correctness is supported, but indexed candidate narrowing does **not** support regex in v1. Regex planning falls back with `query_regex_not_supported` to discovery plus live verification.
 - **Rollout evidence:** See the dedicated [`code_search` rollout page](code-search.md) for measured shell-vs-native results, fallback labels, and recommendation guidance.
@@ -44,6 +45,7 @@ See the dedicated [`code_search` page](code-search.md) for the full parameter co
 Claude-style parity tool for workspace-safe file pattern discovery.
 
 - **Security Tier:** Read-Only (Safe).
+- **Plan Mode:** ✅ Safe for Plan Mode (`--plan`).
 - **Execution:** Native runtime tool backed by workspace discovery metadata helpers.
 - **Contract:** Requires `pattern`; optionally scopes traversal with a workspace-relative `path`.
 - **Compatibility alias:** `glob`
@@ -56,6 +58,7 @@ Claude-style parity tool for workspace-safe file pattern discovery.
 Claude-style parity content search backed by the same Corvus search internals used by `code_search`.
 
 - **Security Tier:** Read-Only (Safe).
+- **Plan Mode:** ✅ Safe for Plan Mode (`--plan`).
 - **Execution:** Native runtime tool with deterministic workspace-relative outputs.
 - **Contract:** Supports `pattern`, optional `path`, optional `glob`, and `output_mode` values `content`, `files_with_matches`, or `count`.
 - **Compatibility alias:** `grep`
@@ -170,6 +173,7 @@ Executes an arbitrary shell command within the workspace directory.
 Reads the contents of a file within the workspace.
 
 - **Security Tier:** Read-Only (Safe).
+- **Plan Mode:** ✅ Safe for Plan Mode (`--plan`).
 - **Constraints:**
   - Path traversal (e.g., `../../etc/passwd`) is strictly blocked.
   - Symlinks that resolve outside the workspace boundary are rejected.

@@ -3,7 +3,7 @@ title: Tools Reference
 description: Overview of the Corvus Agent tool system, security model, and registration.
 owner: team-runtime
 status: canonical
-lastReviewed: 2026-05-06
+lastReviewed: 2026-05-13
 appliesTo: main
 docType: reference
 ---
@@ -20,18 +20,18 @@ Built-in tools are organized into six primary categories:
 
 - [**Core Tools**](core.md) — System command execution (`shell`), persistent tasks (`TaskCreate`), native workspace search (`code_search`, `Grep`), file discovery parity (`Glob`), and workspace filesystem access (`file_read`, `file_write`).
 - [**Web Tools**](web.md) — Web browsing (`browser`), search (`web_search_tool`), structured API calls (`http_request`), and read-only fetch parity (`WebFetch`).
-- [**Memory Tools**](memory.md) — Long-term persistence and retrieval of facts and preferences (`memory_store`, `memory_recall`).
+- [**Memory Tools**](memory.md) — Long-term persistence and retrieval of facts and preferences (`memory_store`, `memory_recall`, `memory_forget`).
 - [**Automation Tools**](automation.md) — Multi-agent delegation (`delegate`), managed app integrations (`composio`), Git repository management, scheduled tasks (Cron/Schedule), and notifications (`pushover`).
-- [**Media Tools**](media.md) — Vision-related capabilities including screen capture and image metadata extraction.
-- [**Hardware Tools**](hardware.md) — Board discovery (`hardware_board_info`), memory introspection (`hardware_memory_read`), and peripheral control (`gpio_write`, `arduino_upload`).
+- [**Media Tools**](media.md) — Vision-related capabilities including screen capture, image metadata extraction (`image_info`), and PDF inspection (`pdf_inspect`).
+- [**Hardware Tools**](hardware.md) — Board discovery (`hardware_board_info`), capabilities (`hardware_capabilities`), memory introspection (`hardware_memory_read`, `hardware_memory_map`), and peripheral control (`gpio_read`, `gpio_write`, `arduino_upload`).
 
 ## Security Model
 
 Every tool execution passes through the `SecurityPolicy` layer. Tools are classified into two operational tiers:
 
 ### Read-Only (Safe)
 These tools do not modify the system or external state. They are generally allowed even in low-autonomy modes.
-- *Examples:* `file_read`, `Glob`, `Grep`, `WebFetch`, `memory_recall`, `web_search_tool`, `image_info`, `hardware_board_info`.
+- *Examples:* `file_read`, `Glob`, `Grep`, `WebFetch`, `memory_recall`, `web_search_tool`, `image_info`, `pdf_inspect`, `hardware_board_info`, `hardware_memory_map`, `hardware_capabilities`, `gpio_read`.
 
 ## Claude-style parity mapping
 

@@ -3,13 +3,31 @@ title: Media Tools
 description: Reference for vision and image-related tools in Corvus.
 owner: team-runtime
 status: canonical
-lastReviewed: 2026-03-26
+lastReviewed: 2026-05-13
 appliesTo: main
 docType: reference
 ---
 
 Media tools provide the agent with visual capabilities, allowing it to "see" the host environment and process image files.
 
+## `pdf_inspect`
+
+Inspect, classify, and extract text from a PDF file.
+
+- **Security Tier:** Read-Only (Safe).
+- **Execution:** Native runtime tool (requires `pdf-inspect` feature).
+- **Functionality:** Detects whether the PDF is text-based, scanned, image-based, or mixed.
+- **Constraints:** Maximum file size: 50 MB. Timeout: 60 seconds.
+
+### Parameters
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `path` | `string` | **Required.** Relative path to the PDF file within the workspace. |
+| `extract_text` | `boolean` | Whether to extract and convert text to Markdown. Default: `true`. |
+
+---
+
 ## `screenshot`
 
 Captures a screenshot of the current screen or a specific region.
@@ -34,6 +52,7 @@ Captures a screenshot of the current screen or a specific region.
 Extracts metadata from an image file and optionally returns it as base64 for processing by multimodal models.
 
 - **Security Tier:** Read-Only (Safe).
+- **Plan Mode:** ✅ Safe for Plan Mode (`--plan`).
 - **Supported Formats:** PNG, JPEG, GIF, WEBP, BMP.
 - **Metadata Extracted:** Format, dimensions (width/height), and file size.
 - **Constraints:** Path-sandboxed to the workspace; maximum file size 5 MB.

@@ -3,7 +3,7 @@ title: Memory Tools
 description: Reference for long-term memory persistence and retrieval tools in Corvus.
 owner: team-runtime
 status: canonical
-lastReviewed: 2026-03-26
+lastReviewed: 2026-05-13
 appliesTo: main
 docType: reference
 ---
@@ -36,6 +36,7 @@ Stores a fact, preference, or note in long-term memory.
 Searches the memory system for relevant information based on a semantic query.
 
 - **Security Tier:** Read-Only (Safe).
+- **Plan Mode:** ✅ Safe for Plan Mode (`--plan`).
 - **Retrieval:** Uses hybrid search (Vector similarity + Keyword BM25) when supported by the backend.
 
 ### Parameters

@@ -3,7 +3,7 @@ title: Web Tools
 description: Reference for web browsing, search, and HTTP request tools in Corvus.
 owner: team-runtime
 status: canonical
-lastReviewed: 2026-05-06
+lastReviewed: 2026-05-13
 appliesTo: main
 docType: reference
 ---
@@ -17,6 +17,7 @@ Web tools enable agents to retrieve information from the internet and interact w
 Performs a web search to find current information, news, or research topics.
 
 - **Security Tier:** Read-Only (Safe).
+- **Plan Mode:** ✅ Safe for Plan Mode (`--plan`).
 - **Providers:**
   - `duckduckgo` (Default): Free, no API key required.
   - `brave`: Requires `web_search.brave_api_key`.
@@ -89,6 +90,7 @@ Performs structured HTTP requests (REST/JSON) to external APIs.
 Read-only fetch-and-extract parity tool for allowlisted web content.
 
 - **Security Tier:** Read-Only (Safe).
+- **Plan Mode:** ✅ Safe for Plan Mode (`--plan`).
 - **Execution:** Uses the same outbound URL-policy boundary as `http_request` for host allowlists, private-host blocking, and redirect-denial behavior.
 - **Compatibility alias:** `web_fetch`
 - **Native relationship:** Uses the same outbound URL policy boundary as `http_request`, but remains a read-only fetch-and-extract surface.

@@ -3,7 +3,7 @@ title: Herramientas Core
 description: Referencia para la ejecución de comandos del sistema y herramientas de archivos en Corvus.
 owner: team-runtime
 status: canonical
-lastReviewed: 2026-05-06
+lastReviewed: 2026-05-13
 appliesTo: main
 docType: reference
 ---
@@ -17,6 +17,7 @@ Las herramientas core proporcionan la base para la autonomía del agente, permit
 Busca coincidencias literales o regex dentro del workspace y devuelve tanto salida legible para humanos como datos estructurados de coincidencias.
 
 - **Nivel de Seguridad:** Solo Lectura (Segura).
+- **Modo Plan:** ✅ Seguro para el Modo Plan (`--plan`).
 - **Ejecución:** Herramienta nativa del runtime con reducción opcional de candidatos por índice para consultas literales y verificación obligatoria en vivo sobre el contenido actual.
 - **Limitación actual:** La corrección regex está soportada, pero la reducción de candidatos por índice **no** soporta regex en v1. El planning regex cae en fallback con `query_regex_not_supported` hacia discovery más live verification.
 - **Evidencia de rollout:** Consulta la página dedicada de [`code_search`](code-search.md) para resultados medidos shell-vs-native, etiquetas de fallback y guía de recomendación.
@@ -32,6 +33,7 @@ Consulta la página dedicada de [`code_search`](code-search.md) para el contrato
 Herramienta de paridad estilo Claude para descubrimiento seguro de archivos por patrón dentro del workspace.
 
 - **Nivel de Seguridad:** Solo Lectura (Segura).
+- **Modo Plan:** ✅ Seguro para el Modo Plan (`--plan`).
 - **Ejecución:** Herramienta nativa del runtime respaldada por helpers de metadata del discovery del workspace.
 - **Contrato:** Requiere `pattern`; opcionalmente limita el recorrido con `path` relativo al workspace.
 - **Nota de paridad:** `Glob` es el nombre canónico para superficies de paridad en este slice y se añade sin quitar los nombres nativos existentes.
@@ -43,6 +45,7 @@ Herramienta de paridad estilo Claude para descubrimiento seguro de archivos por
 Herramienta de paridad estilo Claude para búsqueda de contenido, respaldada por los mismos internals de búsqueda que usa `code_search`.
 
 - **Nivel de Seguridad:** Solo Lectura (Segura).
+- **Modo Plan:** ✅ Seguro para el Modo Plan (`--plan`).
 - **Ejecución:** Herramienta nativa con salidas determinísticas y rutas relativas al workspace.
 - **Contrato:** Soporta `pattern`, `path` opcional, `glob` opcional y `output_mode` con valores `content`, `files_with_matches` o `count`.
 - **Nota de paridad:** `Grep` es canónica para documentación de paridad, mientras `code_search` sigue disponible como contrato nativo retenido.
@@ -156,6 +159,7 @@ Ejecuta un comando de shell arbitrario dentro del directorio del workspace.
 Lee el contenido de un archivo dentro del workspace.
 
 - **Nivel de Seguridad:** Solo Lectura (Segura).
+- **Modo Plan:** ✅ Seguro para el Modo Plan (`--plan`).
 - **Restricciones:**
   - El salto de directorios (path traversal, ej. `../../etc/passwd`) está estrictamente bloqueado.
   - Se rechazan los symlinks que resuelven fuera de los límites del workspace.

@@ -3,7 +3,7 @@ title: Referencia de Herramientas
 description: Descripción general del sistema de herramientas de Corvus Agent, modelo de seguridad y registro.
 owner: team-runtime
 status: canonical
-lastReviewed: 2026-05-06
+lastReviewed: 2026-05-13
 appliesTo: main
 docType: reference
 ---
@@ -20,18 +20,18 @@ Las herramientas integradas se organizan en seis categorías principales:
 
 - [**Herramientas Core**](core.md) — Ejecución de comandos del sistema (`shell`), tareas persistentes (`TaskCreate`), búsqueda nativa en el workspace (`code_search`, `Grep`), descubrimiento de archivos con paridad (`Glob`) y acceso al sistema de archivos del workspace (`file_read`, `file_write`).
 - [**Herramientas Web**](web.md) — Navegación web (`browser`), búsqueda (`web_search_tool`), llamadas estructuradas a APIs (`http_request`) y fetch de solo lectura con paridad (`WebFetch`).
-- [**Herramientas de Memoria**](memory.md) — Persistencia a largo plazo y recuperación de hechos y preferencias (`memory_store`, `memory_recall`).
+- [**Herramientas de Memoria**](memory.md) — Persistencia a largo plazo y recuperación de hechos y preferencias (`memory_store`, `memory_recall`, `memory_forget`).
 - [**Herramientas de Automatización**](automation.md) — Delegación multi-agente (`delegate`), integraciones de aplicaciones gestionadas (`composio`), gestión de repositorios Git, tareas programadas (Cron/Schedule) y notificaciones (`pushover`).
-- [**Herramientas Multimedia**](media.md) — Capacidades relacionadas con la visión, incluyendo captura de pantalla y extracción de metadatos de imágenes.
-- [**Herramientas de Hardware**](hardware.md) — Descubrimiento de placas (`hardware_board_info`), introspección de memoria (`hardware_memory_read`) y control de periféricos (`gpio_write`, `arduino_upload`).
+- [**Herramientas Multimedia**](media.md) — Capacidades relacionadas con la visión, incluyendo captura de pantalla, extracción de metadatos de imágenes (`image_info`) e inspección de PDF (`pdf_inspect`).
+- [**Herramientas de Hardware**](hardware.md) — Descubrimiento de placas (`hardware_board_info`), capacidades (`hardware_capabilities`), introspección de memoria (`hardware_memory_read`, `hardware_memory_map`) y control de periféricos (`gpio_read`, `gpio_write`, `arduino_upload`).
 
 ## Modelo de Seguridad
 
 Cada ejecución de herramienta pasa por la capa de `SecurityPolicy`. Las herramientas se clasifican en dos niveles operativos:
 
 ### Solo Lectura (Seguras)
 Estas herramientas no modifican el sistema ni el estado externo. Generalmente están permitidas incluso en modos de baja autonomía.
-- *Ejemplos:* `file_read`, `Glob`, `Grep`, `WebFetch`, `memory_recall`, `web_search_tool`, `image_info`, `hardware_board_info`.
+- *Ejemplos:* `file_read`, `Glob`, `Grep`, `WebFetch`, `memory_recall`, `web_search_tool`, `image_info`, `pdf_inspect`, `hardware_board_info`, `hardware_memory_map`, `hardware_capabilities`, `gpio_read`.
 
 ## Mapeo de paridad estilo Claude
 

@@ -3,13 +3,31 @@ title: Herramientas Multimedia
 description: Referencia para herramientas de visión e imágenes en Corvus.
 owner: team-runtime
 status: canonical
-lastReviewed: 2026-03-26
+lastReviewed: 2026-05-13
 appliesTo: main
 docType: reference
 ---
 
 Las herramientas multimedia proporcionan al agente capacidades visuales, permitiéndole "ver" el entorno del host y procesar archivos de imagen.
 
+## `pdf_inspect`
+
+Inspecciona, clasifica y extrae texto de un archivo PDF.
+
+- **Nivel de Seguridad:** Solo Lectura (Segura).
+- **Ejecución:** Herramienta nativa del runtime (requiere la característica `pdf-inspect`).
+- **Funcionalidad:** Detecta si el PDF está basado en texto, escaneado, basado en imágenes o es mixto.
+- **Restricciones:** Tamaño máximo de archivo: 50 MB. Tiempo de espera: 60 segundos.
+
+### Parámetros
+
+| Parámetro | Tipo | Descripción |
+| :--- | :--- | :--- |
+| `path` | `string` | **Requerido.** Ruta relativa al archivo PDF dentro del workspace. |
+| `extract_text` | `boolean` | Si se debe extraer y convertir el texto a Markdown. Por defecto: `true`. |
+
+---
+
 ## `screenshot`
 
 Captura una imagen de la pantalla actual o de una región específica.
@@ -34,6 +52,7 @@ Captura una imagen de la pantalla actual o de una región específica.
 Extrae metadatos de un archivo de imagen y, opcionalmente, lo devuelve como base64 para su procesamiento por modelos multimodales.
 
 - **Nivel de Seguridad:** Solo Lectura (Segura).
+- **Modo Plan:** ✅ Seguro para el Modo Plan (`--plan`).
 - **Formatos Soportados:** PNG, JPEG, GIF, WEBP, BMP.
 - **Metadatos Extraídos:** Formato, dimensiones (ancho/alto) y tamaño del archivo.
 - **Restricciones:** Sandboxing de ruta al workspace; tamaño máximo de archivo 5 MB.

@@ -3,7 +3,7 @@ title: Herramientas de Memoria
 description: Referencia para herramientas de persistencia y recuperación de memoria a largo plazo en Corvus.
 owner: team-runtime
 status: canonical
-lastReviewed: 2026-03-26
+lastReviewed: 2026-05-13
 appliesTo: main
 docType: reference
 ---
@@ -36,6 +36,7 @@ Almacena un hecho, preferencia o nota en la memoria a largo plazo.
 Busca en el sistema de memoria información relevante basada en una consulta semántica.
 
 - **Nivel de Seguridad:** Solo Lectura (Segura).
+- **Modo Plan:** ✅ Seguro para el Modo Plan (`--plan`).
 - **Recuperación:** Utiliza búsqueda híbrida (similitud vectorial + BM25 por palabras clave) cuando el backend lo soporta.
 
 ### Parámetros

@@ -3,7 +3,7 @@ title: Herramientas Web
 description: Referencia para herramientas de navegación web, búsqueda y peticiones HTTP en Corvus.
 owner: team-runtime
 status: canonical
-lastReviewed: 2026-05-06
+lastReviewed: 2026-05-13
 appliesTo: main
 docType: reference
 ---
@@ -17,6 +17,7 @@ Las herramientas web permiten a los agentes recuperar información de Internet e
 Realiza una búsqueda web para encontrar información actual, noticias o temas de investigación.
 
 - **Nivel de Seguridad:** Solo Lectura (Segura).
+- **Modo Plan:** ✅ Seguro para el Modo Plan (`--plan`).
 - **Proveedores:**
   - `duckduckgo` (Por defecto): Gratuito, no requiere clave de API.
   - `brave`: Requiere `web_search.brave_api_key`.
@@ -89,6 +90,7 @@ Realiza peticiones HTTP estructuradas (REST/JSON) a APIs externas.
 Herramienta de paridad de solo lectura para fetch-and-extract de contenido web permitido.
 
 - **Nivel de Seguridad:** Solo Lectura (Segura).
+- **Modo Plan:** ✅ Seguro para el Modo Plan (`--plan`).
 - **Ejecución:** Usa el mismo límite de política URL saliente que `http_request` para allowlists de hosts, bloqueo de hosts privados y denegación de redirecciones.
 - **Alias de compatibilidad:** `web_fetch`
 - **Relación nativa:** Utiliza el mismo límite de política de URL de salida que `http_request`, pero sigue siendo una superficie de fetch-and-extract de solo lectura.