@nac3/forge-cli 1.8.6 → 1.9.0

package/dist/docs/doctrine/operate-mode.md

@@ -0,0 +1,118 @@
+# Operate-mode doctrine (Forge Embedded que CONFIGURA el sistema)
+
+El asistente residente nacio DIAGNOSTICO (ver `diagnostic-mode`): leer,
+consultar la base read-only, escribir reportes, y emitir la instruccion precisa
+para el operador. El **operate mode** (Pablo, 2026-10-10) es la salida ACOTADA
+de ese read-only: el asistente ademas CONFIGURA el sistema que atiende.
+
+## 1. El alcance, textual
+
+Tres cosas, y nada mas:
+
+1. **Configurar por ARCHIVOS de datos de configuracion** -- json, xml, txt,
+   ini, env, properties, yaml, toml, vaults.
+2. **Configurar por TABLAS de configuracion** -- UPDATE/INSERT estructurado
+   sobre tablas declaradas como configuracion.
+3. **Crear procesos nuevos y cronearlos en el orquestador** del sistema.
+
+Explicitamente AFUERA:
+
+4. **Las tablas de DATOS del sistema** no se tocan.
+5. **El software del sistema** no se modifica (codigo fuente, binarios, units,
+   definiciones de build o dependencias).
+
+## 2. Como se hace cumplir (no es prompt, es dispatcher)
+
+La ley de esta casa: *las reglas son enforcement, no prompt* -- un cerebro
+ignora un prompt. El alcance vive en `src/core/operate_guard.ts` y se aplica en
+tres capas, donde una capa posterior NUNCA puede ensanchar a la anterior:
+
+- **A. Invariantes compilados.** Toda extension que es software se rechaza
+  aunque el allowlist diga `**/*`; igual el arbol del SO (`/etc`, `/usr`,
+  `/boot`...), los esquemas de sistema de la base, y `.forge/` (el perfil que
+  otorga estos poderes: el asistente no puede ampliarse a si mismo).
+- **B. Allowlist del operador.** `operate.config_files.allow` (globs) y
+  `operate.config_tables.allow` (tablas) en `.forge/profile.<env>.json`.
+  **Default deny**: sin allowlist no se escribe nada. Las tablas de datos
+  quedan afuera por omision -- no hay que enumerarlas.
+- **C. Validacion por llamada.** Topes de tamano, columnas inmutables, WHERE
+  obligatorio, preflight de filas afectadas (0 filas -> no-op rechazado; mas
+  que `max_rows` -> cambio demasiado amplio rechazado), gramatica de cron,
+  saneado de nombres y argumentos que llegan a una linea de comando.
+
+Y una decision de diseno que sostiene el punto 4: **no existe ningun verbo que
+ejecute SQL mutante arbitrario**. El asistente pasa `{table, op, set, where}` y
+el servidor compone la sentencia con identificadores validados y valores
+literales. No hay superficie para "UPDATE pacientes SET ...".
+
+## 3. Los verbos
+
+| Verbo | Para que |
+| --- | --- |
+| `yujin.config.file-set` | Cambiar UN valor en un archivo de configuracion. Preferido: deja el resto del archivo byte a byte, hace backup y VERIFICA releyendo (si no verifica, restaura el backup y falla). |
+| `yujin.config.file-write` | Contenido completo, para lo que el editor puntual no puede expresar (XML complejo, blob de vault, archivo nuevo con `create:true`). Leer el archivo ANTES. |
+| `yujin.config.file-revert` | Restaurar un backup por `backup_id`. El contenido actual tambien se respalda: el revert es reversible. |
+| `yujin.config.table-set` | `{table, op: update\|insert\|delete, set, where}` sobre una tabla de configuracion allowlisteada. |
+| `yujin.orchestrator.process-create` | Registrar un proceso nuevo en el orquestador (y opcionalmente cronearlo en la misma llamada). |
+| `yujin.orchestrator.schedule-set` | Poner/cambiar el cron (5 campos Linux; `@daily` se rechaza) y el enabled de un proceso. |
+
+Los verbos solo aparecen en el manifest cuando el perfil habilita operate mode,
+y `nac3_invoke` los rechaza a nivel perfil cuando esta apagado. Un embed
+diagnostico comun es identico al build anterior.
+
+## 4. El orquestador se declara, no se adivina
+
+Cada sistema tiene su orquestador, asi que la FORMA la declara el operador una
+vez en `operate.orchestrator` y el cerebro solo aporta la intencion
+(`{name, command, cron}`). Tres adaptadores:
+
+- `db_table`: filas en las tablas del orquestador (`process_table` +
+  `schedule_table`) con un mapa logico -> columna real. El orquestador RPA
+  clasico.
+- `http`: POST a la API del propio orquestador (`base_url` + paths, key por env
+  var). **Preferido cuando el sistema valida y recarga sus agendas solo**: un
+  INSERT directo en un motor que hidrata su catalogo en memoria al arrancar no
+  tomaria efecto hasta un reinicio.
+- `cron_file`: fragmento de crontab en un directorio declarado, armado desde un
+  `command_template`. Para sistemas cuyo "orquestador" es cron.
+
+La URL / tabla / template siempre vienen del perfil: el asistente elige QUE
+agendar, nunca ADONDE postear ni QUE binario correr.
+
+## 5. Como trabajar un pedido de configuracion (siendo el asistente)
+
+1. **Triage**: contra el system map, confirmar que el pedido se resuelve
+   OPERANDO el sistema. Si es bug o excepcion no contemplada -> ticket.
+2. **Leer el valor actual** (`yujin.fs.read-file` / `yujin.db.query`). Nunca
+   escribir a ciegas: un archivo de config reconstruido de memoria pierde
+   settings en silencio.
+3. **Decir en una linea** que se va a cambiar y donde, antes de hacerlo.
+4. **Aplicar** con el verbo puntual, de a un valor.
+5. **Verificar** releyendo, y reportar `antes -> despues`.
+6. **Decir que falta para que tome efecto** (reload / restart / proximo tick).
+   Reiniciar un servicio NO es del asistente: se le da al operador el comando
+   exacto.
+7. **Todo queda en el journal** (`.forge/changes/changes.jsonl`) con backup del
+   archivo o before-image de la fila + sentencia de rollback. Ante la duda:
+   revertir, o pasarle al operador el rollback.
+8. Fuera del alcance sigue siendo el asistente DIAGNOSTICO: instruccion
+   precisa, pending, o ticket.
+
+`require_approval` (default true) muestra el cambio en el modal del panel antes
+de aplicarlo -- el operador ve exactamente que se va a tocar. Ponerlo en false
+es una decision deliberada del despliegue (queda igual en el journal).
+
+## 6. Como habilitarlo en un despliegue
+
+`yf embed` genera `.forge/profile.ops.json` (read_only + operate con allowlists
+VACIOS) y su unit `forge-<app>-ops.service` con `YF_ENV=ops`. Receta:
+
+1. Levantar el servicio ops con los allowlists vacios: el asistente ya
+   diagnostica y, como no hay nada declarado, no puede cambiar nada.
+2. Pedirle que construya/actualice su `system-map.md` y que **proponga** el
+   bloque `operate` -- que archivos de config y que tablas de configuracion
+   encontro, y como se registran y agendan los procesos.
+3. Revisar esa propuesta, recortarla (en la duda, afuera) y commitearla. El
+   asistente no puede ampliarse: `.forge/` esta fuera de su alcance.
+4. Reiniciar el servicio ops y probar UN cambio real de punta a punta
+   (antes -> despues -> journal -> revert).

package/dist/nac3/internal_manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"internal_manifest.d.ts","sourceRoot":"","sources":["../../src/nac3/internal_manifest.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,UAAU,GAClB,cAAc,GACd,SAAS,GACT,mBAAmB,GACnB,aAAa,GACb,eAAe,GACf,oBAAoB,CAAC;AAEzB,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,KAAK,GACL,YAAY,GACZ,SAAS,GACT,SAAS,GACT,cAAc,GACd,KAAK,CAAC;AAEV,MAAM,MAAM,QAAQ,GAChB,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,YAAY,GACZ,SAAS,GACT,QAAQ,GACR,YAAY,CAAC;AAEjB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QACzB,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;QAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,YAAY,EAAE,cAAc,EAAE,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB;;;4BAGwB;IACxB,YAAY,EAAE,OAAO,GAAG,QAAQ,CAAC;IACjC;;;;;;qCAMiC;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAm4FD,wBAAgB,QAAQ,IAAI,YAAY,CAOvC;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAGzD;AAED;gEACgE;AAChE,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAO9D;AAED;;;uDAGuD;AACvD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAgCzF;AAED;;sEAEsE;AACtE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAI,GAAG,MAAM,EAAE,CAO/D"}
+{"version":3,"file":"internal_manifest.d.ts","sourceRoot":"","sources":["../../src/nac3/internal_manifest.ts"],"names":[],"mappings":"AAiBA,MAAM,MAAM,UAAU,GAClB,cAAc,GACd,SAAS,GACT,mBAAmB,GACnB,aAAa,GACb,eAAe,GACf,oBAAoB,CAAC;AAEzB,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,KAAK,GACL,YAAY,GACZ,SAAS,GACT,SAAS,GACT,cAAc,GACd,KAAK,CAAC;AAEV,MAAM,MAAM,QAAQ,GAChB,QAAQ,GACR,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,OAAO,GACP,YAAY,GACZ,SAAS,GACT,QAAQ,GACR,YAAY,CAAC;AAEjB,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE;QACzB,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;QAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;QACrB,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;QACzB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC,CAAC;IACH,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7B;AAED,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,cAAc,CAAC;IACvB,MAAM,EAAE,UAAU,CAAC;IACnB,YAAY,EAAE,cAAc,EAAE,CAAC;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB;;;4BAGwB;IACxB,YAAY,EAAE,OAAO,GAAG,QAAQ,CAAC;IACjC;;;;;;qCAMiC;IACjC,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,QAAQ,EAAE,CAAC;CACnB;AAykGD,wBAAgB,QAAQ,IAAI,YAAY,CAOvC;AAED,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAGzD;AAED;gEACgE;AAChE,wBAAgB,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAO9D;AAED;;;uDAGuD;AACvD,wBAAgB,YAAY,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,GAAG,IAAI,CAgCzF;AAED;;sEAEsE;AACtE,wBAAgB,YAAY,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,SAAI,GAAG,MAAM,EAAE,CAO/D"}

package/dist/nac3/internal_manifest.js

@@ -1293,6 +1293,192 @@ const VERBS = [
         visible: false,
         handler_side: 'server',
     },
+    /* ============================================================
+     * OPERATE MODE VERBS (Pablo 2026-10-10) -- the Forge Embedded
+     * assistant CONFIGURING the system it attends.
+     *
+     * Surfaced in the prompt stub ONLY when the deployment profile
+     * enables operate mode (buildManifestStub({includeOperateVerbs})),
+     * and nac3_invoke rejects them profile-wide when it is off, so a
+     * plain diagnostic embed is identical to the pre-operate build.
+     * Scope enforcement (which files, which tables, never software,
+     * never data tables) lives in core/operate_guard.ts.
+     * ============================================================ */
+    {
+        id: 'yujin.config.file-set',
+        role: 'action',
+        action: 'config_file_set',
+        label: 'Cambiar un valor de configuracion en un archivo',
+        description: 'Change ONE value inside a CONFIGURATION DATA FILE of the attended '
+            + 'system (json / xml / ini / env / properties / yaml / txt / vault). '
+            + 'PREFERRED over file-write: it keeps the rest of the file untouched '
+            + '(comments, order, unrelated keys), backs it up, and VERIFIES the new '
+            + 'value by reading it back (a write that does not verify is rolled '
+            + 'back). key syntax by format: json "a.b.c" (or a.b[0].c), ini '
+            + '"section.key", env/properties "KEY", yaml "a.b", xml "root/child" or '
+            + '"root/child@attr". value must be a scalar. The file must be '
+            + 'allowlisted in the deployment profile (operate.config_files.allow); '
+            + 'SOFTWARE files are always refused. READ the current value first and '
+            + 'report before -> after.',
+        schema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Config file. Project-relative, or absolute when the allowlist declares it.', minLength: 1, maxLength: 1000 },
+                key: { type: 'string', description: 'Setting path inside the file (format-dependent, see the description).', minLength: 1, maxLength: 500 },
+                value: { type: 'string', description: 'New value, as text. Its TYPE is taken from the value already in the file (a JSON number stays a number) unless value_type says otherwise.', maxLength: 65535 },
+                value_type: { type: 'string', description: 'Force the written type: auto (default: same as the current value) | string | number | boolean | null.', enum: ['auto', 'string', 'number', 'boolean', 'null'] },
+                format: { type: 'string', description: 'Override the format detected from the extension: json|ini|env|properties|yaml|xml.' },
+                create_missing: { type: 'boolean', description: 'Create the key when it does not exist (json/ini/env only). Default false.' },
+                reason: { type: 'string', description: 'Why this change is being made -- it goes to the change journal.', maxLength: 500 },
+            },
+            required: ['path', 'key', 'value'],
+        },
+        policy: 'approval-required',
+        side_effects: ['filesystem'],
+        visible: false,
+        handler_side: 'server',
+    },
+    {
+        id: 'yujin.config.file-write',
+        role: 'action',
+        action: 'config_file_write',
+        label: 'Reescribir un archivo de configuracion completo',
+        description: 'Replace the FULL content of a configuration file of the attended '
+            + 'system. Use it ONLY when the targeted editor (yujin.config.file-set) '
+            + 'cannot express the change -- a complex XML block, a vault blob, a '
+            + 'brand-new config file (create:true). ALWAYS read the file first and '
+            + 'send it back complete: a config file reconstructed from memory '
+            + 'silently loses settings. Keeps a backup + journal entry. Same '
+            + 'allowlist as file-set; SOFTWARE files are always refused.',
+        schema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Config file (allowlisted).', minLength: 1, maxLength: 1000 },
+                content: { type: 'string', description: 'The COMPLETE new text of the file.', maxLength: 524288 },
+                create: { type: 'boolean', description: 'Allow creating a file that does not exist yet. Default false.' },
+                reason: { type: 'string', description: 'Why -- goes to the change journal.', maxLength: 500 },
+            },
+            required: ['path', 'content'],
+        },
+        policy: 'approval-required',
+        side_effects: ['filesystem'],
+        visible: false,
+        handler_side: 'server',
+    },
+    {
+        id: 'yujin.config.file-revert',
+        role: 'action',
+        action: 'config_file_revert',
+        label: 'Revertir un cambio de configuracion',
+        description: 'Restore a configuration file from a backup taken by this assistant. '
+            + 'backup_id comes from the result of the change, or from the journal '
+            + '(<journal_dir>/changes.jsonl). The current content is backed up too, '
+            + 'so the revert is itself reversible.',
+        schema: {
+            type: 'object',
+            properties: {
+                backup_id: { type: 'string', description: 'Backup id from the change result or the journal.', minLength: 1, maxLength: 200 },
+                reason: { type: 'string', description: 'Why -- goes to the change journal.', maxLength: 500 },
+            },
+            required: ['backup_id'],
+        },
+        policy: 'approval-required',
+        side_effects: ['filesystem'],
+        visible: false,
+        handler_side: 'server',
+    },
+    {
+        id: 'yujin.config.table-set',
+        role: 'action',
+        action: 'config_table_set',
+        label: 'Cambiar un valor en una tabla de configuracion',
+        description: 'STRUCTURED write on a CONFIGURATION TABLE of the attended system: '
+            + '{table, op: update|insert|delete, set:{col:value}, where:{col:value}}. '
+            + 'There is NO verb for arbitrary mutating SQL -- this composes the '
+            + 'statement itself from validated identifiers and literal values. The '
+            + 'table must be allowlisted in the deployment profile '
+            + '(operate.config_tables.allow): the system DATA tables are off limits, '
+            + 'and insert/delete may be disabled. UPDATE/DELETE need a where; the '
+            + 'matched rows are preflighted (0 rows -> refused as a no-op, too many '
+            + '-> refused as too broad) and the before-image plus a rollback '
+            + 'statement go to the journal. FIND the row with yujin.db.query first, '
+            + 'then report before -> after.',
+        schema: {
+            type: 'object',
+            properties: {
+                table: { type: 'string', description: 'Configuration table (optionally db-qualified).', minLength: 1, maxLength: 200 },
+                op: { type: 'string', description: 'update (default) | insert | delete.' },
+                set: { type: 'object', description: '{column: value} to write. Scalars only.' },
+                where: { type: 'object', description: '{column: value} row selector, ANDed. Mandatory for update/delete.' },
+                reason: { type: 'string', description: 'Why -- goes to the change journal.', maxLength: 500 },
+            },
+            required: ['table'],
+        },
+        policy: 'approval-required',
+        side_effects: ['network'],
+        visible: false,
+        handler_side: 'server',
+    },
+    {
+        id: 'yujin.orchestrator.process-create',
+        role: 'action',
+        action: 'orchestrator_process_create',
+        label: 'Crear un proceso en el orquestador',
+        description: 'Register a NEW process in the attended system orchestrator. The HOW '
+            + '(tables / API / cron dir, and the command template) is declared by '
+            + 'the operator in operate.orchestrator; you only say WHAT: name, what '
+            + 'it runs (command, or target_kind + target_slug for a declarative '
+            + 'catalog), optional params, and optionally cron to schedule it in the '
+            + 'same call. This REGISTERS a process -- it never writes the program '
+            + 'itself (that would be modifying the software). Verify it afterwards '
+            + 'and say whether the orchestrator needs a reload.',
+        schema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'Process name (letters, digits, space, . _ -).', minLength: 1, maxLength: 80 },
+                description: { type: 'string', description: 'What it does, for the operator.', maxLength: 500 },
+                command: { type: 'string', description: 'Program/script the orchestrator already has (no shell metacharacters).', maxLength: 400 },
+                target_kind: { type: 'string', description: 'Declarative orchestrators: the kind of catalog entry (e.g. kawa|sazanami).' },
+                target_slug: { type: 'string', description: 'Declarative orchestrators: the catalog entry slug.' },
+                params: { type: 'object', description: 'Extra parameters (serialised as JSON).' },
+                enabled: { type: 'boolean', description: 'Create it enabled. Default true.' },
+                cron: { type: 'string', description: 'Schedule it in the same call: 5 Linux cron fields, e.g. "0 3 * * *".' },
+                reason: { type: 'string', description: 'Why -- goes to the change journal.', maxLength: 500 },
+            },
+            required: ['name'],
+        },
+        policy: 'approval-required',
+        side_effects: ['network', 'filesystem'],
+        visible: false,
+        handler_side: 'server',
+    },
+    {
+        id: 'yujin.orchestrator.schedule-set',
+        role: 'action',
+        action: 'orchestrator_schedule_set',
+        label: 'Agendar (cronear) un proceso del orquestador',
+        description: 'Set / change the SCHEDULE of a process in the attended system '
+            + 'orchestrator: name + cron (5 Linux fields -- validated; macros like '
+            + '@daily are refused) + enabled. With the db_table adapter it updates '
+            + 'the schedule row, and creates it when the process has none yet. Say '
+            + 'when the next run falls and whether the orchestrator re-reads its '
+            + 'schedules live.',
+        schema: {
+            type: 'object',
+            properties: {
+                name: { type: 'string', description: 'The process whose schedule changes.', minLength: 1, maxLength: 80 },
+                cron: { type: 'string', description: '5 Linux cron fields: minute hour day-of-month month day-of-week.', minLength: 1, maxLength: 120 },
+                enabled: { type: 'boolean', description: 'Leave the schedule enabled. Default true.' },
+                context: { type: 'object', description: 'Optional context/payload the orchestrator passes to the run.' },
+                reason: { type: 'string', description: 'Why -- goes to the change journal.', maxLength: 500 },
+            },
+            required: ['name', 'cron'],
+        },
+        policy: 'approval-required',
+        side_effects: ['network', 'filesystem'],
+        visible: false,
+        handler_side: 'server',
+    },
     /* ============================================================
      * MCP BRIDGE VERBS (alpha.59z.26 F101 slice 2)
      *