4 changed files with 104 additions and 0 deletions
@@ -10,6 +10,8 @@ Registry personal de codigo reutilizable con busqueda FTS. Diseñado para compos

 **Sub-repos:** cada app y cada analysis es su propio repo Gitea en `dataforge/<basename>` con branch `master` (ver ADR 0002). Los slash commands `/full-git-push` y `/full-git-pull` orquestan push/pull/clone de fn_registry + todos los sub-repos + `fn sync`. `/full-git-push` auto-inicializa apps/analyses sin `.git` via `ensure_repo_synced_bash_infra`. Los `vaults/` y `subrepos/` NO entran en este flujo.

+**Artefactos:** termino paraguas para apps, analysis, vaults, projects y playgrounds — todo lo que NO es codigo reutilizable. Usa "artefacto" cuando una afirmacion aplica a varios tipos a la vez para no repetir la lista. Ver `.claude/rules/artefactos.md` y `.claude/rules/playgrounds.md`.
+
 **Reglas y convenciones:** ver `.claude/rules/INDEX.md`

 ---
@@ -106,6 +108,7 @@ fn-registry/
  docs/                   # Specs de diseño
  docs/templates/         # Plantillas de frontmatter
  temp/                   # Workspace efimero — pruebas, APIs, prototipos (gitignored, no indexado)
+  <artefacto>/playground/ # Prototipo rapido dentro de un artefacto padre (analysis/app/proyecto). No se indexa
 ```

 ---
@@ -23,3 +23,5 @@ Reglas operativas del proyecto. Cada archivo es una regla independiente.
 | 17 | [apps_tbd.md](apps_tbd.md) | Trunk-based development obligatorio en apps generadas con `fn` (registry exento) |
 | 18 | [uses_functions.md](uses_functions.md) | Convencion de uses_functions para C++: el .md del consumidor declara las dependencias |
 | 19 | [cpp_apps.md](cpp_apps.md) | Estandarizacion de apps C++: estructura, CMake, app.md, sub-repo, runtime — apunta a cpp/PATTERNS.md y cpp/DESIGN_SYSTEM.md como autoritativas |
+| 20 | [artefactos.md](artefactos.md) | Termino paraguas para apps, analysis, vaults, projects y playgrounds (todo lo que no es codigo reutilizable) |
+| 21 | [playgrounds.md](playgrounds.md) | Prototipos rapidos dentro de un artefacto padre — heredan entorno, no se indexan, no tienen repo propio |
@@ -0,0 +1,41 @@
+## Artefactos: termino colectivo
+
+**"Artefacto"** es el termino paraguas para todo lo que vive en el registry pero NO es codigo reutilizable de `functions/` o `types/`. Sirve para no repetir "apps, analysis, vaults, projects, playgrounds" cada vez.
+
+Tipos de artefacto:
+
+| Tipo | Donde vive | Indexado en registry.db | Repo Gitea propio |
+|---|---|---|---|
+| **app** | `apps/`, `cpp/apps/`, `projects/<p>/apps/<a>/` | tabla `apps` | si (`dataforge/<a>`) |
+| **analysis** | `analysis/<t>/`, `projects/<p>/analysis/<t>/` | tabla `analysis` | si (`dataforge/<t>`) |
+| **vault** | `projects/<p>/vaults/<v>` (symlink) | tabla `vaults` | no (datos fuera del repo) |
+| **project** | `projects/<p>/` | tabla `projects` | no (vive dentro de fn_registry) |
+| **playground** | `<artefacto_padre>/playground/` | NO se indexa | no (vive dentro del padre) |
+
+Caracteristicas comunes de los artefactos:
+- NO son codigo reutilizable. La reutilizacion vive en `functions/`.
+- Tienen ciclo de vida propio (crear, modificar, archivar, borrar).
+- `pc_locations` los unifica via `entity_type` (app, analysis, project, vault).
+- Pueden importar funciones del registry; el registry NUNCA importa de un artefacto.
+
+### Cuando usar el termino
+
+Usa "artefacto" cuando hablas de varios tipos a la vez o cuando la afirmacion aplica a todos:
+
+- "Cada artefacto declara sus funciones del registry en su `.md`" (vale para apps y analyses).
+- "Los artefactos no se importan desde `functions/`."
+- "Esta regla aplica a cualquier artefacto desplegable" (apps + services).
+
+Cuando hables de UN tipo concreto, usa el nombre concreto: "esta app...", "este analysis...". No abuses del termino paraguas — es para evitar listas, no para difuminar.
+
+### Que NO es un artefacto
+
+- `functions/`, `python/functions/`, `bash/functions/`, `frontend/functions/` — codigo reutilizable.
+- `types/`, `python/types/`, `frontend/types/` — tipos del registry.
+- `sources/` — repos externos clonados para extraer funciones (gitignored).
+- `temp/` — workspace efimero, ni siquiera versionado.
+- `subrepos/` — espejos de repos externos para referencia.
+
+### Relacion con `pc_locations`
+
+Los artefactos con presencia en disco (app, analysis, project, vault) ya estan unificados en `pc_locations` via la columna `entity_type`. Los **playgrounds** NO entran en `pc_locations` porque son hijos de otro artefacto y se mueven con el (no tienen identidad propia entre PCs).
@@ -0,0 +1,58 @@
+## Playgrounds: prototipos rapidos dentro de un artefacto
+
+Un **playground** es un mini-artefacto efimero que vive **dentro** de otro artefacto (analysis, app o project) y reutiliza su entorno. Sirve para probar visualmente una idea (webapp, demo, dashboard, ejercicio interactivo) antes de decidir si se promueve a app independiente.
+
+Ejemplo canonico: `projects/osint_graph/analysis/gliner_glirel_tuning/playground/` — server FastAPI + index.html + JS vendored que reutiliza el `.venv` del analisis padre para visualizar las recetas del notebook 08 con UI interactiva.
+
+### Estructura
+
+```
+<artefacto_padre>/
+  playground/                  # Un solo playground por padre (si necesitas mas, usa subdirs)
+    server.py | server.go | ...   # Punto de entrada (single-file preferido)
+    index.html                    # UI si la hay
+    static/                       # JS/CSS vendored (no node_modules ni pnpm)
+    server.log                    # Log local (gitignorable)
+```
+
+Si el playground crece a varios subdirs/modulos, ya no es playground — promover a app.
+
+### Reglas
+
+1. **Hereda el entorno del padre**. NO crea su propio `.venv`, `package.json`, ni dependencias. Si el padre es un analysis Python, usa `../.venv/bin/python3`. Si el padre es una app Go, comparte el `go.mod`.
+2. **NO se indexa**. No tiene `app.md`, no aparece en `registry.db`, no tiene entrada en `pc_locations`.
+3. **NO tiene repo propio**. Vive dentro del repo Gitea del artefacto padre y se mueve con el.
+4. **Single-file preferido**. Un `server.py` o `main.go` con todo dentro. Si hace falta partir, considera promover a app.
+5. **Vendor deps front**. JS/CSS como `.min.js` en `static/`, sin `node_modules`. Si necesitas pnpm/vite, ya no es playground.
+6. **Reutiliza funciones del registry** igual que el padre — `sys.path` al `python/functions`, importar paquetes, etc.
+7. **Ciclo de vida**: vive mientras la idea esta cruda. Una vez probada, dos caminos:
+   - **Promover a app** (extraer logica reutilizable como funciones del registry, crear `app.md`, mover a `apps/`).
+   - **Borrar** sin contemplaciones si el experimento no llevo a nada.
+
+### Cuando NO usar playground
+
+- Si necesitas correr en un VPS / tener systemd / health check → es un app + service, no playground.
+- Si la idea ya esta clara y el codigo va a sobrevivir meses → arrancar como app desde el primer dia ahorra una migracion.
+- Si necesitas operations.db, assertions, o el bucle reactivo → es app.
+- Si el padre seria un proyecto entero solo para contener el playground → probablemente sea app standalone con `tags: [prototype]`.
+
+### Relacion con `temp/`
+
+| Cuando | Donde |
+|---|---|
+| Idea suelta sin contexto, prueba de API, snippet desechable | `temp/<lo_que_sea>/` (gitignored, sin contexto) |
+| Prototipo ligado a un analysis/app/proyecto que reutiliza su entorno | `<padre>/playground/` (versionado con el padre) |
+| Codigo que sobrevive y se reutiliza en otros sitios | extraer a `functions/` |
+| Aplicacion ejecutable con identidad propia | `apps/` o `projects/<p>/apps/<a>/` |
+
+`temp/` es para cosas sin padre. Playground es para cosas con padre. Si dudas entre los dos, empieza en `temp/` y mueve a `playground/` cuando quede claro de que artefacto depende.
+
+### Lanzar un playground
+
+Sin convencion fija — depende del stack. El propio `server.py` o un README en el playground documenta como arrancarlo. Ejemplo del playground de OSINT:
+
+```bash
+cd projects/osint_graph/analysis/gliner_glirel_tuning/playground
+../.venv/bin/python3 server.py
+# http://localhost:7878
+```