Connect your first engine in under 60 seconds

./getting-started
1

Connecting an AI engine (Claude Code, Codex, or Gemini) to PaellaDoc takes under 60 seconds: pick the engine, paste your auth method, and run the smoke test.

🇬🇧 English

PaellaDoc orchestrates engines. It doesn’t generate code itself. So before you can do anything, you need at least one engine connected. The Capa 0 in onboarding is a hard gate: no valid engine, no access. Honest, not annoying.

Recommended path: Claude Code CLI (subscription-based)

  1. Install Claude Code if you haven’t: https://claude.com/claude-code
  2. Sign in once with your Anthropic subscription: claude login
  3. Open PaellaDoc → onboarding → Engine step
  4. PaellaDoc auto-detects claude in your PATH and shows it as connected :white_check_mark:

Why this is the recommended path: no per-action cost banner, no rate-limit UI noise. You pay your flat subscription to Anthropic and PaellaDoc just uses it. If the CLI saturates, PaellaDoc propagates the raw error — no fake friendly messages.

Alternative: API key

If you don’t want the subscription, you can paste an API key (Anthropic, OpenAI for Codex, Google for Gemini) in the Engine step. Same orchestration, different billing model — you pay per token to the provider directly.

Multi-engine

You can connect more than one. Then per user story you pick which engine runs it. Useful for: A/B comparison, fallback if one provider has an outage, splitting load.

Common issues

  • “Engine detector returns empty”: PaellaDoc looks for the binary in your PATH. Verify which claude returns a path. If you use nvm/asdf/pyenv-like wrappers, the PATH PaellaDoc sees might differ from your terminal.
  • “It connects but never finishes”: usually means the CLI is interactively prompting for something (login, consent, MFA). Run the CLI manually once to clear those.

For any other engine setup question → category ./engines.

🇪🇸 Español

PaellaDoc orquesta motores. No genera código por sí mismo. Así que antes de hacer nada necesitas al menos un motor conectado. La Capa 0 del onboarding es un hard gate: sin motor válido, no hay acceso. Honesto, no molesto.

Camino recomendado: Claude Code CLI (con suscripción)

  1. Instala Claude Code si no lo tienes: https://claude.com/claude-code
  2. Loguéate una vez con tu suscripción de Anthropic: claude login
  3. Abre PaellaDoc → onboarding → paso Engine
  4. PaellaDoc detecta automáticamente claude en tu PATH y lo muestra como conectado :white_check_mark:

Por qué este es el camino recomendado: sin banner de coste por acción, sin ruido de rate-limit en la UI. Pagas tu suscripción plana a Anthropic y PaellaDoc simplemente la usa. Si la CLI satura, PaellaDoc propaga el error crudo — sin mensajes amables falsos.

Alternativa: API key

Si no quieres la suscripción, puedes pegar una API key (Anthropic, OpenAI para Codex, Google para Gemini) en el paso Engine. Misma orquestación, modelo de facturación distinto — pagas por token al proveedor directamente.

Multi-motor

Puedes conectar más de uno. Después, por user story, eliges qué motor la ejecuta. Útil para: comparación A/B, fallback si un proveedor tiene caída, repartir carga.

Problemas comunes

  • “El detector de motores devuelve vacío”: PaellaDoc busca el binario en tu PATH. Verifica que which claude devuelve una ruta. Si usas wrappers tipo nvm/asdf/pyenv, el PATH que PaellaDoc ve puede diferir del de tu terminal.
  • “Conecta pero nunca termina”: normalmente significa que la CLI está pidiéndote algo interactivamente (login, consent, MFA). Ejecuta la CLI manualmente una vez para limpiar eso.

Cualquier otra duda sobre setup de motores → categoría ./engines.