# INSTALL — pi-new-project

Instalación del paquete/skill `new-project` en pi, en este ordenador o en
cualquier otro.

Repositorios:

- **Distribución** (para usarlo): <https://git.sargatxet.cloud/sargatxet/pi-new-project-dist>.
  Solo contiene lo que pi necesita: `package.json`, `LICENSE`, `extensions/`,
  `skills/` y un `README.md` mínimo. Se genera con `scripts/publicar-dist.sh`.
- **Desarrollo** (para modificarlo): <https://git.sargatxet.cloud/sargatxet/pi-new-project>.

## 1. Requisitos

| Componente | Versión mínima | Notas |
| --- | --- | --- |
| pi | 1.3.0 | Hace falta soporte de skills y de paquetes (`pi install`). |
| bash | 4.0 | El script usa arrays y `${var//}`. |
| git | cualquiera | Opcional: `--git` y autor por defecto. |
| shellcheck | opcional | Para validar el script (`shellcheck new-project.sh`). |

## 2. Opción A — instalarlo como paquete de pi desde git (recomendado)

pi clona el repositorio de distribución y lo instala directamente:

```bash
pi install git:git.sargatxet.cloud/sargatxet/pi-new-project-dist
# equivalente, con la URL completa:
pi install https://git.sargatxet.cloud/sargatxet/pi-new-project-dist
```

Para fijar una versión concreta, añade una etiqueta (`v0.3.1`, …) o un commit:
`pi install git:git.sargatxet.cloud/sargatxet/pi-new-project-dist@<etiqueta-o-commit>`.
Añade `-l` (`--local`) para declararlo solo en el proyecto actual
(`.pi/settings.json`) en lugar de en `~/.pi/agent/settings.json`.

Comprueba con `pi list` y arranca pi: la skill aparecerá como `new-project` y
estará disponible la orden `/modelo-proyecto`.
Para una prueba puntual sin instalarlo:
`pi -e git:git.sargatxet.cloud/sargatxet/pi-new-project-dist`.

> Si ya lo tenías instalado desde el repositorio de desarrollo
> (`git:git.sargatxet.cloud/sargatxet/pi-new-project`), pi lo considera otro
> paquete: quítalo antes con `pi remove git:git.sargatxet.cloud/sargatxet/pi-new-project`
> para que la skill no se cargue dos veces.

### Desde una copia local del repositorio de desarrollo

Si vas a revisarlo o modificarlo:

```bash
git clone https://git.sargatxet.cloud/sargatxet/pi-new-project.git
pi install ./pi-new-project
```

Una instalación local se carga desde ese directorio sin copiarlo: los cambios
(o un `git pull`) se aplican en la siguiente sesión de pi.

## 3. Opción B — copiar la skill

Copia el directorio de la skill a una de las rutas que pi descubre:

```bash
mkdir -p ~/.agents/skills
cp -r pi-new-project/skills/new-project ~/.agents/skills/
```

o enlázalo para mantenerlo actualizado con el repositorio:

```bash
ln -s "$PWD/pi-new-project/skills/new-project" ~/.agents/skills/new-project
```

Rutas equivalentes: `~/.pi/agent/skills/` y, por proyecto, `.agents/skills/`.

En estos ejemplos, `pi-new-project/` es una copia del repositorio obtenida con
`git clone https://git.sargatxet.cloud/sargatxet/pi-new-project-dist.git pi-new-project`
(o del de desarrollo, `.../pi-new-project.git`; ambos tienen `skills/` y `extensions/`).

La skill sola no incluye la orden `/modelo-proyecto` ni la herramienta
`elegir_modelo_proyecto`; cópialas también (o la skill usará el plan B,
`pi --list-models` + `--modelo`):

```bash
mkdir -p ~/.pi/agent/extensions
cp pi-new-project/extensions/modelo-proyecto.ts ~/.pi/agent/extensions/
```

## 4. Opción C — exportar a otro ordenador sin acceso al repositorio

Si el ordenador destino tiene acceso a
<https://git.sargatxet.cloud/sargatxet/pi-new-project-dist>, basta con la opción A.
Si no, copia el directorio (mejor el de distribución, que solo trae lo necesario);
no tiene dependencias.

```bash
# en el ordenador origen
tar -czf pi-new-project-0.3.1.tar.gz pi-new-project/

# en el ordenador destino
tar -xzf pi-new-project-0.3.1.tar.gz
pi install ./pi-new-project        # o la opción B
```


## 5. Verificación

```bash
bash -n pi-new-project/skills/new-project/scripts/new-project.sh
pi-new-project/skills/new-project/scripts/new-project.sh --dry-run --nombre Demo /tmp/demo

# prueba real en un directorio temporal
pi-new-project/skills/new-project/scripts/new-project.sh \
  --nombre Demo --descripcion "Proyecto de prueba" --git /tmp/demo
ls -A /tmp/demo
```

Deben aparecer `AGENTS.md`, `README.md`, `CHANGELOG.md`, `TODO.md`, `INSTALL.md`
y `.gitignore`, sin marcadores `{{...}}` pendientes.

Modelo por defecto:

```bash
pi-new-project/skills/new-project/scripts/new-project.sh \
  --nombre Demo --modelo anthropic/claude-sonnet-4-5 /tmp/demo2
cat /tmp/demo2/.pi/settings.json
```

En pi, dentro de `/tmp/demo2`, `/modelo-proyecto` debe mostrar el selector de
modelos y actualizar `.pi/settings.json`.

## 6. Actualización

```bash
pi update --extensions      # instalado desde git: actualiza el clon gestionado por pi

# instalado desde una copia local o copiado (opción B):
cd pi-new-project && git pull
```

Si se instaló con una etiqueta o un commit fijo (`@<ref>`), `pi update` no lo
mueve: reinstala con la nueva referencia.

## 7. Desinstalación

```bash
pi remove git:git.sargatxet.cloud/sargatxet/pi-new-project-dist  # paquete desde git
pi remove git:git.sargatxet.cloud/sargatxet/pi-new-project       # instalaciones antiguas
pi remove ./pi-new-project          # paquete desde una copia local
rm -rf ~/.agents/skills/new-project # si se copió o enlazó
rm -f ~/.pi/agent/extensions/modelo-proyecto.ts
```

La skill no deja estado propio: no hay caché ni configuración que limpiar.

## Publicar una versión (mantenedores)

El repositorio de distribución se genera desde el de desarrollo; no se edita a
mano. Con los cambios ya commiteados y la versión subida en `package.json` y
`CHANGELOG.md`:

```bash
scripts/publicar-dist.sh --dry-run   # prepara y muestra el contenido sin subir nada
scripts/publicar-dist.sh             # commit + etiqueta vX.Y.Z en pi-new-project-dist
```

El script toma el contenido de `HEAD` (no del directorio de trabajo), se niega a
publicar si hay cambios sin commitear en lo que se publica o si la etiqueta ya
existe, y necesita permiso de escritura en el repositorio de distribución.

## 8. Resolución de problemas

| Síntoma | Causa probable | Solución |
| --- | --- | --- |
| La skill no aparece | Ruta no descubierta | Comprueba la ruta con `pi list` o colócala en `~/.agents/skills/`. |
| `no encuentro las plantillas` | Falta `templates/` | Reinstala el paquete completo, no solo el script. |
| `no puedo deducir el nombre` | Destino `.` o `/` | Pasa `--nombre`. |
| No sobreescribe mis ficheros | Protección por defecto | Usa `--force` tras revisar `--dry-run`. |
| El proyecto no arranca con su modelo | Proyecto no confiado: pi ignora `.pi/settings.json` | Ejecuta `/trust` en el proyecto. |
| `/modelo-proyecto` no existe | Solo se copió la skill | Instala el paquete o copia `extensions/modelo-proyecto.ts`. |
| El selector sale vacío | Ningún proveedor con credenciales | `/login` o configura la API key del proveedor. |