Metadata-Version: 2.3
Name: onesensei
Version: 0.8.0
Summary: Monitor local y privado de tu uso de IA (Claude Code y más). 100% local, solo lectura.
Project-URL: Homepage, https://github.com/OneTerminal-co/sensei
Author: Yulian Zapata
Keywords: claude-code,cost,dashboard,local,privacy,telemetry
Classifier: License :: Other/Proprietary License
Requires-Python: >=3.9
Provides-Extra: pro
Requires-Dist: cryptography>=42; extra == 'pro'
Provides-Extra: voice
Requires-Dist: piper-tts>=1.4; extra == 'voice'
Description-Content-Type: text/markdown

# Sensei

> *El que observa, entiende y enseña.*

Construyes con agentes de IA todos los días. Claude Code, opencode, Kiro, varios modelos, decenas de sesiones, varios clientes. Pero al final del mes tienes una pregunta que nadie responde: **¿cuánto costó todo eso y valió la pena?**

Sensei observa tu trabajo. En silencio, localmente, sin enviar nada a ningún lado. Cada mañana te entrega un reporte. Cada vez que lo pides, te dice exactamente a dónde fue tu plata y qué patrones detectó. Y cuando te ve hacer lo mismo por novena vez, dice: *eso deberías convertirlo en un skill.*

```bash
uvx onesensei          # abrir el dashboard, sin instalar nada
uvx onesensei morning  # tu briefing diario
uvx onesensei doctor   # ver qué puede leer Sensei

# instalado permanentemente (pip install onesensei), es el mismo binario `sensei`:
sensei morning
sensei doctor
```

---

## La historia

**6:47 AM.** Antes de que abras la laptop, Sensei ya estuvo trabajando.

Leyó todas las sesiones de ayer — Claude Code, opencode, Kiro IDE y Kiro CLI. Calculó el costo exacto: $100/mes de tu plan Claude Max, 2.6B tokens usados, 1.8 credits de Kiro. Miró qué modelo usaste para qué, notó que gastaste el 82% del presupuesto en Opus para tareas que Sonnet resuelve igual de bien, y estimó cuánto te cuesta eso por mes. Revisó tus repos git por cambios sin commitear y sacó la próxima acción de cada `STATUS.md`. Detectó que arrancaste cinco sesiones de presales esta semana con contexto casi idéntico — el mismo brief del cliente, tipeado desde cero cada vez.

A las 7:00 AM imprimió esto en tu terminal:

```
════════════════════════════════════════════════
  Sensei · Reporte matutino — 2026-06-30
════════════════════════════════════════════════
  Gasto total     : $100.00/mes (Claude Max)
  Tokens          : 2.6B (suscripción)
  Valor mercado   : $37.5k est.
  Kiro CLI        : 1.8 credits

  ⚡ 2 insights:
    🔴 Opus está haciendo trabajo que Sonnet puede hacer
       $0 adicional pero sí costo de oportunidad
    🔵 5 sesiones largas sin checkpoint

  💡 2 skills para crear:
    · client-bootstrap (alta)
    · eks-triage (alta)
════════════════════════════════════════════════
```

---

## Qué hace Sensei

```
┌─────────────────────────────────────────────────────────┐
│  Sensei · tres capas                                    │
│                                                         │
│  OBSERVAR    lee tus archivos locales (Claude Code,     │
│              opencode, Kiro IDE, Kiro CLI, git)         │
│              — nunca los escribe                        │
│                                                         │
│  ENTENDER    costo exacto por sesión, por modelo,       │
│              por cliente. Suscripción vs API exacto.    │
│              Proxy de ROI. Cache hit. Tendencia 30d.    │
│                                                         │
│  ENSEÑAR     Reglas del Coach: cuándo cambiar de        │
│              modelo, cuándo hacer checkpoint, qué        │
│              convertir en skill. Evidencia incluida.    │
└─────────────────────────────────────────────────────────┘
```

---

## Fuentes

| Herramienta | Superficie | Qué captura | Unidad |
|-------------|-----------|-------------|--------|
| **Claude Code** | CLI | Tokens por sesión/modelo (con desglose input/output/cache), caché, costo exacto | USD (API o suscripción) |
| **opencode** | CLI | Sesiones SQLite, modelo usado, tokens con desglose | USD o suscripción |
| **Kiro IDE** | VS Code ext. | Tokens por workspace, costo por sesión | USD |
| **Kiro CLI** | Terminal | Credits consumidos por turn | credits |
| **GitHub Copilot Chat** | VS Code ext. | Sesiones de chat, turns, modelo por defecto | suscripción |
| **GitHub Copilot CLI** | Terminal | Sesiones y turns (sin tokens/modelo — no lo expone en disco) | suscripción |
| **GitHub Copilot OTel** *(anidado en "copilot", no es card propia)* | VS Code ext. | Tokens reales input/output por conversación — opt-in, apagado por default | suscripción |
| **git** | repos | Rama, dirty flag, `STATUS.md` | — |

Kiro IDE lee de `~/Library/Application Support/Kiro/User/globalStorage/kiro.kiroagent/`.
Kiro CLI lee de `~/.kiro/sessions/cli/`.
opencode lee de `~/.local/share/opencode/opencode.db` (SQLite).
Copilot Chat lee `workspaceStorage/*/GitHub.copilot-chat/transcripts/*.jsonl` de VS Code
(Code, Code - Insiders, VSCodium, Code - OSS — incluye instalaciones Snap y Flatpak en Linux).
Copilot CLI lee `~/.copilot/session-store.db` (SQLite) — ambas superficies se combinan
en una sola fuente "copilot", cada sesión etiquetada por `extra.surface` (`vscode`/`cli`).

**Tokens reales de Copilot Chat (fuera de Sensei, por ahora):**

- **Por qué hace falta esto:** ni los transcripts de VS Code ni el CLI exponen tokens o
  costo real por conversación — es la razón por la que Sensei cuenta *turnos*, nunca
  tokens, para Copilot en todo este documento. No es una limitación de Sensei: esa data
  simplemente no existe en disco salvo que la actives vos mismo.
- **Qué se obtiene activándolo:** VS Code puede exportar tokens reales por request
  (`gen_ai.usage.input_tokens` / `output_tokens`) vía OpenTelemetry — la misma data que
  usa GitHub para facturar en AI Credits, pero apagada por default.
- **Cómo activarlo** — agregá esto a tu `settings.json` de VS Code:

```json
{
  "github.copilot.chat.otel.enabled": true,
  "github.copilot.chat.otel.exporterType": "file",
  "github.copilot.chat.otel.outfile": "/Users/tu-usuario/.copilot-otel.jsonl"
}
```

  Reiniciá VS Code completo (no alcanza con "Reload Window") y mandá un mensaje en
  Copilot Chat — el archivo se crea recién con la primera interacción, no al guardar el
  setting.
- **Cómo lo usa Sensei:** activá `sources.copilot_otel` en `~/.sensei/config.json` (o en
  `/settings`) con `enabled: true` y `path` apuntando al mismo archivo que configuraste
  como `outfile` arriba:

```json
"copilot_otel": {
  "enabled": true,
  "path": "/Users/tu-usuario/.copilot-otel.jsonl"
}
```

  No aparece como una card nueva en el dashboard — no hay ningún campo en el archivo
  OTel que permita correlacionar una conversación con el `session_id` de los
  transcripts, así que fusionarlas por sesión inventaría una relación que no existe.
  En cambio, se anida como enriquecimiento en `sources.copilot.real_usage`: tokens de
  entrada/salida reales por conversación, con `api_equivalent_cost` calculado sobre
  esos tokens reales (no la aproximación por turnos). Los componentes que ya usan
  `by_model`/`api_equivalent_cost` de una fuente (ej. la kata "Plan a medida") prefieren
  automáticamente `real_usage` cuando está disponible, en vez de sumarlo aparte —
  mismo período contado una sola vez, con el número más preciso. `sensei doctor`
  confirma si el archivo está configurado y encontrado.
- **Límite conocido:** el nombre de modelo que reporta VS Code (ej. `claude-haiku-4.5`,
  con punto) puede no coincidir con la clave de tu tabla de `pricing.models` (ej.
  `claude-haiku-4-5`, con guion) — en ese caso el costo equivalente se estima con la
  tarifa `_default`, no con la tarifa exacta de ese modelo. Agregá el nombre tal cual lo
  reporta VS Code a `pricing.models` si querés precisión exacta.
- **Fuera de alcance por ahora:** esta fuente no aparece en `/live` ni en el chip de
  Burn rate — esas vistas siguen siendo Claude Code/opencode (tokens reales medidos al
  vuelo) + Copilot por turnos (ver arriba). Integrarla ahí requeriría poder identificar
  una conversación de OTel como "activa ahora mismo", que el formato actual no facilita
  sin más instrumentación. Tampoco alimenta el ROI todavía: `roi.py` excluye toda sesión
  con `cost == 0` (el filtro central de esa vista), y Copilot siempre reporta `cost=0.0`
  — integrarlo ahí implica pasarle la tabla de precios a `roi.compute()`, calcular un
  costo-equivalente por sesión y recalibrar los umbrales de cuadrante (pensados para
  magnitudes de $ real de API), además de distinguir visualmente "estimado" de "real" en
  el scatter para no violar HONEST NUMBERS — queda pendiente como su propio diseño.

**Más señales reales, además de tokens** (mismo archivo OTel, sin config adicional):
además de tokens por conversación, el archivo trae errores de red/backend
(`copilot_chat.cloud.error.count`), latencia real por modelo
(`gen_ai.client.operation.duration`), y eficiencia de tool calls del agente
(`copilot_chat.tool.call`, con duración y éxito). **Importante:** VS Code re-exporta el
estado *acumulado completo* de estas métricas cada ~10s, incluso sin actividad nueva —
no son deltas pese a declarar `aggregationTemporality: 1` (verificado con datos reales:
el mismo grupo de atributos reporta valores crecientes con el mismo `startTime`). Sensei
se queda con el último reporte de cada combinación de atributos, nunca suma cada reporte
periódico (eso inventaría números absurdos). Con esto, `sources.copilot.real_usage`
también trae:
- `errors`: errores reales reportados por Copilot (no de tu código), por operación y tipo.
- `latency_by_model`: latencia media real por modelo (no percentiles — requeriría
  fusionar los buckets explícitos del histograma, que no se implementó todavía).
- `tool_stats`: llamadas/fallas/duración total por tool del agente (`run_in_terminal`,
  `read_file`, etc.).
- `context_inflation`: sesiones con ratio input/output sostenidamente alto (2+ turnos con
  mucho input para poco output) — proxy de contexto repetido sin resumir.

Tres katas nuevas del Coach usan esto directo: **"Falla repetida"** (3+ errores del mismo
tipo), **"Tool lenta"** (3+ llamadas con promedio ≥5s o ≥20% de fallas), y **"Contexto
repetido"** (sesión con ratio input/output inflado). Ninguna dispara sin evidencia
suficiente — mismo criterio que el resto del Coach.

**Lectura incremental:** el archivo crece rápido por el re-export periódico de arriba —
releerlo entero en cada `collect()` no escala. Sensei guarda un cursor de bytes + el
estado ya derivado en `~/.sensei/cache/copilot_otel/`, y solo procesa los bytes nuevos en
cada corrida (mismo patrón que ya usa `sensei statusline`/`/live` para los transcripts de
Claude Code). Sensei nunca escribe ni trunca el archivo OTel en sí — es de VS Code, no
de Sensei; solo cachea su propio derivado dentro de `~/.sensei/`.

**Claude Desktop (Cowork y sesiones despachadas):** cuando Claude Code corre embebido en
la app de escritorio (terminal integrada o sub-agentes de Cowork), el transcript completo
se escribe en la misma ruta que la CLI (`~/.claude/projects/`) y Sensei lo cuenta con costo
exacto. Cuando un sub-agente no llega a persistir ese transcript completo, Sensei recupera
un resumen parcial de `~/.claude/usage-data/session-meta/` (solo tokens input/output, sin
cache, tarifa `_default`) y lo muestra **separado y marcado como estimado** — nunca sumado
al costo exacto.

**Límite conocido:** esto solo cubre el motor de Claude Code. Las conversaciones de **Chat**
y **Design** (canvas/artifacts) de Claude Desktop que no invocan ese motor no dejan ningún
archivo local con conteo de tokens — ese dato vive del lado de Anthropic, no en disco. Como
Sensei es LOCAL ONLY / READ ONLY, no hay forma honesta de reconstruir ese costo sin inventarlo,
así que esas sesiones no aparecen en absoluto.

---

## Facturación por modelo

Sensei entiende que dentro de una misma herramienta puedes tener modelos con distinto esquema de pago. Se configura en la UI de Settings (`/settings`) o directamente en `~/.sensei/config.json`:

```json
"sources": {
  "claude_code": {
    "model_billing": { "_default": "subscription" },
    "subscriptions": [
      { "name": "Claude Max", "monthly_usd": 100, "covers": ["*"] }
    ]
  },
  "opencode": {
    "model_billing": { "_default": "free" }
  },
  "kiro": {
    "model_billing": { "kiro/cli": "credits", "_default": "api" }
  }
}
```

**Tipos de facturación:**

| Tipo | Qué hace Sensei |
|------|-----------------|
| `api` | Costo exacto = tokens × tarifa. Se suma al total USD. |
| `subscription` | Costo = $0 adicional (cubierto por el plan). Se muestra el `monthly_usd` del plan. |
| `free` | Costo = $0. Los tokens se cuentan pero no se cobran. |
| `credits` | Unidad propia (Kiro CLI). No se mezcla con USD. |

**Presets en la UI de Settings** — un clic para configurar:
- Claude Code: API key · Claude Pro $20/mes · Claude Max $100/mes · Claude Max $200/mes · Personalizado
- opencode: API key · Modelos locales (gratis) · Plan mensual · Personalizado
- Kiro: Solo IDE por token · Solo IDE plan mensual · Solo CLI credits · CLI+IDE · Personalizado
- GitHub Copilot: sin presets (billing siempre suscripción) — solo enable/disable, plan mensual opcional y override de ruta de la extensión VS Code. El CLI (`~/.copilot`) se auto-detecta siempre, sin campo de configuración propio.

---

## Configuración

Editá `~/.sensei/config.json` o usá `/settings` en el dashboard:

### Precios (costo exacto, no estimado)

```json
"pricing": {
  "models": {
    "claude-opus-4-8":   { "input": 15.00, "output": 75.00,
                           "cache_read": 1.50, "cache_write": 18.75 },
    "claude-sonnet-4-6": { "input": 3.00,  "output": 15.00,
                           "cache_read": 0.30, "cache_write": 3.75 },
    "claude-haiku-4-5":  { "input": 0.80,  "output": 4.00,
                           "cache_read": 0.08, "cache_write": 1.00 }
  }
}
```

> ¿Usas **Bedrock**? Reemplaza estos valores con tus tarifas de Bedrock. Sensei calcula `tokens × tarifa` — nunca estima.

### Alias de modelos

Si opencode o Kiro usan nombres internos distintos al modelo real:

```json
"model_pricing_alias": {
  "big-pickle": "claude-sonnet-4-6"
}
```

### Atribución por cliente

```json
"clients": {
  "map": {
    "acme-prd-*":       "Client A",
    "bancoomeva-cards": "Client A",
    "freelance-*":      "Client B",
    "my-brain":         "Personal"
  }
}
```

Soporta comodines `prefix-*`. Los proyectos sin match quedan como "Sin asignar".

### Objetivos

```json
"goals": {
  "monthly_budget_usd": 300,
  "target_score": 80,
  "client_budgets": { "Client A": 200 }
}
```

Editables en `/settings`. Con presupuesto configurado, el tab Costos muestra el gasto API real del mes, la proyección lineal a fin de mes (etiquetada como inferida) y un semáforo; con `target_score`, el Coach muestra la barra de progreso; `client_budgets` agrega semáforo por cliente. `sensei morning` incluye todo en el bloque 🎯 Objetivos.

---

## Cerrar el loop: de detectar a escribir

Sensei no solo diagnostica — cierra el ciclo con números medidos:

1. **Detectar** — el Coach mide contexto repetido de verdad: agrupa sesiones de un mismo proyecto cuya apertura es *idéntica* (hash exacto del primer mensaje) y te dice cuántos tokens re-enviaste. El grafo del Perfil marca nodos con oportunidad (proyecto con sesiones repetidas → CLAUDE.md; framework recurrente → skill).
2. **Cuantificar** — el **Simulador de model-mix** (tab Costos) recalcula tu desglose real de tokens bajo otra tarifa: aritmética exacta, no estimación. La **autopsia de sesión** (botón "¿Por qué?" en el Coach) desglosa una sesión cara por tipo de token — p.ej. "45% del costo fue cache read".
3. **Generar** — CLAUDE.md / skill sugerido por el CLI de IA local (con fallback a reglas si no hay CLI).
4. **Escribir** — el botón **"Aplicar…"** guarda el archivo generado, con doble restricción del server: solo dentro de tu HOME y solo archivos llamados `CLAUDE.md` o `SKILL.md`. Siempre confirmado por ti.

Además: **export CSV** de todas las sesiones (botón en Costos o `GET /api/export.csv`) con la base de cada costo declarada por fila (`api` / `plan` / `credits`), **burn rate real** (tokens/min medidos del tail de los transcripts activos — sin actividad muestra 0.0, nunca un número inventado) y **trayectoria del score** (serie de tus snapshots matutinos reales).

---

## En vivo: el costo mientras estás gastando

Todo lo anterior mira hacia atrás. El copiloto en vivo actúa en el momento:

**`sensei statusline`** — el costo de tu sesión activa de Claude Code, en tu prompt, en cada turno:

```
⛩ $2.41 · 187k tok · sonnet-4-6 · ≈$0.08/turno
```

Agregá a `~/.claude/settings.json` (Sensei no toca ese archivo — es tuyo):

```json
"statusLine": { "type": "command", "command": "sensei statusline" }
```

Lectura **incremental**: guarda un cursor por sesión en `~/.sensei/cache/live/` y solo lee los bytes nuevos — ~40ms por invocación aunque el transcript pese cientos de MB. El ⚠ aparece al pasar 200k tokens (el umbral del coach: de ahí en más cada turno cuesta más sin ganar precisión).

**`/live`** (◉ en la nav del dashboard) — las sesiones activas de los últimos 30 minutos: Claude Code y opencode con costo acumulado, **≈ costo del próximo turno** (= el último observado, etiquetado como inferido) y barra de progreso hacia el umbral de cierre. **GitHub Copilot** (Chat en VS Code y CLI) también aparece ahí, pero mostrando **turnos**, no tokens — GitHub no expone tokens/costo real por conversación, así que no se inventa un número: se muestra "suscripción" en vez de un `$`, y sin la barra de contexto (no aplica a un conteo de turnos). Refresco cada 5s.

El tile **Burn rate** del dashboard principal sigue el mismo criterio: el número grande es 100% tokens/min real de Claude Code + opencode; si hay actividad reciente de Copilot aparece un chip aparte debajo ("+N turnos/min en Copilot — no sumado arriba"), nunca mezclado con el número real.

**Configuración en VS Code:** no hace falta activar nada especial para que esto funcione. Sensei detecta automáticamente la extensión GitHub Copilot Chat en VS Code, VS Code - Insiders, VSCodium o Code - OSS (incluye instalaciones Snap/Flatpak en Linux) apenas la usaste una vez — lee `workspaceStorage/*/GitHub.copilot-chat/transcripts/*.jsonl`, el mismo directorio donde la extensión ya guarda tu historial de chat. Si tenés una instalación en una ruta no estándar, podés apuntar Sensei a mano desde `/settings` → GitHub Copilot → ruta de la extensión VS Code.

---

## Vistas del dashboard

```
  [Resumen] [Tendencia] [ROI] [Skills] [Proyectos] [Costos] [Coach] [Perfil]

  Resumen     → cards por herramienta (plan/API/credits/tokens),
                anillo de burn rate, gasto total, cache hit,
                ROI, sesiones activas, IA subsidiada

  Tendencia   → gráfico de área 14/30d por herramienta:
                costo USD + tokens, créditos Kiro CLI aparte

  ROI         → scatter por sesión
                sage=replicar · sky=ok · gold=neutral · rose=revisar

  Skills      → ranking de uso con gráfico de barras

  Proyectos   → rama git + flag dirty + próxima acción
                ordenados por costo (donde más inviertes)

  Costos      → presupuesto con proyección, barras por cliente
                (con semáforo por presupuesto) + por herramienta
                + por modelo, simulador de model-mix, export CSV

  Coach       → score de madurez con trayectoria y objetivo,
                insights con evidencia (badges nueva/recurrente),
                autopsia de sesiones caras, contexto repetido
                medido, sugerencias de skills con "Aplicar…"
                "Sin datos = sin insight" (nunca fabrica)

  Kata → recomendaciones de emergencia cuando el gasto
                aprieta (CLI ya instalada y sin usar, proyección
                sobre presupuesto, modelo local como respaldo).
                Sidebar ⚠ · feature Pro

  Perfil      → mapa de actividad, burn por hora, distribución
                de tamaño de sesiones, tendencia de modelos
```

---

## Instalación

```bash
# Portable — sin instalación permanente:
uvx onesensei

# O permanente:
pip install onesensei
sensei
```

**Plataformas soportadas:** macOS (Apple Silicon) y Windows. Linux y macOS Intel
todavía no tienen wheel — `pip install`/`uvx` van a fallar ahí hasta que se
agreguen (ver [CHANGELOG](CHANGELOG.md)).

La primera vez, el dashboard abre con un **wizard de bienvenida** de 3 pasos: qué fuentes detectó en tu máquina (con conteo real de sesiones), cómo pagas Claude (API / Pro / Max de Anthropic — decide cómo se calculan tus costos, no confundir con el tier Pro de Sensei) y objetivos opcionales. "Omitir" usa los defaults y no vuelve a aparecer. Para setups por SSH o scripts existe la variante de terminal: `sensei setup`.

---

## Comandos

| Comando | Qué hace |
|---------|----------|
| `sensei` | Abrir dashboard en `http://127.0.0.1:4317` (con wizard de bienvenida la primera vez) |
| `sensei start` | Levantar el dashboard en background, sin bloquear la terminal |
| `sensei stop` | Parar el server que corre en background |
| `sensei status` | Ver si hay un server corriendo, en qué puerto y desde cuándo |
| `sensei setup` | Setup guiado en terminal (para SSH/headless; el del dashboard es el principal) |
| `sensei doctor` | Verificar entorno: rutas detectadas (Claude Code, opencode, Copilot VS Code, Copilot CLI), fuentes, precios |
| `sensei scan` | Imprimir payload JSON completo y salir |
| `sensei export [--output archivo.csv]` | Exportar todas las sesiones en CSV (stdout por defecto) |
| `sensei insights [--json]` | Score de madurez y sus reglas — texto o JSON |
| `sensei costo [--by-work-item] [--export carpeta] [--merge "carpeta/*.json"]` | Costo agrupado por work item (rama git / nombre de proyecto). `--export` guarda el agregado de este dev; `--merge` suma varios exports ya generados (mutuamente excluyentes) |
| `sensei roi` | Scatter ROI en ASCII — deshabilitado por defecto, activar con `features.roi_ascii.enabled: true` en `~/.sensei/config.json` |
| `sensei profile [show\|update]` | Developer Memory: perfil inferido del stack/tipo de trabajo (`show` imprime, `update` recalcula y escribe `~/.sensei/profile/`) — **Pro**, ver abajo |
| `sensei statusline` | Costo de la sesión activa para el statusLine de Claude Code (pensado para invocarse desde `~/.claude/settings.json`, no a mano) |
| `sensei morning [--speak]` | Reporte terminal + snapshot en `~/.sensei/reports/` (`--speak` lo lee en voz alta con TTS nativo) |
| `sensei install-morning` | Instalar job diario a las 7am (launchd en Mac, crontab en Linux, Task Scheduler en Windows) |
| `sensei install-daemon` | Instalar el dashboard como servicio persistente — arranca solo en cada login (launchd en Mac, Task Scheduler en Windows) |
| `sensei uninstall-daemon` | Desinstalar el servicio persistente |
| `sensei dojo connect --url <url> --token <token>` | Conectar con un Dojo usando un token de activación de seat — desbloquea features **Pro** |
| `sensei dojo status` | Ver el estado de la licencia Pro actual |
| `sensei dojo disconnect` | Desconectar y volver a Basic |
| `sensei --port 5000` | Cambiar puerto |
| `sensei --host 0.0.0.0` | Cambiar host (el server igual valida `Host` contra loopback) |
| `sensei --no-browser` | No abrir el navegador |
| `sensei --claude-path <ruta>` | Override de la ruta de Claude Code (default `~/.claude`) |

---

## Sensei Basic vs Pro

Sensei funciona completo sin nada más: cost engine, `sensei export`, copiloto en vivo, autopsia de sesión, contexto repetido y weekly diff son **Basic**, sin licencia, sin Dojo.

El corte es **dato crudo vs. interpretación**: todo lo que *mide* es Basic; todo lo que *interpreta o recomienda* — simulador de model-mix (Whatif), scatter de ROI, banda de referencia de cache, Developer Memory/Profile (`sensei profile`) y las recomendaciones de **Kata** — requiere una licencia Pro emitida por un Dojo. Sin licencia, esas vistas aparecen visibles pero bloqueadas en el dashboard, y `sensei profile` imprime el mensaje de cómo conectarte en vez de degradar en silencio.

**El Coach base sí se ve en Basic.** Los insights heurísticos del Coach (modelo caro que domina el gasto, proyecto concentrado, sesiones largas, presupuesto p90, eficiencia de cache) son locales, baratos y explicables por diseño — se calculan y muestran sin licencia, porque HONEST NUMBERS no depende de Pro. Lo único que queda detrás de Pro dentro del Coach es la categoría **Kata** y la capa narrativa con IA (los botones "¿Por qué?" / "¿Cómo lo hago?"). Sin licencia, el panel Coach muestra sus insights base más un aviso chico de upsell, nunca una pantalla tapada.

```bash
sensei dojo connect --url http://localhost:8088 --token <token-del-seat>
sensei dojo status
sensei dojo disconnect
```

La licencia es por seat (un token por dev), se firma con Ed25519 (Sensei solo guarda la clave pública del Dojo, nunca una privada), tiene TTL de 48h y se refresca sola. La feature Pro opcional requiere `pip install "onesensei[pro]"` (extra `cryptography`, no viene por defecto en `ZERO DEPS`) — sin ella, toda feature Pro degrada a bloqueada, nunca rompe.

---

## Reporte matutino

```bash
sensei morning
```

Instalarlo como job diario en Mac:

```bash
sensei install-morning
# Corre todos los días a las 7:00 AM
# Logs: ~/.sensei/morning.log
```

O con crontab:

```bash
crontab -e
0 7 * * * sensei morning >> ~/.sensei/morning.log 2>&1
```

---

## Reglas del Coach

*(Pro — requiere `sensei dojo connect`, ver [Sensei Basic vs Pro](#sensei-basic-vs-pro))*

El Coach detecta patrones como uso dominante de un modelo caro, cache hit bajo, concentración de gasto en un proyecto o sesiones largas recurrentes — cada regla se dispara solo con evidencia real y exacta, nunca especulación. Sin datos → sin insight. Fuente marcada como "regla" (heurística), sin IA generativa.

---

## ROI

*(Pro — requiere `sensei dojo connect`. El scatter ASCII de `sensei roi` es aparte: no depende de licencia, solo del feature flag `roi_ascii`.)*

Cada sesión recibe un puntaje de valor (0-100) a partir de señales observables — actividad de git, profundidad de la sesión, indicios de output real — y se cruza contra el costo en USD para ubicarla en un cuadrante: **replicar** (alto valor, bajo costo), **vigilar** (alto valor, alto costo), **neutral** (bajo valor, bajo costo) o **revisar** (alto costo, bajo valor).

> El valor es un **proxy** basado en señales observables. No es verdad absoluta — úsalo como brújula, no como veredicto.

---

## Las tres reglas que Sensei nunca rompe

```
1. SOLO LOCAL      el servidor escucha en 127.0.0.1 únicamente.
                   Nada sale de tu máquina.

2. SOLO LECTURA    Sensei nunca escribe tus archivos por su cuenta.
                   Única excepción, acotada y explícita: el botón
                   "Aplicar…" escribe CLAUDE.md/SKILL.md dentro de
                   tu HOME, solo cuando tú lo confirmas.

3. NÚMEROS HONESTOS  costo = tokens × tarifa, exacto.
                     Suscripción = plan declarado, no estimado.
                     Credits de Kiro CLI nunca se mezclan con USD.
                     El ROI siempre se etiqueta como proxy.
```

---

## Roadmap

- [x] **Capa AI del Coach** — narrativas vía CLI de IA local (Claude Code/opencode), 100% local, con fallback a reglas
- [ ] **Paridad opencode** — contexto repetido, autopsia y burn hoy son solo Claude Code
- [ ] **Plugin VS Code** — panel WebView dentro del editor
- [ ] **Collector Bedrock** — leer directamente desde logs de CloudWatch
- [ ] **Multi-máquina** — sincronizar `~/.sensei/reports/` vía iCloud/Dropbox
- [ ] **Pesos ROI personalizados** — scoring configurable en `~/.sensei/config.json`
