navori 0.2.0 → 0.2.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ulises Ciprés
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -25,8 +25,8 @@ navori init
 
 El `init` detecta automáticamente del repo:
 - **Nombre** del proyecto (de `package.json`, `pyproject.toml`, `Cargo.toml`, git remote o basename)
-- **Stack**: framework (Next.js, Vite, NestJS, Expo, etc.), UI, forms, state, test
-- **Preset sugerido** basado en el stack (ej. `vite-react-ts-mantine`, `nextjs-apollo`, `bun-keystone`)
+- **Stack**: framework (Next.js, Vite, NestJS, Express, Astro, etc.), UI, forms, state, test
+- **Preset sugerido** según el stack (ej. `vite-react-ts-mantine`, `nextjs`, `express-mongoose`)
 - **Quality gate** compuesto de los scripts del `package.json`
 - **Branch base** del git (`origin/HEAD`, fallback main/master/develop)
 - **Infraestructura Claude existente** (`.claude/`, `CLAUDE.md`, `AGENTS.md`, agents, skills) — ofrece coexistir o reemplazar con backup
@@ -34,20 +34,56 @@ El `init` detecta automáticamente del repo:
 Y genera:
 - `navori.config.json` — fuente de verdad del repo
 - `CLAUDE.md` con managed blocks que el CLI mantiene sincronizados
+- `.claude/` con agentes, skills, hooks y settings
 
 ## Comandos
 
 | Comando | Qué hace |
 |---|---|
-| `init` | Bootstrap del repo con detección automática + wizard |
-| `add <plugin>` | Activa un plugin + opcionalmente instala la tool externa |
+| `init` | Bootstrap del repo con detección automática + wizard (o `--recommended` sin preguntas) |
+| `add <plugin>` | Activa un plugin y opcionalmente instala la tool externa |
 | `configure <section>` | Ajusta una sección del config sin re-correr el wizard |
 | `update` | Re-detecta el repo, refresca config y corre sync en un paso |
-| `render` | Genera CLAUDE.md con los managed blocks |
-| `sync` | Refresca managed blocks con conflict resolution + backups |
-| `doctor` | Inspecciona config + reporta procedencia de cada managed block |
-| `workspace <sub>` | Gestiona workspaces cross-repo (init, ls, show, add-repo) |
-| `ticket <sub>` | Gestiona tickets-as-files en un workspace (new, list, show) |
+| `render` | Genera CLAUDE.md y `.claude/` desde el config (preview por default; `--apply` escribe) |
+| `sync` | Refresca los managed blocks con conflict resolution + backups |
+| `preset init <id>` | Scaffoldea un preset local en `.navori/presets/<id>/` |
+| `scan` | Detecta workspaces nuevos en monorepos (`pnpm-workspace.yaml` / `package.json#workspaces`) |
+| `doctor` | Audita el config + reporta procedencia y drift de cada managed block (`--strict` para CI) |
+| `status` | Snapshot rápido: config, plugins activos, conteo de drift y próximos pasos |
+| `bench` | Corre `render` en dry-run N veces y reporta latencias (detecta regresiones locales) |
+| `workspace <sub>` | Gestiona workspaces cross-repo (`init`, `ls`, `show`, `rm`) |
+| `ticket <sub>` | Gestiona tickets-as-files en un workspace (`new`, `list`, `show`, `archive`, `delete`) |
+| `backup <sub>` | Lista y restaura backups de `~/.navori/backups/` |
+| `migrations <sub>` | Lista y restaura migraciones de `~/.navori/migrations/` |
+
+## Presets
+
+Un preset aporta skills y reglas específicas del stack además del core. El `init` te sugiere uno según lo que detecta.
+
+**Presets oficiales (incluidos):**
+
+| Preset | Stack |
+|---|---|
+| `vite-react-ts-mantine` | Vite + React + TS + Mantine (SPA) |
+| `nextjs` | Next.js (App Router) |
+| `nestjs` | NestJS (backend) |
+| `express-mongoose` | Express + Mongoose (backend) |
+| `background-worker` | Worker de fondo (jobs + colas: agenda / bullmq / amqplib) |
+| `astro` | Astro (static / SSR) |
+| `medusa` | Medusa.js v2 (backend) |
+
+**¿Tu stack no tiene preset oficial?** No pasa nada. El `init` instala el harness completo (agentes, gates, protocolo, SDD) y funciona desde ya — solo te quedas sin los skills específicos del stack. El init te avisa, te deja en el baseline (`preset: custom`) y te sugiere cubrir el gap con un preset local.
+
+**Presets locales** — crea uno checked-in al repo bajo `.navori/presets/<id>/`:
+
+```bash
+navori preset init sveltekit
+# ✓ .navori/presets/sveltekit/  (manifest + managed/stack.md + skills/)
+# ✓ navori.config.json → preset: sveltekit
+# → edita las plantillas y corre 'navori render --apply'
+```
+
+La resolución es **local → bundled**: si tienes un preset local con el mismo id que uno oficial, gana el local. Así puedes override un preset incluido sin tocar el paquete.
 
 ## Plugins disponibles
 
@@ -66,6 +102,15 @@ navori add engram          # te ofrece instalar la tool externa si falta
 navori add engram --skip-install   # solo registra el plugin
 ```
 
+## Harness defensivo (read-only por default)
+
+El harness que genera `navori` trae permisos seguros desde el arranque, para que tengas menos prompts en lo cotidiano sin bajar la guardia en lo peligroso:
+
+- **Las lecturas no piden confirmación**: `git status/diff/log/show`, `ls`, `cat`, `grep`, `Read`/`Glob`/`Grep`, etc. corren sin interrumpirte.
+- **Lo destructivo pide confirmación** (`ask`): `rm -rf`, `git push --force`, `git reset --hard`, `git clean -f`, `chmod -R`, …
+- **Lo catastrófico se rechaza** (`deny`): `rm -rf /`, `sudo rm`, `mkfs`, …
+- Un hook `guard-destructive` actúa como backstop adicional.
+
 ## Workspace + tickets cross-repo
 
 Si un ticket toca varios repos (frontend + backend + microservicio), el workspace te da un punto único:
@@ -81,7 +126,7 @@ navori workspace add-repo bonum --name backend --path ~/dev/bonum/nexus --stack
 # Crear ticket
 navori ticket new bonum BNM-123 --title "Checkout flow rebuild"
 
-# En cada repo que tocás el ticket, agregá una referencia:
+# En cada repo que toca el ticket, agrega una referencia:
 # echo "ticket: BNM-123" >> progress/current.md
 
 # Ver el ticket + en qué repos aparece
@@ -91,6 +136,18 @@ navori ticket show bonum BNM-123
 El workspace también guarda defaults heredables:
 ```bash
 navori init --workspace bonum    # hereda engines, plugins, branchBase, etc.
+
+# Ajustar un default sin editar el manifest a mano
+navori workspace set-default bonum branchBase main
+navori workspace set-default bonum prTarget develop      # PRs van a develop, no a main
+navori workspace set-default bonum engines claude,cursor
+navori workspace set-default bonum plugins.engram.enabled true
+```
+
+Y re-renderizar todos los repos del workspace de una vez:
+```bash
+navori workspace render bonum           # preview (no toca disco)
+navori workspace render bonum --apply    # escribe en cada repo
 ```
 
 Storage: `~/.navori/workspaces/<name>/` (manifest + tickets/ + backups/).
@@ -105,17 +162,17 @@ contenido sincronizado
 <!-- /navori:managed id="idioma-rol" -->
 ```
 
-- **`hash`**: detecta si vos editaste el bloque (sync te avisa antes de pisar)
+- **`hash`**: detecta si editaste el bloque (sync te avisa antes de pisarlo)
 - **`version`**: cuando se publica una nueva versión de `@navori/core` o un plugin, `sync` reporta "update available"
 - **`source`**: qué paquete es dueño del bloque (`doctor` te muestra la procedencia de cada uno)
 
-Si modificás un managed block a mano y después corrés `sync`, vas a ver:
+Si modificas un managed block a mano y después corres `sync`, vas a ver:
 ```
 Conflict in 'idioma-rol':
   - tu versión
   + versión del Core
 ```
-Y elegís: `skip-conflicts` (mantener tu edit), `apply-all` (pisar) o `abort`.
+Y eliges: `skip-conflicts` (mantener tu edit), `apply-all` (pisar) o `abort`.
 
 Backups automáticos en `~/.navori/backups/<timestamp>/` antes de cada `sync` (retención 30 días).
 
@@ -128,17 +185,20 @@ navori configure plugins              # multiselect de plugins activos
 navori configure quality-gate         # nuevo comando de quality gate
 navori configure language en          # switch a inglés (fallback a es)
 navori configure engines              # multiselect: claude / agents-md / cursor / copilot
+navori configure branch-base main     # punto de fork / rama protegida
+navori configure pr-target develop    # rama destino del PR (gh pr create --base)
 navori configure workspace bonum      # asociar a un workspace
 ```
 
 ## Filosofía
 
-- **Cero opinión sobre tu proceso**. El CLI detecta y propone; vos decidís.
-- **Coexiste con harness existente**. Modo `coexist` no toca nada que ya tenías.
+- **Cero opinión sobre tu proceso**. El CLI detecta y propone; tú decides.
+- **Coexiste con harness existente**. El modo `coexist` no toca nada que ya tenías.
 - **Nunca pisa silenciosamente**. Hash en el marker + backups antes de cada write.
+- **Read-only por default**. Las lecturas no piden permiso; lo destructivo sí.
 - **Output legible siempre**. Texto + `--json` para piping en CI.
-- **Bilingüe ready**. Schema soporta `language: es | en`. Hoy solo `es` está full; `en` cae en fallback honesto.
+- **Bilingüe ready**. El schema soporta `language: es | en`. Hoy `es` está full; `en` cae en fallback honesto.
 
 ## Licencia
 
-ISC.
+MIT.

package/dist/assets/core/core-assets/agents/commit-pr-pilot.md

@@ -18,20 +18,22 @@ Te encargas del **cierre del ciclo**: commits Conventional bien estructurados y
 ## Cuándo NO activar
 
 - Working tree con cambios sin commitear cuando el usuario solo pidió "abre el PR" → primero commiteas o pides permiso.
-- Estás en `{{branchBase}}` u otra rama protegida → abort + pedir branch.
+- Estás en `{{branchBase}}` o `{{prTarget}}` u otra rama protegida → abort + pedir branch.
 - Harness activo y `.claude/progress/review_*.md` reciente contiene `CHANGES_REQUESTED` → no se crea PR.
 - Quality gate en rojo en este turno.
 
+> **Dos ramas, dos roles:** `{{branchBase}}` es el punto de fork (de dónde ramificaste). `{{prTarget}}` es la rama destino del PR (`gh pr create --base`). Suelen coincidir; cuando difieren, el PR y su diff se calculan contra `{{prTarget}}`.
+
 ## Pre-flight obligatorio
 
 Corre estos chequeos antes de redactar nada. Si algo falla, paras y reportas.
 
 ```bash
 git status --porcelain                                # qué falta commitear
-git rev-parse --abbrev-ref HEAD                       # no puede ser {{branchBase}}
-git fetch origin {{branchBase}} --quiet
-git log origin/{{branchBase}}..HEAD --oneline         # debe haber ≥1 commit (o cambios para commitear)
-git diff origin/{{branchBase}}...HEAD --stat          # scope del PR
+git rev-parse --abbrev-ref HEAD                       # no puede ser {{branchBase}} ni {{prTarget}}
+git fetch origin {{prTarget}} --quiet
+git log origin/{{prTarget}}..HEAD --oneline           # debe haber ≥1 commit (o cambios para commitear)
+git diff origin/{{prTarget}}...HEAD --stat            # scope REAL del PR (contra el target)
 gh auth status                                        # gh autenticado
 ```
 
@@ -59,10 +61,11 @@ Sin `APPROVED` y con harness activo → abort, dile al usuario que falta review.
 
 ## Flujo de PR
 
-1. **Recopilar contexto** (curado, no volcar todo el repo):
-   - `git log origin/{{branchBase}}..HEAD --oneline` — commits incluidos.
-   - `git diff origin/{{branchBase}}...HEAD --stat` — siempre.
-   - `git diff origin/{{branchBase}}...HEAD` — solo si el diff < 500 líneas. Si es mayor, usa solo el stat + lista de archivos + los hunks de los 2–3 archivos más relevantes.
+1. **Recopilar contexto** (curado, no volcar todo el repo). El diff del PR es contra `{{prTarget}}` (lo que GitHub mostrará):
+   - `git log origin/{{prTarget}}..HEAD --oneline` — commits incluidos.
+   - `git diff origin/{{prTarget}}...HEAD --stat` — siempre.
+   - `git diff origin/{{prTarget}}...HEAD` — solo si el diff < 500 líneas. Si es mayor, usa solo el stat + lista de archivos + los hunks de los 2–3 archivos más relevantes.
+   - **Arrastre de commits** (solo si `{{branchBase}}` ≠ `{{prTarget}}`): `git fetch origin {{branchBase}} --quiet` y `git rev-list --count origin/{{prTarget}}..origin/{{branchBase}}`. Si es > 0, `{{branchBase}}` va adelantado de `{{prTarget}}` y tu PR arrastra esos commits ajenos: avisa al usuario y sugiere rebasar sobre `{{prTarget}}` antes de abrir.
    - Ticket si aplica: nombre del branch (ej. `BT-1234-fix-x` → `BT-1234`) o referencia en el primer commit.
    - `.claude/progress/impl_<feature>.md` si existe — decisiones no obvias.
 
@@ -79,6 +82,7 @@ Sin `APPROVED` y con harness activo → abort, dile al usuario que falta review.
 
    ```bash
    gh pr create \
+     --base {{prTarget}} \
      --title "<title validado>" \
      --body "$(cat <<'EOF'
    <body validado>
@@ -86,6 +90,8 @@ Sin `APPROVED` y con harness activo → abort, dile al usuario que falta review.
    )"
    ```
 
+   Siempre pasa `--base {{prTarget}}` explícito — no dejes que `gh` use la rama default del repo. Si el target cambió, ajústalo con `navori configure pr-target`.
+
 5. **Output al usuario**: solo la URL del PR + 1 línea con el título. Nada más.
 
 ## Template del body (default genérico)

package/dist/assets/core/core-assets/lib-skills/formik.md

@@ -0,0 +1,57 @@
+---
+name: formik
+description: Patrones de Formik en React+TS — schema de validación, estado de form, submit, errores por campo. Aplica al crear o tocar formularios con Formik.
+type: reference
+---
+
+# Formik — convenciones
+
+## Cuándo usar este skill
+
+Al crear o tocar un formulario con Formik: definir initial values, validación, submit, o pintar errores. Formik es la fuente de verdad del estado del form — no dupliques sus valores en `useState` paralelos.
+
+## El patrón
+
+Validación declarativa con un schema (Yup/Zod), no a mano en `validate`:
+
+```ts
+const formik = useFormik({
+  initialValues: { email: '', role: 'coachee' },
+  validationSchema: toFormikValidationSchema(loginSchema), // zod, o un Yup schema
+  onSubmit: async (values, { setSubmitting, setStatus }) => {
+    try {
+      await api.login(values);
+    } catch (err) {
+      setStatus(toFormError(err)); // error de servidor, no de campo
+    } finally {
+      setSubmitting(false);
+    }
+  },
+});
+```
+
+En el JSX: `formik.getFieldProps('email')` cablea value/onChange/onBlur; el error se muestra solo si el campo fue tocado: `formik.touched.email && formik.errors.email`.
+
+## Gotchas que muerden
+
+- **Una sola fuente de verdad.** Los valores viven en Formik; nada de `useState` espejo que se desincroniza.
+- **`touched` antes de mostrar error** — pintar errores antes del primer blur frustra al usuario; usa `touched.<campo> && errors.<campo>`.
+- **`isSubmitting`** deshabilita el botón y evita doble submit; resetéalo siempre en `finally`.
+- **Errores de campo vs de servidor**: un fallo de validación va a `errors` (vía schema); un fallo de API va a `setStatus`/`setFieldError`, no se inventa como error de campo.
+- **Forms grandes** re-renderizan todo en cada tecla; aísla con `<Field>`/componentes memoizados si pesa.
+- **`enableReinitialize`** cuando los initial values llegan async (editar un recurso cargado), o el form arranca vacío.
+
+## Reglas duras
+
+1. Validación en un schema (Yup/Zod), nunca lógica suelta en `validate` inline.
+2. Estado del form solo en Formik; sin `useState` paralelos a sus valores.
+3. Error de campo solo tras `touched`; error de servidor vía `setStatus`/`setFieldError`.
+4. `isSubmitting` controla el botón y se limpia en `finally`.
+5. `enableReinitialize` para formularios de edición con carga async.
+
+## Antes de declarar listo
+
+- El form valida contra un schema y muestra errores solo tras blur.
+- El submit deshabilita el botón y maneja el error de servidor aparte.
+- No hay estado del form duplicado fuera de Formik.
+- `{{qualityGate.fast}}` en verde.

package/dist/assets/core/core-assets/lib-skills/joi-validation.md

@@ -0,0 +1,73 @@
+---
+name: joi-validation
+description: Validación de input con Joi (@hapi/joi) en Express — schemas por recurso, middleware validate genérico, DTOs explícitos. Aplica al crear schemas o tocar input validation de body/query/params.
+type: reference
+---
+
+# Joi Validation — el patrón canónico
+
+Un schema por recurso (`<resource>.schema.ts`), validado por un middleware genérico que reemplaza `req[target]` con el valor convertido. Como Joi no infiere tipos, el DTO es una `interface` explícita junto al schema.
+
+## Cuándo usar este skill
+
+Al crear un schema, agregar validación a un endpoint, definir un DTO, o tocar input de body/query/params.
+
+## El patrón
+
+El middleware vive en `helpers/validate.ts`: corre `schema.validate(req[target], { abortEarly: true, convert: true })`, y al fallar lanza `BadRequestError(\`${detail.path.join('.')}: ${detail.message}\`)` con el primer issue. En éxito, reasigna `req[target] = value` (el valor ya convertido). Schema y DTO:
+
+```ts
+const objectId = Joi.string().pattern(/^[a-f\d]{24}$/i).message('Invalid ObjectId');
+
+export const createResourceSchema = Joi.object({
+  owner: objectId.required(),
+  resourceType: Joi.string().valid(...Object.values(ResourceTypeEnum)).required(),
+  page: Joi.number().integer().positive().default(1),
+});
+export const updateResourceSchema = createResourceSchema.fork(
+  Object.keys(createResourceSchema.describe().keys),
+  (s) => s.optional(),
+);
+
+export interface CreateResourceDto {
+  owner: string;
+  resourceType: ResourceTypeEnum;
+  page: number;
+}
+```
+
+En la route: `router.post('/', validate(createResourceSchema, 'body'), ...)`. En el controller el cast `req.body as CreateResourceDto` es seguro porque el middleware ya validó y convirtió.
+
+## Gotchas que muerden
+
+- **ObjectId pelado** (`Joi.string()`) deja pasar `"abc"`; Mongoose lanza CastError 500 en vez de 400 limpio. Usa siempre el helper `objectId`.
+- **`convert: true` es obligatorio** para query/params: las query strings llegan como string y Joi sin `convert` rechaza `Joi.number()`. Con `convert` las castea a number/date/boolean.
+- **`abortEarly`**: con `false` juntas todos los errores; con `true` (default recomendado aquí) cortas en el primero — sé consistente con lo que el middleware reporta.
+
+## Reglas duras
+
+1. Toda validación en el schema, nunca inline en el controller.
+2. El schema vive en `<resource>.schema.ts`, nunca en las routes.
+3. DTO como `interface` explícita al lado del schema — mantenlos en sync (Joi no infiere tipos).
+4. Nada de `Joi.any()`: equivale a `any`, prohibido en código nuevo.
+5. Un solo validador por endpoint — no mezcles Joi + Zod (al migrar entre ambos, migra el endpoint completo).
+6. ObjectId con el helper `objectId`; query/params siempre con `convert: true`.
+
+## Tabla rápida
+
+| Necesito validar | Helper |
+|---|---|
+| ObjectId | `objectId` (pattern `/^[a-f\d]{24}$/i`) |
+| String no vacío | `Joi.string().trim().min(1)` |
+| Number desde query | `Joi.number().integer().positive()` (+ `convert: true`) |
+| Date | `Joi.date()` (+ `convert: true`) |
+| Enum TS / literal | `Joi.string().valid(...Object.values(MyEnum))` |
+| Update parcial | `schema.fork(keys, (s) => s.optional())` |
+| Validación cruzada | `.custom((v, helpers) => ...)` o `Joi.object().and('a', 'b')` |
+
+## Antes de declarar listo
+
+- El schema vive en `<resource>.schema.ts` y el DTO es una `interface` explícita.
+- El endpoint usa `validate(schema, target)`; sin validación inline en el controller.
+- Campos ObjectId con el helper `objectId`; el middleware corre con `convert: true`.
+- `{{qualityGate.fast}}` en verde.

package/dist/assets/core/core-assets/{presets/express-mongoose/skills → lib-skills}/mongoose.md

@@ -10,6 +10,8 @@ type: reference
 
 Cuando la tarea toca `domain/models` o ejecuta operaciones de Mongoose en los controllers. Mongoose 6+ sobre MongoDB. El repo no usa repository wrappers: los controllers tocan los Models directo, así que null-guards, casts de ObjectId y `.lean()` viven en cada controller method.
 
+En **NestJS** (`@nestjs/mongoose`) el Model no se importa directo: se inyecta con `@InjectModel(Resource.name) private resourceModel: Model<ResourceDocument>` en el constructor del service. El resto de patrones (`.lean()`, `new Types.ObjectId`, null-guards, soft delete) aplican igual.
+
 ## Patrón canónico
 
 ```ts
@@ -40,7 +42,7 @@ Valida el formato en el schema (`z.string().regex(/^[a-f\d]{24}$/i, ...)`); si n
 
 - **N+1**: `populate` ejecuta queries extra. En paginate sobre datasets grandes usa `$lookup` en vez de `populate`.
 - **`.lean()`**: el resultado no tiene `.save()`, `.delete()` ni virtuals. Si necesitas mutar, no lo uses.
-- **Soft delete**: con `mongoose-delete`, `find` ya excluye `deleted: true`; borra con `doc.delete()` (no `findByIdAndDelete`, que es hard delete) y restaura con `doc.restore()`. Plugin sin tipos → `@ts-expect-error` puntual.
+- **Soft delete**: con `mongoose-delete`, `find` ya excluye `deleted: true`; borra con `doc.delete()` (no `findByIdAndDelete`) y restaura con `doc.restore()`.
 
 ## Reglas duras
 
@@ -49,7 +51,6 @@ Valida el formato en el schema (`z.string().regex(/^[a-f\d]{24}$/i, ...)`); si n
 3. **`.lean()` cuando no necesitas mutar** — evita el overhead de documentos Mongoose.
 4. **Comparar ObjectId con `.equals()`** / `.toString()`, nunca `==`.
 5. **Respeta el soft delete del repo** — no hard delete en modelos con `mongoose-delete`.
-6. **Cast explícito solo cuando hace falta** — `new Types.ObjectId(id)` para aggregations/queries complejas; nada de casts innecesarios.
 
 ## Tabla rápida
 

package/dist/assets/core/core-assets/lib-skills/redux-toolkit.md

@@ -0,0 +1,59 @@
+---
+name: redux-toolkit
+description: Patrones de Redux Toolkit en React+TS — slices, store tipado, hooks tipados, async thunks, selectores. Aplica al tocar estado global, slices o el store.
+type: reference
+---
+
+# Redux Toolkit — convenciones
+
+## Cuándo usar este skill
+
+Al crear o tocar un slice, el store, async thunks, o leer/escribir estado global. RTK es el estándar — nada de `createStore` pelado, action types a mano, ni `connect`. Estado de servidor (fetch/cache) NO va aquí: eso es TanStack Query. Redux es para estado de cliente compartido (sesión, UI cross-página, carrito).
+
+## El patrón
+
+```ts
+const slice = createSlice({
+  name: 'session',
+  initialState,
+  reducers: {
+    setActive(state, action: PayloadAction<Session>) {
+      state.active = action.payload; // Immer: "mutas" un draft, no el real
+    },
+  },
+  extraReducers: (b) => {
+    b.addCase(loadSession.fulfilled, (s, a) => { s.active = a.payload; });
+  },
+});
+export const { setActive } = slice.actions;
+```
+
+Store + hooks tipados una sola vez, y se usan en toda la app:
+
+```ts
+export const useAppDispatch: () => AppDispatch = useDispatch;
+export const useAppSelector: TypedUseSelectorHook<RootState> = useSelector;
+```
+
+## Gotchas que muerden
+
+- **Immer solo dentro de `createSlice`.** Ahí "mutas" el draft; fuera de un reducer, mutar el state es un bug. No retornes Y mutes en el mismo reducer.
+- **Selectores memoizados** con `createSelector` cuando derivan/transforman — un selector que crea un array/objeto nuevo en cada llamada re-renderiza siempre.
+- **`useSelector` devuelve la referencia**: selecciona lo mínimo, no el slice entero.
+- **Async**: `createAsyncThunk` para casos simples; si es data de API que cacheas/invalidas, evalúa RTK Query en vez de thunks + slice manual.
+- **No-serializables** (Date, Map, funciones) fuera del store; rompen devtools y persistencia.
+
+## Reglas duras
+
+1. Estado global solo vía slices de RTK; nada de Context improvisado para lo mismo.
+2. Hooks `useAppDispatch`/`useAppSelector` tipados, nunca los crudos sin tipo.
+3. Selecciona lo mínimo y memoiza los derivados con `createSelector`.
+4. Estado de servidor no vive en Redux — eso es cache de queries.
+5. Solo valores serializables en el store.
+
+## Antes de declarar listo
+
+- El slice nuevo expone acciones tipadas y se consume con los hooks tipados.
+- Los selectores derivados están memoizados; los componentes seleccionan lo mínimo.
+- Nada de data de API duplicada en el store si ya hay capa de queries.
+- `{{qualityGate.fast}}` en verde.

package/dist/assets/core/core-assets/lib-skills/socketio.md

@@ -0,0 +1,56 @@
+---
+name: socketio
+description: Patrones de Socket.IO en un servicio Node — namespaces, rooms, auth en el handshake, eventos tipados, cleanup. Aplica al tocar realtime, gateways o handlers de socket.
+type: reference
+---
+
+# Socket.IO — convenciones del servicio
+
+## Cuándo usar este skill
+
+Al agregar o tocar realtime: un namespace, un evento, autenticación de conexión, o broadcast a un room. Socket.IO sobre el HTTP server de Express. La regla base: el handler de socket es una capa de transporte, no de negocio — delega al mismo service/controller que usan las rutas HTTP.
+
+## El patrón
+
+```ts
+io.of('/sessions').use(authSocket).on('connection', (socket) => {
+  socket.join(`session:${socket.data.sessionId}`);
+
+  socket.on('message:send', async (dto, ack) => {
+    try {
+      const saved = await messageService.create(socket.data.userId, dto);
+      io.to(`session:${dto.sessionId}`).emit('message:new', saved);
+      ack?.({ ok: true, id: saved._id });
+    } catch (err) {
+      ack?.({ ok: false, error: toClientError(err) });
+    }
+  });
+
+  socket.on('disconnect', () => { /* cleanup timers/subscriptions */ });
+});
+```
+
+`authSocket` valida el token en `socket.handshake.auth.token` y rellena `socket.data` (userId/sessionId). Nunca confíes en un id que venga en el payload del evento sin cruzarlo contra `socket.data`.
+
+## Gotchas que muerden
+
+- **Rooms, no broadcast global.** `io.emit` manda a todos los conectados; usa `io.to(room)` / `socket.to(room)` para no filtrar datos entre sesiones/tenants.
+- **`socket.emit` vs `io.to(...).emit`.** `socket.emit` responde solo al emisor; para incluirte y al resto del room usa `io.to(room)`, para excluirte usa `socket.to(room)`.
+- **Listeners colgados.** Toda suscripción/intervalo creado en `connection` se limpia en `disconnect`, o se filtra memoria.
+- **Errores.** Un throw dentro de un handler no llega al cliente: reporta vía el callback `ack` o un evento `error:*`, nunca dejes la promesa sin catch.
+- **Auth en el handshake**, no por evento — rechaza en el middleware `.use()` antes de `connection`.
+
+## Reglas duras
+
+1. El handler delega al service; nada de queries ni lógica de negocio inline.
+2. Identidad desde `socket.data` (poblado en auth), nunca desde el payload.
+3. Emite a un room específico; `io.emit` global solo para health/system.
+4. Cada `on(...)` con efectos secundarios tiene su cleanup en `disconnect`.
+5. Errores al cliente vía `ack`/evento `error`, con el mismo `ApiError` mapeado que HTTP.
+
+## Antes de declarar listo
+
+- Los eventos nuevos validan su input igual que un endpoint HTTP.
+- Ningún `io.emit` global salvo señales de sistema; el resto va por room.
+- Auth resuelta en el middleware del namespace, no dentro de los handlers.
+- `{{qualityGate.fast}}` en verde.

package/dist/assets/core/core-assets/lib-skills/tanstack-query.md

@@ -0,0 +1,58 @@
+---
+name: tanstack-query
+description: Patrones de TanStack Query (React Query) — query keys, mutations, invalidación, staleTime. Aplica al tocar fetching, cache de servidor o mutaciones de datos remotos.
+type: reference
+---
+
+# TanStack Query — convenciones
+
+## Cuándo usar este skill
+
+Al leer/escribir datos del servidor: un `useQuery`, un `useMutation`, invalidar cache, o paginar. TanStack Query es la fuente de verdad del **estado de servidor** (fetch + cache + revalidación). No lo uses para estado de cliente puro (eso es useState/Redux), ni dupliques su data en otro store.
+
+## El patrón
+
+Query keys estructuradas y centralizadas para invalidar sin strings sueltos:
+
+```ts
+const sessionKeys = {
+  all: ['sessions'] as const,
+  detail: (id: string) => [...sessionKeys.all, id] as const,
+};
+
+const { data, isPending, error } = useQuery({
+  queryKey: sessionKeys.detail(id),
+  queryFn: () => api.getSession(id),
+  staleTime: 30_000,
+  enabled: Boolean(id),
+});
+
+const mutation = useMutation({
+  mutationFn: api.updateSession,
+  onSuccess: () => queryClient.invalidateQueries({ queryKey: sessionKeys.all }),
+});
+```
+
+## Gotchas que muerden
+
+- **Query keys como datos, no strings.** Una factory (`sessionKeys`) evita typos y permite invalidar por prefijo (`sessionKeys.all` invalida todos los detalles).
+- **`staleTime` vs `gcTime`.** `staleTime` decide cuándo refetchea; con `0` (default) refetchea agresivo. Súbelo para data estable y evita parpadeos/llamadas extra.
+- **No espejes la data en useState/Redux.** Lee de `data` directo; copiarla a otro estado crea dos verdades que se desincronizan.
+- **`enabled`** para queries dependientes — no dispares con el id aún `undefined`.
+- **Invalidación tras mutar**, no edición manual del cache, salvo update optimista deliberado con rollback en `onError`.
+- **`isPending` vs `isFetching`**: `isPending` es la primera carga sin data; `isFetching` es cualquier fetch en curso (incluye revalidación).
+
+## Reglas duras
+
+1. Estado de servidor vive en Query; no se copia a otro store.
+2. Query keys desde una factory tipada, nunca arrays literales dispersos.
+3. Tras una mutation, invalida las keys afectadas.
+4. `enabled` en queries dependientes; nada de queries con params inválidos.
+5. `staleTime` explícito cuando la data no cambia cada segundo.
+
+## Antes de declarar listo
+
+- Las keys nuevas salen de la factory y se invalidan tras mutar.
+- Ningún dato de query duplicado en useState/Redux.
+- Las queries dependientes usan `enabled`.
+- `{{qualityGate.fast}}` en verde.

package/dist/assets/core/core-assets/managed/cierre-sesion.md

@@ -2,7 +2,7 @@
 
 Antes de cerrar la sesión:
 
-1. **Quality gate**: corre `{{qualityGate.full}}` y confirma que pasa (o documenta deuda en `progress/current.md`).
+1. **Quality gate**: {{qualityGate.full}} — confirma que pasa (o documenta deuda en `progress/current.md`).
 2. **History**: agrega entrada en `progress/history.md` con `## YYYY-MM-DD HH:MM <agente> — <resumen>` + cambios + estado del gate.
 3. **Vaciar current**: deja `progress/current.md` en estado `idle` o con el siguiente paso explícito.
 4. **Sin temporales**: borra scratch files, no dejes `console.log`, `debugger`, ni código comentado.

package/dist/assets/core/core-assets/managed/idioma-rol.md

@@ -1,4 +1,4 @@
 ## Idioma y rol
 
-- Código/JSDoc: inglés. Chat: español MX.
+- Código y comentarios (JSDoc/docstrings): inglés. Chat: español MX.
 - Rol Tech Lead Senior. Antes de codear: ¿lo más simple? ¿legible en 6 meses? ¿mantiene patrón existente? Simplicidad > cleverness.

package/dist/assets/core/core-assets/managed/operaciones-seguras.md

@@ -4,5 +4,6 @@ Read-only por default. Antes de mutar datos, esquema o infraestructura (DB, stor
 
 - **DB / queries**: por default solo lectura (`SELECT`, `EXPLAIN`, flags tipo `onlyRead`). `INSERT/UPDATE/DELETE/DROP/ALTER/TRUNCATE` requieren que el usuario lo pida de forma explícita.
 - **Comandos de shell**: inspeccionar es libre (`ls`, `cat`, `git status/diff/log`). Los destructivos (`rm -rf`, `git reset --hard`, force-push, `chmod -R`) los manda el harness a `ask`/`deny` y un hook los bloquea — no intentes evadir esa capa.
+- **Búsqueda de código**: usa las tools nativas `Glob` (archivos por nombre/patrón) y `Grep` (contenido). Son read-only, más rápidas (ripgrep por debajo) y ya saltan `node_modules`/`.git`, así que no piden permiso. Reserva `find`/`grep` por shell para lo que las tools no cubren — búsqueda por metadata del FS (`-size`, `-mtime`, permisos) — y úsalo solo cuando sea críticamente necesario. `find` no está pre-aprobado a propósito: con `-exec`/`-delete` no es read-only puro, así que pedir permiso ahí es la red de seguridad correcta, no un estorbo.
 - **Si una mutación destructiva es legítima y necesaria**: explica qué hace y por qué, y deja que el usuario la confirme o la corra. Nunca la disfraces con variables, subshells o `--no-verify` para saltarte el gate.
 - **Datos sensibles**: no vuelques secretos, PII ni dumps completos a logs, chat o archivos del repo.

package/dist/assets/core/core-assets/presets/background-worker/managed/stack.md

@@ -0,0 +1,18 @@
+## Stack — Background worker (jobs + queues)
+
+Proceso de fondo en Node/TS cuyo trabajo es **procesar jobs y mensajes**, no servir HTTP. El flujo típico: un scheduler (`agenda` / `bullmq` / `node-cron`) dispara jobs en el tiempo, y/o un consumidor de cola (`amqplib` / `bullmq` / `kafkajs`) reacciona a mensajes. Cada handler hace su trabajo (mandar email, push, recalcular, sincronizar) y reporta éxito/fallo a la infraestructura de jobs.
+
+Aunque el repo tenga `express` en deps, **no expone endpoints de negocio** — a lo sumo un `/health` para el orquestador. Si te piden agregar una "ruta", confirma: casi siempre es un job o un consumer nuevo, no un endpoint.
+
+Reglas de oro:
+- **Idempotencia**: un job/mensaje puede entregarse más de una vez. Todo handler debe ser seguro de re-ejecutar (claves de deduplicación, upserts, chequear estado antes de actuar).
+- **Graceful shutdown**: en `SIGTERM`/`SIGINT`, deja de tomar trabajo nuevo, espera a que los jobs en vuelo terminen (con timeout) y cierra conexiones (DB, broker) antes de salir. Nunca mates un job a la mitad sin re-encolar.
+- **Errores explícitos**: un fallo se reintenta con backoff o va a una dead-letter; nunca se traga en silencio. El logging va por el `Logger` estructurado, nunca `console.log`.
+- **Nada de `process.env`** fuera del módulo de config.
+
+Aplica las skills según la capa que toques:
+- `worker-lifecycle` — bootstrap, graceful shutdown, healthcheck, no servir HTTP de negocio.
+- `job-scheduling` — definir/agendar jobs (agenda/bullmq), idempotencia, reintentos con backoff.
+- `queue-consumers` — consumir mensajes (amqplib/bullmq), `ack`/`nack`, dead-letter, backpressure.
+
+El logging y el flujo de tickets/PR los cubre el harness base (agentes `leader`, `implementer`, `reviewer`, `commit-pr-pilot` y las skills core).