@johpaz/hive-sdk 0.1.4 → 0.1.5

package/docs/HIVE-HARNESS.md

@@ -7,7 +7,7 @@ packets. It's what lets a host app (a `hive-app`, or a production service like
 Hive Cloud) survive a process restart mid-task without losing work or
 double-executing a tool call.
 
-It is deliberately **not** wired into `AgentRunner` automatically, and it has
+It is deliberately **not** wired into the agent loop automatically, and it has
 no built-in notion of "chat" vs "project task" vs any other app-specific job
 type — job `type` and run `kind` are plain strings. The host app defines its
 own vocabulary and registers executors for it. This is the same infrastructure

package/docs/INDEX.md

@@ -41,7 +41,7 @@ const tool = defineTool({
 const agent = await createAgent({
   name: "asistente",
   provider: "openai",
-  model: "gpt-4o-mini",
+  model: "gpt-5.6-luna",
   tools: [tool],
 });
 
@@ -97,7 +97,7 @@ packages/
 │       ├── api/            # createAgent(), Agent interface
 │       ├── agent/          # AgentLoop, ContextCompiler, ConversationStore
 │       │   ├── providers/  # LLM providers (OpenAI, Anthropic, Gemini, Ollama)
-│       │   └── selectors/  # FTS5 ToolSelector, SkillSelector, PlaybookSelector
+│       │   └── tool-selector.ts, skill-selector.ts, playbook-selector.ts (BM25 sobre HiveDB)
 │       ├── tools/          # 70+ built-in tools + ToolRegistry + ToolExecutor
 │       ├── skills/         # SkillLoader, defineSkill()
 │       ├── swarm/          # DAGScheduler, TaskGraph, WorkerPool
@@ -105,7 +105,7 @@ packages/
 │       ├── gateway/        # HTTP/WebSocket server (Bun.serve)
 │       ├── channels/       # Telegram, Discord, WhatsApp, Slack, Webchat
 │       ├── mcp/            # MCPClientManager + transports (SSE, WS, STDIO)
-│       ├── storage/        # SQLite (bun:sqlite) + FTS5
+│       ├── storage/        # HiveDB (colecciones + BM25)
 │       ├── canvas/         # CanvasManager + A2UI emitter
 │       ├── scheduler/      # CronScheduler + DAG execution
 │       ├── tool-runtime/   # Bun Worker pool para ejecución paralela de tools
@@ -137,7 +137,7 @@ packages/
 Unidad de ejecución con configuración, contexto y ciclo de ejecución.
 
 ### Tool
-Función invocable por el agente. Definida con `defineTool()`, seleccionada vía FTS5.
+Función invocable por el agente. Definida con `defineTool()`, seleccionada por búsqueda BM25.
 
 ### Skill
 Composición de tools con triggers semánticos. Definida con `defineSkill()`.

package/docs/TEMPLATE-HIVE-APP.md

@@ -1,6 +1,6 @@
 # Template `hive-app` — Documentación Completa
 
-El template `hive-app` genera una **aplicación harness completa** lista para ejecutar. Incluye gateway HTTP/WebSocket, agente coordinador, configuración de canales, base de datos SQLite, y deployment con Docker.
+El template `hive-app` genera una **aplicación harness completa** lista para ejecutar. Incluye gateway HTTP/WebSocket, agente coordinador, configuración de canales, base de datos HiveDB, y deployment con Docker.
 
 ---
 
@@ -97,7 +97,7 @@ export default {
 | `channels.discord.enabled` | `boolean` | `false` | Bot de Discord |
 | `channels.whatsapp.enabled` | `boolean` | `false` | Bot de WhatsApp |
 | `channels.slack.enabled` | `boolean` | `false` | Bot de Slack |
-| `database.path` | `string` | `"./data/hive.db"` | Ruta de la base de datos SQLite |
+| `database.path` | `string` | `"./data/hive"` | Ruta de la base de datos HiveDB |
 
 ---
 
@@ -105,7 +105,7 @@ export default {
 
 Entry point de la aplicación. Realiza:
 
-1. Inicializa la base de datos (`initializeDatabase`)
+1. Inicializa la base de datos (`ensureHiveDb`, que además siembra el catálogo)
 2. Crea el agente coordinador (`createAgent`)
 3. Inicializa el ChannelManager
 4. Arranca el gateway (`startGateway`)
@@ -115,7 +115,7 @@ Entry point de la aplicación. Realiza:
 import {
   createAgent,
   startGateway,
-  initializeDatabase,
+  ensureHiveDb,
   ChannelManager,
   logger,
 } from "@johpaz/hive-sdk";
@@ -126,12 +126,12 @@ const log = logger.child("app");
 async function main() {
   log.info(`Starting my-hive...`);
 
-  await initializeDatabase();
+  await ensureHiveDb();
 
   const agent = await createAgent({
     name: "coordinator",
     provider: "openai",
-    model: "gpt-4o-mini",
+    model: "gpt-5.6-luna",
     systemPrompt: "You are a helpful AI assistant...",
   });
 
@@ -160,7 +160,7 @@ Puedes cambiar el `provider`, `model`, y `systemPrompt`:
 ```typescript
 const agent = await createAgent({
   name: "coordinator",
-  provider: "anthropic",        // "openai" | "anthropic" | "gemini" | "ollama"
+  provider: "anthropic",        // cualquiera de los 16 del catálogo
   model: "claude-3-5-sonnet-20241022",
   systemPrompt: "Tu system prompt personalizado...",
 });
@@ -183,7 +183,7 @@ const searchTool = defineTool({
 const agent = await createAgent({
   name: "coordinator",
   provider: "openai",
-  model: "gpt-4o-mini",
+  model: "gpt-5.6-luna",
   tools: [searchTool],
 });
 ```
@@ -200,7 +200,7 @@ import { createAgent } from "@johpaz/hive-sdk";
 export const coordinatorAgent = await createAgent({
   name: "coordinator",
   provider: "openai",
-  model: "gpt-4o-mini",
+  model: "gpt-5.6-luna",
   systemPrompt: "You are the coordinator agent...",
 });
 ```
@@ -278,7 +278,7 @@ LOG_LEVEL=info
 |----------|-----------|-------------|
 | `HIVE_HOST` | No | Host del gateway |
 | `HIVE_PORT` | No | Puerto del gateway |
-| `HIVE_DATA_DIR` | No | Directorio de datos SQLite |
+| `HIVE_HOME` | No | Directorio de datos (HiveDB en `<HIVE_HOME>/data`) |
 | `OPENAI_API_KEY` | Sí* | API key de OpenAI |
 | `ANTHROPIC_API_KEY` | Sí* | API key de Anthropic |
 | `GOOGLE_API_KEY` | Sí* | API key de Gemini |

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@johpaz/hive-sdk",
-  "version": "0.1.4",
+  "version": "0.1.5",
+  "private": false,
   "description": "Hive SDK — The Agent Harness SDK. Build, deploy, and scale AI agent applications with multi-channel support, context engineering, and swarm orchestration.",
   "license": "MIT",
   "homepage": "https://github.com/johpaz/hive-sdk#readme",
@@ -31,14 +32,15 @@
     ".": "./packages/core/src/index.ts",
     "./agent": "./packages/core/src/agent/index.ts",
     "./agent/providers": "./packages/core/src/agent/providers/index.ts",
-    "./agent/selectors": "./packages/core/src/agent/selectors/index.ts",
     "./tools": "./packages/core/src/tools/index.ts",
     "./skills": "./packages/core/src/skills/index.ts",
     "./storage": "./packages/core/src/storage/index.ts",
     "./swarm": "./packages/core/src/swarm/index.ts",
     "./swarm/strategies": "./packages/core/src/swarm/strategies/index.ts",
     "./swarm/presets": "./packages/core/src/swarm/presets/index.ts",
-    "./ace": "./packages/core/src/ace/index.ts",
+    "./scheduler": "./packages/core/src/scheduler/index.ts",
+    "./workers": "./packages/core/src/workers/index.ts",
+    "./events": "./packages/core/src/events/event-bus.ts",
     "./ethics": "./packages/core/src/ethics/index.ts",
     "./canvas": "./packages/core/src/canvas/index.ts",
     "./config": "./packages/core/src/config/index.ts",
@@ -63,8 +65,11 @@
   ],
   "scripts": {
     "build": "bun run typecheck",
-    "typecheck": "tsc --build --force",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
     "test": "bun test",
+    "skills:bundle": "bun scripts/generate-skill-bundle.ts",
+    "version:set": "bun scripts/bump-version.ts",
+    "release": "bun scripts/bump-version.ts --push",
     "prepublish": "echo 'No build needed - Bun runs TypeScript directly'"
   },
   "dependencies": {

package/packages/cli/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@hive/cli",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "Hive CLI — init, run, test, trace",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "hive": "./src/index.ts"
+    "hives": "./src/index.ts"
   },
   "main": "./src/index.ts",
   "exports": {

package/packages/cli/src/commands/create-app.test.ts

@@ -31,10 +31,24 @@ describe("hive create-app", () => {
     expect(existsSync(join(TEST_DIR, "docker-compose.yml"))).toBe(true);
     expect(existsSync(join(TEST_DIR, ".env.example"))).toBe(true);
     expect(existsSync(join(TEST_DIR, ".gitignore"))).toBe(true);
+    // Sin README el que corre `hives create-app` queda sin una sola instrucción.
+    expect(existsSync(join(TEST_DIR, "README.md"))).toBe(true);
     expect(existsSync(join(TEST_DIR, "src", "main.ts"))).toBe(true);
     expect(existsSync(join(TEST_DIR, "src", "agents", "coordinator.ts"))).toBe(true);
   });
 
+  it("el README del scaffold lleva el nombre de la app y arranca con los pasos", async () => {
+    const { copyTemplate } = await import("./create-app-utils.ts");
+
+    copyTemplate(TEST_DIR, { "{{APP_NAME}}": "mi-app" });
+
+    const readme = readFileSync(join(TEST_DIR, "README.md"), "utf-8");
+    expect(readme).toContain("# mi-app");
+    expect(readme).not.toContain("{{APP_NAME}}");
+    expect(readme).toContain("bun install");
+    expect(readme).toContain("bun run dev");
+  });
+
   it("replaces {{APP_NAME}} placeholder in all files", async () => {
     const { copyTemplate } = await import("./create-app-utils.ts");
 
@@ -43,8 +57,10 @@ describe("hive create-app", () => {
     const packageJson = readFileSync(join(TEST_DIR, "package.json"), "utf-8");
     expect(packageJson).toContain('"name": "my-awesome-app"');
 
+    // `Config` no tiene una clave `name`, así que el nombre de la app sólo se
+    // sustituye en el comentario de cabecera y en package.json.
     const config = readFileSync(join(TEST_DIR, "hive.config.ts"), "utf-8");
-    expect(config).toContain('name: "my-awesome-app"');
+    expect(config).toContain("my-awesome-app");
 
     const main = readFileSync(join(TEST_DIR, "src", "main.ts"), "utf-8");
     expect(main).toContain("Starting my-awesome-app...");
@@ -80,7 +96,11 @@ describe("hive create-app", () => {
     expect(config).toContain("discord: { enabled: false }");
     expect(config).toContain("whatsapp: { enabled: false }");
     expect(config).toContain("slack: { enabled: false }");
-    expect(config).toContain('path: process.env.HIVE_DATA_DIR ?? "./data/hive.db"');
+    // HiveDB no se configura por `hive.config.ts`: la ruta sale de HIVE_HOME /
+    // HIVE_DB_PATH. Una clave `database` acá rompería el `satisfies Config`.
+    expect(config).not.toContain("database:");
+    expect(config).not.toContain("hive.db");
+    expect(config).toContain("satisfies Config");
   });
 
   it("generates main.ts with all required imports", async () => {
@@ -91,15 +111,21 @@ describe("hive create-app", () => {
     const main = readFileSync(join(TEST_DIR, "src", "main.ts"), "utf-8");
 
     expect(main).toContain('from "@johpaz/hive-sdk"');
-    expect(main).toContain("createAgent");
     expect(main).toContain("startGateway");
-    expect(main).toContain("initializeDatabase");
+    // `initializeDatabase()` desapareció con la capa SQLite: `ensureHiveDb()`
+    // abre HiveDB, crea los índices y siembra el catálogo en un solo paso.
+    expect(main).toContain("ensureHiveDb");
+    expect(main).not.toContain("initializeDatabase");
     expect(main).toContain("ChannelManager");
     expect(main).toContain("logger");
     expect(main).toContain('import config from "../hive.config.ts"');
-    expect(main).toContain("await initializeDatabase()");
+    expect(main).toContain("await ensureHiveDb()");
     expect(main).toContain('await startGateway({');
     expect(main).toContain('process.on("SIGINT"');
+    // El coordinador se define una sola vez, en su módulo, y main.ts lo usa —
+    // antes el template creaba uno propio y dejaba coordinator.ts huérfano.
+    expect(main).toContain('from "./agents/coordinator.ts"');
+    expect(main).toContain("agentId: coordinatorAgent.id");
   });
 
   it("generates coordinator agent with correct config", async () => {
@@ -112,7 +138,10 @@ describe("hive create-app", () => {
     expect(agent).toContain('import { createAgent } from "@johpaz/hive-sdk"');
     expect(agent).toContain('name: "coordinator"');
     expect(agent).toContain('provider: "openai"');
-    expect(agent).toContain('model: "gpt-4o-mini"');
+    // El modelo del scaffold tiene que existir en SEED_DATA.models, o el primer
+    // `bun run dev` de un usuario nuevo muere con "no está en el catálogo".
+    expect(agent).toContain('model: "gpt-5.6-luna"');
+    expect(agent).toContain("export const coordinatorAgent");
   });
 
   it("generates docker-compose.yml with correct ports", async () => {
@@ -139,7 +168,7 @@ describe("hive create-app", () => {
 
     expect(env).toContain("HIVE_HOST=");
     expect(env).toContain("HIVE_PORT=");
-    expect(env).toContain("HIVE_DATA_DIR=");
+    expect(env).toContain("HIVE_HOME=");
     expect(env).toContain("OPENAI_API_KEY=");
     expect(env).toContain("ANTHROPIC_API_KEY=");
     expect(env).toContain("GOOGLE_API_KEY=");

package/packages/cli/src/commands/init.ts

@@ -9,12 +9,12 @@ const HIVE_CONFIG = `{
   "version": "0.1.0",
   "type": "module",
   "dependencies": {
-    "@hive/core": "latest"
+    "@johpaz/hive-sdk": "latest"
   }
 }
 `;
 
-const HIVE_AGENT_TS = `import { createAgent, defineTool } from "@hive/core";
+const HIVE_AGENT_TS = `import { createAgent, defineTool } from "@johpaz/hive-sdk";
 
 const myTool = defineTool({
   name: "hello",
@@ -26,7 +26,7 @@ const myTool = defineTool({
 
 const agent = await createAgent({
   name: "my-agent",
-  model: "gpt-4o",
+  model: "gpt-5.6-luna",
   provider: "openai",
   tools: [myTool],
 });

package/packages/cli/src/commands/run.ts

@@ -10,7 +10,7 @@ async function runCommand() {
 	}
 
 	console.log(`Running agent from ${agentFile}...`);
-	const { createAgent } = await import("@hive/core");
+	const { createAgent } = await import("@johpaz/hive-sdk");
 	const agentModule = await import(agentFile);
 
 	if (agentModule.agent) {

package/packages/cli/src/commands/test.ts

@@ -1,42 +1,54 @@
 export {};
+
+/**
+ * `hives test` — corre los tests del proyecto del usuario.
+ *
+ * Antes hacía glob sobre `packages/core/src/**` — rutas del repo del SDK, no del
+ * proyecto donde se ejecuta el comando, así que en la práctica no encontraba
+ * nada. Ahora busca en `src/` y `test(s)/` del cwd.
+ */
 async function testCommand() {
 	const filter = process.argv[3];
 
 	console.log("Hive Test Runner\n");
 
-	const { initializeDatabase, dbService } = await import("@hive/core");
-	await initializeDatabase();
+	const { ensureHiveDb } = await import("@johpaz/hive-sdk");
+	await ensureHiveDb();
 
 	const { Glob } = await import("bun");
-	const glob = new Glob("packages/core/src/**/*.{test,spec}.ts");
-	const testFiles = Array.from(glob.scanSync({ cwd: process.cwd(), absolute: true }));
+	const patterns = ["src/**/*.{test,spec}.ts", "test/**/*.{test,spec}.ts", "tests/**/*.{test,spec}.ts"];
+
+	const seen = new Set<string>();
+	for (const pattern of patterns) {
+		for (const file of new Glob(pattern).scanSync({ cwd: process.cwd(), absolute: true })) {
+			seen.add(file);
+		}
+	}
 
-	const tests = filter
-		? testFiles.filter((f: string) => f.includes(filter))
-		: testFiles;
+	const tests = [...seen].filter((f) => !filter || f.includes(filter)).sort();
 
 	if (tests.length === 0) {
-		console.log("No tests found.");
-	} else {
-		console.log(`Found ${tests.length} test(s)\n`);
-		let passed = 0;
-		let failed = 0;
-
-		for (const test of tests as string[]) {
-			try {
-				await import(test);
-				console.log(`  ✓ ${test.split("/").pop()}`);
-				passed++;
-			} catch (err) {
-				console.error(`  ✗ ${test.split("/").pop()}: ${(err as Error).message}`);
-				failed++;
-			}
-		}
+		console.log("No tests found under src/, test/ or tests/.");
+		return;
+	}
 
-		console.log(`\n${passed} passed, ${failed} failed`);
+	console.log(`Found ${tests.length} test(s)\n`);
+	let passed = 0;
+	let failed = 0;
+
+	for (const test of tests) {
+		try {
+			await import(test);
+			console.log(`  ✓ ${test.split("/").pop()}`);
+			passed++;
+		} catch (err) {
+			console.error(`  ✗ ${test.split("/").pop()}: ${(err as Error).message}`);
+			failed++;
+		}
 	}
 
-	dbService.close();
+	console.log(`\n${passed} passed, ${failed} failed`);
+	if (failed > 0) process.exitCode = 1;
 }
 
 testCommand();

package/packages/cli/src/commands/trace.ts

@@ -1,10 +1,15 @@
 export {};
+
+/**
+ * `hives trace` — últimas ejecuciones registradas por el ACE Tracer.
+ *
+ * Los traces pasaron de una tabla SQLite a la colección `traces` de HiveDB en
+ * 0.1.5, así que esto ya no es una query SQL.
+ */
 async function traceCommand() {
-	const { initializeDatabase } = await import("@hive/core");
-	const { getDb } = await import("@hive/core/storage");
+	const { ensureHiveDb, col } = await import("@johpaz/hive-sdk");
 
-	await initializeDatabase();
-	const db = getDb();
+	await ensureHiveDb();
 
 	const limit = parseInt(process.argv[3] || "20", 10);
 
@@ -12,43 +17,40 @@ async function traceCommand() {
 	console.log("─".repeat(80));
 
 	try {
-		const rows = db
-			.query(
-				`SELECT id, agent_id, model, tool_calls, duration_ms, tokens_used, created_at
-         FROM traces
-         ORDER BY created_at DESC
-         LIMIT ?`
-			)
-			.all(limit) as Array<{
-			id: string;
+		const tracesCol = await col<{
 			agent_id: string;
 			model: string;
-			tool_calls: string;
-			duration_ms: number;
-			tokens_used: number;
-			created_at: string;
-		}>;
+			provider?: string;
+			tool_calls?: string | null;
+			duration_ms?: number;
+			tokens_used?: number;
+			created_at: number;
+		}>("traces");
+
+		const rows = (await tracesCol.scan({}))
+			.sort((a, b) => b.doc.created_at - a.doc.created_at)
+			.slice(0, limit);
 
 		if (rows.length === 0) {
-			console.log("No traces found.");
+			console.log("No traces found (run the agent first).");
 			return;
 		}
 
 		for (const row of rows) {
 			console.log(`ID:        ${row.id}`);
-			console.log(`Agent:     ${row.agent_id}`);
-			console.log(`Model:     ${row.model}`);
-			console.log(`Duration:  ${row.duration_ms}ms`);
-			console.log(`Tokens:    ${row.tokens_used}`);
-			console.log(`Time:      ${row.created_at}`);
-			if (row.tool_calls) {
-				const tools = JSON.parse(row.tool_calls);
-				console.log(`Tools:     ${Array.isArray(tools) ? tools.join(", ") : row.tool_calls}`);
+			console.log(`Agent:     ${row.doc.agent_id}`);
+			console.log(`Model:     ${row.doc.provider ? `${row.doc.provider}/` : ""}${row.doc.model}`);
+			console.log(`Duration:  ${row.doc.duration_ms ?? 0}ms`);
+			console.log(`Tokens:    ${row.doc.tokens_used ?? 0}`);
+			console.log(`Time:      ${new Date(row.doc.created_at).toISOString()}`);
+			if (row.doc.tool_calls) {
+				const tools = JSON.parse(row.doc.tool_calls);
+				console.log(`Tools:     ${Array.isArray(tools) ? tools.join(", ") : row.doc.tool_calls}`);
 			}
 			console.log("─".repeat(80));
 		}
 	} catch (err) {
-		console.log("No traces table found (run the agent first).");
+		console.error(`No se pudieron leer los traces: ${(err as Error).message}`);
 	}
 }
 

package/packages/cli/templates/hive-app/.env.example

@@ -1,12 +1,20 @@
 # Hive Harness Configuration
 HIVE_HOST=127.0.0.1
 HIVE_PORT=18790
-HIVE_DATA_DIR=./data
 
-# LLM Providers
+# Directorio de datos. HiveDB vive en <HIVE_HOME>/data.
+HIVE_HOME=./.hive
+# Ruta explícita de la base (opcional). ":memory:" para una base efímera.
+# HIVE_DB_PATH=
+
+# LLM Providers — <PROVIDER>_API_KEY, en mayúsculas y con el id del provider.
+# La clave también se puede cargar cifrada en la base desde la app.
 OPENAI_API_KEY=sk-...
 ANTHROPIC_API_KEY=sk-ant-...
 GOOGLE_API_KEY=...
+# MODELSCOPE_API_KEY=ms-...
+# NVIDIA_API_KEY=nvapi-...
+# OPENROUTER_API_KEY=sk-or-...
 
 # Channels (enable as needed)
 TELEGRAM_BOT_TOKEN=

package/packages/cli/templates/hive-app/README.md

@@ -0,0 +1,103 @@
+# {{APP_NAME}}
+
+Aplicación de agentes construida sobre [`@johpaz/hive-sdk`](https://www.npmjs.com/package/@johpaz/hive-sdk).
+
+## Arrancar
+
+```bash
+bun install
+cp .env.example .env     # cargá al menos una API key
+bun run dev
+```
+
+El gateway queda en `http://127.0.0.1:18790`. Probalo:
+
+```bash
+curl -X POST http://127.0.0.1:18790/chat \
+  -H "Content-Type: application/json" \
+  -d '{"message":"Hola","threadId":"t1"}'
+```
+
+## Estructura
+
+```
+src/
+  main.ts                 # arranque: base de datos, canales y gateway
+  agents/coordinator.ts   # el agente principal
+hive.config.ts            # gateway, canales y logging
+```
+
+`main.ts` llama a `ensureHiveDb()`, que abre HiveDB, crea los índices y siembra
+el catálogo de providers y modelos. Es idempotente: correrlo en cada arranque es
+justamente cómo se actualiza el catálogo.
+
+## Cambiar de modelo
+
+En `src/agents/coordinator.ts`. `provider` y `model` tienen que existir en el
+catálogo sembrado, o `createAgent` lanza avisando cuál falta:
+
+```typescript
+export const coordinatorAgent = await createAgent({
+  name: "coordinator",
+  provider: "anthropic",
+  model: "claude-opus-5",
+  systemPrompt: "...",
+});
+```
+
+Hay 18 providers y 106 modelos disponibles. La API key sale de la variable
+`<PROVIDER>_API_KEY` (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `MODELSCOPE_API_KEY`…).
+
+## Agregar una tool
+
+```typescript
+import { createAgent, defineTool } from "@johpaz/hive-sdk";
+import { z } from "zod";
+
+const clima = defineTool({
+  name: "get_weather",
+  description: "Consulta el clima de una ciudad. Sinónimos: tiempo, temperatura",
+  schema: z.object({ city: z.string().describe("la ciudad") }),
+  execute: async ({ city }) => `Soleado en ${city}`,
+});
+
+export const coordinatorAgent = await createAgent({
+  name: "coordinator",
+  provider: "anthropic",
+  model: "claude-opus-5",
+  tools: [clima],
+});
+```
+
+Dos cosas que conviene saber sobre cómo el agente usa las tools:
+
+- El **`description` es lo que la hace encontrable**. El agente arranca con un
+  loadout mínimo y descubre el resto buscando por capacidad, así que poner
+  sinónimos en la descripción es lo que hace que aparezca cuando corresponde.
+- El **`schema` de Zod se traduce a los parámetros que ve el modelo**. Sin
+  schema, la tool se le ofrece sin argumentos.
+
+## Comandos
+
+```bash
+bun run dev      # desarrollo
+bun run start    # producción
+hives add-tool <nombre>     # scaffold de una tool
+hives add-skill <nombre>    # scaffold de una skill
+hives trace                 # últimas ejecuciones del agente
+```
+
+## Datos
+
+HiveDB vive en `<HIVE_HOME>/data` (por defecto `./.hive/data`). Para una base
+efímera —tests— usá `HIVE_DB_PATH=":memory:"`.
+
+## Docker
+
+```bash
+docker compose up -d
+```
+
+## Documentación
+
+[github.com/johpaz/hive-sdk](https://github.com/johpaz/hive-sdk#readme)

package/packages/cli/templates/hive-app/hive.config.ts

@@ -1,7 +1,13 @@
 import type { Config } from "@johpaz/hive-sdk";
 
+/**
+ * Configuración de {{APP_NAME}}.
+ *
+ * La ruta de la base no se configura acá: HiveDB vive en `<HIVE_HOME>/data`, o
+ * en `HIVE_DB_PATH` si lo definís. Usá `HIVE_DB_PATH=":memory:"` para una base
+ * efímera (tests).
+ */
 export default {
-  name: "{{APP_NAME}}",
   gateway: {
     host: process.env.HIVE_HOST ?? "127.0.0.1",
     port: Number(process.env.HIVE_PORT ?? 18790),
@@ -13,7 +19,7 @@ export default {
     whatsapp: { enabled: false },
     slack: { enabled: false },
   },
-  database: {
-    path: process.env.HIVE_DATA_DIR ?? "./data/hive.db",
+  logging: {
+    level: (process.env.LOG_LEVEL as "debug" | "info" | "warn" | "error") ?? "info",
   },
 } satisfies Config;

package/packages/cli/templates/hive-app/src/agents/coordinator.ts

@@ -1,9 +1,16 @@
 import { createAgent } from "@johpaz/hive-sdk";
 
+/**
+ * El coordinador de la app.
+ *
+ * `provider` y `model` tienen que existir en el catálogo sembrado (ver
+ * `SEED_DATA.models`): `createAgent` los valida y los persiste en la fila del
+ * agente, que es de donde el loop resuelve a qué modelo llamar.
+ */
 export const coordinatorAgent = await createAgent({
   name: "coordinator",
   provider: "openai",
-  model: "gpt-4o-mini",
+  model: "gpt-5.6-luna",
   systemPrompt:
     "You are the coordinator agent. You orchestrate tasks, answer questions, and delegate to specialized agents when needed.",
 });