Tabla D1 bib_tours

Creada en migration 0034_bib_tours.sql · s79 (22-05-2026, PR#60).

Almacena los tours pedagógicos generados por bib_generate_tour. Actúa como cache con TTL de 24 horas: si existe un tour vigente para (app, focus), se devuelve directamente sin invocar Haiku (coste $0).

Schema

CREATE TABLE bib_tours (
  id             INTEGER PRIMARY KEY AUTOINCREMENT,
  app            TEXT NOT NULL,
  focus          TEXT,                             -- NULL = tour general
  title          TEXT NOT NULL,
  summary        TEXT,
  steps_json     TEXT NOT NULL,                    -- JSON array de pasos
  step_count     INTEGER DEFAULT 0,
  cost_usd       REAL DEFAULT 0,
  input_tokens   INTEGER DEFAULT 0,
  output_tokens  INTEGER DEFAULT 0,
  created_at     TEXT DEFAULT (datetime('now')),
  expires_at     TEXT DEFAULT (datetime('now', '+24 hours'))
);

(Schema exacto en migrations/0034_bib_tours.sql — diff truncado en el PR; confirmado por descripción y handler.)

Estructura de steps_json

Array de objetos con el siguiente shape:

interface TourStep {
  order: number;           // 1-based, orden topológico
  title: string;           // Máx 80 chars, castellano técnico
  description: string;     // Explicación del paso
  node_qnames: string[];   // 1-3 qualified_names del grafo
  why_now: string;         // Justificación del orden (1 frase)
}

Lógica de cache

1. bib_generate_tour(app, focus, use_cache=true) busca en bib_tours un registro con app = ? AND COALESCE(focus,'') = COALESCE(?,'') AND expires_at > datetime('now').
2. Cache hit: devuelve el tour con cached: true. Coste: $0.
3. Cache miss: genera con Haiku, persiste con expires_at = now + 24h, devuelve con cached: false.
4. use_cache=false fuerza regeneración incluso si existe registro vigente.

Tours expirados no se borran automáticamente; quedan accesibles vía bib_list_tours(include_expired=true) para auditoría histórica.

Tools que usan esta tabla

Casos de uso

• Onboarding técnico: Dani o Txell piden bib_generate_tour(app="monitoring") → reciben walkthrough de 5-15 pasos ordenado topológicamente.
• Dev externo: al incorporar un nuevo colaborador, generar tour del app relevante como primera lectura.
• PR review: focus="auth" para un tour acotado al subsistema de autenticación antes de revisar un PR de seguridad.

Véase también

• [[feature—biblioteca—s79-understand-anything-cherry-picks]]
• [[entity—workspace—service—anthropic-lib]]
• [[entity—workspace—table—bib-layers]]
• [[decision—20260522—evaluacion-understand-anything-vs-bibliotecario]]