Manual

El Manual es el complemento extenso de la referencia CLI. La referencia es la búsqueda rápida (“¿qué hace --enable-tester?”); el manual es la inmersión profunda (“¿cuándo activar el rol tester aporta valor real, cuándo es exceso, y cómo interactúa con la metodología TDD?”).

Cada página sigue la misma estructura canónica para que siempre sepas dónde encontrar la información:

• Qué hace — comportamiento detallado, en prosa clara.
• Cuándo usarlo — escenarios concretos donde aporta, cada uno con un ejemplo de una línea.
• Cuándo NO usarlo — escenarios donde es overhead, ruido o trampa, con la razón.
• Opciones — cada flag con default, cuándo activarlo y cómo interactúa con el resto.
• Ejemplos — 3-5 recetas representativas (uso típico, CI/automatización, avanzado).
• Cómo funciona por dentro — 2-3 párrafos de razonamiento para quien quiere el “porqué del porqué”.
• Relacionado — enlaces al resto del manual.

Por dónde empezar

Si nunca has usado Karajan, primero haz el Primeros Pasos → Inicio Rápido. El manual da por hecho que ya tienes el CLI instalado y has lanzado al menos un pipeline.

A partir de ahí, qué leer depende de lo que quieras hacer:

Objetivo	Empieza aquí
Entender kj run de cabo a rabo	kj run y Roles del pipeline
Generar y ejecutar un plan	kj plan
Auditar un codebase	kj audit y Dimensiones del audit
Preparar el entorno	kj init → kj doctor → kj install-tools
Elegir la herramienta externa correcta	Herramientas externas
Ejecutar un rol aislado	kj code, kj review, kj scan, kj triage

Secciones

• Comandos — una página por comando kj con tratamiento completo. Mira la barra lateral bajo “Manual” para ver la lista entera.
• Roles del pipeline — los 24 roles que componen kj run: cuándo se activa cada uno, por qué existe, cuándo sobra. Leer →
• Dimensiones del audit — las seis dimensiones que evalúa kj audit (security, codeQuality, performance, architecture, testing, accessibility). Leer →
• Herramientas externas — las cinco herramientas no bundleadas con las que integra Karajan (Sonar, OSV-Scanner, Semgrep, Lighthouse, Docker): qué aporta cada una, cómo las invoca Karajan, qué pasa cuando faltan. Leer →

Orden de lectura sugerido

“Quiero empezar a lanzar pipelines reales hoy”:

1. kj init
2. kj doctor → kj install-tools
3. kj run — lee “Qué hace”, ojea las opciones, lanza una task pequeña.
4. Vuelve a Roles del pipeline la primera vez que te preguntes “¿qué es solomon y por qué se está disparando?”

“Quiero entender el diseño”:

1. Roles del pipeline — el corazón del sistema.
2. kj run → sección “Cómo funciona por dentro” al final.
3. Dimensiones del audit — qué cuenta como finding y por qué.

“Estoy montando automatización CI/CD”:

1. kj run — céntrate en --yes, --methodology, --max-iterations, --auto-pr.
2. kj plan y kj audit — ambos tienen flag --deterministic-only muy útil.
3. kj install-tools — --yes --only <subset> para provisionado no interactivo.

---

El manual se actualiza junto con cada release minor. Si encuentras una discrepancia entre el manual y lo que hace kj en la versión que tienes, por favor abre una issue. El pie de cada página indica la versión contra la que se revisó por última vez.