theus-cli-darwin-x64 0.2.84

package/vendor/theus-arsenal/skills/patrones-tinystruct/SKILL.md

@@ -0,0 +1,281 @@
+---
+name: patrones-tinystruct
+description: Guía experta para desarrollar con el framework Java tinystruct. Úsala al trabajar
+  en el código de tinystruct o en cualquier proyecto construido sobre él — creación de clases
+  Application, rutas mapeadas con @Action, tests unitarios, ActionRegistry, manejo dual
+  HTTP/CLI, el servidor HTTP integrado, el sistema de eventos, JSON con Builder/Builders,
+  persistencia en base de datos con AbstractData, generación de POJOs, Server-Sent Events
+  (SSE), subida de archivos y peticiones HTTP salientes.
+---
+
+# Patrones de desarrollo con tinystruct
+
+Patrones de arquitectura e implementación para construir módulos con el framework Java **tinystruct**: un framework ligero y de alto rendimiento que trata la CLI y HTTP como ciudadanos de primera clase, sin requerir método `main()` y con configuración mínima.
+
+## Principio central
+
+**CLI y HTTP son ciudadanos iguales.** Todo método anotado con `@Action` debería, idealmente, poder ejecutarse tanto desde una terminal como desde un navegador web sin modificaciones. Esta capacidad de "modo dual" es la filosofía de diseño central de tinystruct.
+
+## Cuándo activarla
+
+### Cuándo usarla
+
+- Al crear nuevos módulos `Application` extendiendo `AbstractApplication`.
+- Al definir rutas y acciones de línea de comandos con `@Action`.
+- Al manejar estado por petición mediante `Context`.
+- Al serializar JSON con los componentes nativos `Builder` y `Builders`.
+- Al trabajar con persistencia en base de datos mediante POJOs `AbstractData`.
+- Al generar POJOs desde tablas de base de datos con el comando `generate`.
+- Al implementar Server-Sent Events (SSE) para push en tiempo real.
+- Al manejar subidas de archivos mediante datos multipart.
+- Al hacer peticiones HTTP salientes con `URLRequest` y `HTTPHandler`.
+- Al configurar conexiones de base de datos o ajustes del sistema en `application.properties`.
+- Al depurar conflictos de enrutamiento (Actions) o el parseo de argumentos de la CLI.
+
+## Cómo funciona
+
+El framework tinystruct trata cualquier método anotado con `@Action` como un endpoint enrutable tanto para entornos de terminal como web. Las aplicaciones se crean extendiendo `AbstractApplication`, que proporciona los hooks de ciclo de vida principales como `init()` y acceso al `Context` de la petición.
+
+El enrutamiento lo gestiona el `ActionRegistry`, que mapea automáticamente los segmentos de ruta a los argumentos del método e inyecta dependencias. Para servicios que solo devuelven datos, deben usarse los componentes nativos `Builder` y `Builders` para la serialización JSON, manteniendo así una huella de cero dependencias. La capa de base de datos usa POJOs `AbstractData` emparejados con archivos XML de mapeo para operaciones CRUD sin librerías ORM externas.
+
+## Ejemplos
+
+### Aplicación básica (MyService)
+```java
+public class MyService extends AbstractApplication {
+    @Override
+    public void init() {
+        this.setTemplateRequired(false); // Desactiva la búsqueda de .view en apps de datos/API
+    }
+
+    @Override public String version() { return "1.0.0"; }
+
+    @Action("greet")
+    public String greet() {
+        return "¡Hola desde tinystruct!";
+    }
+
+    // Parámetro de ruta: GET /?q=greet/James  O  bin/dispatcher greet/James
+    @Action("greet")
+    public String greet(String name) {
+        return "Hola, " + name + "!";
+    }
+}
+```
+
+### Desambiguación por modo HTTP (login)
+```java
+@Action(value = "login", mode = Mode.HTTP_POST)
+public String doLogin(Request<?, ?> request) throws ApplicationException {
+    request.getSession().setAttribute("userId", "42");
+    return "Sesión iniciada";
+}
+```
+
+### Manejo nativo de datos JSON (Builder + Builders)
+```java
+import org.tinystruct.data.component.Builder;
+import org.tinystruct.data.component.Builders;
+
+@Action("api/data")
+public String getData() throws ApplicationException {
+    Builders dataList = new Builders();
+    Builder item = new Builder();
+    item.put("id", 1);
+    item.put("name", "James");
+    dataList.add(item);
+
+    Builder response = new Builder();
+    response.put("status", "success");
+    response.put("data", dataList);
+    return response.toString(); // {"status":"success","data":[{"id":1,"name":"James"}]}
+}
+```
+
+### SSE (Server-Sent Events)
+```java
+import org.tinystruct.http.SSEPushManager;
+
+@Action("sse/connect")
+public String connect() {
+    return "{\"type\":\"connect\",\"message\":\"Conectado a SSE\"}";
+}
+
+// Enviar push a un cliente específico
+String sessionId = getContext().getId();
+Builder msg = new Builder();
+msg.put("text", "¡Hola, usuario!");
+SSEPushManager.getInstance().push(sessionId, msg);
+
+// Difundir a todos
+SSEPushManager.getInstance().broadcast(msg);
+```
+
+### Subida de archivos
+```java
+import org.tinystruct.data.FileEntity;
+
+@Action(value = "upload", mode = Mode.HTTP_POST)
+public String upload(Request<?, ?> request) throws ApplicationException {
+    List<FileEntity> files = request.getAttachments();
+    if (files != null) {
+        for (FileEntity file : files) {
+            System.out.println("Subido: " + file.getFilename());
+        }
+    }
+    return "Subida OK";
+}
+```
+
+## Integración de servidor MCP y herramientas
+
+tinystruct incorpora soporte nativo para el Model Context Protocol (MCP) a partir de la versión **`1.7.26`** del SDK.
+Las APIs de MCP (p. ej., `org.tinystruct.mcp.MCPTool`, `org.tinystruct.mcp.MCPServer`, `org.tinystruct.mcp.MCPException`) están incluidas directamente en la dependencia principal:
+```xml
+<dependency>
+    <groupId>org.tinystruct</groupId>
+    <artifactId>tinystruct</artifactId>
+    <version>1.7.26</version>
+</dependency>
+```
+
+> **ADVERTENCIA DE SEGURIDAD (inyección de prompts):**
+> Los valores devueltos por las herramientas se inyectan directamente en la ventana de contexto del modelo. **DEBES** validar y sanear todos los argumentos suministrados por el invocador antes de incluirlos en la cadena de retorno de la herramienta. No sanear las entradas puede permitir que un atacante inyecte instrucciones adversarias (inyección de prompts) que alteren el comportamiento del modelo. Valida siempre longitud, conjuntos de caracteres y nulidad.
+
+**Para crear una herramienta MCP:**
+1. Extiende `org.tinystruct.mcp.MCPTool`.
+2. Anota las operaciones con `@Action` y declara los parámetros con `@Argument` dentro del array `arguments`.
+3. Acepta los parámetros como argumentos explícitos del método que coincidan con las claves de `@Argument`. (**No** uses `getContext().getAttribute(...)` para los argumentos de herramientas).
+
+```java
+import org.tinystruct.mcp.MCPTool;
+import org.tinystruct.mcp.MCPException;
+import org.tinystruct.system.annotation.Action;
+import org.tinystruct.system.annotation.Argument;
+
+public class MyCustomTool extends MCPTool {
+    public MyCustomTool() {
+        super("custom", "Una herramienta personalizada de demostración de MCP");
+    }
+
+    @Action(
+        value = "custom/hello",
+        description = "Saluda a alguien",
+        arguments = {
+            @Argument(key = "name", description = "El nombre a saludar", type = "string", optional = false)
+        }
+    )
+    public String hello(String name) throws MCPException {
+        // SEGURIDAD: valida/sanea las entradas antes de devolverlas al modelo
+        // para prevenir vulnerabilidades de inyección de prompts.
+        if (name == null || name.length() > 50 || !name.matches("^[a-zA-Z0-9 ]+$")) {
+            throw new MCPException("Nombre proporcionado no válido");
+        }
+        return "Hola, " + name + "!";
+    }
+}
+```
+
+**Para desplegar un servidor MCP:**
+1. Extiende `org.tinystruct.mcp.MCPServer`.
+2. Sobrescribe `init()` y registra tus herramientas con `this.registerTool()`. El framework escanea y mapea automáticamente los métodos `@Action`.
+
+```java
+import org.tinystruct.mcp.MCPServer;
+
+public class MyMCPServer extends MCPServer {
+    @Override
+    public void init() {
+        super.init();
+        this.registerTool(new MyCustomTool());
+    }
+
+    @Override
+    public String version() {
+        return "1.0.0";
+    }
+}
+```
+
+Ejecuta el servidor mediante el dispatcher:
+```bash
+bin/dispatcher start --import org.tinystruct.system.HttpServer --import com.example.MyMCPServer
+```
+
+## Configuración
+
+Los ajustes se gestionan en `src/main/resources/application.properties`.
+
+```properties
+# Base de datos
+driver=org.h2.Driver
+database.url=jdbc:h2:~/mydb
+database.user=sa
+database.password=
+
+# Servidor
+default.home.page=hello
+server.port=8080
+
+# Idioma
+default.language=es_PE
+
+# Sesión (Redis para entornos en clúster)
+# default.session.repository=org.tinystruct.http.RedisSessionRepository
+# redis.host=127.0.0.1
+# redis.port=6379
+```
+
+Acceso a valores de configuración desde la aplicación:
+```java
+String port = this.getConfiguration("server.port");
+```
+
+## Señales de alerta y antipatrones
+
+| Síntoma | Patrón correcto |
+|---|---|
+| Importar `com.google.gson` o `com.fasterxml.jackson` | Usa `org.tinystruct.data.component.Builder` / `Builders`. |
+| Usar `List<Builder>` para arrays JSON | Usa `Builders` para evitar problemas de type erasure de genéricos. |
+| `ApplicationRuntimeException: template not found` | Llama a `setTemplateRequired(false)` en `init()` para apps solo-API. |
+| Anotar métodos `private` con `@Action` | Las acciones deben ser `public` para que el framework las registre. |
+| Escribir `main(String[] args)` en las apps | Usa `bin/dispatcher` como punto de entrada de todos los módulos. |
+| Registro manual en `ActionRegistry` | Prefiere la anotación `@Action` para el descubrimiento automático. |
+| Acción no encontrada en tiempo de ejecución | Asegura que la clase se importa vía `--import` o está listada en `application.properties`. |
+| Argumento de CLI no visible | Pásalo con `--clave valor`; accede con `getContext().getAttribute("--clave")`. |
+| Dos métodos con la misma ruta, se dispara el equivocado | Define `mode` explícito (p. ej., `HTTP_GET` vs `HTTP_POST`) para desambiguar. |
+
+## Buenas prácticas
+
+1. **Aplicaciones granulares**: divide la lógica en aplicaciones pequeñas y enfocadas en lugar de una sola clase monolítica.
+2. **Configuración en `init()`**: usa `init()` para la puesta a punto (config, BD) en lugar del constructor. NO llames a `setAction()` — usa la anotación `@Action`.
+3. **Conciencia de modo**: usa el parámetro `Mode` en `@Action` para restringir operaciones sensibles a `CLI` o a métodos HTTP concretos.
+4. **Context antes que parámetros**: para flags opcionales de la CLI, usa `getContext().getAttribute("--flag")` en lugar de añadir parámetros a la firma del método.
+5. **Eventos asíncronos**: para tareas pesadas disparadas por eventos, usa `CompletableFuture.runAsync()` dentro del manejador del evento.
+
+## Referencia técnica
+
+Las guías detalladas están disponibles en el directorio `references/`:
+
+- [Arquitectura y configuración](references/architecture.md) — abstracciones, mapa de paquetes, properties
+- [Enrutamiento y @Action](references/routing.md) — detalles de la anotación, modos, parámetros
+- [Manejo de datos](references/data-handling.md) — Builder, Builders, serialización y parseo de JSON
+- [Persistencia en base de datos](references/database.md) — POJOs AbstractData, CRUD, XML de mapeo, generación de POJOs
+- [Sistema y uso](references/system-usage.md) — Context, sesiones, SSE, subida de archivos, eventos, redes
+- [Patrones de testing](references/testing.md) — tests unitarios y de integración HTTP con JUnit 5
+
+## Archivos fuente de referencia (internos)
+
+- `src/main/java/org/tinystruct/AbstractApplication.java` — clase base con hooks de ciclo de vida
+- `src/main/java/org/tinystruct/system/annotation/Action.java` — anotación y modos
+- `src/main/java/org/tinystruct/application/ActionRegistry.java` — motor de enrutamiento
+- `src/main/java/org/tinystruct/data/component/Builder.java` — serializador de objetos JSON
+- `src/main/java/org/tinystruct/data/component/Builders.java` — serializador de arrays JSON
+- `src/main/java/org/tinystruct/data/component/AbstractData.java` — clase base de POJOs con CRUD
+- `src/main/java/org/tinystruct/data/Mapping.java` — parser del XML de mapeo
+- `src/main/java/org/tinystruct/data/tools/MySQLGenerator.java` — referencia del generador de POJOs
+- `src/main/java/org/tinystruct/data/component/FieldType.java` — mapeos de tipos SQL a Java
+- `src/main/java/org/tinystruct/data/component/Condition.java` — constructor fluido de consultas SQL
+- `src/main/java/org/tinystruct/http/SSEPushManager.java` — gestión de conexiones SSE
+- `src/test/java/org/tinystruct/application/ActionRegistryTest.java` — ejemplos de tests del registro
+- `src/test/java/org/tinystruct/system/HttpServerHttpModeTest.java` — patrones de test de integración HTTP

package/vendor/theus-arsenal/skills/patrones-tinystruct/references/architecture.md

@@ -0,0 +1,90 @@
+# Arquitectura y configuración de tinystruct
+
+## Cuándo usarla
+
+Elige **tinystruct** cuando necesites un framework Java ligero y de alto rendimiento que trate la CLI y HTTP como ciudadanos iguales. Ideal para microservicios, utilidades de línea de comandos y aplicaciones orientadas a datos con huella pequeña y manejo de JSON sin dependencias.
+
+## Cómo funciona
+
+### Arquitectura central
+
+El framework opera sobre un `ActionRegistry` singleton que mapea patrones de URL (o cadenas de comando) a objetos `Action`. Cuando llega una petición, el sistema resuelve la ruta e invoca el method handle correspondiente.
+
+#### Abstracciones clave
+
+| Clase/Interfaz | Rol |
+|---|---|
+| `AbstractApplication` | Clase base de todas las aplicaciones tinystruct. Extiéndela. |
+| Anotación `@Action` | Mapea un método a una ruta URI (web) o a un nombre de comando (CLI). Es la única primitiva de enrutamiento. |
+| `ActionRegistry` | Singleton que mapea patrones de URL a objetos `Action` vía regex. Nunca lo instancies directamente. |
+| `Action` | Envuelve un `MethodHandle` + patrón regex + prioridad + `Mode` para el despacho. |
+| `Context` | Almacén de estado por petición. Accede con `getContext()`. Contiene los argumentos de la CLI y el request/response HTTP. |
+| `Dispatcher` | Punto de entrada de la CLI (`bin/dispatcher`). Lee `--import` para cargar aplicaciones. |
+| `HttpServer` | Servidor HTTP integrado. Arranca con `bin/dispatcher start --import org.tinystruct.system.HttpServer`. |
+
+### Mapa de paquetes
+
+```
+org.tinystruct/
+├── AbstractApplication.java      ← extiende esta clase
+├── Application.java              ← interfaz
+├── ApplicationException.java     ← excepción comprobada (checked)
+├── ApplicationRuntimeException.java ← excepción no comprobada (unchecked)
+├── application/
+│   ├── Action.java               ← envoltorio de acción en tiempo de ejecución
+│   ├── ActionRegistry.java       ← registro de rutas singleton
+│   └── Context.java              ← contexto de la petición
+├── system/
+│   ├── annotation/Action.java    ← anotación @Action + enum Mode
+│   ├── Dispatcher.java           ← dispatcher de la CLI
+│   ├── HttpServer.java           ← servidor HTTP integrado
+│   ├── EventDispatcher.java      ← bus de eventos
+│   └── Settings.java             ← lee application.properties
+├── data/
+│   ├── component/Builder.java    ← objeto JSON (úsalo en lugar de Gson/Jackson)
+│   ├── component/Builders.java   ← array JSON
+│   ├── component/AbstractData.java ← POJO base para persistencia en BD
+│   ├── component/Condition.java  ← constructor fluido de consultas SQL
+│   ├── component/FieldType.java  ← mapeos de tipos SQL a Java
+│   ├── Mapping.java              ← lee los metadatos .map.xml
+│   ├── DatabaseOperator.java     ← envoltorio JDBC de bajo nivel
+│   └── FileEntity.java           ← representación de archivo subido
+├── http/                         ← Request, Response, Constants
+│   └── SSEPushManager.java       ← gestión de Server-Sent Events
+└── net/                          ← URLRequest, HTTPHandler (HTTP saliente)
+```
+
+### Comportamiento de plantillas y flujo de despacho
+
+Por defecto, el framework asume que se requiere una plantilla de vista. Si `templateRequired` es `true`, `toString()` busca un archivo `.view` en `src/main/resources/themes/<NombreDeClase>.view`. Usa `setVariable("nombre", valor)` para pasar datos a las plantillas, que usan `{%nombre%}` para la interpolación.
+
+## Ejemplos
+
+### Inicialización mínima de una aplicación
+```java
+@Override
+public void init() {
+    this.setTemplateRequired(false); // Omite la búsqueda de plantilla .view en apps solo de datos
+    // NO llames a setAction() aquí — usa la anotación @Action en su lugar
+}
+```
+
+### Definición de acción e invocación por CLI
+```java
+@Action("hello")
+public String hello() {
+    return "¡Hola, tinystruct!";
+}
+```
+**Ejecución mediante el Dispatcher:**
+```bash
+bin/dispatcher hello
+bin/dispatcher greet/James
+bin/dispatcher echo --words "Hola" --import com.example.HelloApp
+```
+
+### Acceso a la configuración
+Ubicada en `src/main/resources/application.properties`:
+```java
+String port = this.getConfiguration("server.port");
+```

package/vendor/theus-arsenal/skills/patrones-tinystruct/references/data-handling.md

@@ -0,0 +1,60 @@
+# Manejo de datos en tinystruct (JSON)
+
+## Cuándo usarla
+
+Prefiere `org.tinystruct.data.component.Builder` y `Builders` para JSON ligero y sin dependencias. Usa `Builder` para objetos JSON (`{}`) y `Builders` para arrays JSON (`[]`). **Usa siempre `Builders` en lugar de `List<Builder>`** para evitar problemas de type erasure de genéricos.
+
+## Cómo funciona
+
+`Builder` proporciona una interfaz clave-valor para crear y leer objetos JSON. `Builders` proporciona una lista indexada para arrays JSON. Ambos se integran directamente con el manejo de resultados de `AbstractApplication`.
+
+### ¿Por qué Builder/Builders?
+- **Cero dependencias externas** — ligero y rápido
+- **Integración nativa** — funciona con el manejo de resultados del framework
+- **Seguridad de tipos** — `Builders` serializa correctamente a `[]`; `List<Builder>` puede causar problemas de casting
+
+## Ejemplos
+
+### Serializar un objeto único
+```java
+import org.tinystruct.data.component.Builder;
+
+Builder response = new Builder();
+response.put("status", "success");
+response.put("count", 42);
+return response.toString(); // {"status":"success","count":42}
+```
+
+### Serializar una lista con Builders
+```java
+import org.tinystruct.data.component.Builder;
+import org.tinystruct.data.component.Builders;
+
+Builders dataList = new Builders();
+for (MyModel item : myCollection) {
+    Builder b = new Builder();
+    b.put("id", item.getId());
+    b.put("name", item.getName());
+    dataList.add(b);
+}
+Builder response = new Builder();
+response.put("data", dataList);
+return response.toString(); // {"data":[{"id":1,"name":"X"}]}
+```
+
+### Parsear un objeto JSON
+```java
+Builder parsed = new Builder();
+parsed.parse(jsonString);
+String status = parsed.get("status").toString();
+```
+
+### Parsear un array JSON
+```java
+Builders parsedArray = new Builders();
+parsedArray.parse(jsonArrayString);
+for (int i = 0; i < parsedArray.size(); i++) {
+    Builder item = parsedArray.get(i);
+    System.out.println(item.get("name"));
+}
+```

package/vendor/theus-arsenal/skills/patrones-tinystruct/references/database.md

@@ -0,0 +1,99 @@
+# Persistencia en base de datos con tinystruct
+
+## Cuándo usarla
+
+Usa la capa de datos integrada (estilo ORM) para las operaciones de base de datos. Ofrece una alternativa ligera a JPA/Hibernate mediante POJOs que extienden `AbstractData` y archivos XML de mapeo.
+
+## Cómo funciona
+
+### Arquitectura
+
+Cada tabla se representa mediante:
+1. **POJO Java**: extiende `AbstractData`, aporta getters/setters y `setData(Row)`.
+2. **XML de mapeo**: `NombreDeClase.map.xml` en resources, que vincula campos Java con columnas de la BD.
+
+#### Clase base clave: `AbstractData`
+Proporciona los métodos CRUD:
+- `append()` / `appendAndGetId()`
+- `update()`
+- `delete()`
+- `findAll()` / `findOneById()` / `findOneByKey(key, value)`
+- `findWith(where, params)`
+- `find(SQL, params)`
+
+### Generación de POJOs (CLI)
+
+Introspecciona una tabla de una base de datos viva para producir el POJO y el archivo de mapeo.
+
+#### Configuración
+`application.properties`:
+```properties
+driver=com.mysql.cj.jdbc.Driver
+database.url=jdbc:mysql://localhost:3306/mydb
+database.user=root
+database.password=secret
+```
+
+#### Comando
+```bash
+# Modo interactivo
+bin/dispatcher generate
+
+# Especificar tabla
+bin/dispatcher generate --tables users
+```
+
+## Ejemplos
+
+### Operaciones CRUD
+```java
+// CREAR
+User user = new User();
+user.setUsername("james");
+user.append();
+
+// LEER
+User user = new User();
+user.setId(42);
+user.findOneById();
+
+// ACTUALIZAR
+user.setEmail("nuevo@example.com");
+user.update();
+
+// ELIMINAR
+user.delete();
+```
+
+### Consultas con condiciones
+```java
+User user = new User();
+Table results = user.findWith("username LIKE ?", new Object[]{"%jam%"});
+
+// Constructor fluido de condiciones
+Condition condition = new Condition();
+condition.setRequestFields("id,username");
+Table filtered = user.find(
+    condition.select("`users`").and("email LIKE ?").orderBy("id DESC"),
+    new Object[]{"%@example.com"}
+);
+```
+
+### Estructura del XML de mapeo
+`User.map.xml`:
+```xml
+<mapping>
+  <class name="User" table="users">
+    <id name="Id" column="id" increment="true" generate="false" length="11" type="int"/>
+    <property name="username" column="username" length="50" type="varchar"/>
+    <property name="email" column="email" length="100" type="varchar"/>
+  </class>
+</mapping>
+```
+
+## Reglas importantes
+
+1. **Ubicación del archivo**: el XML de mapeo **debe** reflejar la ruta de paquete del POJO bajo `src/main/resources/`.
+2. **Nomenclatura**: los nombres de tabla se singularizan para las clases (`users` → `User`). Las columnas con guiones bajos se convierten en campos camelCase (`created_at` → `createdAt`).
+3. **Setters**: usa los métodos `setFieldAsXxx` (p. ej., `setFieldAsString`) en los setters para sincronizar el estado con el mapa interno de campos.
+4. **Campo Id**: el campo de clave primaria en Java se llama siempre `Id` (heredado de `AbstractData`).

package/vendor/theus-arsenal/skills/patrones-tinystruct/references/routing.md

@@ -0,0 +1,64 @@
+# Referencia de enrutamiento con @Action en tinystruct
+
+## Cuándo usarla
+
+Usa la anotación `@Action` en tus aplicaciones para definir rutas tanto para comandos de CLI como para endpoints HTTP. Es apropiada siempre que necesites mapear lógica a una ruta concreta, manejar peticiones parametrizadas o restringir la ejecución a métodos HTTP específicos manteniendo una estructura de comandos consistente entre entornos.
+
+## Cómo funciona
+
+El `ActionRegistry` analiza las anotaciones `@Action` para construir la tabla de enrutamiento. Para métodos parametrizados, el framework mapea automáticamente los tipos de parámetro de Java a los segmentos regex correspondientes.
+
+### Reglas de generación de regex
+- `getUser(int id)` → patrón: `^/?user/(-?\d+)$`
+- `search(String query)` → patrón: `^/?search/([^/]+)$`
+
+Tipos de parámetro soportados: `String`, `int/Integer`, `long/Long`, `float/Float`, `double/Double`, `boolean/Boolean`, `char/Character`, `short/Short`, `byte/Byte`, `Date` (parseado como `yyyy-MM-dd HH:mm:ss`).
+
+### Valores de Mode
+
+| Mode | Cuándo se dispara |
+|---|---|
+| `DEFAULT` | Tanto CLI como HTTP (GET, POST, etc.) |
+| `CLI` | Solo el dispatcher de la CLI |
+| `HTTP_GET` | Solo HTTP GET |
+| `HTTP_POST` | Solo HTTP POST |
+| `HTTP_PUT` | Solo HTTP PUT |
+| `HTTP_DELETE` | Solo HTTP DELETE |
+| `HTTP_PATCH` | Solo HTTP PATCH |
+
+> **Nota:** puedes mapear nombres de métodos HTTP a `Mode` usando `Action.Mode.fromName(String methodName)`. Los valores desconocidos o nulos devuelven `Mode.DEFAULT`.
+
+## Ejemplos
+
+### Declaración básica de una acción
+```java
+@Action(
+    value = "path/subpath",          // obligatorio: segmento URI o comando de CLI
+    description = "Qué hace",        // se muestra en la salida de --help
+    mode = Mode.DEFAULT,             // por defecto: Mode.DEFAULT
+    example = "bin/dispatcher path/subpath/42"
+)
+public String myAction(int id) { ... }
+```
+
+### Rutas parametrizadas
+```java
+@Action("user/{id}")
+public String getUser(int id) { ... }
+// → CLI: bin/dispatcher user/42
+// → HTTP: /?q=user/42
+```
+
+### Inyección de dependencias
+`ActionRegistry` inyecta automáticamente `Request` y/o `Response` desde el `Context` si son parámetros:
+
+```java
+@Action(value = "upload", mode = Mode.HTTP_POST)
+public String upload(Request<?, ?> req, Response<?, ?> res) throws ApplicationException {
+    // Accede al request/response crudos si lo necesitas
+    return "ok";
+}
+```
+
+### Prioridad de coincidencia de rutas
+Si dos métodos comparten la misma ruta, el framework usa la primera coincidencia en el `ActionRegistry`. Usa valores de `Mode` explícitos para desambiguar (p. ej., separar un GET para un formulario y un POST para su envío).