fn_registry/.claude/rules/playgrounds.md

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:

cd projects/osint_graph/analysis/gliner_glirel_tuning/playground
../.venv/bin/python3 server.py
# http://localhost:7878