diff --git a/README.md b/README.md
index 414a13a..4e19eae 100644
--- a/README.md
+++ b/README.md
@@ -1,46 +1,102 @@
-# Astro Starter Kit: Basics
+# LabRe — Sistema de Préstamos LSC UABC
+
+Aplicación web para gestionar préstamos de material del Laboratorio de Sistemas Computacionales (Facultad de Ingeniería, UABC). Modela el vale físico multi-ítem: un trámite agrupa varios materiales, cada renglón con cantidad y descripción.
+
+**Producción**: https://prestamos.buglabs.dev · **Login**: exclusivo Google con correo `@uabc.edu.mx`
+
+## Roles
+
+- **Alumno**: navega el catálogo con búsqueda por texto y filtro por categoría, arma un vale multi-ítem, consulta el estado de sus préstamos.
+- **Admin**: aprueba/rechaza/marca devoluciones, gestiona inventario (grid con fotos), rastrea equipos por unidad individual (laptops, proyectores), reasigna unidades entre préstamos, consulta estadísticas con gráficas y exporta reportes CSV.
+
+## Stack
+
+- **Frontend**: Astro 7 (SSR, `output: 'server'`) + React 19 islands + Tailwind v4 (tokens en `src/styles/global.css`)
+- **Backend**: Supabase self-hosted (Postgres 15, GoTrue, PostgREST, Storage, Realtime)
+- **Aislamiento**: schema Postgres propio `prestamos` (coexiste con otras apps en la misma instancia)
+- **Auth**: Google OAuth restringido a `@uabc.edu.mx` (verificación a nivel aplicación en middleware)
+- **Gráficas**: recharts
+- **Hosting**: Docker + adaptador `@astrojs/node` detrás de Cloudflare Tunnel
+- **CI/deploy**: git + `docker compose up -d --build` en el homelab
+
+## Requisitos
+
+- Node 22.12+
+- Acceso a una instancia de Supabase con el schema `prestamos` (ver migraciones)
+- Cuenta Google `@uabc.edu.mx` para probar el flujo
+
+## Setup local
 
 ```sh
-npm create astro@latest -- --template basics
+cp .env.example .env    # llenar PUBLIC_SUPABASE_URL, PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY, PUBLIC_APP_URL
+npm install
+npm run dev             # http://localhost:4321
 ```
 
-> 🧑‍🚀 **Seasoned astronaut?** Delete this file. Have fun!
+Antes del primer login, aplica las migraciones y promuévete a admin manualmente:
 
-## 🚀 Project Structure
+```sql
+update prestamos.profiles set rol = 'admin' where email = 'tu-correo@uabc.edu.mx';
+```
 
-Inside of your Astro project, you'll see the following folders and files:
+## Base de datos
+
+Migraciones en `supabase/migrations/`, aplican con `psql -f <archivo>` contra la instancia. Cada migración es idempotente (usa `if not exists`, `drop policy if exists`, etc.) y trae su propio `BEGIN`/`COMMIT`.
+
+- `0001_init.sql` — schema, tablas base, RLS, triggers, seed.
+- `0002_solicitudes_multi_item.sql` — rediseño a "1 vale = N renglones", RPC `crear_solicitud`.
+- `0003_grid_unidades_realtime.sql` — imagen del material, unidades individuales, RPC `reasignar_unidad`, publication realtime, bucket público `materiales-fotos`.
+
+## Estructura
 
 ```text
-/
-├── public/
-│   └── favicon.svg
-├── src
-│   ├── assets
-│   │   └── astro.svg
-│   ├── components
-│   │   └── Welcome.astro
-│   ├── layouts
-│   │   └── Layout.astro
-│   └── pages
-│       └── index.astro
-└── package.json
+src/
+├── layouts/
+│   └── AppLayout.astro         # sidebar desktop + dock móvil + toaster + badge realtime
+├── lib/
+│   ├── supabase.ts             # server/browser clients (schema 'prestamos')
+│   ├── date.ts                 # todayMX() con Intl + DST correcto
+│   └── materialImg.ts          # URL pública del bucket
+├── middleware.ts               # auth + dominio + verificación de rol
+├── pages/
+│   ├── login.astro
+│   ├── alumno/
+│   │   ├── catalogo.astro      # grid + filtro categorías + buscador
+│   │   └── mis-prestamos.astro
+│   ├── admin/
+│   │   ├── index.astro         # panel con KPIs
+│   │   ├── solicitudes/        # bandeja, activos, historial
+│   │   ├── inventario/         # grid CRUD + categorías
+│   │   ├── estadisticas.astro  # 6 KPIs + 3 gráficas recharts
+│   │   └── reportes.astro      # filtros + export CSV
+│   └── api/                    # endpoints REST (guardados por middleware)
+├── components/
+│   ├── alumno/                 # SolicitudCart, AgregarMaterial, FiltroCategorias, BuscadorCatalogo
+│   ├── admin/                  # solicitudes, inventario (MaterialForm, UnidadesManager), estadisticas (Chart), BadgeSolicitudes
+│   └── Toaster.tsx             # notificaciones globales estilo Sileo
+└── styles/global.css           # tokens paleta UABC + sistema neobrutalista
 ```
 
-To learn more about the folder structure of an Astro project, refer to [our guide on project structure](https://docs.astro.build/en/basics/project-structure/).
+## Deploy
 
-## 🧞 Commands
+Ver `deploy/README.md` para el detalle. Flujo resumido:
 
-All commands are run from the root of the project, from a terminal:
+```sh
+git push
+ssh buglabs 'cd ~/labre-web && git pull && docker compose up -d --build'
+```
 
-| Command                   | Action                                           |
-| :------------------------ | :----------------------------------------------- |
-| `npm install`             | Installs dependencies                            |
-| `npm run dev`             | Starts local dev server at `localhost:4321`      |
-| `npm run build`           | Build your production site to `./dist/`          |
-| `npm run preview`         | Preview your build locally, before deploying     |
-| `npm run astro ...`       | Run CLI commands like `astro add`, `astro check` |
-| `npm run astro -- --help` | Get help using the Astro CLI                     |
+## Comandos
 
-## 👀 Want to learn more?
+| Comando           | Acción                                        |
+| :---------------- | :-------------------------------------------- |
+| `npm install`     | Instala dependencias                          |
+| `npm run dev`     | Dev server en `localhost:4321`                |
+| `npm run build`   | Compila a `./dist/` (SSR bundle)              |
+| `npm run preview` | Preview del build                             |
 
-Feel free to check [our documentation](https://docs.astro.build) or jump into our [Discord server](https://astro.build/chat).
+## Documentación interna
+
+- `AGENTS.md` — decisiones de arquitectura, bitácora de sesiones, backlog. Fuente única de verdad del progreso.
+- `DESIGN.md` — sistema de diseño (paleta UABC, tipografía, sombra dura, Text-on-Fill Rule).
+- `PRODUCT.md` — visión de producto y brand commitments.