@vaia-lab/sdk 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 VAIA Lab
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,225 +1,181 @@
 # @vaia-lab/sdk
 
-VAIA Platform Integration SDK — connect your app, agent, or skill to [Gandia-7](https://gandia7.com) and [Handeia](https://handeia.com).
+**Agents with declared authority.** Connect your app to [Gandia-7](https://gandia7.com) and [Handeia](https://handeia.com), and let an assistant operate inside it — without writing the AI, and without giving it more power than you meant to.
 
-Zero runtime dependencies · Works in Node 18+, Edge, Bun, Deno · TypeScript-first
-
----
-
-## Install
+Zero dependencies · Node 18+, Edge, Bun, Deno · TypeScript-first
 
 ```bash
-npm install @vaia-lab/sdk
+npm i @vaia-lab/sdk
+npx vaia init
 ```
 
 ---
 
-## Quick start (Next.js — Gandia-7)
+## The problem it solves
+
+Most agent SDKs can say *"the agent may call this function."*
+
+None of them can say *"it may pay up to $500 on its own, above that it asks, and it may never delete."*
+
+That second sentence is the difference between a demo and something you let run on real data. Here it's mandatory: **a piece without declared authority does not compile.**
 
 ```ts
-// app/api/gandia/invoke/route.ts
-import { gandia, VAIAError } from '@vaia-lab/sdk'
-
-export const runtime = 'edge'
-
-export async function POST(req: Request) {
-  try {
-    const { ctx } = await gandia.verify(req, process.env.GANDIA_KEY_SECRET!)
-    gandia.require(ctx, 'read:students')
-
-    const data = await myDb.getStudents(ctx.tenant.id)
-
-    return gandia.respond.surface(ctx.surface, {
-      card:  () => ({ title: 'Alumnos', value: data.length }),
-      table: () => ({ columns: ['nombre', 'riesgo'], rows: data }),
-      text:  () => `${data.length} alumnos en ${ctx.tenant.name}`,
-    })
-  } catch (err) {
-    if (err instanceof VAIAError) return gandia.respond.error(err.message, err.status)
-    throw err
-  }
-}
+tools: [{
+  name: 'pay_invoice',
+  description: 'Pays a pending invoice.',
+  permission: 'write:payments',
+  authority: {
+    level: 'autonoma',            // autonoma | requiere_aprobacion | prohibida
+    consequence: 'costosa',       // reversible | costosa | irreversible
+    maxAmount: 500,
+    currency: 'MXN',
+    rationale: 'Small recurring invoices. Anything larger gets human review.',
+  },
+}]
 ```
 
----
+### Rules you cannot opt out of
 
-## API Reference
+| rule | why |
+|---|---|
+| **Irreversible is never autonomous** | Doesn't rely on the model behaving well — it relies on the config being **impossible to write** |
+| Autonomous spending needs **a cap and a currency** | A bare `500` means nothing, and guessing the currency is how money disappears |
+| No piece may **exceed its agent's ceiling** | Otherwise you declare a limited agent and slip it a tool that does what the agent can't |
+| A tool **without a permission** is rejected | No permission means no one to ask for consent, and no one to revoke it from |
 
-### `gandia.verify(request, secret)`
+Validation happens **when you declare**, not in production. A bad contract breaks on your desk, not in front of your user.
+
+---
 
-Verifies the HMAC-SHA256 signature on an incoming invoke call from Gandia-7.
+## The agent inside your app
 
-- Checks `X-Gandia-Signature`, `X-Gandia-Timestamp` (replay window ±5 min)
-- Returns `{ ctx: GandiaContext, raw: string }`
-- Throws `VAIAError` (status 401) if invalid
+You declare what you can do. The assistant reasons with that **plus what it knows about the user, which you never see**.
 
 ```ts
-const { ctx } = await gandia.verify(req, process.env.GANDIA_KEY_SECRET!)
-// ctx.tenant.id, ctx.tenant.name, ctx.tenant.sector
-// ctx.user.id, ctx.user.role
-// ctx.permissions  → ['read:students', 'read:grades']
-// ctx.surface      → 'card' | 'table' | 'text' | 'widget' | 'action' | 'data'
-// ctx.query        → user's original question (if trigger = 'user_query')
+agent: {
+  actions: [
+    { name: 'filter_results', description: 'Narrows the visible list.',
+      params: [{ name: 'city', type: 'string', description: 'City to filter by.' }] },
+  ],
+}
 ```
 
-### `gandia.require(ctx, permission)`
-
-Throws `VAIAError` (403) if the context doesn't have the required permission.
-
 ```ts
-gandia.require(ctx, 'write:alerts')           // single
-gandia.requireAll(ctx, 'read:students', 'read:grades')  // all
-const ok = gandia.can(ctx, 'read:health')     // boolean check
+mountAgent({
+  capabilityId: 'com.my-app',
+  getContext: () => ({ route: location.pathname, claims: { visible: 12 } }),
+  onAction: async (name, args) => run(name, args),
+})
 ```
 
-### `gandia.respond.surface(surface, handlers, opts?)`
+**Why the agent doesn't live in your app:** if it brought its own AI, it wouldn't know the user, it would start from zero every session, and — most importantly — **it could never disagree with itself**. This way, if your app scores one option 90 and another 87, the assistant can still recommend the 87, because it knows something about the user your app has no business knowing.
 
-Multi-surface responder — GAIA tells you which surface it wants via `ctx.surface`.
+**What it deliberately cannot do:** it may only request actions you declared. It doesn't improvise, doesn't touch the DOM, doesn't find workarounds. Anything that writes gets confirmed with the user first.
 
-```ts
-return gandia.respond.surface(ctx.surface, {
-  card:  () => ({ title: 'Riesgo', value: 72, unit: '%', trend: 'up' }),
-  table: () => ({ columns: ['alumno', 'score'], rows }),
-  text:  () => `El riesgo promedio es 72%`,
-}, { audit: { data_sources: ['supabase:students'], records_accessed: 120 } })
-```
+---
 
-Available surfaces: `card` · `table` · `text` · `widget` · `action` · `data`
+## Borrowed connectors
 
-### `gandia.respond.*` — individual builders
+Your app needs the user's GitHub or Drive. **You implement no OAuth, and you never receive their token.**
 
 ```ts
-gandia.respond.card({ title, value, unit, trend, subtitle, color })
-gandia.respond.table({ columns, rows, total })
-gandia.respond.text(content, { markdown: true })
-gandia.respond.widget({ url, height, width })
-gandia.respond.action({ type, label, params, confirm })
-gandia.respond.data(payload)
-gandia.respond.ok()
-gandia.respond.error(message, status, code?)
+agent: { needs: ['github', 'drive'] }
 ```
 
-All return a `Response` (Web API standard). For Express/Fastify use `gandia.make.*` instead (returns plain JSON object).
-
-### `gandia.jwt.verify(token, secret)`
+You request an operation, the platform runs it with the token it already holds, and hands you back a trimmed result.
 
-Verifies a Gandia-7 iframe JWT (`gandia_token` URL param). Use in iframe entry routes to skip your own login.
+> If every app stored tokens, the attack surface would multiply by every developer who ships. One compromised app would hand over the GitHub and Drive of all its users. Borrowed, it only reaches what the user granted — rate-limited, audited, and revocable instantly.
 
-```ts
-// In your iframe entry route:
-const claims = await gandia.jwt.fromUrl(request.url, process.env.GANDIA_KEY_SECRET!)
-// claims.sub         → user_id
-// claims.tenant_id   → institution id
-// claims.email       → user email (if available)
-// claims.permissions → what the user can do
-```
+Read-only. Writing to an external service is never lent: that's what the service itself is for.
 
 ---
 
-### `handeia.*`
+## MCP, wrapped
 
-Same API as `gandia.*` but for Handeia (personal platform). No tenant — just the user.
+MCP brings the catalog and the transport. This SDK brings the authority layer **MCP cannot express**.
 
 ```ts
-const { ctx } = await handeia.verify(req, process.env.HANDEIA_KEY_SECRET!)
-// ctx.user.id, ctx.user.email
-// ctx.permissions, ctx.surface, ctx.query
+const { tool, warnings } = fromMCPTool(mcpTool, authority, 'read:web')
 ```
 
+**Importing something from the internet grants it nothing.** Authority is assigned separately, always. The server's own hints only ever produce warnings — *"it flags this as destructive but you declared it reversible"* — never decisions.
+
+Outbound, `toMCPTool()` **withholds anything requiring approval**: exposing it would offer an external agent something even you can't run unattended.
+
 ---
 
-### `defineCapability(config)`
+## Use it without our platform
 
-Declares your capability metadata in code. The Shazam engine reads this with 100% confidence — no manual confirmation needed in the Developer Portal.
+**Ten of the thirteen exports need no account, no network and no keys.** The authority layer is not tied to Gandia-7 or Handeia — it works with any LLM, any framework, any stack.
 
 ```ts
-// vaia.config.ts
-import { defineCapability } from '@vaia-lab/sdk'
-
-export default defineCapability({
-  id: 'mx.monitor-riesgo-academico',  // reverse-domain
-  name: 'Monitor de Riesgo Académico',
-  version: '1.0.0',
-  target: 'gandia',           // 'gandia' | 'handeia' | 'both'
-  type: 'app',                // 'app' | 'ia' | 'skill' | 'eco'
-  level: 'artefacto',         // 'widget' | 'artefacto' | 'espacio'
-  sector: 'educacion',
-  surfaces: {
-    card:  { endpoint: '/api/gandia/invoke' },
-    table: { endpoint: '/api/gandia/invoke' },
-    text:  { endpoint: '/api/gandia/invoke' },
-  },
-  permissions: ['read:students', 'read:grades', 'write:alerts'],
-  risk: 'medium',
-})
-```
+import { validatePieces, checkAuthority, fromMCPTool } from '@vaia-lab/sdk'
 
-Generate `gandia.manifest.json`:
+// Validate your agent's tools at build time — with your own runtime
+const errors = validatePieces({ tools: myTools })
+if (errors.length) throw new Error(errors.join('\n'))
 
-```bash
-# Compile vaia.config.ts first, then:
-npx vaia-sdk manifest
-
-# Validate existing manifest:
-npx vaia-sdk manifest --validate
+// Gate a call before it happens, wherever your agent runs
+const ok = checkAuthority(tool.authority, { amount: 900, currency: 'MXN' })
+if (!ok.ok) return askHuman(ok.reason)
 ```
 
+| works standalone | needs the platform |
+|---|---|
+| `defineCapability` · `toManifest` | `gandia.verify` · `handeia.jwt` |
+| `validatePieces` · `checkAuthority` · `requiresApproval` | `mountAgent` |
+| `validateAgentSurface` · `validateActionCall` | |
+| `fromMCPTool` · `toMCPTool` · `toMCPTools` | |
+
+Bring your own model. Bring your own orchestrator. Keep the guardrails.
+
 ---
 
-## Error handling
+## Identity, without a second login
 
-All verification functions throw `VAIAError` on failure:
+Your app opens from Gandia-7 or Handeia with the user's session already resolved.
 
 ```ts
-import { VAIAError } from '@vaia-lab/sdk'
-
-try {
-  const { ctx } = await gandia.verify(req, secret)
-  // ...
-} catch (err) {
-  if (err instanceof VAIAError) {
-    // err.message → human-readable message (Spanish)
-    // err.code    → machine-readable: 'HMAC_INVALID', 'JWT_EXPIRED', 'PERMISSION_DENIED', etc.
-    // err.status  → HTTP status: 401, 403, 400, 422
-    return gandia.respond.error(err.message, err.status, err.code)
-  }
-  throw err
-}
+const claims = await handeia.jwt.fromUrl(request.url, process.env.HANDEIA_KEY_SECRET!)
 ```
 
-### Error codes
+And to verify a call genuinely came from the platform:
 
-| Code | Status | When |
-|---|---|---|
-| `MISSING_AUTH_HEADERS` | 401 | X-Gandia-Signature or X-Gandia-Timestamp missing |
-| `TIMESTAMP_OUT_OF_RANGE` | 401 | Timestamp outside ±5 min window |
-| `HMAC_INVALID` | 401 | Signature doesn't match |
-| `BODY_PARSE_ERROR` | 400 | Body is not valid JSON |
-| `JWT_MALFORMED` | 401 | JWT doesn't have 3 parts |
-| `JWT_SIGNATURE_INVALID` | 401 | JWT signature check failed |
-| `JWT_EXPIRED` | 401 | JWT exp claim is in the past |
-| `PERMISSION_DENIED` | 403 | Missing required permission |
-| `SURFACE_NOT_SUPPORTED` | 422 | No handler for requested surface |
+```ts
+const { ctx } = await gandia.verify(request, process.env.GANDIA_KEY_SECRET!)
+gandia.require(ctx, 'read:students')
+```
+
+Constant-time HMAC comparison, ±5 min window, and the health probe **requires a signature too**.
+
+---
+
+## The 7 pieces
+
+`skills` · `tools` · `workflows` · `agents` · `personalities` · `modalities` · `permissions`
+
+All declared, all validated, all carried in the manifest — so the portal can show **what authority a capability asks for before anyone installs it**.
 
 ---
 
 ## CLI
 
 ```bash
-npx vaia-sdk manifest            # generate gandia.manifest.json
-npx vaia-sdk manifest --validate # validate existing manifest
-npx vaia-sdk sign payload.json   # sign a payload (needs GANDIA_KEY_SECRET)
-npx vaia-sdk version             # SDK version
+npx vaia init       # drops a ready vaia.config.ts — no account, no keys, no network
+npx vaia manifest   # generates the manifest from your config
+npx vaia sign       # signs a payload for testing
 ```
 
 ---
 
-## Publishing
+## Security
 
-Publication to npm is done manually by the VAIA team via `npm login` + `npm publish`.
+See [SECURITY.md](./SECURITY.md) — what the SDK guarantees, and what's on you, such as deduplicating `call_id` if replay within the window matters to you.
 
----
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md). What's open is **how to declare responsible agents**; the engines that run them are private.
 
 ## License
 
-MIT — VAIA
+MIT

package/dist/cli.js

@@ -3,6 +3,7 @@
 // src/cli.ts
 import { readFileSync, writeFileSync, existsSync } from "fs";
 import { resolve, join } from "path";
+import { pathToFileURL } from "url";
 import { createInterface } from "readline";
 
 // src/crypto.ts
@@ -22,6 +23,107 @@ async function hmacSign(secret, data) {
   return Array.from(new Uint8Array(sig)).map((b) => b.toString(16).padStart(2, "0")).join("");
 }
 
+// src/agent.ts
+var AGENT_PROTOCOL_VERSION = 1;
+var NOMBRE_ACCION = /^[a-z][a-z0-9_]{1,48}$/;
+function validateAgentSurface(cfg) {
+  const errores = [];
+  const vistos = /* @__PURE__ */ new Set();
+  for (const accion of cfg.actions ?? []) {
+    if (!NOMBRE_ACCION.test(accion.name)) {
+      errores.push(`Acci\xF3n "${accion.name}": el nombre debe ser min\xFAsculas, n\xFAmeros o guion bajo.`);
+    }
+    if (vistos.has(accion.name)) {
+      errores.push(`Acci\xF3n "${accion.name}": declarada dos veces.`);
+    }
+    vistos.add(accion.name);
+    if (!accion.description?.trim()) {
+      errores.push(`Acci\xF3n "${accion.name}": falta la descripci\xF3n, que es lo que el agente lee para elegirla.`);
+    }
+    if (accion.writes && !accion.permission) {
+      errores.push(`Acci\xF3n "${accion.name}": modifica datos, as\xED que necesita un permiso declarado.`);
+    }
+    for (const p of accion.params ?? []) {
+      if (!p.name?.trim()) errores.push(`Acci\xF3n "${accion.name}": un par\xE1metro no tiene nombre.`);
+      if (!p.description?.trim()) {
+        errores.push(`Acci\xF3n "${accion.name}", par\xE1metro "${p.name}": falta la descripci\xF3n.`);
+      }
+    }
+  }
+  if (cfg.queryEndpoint && !cfg.queryEndpoint.startsWith("/")) {
+    errores.push('queryEndpoint debe ser una ruta de tu propio servidor, empezando por "/".');
+  }
+  return errores;
+}
+
+// src/pieces.ts
+var NOMBRE = /^[a-z][a-z0-9_]{1,48}$/;
+var ORDEN = {
+  prohibida: 0,
+  requiere_aprobacion: 1,
+  autonoma: 2
+};
+function validatePieces(cfg) {
+  const errores = [];
+  const vistos = /* @__PURE__ */ new Set();
+  const revisarNombre = (pieza, name) => {
+    if (!NOMBRE.test(name)) errores.push(`${pieza} "${name}": el nombre debe ser min\xFAsculas, n\xFAmeros o guion bajo.`);
+    if (vistos.has(name)) errores.push(`"${name}": hay dos piezas con el mismo nombre.`);
+    vistos.add(name);
+  };
+  const revisarAutoridad = (pieza, a) => {
+    if (a.consequence === "irreversible" && a.level === "autonoma") {
+      errores.push(`${pieza}: una acci\xF3n irreversible no puede ser aut\xF3noma \u2014 como m\xEDnimo requiere aprobaci\xF3n.`);
+    }
+    if (a.maxAmount !== void 0) {
+      if (a.maxAmount <= 0) errores.push(`${pieza}: el tope de gasto debe ser mayor que cero.`);
+      if (!a.currency) errores.push(`${pieza}: hay tope de gasto pero no se declar\xF3 la moneda.`);
+    }
+    if (a.consequence === "costosa" && a.level === "autonoma" && a.maxAmount === void 0) {
+      errores.push(`${pieza}: es aut\xF3noma y cuesta dinero, as\xED que necesita un tope declarado.`);
+    }
+  };
+  for (const s of cfg.skills ?? []) {
+    revisarNombre("Skill", s.name);
+    if (!s.description?.trim()) errores.push(`Skill "${s.name}": falta la descripci\xF3n, que es lo que el modelo lee para elegirla.`);
+    if (s.evidence?.required && (s.evidence.accepts?.length ?? 0) === 0) {
+      errores.push(`Skill "${s.name}": exige evidencia pero no declara qu\xE9 tipos acepta.`);
+    }
+  }
+  for (const t of cfg.tools ?? []) {
+    revisarNombre("Herramienta", t.name);
+    if (!t.description?.trim()) errores.push(`Herramienta "${t.name}": falta la descripci\xF3n.`);
+    if (!t.permission?.trim()) errores.push(`Herramienta "${t.name}": toca el mundo real, as\xED que necesita un permiso declarado.`);
+    revisarAutoridad(`Herramienta "${t.name}"`, t.authority);
+  }
+  for (const w of cfg.workflows ?? []) {
+    revisarNombre("Workflow", w.name);
+    if ((w.steps?.length ?? 0) === 0) errores.push(`Workflow "${w.name}": no tiene pasos.`);
+    revisarAutoridad(`Workflow "${w.name}"`, w.authority);
+  }
+  const porNombre = new Map((cfg.tools ?? []).map((t) => [t.name, t]));
+  for (const a of cfg.agents ?? []) {
+    revisarNombre("Agente", a.name);
+    if (!a.purpose?.trim()) {
+      errores.push(`Agente "${a.name}": falta el prop\xF3sito \u2014 para qu\xE9 existe.`);
+    }
+    revisarAutoridad(`Agente "${a.name}"`, a.authority);
+    for (const nombreTool of a.tools ?? []) {
+      const tool = porNombre.get(nombreTool);
+      if (!tool) {
+        errores.push(`Agente "${a.name}": usa la herramienta "${nombreTool}", que no est\xE1 declarada.`);
+        continue;
+      }
+      if (ORDEN[tool.authority.level] > ORDEN[a.authority.level]) {
+        errores.push(
+          `Agente "${a.name}": su herramienta "${nombreTool}" tiene m\xE1s autoridad que \xE9l. Ninguna pieza puede superar el techo de su agente.`
+        );
+      }
+    }
+  }
+  return errores;
+}
+
 // src/define.ts
 function defineCapability(config) {
   const required = ["id", "name", "version", "target", "type", "sector", "permissions", "risk"];
@@ -38,6 +140,20 @@ function defineCapability(config) {
   if (Object.keys(config.surfaces).length === 0) {
     throw new Error(`[@vaia/sdk] defineCapability: 'surfaces' no puede estar vac\xEDo. Define al menos un surface con su endpoint.`);
   }
+  if (config.pieces) {
+    const errores = validatePieces(config.pieces);
+    if (errores.length > 0) {
+      throw new Error(`[@vaia/sdk] defineCapability: piezas inv\xE1lidas:
+  - ${errores.join("\n  - ")}`);
+    }
+  }
+  if (config.agent) {
+    const errores = validateAgentSurface(config.agent);
+    if (errores.length > 0) {
+      throw new Error(`[@vaia/sdk] defineCapability: superficie de agente inv\xE1lida:
+  - ${errores.join("\n  - ")}`);
+    }
+  }
   return config;
 }
 function toManifest(config) {
@@ -52,6 +168,16 @@ function toManifest(config) {
     level: config.level,
     sector: config.sector,
     surfaces,
+    // El agente viaja en el manifest para que el portal y Handeia sepan qué
+    // puede hacer este espacio sin abrir su código.
+    agent: config.agent ? {
+      protocol: AGENT_PROTOCOL_VERSION,
+      actions: config.agent.actions ?? [],
+      query_endpoint: config.agent.queryEndpoint
+    } : void 0,
+    // Las piezas viajan al manifest: el portal necesita mostrar qué autoridad
+    // pide una capacidad ANTES de que alguien la instale.
+    pieces: config.pieces,
     permissions: config.permissions,
     risk: config.risk,
     has_own_auth: config.has_own_auth ?? false,
@@ -72,6 +198,10 @@ var args = process.argv.slice(2);
 var cmd = args[0];
 async function main() {
   switch (cmd) {
+    case "init":
+      return cmdInit();
+    case "doctor":
+      return cmdDoctor();
     case "manifest":
       return cmdManifest();
     case "sign":
@@ -85,6 +215,126 @@ async function main() {
       printHelp();
   }
 }
+async function cmdInit() {
+  const cwd = process.cwd();
+  const out = join(cwd, "vaia.config.ts");
+  if (existsSync(out)) {
+    console.error("\u2717 Ya existe vaia.config.ts en esta carpeta.");
+    process.exit(1);
+  }
+  const plantilla = `import { defineCapability } from '@vaia-lab/sdk'
+
+/**
+ * Tu capacidad, declarada.
+ *
+ * Esto es la \xFAnica fuente de verdad: el portal la lee y arma el manifest solo.
+ */
+export default defineCapability({
+  id: 'mx.mi-capacidad',
+  name: 'Mi capacidad',
+  version: '0.1.0',
+  target: 'handeia',       // 'gandia' | 'handeia' | 'both'
+  type: 'app',
+  sector: 'general',
+  description: 'Describe en una l\xEDnea qu\xE9 resuelve.',
+
+  surfaces: {
+    text: { endpoint: '/api/vaia/invoke' },
+  },
+
+  // \u2500\u2500 Las piezas \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  // La autoridad NO es opcional: hay que decir hasta d\xF3nde puede llegar cada
+  // cosa. Lo irreversible nunca puede ser aut\xF3nomo, y lo que gasta dinero
+  // necesita tope y moneda. Si te lo saltas, esto no compila.
+  pieces: {
+    tools: [
+      {
+        name: 'consultar_datos',
+        description: 'Lee datos del usuario para responder preguntas.',
+        permission: 'read:datos',
+        authority: {
+          level: 'autonoma',          // 'autonoma' | 'requiere_aprobacion' | 'prohibida'
+          consequence: 'reversible',  // 'reversible' | 'costosa' | 'irreversible'
+          rationale: 'Solo lee. No cambia nada del usuario.',
+        },
+      },
+    ],
+  },
+
+  // \u2500\u2500 El agente dentro de tu app \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  // El asistente de Handeia vive en tu superficie. T\xFA declaras qu\xE9 sabes
+  // hacer; \xE9l razona con eso m\xE1s lo que sabe del usuario, que t\xFA nunca ves.
+  agent: {
+    greeting: '\xBFEn qu\xE9 te ayudo?',
+    actions: [
+      {
+        name: 'ir_a',
+        description: 'Lleva al usuario a una secci\xF3n de la app.',
+        params: [
+          { name: 'seccion', type: 'string', description: 'Secci\xF3n destino.', required: true },
+        ],
+      },
+    ],
+    // Servicios que necesitas consultar. NUNCA recibes el token del usuario:
+    // pides la operaci\xF3n y la plataforma te devuelve solo el resultado.
+    needs: [],
+  },
+
+  permissions: ['read:datos'],
+  risk: 'low',
+})
+`;
+  writeFileSync(out, plantilla, "utf8");
+  console.log("\u2713 vaia.config.ts creado");
+  console.log("");
+  console.log("  Siguiente:");
+  console.log("    1. Edita el id, el nombre y lo que sabe hacer tu app.");
+  console.log("    2. npx vaia manifest      \u2192 genera el manifest");
+  console.log("    3. S\xFAbelo desde el portal de developers.");
+}
+async function cmdDoctor() {
+  const cwd = process.cwd();
+  const configPath = resolve(cwd, "vaia.config.js");
+  if (!existsSync(configPath)) {
+    console.error("\u2717 No encontr\xE9 vaia.config.js. Compila tu vaia.config.ts primero, o corre `vaia init`.");
+    process.exit(1);
+  }
+  let config;
+  try {
+    const mod = await import(pathToFileURL(configPath).href);
+    config = mod.default ?? mod.config;
+  } catch (err) {
+    console.error(`\u2717 No pude cargar vaia.config.js:
+  ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+  const avisos = [];
+  const graves = [];
+  for (const t of config.pieces?.tools ?? []) {
+    if (t.authority.level === "autonoma" && t.authority.consequence === "costosa" && !t.authority.rationale) {
+      avisos.push(`"${t.name}" gasta dinero sola y no explica por qu\xE9 se le dio esa confianza.`);
+    }
+    if (t.permission && !config.permissions.includes(t.permission)) {
+      graves.push(`"${t.name}" pide el permiso "${t.permission}", que no est\xE1 en la lista de permisos de la capacidad.`);
+    }
+  }
+  const usados = new Set((config.pieces?.tools ?? []).map((t) => t.permission));
+  for (const p of config.permissions) {
+    if (!usados.has(p)) avisos.push(`El permiso "${p}" se pide pero ninguna herramienta lo usa. Pedir de m\xE1s incomoda al usuario.`);
+  }
+  for (const a of config.agent?.actions ?? []) {
+    if (a.writes && !a.permission) {
+      graves.push(`La acci\xF3n "${a.name}" modifica datos y no declara permiso.`);
+    }
+  }
+  if (graves.length === 0 && avisos.length === 0) {
+    console.log("\u2713 Todo en orden.");
+    return;
+  }
+  for (const g of graves) console.error(`\u2717 ${g}`);
+  for (const a of avisos) console.log(`\u26A0 ${a}`);
+  if (graves.length > 0) process.exit(1);
+}
 async function cmdManifest() {
   const cwd = process.cwd();
   const configPath = resolve(cwd, "vaia.config.js");
@@ -182,6 +432,8 @@ function printHelp() {
     `@vaia/sdk v${pkg.version}`,
     "",
     "Comandos:",
+    "  vaia-sdk init                  Crea vaia.config.ts listo para editar",
+    "  vaia-sdk doctor                Revisa tu configuraci\xF3n y avisa qu\xE9 est\xE1 mal",
     "  vaia-sdk manifest              Genera gandia.manifest.json desde vaia.config.js",
     "  vaia-sdk manifest --validate   Valida un gandia.manifest.json existente",
     "  vaia-sdk sign [payload]        Firma un payload con GANDIA_KEY_SECRET",