@jossuealcala/madre 1.1.2 → 1.1.3

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 (101) hide show
  1. package/CHANGELOG.en.md +21 -1
  2. package/CHANGELOG.md +21 -1
  3. package/README.en.md +3 -3
  4. package/README.md +3 -3
  5. package/SECURITY.md +11 -6
  6. package/bin/madre.mjs +74 -11
  7. package/docs/REFERENCE.md +13 -7
  8. package/docs/SDK.md +8 -8
  9. package/docs/en/REFERENCE.md +10 -6
  10. package/docs/en/SDK.md +8 -8
  11. package/docs/en/training/README.md +1 -1
  12. package/docs/sdk/connector-module.mjs +1 -1
  13. package/docs/sdk/hello-module.mjs +1 -1
  14. package/docs/training/README.md +1 -1
  15. package/docs/training/train.sh +3 -0
  16. package/package.json +4 -2
  17. package/public/activity.js +9 -0
  18. package/public/app.js +988 -171
  19. package/public/attribution.js +9 -0
  20. package/public/brands.js +27 -13
  21. package/public/en.js +1 -2
  22. package/public/es.js +834 -257
  23. package/public/index.html +3 -0
  24. package/public/macroverso.js +24 -5
  25. package/public/manual-content.js +32 -2
  26. package/public/market-view.js +116 -9
  27. package/public/market.js +15 -0
  28. package/public/news-scenes.js +185 -0
  29. package/public/notices.js +66 -0
  30. package/public/power.js +1 -1
  31. package/public/resay.js +3 -0
  32. package/public/salas-mac.css +229 -26
  33. package/public/salas-mac.html +3 -0
  34. package/public/salas-mac.js +454 -37
  35. package/public/styles.css +393 -17
  36. package/public/tips.js +124 -0
  37. package/public/tour-chapters.js +75 -75
  38. package/public/tour.js +36 -8
  39. package/public/troubleshooting.js +215 -22
  40. package/public/welcome-scene.js +358 -0
  41. package/public/welcome.js +514 -273
  42. package/src/adapters/gemini-rest.mjs +236 -0
  43. package/src/adapters/gemini.mjs +9 -7
  44. package/src/adapters/grok.mjs +288 -0
  45. package/src/adapters/process.mjs +14 -3
  46. package/src/auth-probe.mjs +32 -0
  47. package/src/bridge/policy.mjs +1 -1
  48. package/src/capabilities.mjs +30 -0
  49. package/src/checkpoint.mjs +115 -1
  50. package/src/codex-route.mjs +113 -0
  51. package/src/credentials.mjs +46 -8
  52. package/src/dataset.mjs +18 -7
  53. package/src/event-store.mjs +10 -2
  54. package/src/ficha.mjs +142 -0
  55. package/src/files.mjs +36 -2
  56. package/src/lease.mjs +5 -0
  57. package/src/market-check.mjs +1 -1
  58. package/src/market-remote.mjs +135 -1
  59. package/src/mcp/image-server.mjs +1 -1
  60. package/src/mcp/memory-server.mjs +10 -0
  61. package/src/memory-tools.mjs +3 -0
  62. package/src/memory.mjs +29 -4
  63. package/src/models.mjs +21 -3
  64. package/src/modules/ahp.mjs +8 -3
  65. package/src/modules/bishop-exam.mjs +41 -12
  66. package/src/modules/bishop.mjs +2 -2
  67. package/src/modules/choices.mjs +12 -10
  68. package/src/modules/fetch-alone.mjs +7 -0
  69. package/src/modules/helpers.mjs +23 -5
  70. package/src/modules/image-studio.mjs +13 -27
  71. package/src/modules/index.mjs +54 -11
  72. package/src/modules/isolated.mjs +160 -0
  73. package/src/modules/ollama.mjs +35 -6
  74. package/src/modules/playwright.mjs +46 -17
  75. package/src/modules/run-alone.mjs +122 -0
  76. package/src/modules/runs.mjs +11 -8
  77. package/src/modules/sdk.mjs +4 -2
  78. package/src/notices-key.mjs +8 -0
  79. package/src/notices.mjs +185 -0
  80. package/src/ollama.mjs +57 -15
  81. package/src/outbound.mjs +45 -8
  82. package/src/room/archivist.mjs +30 -5
  83. package/src/room/busy.mjs +16 -0
  84. package/src/room/control.mjs +36 -6
  85. package/src/room/guard.mjs +32 -2
  86. package/src/room/prompt.mjs +32 -5
  87. package/src/room/vectors.mjs +7 -1
  88. package/src/room.mjs +94 -28
  89. package/src/router.mjs +1 -1
  90. package/src/runs.mjs +39 -0
  91. package/src/runtime-detection.mjs +46 -6
  92. package/src/salas.mjs +151 -15
  93. package/src/server.mjs +577 -80
  94. package/src/service.mjs +116 -0
  95. package/src/setup-trouble.mjs +20 -1
  96. package/src/skill-check.mjs +269 -0
  97. package/src/skills-import.mjs +128 -0
  98. package/src/skills.mjs +492 -0
  99. package/src/tour.mjs +14 -3
  100. package/src/whats-new.mjs +48 -0
  101. package/src/rumbo.mjs +0 -337
package/src/skills.mjs ADDED
@@ -0,0 +1,492 @@
1
+ // SPDX-License-Identifier: BUSL-1.1
2
+ // MADRE · © 2026 Jossue Alcalá · Business Source License 1.1: LICENSE
3
+ // SKILLS (2026-11-08, H-1 of docs/private/HABILIDADES-MERCADO.md). A skill is a way of working that
4
+ // MADRE hands to whichever agent answers. A module adds buttons and pages and runs on this computer;
5
+ // a skill only tells an agent how to do something — and because MADRE is the one that writes the
6
+ // prompt (src/room/prompt.mjs), the same skill works on all six agents. A skill of Claude's works
7
+ // only in Claude; Codex has its own prompts, Gemini its commands, OpenCode its agents. MADRE already
8
+ // keeps every one of those out of a turn on purpose (--setting-sources '' and no Skill tool for
9
+ // Claude, --pure for OpenCode, --ephemeral for Codex, SKILLS_ENABLED=false for Grok), so what a
10
+ // person already had never reached the room. This is the hole that fills.
11
+ //
12
+ // <folder>/<id>/HABILIDAD.md its header and its instructions. SKILL.md is read the same way, so
13
+ // a skill a person already has is imported without being rewritten.
14
+ // <folder>/<id>/referencias/ what the agent reads when it needs it: templates, examples, data.
15
+ // <folder>/<id>/guiones/ what an agent MAY RUN, and only at #4.
16
+ //
17
+ // Two folders, the same two a module has: ~/.pulse/habilidades (every project) and
18
+ // <project>/.madre/habilidades (this one). Agents never write in either — .madre/ is a forbidden
19
+ // zone and ~/.pulse lives outside every project — so a skill is proposed by an agent and installed
20
+ // by the person, like a module.
21
+ //
22
+ // WHAT CONTAINS A SKILL. The body travels in the prompt, so it is capped: what does not fit goes in
23
+ // referencias/ and the agent reads it when it needs it, which is how skills work everywhere. A
24
+ // script is never run by MADRE: an agent runs it, with the permission of its turn, so below #4 no
25
+ // agent can run anything at all and every script is inert on its own. Nothing is read from outside
26
+ // the skill's own folder: no symlinks, no paths that climb out, no hidden files.
27
+
28
+ import { lstat, mkdir, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
29
+ import { basename, dirname, join, relative, resolve, sep } from 'node:path';
30
+ import { fileURLToPath } from 'node:url';
31
+ import { t } from './i18n.mjs';
32
+
33
+ export const SKILL_FILES = ['HABILIDAD.md', 'SKILL.md'];
34
+ // A file an agent wrote that means «install me as a skill»: <id>.habilidad.md, as a module's own is
35
+ // <id>.module.mjs (src/modules/index.mjs). The agent writes it in its draft folder and cannot
36
+ // install it: the person does, from the room.
37
+ export const isSkillFile = (path) => /\.habilidad\.md$/i.test(String(path ?? ''));
38
+ export const skillIdOf = (path) => String(path ?? '').split(/[\\/]/).pop().replace(/\.habilidad\.md$/i, '');
39
+ // Where the guide an agent writing a skill is pointed at lives in this installation.
40
+ export const skillGuide = () => fileURLToPath(new URL('../docs/HABILIDADES.md', import.meta.url));
41
+ export const ID = /^[a-z][a-z0-9-]{1,39}$/;
42
+ const SEMVER = /^\d+\.\d+\.\d+$/;
43
+ // The body is in every turn this skill enters, so it is the one thing with a tight cap: about two
44
+ // thousand tokens. A skill with more to say puts it in referencias/ and points at it.
45
+ export const MAX_BODY = 8000;
46
+ // `when` never travels in the prompt — only the body does — so its only cost is the matching, and a
47
+ // truncated trigger loses exactly the half that matters: the «and NOT when…» at the end. Measured
48
+ // against the skills on a real computer (H-7, 2026-11-08), where Claude's run to about 900.
49
+ export const MAX_WHEN = 1000;
50
+ export const MAX_NAME = 60;
51
+ // What a skill may weigh ON THIS DISK, which is a different question from what may travel through
52
+ // the Market (src/market-remote.mjs keeps its own, tighter bound: one signed download each). The
53
+ // real ones measured on 2026-11-08 reach 61 files and 1158 KB — Claude's xlsx, pptx and docx carry
54
+ // their own libraries — and refusing those on a number nobody had measured would have been a guess
55
+ // dressed as a rule.
56
+ export const MAX_FILES = 200;
57
+ export const MAX_BYTES = 4 * 1024 * 1024;
58
+ // And what may be SENT to the Market: there each file is a download of its own, signed and pinned.
59
+ export const MARKET_MAX_FILES = 40;
60
+ // What an agent could run, and therefore what only #4 could ever reach. Read from the name, and
61
+ // from the executable bit for anything else.
62
+ const RUNNABLE = /\.(?:sh|bash|zsh|py|rb|pl|mjs|cjs|js|ts)$/i;
63
+ // Read from the name alone, for a file that is not on this disk yet (the Market's, H-4). On disk the
64
+ // executable bit counts too (readSkillFiles).
65
+ export const runnable = (path) => RUNNABLE.test(String(path ?? ''));
66
+
67
+ // Whether a skill may carry a file at this path. The paths come from outside MADRE — a file the
68
+ // person dropped in, an entry of the Market's catalog — so they are checked before anything is
69
+ // written: nothing climbs out, nothing is absolute, nothing hides.
70
+ export const safePath = (path) => {
71
+ const said = String(path ?? '');
72
+ if (!said || said.length > 200 || said.startsWith('/') || said.startsWith('\\')) return false;
73
+ if (/(?:^|[\\/])\.\.(?:[\\/]|$)/.test(said)) return false;
74
+ return said.split(/[\\/]/).every((part) => part && !part.startsWith('.'));
75
+ };
76
+
77
+ export const skillFolders = ({ stateRoot, projectRoot }) => ({
78
+ user: join(stateRoot, 'habilidades'),
79
+ project: join(projectRoot, '.madre', 'habilidades'),
80
+ });
81
+
82
+ // The header between the first two «---» lines, one «key: value» per line, as a skill of Claude's
83
+ // has it and as madre-logs has it. A value may be plain, quoted, or the two languages at once:
84
+ // `name: { es: "Cotizaciones", en: "Quotes" }`.
85
+ export function readHeader(text) {
86
+ const match = String(text ?? '').match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
87
+ if (!match) return null;
88
+ const fields = {};
89
+ for (const line of match[1].split(/\r?\n/)) {
90
+ const at = line.indexOf(':');
91
+ if (at <= 0 || /^\s/.test(line)) continue;
92
+ fields[line.slice(0, at).trim()] = line.slice(at + 1).trim();
93
+ }
94
+ return fields;
95
+ }
96
+ export const bodyOf = (text) => String(text ?? '').replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n?/, '').trim();
97
+
98
+ const unquote = (value) => String(value ?? '').trim().replace(/^(["'])([\s\S]*)\1$/, '$2').trim();
99
+ // One word or the two languages. `{ es: "…", en: "…" }` is read without a YAML reader: a header is
100
+ // one line per field and this is the only shape of value that is not plain text.
101
+ export function words(value, max) {
102
+ const said = String(value ?? '').trim();
103
+ if (!said) return null;
104
+ if (said.startsWith('{')) {
105
+ const out = {};
106
+ for (const lang of ['es', 'en']) {
107
+ const hit = said.match(new RegExp(`\\b${lang}\\s*:\\s*(?:"([^"]*)"|'([^']*)'|([^,}]*))`));
108
+ const one = unquote(hit?.[1] ?? hit?.[2] ?? hit?.[3] ?? '');
109
+ if (one) out[lang] = one.slice(0, max);
110
+ }
111
+ return Object.keys(out).length ? out : null;
112
+ }
113
+ return unquote(said).slice(0, max) || null;
114
+ }
115
+ // Who made it: a name, or `{ name: "Ana Ruiz", github: "anaruiz" }`. The name is what the Market
116
+ // shows; the GitHub user is only how a pull request is signed, so it is read and never demanded.
117
+ export function author(value) {
118
+ const said = unquote(value ?? '');
119
+ if (!said) return null;
120
+ if (!said.startsWith('{')) return { name: said.slice(0, MAX_NAME), github: null };
121
+ const of = (key) => {
122
+ const hit = said.match(new RegExp(`\\b${key}\\s*:\\s*(?:"([^"]*)"|'([^']*)'|([^,}]*))`));
123
+ return unquote(hit?.[1] ?? hit?.[2] ?? hit?.[3] ?? '') || null;
124
+ };
125
+ const name = of('name') ?? of('nombre');
126
+ return name ? { name: name.slice(0, MAX_NAME), github: of('github') } : null;
127
+ }
128
+
129
+ // Whichever language the room speaks, for a name that may be one word or two.
130
+ export const pick = (value, language = 'es') => (value && typeof value === 'object' ? value[language] ?? value.es ?? value.en ?? null : value ?? null);
131
+
132
+ // WHAT A SKILL DECLARES. English keys, as a module's contract has them, with the Spanish ones a
133
+ // person writing by hand will reach for, and the ones a skill of Claude's already carries:
134
+ // `description` is its `when`. MADRE's own words are in English and the room speaks the person's
135
+ // language (src/i18n.mjs), here as everywhere.
136
+ // The last four are only needed to PUBLISH one (src/skill-check.mjs, H-5): what the Market shows.
137
+ // A skill is one file, so they live in its own header — asking for a second file with the same
138
+ // facts in JSON is work for whoever sends it and one more place for the two to disagree.
139
+ const KEYS = {
140
+ id: ['id'], name: ['name', 'nombre'], when: ['when', 'cuando', 'description'],
141
+ version: ['version', 'versión'], minMadre: ['minMadre', 'minmadre'],
142
+ credit: ['credit', 'credito', 'crédito'], license: ['license', 'licencia'],
143
+ line: ['line', 'linea', 'línea'], summary: ['summary', 'resumen'], shelf: ['shelf', 'estante'],
144
+ author: ['author', 'autor', 'autora'],
145
+ };
146
+ export const KNOWN = new Set(Object.values(KEYS).flat());
147
+ const field = (fields, key) => KEYS[key].map((name) => fields[name]).find((value) => String(value ?? '').trim());
148
+
149
+ // One skill read from its text, with what is wrong said in words the person can act on. The id is
150
+ // the folder's name when the header does not say one, so importing a skill of Claude's — which
151
+ // names no id — works as it is.
152
+ export function readSkillText(text, { id = null } = {}) {
153
+ const fields = readHeader(text);
154
+ if (!fields) throw new Error(t('A skill starts with its header between two «---» lines: id, name and when it is for.'));
155
+ const said = unquote(field(fields, 'id') ?? '') || String(id ?? '');
156
+ if (!ID.test(said)) throw new Error(t('«{id}» is not a name MADRE can use for a skill: lowercase letters, numbers and dashes, 2 to 40, starting with a letter.', { id: said || '—' }));
157
+ const body = bodyOf(text);
158
+ if (!body) throw new Error(t('The skill says nothing: under the header go the instructions the agents will read.'));
159
+ if (body.length > MAX_BODY) throw new Error(t('The skill is too long ({has} characters, at most {max}). What does not fit goes in referencias/, and the instructions point at it: the agent reads it when it needs it.', { has: body.length, max: MAX_BODY }));
160
+ const version = unquote(field(fields, 'version') ?? '');
161
+ if (version && !SEMVER.test(version)) throw new Error(t('version: like 1.0.0.'));
162
+ const minMadre = unquote(field(fields, 'minMadre') ?? '');
163
+ if (minMadre && !SEMVER.test(minMadre)) throw new Error(t('minMadre: the oldest MADRE it works with, like 1.1.0.'));
164
+ return {
165
+ id: said,
166
+ name: words(field(fields, 'name'), MAX_NAME) ?? said,
167
+ // Without it, the skill only ever enters a turn because the person turned it on.
168
+ when: words(field(fields, 'when'), MAX_WHEN),
169
+ version: version || null,
170
+ minMadre: minMadre || null,
171
+ credit: words(field(fields, 'credit'), MAX_NAME),
172
+ license: unquote(field(fields, 'license') ?? '') || null,
173
+ // Only for the Market, and only when it is going there (H-5).
174
+ line: words(field(fields, 'line'), 140),
175
+ summary: words(field(fields, 'summary'), 1200),
176
+ shelf: unquote(field(fields, 'shelf') ?? '') || null,
177
+ author: author(field(fields, 'author')),
178
+ body,
179
+ // Said, never ignored in silence, as a module's unknown fields are said when it is installed.
180
+ unknown: Object.keys(fields).filter((key) => !KNOWN.has(key)),
181
+ };
182
+ }
183
+
184
+ // EVERY FILE OF A SKILL, and nothing else. A link is not followed and a file that is not under the
185
+ // skill's own folder is not read: a skill travels, and what travels names its own paths.
186
+ export async function readSkillFiles(dir, { maxFiles = MAX_FILES, maxBytes = MAX_BYTES } = {}) {
187
+ const root = resolve(dir);
188
+ const files = [];
189
+ let bytes = 0;
190
+ const walk = async (at) => {
191
+ for (const entry of (await readdir(at, { withFileTypes: true }).catch(() => []))) {
192
+ if (entry.name.startsWith('.')) continue;
193
+ const path = join(at, entry.name);
194
+ const info = await lstat(path).catch(() => null);
195
+ if (!info) continue;
196
+ if (info.isSymbolicLink()) throw new Error(t('{file} is a link, and a skill carries only its own files.', { file: relative(root, path) }));
197
+ const inside = resolve(path);
198
+ if (inside !== root && !inside.startsWith(root + sep)) throw new Error(t('{file} is outside the skill\'s folder.', { file: entry.name }));
199
+ if (info.isDirectory()) { await walk(path); continue; }
200
+ if (!info.isFile()) continue;
201
+ files.push({ path: relative(root, path), bytes: info.size, runs: RUNNABLE.test(entry.name) || Boolean(info.mode & 0o111) });
202
+ bytes += info.size;
203
+ if (files.length > maxFiles) throw new Error(t('A skill carries at most {max} files.', { max: maxFiles }));
204
+ if (bytes > maxBytes) throw new Error(t('A skill weighs at most {max} KB.', { max: Math.round(maxBytes / 1024) }));
205
+ }
206
+ };
207
+ await walk(root);
208
+ return { files: files.sort((a, b) => a.path.localeCompare(b.path)), bytes };
209
+ }
210
+
211
+ // One skill from a folder on this computer: its text, its files, and the scripts an agent could only
212
+ // ever run at #4. Nothing is run here, and nothing is installed: asking what a folder is must not
213
+ // change anything.
214
+ export async function readSkill(dir, { origin = null } = {}) {
215
+ const root = resolve(dir);
216
+ let text = null;
217
+ let from = null;
218
+ for (const candidate of SKILL_FILES) {
219
+ text = await readFile(join(root, candidate), 'utf8').catch(() => null);
220
+ if (text !== null) { from = candidate; break; }
221
+ }
222
+ if (text === null) throw new Error(t('{folder} has no {file}.', { folder: basename(root), file: SKILL_FILES[0] }));
223
+ const skill = readSkillText(text, { id: basename(root) });
224
+ const { files, bytes } = await readSkillFiles(root);
225
+ return { ...skill, dir: root, file: join(root, from), origin, files, bytes, scripts: files.filter((one) => one.runs).map((one) => one.path) };
226
+ }
227
+
228
+ // WHAT A SKILL SAYS IT DOES, for the person to read before accepting it (H-3). Only what is there:
229
+ // when it says it is for, how long what it tells the agents is, what it carries, and every script —
230
+ // because a script is the one thing that could ever run, and only at #4.
231
+ export const declaredBy = (skill) => ({
232
+ when: skill.when ?? null,
233
+ chars: skill.body.length,
234
+ files: skill.files.length,
235
+ references: skill.files.filter((one) => !one.runs).map((one) => one.path),
236
+ scripts: skill.scripts,
237
+ credit: skill.credit ?? null,
238
+ license: skill.license ?? null,
239
+ });
240
+
241
+ // Every skill of both folders, newest reading each time. One that cannot be read is left out with
242
+ // why, as a module that fails to load is: a bad skill never keeps the others out of the room.
243
+ export async function loadSkills({ stateRoot, projectRoot }) {
244
+ const folders = skillFolders({ stateRoot, projectRoot });
245
+ const loaded = [];
246
+ const failures = [];
247
+ for (const [origin, dir] of Object.entries(folders)) {
248
+ for (const entry of (await readdir(dir, { withFileTypes: true }).catch(() => []))) {
249
+ if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
250
+ const at = join(dir, entry.name);
251
+ try {
252
+ const skill = await readSkill(at, { origin });
253
+ // A skill of this project stands in for one of the same name from every project, the way
254
+ // installing a newer copy of a module replaces it.
255
+ const already = loaded.findIndex((one) => one.id === skill.id);
256
+ if (already >= 0) loaded[already] = skill; else loaded.push(skill);
257
+ } catch (error) {
258
+ failures.push({ dir: at, origin, error: error.message });
259
+ }
260
+ }
261
+ }
262
+ return { loaded: loaded.sort((a, b) => a.id.localeCompare(b.id)), failures, folders };
263
+ }
264
+
265
+ // INSTALLING ONE. The files are checked before a single one is written, and written to a folder of
266
+ // the skill's own name: a skill is never spread over the folder of another. `files` is what the
267
+ // person accepted — its text and whatever came with it — each path relative to the skill's folder.
268
+ export async function installSkill({ files, scope = 'user', stateRoot, projectRoot, source = null }) {
269
+ const main = files.find((one) => SKILL_FILES.includes(one.path));
270
+ if (!main) throw new Error(t('A skill needs its {file}.', { file: SKILL_FILES[0] }));
271
+ const folders = skillFolders({ stateRoot, projectRoot });
272
+ const dir = folders[scope === 'project' ? 'project' : 'user'];
273
+ const skill = readSkillText(main.text ?? main.content ?? '', { id: source?.id ?? null });
274
+ if (files.length > MAX_FILES) throw new Error(t('A skill carries at most {max} files.', { max: MAX_FILES }));
275
+ const safe = [];
276
+ let bytes = 0;
277
+ for (const one of files) {
278
+ const path = String(one.path ?? '');
279
+ if (!safePath(path)) throw new Error(t('{file} is not a path a skill may carry.', { file: path || '—' }));
280
+ const text = one.text ?? one.content ?? '';
281
+ const data = Buffer.isBuffer(text) ? text : Buffer.from(String(text), 'utf8');
282
+ bytes += data.length;
283
+ if (bytes > MAX_BYTES) throw new Error(t('A skill weighs at most {max} KB.', { max: Math.round(MAX_BYTES / 1024) }));
284
+ safe.push({ path, data });
285
+ }
286
+ // Written beside it and moved into place at the end: a write that fails halfway must not leave
287
+ // the person without the skill they had.
288
+ const target = join(dir, skill.id);
289
+ const fresh = `${target}.nuevo`;
290
+ await rm(fresh, { recursive: true, force: true }).catch(() => {});
291
+ try {
292
+ for (const one of safe) {
293
+ await mkdir(dirname(join(fresh, one.path)), { recursive: true });
294
+ await writeFile(join(fresh, one.path), one.data);
295
+ }
296
+ if (source) await writeFile(join(fresh, 'origen.json'), `${JSON.stringify({ ...source, at: new Date().toISOString(), version: skill.version ?? null }, null, 2)}\n`);
297
+ await rm(target, { recursive: true, force: true }).catch(() => {});
298
+ await rename(fresh, target);
299
+ } catch (error) {
300
+ await rm(fresh, { recursive: true, force: true }).catch(() => {});
301
+ throw error;
302
+ }
303
+ return { ...(await readSkill(target, { origin: scope === 'project' ? 'project' : 'user' })), installed: true };
304
+ }
305
+
306
+ // Removing one is the person's, as removing a module is: the folder goes, and nothing a skill's
307
+ // scripts may have written elsewhere is touched.
308
+ export async function removeSkill({ id, stateRoot, projectRoot }) {
309
+ if (!ID.test(String(id ?? ''))) throw new Error(t('No skill «{id}».', { id }));
310
+ const folders = skillFolders({ stateRoot, projectRoot });
311
+ const removed = [];
312
+ for (const dir of [folders.project, folders.user]) {
313
+ const target = join(dir, id);
314
+ if (!(await lstat(target).catch(() => null))?.isDirectory()) continue;
315
+ await rm(target, { recursive: true, force: true });
316
+ removed.push(target);
317
+ }
318
+ if (!removed.length) throw new Error(t('No skill «{id}».', { id }));
319
+ return { id, removed };
320
+ }
321
+
322
+ // ---- WHICH SKILLS A TURN GETS (H-2). Two ways, and the person decides which per skill:
323
+ //
324
+ // always the person turned it on here, so it is in every turn of this project.
325
+ // match the default: it enters when what was asked looks like what its `when` describes.
326
+ // off it is kept, and it enters nothing.
327
+ //
328
+ // MATCHED BY WORDS, not by meaning. A word match is free, works with no internet and no model, is
329
+ // the same every time, and — this is what decided it — it can be SHOWN: the room can say «this
330
+ // entered because you said “cotización”», which a number from an embedder cannot. A meaning pass
331
+ // is worth having on top, and it waits for a cutoff measured against real use rather than guessed
332
+ // (the recall's cut was measured; this one would not be). `nearness` is where it will plug in.
333
+ //
334
+ // Every skill's own words count against one budget, so however many match, a turn pays about what
335
+ // one skill costs and never more. The person's own «always» are seated first: their word before
336
+ // MADRE's guess.
337
+
338
+ // Words that say nothing about which skill is wanted. The ones almost every `when` carries are in
339
+ // here on purpose: without them, «cuando el usuario pide algo» would match every message.
340
+ const STOP = new Set(`
341
+ a acerca al algo alguien algun alguna alguno ante antes aqui asi aun cada como con contra cual
342
+ cuando cuanto de del desde donde dos el ella ellas ellos en entre era eran eres es esa ese eso
343
+ esta estan este esto estos favor hace hacer hacia hasta hay las les lo los mas mientras muy nada
344
+ ni nos nuestra nuestro para pero pide piden pides poco por porque pues que quien quiere quieren
345
+ quieres saber se sea segun ser si sin sobre solo son su sus tal tambien tiene tienen todo todos
346
+ tras una uno unos usa usar usuario ver vez vos
347
+ about after all almost already also always and any anyone anything are ask asked asking asks
348
+ because been before being between both but can cannot does doing done down each else even every
349
+ everything first for from gets getting give given goes going has have having her him his how
350
+ however into its just like made make makes making many may more most much must need needs never
351
+ not now off once one only onto other our out over own same she should since some something such
352
+ than that the their them then there these they this those through thus too under until use used
353
+ user users uses using very wants want was were what when where which while who whom why will with
354
+ within without would you your
355
+ `.trim().split(/\s+/));
356
+ const NO_MARKS = /\p{M}/gu;
357
+ export const MIN_WORD = 4;
358
+ // How many skills one turn may carry, before the budget has anything to say. Three is already more
359
+ // than a person keeps in their head about one request.
360
+ export const MAX_PER_TURN = 3;
361
+
362
+ // The words of a sentence that could tell one skill from another: no accents, no punctuation, no
363
+ // words everybody uses. Short ones are dropped, with two exceptions that carry a whole request on
364
+ // their own: anything with a digit in it («1099», «#4») and a word written in capitals, which is
365
+ // how a person writes the acronym their work turns on — IVA, SAT, RFC, PDF, SEO, API.
366
+ export function keywords(text) {
367
+ const out = new Set();
368
+ for (const raw of String(text ?? '').split(/[^\p{L}\p{N}_-]+/u)) {
369
+ if (!raw) continue;
370
+ const word = raw.normalize('NFD').replace(NO_MARKS, '').toLowerCase();
371
+ if (!word || STOP.has(word)) continue;
372
+ if (word.length >= MIN_WORD || /\d/.test(word) || (word.length >= 3 && raw === raw.toUpperCase())) out.add(word);
373
+ }
374
+ return out;
375
+ }
376
+
377
+ // Only the words that are words, as a module's switch keeps only the booleans (module-scope.mjs).
378
+ export const roomsIn = (block = {}) => Object.fromEntries(Object.entries(block?.rooms ?? {}).filter(([id, said]) => /^[\w.:-]{1,200}$/.test(id) && SKILL_STATES.includes(said)));
379
+
380
+ // The block written when a skill's switch moves. From Home, with no project, it is the word for
381
+ // every project and each project follows it again; from a project, that project's own word, which
382
+ // wins. The whole block, because updateConfig merges one level down.
383
+ export function skillStateIn(block = {}, roomId = null, state) {
384
+ if (!SKILL_STATES.includes(state)) throw new Error(t('A skill is off, matched or always on; nothing else.'));
385
+ if (!roomId) return { ...block, state, rooms: {} };
386
+ return { ...block, rooms: { ...roomsIn(block), [roomId]: state } };
387
+ }
388
+
389
+ // What the person said about this skill, in this project. The shape is the one a module's switch
390
+ // has (src/module-scope.mjs): a word for every project, and a project's own word that wins.
391
+ export const SKILL_STATES = ['off', 'match', 'always'];
392
+ export function skillState(config = {}, id = null, roomId = null) {
393
+ const block = config?.skills?.[id] ?? {};
394
+ const own = roomId ? block?.rooms?.[roomId] : null;
395
+ return SKILL_STATES.includes(own) ? own : SKILL_STATES.includes(block?.state) ? block.state : 'match';
396
+ }
397
+
398
+ // The skills this turn carries, in the order they will be read, each with why it is here.
399
+ // `nearness(skill, text)` is the meaning pass when there is one: a number from 0 to 1, consulted
400
+ // only for a skill no word matched, and only above `near`.
401
+ export function chooseSkills({ skills = [], text = '', config = {}, roomId = null, budget = MAX_BODY, limit = MAX_PER_TURN, nearness = null, near = 1 } = {}) {
402
+ const asked = keywords(text);
403
+ const seats = [];
404
+ for (const skill of skills) {
405
+ const state = skillState(config, skill.id, roomId);
406
+ if (state === 'off') continue;
407
+ if (state === 'always') { seats.push({ skill, state, why: [], score: Infinity }); continue; }
408
+ if (!skill.when) continue; // nothing to match on: only «always» ever seats it
409
+ const why = [...keywords(pick(skill.when, 'es') ?? skill.when)].filter((word) => asked.has(word));
410
+ const close = why.length ? 1 : typeof nearness === 'function' ? Number(nearness(skill, text)) || 0 : 0;
411
+ if (!why.length && !(close >= near && near <= 1)) continue;
412
+ seats.push({ skill, state, why, score: why.length || close });
413
+ }
414
+ seats.sort((a, b) => (b.score - a.score) || a.skill.id.localeCompare(b.skill.id));
415
+ const chosen = [];
416
+ let chars = 0;
417
+ for (const seat of seats) {
418
+ if (chosen.length >= limit) break;
419
+ if (chars + seat.skill.body.length > budget && chosen.length) break;
420
+ chars += seat.skill.body.length;
421
+ chosen.push({ ...seat.skill, state: seat.state, why: seat.why });
422
+ }
423
+ return { chosen, left: seats.slice(chosen.length).map((seat) => seat.skill.id), chars };
424
+ }
425
+
426
+ // ---- THE SKILLS OF ONE TURN, WRITTEN FOR THE AGENT (H-2). Model-facing, so it is in English like
427
+ // the rest of a briefing (src/room/prompt.mjs) and never goes through the catalogue.
428
+ //
429
+ // A skill carries files MADRE does not hand over: its folder lives outside the project, and whether
430
+ // an agent may read there is its own CLI's answer, not MADRE's. So the files are named with their
431
+ // folder and the agent is told what to do when it cannot reach them, which is true for every agent
432
+ // instead of being a promise only some keep.
433
+ const english = (value) => (value && typeof value === 'object' ? value.en ?? value.es ?? null : value ?? null);
434
+ const attribute = (value) => String(value ?? '').replace(/[<>"&\n]/g, ' ').trim().slice(0, 240);
435
+
436
+ export function formatSkills(skills = [], { mode = 1 } = {}) {
437
+ const lines = [];
438
+ for (const skill of skills) {
439
+ const why = skill.state === 'always' ? 'the human turned it on for this project' : skill.why?.length ? `the human said: ${skill.why.join(', ')}` : 'it matches what was asked';
440
+ lines.push(`<skill name="${attribute(english(skill.name) ?? skill.id)}" why="${attribute(why)}">`);
441
+ lines.push(skill.body.trim());
442
+ const carried = (skill.files ?? []).filter((one) => !one.runs && !SKILL_FILES.includes(one.path)).map((one) => one.path);
443
+ if (carried.length) lines.push(`It carries ${carried.join(', ')}, in ${skill.dir}: read one when its instructions point at it. If you cannot reach that folder, say so in one line rather than guessing, and the human will attach what you need.`);
444
+ if (skill.scripts?.length) {
445
+ lines.push(mode === 4
446
+ ? `It carries ${skill.scripts.join(', ')}, in ${skill.dir}: you may run one this turn, and as with any command, say in one line what it does before you do.`
447
+ : `It carries ${skill.scripts.join(', ')}, which nothing runs in this mode: #4 AIRLOCK is the only turn that could, so do not try and do not ask the human to run one for you unless its instructions depend on it.`);
448
+ }
449
+ lines.push('</skill>');
450
+ }
451
+ return lines.join('\n');
452
+ }
453
+
454
+ // ---- SHARING ONE, HAND TO HAND (2026-11-08, C-1). The Market is the curated road: the author of
455
+ // MADRE reads a skill, signs it, and every MADRE can get it and be told when it is taken back. This
456
+ // is the other road, the one things actually travel on: somebody sends a colleague the file that
457
+ // solved their afternoon.
458
+ //
459
+ // What is prepared is the skill as it is, without MADRE's own record of where it came from, in a
460
+ // folder of its own so the person can find it. A skill of ONE file is written as `<id>.habilidad.md`
461
+ // — the same name an agent writes and the room already recognises — so the other side only has to
462
+ // drag it in. One that carries more says so: those files travel together or not at all, and nothing
463
+ // here builds an archive, because MADRE has nothing that opens one.
464
+ //
465
+ // Decided by the author on 2026-11-08: SKILLS ONLY. A module hand to hand would be code running with
466
+ // the permissions of whoever installed it, with nobody having read it.
467
+ export const shareFolder = (stateRoot, id) => join(stateRoot, 'compartir', id);
468
+ export async function shareSkill({ stateRoot, projectRoot, id }) {
469
+ const { loaded } = await loadSkills({ stateRoot, projectRoot });
470
+ const skill = loaded.find((one) => one.id === id);
471
+ if (!skill) throw new Error(t('No skill «{id}».', { id }));
472
+ const folder = shareFolder(stateRoot, id);
473
+ await rm(folder, { recursive: true, force: true }).catch(() => {});
474
+ await mkdir(folder, { recursive: true });
475
+ const carried = skill.files.filter((file) => file.path !== 'origen.json');
476
+ const alone = carried.length === 1 && SKILL_FILES.includes(carried[0].path);
477
+ const written = [];
478
+ for (const file of carried) {
479
+ // Alone, it travels under the name the other side knows; with company, under its own.
480
+ const name = alone ? `${skill.id}.habilidad.md` : file.path;
481
+ const to = join(folder, name);
482
+ await mkdir(dirname(to), { recursive: true });
483
+ await writeFile(to, await readFile(join(skill.dir, file.path)));
484
+ written.push(name);
485
+ }
486
+ return {
487
+ id: skill.id, folder, files: written, alone,
488
+ // What the other side will not get, said here and not discovered there.
489
+ scripts: skill.scripts,
490
+ file: alone ? join(folder, written[0]) : null,
491
+ };
492
+ }
package/src/tour.mjs CHANGED
@@ -51,7 +51,9 @@ export const HINTS = ['switch', 'links', 'key4',
51
51
  'guide-code', 'guide-manual', 'home-coordinator', 'home-manual',
52
52
  'new-code-ask', 'new-notes', 'new-connectors', 'new-manual',
53
53
  // The two drawings of a map, planets and neurons (2026-10-28): said once, by the key that switches them.
54
- 'map-views'];
54
+ 'map-views',
55
+ // The first press of the main keys (1.1, 2026-11-08): Home's and a project's.
56
+ 'home-activity', 'home-market', 'home-modules', 'home-agents', 'touch-activity', 'touch-attach', 'touch-options', 'touch-copilot'];
55
57
  const PATHS = ['new', 'back', 'since'];
56
58
  // The news this code knows (2026-10-21): written on the bonjour as the version a person MET MADRE
57
59
  // with (`met`). The cards of what is new are for whoever met it before a version; someone who meets
@@ -65,8 +67,12 @@ const BEFORE = ['1.0'];
65
67
  // ready after `npx madre` — agents, local AI, memory, the first project — in their order. Where the
66
68
  // person is, what they finished and what they left for later are kept here too, so closing the page
67
69
  // halfway brings them back to the same step, from whichever project or port they open next.
68
- export const WELCOME_STEPS = ['hello', 'machine', 'agents', 'project', 'ai', 'memory', 'ready'];
69
- const freshWelcome = () => ({ at: null, done: [], skipped: [], finished: null });
70
+ // 1.1 (2026-11-08, docs/private/BIENVENIDA-1.1.md): six steps. What the computer is goes into the
71
+ // greeting and the memory into the local AI; «what it is for» comes in, and is kept as `profile`, so
72
+ // the examples MADRE gives are this person's and not a programmer's.
73
+ export const WELCOME_STEPS = ['hello', 'use', 'agents', 'project', 'ai', 'ready'];
74
+ export const WELCOME_PROFILES = ['business', 'numbers', 'code', 'notes', 'curious'];
75
+ const freshWelcome = () => ({ at: null, done: [], skipped: [], finished: null, profile: [] });
70
76
  const fresh = (before = null) => ({ version: TOUR_VERSION, path: null, bonjourAt: null, done: [], at: null, closed: false, finished: null, hints: {}, held: null, before, met: null, welcome: freshWelcome() });
71
77
  // A tab that shows the bonjour or the chapters says so every few seconds; another tab that finds it
72
78
  // said within this long tells the person it is open there, instead of a second bonjour.
@@ -100,6 +106,7 @@ export async function readTour(stateRoot) {
100
106
  done: Array.isArray(raw.welcome?.done) ? WELCOME_STEPS.filter((id) => raw.welcome.done.includes(id)) : [],
101
107
  skipped: Array.isArray(raw.welcome?.skipped) ? WELCOME_STEPS.filter((id) => raw.welcome.skipped.includes(id)) : [],
102
108
  finished: iso(raw.welcome?.finished),
109
+ profile: Array.isArray(raw.welcome?.profile) ? WELCOME_PROFILES.filter((id) => raw.welcome.profile.includes(id)) : [],
103
110
  },
104
111
  };
105
112
  }
@@ -165,6 +172,10 @@ async function applyChange(stateRoot, change, now) {
165
172
  if (said.done !== undefined) mark('done', 'skipped', said.done);
166
173
  if (said.skipped !== undefined) mark('skipped', 'done', said.skipped);
167
174
  if (said.finished === true) state.welcome.finished ??= at;
175
+ if (said.profile !== undefined) {
176
+ if (!Array.isArray(said.profile) || said.profile.some((id) => !WELCOME_PROFILES.includes(id))) return { error: 'profile' };
177
+ state.welcome.profile = WELCOME_PROFILES.filter((id) => said.profile.includes(id));
178
+ }
168
179
  }
169
180
  return writeTour(stateRoot, state);
170
181
  }
package/src/whats-new.mjs CHANGED
@@ -31,6 +31,54 @@ const FILE = 'whats-new.json';
31
31
  export const NEWS_ACTIONS = ['settings', 'errors', 'mother', 'intents', 'permissions', 'github', 'bar', 'modules', 'nostromo', 'room', 'looks', 'finder'];
32
32
 
33
33
  export const NOTES = {
34
+ // 1.1.3 (borrador del 2026-11-08, por aprobar): said as a person would to someone who comes back,
35
+ // with the three things that change their day, each with its own moving picture (`scene`, drawn by
36
+ // public/welcome-scene.js) instead of a screenshot.
37
+ '1.1.3': {
38
+ title: { es: 'Qué bueno verte de nuevo', en: 'Good to see you again' },
39
+ intro: {
40
+ es: 'Mientras no estabas, MADRE aprendió tres cosas que te ahorran tiempo desde hoy.',
41
+ en: 'While you were away, MADRE learned three things that save you time from today.',
42
+ },
43
+ items: [
44
+ {
45
+ id: 'skills',
46
+ icon: 'chip',
47
+ scene: 'skills',
48
+ title: { es: 'Enséñale una vez cómo trabajas', en: 'Teach it once how you work' },
49
+ body: {
50
+ es: 'Con las habilidades, tu forma de cotizar, de escribir o de revisar queda escrita una vez y la usan todas tus IAs, sea Claude, Codex o Grok. Trae las que ya tienes, consigue más en el Mercado o compártelas.',
51
+ en: 'With skills, the way you quote, write or review is written once and all your AIs use it, be it Claude, Codex or Grok. Bring the ones you already have, get more in the Market, or share them.',
52
+ },
53
+ where: { es: 'Mercado › Habilidades', en: 'Market › Skills' },
54
+ action: null,
55
+ },
56
+ {
57
+ id: 'grok',
58
+ icon: 'ufo',
59
+ scene: 'newagent',
60
+ title: { es: 'Grok, ahora entre tus IAs', en: 'Grok, now among your AIs' },
61
+ body: {
62
+ es: 'Si pagas SuperGrok, ya lo usas en tus proyectos: se conecta desde Ajustes › Agentes con tu cuenta, y lee, escribe, busca en internet y hace imágenes.',
63
+ en: 'If you pay for SuperGrok, you can now use it in your projects: it connects from Settings › Agents with your account, and it reads, writes, looks things up on the internet and makes images.',
64
+ },
65
+ where: { es: 'Ajustes › Agentes', en: 'Settings › Agents' },
66
+ action: 'settings',
67
+ },
68
+ {
69
+ id: 'tips',
70
+ icon: 'bell',
71
+ scene: 'tips',
72
+ title: { es: 'MADRE te explica cada cosa', en: 'MADRE explains everything to you' },
73
+ body: {
74
+ es: 'La primera vez que tocas algo importante, una nota corta te dice para qué sirve. Y cada IA te enseña con barras cuánto de tu plan llevas y qué puede hacer.',
75
+ en: 'The first time you press something important, a short note tells you what it is for. And each AI shows you with bars how much of your plan you have used and what it can do.',
76
+ },
77
+ where: { es: 'En toda MADRE', en: 'All over MADRE' },
78
+ action: null,
79
+ },
80
+ ],
81
+ },
34
82
  // 1.1 (2026-10-28): said to whoever comes from 1.0.x, on Home — the first screen of `npx madre` —
35
83
  // and in a project if Home was not opened first. Few things, the ones that change how MADRE looks.
36
84
  '1.1.0': {