> ## Documentation Index
> Fetch the complete documentation index at: https://docs.delixon.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Project lifecycle

> Estados Discovered / Active / Paused / Archived y como Nexenv los maneja

Nexenv modela cada proyecto como una maquina de estados con **cuatro
valores**. La separacion es deliberada: cada estado responde a un caso
de uso real y distinto, y Nexenv adapta lo que ofrece segun el estado
actual.

## Los 4 estados

* **Discovered**: Nexenv encontro el proyecto en disco (por
  `nexenv inspect <path>` o por escaneo recursivo de `~/dev`) pero el
  usuario todavia no lo "adopto". No corre health checks, no toca env
  vars, no instala dependencias. Solo lo lista con badge **Discovered**.
* **Active**: el usuario lo activo y el doctor flow paso. Es el estado
  por defecto para proyectos nuevos. Run scripts, sidebar git, watchers
  de env vars, indexador on-demand, todo disponible.
* **Paused**: pausa consciente. El proyecto sigue ahi pero queda oculto
  del dashboard activo (visible con el filtro **Paused**). No consume
  recursos en background.
* **Archived**: terminal. El usuario lo "cerro" porque ya no lo usa.
  Queda fuera del listado por defecto, recuperable solo con
  **Unarchive** explicito. Pensado para proyectos terminados que se
  quieren conservar para consulta pero ya no estorbar en el dia a dia.

## Transiciones permitidas

| Desde      | Hacia    | Disparador tipico                                                   |
| ---------- | -------- | ------------------------------------------------------------------- |
| Discovered | Active   | El usuario lo adopta (workbench/wizard) y el doctor flow pasa.      |
| Discovered | Archived | El usuario decide descartar sin entrar.                             |
| Active     | Paused   | `nexenv project pause <name>` o "Pausar" desde la tarjeta.          |
| Active     | Archived | `nexenv project archive <name>` o "Archivar" desde la tarjeta.      |
| Paused     | Active   | `nexenv project resume <name>` o "Reactivar".                       |
| Paused     | Archived | `nexenv project archive <name>` (tambien desde Paused).             |
| Archived   | Active   | `nexenv project unarchive <name>` o "Desarchivar". Re-corre doctor. |

**No permitidas** (devuelven error claro): `Archived -> Paused`,
`Archived -> Discovered`, `Paused -> Discovered`, `Active -> Discovered`,
`Discovered -> Paused`. Si quieres pausar un Archived, primero
desarchivar (reactiva con doctor) y despues pausar — es deliberado.

## Filtros por estado en el dashboard

El dashboard tiene una fila de filtros (chips) que controla que
proyectos se muestran:

* **En uso** (default): Active + Discovered. Lo que normalmente quieres ver.
* **Activos**: solo Active.
* **Descubiertos**: solo Discovered.
* **Pausados**: solo Paused.
* **Archivados**: solo Archived.
* **Todos**: los 4 estados.

El estado se preserva durante la sesion (al cambiar de pestania vuelves
al mismo filtro).

## CLI equivalente

Todo lo que hace la GUI tiene paridad en `nexenv`:

```bash theme={null}
# Listar (default: oculta Paused y Archived)
nexenv list

# Listar filtrando por estado
nexenv list --state active
nexenv list --state paused
nexenv list --state archived
nexenv list --state discovered
nexenv list --state all       # los 4 estados

# Transiciones
nexenv project pause <name>
nexenv project resume <name>
nexenv project archive <name>           # pide confirmacion
nexenv project archive <name> --yes     # modo script
nexenv project unarchive <name>
```

Las reglas de transicion viven en el core Rust
(`core/project/state::validate_transition`) y se aplican tanto desde
GUI como CLI. Si invocas una transicion no permitida, recibes el
mismo mensaje en ambos lados.

## Migracion desde 1.3.x

Hasta 1.3.x el modelo tenia 3 estados: `Active`, `Idle`, `Archived`.
En 1.4.0 (Tema 8.5):

* **`Idle` -> `Paused`**: renombrado para alinearse con la convencion
  estandar (GitHub, Linear, etc.) y para distinguir mejor de "Archived".
* **`Discovered` aniadido**: cuarto estado nuevo, prerequisito para el
  flujo de auto-scan que Nexenv puede ejecutar al arrancar.

La migracion SQL `005_lifecycle_state.sql` reescribe los datos
existentes (`idle` -> `paused`) sin perdida de informacion. No hace
falta accion manual del usuario.

## Doctor flow

Las transiciones a `Active` (desde Discovered, Paused o Archived) se
hacen pasar por **doctor flow**: chequeos no destructivos de
dependencias instaladas, env vars declaradas vs `.env` en disco,
runtimes correctos. Si algo no cuadra, doctor reporta y deja al usuario
decidir si "Activate anyway" (con warnings registrados) o "Fix issues
first". Doctor **nunca** ejecuta scripts del proyecto.