## Asset Header

- **Asset ID:** SOP-EL-SX-SysOps-v01
- **Version:** v01
- **Status:** Draft
- **Owner:** Victor Heredia
- **IntellBank:** IB-EL-EmpowerLabs
- **Tipo:** SOP — Standard Operating Procedure
- **Propósito:** BrainOS as a Service — SOP de Operaciones
- **Última actualización:** 2026-04-11

---

# BrainOS as a Service — SOP de Operaciones
## SHA-SOP-SysOps-v01

---


---

## Propósito de este documento

EmpowerLabs opera el BrainOS de cada cliente de Tu Sherpa IA como un servicio gestionado (Track A). El cliente nunca toca la infraestructura — solo recibe una URL y una clave para conectar desde Claude Desktop.

Este SOP documenta todo lo que el equipo de sistemas necesita saber para:

1. **Provisionar** un nuevo cliente (setup completo en 15-20 min)
2. **Operar** la infraestructura de forma continua (monitoreo, costos, mantenimiento)
3. **Gestionar incidentes** (troubleshooting, errores conocidos, escalación)
4. **Offboardear** a un cliente cuando termina el contrato

---

## Sección 1 — Arquitectura del Servicio

### ¿Qué es el BrainOS?

El BrainOS es la memoria persistente de Tu Sherpa IA. Permite que el asistente IA de un cliente recuerde decisiones, aprendizajes, proyectos y compromisos a lo largo del tiempo — incluso entre sesiones distintas.

Tecnológicamente es: una base de datos vectorial en la nube + un servidor MCP (Model Context Protocol) + un modelo de embeddings.

![[Pasted image 20260323104634.png]]
### Stack técnico

| Capa | Tecnología | Función | Quién lo opera |
|------|-----------|---------|---------------|
| **Base de datos** | Supabase (PostgreSQL + pgvector) | Almacena los "thoughts" con embeddings semánticos | EmpowerLabs |
| **Servidor MCP** | Supabase Edge Functions (Deno) | Protocolo que conecta Claude con la base de datos | EmpowerLabs |
| **Embeddings** | OpenRouter → `text-embedding-3-small` | Convierte texto en vectores semánticos para búsqueda | EmpowerLabs (API key compartida) |
| **Cliente IA** | Claude Desktop | La interfaz que usa el cliente | El cliente |
| **Connector** | MCP Connector en Claude Desktop | Enlaza Claude con el servidor MCP | El cliente (configuración una sola vez) |

### Modelo de datos

```
Tabla: thoughts
├── id          UUID (primary key, autogenerado)
├── content     TEXT (el thought capturado — texto libre)
├── embedding   VECTOR(1536) (generado por OpenRouter al insertar)
├── metadata    JSONB (etiquetas, fuente, proyecto, etc.)
├── created_at  TIMESTAMPTZ (timestamp de creación)
└── updated_at  TIMESTAMPTZ (timestamp de última modificación)
```

### Arquitectura por cliente

Cada cliente tiene su propio proyecto Supabase independiente. **No hay base de datos compartida.** Esta es una decisión de diseño intencional:

- **Seguridad:** los datos de un cliente nunca están en el mismo proyecto que otro
- **Soberanía:** se puede entregar el proyecto completo al cliente si lo solicita
- **Independencia de fallos:** un problema en el proyecto de un cliente no afecta a los demás

```
EmpowerLabs (cuenta Supabase central)
├── BrainOS-cliente-A   ← Proyecto independiente, cliente A
├── BrainOS-cliente-B   ← Proyecto independiente, cliente B
├── BrainOS-cliente-C   ← Proyecto independiente, cliente C
└── BrainOS-victor      ← Instancia de referencia interna
```

### Flujo de una operación (ejemplo: capturar un thought)

```
Cliente escribe: "Recuerda que decidí lanzar el producto en mayo"
         ↓
Claude detecta la instrucción y llama al tool capture_thought
         ↓
Servidor MCP recibe el texto + autenticación (key)
         ↓
Servidor llama a OpenRouter para generar el embedding (vector 1536 dims)
         ↓
Embedding + texto se guardan en Supabase tabla thoughts
         ↓
Claude confirma al cliente: "Guardado en tu BrainOS ✅"
```

---

## Sección 2 — Prerequisitos del Equipo

Antes de operar el servicio, el miembro del equipo de sistemas necesita:

### Cuentas y accesos

| Recurso | Acceso necesario | Dónde obtenerlo |
|---------|-----------------|----------------|
| **Supabase** | Miembro de la organización EmpowerLabs | Pedirle a Victor acceso a la org |
| **OpenRouter** | API Key de la cuenta EmpowerLabs | Credential Tracker — EmpowerLabs Master |
| **Supabase CLI** | Instalado en la computadora de trabajo | Ver Paso de instalación abajo |
| **Credential Tracker** | Acceso al tracker de credenciales de clientes | Victor lo provee al onboardear al equipo |

### Instalar Supabase CLI (una sola vez)

**Mac con Homebrew:**
```bash
brew install supabase/tap/supabase
supabase --version   # verificar instalación
```

**Mac sin Homebrew:**
```bash
npm install -g supabase
```

**Windows (Scoop):**
```powershell
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
Invoke-RestMethod -Uri https://get.scoop.sh | Invoke-Expression
scoop bucket add supabase https://github.com/supabase/scoop-bucket.git
scoop install supabase
```

### Autenticarse con Supabase (una sola vez)

```bash
supabase login
# Se abre el browser — autenticarse con la cuenta de la organización EmpowerLabs
```

---

## Sección 3 — Provisioning de Nuevo Cliente

Tiempo estimado: **15-20 minutos**. Ejecutar en orden.

### Checklist de provisioning

Antes de empezar, verificar que tienes:
- [ ] Nombre del cliente (para nombrar el proyecto)
- [ ] Sesión activa en Supabase CLI (`supabase login`)
- [ ] OpenRouter API Key (del Credential Tracker central)
- [ ] Credential Tracker del cliente creado (o espacio listo en el tracker central)

---

### Paso 1 — Crear proyecto Supabase

1. Ir a [supabase.com/dashboard](https://supabase.com/dashboard) → logueado con la cuenta EmpowerLabs
2. **New Project** → seleccionar la organización EmpowerLabs
3. Configurar:
   - **Nombre del proyecto:** `BrainOS-[nombre-cliente]`
     - Ejemplos: `BrainOS-carlos`, `BrainOS-ana-martinez`, `BrainOS-acme`
     - Usar solo minúsculas, sin espacios, guiones permitidos
   - **Database Password:** usar generador del mismo Supabase → **guardar inmediatamente** en el Credential Tracker del cliente
   - **Región:** elegir la más cercana a la ubicación geográfica del cliente
     - México/LATAM: `South America (São Paulo)` o `US East (N. Virginia)`
     - España: `Europe (Frankfurt)`
4. Click **Create new project** → esperar ~2 minutos para que inicialice
5. Una vez cargado el dashboard, guardar en el Credential Tracker:

| Campo | Dónde encontrarlo | Ejemplo |
|-------|------------------|---------|
| **Project URL** | Settings → API → Project URL | `https://abcdef123.supabase.co` |
| **Project Ref** | La URL del browser: `/project/ESTE_STRING` | `abcdef123` |
| **Service Role Key** | Settings → API Keys → `service_role` secret | `eyJ...` (token largo) |
| **DB Password** | El que configuraste en el paso anterior | `Xk9#mP2...` |

---

### Paso 2 — Configurar la base de datos

1. En el dashboard del proyecto nuevo → **SQL Editor** (panel izquierdo)
2. **IMPORTANTE:** Antes de pegar el SQL, copiarlo a un editor de texto externo (VS Code, TextEdit, Notepad) y luego copiarlo desde ahí. El editor del browser a veces corrompe caracteres especiales como `$$` o comillas simples.
3. Crear **New query** y pegar el siguiente SQL completo:

```sql
-- 1. Activar extensión vectorial
create extension if not exists vector;

-- 2. Crear tabla principal
create table thoughts (
  id uuid default gen_random_uuid() primary key,
  content text not null,
  embedding vector(1536),
  metadata jsonb default '{}'::jsonb,
  created_at timestamptz default now(),
  updated_at timestamptz default now()
);

-- 3. Índices de performance
create index on thoughts using hnsw (embedding vector_cosine_ops);
create index on thoughts using gin (metadata);
create index on thoughts (created_at desc);

-- 4. Trigger de actualización automática
create or replace function update_updated_at()
returns trigger as $$
begin
  new.updated_at = now();
  return new;
end;
$$ language plpgsql;

create trigger thoughts_updated_at
  before update on thoughts
  for each row
  execute function update_updated_at();

-- 5. Función de búsqueda semántica
create or replace function match_thoughts(
  query_embedding vector(1536),
  match_threshold float default 0.7,
  match_count int default 10,
  filter jsonb default '{}'::jsonb
)
returns table (
  id uuid,
  content text,
  metadata jsonb,
  similarity float,
  created_at timestamptz
)
language plpgsql
as $$
begin
  return query
  select
    t.id,
    t.content,
    t.metadata,
    1 - (t.embedding <=> query_embedding) as similarity,
    t.created_at
  from thoughts t
  where 1 - (t.embedding <=> query_embedding) > match_threshold
  and (filter = '{}'::jsonb or t.metadata @> filter)
  order by t.embedding <=> query_embedding
  limit match_count;
end;
$$;

-- 6. Seguridad: habilitar RLS
alter table thoughts enable row level security;

create policy "Service role full access"
  on thoughts
  for all
  using (auth.role() = 'service_role');

-- 7. Permisos del rol de servicio
grant select, insert, update, delete on table public.thoughts to service_role;
```

4. Click **Run** → verificar que no hay errores en la salida
5. Ir a **Table Editor** → debe aparecer la tabla `thoughts` con sus columnas

✅ **Checkpoint:** Si la tabla `thoughts` aparece, el paso 2 fue exitoso.

---

### Paso 3 — Generar MCP Access Key del cliente

Esta clave es la contraseña que el cliente usa para autenticarse con el servidor MCP. Es independiente de las claves de Supabase.

**Mac/Linux:**
```bash
openssl rand -hex 32
```

**Windows PowerShell:**
```powershell
-join ((1..32) | ForEach-Object { '{0:x2}' -f (Get-Random -Maximum 256) })
```

El resultado es una cadena de 64 caracteres hexadecimales. Guardar como **MCP Access Key** en el Credential Tracker del cliente.

---

### Paso 4 — Desplegar el servidor MCP

En terminal, ejecutar en orden:

```bash
# 1. Crear carpeta de trabajo temporal para este cliente
mkdir BrainOS-[nombre-cliente] && cd BrainOS-[nombre-cliente]

# 2. Inicializar proyecto Supabase local
supabase init

# 3. Conectar con el proyecto del cliente en la nube
#    (usar el Project Ref guardado en el Paso 1)
supabase link --project-ref PROJECT_REF_DEL_CLIENTE

# 4. Configurar los secretos del servidor
#    IMPORTANTE: usar guiones_bajos, NO guiones-medios
supabase secrets set MCP_ACCESS_KEY=LA_KEY_GENERADA_EN_PASO_3
supabase secrets set OPENROUTER_API_KEY=LA_KEY_DE_EMPOWERLABS

# 5. Crear la función Edge
supabase functions new BrainOS-mcp

# 6. Descargar el servidor MCP desde el repositorio OB1
curl -o supabase/functions/BrainOS-mcp/index.ts \
  https://raw.githubusercontent.com/NateBJones-Projects/OB1/main/server/index.ts

curl -o supabase/functions/BrainOS-mcp/deno.json \
  https://raw.githubusercontent.com/NateBJones-Projects/OB1/main/server/deno.json

# 7. Verificar que se descargó correctamente
head -3 supabase/functions/BrainOS-mcp/index.ts
# Debe mostrar algo como: import "jsr:@supabase/functions-js/edge-runtime.d.ts";

# 8. Deploy
supabase functions deploy BrainOS-mcp --no-verify-jwt
```

✅ **Checkpoint:** El deploy termina con mensaje `Done: Deployed Function BrainOS-mcp`.

---

### Paso 5 — Construir las credenciales del cliente

Con el **Project Ref** y el **MCP Access Key**, construir:

```
URL base del servidor MCP:
https://[PROJECT_REF].supabase.co/functions/v1/BrainOS-mcp

Connection URL (la que va al cliente):
https://[PROJECT_REF].supabase.co/functions/v1/BrainOS-mcp?key=[MCP_ACCESS_KEY]
```

Guardar ambas en el Credential Tracker del cliente.

---

### Paso 6 — Prueba de funcionamiento

Antes de entregar al cliente, verificar que el servidor responde:

```bash
# Test básico con curl — debe retornar JSON con herramientas disponibles
curl -s "https://[PROJECT_REF].supabase.co/functions/v1/BrainOS-mcp?key=[MCP_ACCESS_KEY]" \
  -X POST \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}' | head -50
```

La respuesta debe incluir `thought_stats`, `capture_thought`, `search_thoughts`, `list_thoughts`.

Si retorna `{"error":"Unauthorized"}` → revisar que el secret `MCP_ACCESS_KEY` está bien escrito (con guiones bajos).

---

### Paso 7 — Entrega al cliente

Lo único que el cliente necesita:

1. La **Connection URL** completa (con el `?key=...` al final)
2. Las instrucciones de conexión (ver Apéndice A — Instrucciones para el cliente)

El cliente **nunca debe ver** ni necesitar:
- Project Ref de Supabase
- Service Role Key
- OpenRouter API Key
- Contraseña de la base de datos

---

### Checklist final de provisioning

- [ ] Proyecto Supabase creado con nombre `BrainOS-[cliente]`
- [ ] Tabla `thoughts` visible en Table Editor
- [ ] Función `match_thoughts` visible en SQL Functions
- [ ] RLS activo y policy `Service role full access` creada
- [ ] Grant de permisos al service_role confirmado
- [ ] Secretos `MCP_ACCESS_KEY` y `OPENROUTER_API_KEY` configurados
- [ ] Función `BrainOS-mcp` desplegada (sin errores)
- [ ] Test de curl exitoso (tools/list retorna 4 herramientas)
- [ ] Connection URL construida y guardada en Credential Tracker
- [ ] Todas las credenciales en el Credential Tracker del cliente
- [ ] Connection URL entregada al cliente

---

## Sección 4 — Operación Continua

### Credential Tracker — Estructura por cliente

Para cada cliente, mantener un registro con estos campos:

| Campo | Descripción |
|-------|-------------|
| **Cliente** | Nombre del cliente |
| **Fecha de activación** | Cuando se entregó el servicio |
| **Project Name** | `BrainOS-[nombre-cliente]` |
| **Project Ref** | String del Project Ref de Supabase |
| **Project URL** | `https://[ref].supabase.co` |
| **DB Password** | Contraseña de la base de datos (generada en Step 1) |
| **Service Role Key** | Key de Supabase (uso interno EmpowerLabs — no compartir) |
| **MCP Access Key** | Key de autenticación del servidor MCP |
| **Connection URL** | URL completa con key — la que tiene el cliente |
| **Estado** | Activo / Suspendido / Offboarded |
| **Plan** | Setup $2,500 + $300/mes |
| **Próxima facturación** | Fecha del próximo cobro mensual |
| **Contacto técnico** | Quien del equipo gestiona este cliente |

### Monitoreo de salud del servicio

**¿Qué monitorear?**

| Señal | Frecuencia de revisión | Cómo verificar |
|-------|----------------------|----------------|
| **Thought count activo** | Semanal (via tarea programada del cliente o manual) | MCP tool `thought_stats` |
| **Edge Function activa** | Quincenal | Supabase → Edge Functions → Status |
| **Crédito OpenRouter** | Mensual | openrouter.ai → Usage |
| **Uso de base de datos Supabase** | Mensual | Supabase → Settings → Usage |
| **Errores en logs** | Cuando cliente reporta problemas | Supabase → Edge Functions → Logs |

**Cómo revisar logs de un cliente:**

1. Ir al dashboard del proyecto del cliente en Supabase
2. Panel izquierdo → **Edge Functions** → `BrainOS-mcp`
3. Tab **Logs** → filtrar por errores recientes
4. Los logs más comunes a revisar son errores `500` (servidor) y `401` (autenticación)

### Costos del servicio

**Costo por cliente activo (estimado):**

| Componente | Costo | Periodicidad |
|-----------|-------|-------------|
| **Supabase Free Tier** | $0 | Hasta 500MB de datos (~50,000-100,000 thoughts) |
| **Supabase Pro** (si supera Free) | ~$25/mes | Al superar el tier gratuito |
| **OpenRouter** (embeddings) | ~$0.02-0.10/mes | Por volumen de thoughts capturados |
| **Total estimado** | **~$0-$25/mes por cliente** | |

**Notas de costos:**
- El tier gratuito de Supabase cubre holgadamente a clientes que capturan <500 thoughts/mes
- OpenRouter `text-embedding-3-small` cuesta ~$0.02 por millón de tokens. Un thought promedio = ~100 tokens. 1,000 thoughts = ~$0.002
- EmpowerLabs puede usar **una sola API key de OpenRouter** para todos los clientes (centralizada)
- El margen del servicio es muy alto: costo real ~$0-3/mes, precio al cliente $300/mes

### Actualización del servidor MCP

Cuando OB1 (el repositorio base) publique actualizaciones importantes:

```bash
# Para un cliente específico
cd BrainOS-[nombre-cliente]
supabase link --project-ref PROJECT_REF

# Descargar nueva versión del servidor
curl -o supabase/functions/BrainOS-mcp/index.ts \
  https://raw.githubusercontent.com/NateBJones-Projects/OB1/main/server/index.ts

# Verificar cambios antes de desplegar
diff supabase/functions/BrainOS-mcp/index.ts [version-anterior]

# Desplegar actualización
supabase functions deploy BrainOS-mcp --no-verify-jwt
```

**Política de actualizaciones:**
- Actualizaciones de seguridad: desplegar inmediatamente en todos los clientes
- Nuevas features: notificar a Victor antes de desplegar
- Cambios de schema (base de datos): requieren aprobación de Victor y notificación al cliente

---

## Sección 5 — Troubleshooting

### Los 6 problemas conocidos

| # | Síntoma | Causa raíz | Solución |
|---|---------|-----------|----------|
| **1** | `Relative import path not prefixed with / or ./` en el deploy | El `index.ts` descargado tiene imports sin prefijo `npm:` compatible con Deno | Verificar que el archivo descargado de OB1 ya tenga los prefijos correctos. Si fue editado manualmente, restaurar desde el repositorio. |
| **2** | MCP responde `{"error":"Unauthorized"}` o `401` | El secret se guardó como `MCP-ACCESS-KEY` (guiones medios) en lugar de `MCP_ACCESS_KEY` (guiones bajos) | En Supabase → Settings → Secrets → verificar nombre exacto. Si es incorrecto, eliminar y crear de nuevo con guiones bajos. |
| **3** | Claude dice `Could not find the table 'public.thoughts'` | El SQL del Paso 2 no fue ejecutado, o falló silenciosamente con un error | Ir a Table Editor → verificar si existe `thoughts`. Si no, ejecutar el SQL completo de nuevo desde un archivo de texto externo. |
| **4** | Logs muestran `OAuth discovery 401` | El endpoint de OAuth discovery no está configurado como público | **No es un error real.** El servidor MCP usa key-based auth, no OAuth. Ignorar este log. |
| **5** | El SQL se ejecuta sin errores pero la tabla no aparece o tiene estructura incompleta | El editor del browser de Supabase corrompió caracteres como `$$` o comillas simples al tipear/pegar | Copiar el SQL a un editor de texto externo (VS Code, etc), copiarlo desde ahí al clipboard, y pegarlo con Cmd+V (nunca tipear directo en el browser SQL Editor). |
| **6** | `Permission denied for table thoughts` al usar `capture_thought` | Falta el `GRANT` del último bloque SQL | Ejecutar solo en el SQL Editor: `grant select, insert, update, delete on table public.thoughts to service_role;` |

### Diagnóstico rápido de incidentes

Cuando un cliente reporta que su BrainOS no funciona, seguir este árbol:

```
¿Claude puede ver el conector BrainOS?
│
├── NO → El conector se desactivó o se borró en Claude Desktop
│         → Pedir al cliente que verifique en Settings → Connectors
│         → Si fue borrado, reenviar Connection URL para reconectar
│
└── SÍ → ¿El conector retorna error o no responde?
         │
         ├── Error 401 → Problema de autenticación
         │   → Verificar que Connection URL del cliente tiene el ?key= correcto
         │   → Verificar secret MCP_ACCESS_KEY en Supabase (guiones bajos)
         │
         ├── Error 500 → Error interno del servidor
         │   → Revisar logs en Edge Functions → BrainOS-mcp
         │   → Posibles causas: OPENROUTER_API_KEY inválida o sin crédito
         │
         ├── Tool no encontrado → La función no está desplegada
         │   → Verificar en Supabase → Edge Functions que existe BrainOS-mcp
         │   → Si no existe, re-ejecutar el deploy del Paso 4
         │
         └── Conector "activo" pero no guarda thoughts → Problema de tabla
             → Verificar que la tabla thoughts existe en Table Editor
             → Si no existe, ejecutar el SQL del Paso 2
```

### Protocolo de escalación

| Severidad | Descripción | Tiempo de respuesta | Escalar a |
|-----------|-------------|--------------------|-----------|
| **P1 — Crítico** | Cliente sin servicio, ninguna operación funciona | < 2 horas | Victor directamente |
| **P2 — Alto** | Degradación parcial (ej. búsqueda no funciona, captura sí) | < 24 horas | Equipo técnico → Victor si >4h sin solución |
| **P3 — Medio** | Comportamiento inesperado sin pérdida de funcionalidad | < 72 horas | Equipo técnico |
| **P4 — Bajo** | Dudas, preguntas, mejoras | Próxima sesión disponible | Equipo técnico |

---

## Sección 6 — Offboarding de Cliente

Cuando un cliente termina su contrato o solicita la soberanía de sus datos:

### Opción A — Entrega del proyecto al cliente

El cliente quiere mantener su BrainOS pero operarlo él mismo:

1. Exportar todos los thoughts como CSV:
   - Supabase → Table Editor → `thoughts` → Export CSV
   - Guardar en el Credential Tracker del cliente

2. Cambiar el owner del proyecto Supabase:
   - Settings → Members → Invite al email del cliente como Owner
   - Una vez que el cliente acepta, removerlo de la organización EmpowerLabs

3. Documentar en el Credential Tracker: `Estado: Entregado — [fecha]`

4. El cliente deberá configurar su propia OpenRouter API Key en los secretos

### Opción B — Cierre y eliminación de datos

El cliente no quiere continuar y no necesita sus datos:

1. Exportar backup como en Opción A (para registro interno de EmpowerLabs)
2. En Supabase → Settings → General → **Delete Project**
3. Confirmar la eliminación
4. Actualizar Credential Tracker: `Estado: Offboarded — [fecha]`
5. Archivar las credenciales (no eliminar — pueden necesitarse para disputas o auditoría)

---

## Sección 7 — Gestión de OpenRouter (Cuenta Centralizada)

EmpowerLabs opera con **una sola cuenta de OpenRouter** cuya API Key se usa para todos los proyectos de clientes.

### Por qué es seguro usar una clave centralizada

La OpenRouter API Key vive en los secretos de Supabase de cada proyecto — no la tiene el cliente, no está expuesta en ninguna URL pública, y solo el servidor MCP en Supabase la usa internamente.

### Monitoreo de costos de OpenRouter

1. Ir a [openrouter.ai/usage](https://openrouter.ai/usage)
2. Revisar el consumo mensual total
3. Comparar con el número de clientes activos para detectar uso anómalo
4. Mantener un mínimo de $10 de crédito disponible siempre

**Alerta:** Si el consumo de embeddings supera $5/mes, revisar si algún cliente está haciendo capturas masivas o si hay alguna integración en loop.

### Política si se compromete la clave

1. Ir a OpenRouter → revocar la clave comprometida
2. Generar nueva clave
3. Actualizar el secret `OPENROUTER_API_KEY` en **todos** los proyectos de clientes:
   ```bash
   supabase secrets set OPENROUTER_API_KEY=NUEVA_KEY --project-ref PROJECT_REF_CLIENTE
   ```
4. Hacer redeploy de las Edge Functions de todos los clientes

---

## Sección 8 — Backups y Continuidad

### Política de backups

| Tipo | Frecuencia | Responsable | Dónde se guarda |
|------|-----------|-------------|-----------------|
| **Supabase automático** | Diario (Plan Pro) / Sin backup en Free Tier | Supabase | Dashboard → Backups |
| **Export manual CSV** | Mensual o ante cambios mayores | Equipo de sistemas | Credential Tracker del cliente |
| **Backup pre-offboarding** | Antes de cada cierre | Equipo de sistemas | Registro interno EmpowerLabs |

**Importante:** El Free Tier de Supabase no incluye backups automáticos. Si un cliente tiene datos críticos y alto volumen, considerar upgrade a Pro (~$25/mes).

### Plan de contingencia ante fallo de Supabase

Si Supabase tiene una caída de servicio (ver [status.supabase.com](https://status.supabase.com)):

1. Notificar a Victor para que comunique a los clientes afectados
2. Los clientes pueden seguir usando Tu Sherpa IA en modo L1 (Prompt Portable) mientras tanto
3. No hacer nada más — el servicio se restaura automáticamente cuando Supabase vuelve

---

## Apéndice A — Instrucciones de Conexión para el Cliente

> *Copiar y enviar al cliente cuando el BrainOS esté listo. No incluir nada más.*

---

**Tu BrainOS está listo. Para conectarlo:**

1. Abrir **Claude Desktop** en tu computadora
2. Hacer click en el ícono **+** en la parte inferior izquierda → **Add MCP Server**
3. En el campo URL, pegar exactamente:

```
[CONNECTION_URL_DEL_CLIENTE]
```

4. En el campo Nombre, escribir: `BrainOS`
5. Guardar y activar el toggle

**Verificar que funciona:**
En cualquier conversación de Claude, escribe:
```
Usa la herramienta thought_stats para decirme cuántos thoughts tengo
```

Si Claude responde con un número (probablemente 0 al inicio), tu BrainOS está conectado y listo.

**Guarda bien esta URL** — es todo lo que necesitas para reconectar si cambias de computadora.

Para soporte: victor@masterplaybooks.com

---

## Apéndice B — Glosario Técnico

| Término | Definición |
|---------|-----------|
| **BrainOS** | La base de datos vectorial que actúa como memoria persistente del Sherpa IA |
| **Thought** | Una unidad de memoria: decisión, aprendizaje, compromiso o contexto capturado |
| **Embedding** | Representación matemática del significado de un texto (vector de 1536 números) |
| **MCP** | Model Context Protocol — el protocolo estándar que permite a Claude usar herramientas externas |
| **Edge Function** | Código que corre en los servidores de Supabase, actúa como el servidor MCP |
| **Project Ref** | El identificador único de un proyecto Supabase (string de ~20 caracteres) |
| **Service Role Key** | La clave maestra de Supabase — acceso total a la base de datos. Uso exclusivo interno |
| **MCP Access Key** | La clave que usa el servidor MCP para autenticar las peticiones de Claude |
| **Connection URL** | La URL completa con el `?key=` que el cliente pega en Claude Desktop |
| **RLS** | Row Level Security — capa de seguridad de Supabase que controla acceso a filas |
| **pgvector** | Extensión de PostgreSQL que habilita la búsqueda vectorial (semántica) |
| **OpenRouter** | Servicio que provee acceso a modelos de embeddings (y otros modelos de IA) |
| **Track A** | Modelo de instalación donde EmpowerLabs opera toda la infraestructura |
| **Track B** | Modelo de instalación donde el cliente instala su propio BrainOS |

---

## Registro de versiones

| Versión | Fecha | Cambio |
|---------|-------|--------|
| v1.0 | 2026-03-23 | Creación inicial. Cubre provisioning completo, operación, troubleshooting, offboarding, costos y apéndices. Basado en aprendizajes de FI-SHA-VICTOR (Caso 0) y SHA-GuiaInstalacion-v01. |

---

*[[SHA-SOP-SysOps-v01]] v1.0 — EmpowerLabs / Victor Heredia — 2026-03-23*
*Documento interno. No compartir con clientes.*
*Actualizar después de cada incidente relevante o cambio de arquitectura.*