Comandos, archivos y configuración.

Un comando va en la terminal.

Una terminal es la ventana donde escribe instrucciones para su computadora. En Visual Studio Code, primero abra su carpeta supastack usando Archivo → Abrir carpeta, luego seleccione Terminal → Nueva terminal. La nueva terminal comienza en esa carpeta. En Windows, elija PowerShell usando el menú al lado del botón + del terminal. Utilice bloques de macOS/Linux en una terminal macOS o Linux.

Pegue solo el contenido de un bloque de comando, un comando a la vez, y presione Entrar. No pegue las comillas invertidas de Markdown circundantes, un mensaje como PS C:\... o una salida de ejemplo. Las líneas que comienzan con # son explicaciones; no ejecutan nada. Espere a que finalice cada comando de instalación antes de ingresar el siguiente comando. Un comando del servidor continúa ejecutándose y no devuelve un mensaje nuevo hasta que lo detiene.

Comprueba qué carpeta está usando el terminal

Raíz del repositorio significa la carpeta supastack de nivel superior que contiene package.json, pnpm-workspace.yaml, aplicaciones y paquetes. A menos que un paso indique lo contrario, ejecute los comandos allí. El siguiente comando imprime la carpeta actual; la lista de archivos debería mostrar package.json. En Windows PowerShell pwd y ls también funcionan.

Si el listado muestra solo el contenido de apps/desktop, escriba cd ../.. y presione Enter para volver a la raíz. Si muestra su carpeta personal, escriba cd seguido de un espacio y la ruta completa a su clon, entre comillas si contiene espacios. Normalmente es más fácil abrir la carpeta del proyecto en el editor y crear una terminal nueva.

pwd
ls

La configuración va en un archivo, no en la terminal.

Un bloque como AI_PROVIDER=fake es texto de configuración. Abra el archivo .env nombrado en el editor, busque la línea que comienza con AI_PROVIDER=, reemplace su valor y guárdelo con Ctrl + S (Comando + S en macOS). Cada configuración ocupa una línea en formato KEY=value. No agregue comillas invertidas de Markdown. Evite copias duplicadas de la misma clave en un archivo.

Use el .env de la raíz para los comandos de migración de la base de datos y apps/web/.env.local para el backend Web; en un checkout solo de Desktop, ese archivo pertenece al repositorio de backend separado. El shell de escritorio no lee archivos .env: SUPASTACK_APP_URL es una configuración de entorno de terminal que pasa en la línea de comandos al iniciarlo, no una configuración almacenada en un archivo. Mantenga el archivo de ejemplo sin cambios como referencia.

Los archivos cuyos nombres comienzan con un punto pueden estar ocultos en su administrador de archivos; El Explorador del editor los muestra. Asegúrese de que el nombre del archivo sea exactamente .env.local, no .env.local.txt. Estos archivos locales pueden contener contraseñas y están excluidos de Git; no los cargue ni pegue su contenido en mensajes de soporte.

• Encuentre el significado de cada configuración

Mantenga el comando dev en ejecución; use otra terminal para los comandos

El comando de desarrollo de escritorio compila el shell de Rust y abre la ventana mientras se ejecuta. Deje su terminal abierta mientras prueba la ventana. Un comando de servidor sigue ejecutándose y no devuelve un nuevo prompt hasta que lo detiene.

Para ejecutar otro comando mientras el servidor está activo, seleccione Terminal → Nueva Terminal en el editor. La nueva terminal es una ventana separada del mismo proyecto. Para detener el servidor, seleccione su terminal y presione Ctrl + C una vez. En Windows, si se le solicita Terminar el trabajo por lotes, escriba Y y presione Entrar. Espere el mensaje normal antes de iniciarlo nuevamente.

Después de cambiar la configuración del shell, detenga el comando de escritorio con Ctrl + C y ejecútelo de nuevo. El núcleo de Rust se recompila en cada inicio; cambiar SUPASTACK_APP_URL significa pasar el nuevo valor en la siguiente ejecución, no editar un archivo guardado.

corepack pnpm --filter @supastack/desktop dev

Leer un fallo y pedir ayuda útil

Si una instalación devuelve un texto de error rojo, deténgase en ese paso. Lea el primer error en lugar de continuar iniciando la aplicación. El comando no encontrado generalmente significa que falta una herramienta; no package.json normalmente significa la carpeta incorrecta; ECONNREFUSED generalmente significa que un servidor o base de datos requerido no se está ejecutando; EADDRINUSE significa que otro proceso ya utiliza el puerto.

Cuando solicite ayuda, incluya su sistema operativo, la guía URL y el número de paso, el comando exacto que ingresó y el primer mensaje de error. Elimine contraseñas, claves API, tokens y la parte de contraseña de cualquier base de datos URL. No envíe sus archivos .env. Una captura de pantalla del error puede ayudar, pero el texto copiable es más fácil de diagnosticar.

• Solucionar un error de configuración específico