toiljs 0.0.85 → 0.0.87

package/docs/getting-started/project-structure.md

@@ -0,0 +1,163 @@
+# Project structure
+
+A tour of every folder and file in a toiljs project, what each one is for, and the single most important question: **where does this code run, the browser or the edge?**
+
+## Why this matters
+
+toiljs blends frontend and backend into one repo, so the same `.ts` file extension can mean two very different things. A file in `client/` becomes JavaScript that runs in your user's browser. A file in `server/` becomes WebAssembly that runs on the edge, with different rules and different available APIs. Knowing which folder you are in tells you what you are allowed to do. Keep this mental split and everything else falls into place.
+
+```mermaid
+flowchart TD
+    subgraph Browser["Runs in the browser"]
+        C["client/*"]
+    end
+    subgraph Edge["Runs on the edge (WebAssembly)"]
+        S["server/*  ->  release.wasm"]
+    end
+    subgraph Generated["Generated glue (types + config)"]
+        SH["shared/server.ts"]
+        CFG["toil.config.ts / toilconfig.json"]
+    end
+    C -. "typed calls" .-> SH
+    SH -. "HTTP / realtime" .-> S
+    S --> DB[("ToilDB")]
+```
+
+## The top level
+
+These files sit in your project root.
+
+| File | What it is | Runs where |
+| --- | --- | --- |
+| `package.json` | Scripts (`dev`, `build`, `lint`, `typecheck`, `format`) and dependencies (`toiljs`, `react`, `toilscript`, ...) | tooling only |
+| `toil.config.ts` | **Client and build config.** Uses `defineConfig` to set SEO, images, page transitions, and dev options. | tooling only |
+| `toilconfig.json` | **Server (wasm) build config** for toilscript: the entry file, the output `.wasm` path, and low-level compile options. You rarely edit this. | tooling only |
+| `tsconfig.json` | TypeScript config for the client (`client/`, `shared/`, `emails/`). Extends `toiljs/tsconfig`. | tooling only |
+| `eslint.config.js` | Linting preset (`toiljs/eslint`). | tooling only |
+| `.prettierrc` | Formatting preset (`toiljs/prettier`). | tooling only |
+| `.prettierignore` | Files Prettier should skip (generated files). | tooling only |
+| `.gitignore` | Ignores `build/`, `.toil/`, generated files, and your `.env` files. | tooling only |
+| `.vscode/settings.json` | Tells VS Code to use the project's TypeScript so the toilscript editor plugin loads. | editor only |
+| `toil-env.d.ts` | **Generated** editor types for client globals like `Toil.Link` and `Toil.Image`. Do not edit. | editor only |
+| `toil-routes.d.ts` | **Generated** list of your real route names, so `Toil.Link href="..."` type-checks. Filled in on the first build. | editor only |
+| `README.md` | Your project's readme. | docs |
+| `CLAUDE.md`, `AGENTS.md`, etc. | Optional AI-assistant hint files that point tools at the toiljs docs. | docs |
+
+Two folders you may also see at the root:
+
+- **`.toil/`** is a working directory toiljs manages (a build cache and a copy of the docs). It is gitignored. You never edit it.
+- **`.env` and `.env.secrets`** are files **you** create when you need local environment variables or secrets during `toiljs dev`. They are gitignored so you never commit them, and the edge loads their real values out of band in production. Your server reads them with `Environment.get("KEY")` and `Environment.getSecure("KEY")`. See [Environment and secrets](../services/environment.md).
+
+## `client/` (runs in the browser)
+
+This is a normal React app. You can use React libraries and browser APIs here freely.
+
+```text
+client/
+  toil.tsx              the entry point; mounts your app
+  layout.tsx            the root layout wrapping every page
+  404.tsx               the not-found page
+  global-error.tsx      the top-level error page
+  routes/               file-based pages
+  components/           shared React components
+  styles/               global stylesheets
+  public/               static files served as-is
+```
+
+- **`toil.tsx`** is the entry file. It imports your global styles and calls `Toil.mount(...)` to start the app. You rarely change it beyond the style imports.
+- **`layout.tsx`** is your root layout: the header, footer, and page shell that wrap every route. Its `children` prop is the current page.
+- **`404.tsx`** renders when no route matches. **`global-error.tsx`** renders when a route throws.
+- **`routes/`** is where pages live, and the file name **is** the URL. `routes/index.tsx` is `/`, `routes/about.tsx` is `/about`, `routes/blog/[slug].tsx` is `/blog/:slug`. This is called **file-based routing**. See [Routing](../frontend/routing.md).
+- **`components/`** holds React components you reuse across pages. Nothing here is a route.
+- **`styles/`** holds your global CSS (or Sass, Less, or Stylus, if you chose one). See [Styling](../frontend/styling.md).
+- **`public/`** holds static files served exactly as they are: `favicon`, `robots.txt`, and an `images/` folder (reachable at `/images/...`). The `public/index.html` is the base HTML shell your app mounts into.
+
+A single global, `Toil`, is available in client code without an import (for `Toil.Link`, `Toil.Image`, and `Toil.Head`). It is typed by the generated `toil-env.d.ts`.
+
+## `server/` (runs on the edge, as WebAssembly)
+
+This is your backend. It is compiled by toilscript into one `.wasm` file. Remember the two rules: **memory resets every request**, and **this is not Node.js** (a strict TypeScript subset, no arbitrary npm packages). See [Backend overview](../backend/README.md) and [Types](../concepts/types.md).
+
+```text
+server/
+  main.ts               the entry: wires the handler + imports your modules
+  tsconfig.json         server-only TS config (loads the toilscript editor plugin)
+  toil-server-env.d.ts  generated editor types for server globals
+  core/                 your request handler and shared logic
+  models/               @data classes
+  routes/               @rest controllers (HTTP)
+  services/             @service / @remote (typed RPC)
+  migrations/           ToilDB schema migrations
+  scheduled/            reserved for scheduled tasks
+```
+
+- **`main.ts`** is the entry the build compiles. It does three required things: it sets `Server.handler` (a factory that returns one fresh handler per request), it re-exports the wasm entry points (`export * from 'toiljs/server/runtime/exports'`), and it defines the `abort` hook. It also `import`s your other server modules so a direct toilscript run builds the same code.
+- **`core/`** holds your top-level `ToilHandler` (often `AppHandler.ts`): the first code that sees each request. It can dispatch to your `@rest` controllers and then fall through to any hand-written logic.
+- **`models/`** holds your `@data` classes, one type per file. A `@data` class is a typed message that can cross the wire between client and server (and into ToilDB). See [Data types](../backend/data.md).
+- **`routes/`** holds your `@rest` controllers: classes decorated with `@rest`, `@get`, and `@post` that expose HTTP endpoints. See [HTTP routes](../backend/rest.md).
+- **`services/`** holds `@service` classes and free `@remote` functions: typed remote calls the client makes as plain function calls (no URLs). See [Typed RPC](../backend/rpc.md).
+- **`migrations/`** holds ToilDB schema migrations. When you change the shape of a stored `@data` type, you add a `<Type>.migration.ts` here that carries old records forward. The compiler enforces this convention. See [Documents](../database/documents.md).
+- **`scheduled/`** is reserved for scheduled tasks. New decorated files anywhere under `server/` are picked up automatically by the build.
+- **`tsconfig.json`** and **`toil-server-env.d.ts`** are editor-support files. They teach your editor about the server globals (`crypto`, `Cookie`, `Environment`, and friends) so it stops flagging them. They do not affect the build.
+
+### How the build discovers your server code
+
+You do not register routes in a config file. The compiler scans every `.ts` file under `server/` and picks up anything that declares a decorated surface (`@rest`, `@service`, `@remote`, `@data`, `@user`, `@database`, and so on). Importing those files from `main.ts` is still good practice: it keeps a direct `toilscript` run building the exact same server.
+
+## `shared/` (generated glue)
+
+```text
+shared/
+  server.ts             GENERATED typed client (do not edit)
+```
+
+**`shared/server.ts` is written for you** by the server build. It contains:
+
+- A typed `Server` object the browser uses to call your backend: `Server.REST.*` for HTTP routes and `Server.<service>.*` for RPC.
+- The client-side codecs for every `@data` class, so responses come back as real typed objects.
+- A `getUser()` helper for reading the signed-in user on the client.
+
+Because it is generated, it does not exist in a fresh project and it is gitignored. It appears the first time you run `toiljs dev` or `toiljs build`. Never hand-edit it; change your server code and it regenerates.
+
+## `build/` (compiled output)
+
+```text
+build/
+  server/release.wasm   your compiled backend (+ release.wat, a readable text form)
+  client/               the bundled React app (from Vite)
+```
+
+This is what actually ships. It is gitignored and recreated by `toiljs build`. You do not edit anything here.
+
+## Putting it together: one request
+
+```mermaid
+sequenceDiagram
+    participant B as Browser (client/)
+    participant SH as shared/server.ts
+    participant W as server.wasm (server/)
+    participant DB as ToilDB
+    B->>SH: Server.REST.likes.like()
+    SH->>W: HTTP POST /likes
+    W->>DB: counter.add(key, 1)
+    W-->>SH: typed LikeCount response
+    SH-->>B: { count }
+```
+
+The browser calls a typed method, the generated client turns it into an HTTP request, your `.wasm` handles it and touches ToilDB, and a typed result comes back. You wrote both ends; the middle is generated.
+
+## Gotchas and notes
+
+- **A `.ts` file's folder decides its rules.** The same code that works in `client/` may not compile in `server/`, because the server is a strict subset without Node APIs.
+- **Do not edit generated files.** `shared/server.ts`, `toil-env.d.ts`, `toil-routes.d.ts`, and `toil-server-env.d.ts` are all regenerated by the build and will overwrite your changes.
+- **One `@data` type per file** under `models/` keeps things tidy and matches the convention the tooling expects.
+- **`build/` and `.toil/` are disposable.** Delete them and the next build recreates them.
+
+## Related
+
+- [Your first app](./first-app.md)
+- [Frontend overview](../frontend/README.md) and [Routing](../frontend/routing.md)
+- [Backend overview](../backend/README.md)
+- [Database overview](../database/README.md)
+- [Configuration](../concepts/config.md)
+- [Decorators reference](../concepts/decorators.md)

package/docs/introduction/README.md

@@ -0,0 +1,41 @@
+# Understanding toil
+
+This section is the "why." It explains what toil is, the problem it solves, how it works underneath, and why it is built the way it is. If you read nothing else first, read this: it is what turns "another framework" into "oh, that is the point."
+
+## The one big idea
+
+Almost every website has a split personality. The pretty part (pages, buttons) is served from servers all over the world, close to you. The important part (the database, where your data lives and changes) sits in **one place**, one region, often one machine. Post a comment in Tokyo when the database is in Virginia and your click flies halfway around the planet and back before anything happens.
+
+toil removes the split. Your **frontend** (React) and **backend** (TypeScript, compiled to a tiny WebAssembly program) both run at the **edge**, near your users, and **ToilDB** is distributed too, so writes do not travel to one far-away box. One language, one project, one deploy, running close to everyone.
+
+```mermaid
+flowchart TB
+    subgraph Ordinary["The ordinary web"]
+        U1["User in Tokyo"] -->|fast| E1["Edge (pretty part)"]
+        E1 -->|slow, one region| DB1[("Database in Virginia")]
+    end
+    subgraph Toil["toil"]
+        U2["User in Tokyo"] -->|fast| E2["Edge near Tokyo<br/>(frontend + backend + data)"]
+    end
+```
+
+That is the entire pitch. The rest of these pages is how toil pulls it off, and why almost nobody else does.
+
+## Read these in order
+
+1. **[Why toil? Who is it for?](./why-toil.md)** The problem with today's stacks, who benefits most, and the honest cases against.
+2. **[The modern stack](./modern-stack.md)** The full catalog of modern tech baked in with zero setup.
+3. **[How toil works](./how-it-works.md)** The whole machine end to end: React client, WebAssembly backend, the edge, ToilDB, the four compute tiers.
+4. **[What makes toil hyper-scalable](./hyperscale.md)** What "hyper-scale" means, and the mechanisms that let one small program serve the planet.
+5. **[How toil is distributed](./distributed.md)** The hardest problem in web infrastructure, distributing the writes, and how ToilDB solves it.
+6. **[toil versus other frameworks](./vs-other-frameworks.md)** An honest comparison with Next.js, Rails, Django, serverless, edge runtimes, and backend-as-a-service.
+7. **[Why toil is built this way (the RSG bar)](./design-principles.md)** The rubric toil grades itself against.
+
+## The short version
+
+- **Who it is for:** people building real products who want global speed and reliability without a platform team or ten stitched-together vendors. See [Why toil](./why-toil.md).
+- **Why it is fast:** the code runs next to the user, with no slow trip to a central origin. See [Hyper-scale](./hyperscale.md).
+- **Why it is different:** it distributes the writes, not just the reads. See [Distributed](./distributed.md).
+- **Why it is safe:** the backend is a sandbox, passwords never reach the server in a usable form, secrets never ship in the code, and the browser verifies every asset it loads. See [Security](../concepts/security.md).
+
+When you are ready to build, jump to [Getting started](../getting-started/README.md).

package/docs/introduction/design-principles.md

@@ -0,0 +1,55 @@
+# Why toil is built this way (the RSG bar)
+
+toil is opinionated on purpose. Almost every design decision traces back to one internal rubric it
+holds itself against, and this page shows the rubric and the choice each axis forces.
+
+## The rubric in a paragraph
+
+**RSG** (Resilience and Scale Grade) is toil's own internal rubric for how resilient, distributed,
+fast, lean, and secure an app really is, scored as a single letter from AAA down to D. It grades
+nine axes, and the one rule that matters is this: **your grade is your weakest axis**, never the
+average and never the best. To earn AAA, all nine must be AAA at the same time. A globally edged
+frontend on a single-region database is capped by the database. A worldwide system serving a
+one-second app is capped by latency. The lowest column sets the grade, every time. RSG is not an
+external certification and no auditor issues it; it is a design mirror the team holds up to find
+the weakest link and fix it first. The full rubric lives at the repository root in
+[`RSG.md`](../../RSG.md).
+
+The reason for the weakest-link rule is the most common lie in this space: calling something
+"global scale" because the read path is global, while the write path is one box in one region.
+Averaging would let that one strong axis hide the weak one. The minimum refuses to.
+
+## The nine axes, and the one choice each one forces
+
+Each axis names a way a system can be weak. Each row is the single design decision toil makes so
+that axis cannot be the thing that caps it.
+
+| RSG axis | What it grades | The toil design choice that hits it |
+| --- | --- | --- |
+| **Topology + distribution** | How close your code runs to users, and in how many places | Edge compute: your frontend and backend both run on nodes next to users, worldwide, not in one origin region. |
+| **Availability** | What survives a failure | Cross-region failover with no single point of failure, so losing a node or a region does not take the app down. |
+| **Data path** | Where data is read and *written* (the hard one) | ToilDB's per-key-home model distributes the **writes**, not just the reads. See [How toil is distributed](./distributed.md). |
+| **Delivered p99 latency** | The end-to-end time the user actually feels (measured, under 100ms = AAA) | An allocation-free hot path, measured rather than assumed, so the response is fast for real, not just on paper. |
+| **Program performance + efficiency** | Hot-path code quality, and cost per request (no brute-forcing latency with a big server bill) | No blocking work on the request path; the fast path does no wasted work, so speed comes from the code, not from overprovisioning. |
+| **Dependencies** | How much of your critical path you own (zero third-party on it = AAA) | An owned, batteries-included stack: nothing third-party sits on the critical request path for you to be unable to inspect or fix. |
+| **Security** | How hard the system is to break, and how bad a breach would be | Post-quantum password login (the password never reaches the server in usable form), sandboxed WebAssembly backends, and Subresource Integrity on every asset. See [Security](../concepts/security.md). |
+| **Client performance + reach** | How well the shipped app runs on old and low-end devices as data grows | A lean React client: a small bundle and linear-or-better hot paths, so it stays smooth on weak hardware, not just new flagships. |
+| **Modern stack + compatibility** | Current protocols, *with* graceful fallback for older clients | HTTP/3, QUIC, and WebTransport where they fit, negotiating down cleanly so nobody one version behind gets a blank screen. |
+
+## The punchline
+
+toil is opinionated because being AAA on **every** axis at once forces these choices. You cannot
+reach the top grade with a fast frontend on a centralized database, or a global system running
+slow code, or a modern stack that only works on the newest browser. The weakest-link rule closes
+every one of those escape hatches. Any framework that lets a single axis slip is, by its own
+honest scoring, not AAA. Holding all nine at once is the whole reason toil looks the way it does.
+
+## Related
+
+- [How toil is distributed](./distributed.md): the data-path axis in depth, and why distributing
+  writes is the hard one.
+- [What makes toil hyper-scalable](./hyperscale.md): the topology, latency, and program axes in
+  practice.
+- [Security](../concepts/security.md): the security axis and its hard caps.
+- [`RSG.md`](../../RSG.md) at the repository root: the full rubric, the internal mirror this page
+  summarizes.

package/docs/introduction/distributed.md

@@ -0,0 +1,74 @@
+# How toil is distributed
+
+Distributing a website's reads is easy. Distributing its writes is the hard part almost nobody solves, and it is why "global" apps are usually only half global. Here is the problem, and how ToilDB (the database built into toil) actually distributes the writes.
+
+## Reads are easy, writes are hard
+
+A read never changes anything, so you copy your data to servers worldwide and let each user read the nearest copy. Every copy agrees: a reader in Tokyo and one in Paris both get a fast, local answer.
+
+A write is a change, and two writes to the *same thing* can collide. A counter says `10`. Tokyo and Paris both read `10`, both add one, both write `11`. The real answer was `12`, so one add vanished with no error. That is a **write conflict**.
+
+You could make every copy agree before accepting a write, but the network will eventually split (a **partition**), and the **CAP tradeoff** says that during a split you keep only two of consistency, availability, and partition tolerance. You either refuse the write (correct but unavailable) or accept it on one side and reconcile later (available but briefly inconsistent). Distributing writes is a real tradeoff to design around.
+
+
+## So almost everyone centralizes the write database
+
+Faced with that, nearly every stack keeps **one** primary write database in **one** region and spreads only read replicas worldwide. All writes funnel to that one box, one at a time, so conflicts cannot happen.
+
+It is a reasonable choice, and it hides two costs the [RSG rubric](./design-principles.md) flags on its data-path axis:
+
+- **Far writes are slow.** Post from Tokyo to a primary in Virginia and your write crosses the planet and back before anything saves. The page was local; the action was not.
+- **The primary is a single point of failure.** One region holds every write, so if it has a bad day, nothing anywhere can be changed.
+
+The read path is global; the write path is one machine in one city. Under RSG's weakest-link rule, that single data path caps the whole system.
+
+## ToilDB's answer: every key has a home
+
+ToilDB gives **every key its own home**. A key is the label you store data under (a user id, a username, a room name; see the [database overview](../database/README.md)). Each key is assigned one home: the single source of truth that orders its writes.
+
+Two things follow, and together they are the whole trick:
+
+- **Writes to one key are safe.** Every write to a key travels to that key's home, which **serializes** them (applies them one at a time, in order). Both counter adds are ordered at the counter's home, so the result is `12`. No global lock over the whole database.
+- **Writes spread worldwide.** Different keys get different homes, so total write load spreads out. Tokyo users' data can home near Tokyo, Paris users' near Paris. No single box every write funnels through, so no single bottleneck.
+
+```mermaid
+flowchart TB
+    WA["write user:aiko"] --> KA["home near Tokyo<br/>key: user:aiko"]
+    WB["write user:bruno"] --> KB["home near Paris<br/>key: user:bruno"]
+    WC["write room:general"] --> KC["home near Ohio<br/>key: room:general"]
+    KA -.->|"replicate for<br/>local reads"| KB
+    KA -.-> KC
+```
+
+Reads stay local: each key still replicates out, so a reader anywhere gets a nearby copy. Those copies are **eventually consistent**, meaning that for a brief moment (usually milliseconds) after a write lands at the home, a far read can lag before it catches up. For almost all app data this is invisible; the [database overview](../database/README.md) has the full picture.
+
+Which location owns a key is decided by a shared formula (rendezvous hashing) every node computes the same way, so any node routes a write to the right home with no central coordinator. A key's home can move to follow demand, without rehashing the database.
+
+## The seven families pick the right consistency tool
+
+One "home orders the writes" rule fixes the counter, but different jobs want different guarantees. So ToilDB ships **seven families**, each a collection type tuned for one shape of data, each exposing only the operations that are safe and fast for it:
+
+| Family | What it gives |
+| --- | --- |
+| [Documents](../database/documents.md) | A record you look up by id |
+| [Counters](../database/counters.md) | Conflict-free tallies: adds from anywhere merge, no lost updates |
+| [Unique](../database/unique.md) | A one-of-a-kind claim (a username); the home picks exactly one winner |
+| [Capacity](../database/capacity.md) | Limited stock (tickets); reserve/confirm/cancel holds prevent overselling |
+| [Events](../database/events.md) | An append-only log in one agreed order |
+| [Membership](../database/membership.md) | Sets of who belongs to what |
+| [View](../database/views.md) | A read-optimized result a background job builds |
+
+Distributing writes is not one problem with one answer; each family is the right tool for one shape.
+
+## The hard machinery toil provides so you do not have to
+
+The per-key-home model only works if a lot of unglamorous machinery runs reliably across a flaky network, and ToilDB owns it: per-key **placement** and safe **rehoming** (a rising epoch plus a fencing token so the old owner stops the instant the new one takes over), ordered **cross-region replication** with per-stream cursors that detect and backfill gaps, **idempotent apply** so redelivered writes cannot double-count, **capacity escrow** and **tenant quotas**, and **failover** with snapshot re-seeding for a cell that has fallen too far behind. Getting all of these right at once is exactly why truly distributed websites are rare.
+
+**Still being finished:** live multi-cell **WAN routing** (wiring many real regions into one running mesh) and the full database-level **leader fencing** on the write path (the host-side leader gate is the current version). The design is settled; the last-mile host wiring is what remains.
+
+## Related
+
+- [The database (ToilDB)](../database/README.md): families, keys and values, and eventual consistency in depth.
+- [Compute tiers](../concepts/tiers.md): where your code runs, the compute side of the same story.
+- [What makes toil hyper-scalable](./hyperscale.md): the mechanisms that let one small program serve the planet.
+- [Why toil is built this way (the RSG bar)](./design-principles.md): the rubric behind the data-path axis.

package/docs/introduction/how-it-works.md

@@ -0,0 +1,74 @@
+# How toil works
+
+What your project compiles into, and what happens when a user makes a request. Every term is defined as it appears.
+
+## What "build" produces
+
+`toiljs build` turns your one TypeScript project into three outputs, because your code has two homes: the browser and the edge.
+
+- **Client bundle.** Your React app plus any pages toil renders ahead of time, packaged as ordinary web files (HTML, JS, CSS, images). Runs in the browser.
+- **`server.wasm`.** Your backend. You write it as normal TypeScript classes in `server/`, and the **toilscript** compiler turns it into WebAssembly. It runs on the edge, not in the browser and not in Node.
+- **Generated typed client (`shared/`).** A small browser-side client toil generates from the shape of your backend. Your React code calls a normal-looking async function, and the types line up end to end: rename a field on the server and the frontend stops compiling until you fix it.
+
+**WebAssembly** (WASM), in two sentences: a compact binary format that runs at close to native speed with no interpreter warm-up, and runs **sandboxed**, in a locked box that cannot open files, reach the operating system, or make network calls on its own. It touches the outside world only through the small, fixed set of functions the host hands it (read the request, build a response, query the database), which is what makes it safe to pack many apps onto one shared box. ([Why that matters for scale](./hyperscale.md).)
+
+## The request lifecycle
+
+It all happens on the **edge node nearest the user**, with no trip to a central origin.
+
+Two terms first:
+
+- **The edge** is a fleet of servers spread across many cities. A request is served by whichever node is physically closest, which means lower latency (the delay before something happens).
+- An **origin server** is the single far machine a traditional site calls back to for anything real. toil has none: your backend and its database are replicated out to the edge, so there is nothing far away to call.
+
+```mermaid
+sequenceDiagram
+    participant U as User's browser
+    participant E as Nearest edge node
+    participant W as server.wasm (your handler)
+    participant DB as ToilDB (local copy)
+
+    U->>E: Request (page or API call)
+    alt Path is a page/asset it can serve
+        E-->>U: Prerendered / SSR page or static file
+    else Path is a dynamic API call
+        E->>W: Decode bytes, call your handler
+        W->>DB: Read / write (a local, nearby copy)
+        DB-->>W: Result
+        W-->>E: Response
+        E-->>U: Response
+    end
+```
+
+1. **The request lands on the closest edge node.** The network routes the user there automatically.
+2. **Page or code?** If the path is a prerendered page, a server-rendered page, or a static asset, the edge serves it and never wakes your backend. This is the fast path for most page loads.
+3. **Otherwise it runs your backend.** The edge decodes the raw bytes into a `Request` object and calls the single entry point of your `server.wasm`, which routes to your handler.
+4. **Your handler reads and writes locally.** When it needs stored data it talks to [ToilDB](../database/README.md), which has a copy right there at the edge. No ocean crossing.
+5. **Your handler returns a `Response`,** toil encodes it back to bytes, and the edge sends it to the browser.
+
+The mental model for your backend: a function of the request. Bytes in, bytes out, one request at a time.
+
+### Stateless by default
+
+A fresh copy of your handler serves each request, and the next request might be served by a node on the other side of the planet. So anything you set on a field does not survive. This is a feature: interchangeable copies with nothing to coordinate are what let the backend scale worldwide. When you need something to persist, write it to ToilDB. See the [backend overview](../backend/README.md#stateless-by-default).
+
+## The pieces
+
+Five parts make up a running toil app; you have now met all of them.
+
+| Piece | What it is | Where it runs |
+| --- | --- | --- |
+| **React client** | Your frontend UI, the client bundle from the build. | The user's browser |
+| **toilscript backend** | Your TypeScript backend compiled to `server.wasm`. | The edge |
+| **The Dacely edge** | The Rust runtime that terminates the connection, serves pages, and runs your WASM. | Servers in many cities |
+| **ToilDB** | The globally distributed database, replicated next to your code. | The edge |
+| **The four tiers** | Where and for how long a piece of backend code lives. | L1 nearest, up to L4 worldwide |
+
+Most of your backend is the stateless, per-request handler above (tier **L1**). Long-lived connections (L2/L3) and single-worldwide scheduled jobs (L4 daemons) run on other tiers. Full detail, and how the build assigns them, is on the [tiers page](../concepts/tiers.md).
+
+## Related
+
+- [Backend overview](../backend/README.md): the request/response model and the sandbox in depth.
+- [The database (ToilDB)](../database/README.md): where persistent, shared state lives.
+- [Compute tiers](../concepts/tiers.md): L1 request, L2/L3 stream, L4 daemon.
+- [What makes toil hyper-scalable](./hyperscale.md): why this design serves the planet cheaply.

package/docs/introduction/hyperscale.md

@@ -0,0 +1,51 @@
+# What makes toil hyper-scalable
+
+**Hyper-scale** is serving very large, worldwide traffic at low latency without rebuilding your app as it grows. The test: when traffic goes from a thousand users to a hundred million across every continent, do you rewrite the system, or just run more of it?
+
+Most stacks scale the easy half (serving pages and cached reads from many places) but leave the hard half (writes, where data actually changes) in one region, so they slow down at once when enough far-away users start writing. toil scales both halves out together. It promises a design where scaling is cheap, adding more identical edge nodes with no central part everything funnels through, not a specific requests-per-second number.
+
+## The mechanisms
+
+**1. Compute next to the user.** toil has no origin server. Your `server.wasm` and its database are replicated to the [edge](../concepts/tiers.md) and run on the node nearest each user, so there is no slow hop to a faraway box. This is the biggest latency win, and the rest of the design exists to support it.
+
+```mermaid
+flowchart LR
+    subgraph Origin["Everything funnels to one origin"]
+        direction TB
+        A1["User (Tokyo)"] -->|slow| O[("Origin + DB<br/>(Virginia)")]
+        A2["User (Paris)"] -->|slow| O
+        A3["User (Sydney)"] -->|slow| O
+    end
+    subgraph Toil["Edge + distributed DB scales out"]
+        direction TB
+        B1["User (Tokyo)"] --> E1["Edge + data (Tokyo)"]
+        B2["User (Paris)"] --> E2["Edge + data (Paris)"]
+        B3["User (Sydney)"] --> E3["Edge + data (Sydney)"]
+        E1 <-.->|"replicate"| E2
+        E2 <-.->|"replicate"| E3
+    end
+```
+
+The left side has one hot center every user drags a request to and back from, a bottleneck no amount of caching removes. The right side has no center: add a city, add an edge node.
+
+**2. WASM isolation and density.** Each site compiles to its own tiny, [sandboxed](./how-it-works.md#what-build-produces) WASM module that starts fast and cannot touch another tenant's files, memory, or network. Hard per-request limits (a memory cap in the tens of MiB, a **hard compute cap** that cuts off a looping handler, rate limits, and hostile-wasm containment) let one box safely hold many tenants at once, which is what makes compute in many cities affordable instead of a luxury.
+
+**3. Allocation-free hot path.** The code that runs on every request wastes nothing: no per-request allocations, and no garbage-collection pauses (so no random latency spikes under load). This earns latency with lean code rather than by overprovisioning hardware to hide slow code, which is a bar toil holds itself to explicitly ([the RSG rubric](./design-principles.md)).
+
+**4. Stateless tier over a distributed database.** A fresh copy of your handler serves each request and keeps nothing, so every node is interchangeable and you scale out purely by adding more. The data they share lives in [ToilDB](../database/README.md), which distributes **writes** too, not just reads, so there is no single box every write funnels through. The write mechanism and its honest trade-off (eventual consistency) are in [how toil is distributed](./distributed.md).
+
+**5. Modern transport.** The edge speaks HTTP/3 over QUIC (with graceful fallback to HTTP/2 and HTTP/1.1, plus WebTransport for realtime), and its networking is tuned to keep the connection-level cost of each request low as traffic grows. You configure none of it.
+
+The five reinforce each other: take any one away and a bottleneck reappears. No density and edge compute is too expensive to spread; no distributed writes and the database caps you; a wasteful hot path and you are back to buying latency with servers.
+
+## An honest note on numbers
+
+This describes a design, not a benchmark: real throughput and latency depend on your hardware, where your users are, how your data is shaped, and how your handler is written, and toil removes central bottlenecks and keeps per-request cost low without making a slow handler fast or repealing the speed of light between continents.
+
+## Related
+
+- [How toil is distributed](./distributed.md): distributing the writes, the hard problem this rests on.
+- [Why toil is built this way (the RSG bar)](./design-principles.md): the efficiency check behind the hot path.
+- [Compute tiers](../concepts/tiers.md): L1 through L4, and the stateless request model.
+- [How toil works](./how-it-works.md): the build outputs and the request lifecycle.
+- [The database (ToilDB)](../database/README.md): families, homes, and eventual consistency.

package/docs/introduction/modern-stack.md

@@ -0,0 +1,36 @@
+# The modern stack: what toil gives you that others do not
+
+Most frameworks give you a way to write code and then send you shopping: a database, an auth provider, email, a rate limiter, analytics, a realtime service, a job runner, all wired together and kept in sync by you. toil owns those parts instead: built in, and on from the first line. This page is the catalog of what ships; for how the edge and distribution actually work, see [How toil works](./how-it-works.md) and [How toil is distributed](./distributed.md).
+
+## What is built in
+
+| Feature | What it is | Why it matters |
+| --- | --- | --- |
+| Edge compute over HTTP/3 | Frontend and backend both run on servers in many cities, over HTTP/3 with automatic fallback to HTTP/2 or HTTP/1.1. | Code runs next to the user, so there is no slow round trip to one origin. |
+| [ToilDB](../database/README.md) | A global database with no connection string and seven families (documents, unique, counter, events, capacity, membership, view). | Distributes writes, not just reads, so a thousand servers can write at once without a single-region bottleneck (trade: eventual consistency). |
+| [Post-quantum auth](../auth/README.md) | Password login via `server: { auth: true }`; the password becomes an ML-DSA-44 key in the browser and the server stores only the public key. | The password never crosses the wire in a replayable form, so a breached server yields no usable passwords, and there is no identity vendor to rent. |
+| Automatic SRI | A SHA-384 fingerprint on every local script, preload, and stylesheet, plus an import map covering the whole module graph. | Tampered assets simply do not run, even if a CDN or cache hop is compromised. |
+| [Email](../services/email.md) | `EmailService.send(...)` or a reusable `EmailTemplate` with `{{placeholder}}` bodies, through a provider you configure once. | Verification codes, resets, and receipts are one call: validated, per-tenant capped, and off the worker while the provider replies. |
+| [Rate limiting](../services/ratelimit.md) | `@ratelimit` on a route, counted at the edge in an exact cross-worker limiter keyed on the caller's network address. | Over-limit clients are rejected before your code runs, blunting brute-force and spam. |
+| [Analytics and time series](../services/analytics.md) | The `Analytics` global reads your site's own counters: `self()` for a snapshot, `series(metric, range)` for a graph. | A real usage dashboard with no extra code and no analytics vendor, correct across every edge location. |
+| [Realtime streaming](../realtime/README.md) | A `@stream` class with `@connect`/`@message`/`@close`/`@disconnect` hooks, opened from React with `useChannel`; WebTransport in production, WebSocket in dev. | A resident instance stays alive per connection and remembers state next to the user (chat, presence, progress). |
+| [Daemons and @derive](../background/README.md) | `@daemon` runs one global background worker on a schedule (interval or cron) with lease-based failover; `@derive` re-runs when its source data changes to refresh a View. | Nightly jobs and rollups run once globally, with no cron server, queue, or leader election to run yourself. |
+| [Owned globals](../services/README.md) | No-import cookies (read/set, sign or encrypt), crypto (hash, HMAC, AES, random), time (the edge clock), and environment/secrets. | Your request's small dependencies live in one system, and your compiled program carries no credential. |
+| [Toolchain](../cli/README.md) | `toiljs create` scaffolding, a shared ESLint config, Prettier plus a decorator-aware plugin, an editor plugin, one CLI, and `toiljs doctor --fix`. | Set up for you and wired by types, so a server change is a compile error at your desk, not a production bug. |
+| LLM-friendly docs | A machine-readable `llms.txt` plus a generated `.toil/docs/` folder and pointer files (`CLAUDE.md`, `AGENTS.md`, editor rules), refreshed on every build. | An assistant reads your current conventions instead of guessing from stale training. |
+
+## Built in versus assemble it yourself
+
+| Capability | toil (built in, zero setup) | Typical stack (you assemble it) |
+| --- | --- | --- |
+| Edge and transport | Frontend and backend worldwide over HTTP/3 | A separate edge product, often reads-only |
+| Database | ToilDB: global, distributed writes, seven families | A managed database, usually single-region for writes |
+| Auth | Post-quantum login; the server holds no password | A rented identity provider or hand-rolled hashing |
+| Email, rate limiting, analytics | Built-in primitives, one call each | A separate SDK or vendor per capability |
+| Realtime and background | `@stream`, `@daemon`, `@derive` | A realtime service plus a cron server, queue, and leader election |
+| Asset integrity and toolchain | Automatic SRI, ESLint/Prettier/editor plugins, one CLI | Manual or skipped; configured and maintained by you |
+| Critical-path ownership | The core is toil's own | A mix of vendors you cannot inspect or fix |
+
+## Why it is all a default
+
+None of this is an upgrade you unlock later. toil grades itself against [RSG](./design-principles.md) (Resilience and Scale Grade), whose one rule is that your grade is your weakest axis, never the average, so these batteries exist to keep any single axis from quietly capping the whole. Where the honest trade fits your project (ToilDB is not general SQL, the server language is a strict TypeScript subset, the catalog is younger than long-established platforms), the built-in stack is the whole point; [Why toil](./why-toil.md) says where it does not.

package/docs/introduction/vs-other-frameworks.md

@@ -0,0 +1,48 @@
+# toil versus other stacks
+
+An honest look at where each stack you already use hits a ceiling, and why toil bets on a different shape. Each of these tools is genuinely good at what it was built for, so the goal is not to crown a winner but to show *where* each one typically caps.
+
+We grade with the [RSG rubric](./design-principles.md), whose rule is that a system's grade is its **weakest** axis, never the average. So the useful question is not "what is it great at?" but "what quietly caps it?" For most stacks the answer is the same axis: the **data path** (how and where writes happen), sometimes joined by **dependencies** (how much of the critical path you rent versus own).
+
+RSG is toil's own internal rubric, not an external standard, and every stack below can be configured many ways. The caps described are the *typical* production shape, not a claim that they are unavoidable.
+
+## Where each stack caps
+
+| Stack | Great at | Typical binding axis | Why it caps there |
+| --- | --- | --- | --- |
+| **Next.js / Vercel** | DX, React, global edge reads | data path | Global reads, single-region writes: a sudden write-heavy spike concentrates on one DB box that edge caches and read replicas cannot relieve, while serverless cold starts add latency and per-invocation billing climbs exactly when load peaks |
+| **Rails / Django** | Maturity, batteries included | topology / availability / data | Centralized single-region monolith: one place to be near, one place to fail, and one primary every write must reach |
+| **Serverless functions** (Lambda, Cloud Functions) | Elastic stateless compute | data path | Distributes compute, not state; the central DB stays the write bottleneck, and a cold-start burst adds latency and cost right when traffic surges |
+| **Edge runtimes** (Workers, Deno Deploy) | Code at the edge, near users | data path | Distributes compute beautifully, but the DB you attach is usually single-region (Durable Objects / D1 excepted, below) |
+| **BaaS** (Supabase, Firebase) | Fastest to start | dependencies + data path | You rent a managed service you cannot inspect or fix, and writes resolve against a primary |
+| **toil** | Owned stack, distributed writes | aims for no single binder | Every key has one home region that serializes its writes; auth, DB, email, and jobs are owned, so the usual caps are designed out (latency and client axes are still yours to earn) |
+
+## One line each
+
+- **Next.js / Vercel:** superb reads and DX, but a sudden spike (a viral launch, a flash sale, a timed drop where everyone writes in the same second) lands as a thundering herd on the one write region, so latency, timeouts, and per-invocation cost climb together while edge caching helps only the reads.
+- **Rails / Django:** mature and productive, capped by its single-region shape; you can add replicas and standbys to climb, but distributed *writes* are not in the default model.
+- **Serverless functions:** great elastic compute, but it is stateless compute in front of a central database, so a write burst still bottlenecks on that store and each cold invocation bills separately.
+- **Edge runtimes:** the closest in spirit to toil's compute model, yet edge compute in front of a central database is just a faster front door to the same bottleneck.
+- **Cloudflare Durable Objects / D1:** the closest mainstream analog to toil's idea, and credit is due. A Durable Object gives one object a single-writer home that serializes its writes, the same shape as ToilDB's per-key home. The difference is packaging: with the edge-runtime approach you assemble the pieces yourself (runtime, object or DB product, auth, email), whereas toil ships distributed writes, the seven database families, auth, email, streaming, and jobs as one integrated owned stack. Which you prefer is a genuine trade-off.
+- **BaaS (Supabase, Firebase):** fastest to start, but the convenience is a managed service on your critical path, and writes still resolve against a primary, so it is **dependency-bound and data-bound**.
+
+## Being honest about toil's own limits
+
+RSG grades toil by the same weakest-link rule, and some axes are not handed to you for free:
+
+- **Younger, smaller ecosystem.** Fewer integrations, tutorials, and hosting options than the mature stacks above. If your project is defined by a large existing integration catalog, that gap is real today.
+- **The server language is a TypeScript subset.** toilscript compiles a strict subset of TypeScript to WebAssembly: no arbitrary npm packages or Node APIs on the server, built-in globals instead. That is the price of the small, fast, safe sandbox.
+- **ToilDB is not SQL.** It is seven purpose-built families, not a relational engine, so heavy ad-hoc joins and existing SQL schemas are not its shape (see the [database overview](../database/README.md)).
+- **Some axes you still earn.** RSG measures delivered latency, program performance, and client performance from *your* code. toil removes the structural caps, but it cannot make slow application code fast or a bloated client light.
+
+## toil's bet
+
+Every stack above is capped in almost the same place: the write path is one box in one region, or the critical path leans on a service you rent. toil's bet is to refuse both at once, own the whole stack and distribute the writes, so the axes that usually cap a "global" system are designed out and the only limits left are the ones your own code sets.
+
+Whether that bet fits *your* project is the honest checklist in [Why toil](./why-toil.md).
+
+## Related
+
+- [Why toil? Who is it for?](./why-toil.md): the problem toil solves and the honest cases where you should not use it.
+- [How toil is distributed](./distributed.md): the mechanism behind distributed writes (every key's single home region).
+- [Why toil is built this way (the RSG bar)](./design-principles.md): the weakest-link rubric this comparison uses.