@jossuealcala/madre 1.1.2 → 1.1.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (166) hide show
  1. package/CHANGELOG.en.md +40 -1
  2. package/CHANGELOG.md +40 -1
  3. package/README.en.md +3 -3
  4. package/README.md +3 -3
  5. package/SECURITY.md +11 -6
  6. package/TRADEMARKS.md +6 -2
  7. package/bin/madre.mjs +76 -11
  8. package/docs/REFERENCE.md +16 -10
  9. package/docs/SDK.md +36 -9
  10. package/docs/en/REFERENCE.md +12 -8
  11. package/docs/en/SDK.md +34 -8
  12. package/docs/en/training/README.md +1 -1
  13. package/docs/sdk/connector-module.mjs +1 -1
  14. package/docs/sdk/hello-module.mjs +39 -4
  15. package/docs/training/README.md +1 -1
  16. package/docs/training/train.sh +3 -0
  17. package/habilidades/explicamelo-facil/HABILIDAD.md +19 -0
  18. package/habilidades/hojas-de-calculo/HABILIDAD.md +18 -0
  19. package/habilidades/mensajes-a-clientes/HABILIDAD.md +19 -0
  20. package/habilidades/publicaciones-para-redes/HABILIDAD.md +19 -0
  21. package/habilidades/resumen-y-pendientes/HABILIDAD.md +18 -0
  22. package/habilidades/tu-pagina-paso-a-paso/HABILIDAD.md +19 -0
  23. package/package.json +7 -4
  24. package/public/activity.js +66 -22
  25. package/public/app.js +4947 -894
  26. package/public/assets/brand/OFL-SpaceGrotesk.txt +93 -0
  27. package/public/assets/brand/SpaceGrotesk-latin-ext.woff2 +0 -0
  28. package/public/assets/brand/SpaceGrotesk-latin.woff2 +0 -0
  29. package/public/assets/brand/madre-app-180.png +0 -0
  30. package/public/assets/brand/madre-app-192.png +0 -0
  31. package/public/assets/brand/madre-app-512.png +0 -0
  32. package/public/assets/brand/madre-app.svg +1 -1
  33. package/public/assets/brand/madre-favicon.svg +1 -1
  34. package/public/attribution.js +29 -19
  35. package/public/auto-open.js +102 -0
  36. package/public/brands.js +36 -19
  37. package/public/changes.js +63 -0
  38. package/public/en.js +1085 -102
  39. package/public/es.js +2940 -1656
  40. package/public/i18n.js +11 -0
  41. package/public/index.html +31 -27
  42. package/public/loader.js +322 -117
  43. package/public/macroverso.js +57 -355
  44. package/public/manual-content.js +69 -9
  45. package/public/manual.js +21 -6
  46. package/public/market-view.js +298 -84
  47. package/public/market.js +25 -2
  48. package/public/mcp-catalog.js +7 -2
  49. package/public/missions.js +169 -0
  50. package/public/news-scenes.js +292 -0
  51. package/public/nostromo-engine.js +935 -654
  52. package/public/notices.js +78 -0
  53. package/public/notifications.js +119 -0
  54. package/public/power.js +1 -1
  55. package/public/provider-marks.js +170 -0
  56. package/public/provider-pick.js +147 -0
  57. package/public/resay.js +4 -0
  58. package/public/review-ask.js +16 -13
  59. package/public/routing.js +29 -3
  60. package/public/salas-mac.css +467 -47
  61. package/public/salas-mac.html +8 -5
  62. package/public/salas-mac.js +805 -109
  63. package/public/salas.css +2 -2
  64. package/public/salas.html +2 -2
  65. package/public/salas.js +1 -1
  66. package/public/starters.js +128 -0
  67. package/public/styles.css +3036 -340
  68. package/public/subscription.js +303 -0
  69. package/public/terms-field.js +170 -0
  70. package/public/terms.js +117 -19
  71. package/public/tips.js +158 -0
  72. package/public/tour-chapters.js +88 -88
  73. package/public/tour.js +364 -46
  74. package/public/troubleshooting.js +313 -27
  75. package/public/welcome-scene.js +446 -0
  76. package/public/welcome.js +827 -282
  77. package/src/adapters/claude.mjs +2 -1
  78. package/src/adapters/codex.mjs +2 -1
  79. package/src/adapters/cursor.mjs +9 -6
  80. package/src/adapters/gemini-rest.mjs +236 -0
  81. package/src/adapters/gemini.mjs +13 -7
  82. package/src/adapters/grok.mjs +290 -0
  83. package/src/adapters/madre.mjs +71 -23
  84. package/src/adapters/opencode.mjs +15 -2
  85. package/src/adapters/process.mjs +14 -3
  86. package/src/adapters/steps.mjs +176 -0
  87. package/src/app-invite.mjs +90 -0
  88. package/src/auth-probe.mjs +32 -0
  89. package/src/billing-key.mjs +8 -0
  90. package/src/billing.mjs +317 -0
  91. package/src/bridge/policy.mjs +1 -1
  92. package/src/capabilities.mjs +46 -10
  93. package/src/chats.mjs +44 -2
  94. package/src/checkpoint.mjs +119 -1
  95. package/src/codex-route.mjs +113 -0
  96. package/src/commands.mjs +5 -2
  97. package/src/credentials.mjs +46 -8
  98. package/src/dataset.mjs +18 -7
  99. package/src/directives.mjs +1 -0
  100. package/src/event-store.mjs +25 -2
  101. package/src/extensions.mjs +5 -1
  102. package/src/ficha.mjs +158 -0
  103. package/src/files.mjs +36 -2
  104. package/src/image-studio.mjs +13 -3
  105. package/src/install-metrics.mjs +9 -3
  106. package/src/lease.mjs +6 -1
  107. package/src/looks.mjs +4 -1
  108. package/src/market-check.mjs +1 -1
  109. package/src/market-remote.mjs +135 -1
  110. package/src/mcp/image-server.mjs +59 -90
  111. package/src/mcp/memory-server.mjs +10 -0
  112. package/src/memory-tools.mjs +3 -0
  113. package/src/memory.mjs +29 -4
  114. package/src/models.mjs +21 -3
  115. package/src/modules/ahp.mjs +10 -4
  116. package/src/modules/bishop-exam.mjs +41 -12
  117. package/src/modules/bishop.mjs +2 -2
  118. package/src/modules/choices.mjs +12 -10
  119. package/src/modules/fetch-alone.mjs +7 -0
  120. package/src/modules/github.mjs +6 -2
  121. package/src/modules/helpers.mjs +23 -5
  122. package/src/modules/image-providers.mjs +281 -0
  123. package/src/modules/image-studio.mjs +106 -39
  124. package/src/modules/index.mjs +61 -12
  125. package/src/modules/intents-observe.mjs +3 -1
  126. package/src/modules/isolated.mjs +160 -0
  127. package/src/modules/ollama.mjs +35 -6
  128. package/src/modules/playwright.mjs +78 -20
  129. package/src/modules/reminders.mjs +42 -2
  130. package/src/modules/ripley.mjs +2 -1
  131. package/src/modules/run-alone.mjs +122 -0
  132. package/src/modules/runs.mjs +11 -8
  133. package/src/modules/sdk.mjs +10 -3
  134. package/src/notices-key.mjs +8 -0
  135. package/src/notices.mjs +185 -0
  136. package/src/ollama.mjs +57 -15
  137. package/src/opencode-health.mjs +1 -1
  138. package/src/outbound.mjs +124 -13
  139. package/src/quota-sources.mjs +148 -3
  140. package/src/review-ask.mjs +55 -31
  141. package/src/room/archivist.mjs +30 -5
  142. package/src/room/busy.mjs +16 -0
  143. package/src/room/changes.mjs +79 -0
  144. package/src/room/control.mjs +36 -6
  145. package/src/room/economy.mjs +1 -1
  146. package/src/room/guard.mjs +39 -2
  147. package/src/room/prompt.mjs +49 -6
  148. package/src/room/vectors.mjs +7 -1
  149. package/src/room.mjs +181 -49
  150. package/src/router.mjs +1 -1
  151. package/src/runs.mjs +39 -0
  152. package/src/runtime-detection.mjs +46 -6
  153. package/src/salas.mjs +181 -18
  154. package/src/server.mjs +1101 -118
  155. package/src/service.mjs +116 -0
  156. package/src/setup-trouble.mjs +20 -1
  157. package/src/setup.mjs +1 -1
  158. package/src/skill-check.mjs +269 -0
  159. package/src/skills-import.mjs +128 -0
  160. package/src/skills.mjs +502 -0
  161. package/src/terms.mjs +23 -5
  162. package/src/tour.mjs +31 -5
  163. package/src/updates.mjs +47 -4
  164. package/src/web-preview.mjs +181 -0
  165. package/src/whats-new.mjs +121 -1
  166. package/src/rumbo.mjs +0 -337
package/docs/SDK.md CHANGED
@@ -36,9 +36,9 @@ export default {
36
36
  };
37
37
  ```
38
38
 
39
- **Tu módulo no importa paquetes.** Ni a MADRE, ni al SDK, ni nada de npm. Antes de instalarlo, MADRE copia tu archivo a una carpeta temporal aparte y lo carga ahí —así revisa qué es sin que corra donde vive— y en esa carpeta no hay `node_modules`: un `import` por nombre de paquete no resuelve y la instalación falla.
39
+ **Tu módulo no importa paquetes.** Ni a MADRE, ni al SDK, ni nada de npm. Antes de instalarlo, MADRE copia tu archivo a una carpeta temporal aparte y lo carga en un proceso con permisos limitados; en esa carpeta no hay `node_modules`: un `import` por nombre de paquete no resuelve y la instalación falla. Ya instalado, cada llamada al módulo también corre en un proceso separado.
40
40
 
41
- Los **builtins de Node sí**, siempre: `node:fs`, `node:url`, `node:tls`, `node:child_process`. Con eso alcanza para hablar cualquier protocolo. Lo que no hay es nada que instalar.
41
+ Los **builtins de Node se pueden importar**: `node:fs`, `node:url`, `node:tls`, `node:child_process`. El cerco limita lo que hacen: un módulo tuyo no puede leer archivos ajenos, escribir directamente ni abrir procesos. Para hablar con un servicio externo puede usar `fetch` o los protocolos de Node según las reglas de red de la versión de Node. No hay paquetes que instalar.
42
42
 
43
43
  Si necesitas `defineModule` —para calcular algo antes de definir el módulo, por ejemplo— **MADRE te lo entrega**: exporta una función y lo recibes como argumento.
44
44
 
@@ -54,7 +54,7 @@ export default ({ defineModule }) => defineModule({
54
54
 
55
55
  ## Lo que un módulo puede declarar
56
56
 
57
- Esta tabla es **el contrato completo**: 41 campos, ni uno más. Cualquier otro que escribas MADRE
57
+ Esta tabla es **el contrato completo**: 42 campos, ni uno más. Cualquier otro que escribas MADRE
58
58
  te lo dice al instalar («no entendí estos campos») en vez de ignorarlo en silencio. Una prueba de
59
59
  la suite compara esta tabla contra el código, así que si alguna vez se separan, es un fallo.
60
60
 
@@ -75,14 +75,15 @@ la suite compara esta tabla contra el código, así que si alguna vez se separan
75
75
  | `ready(ctx)` | Lo que pides antes de encender, en un proyecto o en todos (desde el Mercado también): `null` si está listo, `{ status, body: { error } }` si no. Apagar nunca lo pregunta |
76
76
  | `footer` | Hasta dos teclas junto a la versión de MADRE, abajo a la derecha, mientras tu módulo está encendido: `[{ icon: 'heart' \| 'star' \| 'link', label, text, action, url }]`. Los textos pueden ser una frase o `{ es, en }`; `url` tiene que ser https y se abre en otra pestaña. MADRE la dibuja: al pasar el ratón muestra `text` y un botón con `action` |
77
77
  | `credit` | De quién fue la idea, si no fue tuya: un nombre. MADRE lo dice en la ficha del módulo y en el Mercado («Idea de …») |
78
+ | `notifies` | Su permiso para avisar por las notificaciones del sistema: `{ label, note }`, qué avisa y cuándo (por ejemplo, Recordatorios: «Vence un recordatorio»). Un módulo nunca toca macOS ni el navegador: MADRE lo lista en Ajustes › Notificaciones con su interruptor y es quien manda el aviso, si la persona lo deja |
78
79
  | `icon` | El ícono de tu módulo: `{ svg, color }`. `svg` es el dibujo —sus formas (`<path d="…"/>`) o un `<svg>` entero, en la cuadrícula que quieras— y `color` el de su mosaico, `#rrggbb`. MADRE lo ajusta solo para que se vea como los suyos: lo centra y lo escala al mismo cuadro, lo pinta en blanco y de un solo color, usa el color de MADRE más parecido al tuyo y quita lo que no sea dibujo (scripts, imágenes, enlaces, estilos, degradados). Sin `icon`, tu módulo lleva la pieza de rompecabezas en gris. Hasta 8000 caracteres |
79
80
  | `slash` | Comandos `/nombre` que corren en el servidor con tu `ctx` y devuelven `{ ok, title, text, link }`. La sala los muestra como tarjeta y los agentes los leen. `link` es opcional: `{ href, label }` con una ruta tuya (`/api/x/<id>/…`), y la tarjeta la ofrece como botón que abre otra pestaña; una dirección fuera de tus rutas se ignora |
80
- | `toolsForTurn(ctx, turn)` | Servidores MCP para el turno de un agente: `[{ name, command, args, env, tools, sends, brief }]`. MADRE los adjunta a la CLI en su corrida aislada y describe `brief` al agente. `turn` trae el agente, el modo, el arriendo, la carpeta, el puerto y `turn.turn`: el id de la respuesta que ese turno escribirá. Si tu servidor llama de vuelta a la sala en nombre del turno, manda ese id; `ctx.room.runningTurn(id)` dice si sigue corriendo y para qué agente |
81
+ | `toolsForTurn(ctx, turn)` | Servidores MCP para el turno de un agente: `[{ name, command, args, env, tools, sends, brief }]`. Para un módulo tuyo, `command` debe ser Node y el primer argumento debe ser **el mismo archivo del módulo**; MADRE lo arranca con el mismo cerco de permisos. Un ejecutable diferente no se ofrece al agente. `turn` trae el agente, el modo, el arriendo, la carpeta, el puerto y `turn.turn`: el id de la respuesta que ese turno escribirá |
81
82
  | `toolsForTurn` → `sends` | Cuáles de tus herramientas **mandan algo fuera**. El núcleo las retira por debajo de `#4` AIRLOCK: ni se le cuenta al modelo que existen. Ver abajo |
82
83
  | `reaches` | A dónde llega tu módulo, en las mismas cuatro respuestas que da MADRE de las suyas. Ver abajo |
83
84
  | `secrets` | Las llaves que necesitas, declaradas en vez de dibujadas: `[{ name, label, note, where }]`. MADRE pinta el campo, la guarda en su bodega bajo tu id y te la devuelve por `ctx.vault`. Ver abajo |
84
85
  | `routes` | Rutas HTTP propias: `{ method, path, handler(ctx, { payload, params, url, request, viaPhone }) }` → `{ status, body }`. `viaPhone` es `true` cuando la petición llega desde un teléfono emparejado: niégalo tú si tu ruta es de la Mac |
85
- | `onEvent(ctx, event)` | Cada evento del ledger de cada conversación viva de la sala, mientras tu módulo está encendido. `ctx.room` y `ctx.chat` son los de esa conversación y `ctx.record` escribe en ella. Corre aparte: lo que tarde o falle no detiene a la sala. Como siempre, un módulo no fabrica mensajes ni turnos |
86
+ | `onEvent(ctx, event)` | Cada evento del ledger de cada conversación viva de la sala, mientras tu módulo está encendido. `ctx.room` y `ctx.chat` son los de esa conversación y `ctx.record` escribe en ella. Corre aparte: lo que tarde o falle no detiene a la sala. En un módulo que instala una persona, cada evento abre un proceso nuevo: lo que guardes en una variable no llega al siguiente (guárdalo con `ctx.updateConfig`), y también llegan los avisos de cuánto queda del plan de cada IA, aunque nadie escriba; mira `event.type` primero y termina pronto. Como siempre, un módulo no fabrica mensajes ni turnos |
86
87
  | `controls` | Los ajustes de tu módulo, declarados en vez de dibujados: `[{ key, label, type: 'select' \| 'switch' \| 'text', options, choices, note, invert }]`. MADRE los pinta en la ficha y los guarda en tu bloque de `config.json`. En un `select`, `choices: [{ value, label }]` dice qué frase lee la persona por cada valor que se guarda (si lo das, `options` sale de ahí); sin él, la persona lee el valor tal cual |
87
88
  | `onSettings(ctx, settings)` | Te avisa cuando la humana cambió uno de tus `controls`, por si algo vivo tiene que enterarse |
88
89
  | `conditions` | Entradas para el catálogo de MU/TH/UR, con remedio por plataforma |
@@ -96,6 +97,32 @@ la suite compara esta tabla contra el código, así que si alguna vez se separan
96
97
  | `preflight(ctx)`, `detect(ctx)`, `installCommand(ctx)` | **Herencia**, de cuando un módulo solo podía ser un instalador. Siguen funcionando; para algo nuevo, devuelve `preflight` desde `status(ctx)` como arriba |
97
98
  | `describe(ctx)` | Lo arma MADRE con todo lo anterior. **No lo declares**: está en la lista porque el objeto lo lleva, no porque tengas que escribirlo |
98
99
 
100
+ ### Rutas, enlace y estado, exactos
101
+
102
+ Las tres formas que un agente no debe adivinar, tal como MADRE las lee. `docs/sdk/hello-module.mjs` las trae funcionando.
103
+
104
+ **Rutas.** Cada una es `{ method, path, handler }`. `path` es la dirección completa y vive siempre debajo de `/api/x/<id>/`: un texto, que se compara exacto, o una expresión regular (puede empezar con `^`), cuyas capturas llegan en `params` como lista, en orden. Un módulo que instalas solo contesta debajo de su `/api/x/<id>/`, diga lo que diga su expresión.
105
+
106
+ ```js
107
+ routes: [
108
+ { method: 'GET', path: '/api/x/informe/hoy', async handler(ctx) { return { status: 200, body: { ok: true } }; } },
109
+ { method: 'GET', path: /^\/api\/x\/informe\/dia\/(\d{4}-\d{2}-\d{2})$/, async handler(ctx, { params }) {
110
+ const [dia] = params;
111
+ return { status: 200, html: `<!doctype html><meta charset="utf-8"><h1>Informe del ${dia}</h1>` };
112
+ } },
113
+ ],
114
+ ```
115
+
116
+ El segundo argumento del `handler` es `{ payload, params, url, request, viaPhone }`. `payload` es el cuerpo JSON de un `POST` (`{}` en lo demás), `url` un `URL`, `request` solo `{ method, headers }` y `viaPhone` es `true` si llega desde un teléfono enlazado. Se responde `{ status, body }` para JSON o `{ status, html }` para una página.
117
+
118
+ **El enlace de una tarjeta.** Un comando de `slash` devuelve `{ ok, title, text, link }`. `link` es opcional: `{ href, label }`, donde `href` es una ruta tuya (empieza con `/api/x/<id>/`, sin espacios ni comillas, hasta 400 caracteres) y `label` se corta en 80. La tarjeta lo ofrece como botón que abre otra pestaña, ya con la ficha de MADRE; un enlace a otro lado se ignora sin avisar.
119
+
120
+ ```js
121
+ return { ok: true, title: 'Informe', text: `Listo el informe del ${dia}.`, link: { href: `/api/x/informe/dia/${dia}`, label: 'Abrir el informe' } };
122
+ ```
123
+
124
+ **El estado.** `status(ctx)` devuelve `{ status: { installed, detail } }`; `detail` es la frase junto a «Activo». Opcionales: `preflight: { ok, problems: [] }` (lo que falta antes de usarlo, en frases), `install: { display }` y `runs: [{ name, version, target }]` si envuelve un programa de fuera.
125
+
99
126
  ### ¿Se puede conectar con *X*?
100
127
 
101
128
  No depende de MADRE. Un módulo puede hacer lo que pueda hacer un proceso de Node en tu
@@ -236,7 +263,7 @@ terminando, y mientras tanto solo se activa a propósito con `PULSE_LABS=correo`
236
263
 
237
264
  La ficha de un módulo tuyo trae **GET A NEWER FILE**: MADRE va por el archivo —a la `url` que declaraste o al archivo desde el que lo instalaste—, lo verifica en una copia aparte y solo reemplaza al instalado si carga, respeta las reglas de la casa y dice una versión distinta. Verificar no instala nada.
238
265
 
239
- Y en la cabecera de MODULES hay **+ ADD A MODULE** para instalar el `.mjs` de alguien más. Pasa por la misma puerta que todo lo demás. Dicho claro, porque es lo que es: un módulo corre **dentro de MADRE, con los permisos de quien la abre**. MADRE comprueba que cargue y que no se salga de su corral —id propio, rutas solo bajo `/api/x/<id>/`, jamás encima de un módulo de MADRE—; lo que el código *pretende* no lo puede comprobar nadie más que tú.
266
+ Y en la cabecera de MODULES hay **+ ADD A MODULE** para instalar el `.mjs` de alguien más. Pasa por la misma puerta que todo lo demás. MADRE lo carga y ejecuta aparte: las API ordinarias pueden leer su archivo y el código del SDK, pero no escribir tus archivos ni abrir procesos. Si ofrece una herramienta MCP, también debe ser ese mismo archivo y corre con esos límites. Cuando Node ofrece `--allow-net`, solo un módulo que declara un destino recibe acceso a la red; en versiones anteriores, el modelo de permisos no restringe la red. La declaración no limita los dominios a los que puede llamar. **El modelo de permisos de Node no es una barrera de seguridad contra código malicioso.** Revisa el código y los destinos antes de instalarlo.
240
267
 
241
268
  ### En el Mercado, para todos
242
269
 
@@ -276,12 +303,12 @@ Un módulo que se instala en el proyecto en vez de encenderse conserva su tarjet
276
303
  ctx = {
277
304
  projectRoot, stateRoot, // el proyecto y ~/.pulse
278
305
  config, settings, // config.json completo y tus ajustes con defaults
279
- env, agents, room, // agentes detectados; la sala (room.capabilities(), room.record(...))
306
+ env, agents, room, // env vacío para módulos tuyos; agentes detectados; sala mediada
280
307
  readConfig(), updateConfig(patch),
281
308
  record(type, payload), // escribe un evento en el ledger; tipo "algo.algo", nunca message.* ni agent.*
282
309
  language, t(text, vars), // el idioma de la sala, 'es' o 'en', y tus palabras en él (sdk: 2):
283
310
  // una frase en inglés que MADRE ya conoce, o la tuya en { es, en }
284
- services: { history, imageKey, ollama: { state, generate }, … }, // lo que el servidor ofrece;
311
+ services: { history, ollama: { state, generate } }, // lo que el servidor ofrece a módulos tuyos;
285
312
  // ollama.generate({ system, prompt, json }) contesta con el modelo local (sdk: 2)
286
313
  vault: { get, held, keep, forget } // tus secretos, y solo los tuyos
287
314
  }
@@ -329,7 +356,7 @@ Un módulo tuyo lleva la etiqueta «Tuyo» y se quita desde su ficha con «Quita
329
356
 
330
357
  ## Lo que un módulo no puede tocar
331
358
 
332
- Un módulo corre dentro del proceso de MADRE con tus permisos: instala solo lo que leíste. MADRE, por su parte, protege su núcleo así:
359
+ Un módulo tuyo corre en un proceso separado. El modelo de permisos de Node limita las API ordinarias a su archivo y el código del SDK, sin escritura directa ni apertura de otros procesos. Las funciones de `ctx` pasan por MADRE: la bodega solo entrega los secretos de ese módulo y `updateConfig` solo acepta su bloque de ajustes. Una herramienta MCP del módulo usa el mismo archivo y cerco; si el turno tiene carpeta de borrador, puede escribir allí. El modelo de Node no garantiza contener código malicioso: revisa el código y los destinos de red antes de instalarlo. MADRE protege su núcleo así:
333
360
 
334
361
  - Sus rutas HTTP viven bajo `/api/x/<id>/`; un módulo con rutas fuera de ahí no carga, así ninguno puede suplantar `/api/state`, `/api/messages` o cualquier ruta propia de MADRE.
335
362
  - No puede usar el `id` de un módulo integrado ni de otro ya cargado.
@@ -14,7 +14,7 @@ Everything MADRE does, with the exact numbers. To get started in five minutes, s
14
14
  You need Node 22.5 or later and at least one of these CLIs with a signed-in session: **Codex**, **Claude Code**, **Gemini CLI**, **OpenCode**. If **Ollama** is also running with a chat model, the project gets a fifth, local agent.
15
15
 
16
16
  1. Run `npx @jossuealcala/madre` from any folder: it opens Home, with all your projects and the Coordinator at the top. The first time, a three-step assistant walks you through it: connect the agents (each with its own button to install it and sign in, right there; once for all projects), add the projects (you choose folders inside your user folder; adding does not open them) and open the ones you are going to use. `npx @jossuealcala/madre start` inside a folder still opens that project directly; if there are no agents, the project opens anyway on Connect your agents so you can install them and sign in.
17
- 2. The project opens at `http://127.0.0.1:4317`. Pick an agent in the selector or type `@claude …`. The chip next to `to @agente` says which mode the message goes out in; `#1 CHAT ONLY`, read-only, is the default.
17
+ 2. The project opens at `http://127.0.0.1:4317`. MADRE opens the browser with its ficha in the address (`?ficha=…`): the browser keeps it and the address is left clean. Pick an agent in the selector or type `@claude …`. The chip next to `to @agente` says which mode the message goes out in; `#1 CHAT ONLY`, read-only, is the default.
18
18
  3. To add or reconnect an AI later: Settings → Agents (the settings button in the bar, or ⌘, / Ctrl+,), where the agents live alongside the rest of the settings. Codex, Claude Code, Gemini (with your Google account) and OpenCode (with GitHub Copilot) sign in with one click; Gemini and OpenCode also accept their key right there. Under each agent, "Prefer your terminal?" unfolds the same step written as a command, for whoever prefers to do it by hand. MADRE does not store provider credentials: each session and each key goes to its own CLI's file.
19
19
  4. With Ollama, the Local AI module (Modules, in the bar) is already on: memory is embedded locally and `@madre` appears in the row.
20
20
  5. Settings → Memory decides who distills the memory and how often. The Memory map, from the Diagnostics header, shows what the project remembers.
@@ -25,7 +25,7 @@ npx @jossuealcala/madre setup # the same setup, from the terminal, if you
25
25
  npx @jossuealcala/madre start --no-open --project RUTA
26
26
  ```
27
27
 
28
- **On a server, with no screen.** MADRE listens only on `127.0.0.1` of the machine it runs on, and on purpose: it has no password, and whoever reached it could set the agents to work there. Do not open its ports to the network. To use it on a server, open it through an SSH tunnel from your computer. Home uses 4317 and every project you open takes the next free port (4318, 4319…), so the tunnel carries several; if you open more projects, add more `-L`.
28
+ **On a server, with no screen.** MADRE listens only on `127.0.0.1` of the machine it runs on, and on purpose: whoever reached it could set the agents to work there. Do not open its ports to the network. To use it on a server, open it through an SSH tunnel from your computer. Home uses 4317 and every project you open takes the next free port (4318, 4319…), so the tunnel carries several; if you open more projects, add more `-L`.
29
29
 
30
30
  ```bash
31
31
  # on your computer: reach the server with the tunnel
@@ -34,7 +34,9 @@ ssh -L 4317:127.0.0.1:4317 -L 4318:127.0.0.1:4318 -L 4319:127.0.0.1:4319 -L 4320
34
34
  npx @jossuealcala/madre --no-open
35
35
  ```
36
36
 
37
- Then open `http://127.0.0.1:4317/salas` in your computer's browser. The agents are installed on the server and connected from Settings › Agents: Claude gives you a link and a code you paste right there, and Gemini and OpenCode take their key. Use your own user, not root: the agents work with the permissions of whoever runs MADRE.
37
+ Then open, in your computer's browser, the address MADRE wrote in the server's terminal, the one that ends in `?ficha=…`. The agents are installed on the server and connected from Settings › Agents: Claude gives you a link and a code you paste right there, and Gemini and OpenCode take their key. Use your own user, not root: the agents work with the permissions of whoever runs MADRE.
38
+
39
+ **The ficha.** Every request to MADRE carries its ficha (Spanish for «token»): a random secret in `~/.pulse/credentials/ficha.json` that only your user can read. The browser gets it once, in the address MADRE opens, and keeps it in a cookie; MADRE's own processes send it in the `x-madre-ficha` header. Without it, MADRE only says that it is MADRE and its version: it lets nobody read your projects, install modules or open #4. Home makes a new one each time it starts and opens the browser; a restart with no browser (an update, a project Home opens) keeps the one before. A tab without the ficha tells you where to open MADRE from. What it does not stop: a program running as your user can read the file, as it reads everything of yours, and the cookie also travels to other ports of `127.0.0.1` you open in the same browser.
38
40
 
39
41
  **Three names.** **MADRE** is the product. **Diagnostics** is its operational voice: failures, connections, settings. **Log** is the channel the project runs on: the event record, the plan block, the `.pulse/` folder where artifacts land; those identifiers keep their old name, PULSE.
40
42
 
@@ -116,7 +118,7 @@ Every message goes out with a mode. Your mode is the ceiling of any plan that me
116
118
  | **OpenCode** | yes | `-f` | per-pattern `edit` permissions | yes, with **Images** | webfetch / websearch |
117
119
  | **@madre** | the memory | no | no | no | no |
118
120
 
119
- **Images** is a MADRE module: its own MCP server that exposes `generate_image` on top of the Gemini API's image models, with your own key and your credits. Today **only Gemini**, and for a reason: it is the only agent account whose key MADRE already finds without asking you for a new one, and it has a free tier. Anthropic does not generate images —Claude reads them, it does not make them—, the ChatGPT account Codex signs in with does not give access to the images API, and OpenCode depends on the provider you point it at. It is connected to Claude, Gemini and OpenCode only inside a CREATE permission with the image scope turned on, in their isolated homes, and the image lands in the turn's folder like any artifact. `/image <petición>` sets up the permission and routes to the agent that can generate. With all four agents you can ask for an image; Codex makes it with its own tools, the others with Images.
121
+ **Images** is a MADRE module: its own MCP server that exposes `generate_image` on top of the image model you choose in Modules › Images —Gemini (Google), GPT Image (OpenAI) or Grok Imagine (xAI)—, with your own key and your credit; all of them charge each image, none has a free tier for images. The module's page, «With what it draws», shows what you already have without asking: the Gemini key Gemini CLI uses (`~/.gemini/.env` or the keychain), the OpenAI, xAI or Google keys OpenCode uses (its `auth.json`), the OpenAI key Codex signed in with, and `GEMINI_API_KEY`, `OPENAI_API_KEY` or `XAI_API_KEY` if MADRE was opened with them. What you do not have appears with what it is, where the key is made and a field to paste it: a Gemini key is kept where Gemini CLI reads it; an OpenAI or xAI key in MADRE's vault (`~/.pulse/credentials/image-studio.json`, `0600`), after the provider is asked whether it takes it (it lists models and spends no credit). Until you choose, the first provider whose key is found draws. The server reads the key itself when it draws: it does not travel in its environment, which Claude Code receives in its arguments. Ollama drew for a while, on the Mac only, and does not today, so it is not offered. It is connected to Claude, Gemini and OpenCode only inside a CREATE permission with the image scope turned on, in their isolated homes, and the image lands in the turn's folder like any artifact. `/image <petición>` sets up the permission and routes to the agent that can generate. Codex and Grok draw with their own account; the others, with Images.
120
122
 
121
123
  Web access is a permanent per-agent permission, off by default, turned on in Settings → Agents, with Web access.
122
124
 
@@ -129,7 +131,7 @@ Since 1.1.0, from **#1 to #3**, Claude, OpenCode and Codex may split their work
129
131
  | **Claude** | The `Agent` tool: the subagent inherits the same tools and rules (`--tools`, `--allowedTools`, `dontAsk`) | No `Agent` |
130
132
  | **OpenCode** | Only `explore` and `general`, each with the turn's permissions and unable to call another (OpenCode's own write and run commands) | `task` denied |
131
133
  | **Codex** | Its subagents stay inside the same sandbox | A one-thread limit: `features.multi_agent_v2.max_concurrent_threads_per_session=1` |
132
- | **Gemini** · **Cursor** | No | No |
134
+ | **Gemini** · **Cursor** · **Grok** | No | No |
133
135
 
134
136
  Tried with the real AIs (Claude 2.1.267, OpenCode 1.18.4, Codex 0.161): in #1 the subagent reads and does not write; in #3 it writes in the project, `.pulse/` refuses it and there are no commands; in #4 Codex answers «agent thread limit reached».
135
137
 
@@ -153,7 +155,7 @@ MADRE runs the steps as normal turns: each one stays in the ledger and goes thro
153
155
 
154
156
  **TURNS.** In Diagnostics, next to the sentinel. On by default: a conversation that is still working when you open another one does not stop, it keeps writing its record and the conversations panel marks it until it finishes. Two limits: conversations working at the same time (2) and turns at the same time in each one (3); a message that would exceed them is rejected with the reason before it starts. All conversations share a single holder of EDIT or FULL ACCESS. When it is off, a single conversation drives the agents and you cannot switch away from one that is working. `STOP ALL` stops them all.
155
157
 
156
- **STOP ALL.** The button in the bar, `STOPALL` in the Write box or `curl -X POST http://127.0.0.1:4317/api/stop-all` stop all plans and kill all agent processes. Diagnostics warns in red when the project gets out of hand: three agents at once, one agent with two overlapping turns, a plan longer than five minutes.
158
+ **STOP ALL.** The button in the bar, `STOPALL` in the Write box or `curl -X POST -H "x-madre-ficha: $(node -p "require(require('os').homedir() + '/.pulse/credentials/ficha.json').ficha")" http://127.0.0.1:4317/api/stop-all` stop all plans and kill all agent processes. Diagnostics warns in red when the project gets out of hand: three agents at once, one agent with two overlapping turns, a plan longer than five minutes.
157
159
 
158
160
  ---
159
161
 
@@ -199,7 +201,7 @@ Change who it goes to and the words change; raise the mode and the permission it
199
201
 
200
202
  **THE LAUNCH.** Below the document, the exact command MADRE would run to deliver it: the executable, the directory, every flag and the place where the briefing goes in. It is not a description — it is built by the same adapters that would build it for real. Below that, what keeps the run inside the turn (the session that does not persist, the temporary home that is deleted when it ends) and the MCP servers it could call, with their tools counted. **No environment value from that command is ever printed, only the names**: a command line is something people take photos of.
201
203
 
202
- **Outbound.** The record of what went out: every destination MADRE or an agent called, with its count. Never bodies, headers or query values — only where and how many times.
204
+ **Outbound.** The record of MADRE's and its modules' `fetch` calls, including isolated modules and their one-file MCP servers. It does not observe other Node protocols or agent CLI connections. It never stores bodies, headers or query values: only destinations and call counts.
203
205
 
204
206
  **The console.** Inside the core, Diagnostics answers from what the project already has. Three answers it does not understand and the interface closes.
205
207
 
@@ -223,7 +225,7 @@ The button in the bar opens the diagnostics screen. Type a symptom, an agent or
223
225
  | Module | What it adds |
224
226
  |---|---|
225
227
  | **Git** | `/git status`, `/git log [n]`, `/git diff`, `/git branches`: facts about the repository as a card in the thread, which the agents also read. `/git commit "mensaje"` and `/git push confirm`: your hand on the repository, with a preview of what would go out |
226
- | **Images** | `generate_image` for Claude, Gemini and OpenCode, with your Gemini key, inside CREATE |
228
+ | **Images** | `generate_image` for Claude, Gemini and OpenCode, with your Gemini, OpenAI or xAI key, inside CREATE |
227
229
  | **Preview** | The viewer renders HTML, SVG and Markdown in a sealed frame, with automatic reload |
228
230
  | **Local AI** | Smart search, archivist and `@madre` locally, free and without an account. It is installed, woken up and downloads its model from Connect your agents |
229
231
  | **Test browser** | A headless browser in turns that ask to see, test or capture a page. It only reaches this MADRE and the servers you started from COMMANDS: open the Preview or the served app, click, read the console, screenshots to the turn's scratch area. When you turn it on, MADRE checks that the server starts with its browser. Requires `@playwright/mcp` |
@@ -405,6 +407,8 @@ MADRE's folder is only taken away whole when it is MADRE's beyond doubt: an abso
405
407
  | `PULSE_DELEGATION` · `PULSE_MAX_PLAN_STEPS` | `1` · `4` | Plans |
406
408
  | `PULSE_ESCALATION_MS` | `180000` | Permission request timer |
407
409
  | `PULSE_OPENCODE_MODEL` | from the config | `proveedor/modelo` for OpenCode |
410
+ | `PULSE_GROK_MODEL` | Grok's own | Grok's model when none is chosen (`grok models` lists them) |
411
+ | `PULSE_GROK_SANDBOX` | `read-only` | `off` drops `--sandbox` where Grok's isolation cannot start; `--tools` still keeps it to reading |
408
412
  | `PULSE_CLAUDE_USAGE` · `PULSE_OFFICIAL_QUOTA` | `0` · `1` | Claude's official quota (reads the keychain); `0` turns off all provider reads |
409
413
  | `PULSE_GEMINI_IDLE_MS` · `PULSE_GEMINI_RETRIES` · `PULSE_GEMINI_FALLBACK_MODEL` | `90000` · `1` · `gemini-3-flash-preview` (empty: no spare) | Gemini under load |
410
414
 
package/docs/en/SDK.md CHANGED
@@ -36,9 +36,9 @@ export default {
36
36
  };
37
37
  ```
38
38
 
39
- **Your module does not import packages.** Not MADRE, not the SDK, nothing from npm. Before installing it, MADRE copies your file to a separate temporary folder and loads it there —that way it checks what it is without running it where it lives— and that folder has no `node_modules`: an `import` by package name doesn't resolve and the installation fails.
39
+ **Your module does not import packages.** Not MADRE, not the SDK, nothing from npm. Before installing it, MADRE copies your file to a separate temporary folder and loads it in a restricted process. That folder has no `node_modules`: an `import` by package name doesn't resolve and the installation fails. Once installed, each call also runs in a separate process.
40
40
 
41
- **Node builtins do work**, always: `node:fs`, `node:url`, `node:tls`, `node:child_process`. That's enough to speak any protocol. What there isn't is anything to install.
41
+ **Node builtins can be imported**: `node:fs`, `node:url`, `node:tls`, `node:child_process`. The fence limits what they can do: your module cannot read other files, write directly or start processes. It can use `fetch` or Node protocols for an outside service under the network rules of the installed Node version. There are no packages to install.
42
42
 
43
43
  If you need `defineModule` —to compute something before defining the module, for example— **MADRE hands it to you**: export a function and you receive it as an argument.
44
44
 
@@ -77,12 +77,12 @@ the suite compares this table against the code, so if they ever drift apart, it'
77
77
  | `credit` | Whose idea it was, if it was not yours: a name. MADRE says it on the module's card and in the Market («Idea by …») |
78
78
  | `icon` | Your module's icon: `{ svg, color }`. `svg` is the drawing — its shapes (`<path d="…"/>`) or a whole `<svg>`, on whatever grid you like — and `color` its tile's, `#rrggbb`. MADRE fits it on its own so it looks like MADRE's: centred and scaled to the same square, drawn in white in one color, on the MADRE color nearest to yours, with anything that is not drawing taken out (scripts, images, links, styles, gradients). Without `icon`, your module wears the grey puzzle piece. Up to 8000 characters |
79
79
  | `slash` | `/name` commands that run on the server with your `ctx` and return `{ ok, title, text, link }`. The room shows them as a card and the agents read them. `link` is optional: `{ href, label }` with a route of yours (`/api/x/<id>/…`), and the card offers it as a key that opens another tab; an address outside your routes is ignored |
80
- | `toolsForTurn(ctx, turn)` | MCP servers for an agent's turn: `[{ name, command, args, env, tools, sends, brief }]`. MADRE attaches them to the CLI in its isolated run and describes `brief` to the agent. `turn` carries the agent, the mode, the lease, the folder, the port, and `turn.turn`: the id of the reply that turn will write. If your server calls back to the room on behalf of the turn, send that id; `ctx.room.runningTurn(id)` tells you whether it is still running and for which agent |
80
+ | `toolsForTurn(ctx, turn)` | MCP servers for an agent's turn: `[{ name, command, args, env, tools, sends, brief }]`. For a module of yours, `command` must be Node and the first argument must be **the module's own file**; MADRE starts it with the same permission fence. Another executable is withheld. `turn` carries the agent, mode, lease, folder, port and `turn.turn`: the id of the reply the turn will write |
81
81
  | `toolsForTurn` → `sends` | Which of your tools **send something outside**. The core withdraws them below `#4` AIRLOCK: the model isn't even told they exist. See below |
82
82
  | `reaches` | Where your module reaches, in the same four answers MADRE gives about its own. See below |
83
83
  | `secrets` | The keys you need, declared instead of drawn: `[{ name, label, note, where }]`. MADRE draws the field, keeps it in its vault under your id, and gives it back to you through `ctx.vault`. See below |
84
84
  | `routes` | Your own HTTP routes: `{ method, path, handler(ctx, { payload, params, url, request, viaPhone }) }` → `{ status, body }`. `viaPhone` is `true` when the request comes from a paired phone: deny it yourself if your route belongs to the Mac |
85
- | `onEvent(ctx, event)` | Every ledger event of every live conversation in the room, while your module is on. `ctx.room` and `ctx.chat` are that conversation's, and `ctx.record` writes into it. It runs separately: whatever it takes long on or fails at doesn't stop the room. As always, a module doesn't fabricate messages or turns |
85
+ | `onEvent(ctx, event)` | Every ledger event of every live conversation in the room, while your module is on. `ctx.room` and `ctx.chat` are that conversation's, and `ctx.record` writes into it. It runs separately: whatever it takes long on or fails at doesn't stop the room. In a module a person installs, each event starts a new process: what you keep in a variable doesn't reach the next one (keep it with `ctx.updateConfig`), and the notices of how much is left of each AI's plan arrive too, even when nobody writes; check `event.type` first and finish quickly. As always, a module doesn't fabricate messages or turns |
86
86
  | `controls` | Your module's settings, declared instead of drawn: `[{ key, label, type: 'select' \| 'switch' \| 'text', options, choices, note, invert }]`. MADRE draws them on the page and saves them in your block of `config.json`. In a `select`, `choices: [{ value, label }]` says which phrase the person reads for each value that gets saved (if you give it, `options` comes from there); without it, the person reads the value as is |
87
87
  | `onSettings(ctx, settings)` | Tells you when the human changed one of your `controls`, in case something live needs to know |
88
88
  | `conditions` | Entries for the MU/TH/UR catalog, with a remedy per platform |
@@ -96,6 +96,32 @@ the suite compares this table against the code, so if they ever drift apart, it'
96
96
  | `preflight(ctx)`, `detect(ctx)`, `installCommand(ctx)` | **Legacy**, from when a module could only be an installer. They still work; for something new, return `preflight` from `status(ctx)` as above |
97
97
  | `describe(ctx)` | MADRE builds it from everything above. **Don't declare it**: it is on the list because the object carries it, not because you have to write it |
98
98
 
99
+ ### Routes, link and status, exactly
100
+
101
+ The three shapes an agent must not guess, as MADRE reads them. `docs/sdk/hello-module.mjs` has them working.
102
+
103
+ **Routes.** Each is `{ method, path, handler }`. `path` is the whole address and always lives under `/api/x/<id>/`: a string, matched exactly, or a regular expression (it may start with `^`), whose captures arrive in `params` as a list, in order. A module you install only answers under its `/api/x/<id>/`, whatever its expression says.
104
+
105
+ ```js
106
+ routes: [
107
+ { method: 'GET', path: '/api/x/report/today', async handler(ctx) { return { status: 200, body: { ok: true } }; } },
108
+ { method: 'GET', path: /^\/api\/x\/report\/day\/(\d{4}-\d{2}-\d{2})$/, async handler(ctx, { params }) {
109
+ const [day] = params;
110
+ return { status: 200, html: `<!doctype html><meta charset="utf-8"><h1>Report for ${day}</h1>` };
111
+ } },
112
+ ],
113
+ ```
114
+
115
+ The handler's second argument is `{ payload, params, url, request, viaPhone }`. `payload` is the JSON body of a `POST` (`{}` otherwise), `url` a `URL`, `request` only `{ method, headers }`, and `viaPhone` is `true` when it comes from a paired phone. Answer `{ status, body }` for JSON or `{ status, html }` for a page.
116
+
117
+ **A card's link.** A `slash` command returns `{ ok, title, text, link }`. `link` is optional: `{ href, label }`, where `href` is a route of yours (it starts with `/api/x/<id>/`, no spaces or quotes, up to 400 characters) and `label` is cut at 80. The card offers it as a key that opens another tab, already with MADRE's ficha; a link anywhere else is dropped without a word.
118
+
119
+ ```js
120
+ return { ok: true, title: 'Report', text: `The report for ${day} is ready.`, link: { href: `/api/x/report/day/${day}`, label: 'Open the report' } };
121
+ ```
122
+
123
+ **Status.** `status(ctx)` returns `{ status: { installed, detail } }`; `detail` is the line beside «On». Optional: `preflight: { ok, problems: [] }` (what is missing before it can be used, in sentences), `install: { display }`, and `runs: [{ name, version, target }]` if it wraps an outside program.
124
+
99
125
  ### Can it connect to *X*?
100
126
 
101
127
  That doesn't depend on MADRE. A module can do whatever a Node process can do on your
@@ -236,7 +262,7 @@ finishing it, and in the meantime it can only be turned on deliberately with `PU
236
262
 
237
263
  The page of a module of yours has **GET A NEWER FILE**: MADRE fetches the file —from the `url` you declared or from the file you installed it from—, verifies it in a separate copy, and only replaces the installed one if it loads, follows the house rules, and states a different version. Verifying installs nothing.
238
264
 
239
- And in the MODULES header there is **+ ADD A MODULE** to install someone else's `.mjs`. It goes through the same door as everything else. Said plainly, because it is what it is: a module runs **inside MADRE, with the permissions of whoever opens it**. MADRE checks that it loads and that it doesn't leave its pen —its own id, routes only under `/api/x/<id>/`, never on top of a MADRE module—; what the code *intends* is something nobody but you can check.
265
+ And in the MODULES header there is **+ ADD A MODULE** to install someone else's `.mjs`. It goes through the same door as everything else. MADRE loads and runs it separately: ordinary APIs can read the module file and SDK code, but cannot directly write your files or start processes. An MCP tool it offers must use that same file and limits. Where Node offers `--allow-net`, only modules declaring an outside destination receive network access; older versions do not restrict network access. A declaration does not limit the hosts it can contact. **Node's permission model is not a security boundary against malicious code.** Review the code and destinations before installing it.
240
266
 
241
267
  ### In the Market, for everyone
242
268
 
@@ -276,12 +302,12 @@ A module that installs into the project instead of being turned on keeps its ins
276
302
  ctx = {
277
303
  projectRoot, stateRoot, // el proyecto y ~/.pulse
278
304
  config, settings, // config.json completo y tus ajustes con defaults
279
- env, agents, room, // agentes detectados; la sala (room.capabilities(), room.record(...))
305
+ env, agents, room, // empty env for your modules; detected agents; mediated room
280
306
  readConfig(), updateConfig(patch),
281
307
  record(type, payload), // escribe un evento en el ledger; tipo "algo.algo", nunca message.* ni agent.*
282
308
  language, t(text, vars), // the room's language, 'es' or 'en', and your words in it (sdk: 2):
283
309
  // an English sentence MADRE already knows, or your own { es, en }
284
- services: { history, imageKey, ollama: { state, generate }, … }, // what the server offers;
310
+ services: { history, ollama: { state, generate } }, // what the server offers your modules;
285
311
  // ollama.generate({ system, prompt, json }) answers with the local model (sdk: 2)
286
312
  vault: { get, held, keep, forget } // tus secretos, y solo los tuyos
287
313
  }
@@ -329,7 +355,7 @@ A module of yours carries the «Yours» tag and is removed from its page with «
329
355
 
330
356
  ## What a module cannot touch
331
357
 
332
- A module runs inside MADRE's process with your permissions: install only what you've read. MADRE, for its part, protects its core like this:
358
+ A module of yours runs in a separate process. Node limits ordinary APIs to its file and the SDK code and denies direct writes and child processes. The `ctx` functions pass through MADRE: the vault returns only that module's secrets, and `updateConfig` accepts only its settings block. Its one-file MCP server uses the same limits and may write to the turn's scratch folder when one exists. Node does not guarantee containment of malicious code: review its code and network destinations before installing it. MADRE also protects its core like this:
333
359
 
334
360
  - Its HTTP routes live under `/api/x/<id>/`; a module with routes outside that doesn't load, so none can impersonate `/api/state`, `/api/messages`, or any route of MADRE's own.
335
361
  - It cannot use the `id` of a built-in module or of another one already loaded.
@@ -10,7 +10,7 @@ From **Settings › What it remembers › Train your own AI › Export** (when i
10
10
  npx @jossuealcala/madre dataset # in the project folder
11
11
  ```
12
12
 
13
- It writes `~/.pulse/rooms/<project>/dataset/{train.jsonl, valid.jsonl, manifest.json}`. Each line is `{"messages":[{role:"system"},{role:"user"},{role:"assistant"}]}`: the project's real answers, redacted (no paths, names, emails or keys), plus the summarized notes as recall pairs. Messages sent in #0 INCOGNITO are never there.
13
+ It writes `~/.pulse/rooms/<project>/dataset/{train.jsonl, valid.jsonl, test.jsonl, manifest.json}`: one pair in ten goes to `valid.jsonl`, to measure while it trains, and another one in ten to `test.jsonl`, never trained on, for the test at the end. Each line is `{"messages":[{role:"system"},{role:"user"},{role:"assistant"}]}`: the project's real answers, redacted (no paths, names, emails or keys), plus the summarized notes as recall pairs. Messages sent in #0 INCOGNITO are never there.
14
14
 
15
15
  How much you need: with fewer than ~200 pairs the model learns the tone and little more; from ~1000 on it starts to be worth it. Export every so often; the split is deterministic, so lines don't switch sides.
16
16
 
@@ -10,7 +10,7 @@
10
10
  //
11
11
  // ─── The one shape worth copying ──────────────────────────────────────────────────────────────
12
12
  //
13
- // A connector needs two things that look like they need two files: a module MADRE imports, and
13
+ // A connector needs two things that look like they need two files: a module MADRE loads separately, and
14
14
  // an MCP server MADRE runs as its own process. They are the same file. It is the spec when
15
15
  // imported and the server when executed, and it tells the two apart at the bottom.
16
16
  //
@@ -20,7 +20,7 @@ export default {
20
20
  name: 'HELLO', // how MODULES shows it
21
21
  vendor: 'you', // a person, a team, a company
22
22
  version: '0.1.0',
23
- summary: 'Greets the room from the composer. The smallest possible module: a switch, one setting, one slash command.',
23
+ summary: 'Greets the room from the composer. A small module with everything in its place: a switch, one setting, one slash command with its link, and two routes.',
24
24
  creates: ['nothing in the project'],
25
25
  requires: [],
26
26
  settings: { enabled: false, greeting: 'hola' }, // defaults; the human changes them in config.json
@@ -28,21 +28,56 @@ export default {
28
28
  // nearest of its own tile colors, so draw it on any grid and do not worry about its size.
29
29
  icon: { svg: '<path d="M4 10.5c0-3.3 2.7-6 6-6s6 2.7 6 6-2.7 6-6 6H4z" fill="none" stroke="currentColor" stroke-width="1.6" stroke-linejoin="round"/>', color: '#0f766e' },
30
30
 
31
- // What MODULES shows for this module. ctx.settings already has the defaults applied.
31
+ // What MODULES shows for this module. ctx.settings already has the defaults applied. The whole
32
+ // shape: { status: { installed, detail }, preflight: { ok, problems }, install: { display },
33
+ // runs: [{ name, version, target }] }; only `status` is needed, `detail` is the line beside «On».
32
34
  async status(ctx) {
33
35
  return { status: { installed: Boolean(ctx.settings.enabled), detail: ctx.settings.enabled ? `on · says "${ctx.settings.greeting}"` : 'off' } };
34
36
  },
35
37
 
36
- // Slash commands: they run on the server, inside MADRE, and their answer lands in the room as a
38
+ // Slash commands: they run in a separate process, and their answer lands in the room as a
37
39
  // fact card that the human and every agent read. Only while the module is on.
38
40
  slash: [
39
41
  {
40
42
  name: 'hello',
41
43
  usage: '/hello [name]',
42
44
  summary: 'Greets someone in the room.',
45
+ // The answer: { ok, title, text, link }. `link` is optional: { href, label }, where href is one
46
+ // of this module's own routes (/api/x/<id>/…, no spaces or quotes, up to 400 characters) and
47
+ // label is cut at 80. The card offers it as a key that opens another tab, already with MADRE's
48
+ // ficha. A link anywhere else is dropped without a word.
43
49
  async execute(ctx, args) {
44
50
  const who = args[0] ?? 'crew';
45
- return { ok: true, title: 'HELLO', text: `${ctx.settings.greeting}, ${who}. Project: ${ctx.projectRoot.split('/').pop()}. Agents online: ${ctx.agents.filter((agent) => agent.ready).map((agent) => `@${agent.id}`).join(', ') || 'none'}.` };
51
+ const page = /^[a-z0-9-]{1,40}$/i.test(who) ? who.toLowerCase() : 'crew';
52
+ return {
53
+ ok: true,
54
+ title: 'HELLO',
55
+ text: `${ctx.settings.greeting}, ${who}. Project: ${ctx.projectRoot.split('/').pop()}. Agents online: ${ctx.agents.filter((agent) => agent.ready).map((agent) => `@${agent.id}`).join(', ') || 'none'}.`,
56
+ link: { href: `/api/x/hello/card/${page}`, label: 'Open the greeting' },
57
+ };
58
+ },
59
+ },
60
+ ],
61
+
62
+ // Routes of its own: { method, path, handler(ctx, { payload, params, url, request, viaPhone }) }.
63
+ // `path` is the whole address and always lives under /api/x/<id>/: a string, matched exactly, or a
64
+ // pattern, whose captures arrive in `params` as a list, in order. `payload` is the JSON body of a
65
+ // POST ({} otherwise), `url` a URL, `request` only { method, headers }, `viaPhone` true when it comes
66
+ // from a paired phone. Answer { status, body } for JSON or { status, html } for a page.
67
+ routes: [
68
+ {
69
+ method: 'GET',
70
+ path: '/api/x/hello/greeting',
71
+ async handler(ctx) {
72
+ return { status: 200, body: { greeting: ctx.settings.greeting } };
73
+ },
74
+ },
75
+ {
76
+ method: 'GET',
77
+ path: /^\/api\/x\/hello\/card\/([a-z0-9-]{1,40})$/,
78
+ async handler(ctx, { params }) {
79
+ const [who] = params;
80
+ return { status: 200, html: `<!doctype html><meta charset="utf-8"><title>HELLO</title><p>${ctx.settings.greeting}, ${who}.</p>` };
46
81
  },
47
82
  },
48
83
  ],
@@ -10,7 +10,7 @@ Desde **Ajustes › Lo que recuerda › Entrena tu propia IA › Exportar** (al
10
10
  npx @jossuealcala/madre dataset # en la carpeta del proyecto
11
11
  ```
12
12
 
13
- Escribe `~/.pulse/rooms/<proyecto>/dataset/{train.jsonl, valid.jsonl, manifest.json}`. Cada línea es `{"messages":[{role:"system"},{role:"user"},{role:"assistant"}]}`: las respuestas reales del proyecto, redactados (sin rutas, nombres, correos ni claves), más las notas resumidas como pares de recuerdo. Lo que se envió en #0 INCÓGNITO nunca está.
13
+ Escribe `~/.pulse/rooms/<proyecto>/dataset/{train.jsonl, valid.jsonl, test.jsonl, manifest.json}`: uno de cada diez pares va a `valid.jsonl`, para medir mientras entrena, y otro de cada diez a `test.jsonl`, que nunca se entrena, para la prueba del final. Cada línea es `{"messages":[{role:"system"},{role:"user"},{role:"assistant"}]}`: las respuestas reales del proyecto, redactados (sin rutas, nombres, correos ni claves), más las notas resumidas como pares de recuerdo. Lo que se envió en #0 INCÓGNITO nunca está.
14
14
 
15
15
  Cuánto hace falta: con menos de ~200 pares el modelo aprende el tono y poco más; a partir de ~1000 empieza a valer. Exporta cada tanto; el split es determinista, así que las líneas no cambian de lado.
16
16
 
@@ -7,6 +7,9 @@ ROOM="${1:?room dir, e.g. ~/.pulse/rooms/<sala>}"
7
7
  BASE="${2:-Qwen/Qwen2.5-1.5B-Instruct}"
8
8
  ITERS="${3:-600}"
9
9
  [ -f "$ROOM/dataset/train.jsonl" ] || { echo "no dataset: run 'madre dataset' first"; exit 2; }
10
+ # The test at the end reads test.jsonl, never trained on; a dataset exported before MADRE wrote it
11
+ # has none, and mlx-lm stops there (RX-30).
12
+ [ -s "$ROOM/dataset/test.jsonl" ] || { echo "no test.jsonl: export the dataset again with 'madre dataset'"; exit 2; }
10
13
  PAIRS=$(wc -l < "$ROOM/dataset/train.jsonl")
11
14
  [ "$PAIRS" -ge 50 ] || { echo "only $PAIRS training pairs; let the room grow (aim for a few hundred)"; exit 3; }
12
15
  python3 -c "import mlx_lm" 2>/dev/null || { echo "pip install mlx-lm (inside a venv) first"; exit 4; }
@@ -0,0 +1,19 @@
1
+ ---
2
+ id: explicamelo-facil
3
+ name: { es: "Explícamelo fácil", en: "Explain it simply" }
4
+ line: { es: "Te explica cualquier cosa con palabras de todos los días, sin tecnicismos.", en: "Explains anything in everyday words, without jargon." }
5
+ icon: help
6
+ when: { es: "La persona no entiende algo y pide que se lo expliquen: explícame, explícamelo, explica, explicación, entiendo, entiende, entender, significa, significado, ¿qué es?, ¿cómo funciona?, ¿para qué sirve?, soy nueva, soy nuevo, principiante, no sé programar. Solo para explicar.", en: "The person does not understand something and asks for an explanation: explain, explanation, understand, means, meaning, what is it, how does it work, what is it for, beginner, new to this, cannot code. Only to explain." }
7
+ version: 1.0.0
8
+ minMadre: 1.1.4
9
+ ---
10
+
11
+ Quien pregunta está empezando: no programa y apenas conoce la IA. Explícale como a una persona lista que no es del tema.
12
+
13
+ - Contesta en su idioma, con palabras de todos los días. Si tienes que usar una palabra técnica, dila una vez y explícala en la misma oración: «el repositorio, que es la carpeta del proyecto con su historial».
14
+ - Empieza por lo que le sirve: qué es y para qué le importa, en una o dos líneas. Los detalles van después y solo si ayudan.
15
+ - Usa una comparación de la vida diaria cuando aclare (una receta, una tienda, una libreta), nunca más de una.
16
+ - Si hay pasos, numéralos y que cada paso sea una sola acción.
17
+ - Muestra un ejemplo real del proyecto en lugar de uno inventado cuando lo tengas a la mano.
18
+ - No le pidas que abra la terminal ni que escriba comandos: si algo hay que correr, dilo y ofrécete a hacerlo tú cuando el modo lo permita.
19
+ - Termina con una sola pregunta corta para saber si quedó claro o qué quiere hacer después.
@@ -0,0 +1,18 @@
1
+ ---
2
+ id: hojas-de-calculo
3
+ name: { es: "Tablas y hojas de cálculo", en: "Tables and spreadsheets" }
4
+ line: { es: "Ordena tus hojas de cálculo, saca totales y te explica las fórmulas.", en: "Tidies your spreadsheets, gets totals and explains the formulas." }
5
+ icon: bars
6
+ when: { es: "La persona trabaja con una hoja de cálculo, excel, csv, tabla, columnas, fórmula, fórmulas, total, totales, suma, sumar, promedio, gastos, ventas, inventario, reporte o control de números.", en: "The person works with a spreadsheet, excel, csv, table, columns, formula, formulas, total, totals, sum, average, expenses, sales, stock, inventory, report or tracking numbers." }
7
+ version: 1.0.0
8
+ minMadre: 1.1.4
9
+ ---
10
+
11
+ Quien pregunta usa hojas de cálculo, no programa.
12
+
13
+ - Antes de cambiar un archivo, di en una línea qué vas a hacer y en qué columnas. Nunca borres filas sin decirlo; si limpias datos, guarda una copia o deja el original intacto.
14
+ - Cuando des un total o una conclusión, di de qué filas sale para que la persona lo pueda comprobar.
15
+ - Si propones una fórmula, escríbela lista para pegar (para Excel o Google Sheets, la que use) y explica qué hace en una oración.
16
+ - Prefiere columnas claras: fecha, concepto, cantidad, monto. Fechas en un solo formato, montos sin símbolos mezclados.
17
+ - Para un reporte, primero tres o cuatro números que importan y luego la tabla, no al revés.
18
+ - Si ves algo raro (montos negativos, fechas imposibles, duplicados), señálalo antes de seguir.
@@ -0,0 +1,19 @@
1
+ ---
2
+ id: mensajes-a-clientes
3
+ name: { es: "Mensajes y correos a clientes", en: "Messages and emails to customers" }
4
+ line: { es: "Correos y WhatsApp a clientes, listos para copiar y mandar.", en: "Emails and WhatsApp messages to customers, ready to copy and send." }
5
+ icon: chat
6
+ when: { es: "La persona pide escribir o contestar un correo, mail, email, mensaje, whatsapp, respuesta, recordatorio de pago, cobro, disculpa o aviso para un cliente, clienta, proveedor o contacto.", en: "The person asks to write or answer an email, mail, message, whatsapp, reply, payment reminder, apology or notice for a customer, client, supplier or contact." }
7
+ version: 1.0.0
8
+ minMadre: 1.1.4
9
+ ---
10
+
11
+ Escribe mensajes que la persona pueda copiar y mandar tal cual.
12
+
13
+ - Primero el mensaje listo, en un bloque aparte para copiarlo fácil. Después, si hace falta, una línea de por qué lo escribiste así.
14
+ - Corto y claro: saludo, lo importante en las dos primeras líneas, qué se espera del otro, cierre. Un WhatsApp cabe en la pantalla sin bajar.
15
+ - Tono cálido y profesional, sin sonar a robot ni a plantilla. Nunca grosero aunque el cliente lo haya sido.
16
+ - Cobrar o decir que no también se hace con amabilidad: firme en lo que se pide, suave en cómo se pide.
17
+ - Si falta un dato que el mensaje necesita (un monto, una fecha, un nombre), deja un espacio claro como [fecha] y dilo, en lugar de inventarlo.
18
+ - Si la persona dio un borrador, respeta su voz: mejora sin reescribirlo de cero.
19
+ - Ofrece, en una línea, una versión más formal o más breve si puede servir.
@@ -0,0 +1,19 @@
1
+ ---
2
+ id: publicaciones-para-redes
3
+ name: { es: "Publicaciones para redes", en: "Social media posts" }
4
+ line: { es: "Ideas y textos para tus redes que no suenan a anuncio genérico.", en: "Ideas and texts for your social media that do not sound like a generic ad." }
5
+ icon: image
6
+ when: { es: "La persona pide ideas o textos para redes sociales: publicación, publicaciones, post, posts, instagram, facebook, tiktok, linkedin, historias, reels, hashtags, caption, anuncio, calendario de publicaciones, contenido.", en: "The person asks for ideas or texts for social media: post, posts, instagram, facebook, tiktok, linkedin, stories, reels, hashtags, caption, ad, posting calendar, content." }
7
+ version: 1.0.0
8
+ minMadre: 1.1.4
9
+ ---
10
+
11
+ Ayuda a un negocio pequeño o a una persona a publicar sin que suene a anuncio genérico.
12
+
13
+ - Antes de escribir, usa lo que sepas del proyecto (qué vende, a quién, en qué ciudad). Si no sabes nada, pregunta solo eso, en una línea.
14
+ - Cada publicación: un gancho en la primera línea, el valor para quien la lee, y una sola invitación clara (comentar, escribir por mensaje, visitar).
15
+ - Escribe para la red que te pidieron: Instagram más visual y corto, LinkedIn más explicativo, TikTok como guion de pocos segundos.
16
+ - Máximo cinco hashtags, de los que la gente de verdad busca, nunca una lista larga.
17
+ - Si piden varias, varía el tipo: una que enseña, una que muestra el producto, una de detrás de cámaras, una con una pregunta.
18
+ - Cuando sirva, sugiere la imagen o el video en una línea («foto de la taza en la mano, luz de mañana»).
19
+ - No prometas resultados ni inventes datos, precios o testimonios.
@@ -0,0 +1,18 @@
1
+ ---
2
+ id: resumen-y-pendientes
3
+ name: { es: "Resúmenes y pendientes", en: "Summaries and to-dos" }
4
+ line: { es: "Convierte lo largo en lo decidido, lo pendiente y las dudas.", en: "Turns something long into what was decided, what is pending and what is open." }
5
+ icon: list
6
+ when: { es: "La persona pide un resumen, resumir, resume, resúmeme, pendientes, decisiones, puntos importantes, minuta, junta, reunión, notas o ponerse al día con algo largo.", en: "The person asks for a summary, summarize, sum up, to-dos, decisions, key points, minutes, meeting, notes or catching up on something long." }
7
+ version: 1.0.0
8
+ minMadre: 1.1.4
9
+ ---
10
+
11
+ Convierte lo largo en algo que se lee en un minuto.
12
+
13
+ - Empieza con una o dos líneas de qué es y de qué trata.
14
+ - Luego tres apartados cortos, solo los que tengan algo: **Decidido**, **Pendiente** (con quién y para cuándo, si se sabe) y **Dudas** que siguen abiertas.
15
+ - Usa las palabras del documento para lo importante; no inventes fechas, nombres ni compromisos que no estén ahí. Si algo no está claro, dilo como duda.
16
+ - Viñetas de una línea. Nada de párrafos largos.
17
+ - Si el texto es muy largo, avisa qué partes leíste.
18
+ - Al final, ofrece en una línea convertir los pendientes en recordatorios o en un mensaje para mandar.
@@ -0,0 +1,19 @@
1
+ ---
2
+ id: tu-pagina-paso-a-paso
3
+ name: { es: "Tu página, paso a paso", en: "Your website, step by step" }
4
+ line: { es: "Cambia tu página web en pasos pequeños, sin que tengas que programar.", en: "Changes your website in small steps, without you having to code." }
5
+ icon: globe
6
+ when: { es: "La persona quiere hacer o cambiar su página, página web, sitio, tienda en línea, landing, sección, botón, colores, fotos, textos de la página, formulario o que se vea bien en el celular, sin saber programar.", en: "The person wants to make or change their page, website, site, online store, landing, section, button, colours, photos, page texts, form or how it looks on a phone, without knowing how to code." }
7
+ version: 1.0.0
8
+ minMadre: 1.1.4
9
+ ---
10
+
11
+ Quien pide esto no programa: trabaja con su página como lo haría con una diseñadora.
12
+
13
+ - Cambios pequeños y de uno en uno. Antes de tocar un archivo, di en palabras qué va a cambiar en la página («el botón verde de abajo dirá Escríbenos»), no qué línea de código.
14
+ - Después de cada cambio, di cómo verlo: qué página abrir y dónde mirar. Si MADRE puede mostrarla en la vista previa, sugiere abrirla ahí.
15
+ - No cambies el diseño completo si te pidieron un detalle. Si ves algo que convendría arreglar, propónlo al final en una línea, sin hacerlo.
16
+ - Textos de la página: claros, con lo que el visitante busca primero (qué ofreces, precio o cómo pedir, cómo contactar).
17
+ - Si algo puede romper la página (borrar secciones, cambiar la estructura), pide confirmación antes.
18
+ - Nunca pongas datos privados, llaves ni contraseñas en la página.
19
+ - Al terminar, resume en dos o tres viñetas lo que cambió, para que la persona lo pueda revisar.
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@jossuealcala/madre",
3
- "version": "1.1.2",
4
- "description": "MADRE · one local room where the AI coding agents already on your machine (Codex, Claude Code, Gemini CLI, OpenCode) work on your project together, share one memory you can see and explore, and answer to you. Read-only by default, with per-message permission modes and checkpoints you can undo. Nothing leaves your machine on its own.",
3
+ "version": "1.1.4",
4
+ "description": "MADRE · one local room where the AI coding agents already on your machine (Codex, Claude Code, Gemini CLI, Cursor, OpenCode, Grok) work on your project together, share one memory you can see and explore, and answer to you. Read-only by default, with per-message permission modes and checkpoints you can undo. Nothing leaves your machine on its own.",
5
5
  "keywords": [
6
6
  "ai-agents",
7
7
  "codex",
@@ -40,7 +40,10 @@
40
40
  "files": [
41
41
  "bin",
42
42
  "src",
43
+ "!src/madre-logs.mjs",
44
+ "!src/rumbo.mjs",
43
45
  "public",
46
+ "habilidades",
44
47
  "!public/assets/manual/*.pdf",
45
48
  "README.md",
46
49
  "CHANGELOG.md",
@@ -66,8 +69,8 @@
66
69
  "docs/en/training"
67
70
  ],
68
71
  "bin": {
69
- "madre": "./bin/madre.cjs",
70
- "pulse": "./bin/madre.cjs"
72
+ "madre": "bin/madre.cjs",
73
+ "pulse": "bin/madre.cjs"
71
74
  },
72
75
  "engines": {
73
76
  "node": ">=22.5.0"