orquestra-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 José Alfonso Guerrero Juárez
+
+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

@@ -0,0 +1,196 @@
+# orquestra-mcp
+
+Servidor MCP (Model Context Protocol) para Orquestra. Expone **35 tools**
+que llaman a la API de `orquestra-infra`: lectura de contexto/dashboard/
+workspace/infra/paridad/listados, y escritura de tareas/ideas/changelog/
+notas/docs/módulos/flujo/categorías/infra/proyectos — un agente puede
+prácticamente todo lo que un humano hace en la web, directo desde la
+conversación. `get_setup_guide` documenta el orden recomendado para
+configurar/sincronizar un proyecto completo sin crear duplicados.
+
+Ver `CLAUDE.md` para contexto de desarrollo. Ver la memoria del proyecto
+`orquestra-mcp-api-plan` para las 8 fases del plan MCP/API completo.
+
+## Setup rápido (recomendado)
+
+```bash
+npm install
+node bin/orquestra-mcp.mjs setup
+```
+
+Esto abre tu navegador en `https://app.orquestra.me/cli-auth` para
+confirmar tu sesión (Google o email/password, lo que ya uses) y:
+
+- Si **no tienes** workspace/proyecto todavía: te crea uno default
+  ("Mi primer proyecto", con los 6 estatus base) — puedes renombrarlo o
+  cambiarlo cuando quieras desde `orquestra-web`.
+- Si **ya tienes** uno o varios: te deja elegir cuál usar por default
+  desde la misma terminal.
+
+Guarda todo (`apiToken`, `workspaceId`, `defaultProjectId`) en
+`~/.orquestra/mcp-config.json` — después de esto, `node bin/orquestra-mcp.mjs`
+(sin más flags ni env vars) ya funciona.
+
+Variable opcional `ORQUESTRA_WEB_URL` para apuntar el login a otro lugar
+(ej. `http://localhost:5173` mientras desarrollas `orquestra-web` local en
+vez de contra producción).
+
+## Setup manual (alternativa, sin el flujo de navegador)
+
+Si preferís generar el token vos mismo en vez de usar `setup`:
+
+1. **Cuenta + workspace en `orquestra-web`**: entra a la app, si no tienes
+   `workspaceId` te manda al wizard de onboarding.
+2. **Token de servicio**, con esa misma sesión ya logueada:
+
+   ```bash
+   curl -X POST "$API_BASE/v1/tokens" \
+     -H "Authorization: Bearer $FIREBASE_ID_TOKEN" \
+     -H "Content-Type: application/json" \
+     -d '{"workspaceId":"<workspace-id>"}'
+   ```
+
+   El token se muestra **una sola vez** — guárdalo.
+3. Pasa `ORQUESTRA_API_TOKEN`/`ORQUESTRA_WORKSPACE_ID` como env vars (ver
+   abajo) — en este modo `projectId` es obligatorio en cada tool call, ya
+   que no hay `defaultProjectId` guardado.
+
+## Configuración
+
+Variables de entorno (todas opcionales si ya corriste `setup` — se leen de
+`~/.orquestra/mcp-config.json` como fallback):
+
+| Variable | Requerida sin `setup` | Default |
+|---|---|---|
+| `ORQUESTRA_API_TOKEN` | sí | — |
+| `ORQUESTRA_WORKSPACE_ID` | sí | — |
+| `ORQUESTRA_DEFAULT_PROJECT_ID` | no | — |
+| `ORQUESTRA_API_BASE` | no | `ApiBaseUrl` de producción |
+| `ORQUESTRA_WEB_URL` (solo `setup`) | no | `https://app.orquestra.me` |
+
+### Claude Code
+
+Si ya corriste `setup`, alcanza con:
+
+```bash
+claude mcp add orquestra -- node /ruta/absoluta/a/orquestra-mcp/bin/orquestra-mcp.mjs
+```
+
+O manual, sin `setup`:
+
+```bash
+claude mcp add orquestra \
+  -e ORQUESTRA_API_TOKEN=orq_... \
+  -e ORQUESTRA_WORKSPACE_ID=... \
+  -- node /ruta/absoluta/a/orquestra-mcp/bin/orquestra-mcp.mjs
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "orquestra": {
+      "command": "node",
+      "args": ["/ruta/absoluta/a/orquestra-mcp/bin/orquestra-mcp.mjs"]
+    }
+  }
+}
+```
+
+(sin `env` si ya corriste `setup`; si no, agrega `ORQUESTRA_API_TOKEN`/`ORQUESTRA_WORKSPACE_ID` igual que en Claude Code.)
+
+## Tools
+
+Lectura de contexto:
+
+| Tool | Args | Descripción |
+|---|---|---|
+| `get_project_context` | `projectId?` | Snapshot compacto del proyecto (fase, tareas abiertas/vencidas/bloqueadas, módulos, ideas, changelog reciente) |
+| `list_tasks` | `projectId?`, `statusId?` | Lista de tareas, filtro opcional por estatus |
+| `search` | `projectId?`, `q` | Búsqueda por texto en tareas/notas/ideas/docs |
+| `get_dashboard_summary` | `projectId?` | Hoy/vencidas/bloqueadas, salud de módulos, actividad reciente |
+| `get_infra_status` | `projectId?` | Servicios, entornos y distribuciones con conteos operational/degraded/down |
+| `get_parity_summary` | `projectId?` | Desfases de paridad multiplataforma (tasks y modules por separado) |
+| `get_workspace_summary` | — | Progreso agregado de todos los proyectos del workspace |
+| `get_stage_playbook` | `stageId` | Plantilla de módulo+tareas para una etapa (`pre`\|`build`\|`post`) — sin red |
+| `get_setup_guide` | — | Orden recomendado (flujo→categorías→infra→módulos→tareas→ideas→notas→changelog→docs) para configurar/sincronizar sin duplicar — sin red |
+| `list_modules` / `list_statuses` / `list_categories` / `list_services` / `list_environments` / `list_distributions` | `projectId?` | Lista completa de cada entidad — revísalos antes de `create_*` para no duplicar (patrón upsert) |
+
+Creación (`create_*`) y edición (`update_*`) — mismo patrón en todos, solo
+crear/editar, sin `delete_*`:
+
+| Entidad | Tools | Notas |
+|---|---|---|
+| Tareas | `create_task`, `update_task` | `update_task` incluye `scope` — úsalo para resolver desfases de paridad |
+| Ideas | `create_idea` | |
+| Changelog | `create_changelog_entry` | Estilo Keep a Changelog |
+| Notas | `create_note` | |
+| Docs | `create_doc` | |
+| Módulos | `create_module`, `update_module` | `scope` también editable |
+| Flujo (estatus) | `create_status`, `update_status` | `nextIds` define las transiciones válidas |
+| Categorías | `create_category`, `update_category` | |
+| Servicios | `create_service`, `update_service` | `update_service` para cambiar `status` tras un incidente |
+| Entornos | `create_environment`, `update_environment` | `update_environment` para reflejar un deploy |
+| Distribuciones | `create_distribution`, `update_distribution` | |
+
+Compuestas:
+
+| Tool | Args | Descripción |
+|---|---|---|
+| `init_project` | `name`, `description?`, `phase?`, `projectType?`, `distributions?`, `categories?` | Crea un proyecto nuevo en el workspace — categorías+distribuciones+flujo conectado en un paso |
+| `apply_stage_playbook` | `stageId`, `moduleName?`, `includeDates?` | Crea el módulo + todas las tareas de la plantilla de una etapa |
+
+Los campos enum (`type`, `priority`, `status`, etc.) están fijos y
+documentados en el `inputSchema` de cada tool — el modelo los ve sin
+adivinar. Todo lo que se crea/edita aparece en vivo en `orquestra-web`
+(misma colección de Firestore, mismo `onSnapshot`).
+
+`projectId` es opcional en todas las tools de proyecto si hay un
+`defaultProjectId` configurado (por `setup` o por
+`ORQUESTRA_DEFAULT_PROJECT_ID`) — si no hay ninguno de los dos, la tool
+devuelve error pidiendo uno explícito. `get_workspace_summary` e
+`init_project` no usan `projectId` en absoluto (operan a nivel workspace).
+
+El `workspaceId` nunca es un argumento de las tools — viene fijo de la
+configuración, así el token de servicio no puede usarse fuera del
+workspace para el que se creó.
+
+## Probar localmente
+
+```bash
+npm install
+ORQUESTRA_API_TOKEN=orq_... ORQUESTRA_WORKSPACE_ID=... \
+  npx @modelcontextprotocol/inspector node bin/orquestra-mcp.mjs
+```
+
+Abre la UI del inspector y llama las tools contra un proyecto real.
+
+## Flujo recomendado para configurar/sincronizar un proyecto
+
+Para que un agente pueda "barrer" un proyecto completo (llenar o
+actualizar todo sin crear duplicados), el patrón es:
+
+1. Llamar `get_setup_guide` una vez al inicio de la conversación de setup.
+2. Para cada sección, en el orden que indica la guía: listar lo existente
+   (`list_*`/`search`), decidir por coincidencia de `name`/`title`/`type`
+   si ya hay algo — `update_*` si sí, `create_*` si no.
+3. Respetar el orden: flujo → categorías → infra → módulos → tareas →
+   ideas → notas → changelog → docs — los módulos y tareas referencian
+   ids (`statusId`, `categoryId`) que deben existir antes.
+
+No hay ninguna tool que haga esto automáticamente de punta a punta — la
+guía orienta al agente, pero decidir qué contenido va en cada
+create/update sigue siendo criterio del agente y del humano.
+
+## Estado
+
+35 tools: 8 de lectura (contexto/tasks/search + dashboard/workspace/infra/
+paridad/playbook) + 6 `list_*` + `get_setup_guide` + 18 de creación/
+edición (tasks/ideas/changelog/notes/docs + módulos/flujo/categorías/
+servicios/entornos/distribuciones) + 2 compuestas (init_project,
+apply_stage_playbook). No hay `delete_*`, ni `update_idea`/`update_note`/
+`update_doc`/`update_changelog_entry` todavía. Distribuido por ahora vía
+path local o `npx github:ajuarez93/orquestra-mcp` — publish a npm como
+`orquestra-mcp` queda pendiente (requiere crear el scope `orquestra` en
+npmjs.com).

package/bin/orquestra-mcp.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { createServer } from '../src/server.mjs'
+import { runSetup } from '../src/setup.mjs'
+
+async function main() {
+  if (process.argv[2] === 'setup') {
+    await runSetup()
+    return
+  }
+
+  let server
+  try {
+    server = createServer()
+  } catch (err) {
+    console.error(`[orquestra-mcp] ${err.message}`)
+    process.exit(1)
+  }
+
+  const transport = new StdioServerTransport()
+  await server.connect(transport)
+}
+
+main().catch((err) => {
+  console.error('[orquestra-mcp] Error fatal:', err)
+  process.exit(1)
+})

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "orquestra-mcp",
+  "version": "1.0.0",
+  "description": "Servidor MCP de Orquestra -- 35 tools para leer y escribir tareas, ideas, changelog, infraestructura y más desde un agente de IA",
+  "type": "module",
+  "bin": {
+    "orquestra-mcp": "./bin/orquestra-mcp.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "homepage": "https://orquestra.me/mcp",
+  "keywords": ["mcp", "model-context-protocol", "orquestra", "claude", "ai-agent"],
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.23.8"
+  }
+}

package/src/api.mjs

@@ -0,0 +1,82 @@
+import { readConfigFile, CONFIG_PATH } from './configFile.mjs'
+
+const DEFAULT_API_BASE = 'https://if9c2vlf35.execute-api.us-east-1.amazonaws.com'
+
+export function loadConfig() {
+  const fileConfig = readConfigFile()
+  const apiBase = process.env.ORQUESTRA_API_BASE || fileConfig?.apiBase || DEFAULT_API_BASE
+  const apiToken = process.env.ORQUESTRA_API_TOKEN || fileConfig?.apiToken
+  const workspaceId = process.env.ORQUESTRA_WORKSPACE_ID || fileConfig?.workspaceId
+  const defaultProjectId = process.env.ORQUESTRA_DEFAULT_PROJECT_ID || fileConfig?.defaultProjectId
+
+  const missing = []
+  if (!apiToken) missing.push('ORQUESTRA_API_TOKEN')
+  if (!workspaceId) missing.push('ORQUESTRA_WORKSPACE_ID')
+  if (missing.length) {
+    throw new Error(
+      `Faltan variables de entorno requeridas: ${missing.join(', ')} (y no hay config en ${CONFIG_PATH}). ` +
+      `Corre "npx orquestra-mcp setup" para conectarlo con tu cuenta -- crea un workspace/proyecto ` +
+      `default si no tienes uno, o te deja elegir uno existente. Alternativa manual: 1) cuenta+workspace ` +
+      `ya creados en orquestra-web, 2) generar un token con POST ${apiBase}/v1/tokens con tu ID token ` +
+      `de Firebase, y 3) pasar ese token + el workspaceId acá.`
+    )
+  }
+
+  return { apiBase, apiToken, workspaceId, defaultProjectId }
+}
+
+export class ApiError extends Error {
+  constructor(status, message) {
+    super(message)
+    this.status = status
+  }
+}
+
+function buildUrl(config, path, params) {
+  const url = new URL(path, config.apiBase)
+  url.searchParams.set('workspaceId', config.workspaceId)
+  for (const [key, value] of Object.entries(params)) {
+    if (value !== undefined && value !== null && value !== '') url.searchParams.set(key, value)
+  }
+  return url
+}
+
+async function parseResponse(res) {
+  const text = await res.text()
+  let body
+  try { body = text ? JSON.parse(text) : null } catch { body = text }
+
+  if (!res.ok) {
+    const message = (body && body.error) || (typeof body === 'string' ? body : `HTTP ${res.status}`)
+    throw new ApiError(res.status, message)
+  }
+  return body
+}
+
+export async function apiGet(config, path, params = {}) {
+  const url = buildUrl(config, path, params)
+  const res = await fetch(url, {
+    headers: { Authorization: `Bearer ${config.apiToken}` },
+  })
+  return parseResponse(res)
+}
+
+export async function apiPost(config, path, { projectId, ...body }) {
+  const url = buildUrl(config, path, { projectId })
+  const res = await fetch(url, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${config.apiToken}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+  return parseResponse(res)
+}
+
+export async function apiPatch(config, path, { projectId, id, ...body }) {
+  const url = buildUrl(config, `${path}/${id}`, { projectId })
+  const res = await fetch(url, {
+    method: 'PATCH',
+    headers: { Authorization: `Bearer ${config.apiToken}`, 'Content-Type': 'application/json' },
+    body: JSON.stringify(body),
+  })
+  return parseResponse(res)
+}

package/src/configFile.mjs

@@ -0,0 +1,19 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { homedir } from 'os'
+import { join, dirname } from 'path'
+
+export const CONFIG_PATH = join(homedir(), '.orquestra', 'mcp-config.json')
+
+export function readConfigFile() {
+  if (!existsSync(CONFIG_PATH)) return null
+  try {
+    return JSON.parse(readFileSync(CONFIG_PATH, 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+export function writeConfigFile(data) {
+  mkdirSync(dirname(CONFIG_PATH), { recursive: true })
+  writeFileSync(CONFIG_PATH, JSON.stringify(data, null, 2), { mode: 0o600 })
+}

package/src/server.mjs

@@ -0,0 +1,560 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { loadConfig, apiGet, apiPost, apiPatch, ApiError } from './api.mjs'
+import { STAGES, PLAYBOOKS } from './stages.mjs'
+
+function errorResult(err) {
+  const text = err instanceof ApiError ? `Error (${err.status}): ${err.message}` : `Error: ${err.message}`
+  return { content: [{ type: 'text', text }], isError: true }
+}
+
+function textResult(data) {
+  return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] }
+}
+
+const PROJECT_ID_DESC = 'ID del proyecto dentro del workspace configurado. Si hay un proyecto default configurado (via "setup" o ORQUESTRA_DEFAULT_PROJECT_ID), este argumento se ignora -- el server queda fijo a ese proyecto y no puede leer/escribir otro.'
+
+const TASK_TYPES = ['feature', 'bug', 'improvement', 'tech', 'docs', 'idea', 'meeting', 'call', 'followup', 'business']
+const TASK_PRIORITIES = ['high', 'medium', 'low']
+const CHANGELOG_SECTIONS = ['Added', 'Changed', 'Deprecated', 'Removed', 'Fixed', 'Security']
+const DOC_TYPES = ['readme', 'usecase', 'diagram', 'env', 'adr', 'runbook', 'api']
+const SERVICE_TYPES = ['backend', 'database', 'auth', 'storage', 'push', 'email', 'payments', 'analytics', 'realtime', 'search', 'maps', 'flags', 'admin', 'cdn', 'queue']
+const PLATFORM_TYPES = ['android', 'ios', 'web', 'desktop-mac', 'desktop-win', 'backend', 'extension', 'other']
+const INFRA_STATUSES = ['operational', 'degraded', 'down']
+const STAGE_IDS = STAGES.map(s => s.id)
+
+const SETUP_GUIDE = {
+  intro: 'Para configurar o sincronizar un proyecto completo: revisa primero con la tool de "check" de cada paso; si ya existe algo que coincide por name/type/title, edítalo con la tool de "update"; si no existe, créalo con la de "create". Sigue el orden -- los pasos 4 en adelante referencian ids de los pasos 1-3 (statusId, categoryId, moduleId, distId).',
+  steps: [
+    { step: 1, section: 'Flujo (estatus)', check: 'list_statuses', createOrUpdate: 'create_status / update_status', matchBy: 'name' },
+    { step: 2, section: 'Categorías', check: 'list_categories', createOrUpdate: 'create_category / update_category', matchBy: 'name' },
+    { step: 3, section: 'Infraestructura', check: 'list_services / list_environments / list_distributions (o get_infra_status para los 3 juntos)', createOrUpdate: 'create_service|environment|distribution / update_*', matchBy: 'name (o type para servicios/distribuciones)' },
+    { step: 4, section: 'Módulos', check: 'list_modules', createOrUpdate: 'create_module / update_module', matchBy: 'name', dependsOn: ['statusId (paso 1)', 'categoryId (paso 2)'] },
+    { step: 5, section: 'Tareas', check: 'list_tasks', createOrUpdate: 'create_task / update_task', matchBy: 'title', dependsOn: ['statusId', 'categoryId', 'moduleId'] },
+    { step: 6, section: 'Ideas', check: 'search', createOrUpdate: 'create_idea (sin update_idea todavía)', matchBy: 'title' },
+    { step: 7, section: 'Notas', check: 'search', createOrUpdate: 'create_note (sin update_note todavía)', matchBy: 'title' },
+    { step: 8, section: 'Changelog', check: 'get_dashboard_summary (recent.changelog) o search', createOrUpdate: 'create_changelog_entry (sin update todavía)', matchBy: 'text' },
+    { step: 9, section: 'Docs', check: 'search', createOrUpdate: 'create_doc (sin update_doc todavía)', matchBy: 'title' },
+  ],
+}
+
+export function createServer() {
+  const config = loadConfig()
+  const server = new McpServer({ name: 'orquestra-mcp', version: '1.0.0' })
+
+  function resolveProjectId(projectId) {
+    if (config.defaultProjectId) return config.defaultProjectId
+    if (!projectId) throw new Error('Falta projectId -- no hay proyecto default configurado, corre "npx orquestra-mcp setup" o pasa projectId explícito.')
+    return projectId
+  }
+
+  function registerRead(name, path, description, extraSchema, buildParams) {
+    server.registerTool(
+      name,
+      { description, inputSchema: { projectId: z.string().optional().describe(PROJECT_ID_DESC), ...extraSchema } },
+      async (args) => {
+        try {
+          const data = await apiGet(config, path, buildParams(args, resolveProjectId(args.projectId)))
+          return textResult(data)
+        } catch (err) {
+          return errorResult(err)
+        }
+      }
+    )
+  }
+
+  function registerCreate(name, path, description, extraSchema) {
+    server.registerTool(
+      name,
+      { description, inputSchema: { projectId: z.string().optional().describe(PROJECT_ID_DESC), ...extraSchema } },
+      async ({ projectId, ...body }) => {
+        try {
+          const data = await apiPost(config, path, { projectId: resolveProjectId(projectId), ...body })
+          return textResult(data)
+        } catch (err) {
+          return errorResult(err)
+        }
+      }
+    )
+  }
+
+  function registerUpdate(name, path, description, extraSchema) {
+    server.registerTool(
+      name,
+      {
+        description,
+        inputSchema: {
+          projectId: z.string().optional().describe(PROJECT_ID_DESC),
+          id: z.string().describe('ID del registro a editar'),
+          ...extraSchema,
+        },
+      },
+      async ({ projectId, id, ...body }) => {
+        try {
+          const data = await apiPatch(config, path, { projectId: resolveProjectId(projectId), id, ...body })
+          return textResult(data)
+        } catch (err) {
+          return errorResult(err)
+        }
+      }
+    )
+  }
+
+  // ═══ LECTURA (existentes) ══════════════════════════════════════════════════
+
+  registerRead(
+    'get_project_context',
+    '/v1/context',
+    'Resumen compacto del estado de un proyecto de Orquestra: fase, plataformas, tareas abiertas/vencidas/bloqueadas, módulos, ideas y changelog reciente.',
+    {},
+    (args, projectId) => ({ projectId })
+  )
+
+  registerRead(
+    'list_tasks',
+    '/v1/tasks',
+    'Lista las tareas de un proyecto de Orquestra, opcionalmente filtradas por estatus.',
+    { statusId: z.string().optional().describe('ID de estatus para filtrar (opcional)') },
+    (args, projectId) => ({ projectId, statusId: args.statusId })
+  )
+
+  registerRead(
+    'search',
+    '/v1/search',
+    'Busca por texto en tareas, notas, ideas y docs de un proyecto de Orquestra.',
+    { q: z.string().describe('Texto a buscar') },
+    (args, projectId) => ({ projectId, q: args.q })
+  )
+
+  // ═══ LECTURA (nivel A -- dashboard, workspace, infra, paridad, playbooks) ═══
+
+  registerRead(
+    'get_dashboard_summary',
+    '/v1/dashboard',
+    'Resumen tipo dashboard de un proyecto: tareas de hoy, vencidas, bloqueadas, salud de módulos y actividad reciente.',
+    {},
+    (args, projectId) => ({ projectId })
+  )
+
+  registerRead(
+    'get_infra_status',
+    '/v1/infra',
+    'Estado de infraestructura de un proyecto: servicios compartidos, entornos y distribuciones, con conteos de operational/degraded/down.',
+    {},
+    (args, projectId) => ({ projectId })
+  )
+
+  registerRead(
+    'get_parity_summary',
+    '/v1/parity',
+    'Desfases de paridad multiplataforma: tareas y módulos cuyo scope avanza en una distribución pero sigue pendiente en otra.',
+    {},
+    (args, projectId) => ({ projectId })
+  )
+
+  server.registerTool(
+    'get_workspace_summary',
+    {
+      description: 'Progreso agregado de todos los proyectos del workspace configurado (no requiere projectId).',
+    },
+    async () => {
+      try {
+        const data = await apiGet(config, '/v1/workspace-summary', {})
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  registerRead(
+    'list_modules',
+    '/v1/modules',
+    'Lista los módulos de un proyecto. Úsala antes de create_module para revisar si ya existe uno con ese nombre.',
+    {},
+    (args, projectId) => ({ projectId })
+  )
+
+  registerRead(
+    'list_statuses',
+    '/v1/statuses',
+    'Lista los estatus (columnas del flujo de tareas) de un proyecto. Úsala antes de create_status para no duplicar.',
+    {},
+    (args, projectId) => ({ projectId })
+  )
+
+  registerRead(
+    'list_categories',
+    '/v1/categories',
+    'Lista las categorías de un proyecto. Úsala antes de create_category para no duplicar.',
+    {},
+    (args, projectId) => ({ projectId })
+  )
+
+  registerRead(
+    'list_services',
+    '/v1/services',
+    'Lista los servicios de infraestructura de un proyecto. Úsala antes de create_service para no duplicar.',
+    {},
+    (args, projectId) => ({ projectId })
+  )
+
+  registerRead(
+    'list_environments',
+    '/v1/environments',
+    'Lista los entornos de un proyecto. Úsala antes de create_environment para no duplicar.',
+    {},
+    (args, projectId) => ({ projectId })
+  )
+
+  registerRead(
+    'list_distributions',
+    '/v1/distributions',
+    'Lista las distribuciones/plataformas de un proyecto. Úsala antes de create_distribution para no duplicar.',
+    {},
+    (args, projectId) => ({ projectId })
+  )
+
+  server.registerTool(
+    'get_setup_guide',
+    {
+      description: 'Guía del orden recomendado para configurar o sincronizar un proyecto completo (flujo → categorías → infra → módulos → tareas → ideas → notas → changelog → docs). No llama a la API -- datos estáticos.',
+    },
+    async () => textResult(SETUP_GUIDE)
+  )
+
+  server.registerTool(
+    'get_stage_playbook',
+    {
+      description: 'Plantilla de módulo + tareas para una etapa del proyecto (pre-proyecto, proyecto, post-proyecto). No llama a la API -- datos estáticos.',
+      inputSchema: { stageId: z.enum(STAGE_IDS).describe('pre (idea/diseño) | build (mvp/alpha/beta) | post (launch en adelante)') },
+    },
+    async ({ stageId }) => {
+      const stage = STAGES.find(s => s.id === stageId)
+      const playbook = PLAYBOOKS[stageId]
+      return textResult({ stage, playbook })
+    }
+  )
+
+  // ═══ ESCRITURA (existentes) ═════════════════════════════════════════════════
+
+  registerCreate(
+    'create_task',
+    '/v1/tasks',
+    'Crea una tarea en un proyecto de Orquestra.',
+    {
+      title: z.string().describe('Título de la tarea'),
+      description: z.string().optional(),
+      type: z.enum(TASK_TYPES).optional().describe('Default: feature'),
+      priority: z.enum(TASK_PRIORITIES).optional().describe('Default: medium'),
+      statusId: z.string().optional().describe('Default: el primer estatus del proyecto'),
+      categoryId: z.string().optional(),
+      moduleId: z.string().optional(),
+      dueDate: z.string().optional().describe('YYYY-MM-DD'),
+      assignedTo: z.string().optional().describe('uid del miembro asignado'),
+      tags: z.array(z.string()).optional(),
+    }
+  )
+
+  registerUpdate(
+    'update_task',
+    '/v1/tasks',
+    'Edita una tarea existente (incluido su scope multiplataforma, para resolver desfases de paridad).',
+    {
+      title: z.string().optional(),
+      description: z.string().optional(),
+      type: z.enum(TASK_TYPES).optional(),
+      priority: z.enum(TASK_PRIORITIES).optional(),
+      statusId: z.string().optional(),
+      categoryId: z.string().optional(),
+      moduleId: z.string().optional(),
+      dueDate: z.string().optional().describe('YYYY-MM-DD'),
+      assignedTo: z.string().optional(),
+      tags: z.array(z.string()).optional(),
+      scope: z.array(z.object({ distId: z.string(), layer: z.string().optional(), done: z.boolean() })).optional()
+        .describe('Alcance por distribución -- usa get_parity_summary para ver el scope actual antes de editarlo'),
+    }
+  )
+
+  registerCreate(
+    'create_idea',
+    '/v1/ideas',
+    'Crea una idea en un proyecto de Orquestra.',
+    {
+      title: z.string().describe('Título de la idea'),
+      description: z.string().optional(),
+      priority: z.enum(TASK_PRIORITIES).optional().describe('Default: medium'),
+      categoryId: z.string().optional(),
+      dueDate: z.string().optional().describe('YYYY-MM-DD'),
+    }
+  )
+
+  registerCreate(
+    'create_changelog_entry',
+    '/v1/changelog',
+    'Crea una entrada de changelog en un proyecto de Orquestra (estilo Keep a Changelog).',
+    {
+      section: z.enum(CHANGELOG_SECTIONS).describe('Sección del changelog'),
+      text: z.string().describe('Descripción de la entrada'),
+      version: z.string().optional(),
+    }
+  )
+
+  registerCreate(
+    'create_note',
+    '/v1/notes',
+    'Crea una nota en un proyecto de Orquestra.',
+    {
+      title: z.string().describe('Título de la nota'),
+      body: z.string().optional(),
+      pinned: z.boolean().optional(),
+    }
+  )
+
+  registerCreate(
+    'create_doc',
+    '/v1/docs',
+    'Crea un documento en un proyecto de Orquestra.',
+    {
+      type: z.enum(DOC_TYPES).describe('Tipo de documento'),
+      title: z.string().describe('Título del documento'),
+      content: z.string().optional(),
+    }
+  )
+
+  // ═══ ESCRITURA (nivel B -- módulos, flujo, categorías, infra) ═══════════════
+
+  const SCOPE_SCHEMA = z.array(z.object({ distId: z.string(), layer: z.string().optional(), done: z.boolean().optional() })).optional()
+
+  registerCreate('create_module', '/v1/modules', 'Crea un módulo en un proyecto de Orquestra.', {
+    name: z.string().describe('Nombre del módulo'),
+    description: z.string().optional(),
+    statusId: z.string().optional(),
+    categoryId: z.string().optional(),
+    scope: SCOPE_SCHEMA.describe('Alcance por distribución, ej: [{distId, layer, done}]'),
+    tags: z.array(z.string()).optional(),
+    dueDate: z.string().optional().describe('YYYY-MM-DD'),
+  })
+  registerUpdate('update_module', '/v1/modules', 'Edita un módulo existente (incluido su scope multiplataforma).', {
+    name: z.string().optional(),
+    description: z.string().optional(),
+    statusId: z.string().optional(),
+    categoryId: z.string().optional(),
+    scope: SCOPE_SCHEMA,
+    tags: z.array(z.string()).optional(),
+    dueDate: z.string().optional().describe('YYYY-MM-DD'),
+  })
+
+  registerCreate('create_status', '/v1/statuses', 'Crea un estatus (columna del flujo de tareas) en un proyecto.', {
+    name: z.string().describe('Nombre del estatus'),
+    color: z.string().describe('Color hex, ej: #5E6AD2'),
+    order: z.number().optional().describe('Orden en el flujo, default 0'),
+    isInitial: z.boolean().optional().describe('Si es el estatus por default de tareas nuevas'),
+    isFinal: z.boolean().optional().describe('Si representa "terminado"'),
+    isCancel: z.boolean().optional(),
+    isArchive: z.boolean().optional(),
+    nextIds: z.array(z.string()).optional().describe('IDs de estatus a los que se puede transicionar desde este'),
+  })
+  registerUpdate('update_status', '/v1/statuses', 'Edita un estatus existente (nombre, color, orden, transiciones).', {
+    name: z.string().optional(),
+    color: z.string().optional(),
+    order: z.number().optional(),
+    isInitial: z.boolean().optional(),
+    isFinal: z.boolean().optional(),
+    isCancel: z.boolean().optional(),
+    isArchive: z.boolean().optional(),
+    nextIds: z.array(z.string()).optional(),
+  })
+
+  registerCreate('create_category', '/v1/categories', 'Crea una categoría (agrupación/audiencia) en un proyecto.', {
+    name: z.string().describe('Nombre de la categoría'),
+    color: z.string().optional().describe('Color hex'),
+  })
+  registerUpdate('update_category', '/v1/categories', 'Edita una categoría existente.', {
+    name: z.string().optional(),
+    color: z.string().optional(),
+  })
+
+  // Campos específicos por tipo de servicio -- unión deduplicada de las
+  // ~15 categorías (ver SERVICE_SPECIFIC_FIELDS en
+  // orquestra-web/src/pages/InfraPanel.jsx, mapa hoy duplicado a mano en
+  // 3 lados: web, entities.mjs de la API, y acá -- si cambia uno, cambiar
+  // los 3). Solo aplican los que correspondan a `type`; el resto se ignora
+  // en el doc. 'authType', no 'type' -- ese nombre ya lo usa el propio
+  // catálogo del servicio (bug real encontrado y corregido el 8 ago antes
+  // de exponerlo aquí).
+  const SERVICE_SPECIFIC_SCHEMA = {
+    technology:    z.string().optional().describe('Stack -- backend'),
+    hosting:       z.string().optional().describe('Hosting -- backend'),
+    apiUrl:        z.string().optional().describe('API URL -- backend'),
+    region:        z.string().optional().describe('Región, ej. us-east-1 -- backend/database'),
+    engine:        z.string().optional().describe('Motor, ej. PostgreSQL 15 -- database'),
+    provider:      z.string().optional().describe('Proveedor -- database/storage/push/email/payments/analytics/realtime/search/maps/flags/cdn/queue'),
+    backups:       z.string().optional().describe('Frecuencia de backups -- database'),
+    bucket:        z.string().optional().describe('Bucket -- storage'),
+    cdnUrl:        z.string().optional().describe('CDN URL -- storage'),
+    stores:        z.string().optional().describe('Qué guarda -- storage'),
+    platforms:     z.string().optional().describe('Plataformas cubiertas -- push'),
+    authType:      z.string().optional().describe('Tipo de auth, ej. JWT/Firebase Auth -- auth'),
+    methods:       z.string().optional().describe('Social login -- auth'),
+    domain:        z.string().optional().describe('Dominio -- email/cdn'),
+    transactional: z.string().optional().describe('Transaccional -- email'),
+    currencies:    z.string().optional().describe('Monedas -- payments'),
+    mode:          z.string().optional().describe('Modo live/test -- payments'),
+    events:        z.string().optional().describe('Eventos rastreados -- analytics'),
+    protocol:      z.string().optional().describe('Protocolo -- realtime'),
+    index:         z.string().optional().describe('Índice -- search'),
+    usage:         z.string().optional().describe('Uso, ej. geocoding/rutas -- maps'),
+    flags:         z.string().optional().describe('Flags activos -- flags'),
+    stack:         z.string().optional().describe('Stack del panel -- admin'),
+    url:           z.string().optional().describe('URL -- admin'),
+    queues:        z.string().optional().describe('Colas activas -- queue'),
+    details:       z.string().optional().describe('Detalles libres -- tipos sin campos propios'),
+  }
+
+  registerCreate('create_service', '/v1/services', 'Crea un servicio compartido de infraestructura (backend, base de datos, auth, etc.) en un proyecto. Además de status/notes, acepta los campos específicos de cada tipo (ej. apiUrl/region para backend, engine/provider para database) -- manda solo los que apliquen a `type`.', {
+    type: z.enum(SERVICE_TYPES).describe('Tipo de servicio'),
+    name: z.string().describe('Nombre del servicio'),
+    status: z.enum(INFRA_STATUSES).optional().describe('Default: operational'),
+    notes: z.string().optional(),
+    ...SERVICE_SPECIFIC_SCHEMA,
+  })
+  registerUpdate('update_service', '/v1/services', 'Edita un servicio de infraestructura existente (status, campos específicos por tipo, incidente...).', {
+    type: z.enum(SERVICE_TYPES).optional(),
+    name: z.string().optional(),
+    status: z.enum(INFRA_STATUSES).optional(),
+    notes: z.string().optional(),
+    lastIncident: z.string().optional(),
+    ...SERVICE_SPECIFIC_SCHEMA,
+  })
+
+  registerCreate('create_environment', '/v1/environments', 'Crea un entorno (producción, staging, desarrollo) en un proyecto.', {
+    name: z.string().describe('Nombre del entorno'),
+    url: z.string().optional(),
+    version: z.string().optional(),
+    branch: z.string().optional(),
+    status: z.enum(INFRA_STATUSES).optional().describe('Default: operational'),
+    notes: z.string().optional(),
+    lastDeploy: z.string().optional().describe('Texto libre, ej. "hace 2 días" -- no es una fecha estructurada'),
+  })
+  registerUpdate('update_environment', '/v1/environments', 'Edita un entorno existente (útil para actualizar su status/version tras un deploy).', {
+    name: z.string().optional(),
+    url: z.string().optional(),
+    version: z.string().optional(),
+    branch: z.string().optional(),
+    status: z.enum(INFRA_STATUSES).optional(),
+    notes: z.string().optional(),
+    lastDeploy: z.string().optional(),
+  })
+
+  registerCreate('create_distribution', '/v1/distributions', 'Crea una distribución/plataforma (iOS, Android, Web, etc.) en un proyecto.', {
+    type: z.enum(PLATFORM_TYPES).describe('Tipo de plataforma'),
+    label: z.string().describe('Nombre a mostrar por default'),
+    name: z.string().optional().describe('Nombre editable -- si no se manda, la UI usa label'),
+    categoryId: z.string().optional(),
+    status: z.enum(INFRA_STATUSES).optional().describe('Default: operational'),
+    phase: z.string().optional().describe('idea | design | alpha | beta | live | deprecated'),
+    identifier: z.string().optional().describe('Legado -- preferir bundleId (no-web) o domain (web)'),
+    bundleId: z.string().optional().describe('Bundle ID / package name -- plataformas no-web'),
+    domain: z.string().optional().describe('Dominio -- plataforma web'),
+    hosting: z.string().optional().describe('Hosting -- web/backend'),
+    deployMode: z.enum(['auto', 'manual']).optional().describe('Modo de deploy -- web'),
+    hasPush: z.boolean().optional().describe('Tiene push notifications -- apps (ios/android)'),
+    storeUrl: z.string().optional(),
+    stack: z.array(z.string()).optional(),
+    version: z.string().optional().describe('Versión en store'),
+    reviewVersion: z.string().optional().describe('Build en revisión -- apps'),
+  })
+  registerUpdate('update_distribution', '/v1/distributions', 'Edita una distribución existente.', {
+    label: z.string().optional(),
+    name: z.string().optional(),
+    categoryId: z.string().optional(),
+    status: z.enum(INFRA_STATUSES).optional(),
+    phase: z.string().optional(),
+    identifier: z.string().optional(),
+    bundleId: z.string().optional(),
+    domain: z.string().optional(),
+    hosting: z.string().optional(),
+    deployMode: z.enum(['auto', 'manual']).optional(),
+    hasPush: z.boolean().optional(),
+    storeUrl: z.string().optional(),
+    stack: z.array(z.string()).optional(),
+    version: z.string().optional(),
+    reviewVersion: z.string().optional(),
+  })
+
+  // ═══ COMPUESTAS (nivel C) ═══════════════════════════════════════════════════
+
+  server.registerTool(
+    'init_project',
+    {
+      description: 'Crea un proyecto nuevo dentro del workspace configurado (categorías, distribuciones y los 6 estatus del flujo ya conectados).',
+      inputSchema: {
+        name: z.string().describe('Nombre del proyecto'),
+        description: z.string().optional(),
+        phase: z.string().optional().describe('idea | mvp | v1 | v2 | beta | produccion (default: idea)'),
+        projectType: z.enum(['code', 'content', 'hybrid']).optional().describe('Default: hybrid'),
+        url: z.string().optional(),
+        distributions: z.array(z.enum(PLATFORM_TYPES)).optional().describe('Plataformas a crear, ej: ["web","ios"]'),
+        categories: z.array(z.string()).optional().describe('Nombres de categorías a crear (default: ["General"])'),
+      },
+    },
+    async (body) => {
+      try {
+        const data = await apiPost(config, '/v1/projects', body)
+        return textResult(data)
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  server.registerTool(
+    'apply_stage_playbook',
+    {
+      description: 'Crea el módulo y las tareas de la plantilla de una etapa (pre-proyecto, proyecto, post-proyecto) en un proyecto real.',
+      inputSchema: {
+        projectId: z.string().optional().describe(PROJECT_ID_DESC),
+        stageId: z.enum(STAGE_IDS).describe('pre | build | post -- ver get_stage_playbook para el contenido'),
+        moduleName: z.string().optional().describe('Nombre del módulo -- default: el de la plantilla'),
+        includeDates: z.boolean().optional().describe('Si asigna dueDate a cada tarea usando los offsetDays de la plantilla (default: false)'),
+      },
+    },
+    async ({ projectId, stageId, moduleName, includeDates }) => {
+      try {
+        const pid = resolveProjectId(projectId)
+        const playbook = PLAYBOOKS[stageId]
+        const moduleData = await apiPost(config, '/v1/modules', {
+          projectId: pid,
+          name: moduleName || playbook.moduleName,
+          description: playbook.moduleDescription,
+          tags: playbook.moduleTags,
+        })
+
+        const taskIds = []
+        for (const t of playbook.tasks) {
+          const dueDate = includeDates
+            ? new Date(Date.now() + t.offsetDays * 86400000).toISOString().slice(0, 10)
+            : undefined
+          const created = await apiPost(config, '/v1/tasks', {
+            projectId: pid,
+            title: t.title,
+            description: t.description,
+            type: t.type,
+            priority: t.priority,
+            tags: t.tags,
+            moduleId: moduleData.id,
+            dueDate,
+          })
+          taskIds.push(created.id)
+        }
+
+        return textResult({ module: moduleData, tasksCreated: taskIds.length, taskIds })
+      } catch (err) {
+        return errorResult(err)
+      }
+    }
+  )
+
+  return server
+}

package/src/setup.mjs

@@ -0,0 +1,104 @@
+import { createServer } from 'http'
+import { randomBytes } from 'crypto'
+import { exec } from 'child_process'
+import { createInterface } from 'readline'
+import { writeConfigFile, CONFIG_PATH } from './configFile.mjs'
+
+const DEFAULT_API_BASE = 'https://if9c2vlf35.execute-api.us-east-1.amazonaws.com'
+const DEFAULT_WEB_URL = 'https://app.orquestra.me'
+const CALLBACK_TIMEOUT_MS = 5 * 60 * 1000
+
+function openBrowser(url) {
+  const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open'
+  exec(`${cmd} "${url}"`, () => {})
+}
+
+function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stdout })
+  return new Promise(resolve => rl.question(question, answer => { rl.close(); resolve(answer) }))
+}
+
+export async function runSetup() {
+  const apiBase = process.env.ORQUESTRA_API_BASE || DEFAULT_API_BASE
+  const webUrl = process.env.ORQUESTRA_WEB_URL || DEFAULT_WEB_URL
+  const state = randomBytes(16).toString('hex')
+
+  // Levantamos el server primero para conocer el puerto antes de armar la URL.
+  const server = createServer()
+  await new Promise(resolve => server.listen(0, resolve))
+  const port = server.address().port
+  server.close()
+
+  const idTokenPromise = new Promise((resolve, reject) => {
+    const httpServer = createServer((req, res) => {
+      res.setHeader('Access-Control-Allow-Origin', '*')
+      res.setHeader('Access-Control-Allow-Methods', 'POST, OPTIONS')
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type')
+
+      if (req.method === 'OPTIONS') { res.writeHead(204); res.end(); return }
+      if (req.method !== 'POST' || req.url !== '/callback') { res.writeHead(404); res.end(); return }
+
+      let body = ''
+      req.on('data', chunk => { body += chunk })
+      req.on('end', () => {
+        try {
+          const { state: gotState, idToken } = JSON.parse(body)
+          if (gotState !== state || !idToken) throw new Error('state/idToken inválido')
+          res.writeHead(200, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify({ ok: true }))
+          clearTimeout(timeout)
+          httpServer.close()
+          resolve(idToken)
+        } catch (e) {
+          res.writeHead(400, { 'Content-Type': 'application/json' })
+          res.end(JSON.stringify({ ok: false, error: e.message }))
+        }
+      })
+    })
+
+    const timeout = setTimeout(() => {
+      httpServer.close()
+      reject(new Error('Se agotó el tiempo esperando el login (5 min). Corre "npx orquestra-mcp setup" de nuevo.'))
+    }, CALLBACK_TIMEOUT_MS)
+
+    httpServer.listen(port)
+    httpServer.on('error', reject)
+  })
+
+  const authUrl = `${webUrl}/cli-auth?state=${state}&port=${port}`
+  console.log('Abriendo el navegador para conectar tu cuenta de Orquestra...')
+  console.log(`Si no se abre solo, entra a: ${authUrl}`)
+  openBrowser(authUrl)
+
+  const idToken = await idTokenPromise
+  console.log('Login recibido, configurando...')
+
+  const res = await fetch(`${apiBase}/v1/bootstrap`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${idToken}` },
+  })
+  const body = await res.json()
+  if (!res.ok) throw new Error(body?.error || `HTTP ${res.status}`)
+
+  const { workspaceId, token, created, projects } = body
+  let defaultProjectId
+
+  if (created) {
+    defaultProjectId = body.projectId
+    console.log(`Se creó un workspace y un proyecto default para ti ("${projects[0].name}") -- puedes renombrarlos cuando quieras desde orquestra-web.`)
+  } else if (projects.length === 1) {
+    defaultProjectId = projects[0].id
+    console.log(`Usando tu proyecto "${projects[0].name}" como default.`)
+  } else {
+    console.log('\nElige el proyecto que este MCP va a usar por default:')
+    projects.forEach((p, i) => console.log(`  ${i + 1}. ${p.name}`))
+    const answer = await prompt('Número: ')
+    const idx = parseInt(answer, 10) - 1
+    if (idx < 0 || idx >= projects.length) throw new Error('Selección inválida')
+    defaultProjectId = projects[idx].id
+  }
+
+  writeConfigFile({ apiBase, apiToken: token, workspaceId, defaultProjectId })
+  console.log(`\nListo. Configuración guardada en ${CONFIG_PATH}.`)
+  console.log('Ya puedes correr "npx orquestra-mcp" (o configurarlo en tu cliente MCP) sin pasar variables de entorno.')
+}

package/src/stages.mjs

@@ -0,0 +1,84 @@
+// Puerto exacto de orquestra-web/src/lib/stages.js (STAGES + PLAYBOOKS) --
+// constantes estaticas, sin acceso a red ni Firestore. get_stage_playbook y
+// apply_stage_playbook las leen directo desde aca.
+export const STAGES = [
+  {
+    id: 'pre',
+    label: 'Pre-proyecto',
+    color: '#F0A500',
+    phases: ['idea', 'diseño'],
+    focus: 'Valida el problema y define el alcance antes de escribir código.',
+  },
+  {
+    id: 'build',
+    label: 'Proyecto',
+    color: '#5E6AD2',
+    phases: ['mvp', 'alpha', 'beta'],
+    focus: 'Construye por módulos hasta llegar a una beta estable y medible.',
+  },
+  {
+    id: 'post',
+    label: 'Post-proyecto',
+    color: '#3B8C65',
+    phases: ['launch', 'v1', 'v2', 'v3', 'mantenimiento', 'deprecado'],
+    focus: 'Lanzamiento, contenido y adquisición — lleva el producto a la gente.',
+  },
+]
+
+export function getStageForPhase(phase) {
+  return STAGES.find(s => s.phases.includes(phase)) || STAGES[0]
+}
+
+export const PLAYBOOKS = {
+  pre: {
+    moduleName: 'Validación y definición',
+    moduleDescription: 'Valida el problema, el público y el alcance antes de construir. Completar este módulo evita construir algo que nadie necesita.',
+    moduleTags: ['playbook', 'pre-proyecto'],
+    intro: 'Antes de escribir código: valida que el problema existe y define exactamente qué vas a construir.',
+    tasks: [
+      { title: 'Definir el problema y la propuesta de valor', description: 'En una frase: ¿qué problema resuelves y para quién? Si no cabe en una frase, aún no está claro. Escríbelo en una nota del proyecto.', type: 'business', priority: 'high', tags: ['validación'], offsetDays: 1 },
+      { title: 'Identificar público objetivo y casos de uso', description: 'Describe 2-3 perfiles de usuario concretos y el caso de uso principal de cada uno. ¿Quién lo usa, cuándo y por qué?', type: 'business', priority: 'high', tags: ['validación'], offsetDays: 3 },
+      { title: 'Analizar 3 competidores o alternativas', description: 'Cómo resuelve la gente este problema hoy (aunque sea con Excel o WhatsApp). Qué hacen bien, qué les falta, y cuál es tu diferencia.', type: 'business', priority: 'medium', tags: ['validación'], offsetDays: 5 },
+      { title: 'Validar la idea con 5 usuarios potenciales', description: 'Conversaciones reales, no encuestas. Pregunta por su problema actual, no por tu solución. Registra los hallazgos en Notas.', type: 'followup', priority: 'high', tags: ['validación'], offsetDays: 10 },
+      { title: 'Definir alcance del MVP — qué entra y qué NO', description: 'Lista las features del MVP y, más importante, la lista explícita de lo que se queda fuera de la v1. Documéntalo en Docs.', type: 'docs', priority: 'high', tags: ['alcance'], offsetDays: 12 },
+      { title: 'Elegir stack y plataformas iniciales', description: 'Decide con qué empiezas (¿solo web?, ¿iOS primero?) y regístralo en Ajustes → Infraestructura como distribuciones con su stack.', type: 'tech', priority: 'medium', tags: ['stack'], offsetDays: 14 },
+      { title: 'Definir métricas de éxito del MVP', description: '¿Cómo sabrás que funcionó? Ej: "10 usuarios lo usan 3 veces por semana". Sin esto, el MVP nunca "termina".', type: 'business', priority: 'medium', tags: ['métricas'], offsetDays: 14 },
+    ],
+  },
+  build: {
+    moduleName: 'Camino a beta',
+    moduleDescription: 'La base técnica y de proceso que necesitas para llegar a una beta estable con usuarios reales dando feedback.',
+    moduleTags: ['playbook', 'proyecto'],
+    intro: 'Construye con dirección: infraestructura medible, feedback desde el día uno y una beta que puedas poner en manos de usuarios reales.',
+    tasks: [
+      { title: 'Configurar entornos e infraestructura base', description: 'Backend, base de datos, auth y storage funcionando. Regístralos en la sección Infra con su proveedor y estado.', type: 'tech', priority: 'high', tags: ['infra'], offsetDays: 3 },
+      { title: 'Instrumentar analytics y crash reporting', description: 'Desde el primer build: eventos clave (registro, acción principal, retorno) y reporte de crashes. Sin datos no hay decisiones.', type: 'tech', priority: 'high', tags: ['analytics'], offsetDays: 7 },
+      { title: 'Implementar autenticación y onboarding', description: 'El flujo de entrada define la primera impresión. Registro simple + un onboarding que lleve al usuario a su primer momento de valor.', type: 'feature', priority: 'high', tags: ['onboarding'], offsetDays: 14 },
+      { title: 'Definir flujo de feedback de beta testers', description: '¿Cómo te van a reportar bugs y sugerencias? (formulario, grupo de WhatsApp, botón in-app). Decide dónde aterriza: aquí en Ideas.', type: 'improvement', priority: 'medium', tags: ['beta', 'feedback'], offsetDays: 18 },
+      { title: 'Preparar build de beta (TestFlight / track interno / staging)', description: 'Un canal de distribución de beta por plataforma. Registra la versión en review en el panel de Infra.', type: 'tech', priority: 'high', tags: ['beta'], offsetDays: 21 },
+      { title: 'Reclutar 10-20 beta testers', description: 'Idealmente del público objetivo que validaste en pre-proyecto. Amigos que no son el público te dirán que "está padre" y nada más.', type: 'business', priority: 'medium', tags: ['beta'], offsetDays: 25 },
+      { title: 'Documentar setup del proyecto (README)', description: 'Cómo levantar el proyecto desde cero: dependencias, variables de entorno, comandos. Guárdalo en Docs. Tu yo del futuro lo agradece.', type: 'docs', priority: 'low', tags: ['docs'], offsetDays: 28 },
+      { title: 'Checklist de estabilidad pre-lanzamiento', description: 'Crashes < 1%, flujos principales sin bugs conocidos, tiempos de carga aceptables, datos de prueba limpios. Si pasa, estás listo para launch.', type: 'tech', priority: 'high', tags: ['calidad'], offsetDays: 35 },
+    ],
+  },
+  post: {
+    moduleName: 'Lanzamiento y crecimiento',
+    moduleDescription: 'El plan de marketing paso a paso después de la beta: posicionamiento, canales de lanzamiento, contenido, y el loop de métricas y feedback que convierte un lanzamiento en crecimiento.',
+    moduleTags: ['playbook', 'post-proyecto', 'marketing'],
+    intro: 'Terminaste la beta — ahora el trabajo es que la gente lo use. Este playbook te lleva del "¿y ahora qué?" a un lanzamiento con canales, contenido y métricas.',
+    tasks: [
+      { title: 'Redactar el pitch: propuesta de valor en una frase', description: 'La frase que usarás en la tienda, la landing y redes. Fórmula: "[Producto] ayuda a [público] a [resultado] sin [dolor]". Itérala hasta que alguien ajeno la entienda a la primera.', type: 'business', priority: 'high', tags: ['marketing', 'posicionamiento'], offsetDays: 2 },
+      { title: 'Preparar assets de tienda (ASO): capturas, descripción, keywords', description: '5-8 capturas que cuenten una historia (no pantallas sueltas), descripción con el pitch arriba, y keywords que tu público realmente busca.', type: 'business', priority: 'high', tags: ['marketing', 'aso'], offsetDays: 5 },
+      { title: 'Publicar landing con captura de correos', description: 'Una página: pitch, 3 beneficios, capturas y un CTA (descargar o dejar correo). Los correos capturados son tu canal propio para siempre.', type: 'feature', priority: 'high', tags: ['marketing', 'landing'], offsetDays: 7 },
+      { title: 'Configurar analytics de adquisición', description: 'Fuentes de tráfico, conversión de visita→registro→activación. Necesitas saber DE DÓNDE llegan los usuarios que sí se quedan.', type: 'tech', priority: 'medium', tags: ['analytics', 'adquisición'], offsetDays: 8 },
+      { title: 'Plan de contenido de lanzamiento (2 semanas)', description: 'Programa las publicaciones en la sección Contenido: teaser, anuncio, demo del caso de uso principal, historia de por qué lo construiste, testimonios de beta testers.', type: 'business', priority: 'high', tags: ['marketing', 'contenido'], offsetDays: 10 },
+      { title: 'Lanzar en canales: Product Hunt, comunidades y redes', description: 'Elige 3 canales donde vive tu público (PH, subreddits, grupos de FB/Discord, foros del nicho). Un post honesto de creador funciona mejor que uno de venta.', type: 'business', priority: 'high', tags: ['marketing', 'lanzamiento'], offsetDays: 14 },
+      { title: 'Contactar 10 personas con audiencia en el nicho', description: 'Creators, newsletters, podcasts o prensa pequeña del tema. Mensaje corto y personalizado + acceso gratis. Con que respondan 2, ganaste.', type: 'followup', priority: 'medium', tags: ['marketing', 'outreach'], offsetDays: 16 },
+      { title: 'Activar loop de feedback de usuarios reales', description: 'Un canal permanente: encuesta in-app, correo de bienvenida que pregunta "¿qué te trajo aquí?", o botón de sugerencias. Todo aterriza en Ideas.', type: 'improvement', priority: 'medium', tags: ['feedback'], offsetDays: 18 },
+      { title: 'Definir y medir activación y retención (D1 / D7 / D30)', description: 'Activación: % que llega al momento de valor. Retención: % que regresa al día 1, 7 y 30. Estos números te dicen si tienes producto o solo descargas.', type: 'business', priority: 'medium', tags: ['métricas'], offsetDays: 21 },
+      { title: 'Ritmo de contenido post-lanzamiento (3 publicaciones/semana)', description: 'El lanzamiento es un día; el crecimiento es constancia. Deja programadas en Contenido las siguientes 2 semanas: tips de uso, casos, mejoras del changelog.', type: 'business', priority: 'medium', tags: ['marketing', 'contenido'], offsetDays: 24 },
+      { title: 'Publicar release notes / changelog público v1', description: 'Convierte tu Changelog en comunicación: qué hay de nuevo, en lenguaje de usuario. Cada release es una excusa para volver a aparecer.', type: 'docs', priority: 'low', tags: ['changelog'], offsetDays: 26 },
+      { title: 'Revisión semanal de métricas y próximos pasos', description: 'Reunión recurrente (aunque seas solo tú): adquisición, activación, retención, top feedback. Decide UNA mejora prioritaria por semana.', type: 'meeting', priority: 'medium', tags: ['métricas', 'ritmo'], offsetDays: 28 },
+    ],
+  },
+}