## Projects: apps, analysis y vaults bajo un tema comun

Un project agrupa apps, analyses y vaults relacionados. Vive en `projects/{nombre}/` con esta estructura:

```
projects/{nombre}/
  project.md                    # Frontmatter obligatorio (name, description, tags)
  apps/                         # Apps del proyecto (cada una con app.md)
    {app_name}/
      app.md
      ...
  analysis/                     # Analyses del proyecto (cada uno con analysis.md)
    {analysis_name}/
      analysis.md
      .venv/
      notebooks/
      run-jupyter-lab.sh
      ...
  vaults/                       # Datos del proyecto
    vault.yaml                  # Manifest de vaults (nombre, descripcion, path, tags)
    {vault_name} -> /abs/path   # Symlinks a directorios reales de datos
```

### Reglas

- `project.md` sigue el template de `docs/templates/project.md` — campos: `name`, `description`, `tags`, `repo_url`
- `analysis.md` sigue el template de `docs/templates/analysis.md` — `dir_path` debe apuntar a `projects/{nombre}/analysis/{tema}/`
- `vault.yaml` lista los vaults con nombre, descripcion, path absoluto y tags
- Los vaults reales viven fuera del repo (ej: `~/vaults/{nombre}/`) con symlinks en el proyecto
- `fn index` escanea `projects/*/` y setea `project_id` automaticamente en apps, analyses y vaults

### Cada project es su propio repo Gitea (sub-repo)

Desde 2026-06-05 cada `projects/<nombre>/` es un **repo Gitea independiente** `dataforge/<nombre>` (branch `master`), igual que las apps y los analyses. El repo del project versiona **solo las docs de nivel-project** (`project.md`, `CONVENTIONS.md` y demás `.md`/`.claude/` propios del project). El contenido de los hijos NO se versiona aquí: cada `apps/<app>/` y cada `analysis/<a>/` es su propio sub-repo Gitea y queda excluido por el `.gitignore` del project:

```gitignore
apps/*/
analysis/*/
vaults/*
!vaults/.gitkeep
```

- **Crear el repo del project**: `ensure_repo_synced_bash_infra projects/<nombre> dataforge <nombre> master "init: project <nombre>"` (necesita `GITEA_URL` + `GITEA_TOKEN`; el token está en `pass gitea/dataforge-git-token`). Crear el `.gitignore` de arriba ANTES, para no trackear el contenido de los sub-repos hijos.
- **Push/pull**: `/full-git-push` y `/full-git-pull` ya lo manejan automáticamente — `discover_git_repos_bash_infra` descubre cualquier `.git` bajo `fn_registry`, incluidos los projects.
- **`repo_url`** en `project.md` apunta al repo del project; los `repo_url` de cada app viven en su `app.md`. Así el project "referencia" sus sub-repos sin git submodules (KISS).
- El repo padre `fn_registry` sigue ignorando `projects/*/` entero (regla `apps_subrepo.md`): nunca trackea contenido de projects.
- Estado actual: `dataforge/web_scraping`, `dataforge/fn_monitoring`, `dataforge/message_bus`.
- Apps y analyses sueltos (sin proyecto) siguen en `apps/` y `analysis/` en la raiz

### Raiz vs proyecto

| Ubicacion | Para que |
|-----------|---------|
| `apps/` | Apps independientes que no pertenecen a ningun proyecto |
| `analysis/` | Analyses independientes |
| `projects/{nombre}/apps/` | Apps de un proyecto — `project_id` se setea automaticamente |
| `projects/{nombre}/analysis/` | Analyses de un proyecto — `project_id` se setea automaticamente |

### Crear un proyecto nuevo

```bash
# 1. Crear estructura
mkdir -p projects/{nombre}/{apps,analysis,vaults}

# 2. Crear project.md con frontmatter
fn add -k project  # genera template

# 3. Crear vault (datos fuera del repo, symlink dentro)
mkdir -p ~/vaults/{vault_name}/{raw,processed,exports}
ln -s ~/vaults/{vault_name} projects/{nombre}/vaults/{vault_name}
# Crear vault.yaml con la entrada

# 4. Crear analysis dentro del proyecto (un solo comando; ya indexa)
fn run init_jupyter_analysis --project {nombre} {nombre_analysis} --desc "..." [paquetes...]

# 5. Verificar
fn show {nombre}  # verifica el project y sus componentes

# NUNCA: crear el analisis en analysis/ y luego mv al proyecto.
# Al mover se rompe el .venv (paths hardcodeados en activate).
# Si ya te paso: cd projects/{nombre}/analysis/{tema} && rm -rf .venv && uv sync
```

### Consultas utiles

```sql
-- Listar proyectos
SELECT id, description FROM projects;

-- Analysis de un proyecto
SELECT id, name, dir_path FROM analysis WHERE project_id = 'app_turismo';

-- Vaults de un proyecto
SELECT id, name, path, symlink FROM vaults WHERE project_id = 'app_turismo';

-- Apps de un proyecto
SELECT id, name, dir_path FROM apps WHERE project_id = 'app_turismo';

-- Todo lo que pertenece a un proyecto
SELECT 'analysis' as tipo, id, name FROM analysis WHERE project_id = ?
UNION ALL
SELECT 'vault', id, name FROM vaults WHERE project_id = ?
UNION ALL
SELECT 'app', id, name FROM apps WHERE project_id = ?;
```