@tinya-code/gas-admin-ui 0.1.0-alpha.4 → 0.2.0-alpha.0

package/README.md

@@ -1,26 +1,59 @@
 # @tinya-code/gas-admin-ui
 
-Motor de render del ecosistema `@tinya-code`: el front que **sólo declara** su
-dominio (`schemas/*.schema.ts`) y consume el motor compilado — mismo contrato
-que `@tinya-code/gas-admin` en el back, pero para Angular.
+Angular rendering engine for the `@tinya-code` ecosystem. You declare your domain in typed schema files — the engine renders views, forms, lists, actions, shell, and routes. You never write components by hand.
+
+## Requirements
+
+| Requirement | Version / detail |
+| --- | --- |
+| Angular | `22.2` (standalone, signals) |
+| Angular peers | `@angular/{cdk,common,core,forms,platform-browser,router} ^22.2` |
+| Icons / charts | `@lucide/angular ^1.51`, `chart.js ^4.5` |
+| CSS | Tailwind v4 — with the engine's `@source` ([step 2](#2-declare-the-tailwind-source)) |
+| Backend | [`@tinya-code/gas-admin`](https://www.npmjs.com/package/@tinya-code/gas-admin) — its CLI generates and validates front-end schemas |
+
+---
+
+## Quick start from scratch
+
+### 1. Install the package
 
 ```bash
 npm i @tinya-code/gas-admin-ui
 ```
 
-**Peers:** `@angular/{cdk,common,core,forms,platform-browser,router} ^22.2`,
-`@lucide/angular ^1.51`, `chart.js ^4.5`.
+An Angular 22.2 project already has `@angular/*` — verify the remaining peers (`@lucide/angular`, `chart.js`).
+
+### 2. Declare the Tailwind source
 
-## Uso mínimo
+In `src/styles.css`:
 
-**1. Wiring** — `app.config.ts` entrega el dominio al motor (catálogo +
-HTTP con interceptor del envelope + loaders de config/sesión):
+```css
+/* Required: lets Tailwind scan the engine's templates for utility classes */
+@source '../node_modules/@tinya-code/gas-admin-ui/fesm2022';
+
+@import 'tailwindcss';
+@import './styles/theme.css';   /* your design tokens */
+@import './styles/base.css';    /* your base resets   */
+```
+
+Without this the app compiles and tests pass, but the engine UI renders with no styles.
+
+### 3. Wire the engine — `app.config.ts`
 
 ```ts
+// src/app/app.config.ts
+import { ApplicationConfig, provideBrowserGlobalErrorListeners } from '@angular/core';
+import { provideRouter } from '@angular/router';
 import { API_URL, provideGasAdmin } from '@tinya-code/gas-admin-ui';
+import { routes } from './app.routes';
+import { schemas } from './schemas/registry';
+import { authSchema } from './schemas/auth.schema';
+import { environment } from '../environments/environment';
 
 export const appConfig: ApplicationConfig = {
   providers: [
+    provideBrowserGlobalErrorListeners(),
     provideRouter(routes),
     provideGasAdmin({ schemas, auth: authSchema }),
     { provide: API_URL, useValue: environment.apiUrl },
@@ -28,97 +61,568 @@ export const appConfig: ApplicationConfig = {
 };
 ```
 
-**2. Rutas** — `app.routes.ts`:
+```ts
+// src/environments/environment.ts
+export const environment = {
+  production: false,
+  apiUrl: 'http://localhost:3000/api/v1',
+};
+```
+
+### 4. Declare routes — `app.routes.ts`
 
 ```ts
+// src/app/app.routes.ts
+import { Routes } from '@angular/router';
 import { authGuard, shellRoutes } from '@tinya-code/gas-admin-ui';
+import { schemas } from './schemas/registry';
+
+const firstResource = schemas[0]?.id || 'dashboard';
 
 export const routes: Routes = [
   { path: '', pathMatch: 'full', redirectTo: firstResource },
-  { path: 'login', loadComponent: () => import('@tinya-code/gas-admin-ui').then((m) => m.Login) },
-  { path: '', canActivate: [authGuard], loadChildren: () => shellRoutes },
+  {
+    path: 'login',
+    loadComponent: () => import('@tinya-code/gas-admin-ui').then((m) => m.Login),
+  },
+  {
+    path: '',
+    canActivate: [authGuard],
+    loadChildren: () => shellRoutes,
+  },
   { path: '**', redirectTo: firstResource },
 ];
 ```
 
-**3. Dominio** — la carpeta `src/app/schemas/` se genera desde el back. Con
-el CLI del back instalado (`npm i -D @tinya-code/gas-admin`):
+`login` lives outside the shell on purpose — if it were inside, `authGuard` would block it.
+
+### 5. Declare auth — `auth.schema.ts`
+
+```ts
+// src/app/schemas/auth.schema.ts
+import type { AuthSchema } from '@tinya-code/gas-admin-ui';
+
+export const authSchema: AuthSchema = {
+  providers: ['password'],
+  loginFields: [
+    { key: 'email', type: 'email', required: true },
+    { key: 'password', type: 'password', required: true },
+  ],
+  redirectAfterLogin: '/dashboard',
+  rememberMe: false,
+};
+```
+
+### 6. Declare your schemas — `registry.ts`
+
+```ts
+// src/app/schemas/registry.ts
+import type { ResourceSchema } from '@tinya-code/gas-admin-ui';
+import { dashboardSchema } from './dashboard.schema';
+import { businessSchema } from './business.schema';
+import { clientsSchema } from './clients.schema';
+import { ranksSchema } from './ranks.schema';
+import { rewardsSchema } from './rewards.schema';
+import { couponsSchema } from './coupons.schema';
+import { feedbackSchema } from './feedback.schema';
+
+export const schemas: ResourceSchema[] = [
+  dashboardSchema,
+  businessSchema,
+  clientsSchema,
+  ranksSchema,
+  rewardsSchema,
+  couponsSchema,
+  feedbackSchema,
+];
+```
+
+The array order determines both menu order and the default redirect route.
+
+### 7. Start the app
 
 ```bash
-npx gas-admin scaffold
+npm start
 ```
 
-Por cada recurso de `api/schema/resources/` escribe su `*.schema.ts`
-(campos, validators, enums y endpoint derivados de la proyección back), más
-`registry.ts` (el array ordenado que alimenta menú y rutas),
-`auth.schema.ts` (las claves exactas del `input` de `/auth/login`) y
-`seed-catalog.ts` (siembra el catálogo para los specs). Los `label` salen
-de las keys: reemplazá los placeholders por los del dominio y sumá las
-vistas/filtros que quieras (el recorrido de capacidades está en la
-cabecera de `registry.ts`). Estructura equivalente a mano si preferís
-escribirlo. La validación de que todo siga coincidiendo con el back la hace
-`gas-admin validate --with-front` (`contract-check` de
-`@tinya-code/gas-admin`).
+The shell starts at `/login` and, once authenticated, shows the sidebar menu and views derived from your schemas.
 
-## Requisitos del consumidor
+---
 
-### Tailwind v4 — `@source` obligatorio
+## Schema examples (real implementations)
 
-Tailwind genera utilities escaneando **tus** fuentes; el motor vive en
-`node_modules` y no lo escanea solo. Agregar en `styles.css`:
+The examples below are taken from a production consumer of this library.
 
-```css
-@source '../node_modules/@tinya-code/gas-admin-ui/fesm2022';
+### Dashboard — `kind: 'dashboard'`
+
+A read-only panel with metric cards. No list, no form.
+
+```ts
+// src/app/schemas/dashboard.schema.ts
+import type { ResourceSchema } from '@tinya-code/gas-admin-ui';
+
+export const dashboardSchema: ResourceSchema = {
+  id: 'dashboard',
+  label: 'Panel',
+  labelPlural: 'Dashboard',
+  kind: 'dashboard',
+  uiViews: {
+    overview: { type: 'dashboard' },
+  },
+  endpoint: {
+    get: '/admin/dashboard',
+  },
+  keyField: 'id',
+  titleField: 'label',
+  listColumns: [],
+  fields: [],
+  widgets: [
+    { type: 'metric-card', key: 'totalClients',      label: 'Total Clients',       hint: 'Registered memberships',    width: 4 },
+    { type: 'metric-card', key: 'activeClients30d',  label: 'Active (30d)',         hint: 'Visited in last 30 days',   width: 4 },
+    { type: 'metric-card', key: 'visitsThisMonth',   label: 'Visits This Month',   hint: 'Current month',             width: 4 },
+    { type: 'metric-card', key: 'averageRating',     label: 'Average Rating',      hint: 'Historical satisfaction',   width: 4 },
+    { type: 'metric-card', key: 'issuedCoupons',     label: 'Issued Coupons',      hint: 'All time',                  width: 4 },
+    { type: 'metric-card', key: 'usedCoupons',       label: 'Redeemed Coupons',    hint: 'Effective rewards',         width: 4 },
+  ],
+};
+```
+
+---
+
+### Singleton — `kind: 'singleton'` with sections layout
+
+One record, no list. The form is divided into labelled sections.
+
+```ts
+// src/app/schemas/business.schema.ts
+import type { ResourceSchema } from '@tinya-code/gas-admin-ui';
+
+export const businessSchema: ResourceSchema = {
+  id: 'business',
+  label: 'My Business',
+  labelPlural: 'My Business',
+  kind: 'singleton',
+  uiViews: {
+    settings: { type: 'form' },
+  },
+  endpoint: {
+    get: '/admin/businesses/current',
+    update: '/admin/businesses/current',
+  },
+  keyField: 'key',
+  titleField: 'name',
+  listColumns: [],
+  layout: {
+    mode: 'sections',
+    sections: [
+      { id: 'general',  label: 'General' },
+      { id: 'branding', label: 'Design & Card' },
+      { id: 'social',   label: 'Social & Links' },
+    ],
+  },
+  fields: [
+    { key: 'name',     type: 'text',   label: 'Business Name', required: true, validators: { minLength: 2, maxLength: 120 }, section: 'general',  width: 6 },
+    { key: 'slug',     type: 'slug',   from: 'name', label: 'Slug', required: true, lockAfterCreate: true, section: 'general', width: 6 },
+    { key: 'timezone', type: 'text',   label: 'Timezone', required: true, help: 'e.g. America/Lima', section: 'general', width: 6 },
+    {
+      key: 'visitResetPolicy',
+      type: 'select',
+      label: 'Visit Reset Policy',
+      section: 'general',
+      width: 6,
+      options: [
+        { value: 'none',    label: 'None' },
+        { value: 'monthly', label: 'Monthly' },
+        { value: 'yearly',  label: 'Yearly' },
+      ],
+    },
+    { key: 'colorPrimary',   type: 'text',  label: 'Primary Color (HEX)',   placeholder: '#4A2C11', section: 'branding', width: 6 },
+    { key: 'colorSecondary', type: 'text',  label: 'Secondary Color (HEX)', placeholder: '#D4A373', section: 'branding', width: 6 },
+    { key: 'logoUrl',        type: 'image', label: 'Logo', readonly: true, section: 'branding', width: 12 },
+    { key: 'googleReviewUrl', type: 'url',  label: 'Google Reviews URL', section: 'social', width: 6 },
+    { key: 'instagramUrl',   type: 'url',   label: 'Instagram', section: 'social', width: 6 },
+  ],
+};
+```
+
+---
+
+### Collection with full CRUD — `kind: 'collection'`
+
+List + create + edit. Includes search, filters, and field validators.
+
+```ts
+// src/app/schemas/ranks.schema.ts
+import type { ResourceSchema } from '@tinya-code/gas-admin-ui';
+
+export const ranksSchema: ResourceSchema = {
+  id: 'ranks',
+  label: 'Rank',
+  labelPlural: 'Ranks',
+  kind: 'collection',
+  uiViews: {
+    list:   { type: 'list' },
+    create: { type: 'form', path: 'new' },
+    edit:   { type: 'form', path: ':key/edit' },
+  },
+  endpoint: {
+    list:   '/admin/businesses/current/ranks',
+    get:    '/admin/businesses/current/ranks/{key}',
+    create: '/admin/businesses/current/ranks',
+    update: '/admin/businesses/current/ranks/{key}',
+    remove: '/admin/businesses/current/ranks/{key}',
+  },
+  keyField: 'id',
+  titleField: 'name',
+  search: ['name'],
+  filters: [
+    { key: 'includeInactive', label: 'Include Inactive', type: 'boolean' },
+  ],
+  listColumns: [
+    { key: 'level',       label: 'Level' },
+    { key: 'name',        label: 'Name' },
+    { key: 'minVisits',   label: 'Min Visits' },
+    { key: 'benefitType', label: 'Benefit Type' },
+    { key: 'benefitValue',label: 'Value' },
+    { key: 'active',      label: 'Active', format: 'boolean' },
+  ],
+  fields: [
+    { key: 'name',     type: 'text',   label: 'Rank Name', required: true, validators: { minLength: 1, maxLength: 80 } },
+    { key: 'level',    type: 'number', label: 'Level', required: true, min: 1, help: 'Must be unique among active ranks' },
+    { key: 'minVisits',type: 'number', label: 'Minimum Visits', required: true, min: 0 },
+    {
+      key: 'benefitType',
+      type: 'select',
+      label: 'Benefit Type',
+      required: true,
+      options: [
+        { value: 'none',                label: 'None' },
+        { value: 'percentage_discount', label: 'Percentage Discount' },
+        { value: 'fixed_discount',      label: 'Fixed Discount' },
+        { value: 'free_item',           label: 'Free Item' },
+        { value: 'priority',            label: 'Priority Service' },
+      ],
+    },
+    { key: 'benefitValue',       type: 'number',   label: 'Benefit Value' },
+    { key: 'benefitDescription', type: 'textarea', label: 'Benefit Description', validators: { maxLength: 200 } },
+    { key: 'color',              type: 'text',     label: 'Color (HEX)', placeholder: '#CD7F32' },
+    { key: 'iconUrl',            type: 'image',    label: 'Icon', readonly: true },
+    { key: 'active',             type: 'boolean',  label: 'Active', readonlyOn: 'create' },
+  ],
+};
+```
+
+---
+
+### Read-only collection with detail view
+
+List + detail only — no create, no edit form.
+
+```ts
+// src/app/schemas/clients.schema.ts
+import type { ResourceSchema } from '@tinya-code/gas-admin-ui';
+
+export const clientsSchema: ResourceSchema = {
+  id: 'clients',
+  label: 'Client',
+  labelPlural: 'Clients',
+  kind: 'collection',
+  uiViews: {
+    list:   { type: 'list' },
+    detail: { type: 'detail', path: ':key' },
+    edit:   { type: 'form',   path: ':key/edit' },
+  },
+  endpoint: {
+    list:   '/admin/businesses/current/clients',
+    get:    '/admin/businesses/current/clients/{key}',
+    update: '/admin/businesses/current/clients/{key}/status',
+    // no create / remove → those actions won't appear in the UI
+  },
+  keyField: 'membershipId',
+  titleField: 'name',
+  search: ['name', 'phone'],
+  filters: [
+    { key: 'active', label: 'Active', type: 'boolean' },
+  ],
+  listColumns: [
+    { key: 'name',        label: 'Name' },
+    { key: 'phone',       label: 'Phone' },
+    { key: 'email',       label: 'Email' },
+    { key: 'totalVisits', label: 'Total Visits' },
+    { key: 'lastVisitAt', label: 'Last Visit' },
+    { key: 'active',      label: 'Active', format: 'boolean' },
+    { key: 'registeredAt',label: 'Registered' },
+  ],
+  detail: {
+    enabled: true,
+    headerFields: ['name', 'phone', 'active'],
+  },
+  fields: [
+    { key: 'membershipId',        type: 'readonly-text', label: 'Membership ID',     readonly: true },
+    { key: 'name',                type: 'text',          label: 'Name',              readonly: true },
+    { key: 'phone',               type: 'phone',         label: 'Phone',             readonly: true },
+    { key: 'email',               type: 'email',         label: 'Email',             readonly: true },
+    { key: 'active',              type: 'boolean',       label: 'Active Membership' },
+    { key: 'totalVisits',         type: 'number',        label: 'Total Visits',      readonly: true },
+    { key: 'currentPeriodVisits', type: 'number',        label: 'Period Visits',     readonly: true },
+    { key: 'registeredAt',        type: 'date',          label: 'Registered At',     readonly: true },
+    { key: 'lastVisitAt',         type: 'date',          label: 'Last Visit',        readonly: true },
+  ],
+};
+```
+
+---
+
+### Read-only collection with select filter
+
+```ts
+// src/app/schemas/coupons.schema.ts
+import type { ResourceSchema } from '@tinya-code/gas-admin-ui';
+
+export const couponsSchema: ResourceSchema = {
+  id: 'coupons',
+  label: 'Coupon',
+  labelPlural: 'Coupons',
+  kind: 'collection',
+  uiViews: {
+    list:   { type: 'list' },
+    detail: { type: 'detail', path: ':key' },
+  },
+  endpoint: {
+    list: '/admin/businesses/current/coupons',
+    get:  '/admin/businesses/current/coupons/{key}',
+  },
+  keyField: 'id',
+  titleField: 'code',
+  search: ['code'],
+  filters: [
+    {
+      key: 'status',
+      label: 'Status',
+      type: 'select',
+      options: [
+        { value: 'issued',  label: 'Issued' },
+        { value: 'used',    label: 'Redeemed' },
+        { value: 'expired', label: 'Expired' },
+      ],
+    },
+  ],
+  listColumns: [
+    { key: 'code',     label: 'Code' },
+    { key: 'status',   label: 'Status' },
+    { key: 'issuedAt', label: 'Issued' },
+    { key: 'expiresAt',label: 'Expires' },
+    { key: 'usedAt',   label: 'Redeemed' },
+  ],
+  detail: {
+    enabled: true,
+    headerFields: ['code', 'status', 'issuedAt'],
+  },
+  fields: [
+    { key: 'id',        type: 'readonly-text', label: 'ID',         readonly: true },
+    { key: 'code',      type: 'text',          label: 'Code',       readonly: true },
+    { key: 'status',    type: 'text',          label: 'Status',     readonly: true },
+    { key: 'issuedAt',  type: 'date',          label: 'Issued At',  readonly: true },
+    { key: 'expiresAt', type: 'date',          label: 'Expires At', readonly: true },
+    { key: 'usedAt',    type: 'date',          label: 'Redeemed At',readonly: true },
+  ],
+};
+```
+
+---
+
+## Firebase Auth
+
+The package supports federated authentication with Google and Firebase Email/Password via the decoupled `FirebaseAuthAdapter`. Firebase is declared as an optional `peerDependency` — the library does not bundle it.
+
+### 1. Install Firebase in the consumer app
+
+```bash
+npm i firebase
 ```
 
-Sin esto, la app compila pero la UI pierde las clases del motor (visual roto,
-tests en verde).
+### 2. Declare providers in `AuthSchema`
 
-### Tests del consumidor — desde `node_modules` (sin alias)
+```ts
+// src/app/schemas/auth.schema.ts
+import type { AuthSchema } from '@tinya-code/gas-admin-ui';
 
-Los specs del consumidor resuelven `@tinya-code/gas-admin-ui` desde
-`node_modules` (la versión publicada en `dependencies`), sin alias de
-`tsconfig.spec.json` ni clone del repo como directorio hermano en CI: la
-app y los tests usan la MISMA copia compilada ⇒ Angular se instancia una
-sola vez (verificado en admin-schema: 116/116 sin alias). Para probar un
-cambio del motor en el consumidor: publicar un alpha y bumpear la
-dependencia.
+// Option A — password only (default, no Firebase required)
+export const authSchema: AuthSchema = {
+  providers: ['password'],
+  loginFields: [
+    { key: 'email',    type: 'email',    required: true },
+    { key: 'password', type: 'password', required: true },
+  ],
+  redirectAfterLogin: '/dashboard',
+  rememberMe: false,
+};
 
-Si una combinación de versiones llegara a reproducir `NG0203`/`NG01908`
-(doble instancia de Angular: vitest prebundlea `@angular/*` pero la lib
-corre en ESM nativo), el workaround es compilar la lib desde source en el
-grafo de tests (`paths` en `tsconfig.spec.json` apuntando al source del
-paquete) junto con un clone del repo como directorio hermano en CI.
+// Option B — Google only
+export const authSchema: AuthSchema = {
+  providers: ['google'],
+  loginFields: [],
+  redirectAfterLogin: '/dashboard',
+  rememberMe: false,
+  firebase: { exchangeEndpoint: '/auth/firebase' },
+};
 
-## API pública
+// Option C — Google + Password (both)
+export const authSchema: AuthSchema = {
+  providers: ['google', 'password'],
+  loginFields: [
+    { key: 'email',    type: 'email',    required: true },
+    { key: 'password', type: 'password', required: true },
+  ],
+  redirectAfterLogin: '/dashboard',
+  rememberMe: false,
+  firebase: { exchangeEndpoint: '/auth/firebase' },
+};
+```
+
+### 3. Implement the adapter and wire it in `app.config.ts`
 
-Sólo lo exportado por `public-api.ts` es contrato; el resto es privado y
-puede cambiar entre alphas. Superficie v1:
+```ts
+// src/app/app.config.ts
+import { initializeApp } from 'firebase/app';
+import {
+  getAuth,
+  GoogleAuthProvider,
+  signInWithPopup,
+  signInWithEmailAndPassword,
+  signOut,
+} from 'firebase/auth';
+import {
+  API_URL,
+  provideGasAdmin,
+  provideFirebaseAdapter,
+} from '@tinya-code/gas-admin-ui';
+import type { FirebaseAuthAdapter } from '@tinya-code/gas-admin-ui';
+import { environment } from '../environments/environment';
+
+const firebaseApp  = initializeApp(environment.firebase);
+const firebaseAuth = getAuth(firebaseApp);
 
-| Grupo | Exportaciones |
+class AppFirebaseAuthAdapter implements FirebaseAuthAdapter {
+  async signInWithGoogle(): Promise<string> {
+    const cred = await signInWithPopup(firebaseAuth, new GoogleAuthProvider());
+    return cred.user.getIdToken();
+  }
+  async signInWithEmailAndPassword(email: string, password: string): Promise<string> {
+    const cred = await signInWithEmailAndPassword(firebaseAuth, email, password);
+    return cred.user.getIdToken();
+  }
+  async signOut(): Promise<void> {
+    await signOut(firebaseAuth);
+  }
+}
+
+export const appConfig: ApplicationConfig = {
+  providers: [
+    provideRouter(routes),
+    provideGasAdmin({ schemas, auth: authSchema }),
+    provideFirebaseAdapter(new AppFirebaseAuthAdapter()),  // ← add this
+    { provide: API_URL, useValue: environment.apiUrl },
+  ],
+};
+```
+
+### 4. Backend endpoint — `POST /auth/firebase`
+
+The library sends the Firebase ID token using the **same envelope transport** as every other request. Your backend must:
+
+1. Receive `{ idToken: string }` in the payload.
+2. Verify it with the Firebase Admin SDK (`getAuth().verifyIdToken(idToken)`).
+3. Return `{ token, user }` — identical shape to `/auth/login`.
+
+```json
+// Request body (Content-Type: text/plain)
+{ "token": null, "method": "POST", "path": "/auth/firebase", "payload": { "idToken": "..." } }
+
+// Response
+{ "token": "<your-app-jwt>", "user": { "id": "...", "email": "...", "name": "...", "role": "..." }, "meta": {} }
+```
+
+For a full consumer integration guide including a backend handler example, environment config, and a pre-production checklist, see [`doc/firebase-consumer-example.md`](../../doc/firebase-consumer-example.md).
+
+---
+
+## Consumer requirements
+
+### Tailwind v4 — mandatory `@source`
+
+Tailwind generates utilities by scanning **your** source files. The engine lives in `node_modules` and is not scanned by default. The `@source` directive in `styles.css` (step 2) is required — without it the app compiles and tests pass green, but the engine UI renders without any styles.
+
+### Tests — resolve from `node_modules` (no alias)
+
+Consumer specs must resolve `@tinya-code/gas-admin-ui` from `node_modules` (the published, compiled version), without `tsconfig.spec.json` aliases. This guarantees Angular is instantiated exactly once. To test a library change, publish an alpha and bump the dependency.
+
+---
+
+## Generated schema structure (`npx gas-admin scaffold`)
+
+```text
+src/app/schemas/
+├── auth.schema.ts        # auth provider and login fields
+├── registry.ts           # ordered array that feeds the menu and routes
+├── seed-catalog.ts       # seeds the catalog for specs
+├── dashboard.schema.ts   # kind: dashboard
+├── business.schema.ts    # kind: singleton
+├── clients.schema.ts     # kind: collection (read-only with detail)
+├── ranks.schema.ts       # kind: collection (full CRUD)
+├── rewards.schema.ts     # kind: collection (full CRUD)
+├── coupons.schema.ts     # kind: collection (read-only with filters)
+└── feedback.schema.ts    # kind: collection (read-only with search)
+```
+
+`scaffold` fails with exit 1 if the target folder already contains `*.ts` files — use `--force` to regenerate.
+
+---
+
+## Public API
+
+Only what `public-api.ts` exports is stable contract; everything else is private and may change between alphas.
+
+| Group | Exports |
 | --- | --- |
-| Wiring | `provideGasAdmin`, `GAS_SCHEMAS`, `setSchemaCatalog`, `getSchema`, `allSchemas`, `getAuth`, `API_URL` |
-| Rutas/guard | `authGuard`, `shellRoutes`, `resourceRoutes` |
-| Componentes | `Login`, `Sidebar`, `Dashboard`, `ListView`, `FormView`, `ResourcePage`, `ComposerHost`, `FieldHost`, `ConfirmDialog`, `Toast` |
-| Servicios | `ApiService`, `AuthService`, `NotificationService`, `DataSourceService`, `UploadService`, `ErrorMapperService`, `apiErrorInterceptor` |
-| Modelos | `ResourceSchema`, `AuthSchema`, `ResourceAction`, tipos de `views`/`columns`/`fields` |
-| Registros | `fieldDescriptors`, `columnFormatDescriptors`, `layoutDescriptors`, `viewDescriptors`, `registerRenderDescriptor`, `renderKinds`, `ValidatorName` |
+| Wiring & catalog | `provideGasAdmin`, `provideFirebaseAdapter`, `GAS_SCHEMAS`, `setSchemaCatalog`, `getSchema`, `allSchemas`, `getAuth`, type `GasAdminConfig` |
+| Tokens & adapters | `API_URL`, `FIREBASE_AUTH_ADAPTER`, type `FirebaseAuthAdapter` |
+| Routes & guard | `authGuard`, `shellRoutes`, `resourceRoutes` |
+| Pages | `Login`, `Dashboard`, `ListView`, `FormView`, `ResourcePage` |
+| Components | `Sidebar`, `ComposerHost`, `FieldHost`, `ConfirmDialog`, `Toast` |
+| Services | `ApiService`, `AuthService` (+ `SESSION_TOKEN_KEY`, `SESSION_USER_KEY`), `NotificationService`, `DataSourceService`, `UploadService`, `ErrorMapperService`, `apiErrorInterceptor` |
 | Forms | `buildFormSchema`, `seedModel`, `buildPayload` |
+| Schema models | `ResourceSchema`, `AuthSchema`, `AuthProvider`, `FirebaseAuthConfig`, `ResourceAction`, `ApiError` and the full field/widget/view/layout vocabulary |
+| Render registries | `fieldDescriptors`, `columnFormatDescriptors`, `viewDescriptors`, `layoutDescriptors`, `renderKinds` |
+| Custom render | `registerRenderDescriptor`, `unregisterRenderDescriptor`, `provideRenderDescriptors`, `getRenderDescriptor`, `isSupported`, `isRenderSupported`, types `RenderKind`, `ComponentRenderKind` |
+| Composition | `validateComposition`, `MAX_DEPTH`, `SchemaCompositionError` |
+| Custom actions | `registerAction`, `getAction`, `actionsFor`, `actionType`, `actionTypes`, types `ActionDescriptor`, `ActionSurface`, `ActionContext`, `ActionResult` |
+| Validators | type `ValidatorName` |
+| Utilities | `interpolateTemplate` |
+
+---
+
+## See also
+
+- **Backend** — domain declaration, `doc`, `validate`:
+  [`@tinya-code/gas-admin`](https://github.com/Tinya-Code/gas-admin) → `docs/guia-de-uso.md`.
+- **Firebase consumer guide** — full wiring, backend contract, pre-production checklist:
+  [`doc/firebase-consumer-example.md`](../../doc/firebase-consumer-example.md).
+
+---
 
-## Desarrollo (este repo)
+## Development (this repo)
 
 ```bash
-ng build gas-admin-ui     # ng-packagr → dist/gas-admin-ui (fesm2022 + types)
-ng test gas-admin-ui      # vitest: 489 tests del motor (fixtures congelados)
+ng build gas-admin-ui     # ng-packagr → dist/gas-admin-ui
+ng test gas-admin-ui      # vitest: engine tests
 ```
 
-Publicación (tag `alpha` obligatorio en prereleases):
+Publish (npm requires explicit `--tag` for pre-releases):
 
 ```bash
 npm publish ./dist/gas-admin-ui --tag alpha
 ```
 
-Los specs que renderizan los schemas **reales** de un consumidor no viven
-acá (la lib no puede importar al consumidor): viven en el repo del
-consumidor importando desde este paquete — ver los 16 specs de
-integración de `admin-schema`.
+- `dist/` is gitignored — the build is always local and never committed.
+- Specs that render a consumer's real schemas live in the consumer repo, not here.