feat: add initialization guide and validation steps to init.md; enhance UI layer rules with navigation patterns and search functionality

Author: Alejandro Caicedo

.ai/commands/init.md

@@ -0,0 +1,60 @@
+---
+description: Inicializa y valida el template
+agent: build
+---
+
+Usa @TEMPLATE_USAGE.md como checklist oficial.
+
+Objetivo: ejecutar automaticamente todo lo posible para dejar el proyecto listo.
+No inventes credenciales ni valores privados. No hagas cambios destructivos salvo que se pida explicitamente en argumentos.
+
+Argumentos opcionales en $ARGUMENTS:
+
+- `--clean-examples`: elimina el modulo de ejemplo y ajusta navegacion relacionada.
+- `--skip-checks`: no corre test/typecheck/lint.
+
+Pasos a ejecutar:
+
+1. Entorno
+
+- Si `.env` no existe, copia `.env.example` a `.env`.
+- Valida que existan `API_URL`, `SERVICE_PROVIDER`, `ROOT_USERNAME`, `ROOT_PASSWORD`.
+- Si faltan variables, agregalas usando placeholders seguros y marcando TODO.
+
+2. Firebase (solo validacion automatica)
+
+- Lee `SERVICE_PROVIDER` desde `.env`.
+- Si `SERVICE_PROVIDER=firebase`, verifica existencia de:
+  - `android/app/google-services.json`
+  - `ios/GoogleService-Info.plist`
+- Si faltan, no crees archivos falsos: reporta accion manual requerida.
+
+3. Seguridad (validacion)
+
+- Verifica si `ROOT_USERNAME`/`ROOT_PASSWORD` siguen en valores por defecto.
+- Si siguen por defecto, reporta recomendacion para cambiarlos/removerlos en produccion.
+
+4. Limpieza opcional
+
+- Solo si `$ARGUMENTS` contiene `--clean-examples`, elimina:
+  - `src/modules/examples/`
+  - `src/navigation/stacks/ExampleStackNavigator.tsx` (si existe)
+- Ajusta rutas/stacks/imports para que compile sin modulo examples.
+- Si NO se pasa `--clean-examples`, solo reporta esta tarea como pendiente.
+
+5. Verificaciones
+
+- Salvo que `$ARGUMENTS` contenga `--skip-checks`, ejecuta:
+  - `bun run test`
+  - `bun run typecheck`
+  - `bun run lint`
+
+6. CI/CD
+
+- Revisa `.github/workflows/` y reporta que cambios deben hacerse manualmente (secrets, jobs, deploy).
+
+Entrega final en formato breve:
+
+- `Hecho`: lista de acciones completadas.
+- `Pendiente manual`: lo que requiere decision/credenciales humanas.
+- `Errores`: comandos que fallaron y sugerencia puntual.

.ai/rules/layer-ui.md

@@ -8,6 +8,9 @@ The UI layer contains screens and screen-specific components.
 2. **State Handling**: Use `LoadingState`, `ErrorState`, `EmptyState` from `@components/layout`
 3. **Lists**: Use `FlashList` from `@shopify/flash-list`
 4. **Forms**: Use `react-hook-form` with `yupResolver`
+5. **Create Navigation from ListView**: There are two valid patterns to open `{Entity}FormView` from `{Entities}ListView`:
+   - Header action icon: `<Header onPress={onAdd{Entity}} pressIcon="plus" />`
+   - Floating Action Button: `<RootLayout fab={{ icon: 'plus', onPress: onAdd{Entity} }} />`
 
 ## File Structure
 
@@ -26,18 +29,37 @@ src/modules/{module}/ui/
 ## Golden Example: ListView Structure
 
 ```typescript
+// Variant A: FAB in RootLayout (Products)
 export function ProductsListView() {
-  const [searchText, setSearchText] = useState('');
-  const debouncedSearch = useDebounce(searchText, 500);
   const { navigate } = useNavigationProducts();
+  const onAddProduct = () => navigate(ProductsRoutes.ProductForm);
+
+  return (
+    <RootLayout
+      scroll={false}
+      toolbar={false}
+      fab={{ icon: 'plus', onPress: onAddProduct }}
+    >
+      <Header title="Productos" searchbar="products" />
+      <ProductList />
+    </RootLayout>
+  );
+}
+
+// Variant B: Header action icon (Users)
+export function UsersListView() {
+  const { navigate } = useNavigationUsers();
+  const onAddUser = () => navigate(UsersRoutes.UserForm);
 
   return (
     <RootLayout scroll={false} toolbar={false}>
       <Header
-        title="Productos"
-        onPress={() => navigate(ProductsRoutes.ProductForm)}
+        title="Usuarios"
+        onPress={onAddUser}
+        pressIcon="plus"
+        searchbar="users"
       />
-      <ProductList searchText={debouncedSearch} />
+      <UserList />
     </RootLayout>
   );
 }

.ai/rules/list-view-with-filters.md

@@ -35,6 +35,9 @@ This pattern complements `layer-ui.md` and `layer-application.md`.
    - Guards `onEndReached` with `isConnected && hasNextPage` to avoid offline fetches
    - Uses `ItemSeparatorComponent` from `@components/layout`
 7. **ListView Screen**: `{Entities}ListView` is layout-only — it orchestrates `FiltersBar` + `List` but contains NO data-fetching logic directly. Data fetching lives inside the list component or a dedicated hook.
+   - If the screen needs navigation to `{Entity}FormView`, use one of these valid patterns:
+     - Header action icon: `<Header onPress={onAdd{Entity}} pressIcon="plus" ... />`
+     - Floating Action Button: `<RootLayout fab={{ icon: 'plus', onPress: onAdd{Entity} }} ... />`
 8. **Persistence**: Persist active filters per source/entity via Zustand + MMKV. Re-hydrate on mount; sanitize stale keys when the source changes. Shared UI search state (e.g. for cross-screen search persistence) should live in `@modules/core/application/app.storage.ts`.
 9. **Query Key Fingerprint**: Serialize filters with `JSON.stringify` to build a stable cache fingerprint. Include the fingerprint in the `queryKey`.
 

.ai/skills/components-gallery/SKILL.md

@@ -1044,26 +1044,27 @@ import { RootLayout } from '@components/layout';
 
 ### Header
 
-List screen header with title, "Agregar" button, and search input.
+List screen header with title, action icon, and integrated app searchbar state.
 
 ```typescript
 import { Header } from '@components/layout';
 
 <Header
   title="Productos"
   onPress={() => navigate(ProductsRoutes.ProductForm)}
-  searchText={searchText}
-  setSearchText={setSearchText}
+  pressIcon="plus"
+  searchbar="products"
 />;
 ```
 
 **Props:**
 | Prop | Type | Description |
 |---|---|---|
 | `title` | `string` | Screen title (`h1` variant) |
-| `onPress` | `() => void` | "Agregar" button handler |
-| `searchText` | `string` | Controlled search input value |
-| `setSearchText` | `(text: string) => void` | Search input handler |
+| `onPress` | `() => void` | Header action handler |
+| `pressIcon` | `IconName` | Optional action icon (`'menu'` by default) |
+| `searchbar` | `SearchbarStorage` | Search storage key (`'products'`, `'users'`, etc.) |
+| `onPressFilter` | `() => void` | Optional filter action handler |
 
 ---
 
@@ -1322,53 +1323,25 @@ No props.
 
 ## STANDARD LIST SCREEN PATTERN
 
-Complete pattern combining layout components with FlashList:
+Complete pattern combining layout components with FlashList (FAB navigation variant):
 
 ```typescript
-import React, { useState } from 'react';
-import { FlashList } from '@shopify/flash-list';
-import {
-  RootLayout,
-  Header,
-  LoadingState,
-  ErrorState,
-  EmptyState,
-  ItemSeparatorComponent,
-} from '@components/layout';
-import { useDebounce } from '@utils/debounce';
+import React from 'react';
+import { RootLayout, Header } from '@components/layout';
+import { ProductList } from '@modules/products/ui/components/ProductList';
 
 export function ProductsListView() {
-  const [searchText, setSearchText] = useState('');
-  const debouncedSearch = useDebounce(searchText, 500);
   const { navigate } = useNavigationProducts();
-  const { data, isLoading, isError, error } = useProducts({
-    searchText: debouncedSearch,
-  });
+  const onAddProduct = () => navigate(ProductsRoutes.ProductForm);
 
   return (
-    <RootLayout scroll={false} toolbar={false}>
-      <Header
-        title="Productos"
-        onPress={() => navigate(ProductsRoutes.ProductForm)}
-        searchText={searchText}
-        setSearchText={setSearchText}
-      />
-      {isLoading && <LoadingState message="Cargando productos..." />}
-      {isError && <ErrorState message={error?.message} onRetry={refetch} />}
-      {!isLoading && !isError && !data?.length && (
-        <EmptyState
-          title="Sin productos"
-          message="No hay productos disponibles"
-        />
-      )}
-      {!isLoading && !isError && !!data?.length && (
-        <FlashList
-          data={data}
-          renderItem={({ item }) => <ProductItem product={item} />}
-          estimatedItemSize={64}
-          ItemSeparatorComponent={ItemSeparatorComponent}
-        />
-      )}
+    <RootLayout
+      scroll={false}
+      toolbar={false}
+      fab={{ icon: 'plus', onPress: onAddProduct }}
+    >
+      <Header title="Productos" searchbar="products" />
+      <ProductList />
     </RootLayout>
   );
 }

.ai/skills/create-layout-component/SKILL.md

@@ -253,63 +253,112 @@ const styles = StyleSheet.create({
 #### Header
 
 ```typescript
-import React from 'react';
+import React, { useMemo } from 'react';
 import { View, StyleSheet } from 'react-native';
 // Components
-import { Text, Button, TextInput } from '@components/core';
+import {
+  AnimatedPressable,
+  Icon,
+  IconName,
+  Text,
+  TextInput,
+} from '@components/core';
 // Theme
-import { useTheme } from '@theme/index';
+import { spacing, useTheme } from '@theme/index';
+import { useAppStorage } from '@modules/core/application/app.storage';
+import { SearchbarStorage } from '@modules/core/application/app.storage';
+
+interface SearchBarProps {
+  searchbar: SearchbarStorage;
+  onPressFilter?: () => void;
+}
+
+function SearchBar({ searchbar = '', onPressFilter }: SearchBarProps) {
+  const { searchText, setSearchText } = useAppStorage(
+    state => state.searchbar[searchbar] || {},
+  );
+
+  return (
+    <View style={styles.searchbar}>
+      <TextInput
+        value={searchText}
+        onChangeText={setSearchText}
+        placeholder="Buscar..."
+        containerStyle={styles.searchInput}
+      />
+      {onPressFilter ? (
+        <AnimatedPressable onPress={onPressFilter} style={styles.filterButton}>
+          <Icon name="filter" size={spacing.base} />
+        </AnimatedPressable>
+      ) : null}
+    </View>
+  );
+}
 
 interface HeaderProps {
   title: string;
   onPress?: () => void;
-  searchText?: string;
-  setSearchText?: (text: string) => void;
+  pressIcon?: IconName;
+  searchbar?: SearchbarStorage;
+  onPressFilter?: () => void;
 }
 
 export function Header({
   title,
   onPress,
-  searchText,
-  setSearchText,
+  pressIcon,
+  searchbar = '',
+  onPressFilter,
 }: HeaderProps) {
-  const theme = useTheme();
+  const {
+    colors: { surface, border },
+  } = useTheme();
+
+  const dynamicStyles = useMemo(
+    () => [
+      styles.container,
+      { backgroundColor: surface, borderBottomColor: border },
+    ],
+    [surface, border],
+  );
 
   return (
-    <View style={[styles.container, { borderColor: theme.colors.border }]}>
+    <View style={dynamicStyles}>
       <View style={styles.row}>
         <Text variant="h1">{title}</Text>
-        {onPress && (
-          <Button variant="primary" size="sm" onPress={onPress}>
-            Agregar
-          </Button>
-        )}
+        {onPress ? (
+          <AnimatedPressable onPress={onPress} testID="header-action-button">
+            <Icon name={pressIcon || 'menu'} size={spacing.lg} />
+          </AnimatedPressable>
+        ) : null}
       </View>
-      {setSearchText && (
-        <TextInput
-          value={searchText}
-          onChangeText={setSearchText}
-          placeholder="Buscar..."
-          style={styles.search}
-        />
-      )}
+
+      <SearchBar searchbar={searchbar} onPressFilter={onPressFilter} />
     </View>
   );
 }
 
 const styles = StyleSheet.create({
   container: {
-    padding: 16,
+    padding: spacing.md,
     borderBottomWidth: 1,
-    gap: 12,
+    gap: spacing.md,
   },
   row: {
     flexDirection: 'row',
     justifyContent: 'space-between',
     alignItems: 'center',
   },
-  search: {
-    marginTop: 8,
+  searchbar: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: spacing.sm,
+  },
+  searchInput: {
+    flex: 1,
+  },
+  filterButton: {
+    padding: spacing.md,
   },
 });
 ```