@hablala/api-contract 0.4.0 → 0.5.0

package/dist/index.d.ts

@@ -1195,7 +1195,7 @@ interface paths {
         put?: never;
         /**
          * Crear un access token
-         * @description Emite una credencial de máquina (`hpat_…`) con la que un agente (Claude Code) o un script CI escribe la ontología por HTTP. La respuesta incluye el secreto en claro UNA sola vez (`token`); guárdalo, no se puede recuperar. Los permisos se intersectan con los del creador (un token nunca puede más que quien lo emite).
+         * @description Emite una credencial de máquina (`hpat_…`) con la que un agente (Claude Code) o un script CI escribe el modelo de datos por HTTP. La respuesta incluye el secreto en claro UNA sola vez (`token`); guárdalo, no se puede recuperar. Los permisos se intersectan con los del creador (un token nunca puede más que quien lo emite).
          */
         post: operations["HablalaApiWeb.AccessTokens.TokenController.create"];
         delete?: never;
@@ -1305,10 +1305,10 @@ interface paths {
             cookie?: never;
         };
         /** Listar citas */
-        get: operations["HablalaApiWeb.Agenda.AppointmentController.index"];
+        get: operations["HablalaApiWeb.Scheduling.AppointmentController.index"];
         put?: never;
         /** Crear una cita */
-        post: operations["HablalaApiWeb.Agenda.AppointmentController.create"];
+        post: operations["HablalaApiWeb.Scheduling.AppointmentController.create"];
         delete?: never;
         options?: never;
         head?: never;
@@ -1323,7 +1323,7 @@ interface paths {
             cookie?: never;
         };
         /** Ver una cita */
-        get: operations["HablalaApiWeb.Agenda.AppointmentController.show"];
+        get: operations["HablalaApiWeb.Scheduling.AppointmentController.show"];
         put?: never;
         post?: never;
         delete?: never;
@@ -1342,7 +1342,7 @@ interface paths {
         get?: never;
         put?: never;
         /** Cancelar una cita (libera el hueco) */
-        post: operations["HablalaApiWeb.Agenda.AppointmentController.cancel"];
+        post: operations["HablalaApiWeb.Scheduling.AppointmentController.cancel"];
         delete?: never;
         options?: never;
         head?: never;
@@ -1359,7 +1359,7 @@ interface paths {
         get?: never;
         put?: never;
         /** Confirmar una cita pending */
-        post: operations["HablalaApiWeb.Agenda.AppointmentController.confirm"];
+        post: operations["HablalaApiWeb.Scheduling.AppointmentController.confirm"];
         delete?: never;
         options?: never;
         head?: never;
@@ -1379,7 +1379,7 @@ interface paths {
          * Marcar/desmarcar el no-show
          * @description Flag ortogonal al estado; la cita no libera su hueco.
          */
-        post: operations["HablalaApiWeb.Agenda.AppointmentController.no_show"];
+        post: operations["HablalaApiWeb.Scheduling.AppointmentController.no_show"];
         delete?: never;
         options?: never;
         head?: never;
@@ -1399,7 +1399,7 @@ interface paths {
          * Reagendar una cita
          * @description Cancela la cita y crea una nueva enlazada, en una transacción: si el hueco nuevo está tomado, la original queda intacta.
          */
-        post: operations["HablalaApiWeb.Agenda.AppointmentController.reschedule"];
+        post: operations["HablalaApiWeb.Scheduling.AppointmentController.reschedule"];
         delete?: never;
         options?: never;
         head?: never;
@@ -1538,7 +1538,7 @@ interface paths {
         };
         /**
          * Exportar la configuración del workspace como manifiesto
-         * @description El estado real de lo declarable (ontología, workflows, agentes) como manifiesto. Es lo que `hablala pull`/`init` baja a archivos.
+         * @description El estado real de lo declarable (objetos, workflows, agentes) como manifiesto. Es lo que `hablala pull`/`init` baja a archivos.
          */
         get: operations["HablalaApiWeb.Data.WorkspaceConfigController.show"];
         /**
@@ -2191,10 +2191,10 @@ interface paths {
             cookie?: never;
         };
         /** Listar horarios del equipo */
-        get: operations["HablalaApiWeb.Agenda.ScheduleController.index"];
+        get: operations["HablalaApiWeb.Scheduling.ScheduleController.index"];
         put?: never;
         /** Crear un horario */
-        post: operations["HablalaApiWeb.Agenda.ScheduleController.create"];
+        post: operations["HablalaApiWeb.Scheduling.ScheduleController.create"];
         delete?: never;
         options?: never;
         head?: never;
@@ -2209,16 +2209,16 @@ interface paths {
             cookie?: never;
         };
         /** Ver un horario */
-        get: operations["HablalaApiWeb.Agenda.ScheduleController.show"];
+        get: operations["HablalaApiWeb.Scheduling.ScheduleController.show"];
         /** Actualizar un horario (nombre, zona) */
-        put: operations["HablalaApiWeb.Agenda.ScheduleController.update"];
+        put: operations["HablalaApiWeb.Scheduling.ScheduleController.update"];
         post?: never;
         /** Borrar un horario (y sus franjas) */
-        delete: operations["HablalaApiWeb.Agenda.ScheduleController.delete"];
+        delete: operations["HablalaApiWeb.Scheduling.ScheduleController.delete"];
         options?: never;
         head?: never;
         /** Actualizar un horario (nombre, zona) */
-        patch: operations["HablalaApiWeb.Agenda.ScheduleController.update (2)"];
+        patch: operations["HablalaApiWeb.Scheduling.ScheduleController.update (2)"];
         trace?: never;
     };
     "/v1/organizations/{organization_id}/workspaces/{workspace_id}/schedules/{schedule_id}/availabilities": {
@@ -2231,7 +2231,7 @@ interface paths {
         get?: never;
         put?: never;
         /** Agregar una franja de disponibilidad al horario */
-        post: operations["HablalaApiWeb.Agenda.ScheduleController.add_availability"];
+        post: operations["HablalaApiWeb.Scheduling.ScheduleController.add_availability"];
         delete?: never;
         options?: never;
         head?: never;
@@ -2249,7 +2249,7 @@ interface paths {
         put?: never;
         post?: never;
         /** Quitar una franja de disponibilidad */
-        delete: operations["HablalaApiWeb.Agenda.ScheduleController.remove_availability"];
+        delete: operations["HablalaApiWeb.Scheduling.ScheduleController.remove_availability"];
         options?: never;
         head?: never;
         patch?: never;
@@ -2885,7 +2885,7 @@ interface components {
     schemas: {
         /**
          * AccessToken
-         * @description Metadatos de un access token de máquina (`hpat_…`): la credencial con la que un agente (Claude Code) o un script CI escribe la ontología por HTTP. El secreto en claro NO se incluye aquí — solo se devuelve una vez, al crearlo.
+         * @description Metadatos de un access token de máquina (`hpat_…`): la credencial con la que un agente (Claude Code) o un script CI escribe el modelo de datos por HTTP. El secreto en claro NO se incluye aquí — solo se devuelve una vez, al crearlo.
          */
         AccessToken: {
             /** @description ¿Ni revocado ni expirado? */
@@ -2965,7 +2965,7 @@ interface components {
             name: string;
             /** @description Permisos RBAC (`recurso:accion`) crudos, p. ej. `["objects:create", "objects:read"]`. Vía avanzada (CI/scripts); la UI usa `preset` en su lugar. */
             permissions?: string[];
-            /** @description Clave de un preset de permisos (ver `GET .../access-tokens/presets`), p. ej. `"ontology_builder"`. La vía que usa la UI. Si viene, gana sobre `permissions`. */
+            /** @description Clave de un preset de permisos (ver `GET .../access-tokens/presets`), p. ej. `"objects_builder"`. La vía que usa la UI. Si viene, gana sobre `permissions`. */
             preset?: string;
         };
         /** AccessTokensResponse */
@@ -3494,10 +3494,51 @@ interface components {
         EdgeResponse: {
             data: components["schemas"]["Edge"];
         };
-        /** Error */
+        /**
+         * Error
+         * @description Error en formato RFC 9457 (application/problem+json).
+         */
         Error: {
-            /** @description Detalle del error; por campo o `detail` para errores genéricos. */
-            errors: Record<string, never>;
+            /**
+             * @description Code estable legible por máquina; el ancla del contrato de errores.
+             * @example validation_failed
+             */
+            code: string;
+            /**
+             * @description Mensaje humano específico de esta ocurrencia.
+             * @example uno o más campos no son válidos
+             */
+            detail: string;
+            /**
+             * @description Sugerencias por sinónimo/similitud (unknown_attribute/object).
+             * @example [
+             *       "titulo"
+             *     ]
+             */
+            did_you_mean?: string[];
+            /** @description Errores por campo (validación). */
+            errors?: {
+                /** @example talla */
+                field?: string;
+                /** @example is required */
+                message?: string;
+            }[];
+            /**
+             * @description Código HTTP.
+             * @example 422
+             */
+            status: number;
+            /**
+             * @description Etiqueta canónica en inglés del tipo de problema (estable).
+             * @example Validation failed
+             */
+            title: string;
+            /**
+             * Format: uri
+             * @description URI que identifica el tipo de problema (deriva de `code`).
+             * @example https://hablala.com/errors/validation_failed
+             */
+            type: string;
         };
         /**
          * Event
@@ -5082,14 +5123,12 @@ interface components {
         };
         /**
          * WorkspaceConfigManifest
-         * @description El manifiesto declarativo del workspace (WORKSPACE_AS_CODE): el estado deseado de lo declarable — ontología, workflows y agentes. Cada sección es opcional (ausente = no gestionada) y autoritativa cuando está presente (lo existente no declarado se archiva; nunca se borra). Los datos (records) no son configuración.
+         * @description El manifiesto declarativo del workspace (WORKSPACE_AS_CODE): el estado deseado de lo declarable — objects, relationships, workflows y agentes. Cada sección es opcional (ausente = no gestionada) y autoritativa cuando está presente (lo existente no declarado se archiva; nunca se borra). Los datos (records) no son configuración.
          */
         WorkspaceConfigManifest: {
             agents?: components["schemas"]["ManifestAgent"][];
-            ontology?: {
-                objects?: components["schemas"]["ManifestObject"][];
-                relationships?: components["schemas"]["ManifestRelationship"][];
-            };
+            objects?: components["schemas"]["ManifestObject"][];
+            relationships?: components["schemas"]["ManifestRelationship"][];
             workflows?: components["schemas"]["ManifestWorkflow"][];
         };
         /**
@@ -8682,7 +8721,7 @@ interface operations {
             };
         };
     };
-    "HablalaApiWeb.Agenda.AppointmentController.index": {
+    "HablalaApiWeb.Scheduling.AppointmentController.index": {
         parameters: {
             query?: {
                 organizerId?: string;
@@ -8710,7 +8749,7 @@ interface operations {
             };
         };
     };
-    "HablalaApiWeb.Agenda.AppointmentController.create": {
+    "HablalaApiWeb.Scheduling.AppointmentController.create": {
         parameters: {
             query?: never;
             header?: never;
@@ -8747,7 +8786,7 @@ interface operations {
             };
         };
     };
-    "HablalaApiWeb.Agenda.AppointmentController.show": {
+    "HablalaApiWeb.Scheduling.AppointmentController.show": {
         parameters: {
             query?: never;
             header?: never;
@@ -8780,7 +8819,7 @@ interface operations {
             };
         };
     };
-    "HablalaApiWeb.Agenda.AppointmentController.cancel": {
+    "HablalaApiWeb.Scheduling.AppointmentController.cancel": {
         parameters: {
             query?: never;
             header?: never;
@@ -8818,7 +8857,7 @@ interface operations {
             };
         };
     };
-    "HablalaApiWeb.Agenda.AppointmentController.confirm": {
+    "HablalaApiWeb.Scheduling.AppointmentController.confirm": {
         parameters: {
             query?: never;
             header?: never;
@@ -8851,7 +8890,7 @@ interface operations {
             };
         };
     };
-    "HablalaApiWeb.Agenda.AppointmentController.no_show": {
+    "HablalaApiWeb.Scheduling.AppointmentController.no_show": {
         parameters: {
             query?: {
                 /** @description Default true. */
@@ -8878,7 +8917,7 @@ interface operations {
             };
         };
     };
-    "HablalaApiWeb.Agenda.AppointmentController.reschedule": {
+    "HablalaApiWeb.Scheduling.AppointmentController.reschedule": {
         parameters: {
             query?: never;
             header?: never;
@@ -11322,7 +11361,7 @@ interface operations {
             };
         };
     };
-    "HablalaApiWeb.Agenda.ScheduleController.index": {
+    "HablalaApiWeb.Scheduling.ScheduleController.index": {
         parameters: {
             query?: never;
             header?: never;
@@ -11354,7 +11393,7 @@ interface operations {
             };
         };
     };
-    "HablalaApiWeb.Agenda.ScheduleController.create": {
+    "HablalaApiWeb.Scheduling.ScheduleController.create": {
         parameters: {
             query?: never;
             header?: never;
@@ -11391,7 +11430,7 @@ interface operations {
             };
         };
     };
-    "HablalaApiWeb.Agenda.ScheduleController.show": {
+    "HablalaApiWeb.Scheduling.ScheduleController.show": {
         parameters: {
             query?: never;
             header?: never;
@@ -11424,7 +11463,7 @@ interface operations {
             };
         };
     };
-    "HablalaApiWeb.Agenda.ScheduleController.update": {
+    "HablalaApiWeb.Scheduling.ScheduleController.update": {
         parameters: {
             query?: never;
             header?: never;
@@ -11462,7 +11501,7 @@ interface operations {
             };
         };
     };
-    "HablalaApiWeb.Agenda.ScheduleController.delete": {
+    "HablalaApiWeb.Scheduling.ScheduleController.delete": {
         parameters: {
             query?: never;
             header?: never;
@@ -11484,7 +11523,7 @@ interface operations {
             };
         };
     };
-    "HablalaApiWeb.Agenda.ScheduleController.update (2)": {
+    "HablalaApiWeb.Scheduling.ScheduleController.update (2)": {
         parameters: {
             query?: never;
             header?: never;
@@ -11522,7 +11561,7 @@ interface operations {
             };
         };
     };
-    "HablalaApiWeb.Agenda.ScheduleController.add_availability": {
+    "HablalaApiWeb.Scheduling.ScheduleController.add_availability": {
         parameters: {
             query?: never;
             header?: never;
@@ -11560,7 +11599,7 @@ interface operations {
             };
         };
     };
-    "HablalaApiWeb.Agenda.ScheduleController.remove_availability": {
+    "HablalaApiWeb.Scheduling.ScheduleController.remove_availability": {
         parameters: {
             query?: never;
             header?: never;

package/llms.txt

@@ -0,0 +1,53 @@
+# @hablala/api-contract
+
+> El contrato **single source of truth** de la API de Hablalá: un `openapi.json` (OpenAPI 3.1)
+> generado desde el backend Elixir con OpenApiSpex, del que derivan los tipos TypeScript. Nadie
+> escribe tipos de la API a mano. Hablalá es API-first y headless: la API es el producto, solo
+> habla JSON, sin UI.
+
+## El contrato
+
+- [openapi.json](./openapi.json): el spec OpenAPI 3.1 completo, generado desde Elixir
+  (`mix openapi.spec.json`). Es la fuente de verdad; los tipos y los clientes derivan de aquí.
+- [generated/types.ts](./generated/types.ts): tipos TypeScript generados con `openapi-typescript`
+  (no editar a mano). Se reexportan desde `src/index.ts` como `paths`, `components`, `operations`.
+
+## Formato de error (RFC 9457)
+
+Todo error de la API responde con `application/problem+json` (RFC 9457), un formato único:
+
+    {
+      "type": "https://hablala.com/errors/<code>",
+      "title": "<etiqueta canónica en inglés>",
+      "status": <int>,
+      "detail": "<mensaje humano>",
+      "code": "<code estable, legible por máquina>",
+      "did_you_mean": ["<sugerencia>"],          // opcional (unknown_attribute/object)
+      "errors": [{ "field": "...", "message": "..." }]  // opcional (validación por campo)
+    }
+
+El `code` es el ancla del contrato: ramifica por él, no por el status. El schema está en
+`components.schemas.Error` del `openapi.json`.
+
+## Rate limiting
+
+Las respuestas llevan `X-RateLimit-Limit` / `X-RateLimit-Remaining` / `X-RateLimit-Reset`. Al
+exceder la cuota: `429` con `Retry-After` (segundos) y un cuerpo RFC 9457 con `code: "rate_limited"`.
+
+## Autenticación
+
+Una credencial es una identidad completa (el token porta su tenant): no se pasa `organizationId`
+ni `workspaceId`. Access token de máquina `hpat_…` (Bearer) para el motor; storefront token
+`sfpk_…`/`sfpr_…` (header `X-Hablala-Storefront-Token`) para la Data API pública read-only.
+
+## Cómo consumirlo
+
+- TypeScript (web/móvil): importa los tipos de `@hablala/api-contract` y usa `openapi-fetch`.
+  El SDK de alto nivel es [`@hablala/client`](../client).
+- Regeneración: `npm run generate` (openapi.json → types.ts). CI falla si hay drift.
+
+## Docs de arquitectura (en el monorepo)
+
+- [apps/api/ARCHITECTURE.md](../../apps/api/ARCHITECTURE.md): el mapa completo de la plataforma.
+- [apps/api/API_FIRST.md](../../apps/api/API_FIRST.md): por qué API-first, cómo se genera el contrato.
+- [apps/api/UBIQUITOUS_LANGUAGE.md](../../apps/api/UBIQUITOUS_LANGUAGE.md): el vocabulario normativo.

package/openapi.json

@@ -3,7 +3,7 @@
     "responses": {},
     "schemas": {
       "AccessToken": {
-        "description": "Metadatos de un access token de máquina (`hpat_…`): la credencial con la que un agente (Claude Code) o un script CI escribe la ontología por HTTP. El secreto en claro NO se incluye aquí — solo se devuelve una vez, al crearlo.",
+        "description": "Metadatos de un access token de máquina (`hpat_…`): la credencial con la que un agente (Claude Code) o un script CI escribe el modelo de datos por HTTP. El secreto en claro NO se incluye aquí — solo se devuelve una vez, al crearlo.",
         "properties": {
           "active": {
             "description": "¿Ni revocado ni expirado?",
@@ -263,7 +263,7 @@
             "x-validate": null
           },
           "preset": {
-            "description": "Clave de un preset de permisos (ver `GET .../access-tokens/presets`), p. ej. `\"ontology_builder\"`. La vía que usa la UI. Si viene, gana sobre `permissions`.",
+            "description": "Clave de un preset de permisos (ver `GET .../access-tokens/presets`), p. ej. `\"objects_builder\"`. La vía que usa la UI. Si viene, gana sobre `permissions`.",
             "type": "string",
             "x-struct": null,
             "x-validate": null
@@ -2205,16 +2205,90 @@
         "x-validate": null
       },
       "Error": {
+        "description": "Error en formato RFC 9457 (application/problem+json).",
         "properties": {
+          "code": {
+            "description": "Code estable legible por máquina; el ancla del contrato de errores.",
+            "example": "validation_failed",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "detail": {
+            "description": "Mensaje humano específico de esta ocurrencia.",
+            "example": "uno o más campos no son válidos",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "did_you_mean": {
+            "description": "Sugerencias por sinónimo/similitud (unknown_attribute/object).",
+            "example": [
+              "titulo"
+            ],
+            "items": {
+              "type": "string",
+              "x-struct": null,
+              "x-validate": null
+            },
+            "type": "array",
+            "x-struct": null,
+            "x-validate": null
+          },
           "errors": {
-            "description": "Detalle del error; por campo o `detail` para errores genéricos.",
-            "type": "object",
+            "description": "Errores por campo (validación).",
+            "items": {
+              "properties": {
+                "field": {
+                  "example": "talla",
+                  "type": "string",
+                  "x-struct": null,
+                  "x-validate": null
+                },
+                "message": {
+                  "example": "is required",
+                  "type": "string",
+                  "x-struct": null,
+                  "x-validate": null
+                }
+              },
+              "type": "object",
+              "x-struct": null,
+              "x-validate": null
+            },
+            "type": "array",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "status": {
+            "description": "Código HTTP.",
+            "example": 422,
+            "type": "integer",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "title": {
+            "description": "Etiqueta canónica en inglés del tipo de problema (estable).",
+            "example": "Validation failed",
+            "type": "string",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "type": {
+            "description": "URI que identifica el tipo de problema (deriva de `code`).",
+            "example": "https://hablala.com/errors/validation_failed",
+            "format": "uri",
+            "type": "string",
             "x-struct": null,
             "x-validate": null
           }
         },
         "required": [
-          "errors"
+          "type",
+          "title",
+          "status",
+          "detail",
+          "code"
         ],
         "title": "Error",
         "type": "object",
@@ -7948,7 +8022,7 @@
         "x-validate": null
       },
       "WorkspaceConfigManifest": {
-        "description": "El manifiesto declarativo del workspace (WORKSPACE_AS_CODE): el estado deseado de lo declarable — ontología, workflows y agentes. Cada sección es opcional (ausente = no gestionada) y autoritativa cuando está presente (lo existente no declarado se archiva; nunca se borra). Los datos (records) no son configuración.",
+        "description": "El manifiesto declarativo del workspace (WORKSPACE_AS_CODE): el estado deseado de lo declarable — objects, relationships, workflows y agentes. Cada sección es opcional (ausente = no gestionada) y autoritativa cuando está presente (lo existente no declarado se archiva; nunca se borra). Los datos (records) no son configuración.",
         "properties": {
           "agents": {
             "items": {
@@ -7958,26 +8032,19 @@
             "x-struct": null,
             "x-validate": null
           },
-          "ontology": {
-            "properties": {
-              "objects": {
-                "items": {
-                  "$ref": "#/components/schemas/ManifestObject"
-                },
-                "type": "array",
-                "x-struct": null,
-                "x-validate": null
-              },
-              "relationships": {
-                "items": {
-                  "$ref": "#/components/schemas/ManifestRelationship"
-                },
-                "type": "array",
-                "x-struct": null,
-                "x-validate": null
-              }
+          "objects": {
+            "items": {
+              "$ref": "#/components/schemas/ManifestObject"
             },
-            "type": "object",
+            "type": "array",
+            "x-struct": null,
+            "x-validate": null
+          },
+          "relationships": {
+            "items": {
+              "$ref": "#/components/schemas/ManifestRelationship"
+            },
+            "type": "array",
             "x-struct": null,
             "x-validate": null
           },
@@ -13261,7 +13328,7 @@
       },
       "post": {
         "callbacks": {},
-        "description": "Emite una credencial de máquina (`hpat_…`) con la que un agente (Claude Code) o un script CI escribe la ontología por HTTP. La respuesta incluye el secreto en claro UNA sola vez (`token`); guárdalo, no se puede recuperar. Los permisos se intersectan con los del creador (un token nunca puede más que quien lo emite).",
+        "description": "Emite una credencial de máquina (`hpat_…`) con la que un agente (Claude Code) o un script CI escribe el modelo de datos por HTTP. La respuesta incluye el secreto en claro UNA sola vez (`token`); guárdalo, no se puede recuperar. Los permisos se intersectan con los del creador (un token nunca puede más que quien lo emite).",
         "operationId": "HablalaApiWeb.AccessTokens.TokenController.create",
         "parameters": [
           {
@@ -13860,7 +13927,7 @@
     "/v1/organizations/{organization_id}/workspaces/{workspace_id}/appointments": {
       "get": {
         "callbacks": {},
-        "operationId": "HablalaApiWeb.Agenda.AppointmentController.index",
+        "operationId": "HablalaApiWeb.Scheduling.AppointmentController.index",
         "parameters": [
           {
             "description": "",
@@ -13932,12 +13999,12 @@
         },
         "summary": "Listar citas",
         "tags": [
-          "agenda"
+          "scheduling"
         ]
       },
       "post": {
         "callbacks": {},
-        "operationId": "HablalaApiWeb.Agenda.AppointmentController.create",
+        "operationId": "HablalaApiWeb.Scheduling.AppointmentController.create",
         "parameters": [
           {
             "description": "",
@@ -13997,14 +14064,14 @@
         },
         "summary": "Crear una cita",
         "tags": [
-          "agenda"
+          "scheduling"
         ]
       }
     },
     "/v1/organizations/{organization_id}/workspaces/{workspace_id}/appointments/{id}": {
       "get": {
         "callbacks": {},
-        "operationId": "HablalaApiWeb.Agenda.AppointmentController.show",
+        "operationId": "HablalaApiWeb.Scheduling.AppointmentController.show",
         "parameters": [
           {
             "description": "",
@@ -14064,14 +14131,14 @@
         },
         "summary": "Ver una cita",
         "tags": [
-          "agenda"
+          "scheduling"
         ]
       }
     },
     "/v1/organizations/{organization_id}/workspaces/{workspace_id}/appointments/{id}/cancel": {
       "post": {
         "callbacks": {},
-        "operationId": "HablalaApiWeb.Agenda.AppointmentController.cancel",
+        "operationId": "HablalaApiWeb.Scheduling.AppointmentController.cancel",
         "parameters": [
           {
             "description": "",
@@ -14142,14 +14209,14 @@
         },
         "summary": "Cancelar una cita (libera el hueco)",
         "tags": [
-          "agenda"
+          "scheduling"
         ]
       }
     },
     "/v1/organizations/{organization_id}/workspaces/{workspace_id}/appointments/{id}/confirm": {
       "post": {
         "callbacks": {},
-        "operationId": "HablalaApiWeb.Agenda.AppointmentController.confirm",
+        "operationId": "HablalaApiWeb.Scheduling.AppointmentController.confirm",
         "parameters": [
           {
             "description": "",
@@ -14209,7 +14276,7 @@
         },
         "summary": "Confirmar una cita pending",
         "tags": [
-          "agenda"
+          "scheduling"
         ]
       }
     },
@@ -14217,7 +14284,7 @@
       "post": {
         "callbacks": {},
         "description": "Flag ortogonal al estado; la cita no libera su hueco.",
-        "operationId": "HablalaApiWeb.Agenda.AppointmentController.no_show",
+        "operationId": "HablalaApiWeb.Scheduling.AppointmentController.no_show",
         "parameters": [
           {
             "description": "",
@@ -14278,7 +14345,7 @@
         },
         "summary": "Marcar/desmarcar el no-show",
         "tags": [
-          "agenda"
+          "scheduling"
         ]
       }
     },
@@ -14286,7 +14353,7 @@
       "post": {
         "callbacks": {},
         "description": "Cancela la cita y crea una nueva enlazada, en una transacción: si el hueco nuevo está tomado, la original queda intacta.",
-        "operationId": "HablalaApiWeb.Agenda.AppointmentController.reschedule",
+        "operationId": "HablalaApiWeb.Scheduling.AppointmentController.reschedule",
         "parameters": [
           {
             "description": "",
@@ -14357,7 +14424,7 @@
         },
         "summary": "Reagendar una cita",
         "tags": [
-          "agenda"
+          "scheduling"
         ]
       }
     },
@@ -14955,7 +15022,7 @@
     "/v1/organizations/{organization_id}/workspaces/{workspace_id}/config": {
       "get": {
         "callbacks": {},
-        "description": "El estado real de lo declarable (ontología, workflows, agentes) como manifiesto. Es lo que `hablala pull`/`init` baja a archivos.",
+        "description": "El estado real de lo declarable (objetos, workflows, agentes) como manifiesto. Es lo que `hablala pull`/`init` baja a archivos.",
         "operationId": "HablalaApiWeb.Data.WorkspaceConfigController.show",
         "parameters": [
           {
@@ -19206,7 +19273,7 @@
     "/v1/organizations/{organization_id}/workspaces/{workspace_id}/schedules": {
       "get": {
         "callbacks": {},
-        "operationId": "HablalaApiWeb.Agenda.ScheduleController.index",
+        "operationId": "HablalaApiWeb.Scheduling.ScheduleController.index",
         "parameters": [
           {
             "description": "",
@@ -19255,12 +19322,12 @@
         },
         "summary": "Listar horarios del equipo",
         "tags": [
-          "agenda"
+          "scheduling"
         ]
       },
       "post": {
         "callbacks": {},
-        "operationId": "HablalaApiWeb.Agenda.ScheduleController.create",
+        "operationId": "HablalaApiWeb.Scheduling.ScheduleController.create",
         "parameters": [
           {
             "description": "",
@@ -19320,14 +19387,14 @@
         },
         "summary": "Crear un horario",
         "tags": [
-          "agenda"
+          "scheduling"
         ]
       }
     },
     "/v1/organizations/{organization_id}/workspaces/{workspace_id}/schedules/{id}": {
       "delete": {
         "callbacks": {},
-        "operationId": "HablalaApiWeb.Agenda.ScheduleController.delete",
+        "operationId": "HablalaApiWeb.Scheduling.ScheduleController.delete",
         "parameters": [
           {
             "description": "",
@@ -19370,12 +19437,12 @@
         },
         "summary": "Borrar un horario (y sus franjas)",
         "tags": [
-          "agenda"
+          "scheduling"
         ]
       },
       "get": {
         "callbacks": {},
-        "operationId": "HablalaApiWeb.Agenda.ScheduleController.show",
+        "operationId": "HablalaApiWeb.Scheduling.ScheduleController.show",
         "parameters": [
           {
             "description": "",
@@ -19435,12 +19502,12 @@
         },
         "summary": "Ver un horario",
         "tags": [
-          "agenda"
+          "scheduling"
         ]
       },
       "patch": {
         "callbacks": {},
-        "operationId": "HablalaApiWeb.Agenda.ScheduleController.update (2)",
+        "operationId": "HablalaApiWeb.Scheduling.ScheduleController.update (2)",
         "parameters": [
           {
             "description": "",
@@ -19511,12 +19578,12 @@
         },
         "summary": "Actualizar un horario (nombre, zona)",
         "tags": [
-          "agenda"
+          "scheduling"
         ]
       },
       "put": {
         "callbacks": {},
-        "operationId": "HablalaApiWeb.Agenda.ScheduleController.update",
+        "operationId": "HablalaApiWeb.Scheduling.ScheduleController.update",
         "parameters": [
           {
             "description": "",
@@ -19587,14 +19654,14 @@
         },
         "summary": "Actualizar un horario (nombre, zona)",
         "tags": [
-          "agenda"
+          "scheduling"
         ]
       }
     },
     "/v1/organizations/{organization_id}/workspaces/{workspace_id}/schedules/{schedule_id}/availabilities": {
       "post": {
         "callbacks": {},
-        "operationId": "HablalaApiWeb.Agenda.ScheduleController.add_availability",
+        "operationId": "HablalaApiWeb.Scheduling.ScheduleController.add_availability",
         "parameters": [
           {
             "description": "",
@@ -19665,14 +19732,14 @@
         },
         "summary": "Agregar una franja de disponibilidad al horario",
         "tags": [
-          "agenda"
+          "scheduling"
         ]
       }
     },
     "/v1/organizations/{organization_id}/workspaces/{workspace_id}/schedules/{schedule_id}/availabilities/{id}": {
       "delete": {
         "callbacks": {},
-        "operationId": "HablalaApiWeb.Agenda.ScheduleController.remove_availability",
+        "operationId": "HablalaApiWeb.Scheduling.ScheduleController.remove_availability",
         "parameters": [
           {
             "description": "",
@@ -19726,7 +19793,7 @@
         },
         "summary": "Quitar una franja de disponibilidad",
         "tags": [
-          "agenda"
+          "scheduling"
         ]
       }
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hablala/api-contract",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "description": "Contrato tipado (OpenAPI → TypeScript) de la API de Hablalá — single source of truth generada desde el backend Elixir.",
   "license": "MIT",
@@ -30,6 +30,7 @@
   "files": [
     "dist",
     "openapi.json",
+    "llms.txt",
     "README.md",
     "LICENSE"
   ],