alepha 0.20.8 → 0.21.0

package/README.md

@@ -9,7 +9,7 @@
 />
 Alepha
 </h1>
-<p>TypeScript Framework Made Easy</p>
+<p>One full-stack TypeScript framework. No glue.</p>
 <a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/v/alepha.svg" alt="npm version"/></a>
 <a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/l/alepha.svg" alt="license"/></a>
 <a href="https://codecov.io/gh/feunard/alepha"><img src="https://codecov.io/gh/feunard/alepha/graph/badge.svg?token=ZDLWI514CP" alt="coverage"/></a>
@@ -18,26 +18,40 @@ Alepha
 
 ## What is Alepha?
 
-Full-stack TypeScript framework for agentic era. Define your schema once — get database, API, types, and forms.
+Alepha is a full-stack TypeScript framework built for the agentic era.
+
+Everything between your code and the runtime — HTTP server, routing, auth, queues, storage, jobs, SSR — is rewritten clean and integrated for Node, Bun, and Cloudflare Workers. Two load-bearing layers are deliberately *not* reinvented: **React** for UI and **Drizzle** for SQL. No library glue, no config sprawl: one small, consistent surface of typed primitives.
+
+That small surface is the point. AI coding agents (Claude Code, Codex) work best against a narrow, predictable API — so they generate predictable, consistent code you can actually review.
 
 - **One schema, everywhere** — Database, API validation, TypeScript types, React forms — all from one definition
-- **Full autocomplete** — Client calls server with complete type safety, zero codegen
+- **One surface** — Every feature is a typed `$primitive`. No third-party glue to wire up or keep in sync
 - **Multi-runtime** — Same code runs on Node, Bun, and Cloudflare Workers
 - **Deploy anywhere** — Cloudflare, Vercel, Docker, bare metal
 
-Built on predictable conventions and typed primitives — works great with AI coding assistants (BYOA).
+## Architecture
+
+Each layer builds on the previous — use only what you need.
+
+| Layer          | Description | Primitives                                              |
+|----------------|-------------|---------------------------------------------------------|
+| **Foundation** | DI, lifecycle, config | `$inject`, `$env`, `$module`, `$hook`, `$logger`        |
+| **Backend**    | Database, queues, storage, API | `$entity`, `$action`, `$queue`, `$bucket`, `$scheduler` |
+| **Frontend**   | React with SSR, routing, i18n | `$page`, `$head`, `$atom`, `$dictionary`                |
+| **Platform**   | Users, auth, jobs, audits | `$realm`, `$job`, `$audit`, `$notification`             |
+
+## Built for agents
 
-Each layer builds on the previous.
+Every feature is one typed `$primitive` — no decorators, no file-system magic, no runtime metadata. An agent reading the code sees exactly what it does, in one place.
 
-| Layer        | Description | Primitives                                              |
-|--------------|-------------|---------------------------------------------------------|
-| **Core**     | DI, lifecycle, config | `$inject`, `$env`, `$module`, `$hook`, `$logger`        |
-| **Backend**  | Database, queues, storage, API | `$entity`, `$action`, `$queue`, `$bucket`, `$scheduler` |
-| **Frontend** | React with SSR, routing, i18n | `$page`, `$head`, `$atom`, `$dictionary`                |
-| **Modules**  | Users, auth, jobs, audits | `$realm`, `$job`, `$audit`, `$notification`             |
+For UI, Alepha keeps **React** as the coding interface — agents write standard React components, the most familiar surface in their training data, with no framework-specific dialect to get wrong. For SQL it builds on **Drizzle**, but wraps it completely: you write one typed `$entity` schema and a `$repository`, never Drizzle itself. One is a proven interface agents already know; the other is a proven engine they never have to think about.
+
+The smaller and more consistent the surface, the more reliably an agent generates correct code against it. Point your AI assistant at [`alepha.dev/llms.txt`](https://alepha.dev/llms.txt) for the full machine-readable API.
 
 ## Example
 
+Define an API, call it from a React page — typed end-to-end, no codegen, no glue.
+
 ```tsx
 // src/Api.ts
 import { t } from "alepha";
@@ -85,19 +99,16 @@ export class AppRouter {
 }
 ```
 
+The `Api` class is the only contract. `$client<Api>()` derives every call site from it — change a handler's return type and the page stops compiling.
+
 ## Getting Started
 
 Requirements: [Node.js](https://nodejs.org/) 22+ or [Bun](https://bun.sh/) 1.3+
 
 ```bash
-# L1: Backend only
-npx alepha init my-api --api
-
-# L2: React frontend (with or without backend)
-npx alepha init my-app --react
-
-# L3: Api, Frontend, Admin UI
-npx alepha init my-saas --saas
+npx alepha init my-api  --api     # REST API
+npx alepha init my-app  --react   # React app (SSR)
+npx alepha init my-saas --saas    # API + React + auth + admin panel
 ```
 
 ## Learn More