/wiki-init — Wiki Viviente para humanos y agentes

Instala un sistema de documentación completo en cualquier repo. Sirve tanto para
un dev nuevo que no sabe nada del proyecto, como para el agente que retoma contexto
en cada sesión. Es un documento vivo: cada cambio importante se refleja en el wiki
y se sube a Linear como resource del proyecto.

Precondiciones

1. Estar dentro del repo destino (CWD = root del proyecto).
2. El repo tiene CLAUDE.md en root (si no, crearlo mínimo antes).
3. El repo NO tiene ya /wiki (si lo tiene, avisar y preguntar antes de sobreescribir).

Qué instala

Estructura

<repo>/
├── wiki/
│   ├── index.md          ← bienvenida + mapa del proyecto (empieza aquí)
│   ├── onboarding.md     ← cómo arrancar desde cero (para humanos)
│   ├── architecture.md   ← stack, capas, datos, auth
│   ├── testing-guide.md  ← flujos que un humano debe probar + tests automáticos
│   ├── decisions.md      ← decisiones técnicas con Por qué / Aplica a
│   ├── changelog.md      ← historial de cambios por sesión (documento vivo)
│   ├── dont-touch.md     ← archivos privados, config sensible, reglas commit
│   ├── glossary.md       ← términos del dominio
│   ├── workflows.md      ← flujos recurrentes + delegación humana
│   └── reference.md      ← IDs Linear/Harvest, Slack, APIs frecuentes
├── raw/
│   └── README.md         ← inbox de notas crudas
├── scripts/
│   └── wiki-sync.mjs     ← sube wiki a Linear como resource
├── .gitignore            ← + raw/* !raw/README.md
└── CLAUDE.md             ← + bloque "Protocolo de sesión + wiki vivo"

Flujo de ejecución

Paso 0 — Modo interactivo (OBLIGATORIO antes de generar)

Antes de crear ningún archivo, hacer estas preguntas al usuario. Esperar respuestas
antes de continuar.

Voy a generar el wiki de este proyecto. Necesito 5 respuestas rápidas:

1. ¿Quién va a usar esto además de ti? (ej: dev externo, cliente, equipo interno)
2. ¿Cuál es el flujo principal que debe poder hacer un usuario nuevo sin ayuda?
   (ej: "reservar un set", "crear un proyecto", "generar una factura")
3. ¿Hay algo en este proyecto que parece obvio pero no lo es? ¿Alguna trampa?
4. ¿Qué es lo que más cambia en este proyecto sprint a sprint?
5. ¿Tienes el ID del proyecto en Linear? (para conectar el wiki-sync)

Usar las respuestas para enriquecer el contenido. Si el usuario no tiene alguna
respuesta, marcar como TODO en el archivo correspondiente.

Paso 1 — Descubrir el repo

Leer en paralelo:

• package.json o equivalente para stack y scripts
• CLAUDE.md para contexto existente
• README.md si existe
• Estructura top-level
• lib/, src/, app/ — solo listar, no leer todo
• git log --oneline -10 para entender qué ha cambiado recientemente
• CHANGELOG.md o TODOS.md si existen

Nunca inventar datos. Si no se puede inferir algo, marcarlo TODO visible.

Paso 2 — Poblar archivos

index.md — Bienvenida (para humanos Y agentes)

# [Nombre del Proyecto] — Wiki

> Si eres nuevo en este proyecto, empieza por [onboarding.md](onboarding.md).
> Si eres el agente retomando sesión, lee esto y luego ve a [reference.md](reference.md).

## ¿Qué es esto?

[Descripción en 2-3 líneas. Qué problema resuelve, quién lo usa.]

## Mapa del proyecto

| Archivo | Para quién | Qué contiene |
|---------|-----------|--------------|
| [onboarding.md](onboarding.md) | Dev nuevo / cliente | Cómo arrancar desde cero |
| [architecture.md](architecture.md) | Dev / agente | Stack, capas, datos |
| [testing-guide.md](testing-guide.md) | QA / dev / cliente | Flujos a probar manualmente |
| [decisions.md](decisions.md) | Dev / agente | Por qué está hecho así |
| [changelog.md](changelog.md) | Todos | Qué cambió y cuándo |
| [workflows.md](workflows.md) | Agente | Flujos recurrentes |
| [reference.md](reference.md) | Agente | IDs, tokens, endpoints |
| [dont-touch.md](dont-touch.md) | Agente | Qué no tocar |
| [glossary.md](glossary.md) | Todos | Términos del dominio |

## Estado actual

- **Versión:** [x.x.x o TODO]
- **Deploy:** [URL o TODO]
- **Linear:** [link al proyecto o TODO]
- **Última actualización del wiki:** [fecha]

onboarding.md — Para humanos que arrancan desde cero

# Onboarding — [Nombre del Proyecto]

## Requisitos previos

- [ ] Node.js [versión]
- [ ] [Otras dependencias del proyecto]
- [ ] Acceso a: [Supabase / Airtable / etc.]
- [ ] Variables de entorno (ver sección abajo)

## Arrancar en local

```bash
git clone [repo]
cd [proyecto]
npm install
cp .env.example .env.local   # o pedir .env al equipo
npm run dev

Abrir: http://localhost:3000

Variables de entorno necesarias

Primer recorrido recomendado

Antes de tocar código, hacer este recorrido para entender el flujo principal:

1. [Paso 1 — ej: ir a /login y autenticarse]
2. [Paso 2 — ej: crear una reserva de prueba]
3. [Paso 3 — ej: verla en el panel de admin]

Estructura de carpetas (lo importante)

[Llenar con la estructura real del repo. Solo las carpetas que importan.]

Preguntas frecuentes de nuevos devs

P: ¿Por qué [algo que parece raro]?
R: [TODO — respuesta de la pregunta 3 del modo interactivo]

---

#### `testing-guide.md` — Flujos que un humano debe probar

Este es el archivo más importante para QA y para el cliente.

```markdown
# Testing Guide — [Nombre del Proyecto]

> Esta guía es para pruebas manuales. Para tests automáticos ver sección al final.

## Flujos críticos (probar en cada release)

### Flujo 1: [Nombre del flujo principal — ej: Reservar un set]

**Actor:** [Cliente / Admin / etc.]
**Precondición:** [ej: usuario autenticado, set disponible]

| # | Paso | Resultado esperado | Estado |
|---|------|--------------------|--------|
| 1 | [acción] | [qué debe pasar] | ⬜ |
| 2 | [acción] | [qué debe pasar] | ⬜ |
| 3 | [acción] | [qué debe pasar] | ⬜ |

**Casos edge a probar:**
- [ ] [ej: intentar reservar horario ya ocupado]
- [ ] [ej: cancelar a mitad del flujo]

---

### Flujo 2: [Siguiente flujo importante]

[mismo formato]

---

## Flujos de admin (probar con cuenta admin)

### [Flujo admin 1]
[mismo formato]

---

## Tests automáticos

```bash
npm run test:run   # todos los tests
npm test           # modo watch

Cobertura actual: [TODO — correr y pegar resultado]

Qué está cubierto con tests automáticos:

• [ej: lib/pricing.ts — lógica de precios]
• [ej: lib/db/bookings.ts — CRUD reservas]

Qué NO está cubierto (prueba manual obligatoria):

• [ej: flujo de Stripe en staging]
• [ej: envío de emails con Resend]

Ambiente de staging

[URL de staging o TODO]
Credenciales de prueba: [TODO — pedir al equipo]

---

#### `changelog.md` — Documento vivo

```markdown
# Changelog — [Nombre del Proyecto]

> Este archivo se actualiza al cerrar cada sesión de trabajo.
> Formato: fecha + qué cambió + quién lo pidió.

---

## [FECHA] — Inicialización del wiki

- Wiki instalado con wiki-init
- Secciones creadas: index, onboarding, architecture, testing-guide, decisions, changelog, glossary, workflows, reference, dont-touch
- **Solicitado por:** Gabriel / equipo GNB Labs

---

<!-- Agregar nuevas entradas arriba de esta línea -->

Regla para agregar entradas:

## [YYYY-MM-DD] — [Título corto del cambio]

### Qué cambió
- [cambio 1]
- [cambio 2]

### Por qué
[contexto breve — qué lo motivó, quién lo pidió]

### Archivos principales tocados
- `[archivo]` — [qué se hizo]

### Notas para el siguiente dev
[advertencias, TODOs pendientes, contexto que no está en el código]

architecture.md — Stack y estructura

# Arquitectura — [Nombre del Proyecto]

## Stack

| Capa | Tecnología | Por qué |
|------|-----------|---------|
| Frontend | [framework] | [TODO] |
| Auth | [solución] | [TODO] |
| Base de datos | [DB] | [TODO] |
| Pagos | [Stripe / etc.] | [TODO] |
| Email | [Resend / etc.] | [TODO] |
| Hosting | [Vercel / etc.] | [TODO] |

## Estructura de carpetas

[Llenar con estructura real]

## Cómo fluyen los datos

[Diagrama texto o descripción del flujo principal de datos]

## Auth

[Cómo funciona la autenticación — sesiones, tokens, roles]

## Variables de entorno

Ver [onboarding.md](onboarding.md) para la tabla completa.

decisions.md — Por qué está hecho así

# Decisiones técnicas — [Nombre del Proyecto]

> Cada decisión importante merece una entrada aquí.
> Formato: contexto → opciones consideradas → decisión → por qué.

---

<!-- Ejemplo comentado — descomentar y llenar con decisiones reales -->
<!--
## [Fecha] — [Título de la decisión]

**Contexto:** [qué problema resolvía]
**Opciones consideradas:** [A, B, C]
**Decisión:** [qué se eligió]
**Por qué:** [razón real, no la obvia]
**Aplica a:** [qué partes del código afecta]
-->

glossary.md, dont-touch.md, workflows.md, reference.md

Seguir el mismo patrón que la versión anterior del skill, pero enriquecidos con
lo que se obtuvo del modo interactivo.

dont-touch.md — agregar siempre:

## Git / deploy
- NUNCA usar `Co-Authored-By: Claude` en commits (Vercel bloquea deploys).
- No force-push a `main`.
- No deploys sin pedirlo explícitamente.

workflows.md — agregar siempre:

## Delegar acciones a humanos (REGLA)

Si necesito que una persona haga algo, la única forma de que se acuerde es
creando una tarea en Linear. Nunca dejarlo solo en el chat.

### Cuándo NO crear tarea
- Pregunta de aclaración → solo chat.
- Acción que Claude ejecuta solo → ejecutar y reportar.
- Info de referencia → wiki/reference.md, no tarea.

## Actualizar el wiki (REGLA)

Al cerrar una sesión donde se hicieron cambios importantes:
1. Agregar entrada en `wiki/changelog.md`
2. Actualizar el archivo del wiki que corresponda (architecture, decisions, etc.)
3. Correr `node scripts/wiki-sync.mjs` para subir a Linear

Paso 3 — Crear scripts/wiki-sync.mjs

Este script lee todos los archivos de wiki/ y los sube a Linear como
"resources" (attachments) del proyecto. Se corre después de actualizar el wiki.

// scripts/wiki-sync.mjs
// Sube los archivos de wiki/ a Linear como resources del proyecto.
// Uso: node scripts/wiki-sync.mjs
// Requiere: LINEAR_API_KEY y LINEAR_PROJECT_ID en .env o .env.local

import { readFileSync, readdirSync } from "fs";
import path from "path";
import { fileURLToPath } from "url";

const __dirname = path.dirname(fileURLToPath(import.meta.url));
const ROOT = path.join(__dirname, "..");

// Cargar env manualmente (sin dotenv para evitar dependencia)
function loadEnv() {
  const envFiles = [".env.local", ".env"];
  for (const file of envFiles) {
    try {
      const content = readFileSync(path.join(ROOT, file), "utf-8");
      for (const line of content.split("\n")) {
        const [key, ...vals] = line.split("=");
        if (key && vals.length) process.env[key.trim()] = vals.join("=").trim();
      }
      break;
    } catch {}
  }
}

loadEnv();

const LINEAR_API_KEY = process.env.LINEAR_API_KEY;
const LINEAR_PROJECT_ID = process.env.LINEAR_PROJECT_ID;

if (!LINEAR_API_KEY || !LINEAR_PROJECT_ID) {
  console.error("❌ Faltan LINEAR_API_KEY o LINEAR_PROJECT_ID en .env");
  process.exit(1);
}

async function linearQuery(query, variables = {}) {
  const res = await fetch("https://api.linear.app/graphql", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: LINEAR_API_KEY,
    },
    body: JSON.stringify({ query, variables }),
  });
  return res.json();
}

async function syncWiki() {
  const wikiDir = path.join(ROOT, "wiki");
  const files = readdirSync(wikiDir).filter((f) => f.endsWith(".md")).sort();

  console.log(`📚 Sincronizando ${files.length} archivos a Linear...`);

  for (const file of files) {
    const content = readFileSync(path.join(wikiDir, file), "utf-8");
    const title = content.split("\n").find((l) => l.startsWith("# "))?.replace("# ", "") ?? file;
    const slug = file.replace(".md", "");

    // Buscar si ya existe un document con este slug en el proyecto
    const listResult = await linearQuery(`
      query($projectId: String!) {
        project(id: $projectId) {
          documents { nodes { id title content } }
        }
      }
    `, { projectId: LINEAR_PROJECT_ID });

    const existing = listResult?.data?.project?.documents?.nodes?.find(
      (d) => d.title === title || d.title === slug
    );

    if (existing) {
      // Actualizar
      await linearQuery(`
        mutation($id: String!, $input: DocumentUpdateInput!) {
          documentUpdate(id: $id, input: $input) { success }
        }
      `, { id: existing.id, input: { title, content } });
      console.log(`  ✅ Actualizado: ${title}`);
    } else {
      // Crear
      await linearQuery(`
        mutation($input: DocumentCreateInput!) {
          documentCreate(input: $input) { success document { id } }
        }
      `, { input: { title, content, projectId: LINEAR_PROJECT_ID } });
      console.log(`  ✨ Creado: ${title}`);
    }
  }

  console.log("\n✅ Wiki sincronizado a Linear.");
  console.log(`   Ver en: https://linear.app/[tu-org]/project/${LINEAR_PROJECT_ID}`);
}

syncWiki().catch(console.error);

Importante al crear este archivo:

• Verificar que scripts/ exista; si no, crearlo
• Agregar LINEAR_PROJECT_ID= al .env.example si existe
• Mencionar al usuario que debe agregar LINEAR_PROJECT_ID al .env.local

Paso 4 — .gitignore

Agregar al final:

# Wiki raw inbox (notas crudas, privadas)
raw/*
!raw/README.md

Paso 5 — CLAUDE.md

Insertar este bloque al principio (después del H1):

## Wiki del proyecto (LEER PRIMERO)

1. **Al inicio de cada sesión:** leer `wiki/index.md`.
2. **Si `raw/` tiene archivos nuevos:** revisarlos, extraer lo útil, proponer
   actualizar `wiki/`. No procesar sin avisar.
3. **Al cerrar sesión con cambios importantes:**
   - Agregar entrada en `wiki/changelog.md`
   - Actualizar el archivo wiki que corresponda
   - Correr `node scripts/wiki-sync.mjs` (si hay LINEAR_PROJECT_ID configurado)
4. **Nunca editar `wiki/` durante trabajo normal.** Solo al actualizar explícitamente.
5. **División con auto-memory:** `wiki/` = conocimiento del proyecto.
   Auto-memory global = preferencias del usuario. No duplicar.

Si ya existe un bloque similar, NO sobreescribir — preguntar al usuario.

Paso 6 — Reporte final

Mostrar al usuario:

✅ Wiki instalado en [repo]

Archivos creados:
  wiki/index.md
  wiki/onboarding.md
  wiki/architecture.md
  wiki/testing-guide.md
  wiki/decisions.md
  wiki/changelog.md
  wiki/dont-touch.md
  wiki/glossary.md
  wiki/workflows.md
  wiki/reference.md
  raw/README.md
  scripts/wiki-sync.mjs

TODOs pendientes (necesito tu ayuda para completarlos):
  [lista de TODOs específicos que quedaron en los archivos]

Próximos pasos:
1. Agrega LINEAR_PROJECT_ID=[id] a tu .env.local
2. Corre `node scripts/wiki-sync.mjs` para subir el wiki a Linear
3. Revisa wiki/testing-guide.md y completa los flujos de prueba
4. Revisa los TODOs de onboarding.md con las variables de entorno reales

Principios

• No inventar. Si un dato no está en el repo, marcarlo TODO visible.
• Humanos primero. onboarding.md y testing-guide.md son para personas,
  no para el agente. Lenguaje claro, pasos concretos.
• Documento vivo. El valor real es que se actualice. El protocolo en CLAUDE.md
  es lo que lo mantiene vivo.
• Linear como fuente de verdad externa. El wiki vive en el repo, Linear es
  el espejo accesible para clientes y equipo sin acceso al código.
• No duplicar con auto-memory. Auto-memory = preferencias del usuario.
  Wiki = conocimiento del repo.
• No romper nada existente. Si hay CLAUDE.md con protocolo similar, NO
  sobreescribir — preguntar.

Referencia canónica

El wiki más maduro vive en c:\Users\mnbon\gabrielneuman\gnbsite\wiki\.
Cuando tengas dudas de formato, abrirlo y copiar estructura.