toiljs 0.0.115 → 0.0.117

package/docs/cli/README.md

@@ -1,379 +0,0 @@
-# The toiljs CLI
-
-The `toiljs` command is how you scaffold, run, build, self-host, and diagnose a toiljs app. This page lists every command and every flag, with copy-pasteable examples.
-
-## What it is
-
-When you install the `toiljs` package, it adds one executable to your project: `toiljs`. Everything you do day to day (start the dev server, produce a production build, check your setup) goes through it.
-
-You almost never type the full path. A freshly scaffolded project already has npm scripts that call it, so you run `npm run dev` and `npm run build`. When you want a command that has no script (like `doctor` or `db`), run it with `npx`:
-
-```bash
-npx toiljs doctor
-```
-
-`toiljs` needs **Node.js 24 or newer** (older versions will not run it).
-
-## Command overview
-
-| Command | What it does |
-| --- | --- |
-| `toiljs create [name]` | Scaffold a brand new toiljs app in a new folder. |
-| `toiljs dev` | Start the local development server with hot reload. |
-| `toiljs build` | Produce the optimized production build (client bundle + server WebAssembly). |
-| `toiljs start` | Self-host the built app on a fast production HTTP server. |
-| `toiljs configure` | Turn styling features (Sass/Less/Stylus, Tailwind) on or off in an existing project. |
-| `toiljs doctor` | Diagnose your project setup and (with `--fix`) repair common wiring. |
-| `toiljs update` | Check npm for newer dependency versions and apply the ones you pick. |
-| `toiljs db <action>` | Inspect, reset, snapshot, or restore the local dev database. |
-| `toiljs help` | Print the built-in help. Also `--help` or `-h`. |
-| `toiljs --version` | Print the installed toiljs version. Also `-v`. |
-
-Run `toiljs help` any time to see this list in your terminal.
-
-## Global behavior
-
-A few things apply to every command.
-
-- **`--root <dir>`**: run the command against a project in another directory instead of the current one. Every command accepts it.
-- **Automatic update check**: on every run (including `npm run dev`, which calls the CLI under the hood), toiljs quietly asks the npm registry whether a newer `toiljs` exists and prints a one-line notice on stderr if you are behind. It never blocks or slows the command in a meaningful way (the answer is cached for an hour and the network call is capped at two seconds). To turn it off, set the environment variable `TOILJS_NO_UPDATE_CHECK=1`. It also respects the common `NO_UPDATE_NOTIFIER` and `CI` variables.
-
-```bash
-# Run any command against a project in another folder.
-toiljs build --root ./apps/marketing
-
-# Silence the "newer version available" notice.
-TOILJS_NO_UPDATE_CHECK=1 toiljs dev
-```
-
-## `toiljs create`
-
-Scaffolds a new project into a new folder. By default it is interactive: it asks a short series of questions (project name, template, styling, and so on), then writes the files and installs dependencies. Pass flags to skip questions, or `-y` to accept every default and run with no questions at all.
-
-```bash
-# Interactive: answer the prompts.
-npx toiljs create
-
-# Give it a name up front.
-npx toiljs create my-app
-
-# Fully non-interactive (great for scripts and CI).
-npx toiljs create my-app --yes --template app --style css
-```
-
-### What it sets up
-
-Every new project comes wired for you: the enforced TypeScript, ESLint, and Prettier presets, file-based routing, a `toil.config.ts`, a `toilconfig.json` (the server compiler settings), a `.gitignore`, and the editor settings that make the toilscript language plugin work. It also scaffolds a `server/migrations/` folder (where ToilDB schema migrations live) and, unless you opt out, a set of AI assistant helper files.
-
-The scaffolded `package.json` includes these scripts:
-
-| Script | Runs |
-| --- | --- |
-| `npm run dev` | `toiljs dev` |
-| `npm run build` | `toiljs build` |
-| `npm run build:server` | `toiljs build --server` |
-| `npm run lint` | `eslint client` |
-| `npm run typecheck` | `tsc --noEmit` |
-| `npm run format` | `prettier --write ...` |
-
-### Generated docs and AI-assistant pointers
-
-Every project carries a full copy of this documentation set at `.toil/docs/`. You do not maintain it: toiljs regenerates it from the installed toiljs version on every `toiljs dev` and `toiljs build`, so it always matches the version you are on. Do not edit those files by hand (your changes are overwritten on the next dev or build).
-
-Unless you opt out, `toiljs create` also writes small **pointer files** at the project root that tell AI coding assistants to read `.toil/docs/` before touching the project: `CLAUDE.md` (Claude Code), `AGENTS.md` (Codex and others), `.cursor/rules/toiljs.mdc` (Cursor), and `.github/copilot-instructions.md` (GitHub Copilot). These are written once, committed, and yours to edit. Control them with `--ai` / `--no-ai` (when you pass neither, `create` asks).
-
-### create options
-
-| Flag | Meaning |
-| --- | --- |
-| `[name]` | The project folder name (a positional argument). If omitted, you are asked. |
-| `-t, --template <app\|minimal>` | `app` is the full starter (landing page, layout, styles, demo routes). `minimal` is just a layout and a home route. Default `app`. |
-| `--style <css\|sass\|less\|stylus>` | Which CSS flavor to set up. Default `css` (plain CSS). |
-| `--tailwind` / `--no-tailwind` | Add or skip Tailwind CSS (v4). Off by default. |
-| `--ai` / `--no-ai` | Include or skip AI assistant files (like `CLAUDE.md`). When omitted, you are asked. |
-| `--images` / `--no-images` | Enable or skip build-time image optimization. On by default. |
-| `--git` / `--no-git` | Initialize a git repository. When omitted, you are asked (default yes). |
-| `--install` / `--no-install` | Install dependencies after scaffolding. When omitted, you are asked (default yes). |
-| `--pm <npm\|pnpm\|yarn\|bun>` | Which package manager to install with. Default `npm`. |
-| `-y, --yes` | Accept all defaults and skip every prompt. |
-
-For a walkthrough, see [Create a project](../getting-started/create-project.md).
-
-## `toiljs dev`
-
-Starts the local development server with hot reload, so you edit a file and the browser updates in place. This is the command you leave running while you build.
-
-```bash
-npm run dev
-# or, to pick a port:
-npx toiljs dev --port 4000
-```
-
-### What the dev server emulates
-
-The whole point of the dev server is to run your app locally the same way the real Dacely edge runs it in production, so what you see locally is what you ship. It emulates three things:
-
-1. **The edge.** For a project with a server (any project with a `toilconfig.json`), a small local HTTP server takes the public port and dispatches incoming requests into your compiled `server.wasm` using the exact same request envelope the production edge uses. Anything your server does not claim (page routes, static assets, the hot-reload websocket) is proxied to Vite behind the scenes. So your React frontend and your WebAssembly backend run together, on one URL, exactly like production.
-2. **The database.** ToilDB runs in-process as a local emulator. Every family (documents, views, unique, events, counters, membership, capacity) works, and the data is written to `.toil/devdata.json` so it survives restarts. You manage that file with [`toiljs db`](#toiljs-db).
-3. **The host functions.** The platform services your server code calls (email, environment variables and secrets, time, crypto, rate limiting, auth) are wired up locally so they behave like the edge. Email actually sends if you configure a provider (see [Email](../services/email.md)).
-
-A **client-only** project (no `toilconfig.json`) just gets the plain Vite dev server on your port, unchanged.
-
-### How hot reload works
-
-```mermaid
-flowchart TD
-    E["You edit a file"] --> Q{"Which file?"}
-    Q -->|"client/ (React, CSS)"| V["Vite hot-swaps it in the browser"]
-    Q -->|"server/ (a @rest / @data / @service file)"| S["toilscript recompiles the server"]
-    S --> G["shared/server.ts is regenerated"]
-    G --> V2["Vite hot-swaps the new typed client"]
-    S --> W["the dev server hot-swaps the new server.wasm"]
-    V --> B["Browser updates, no full reload"]
-    V2 --> B
-    W --> B
-```
-
-Client edits go straight through Vite's hot module replacement. Server edits trigger a toilscript rebuild: toiljs recompiles your backend, regenerates `shared/server.ts` (the typed client the browser imports to call your server), and hot-swaps the recompiled WebAssembly, all without you touching the browser. Rebuilds are debounced (grouped over about 150 milliseconds) so a "save all" or a formatter pass does not trigger a storm of builds.
-
-If your project has an `emails/` folder, the dev server also prints an email-preview URL at `/__toil/emails`.
-
-### dev options
-
-| Flag | Meaning |
-| --- | --- |
-| `--port <n>` | Port to listen on. Default `3000` (or `client.port` from your config). |
-| `--root <dir>` | Run against a project in another directory. |
-
-Press `Ctrl+C` to stop. toiljs restores your terminal and force-exits even if a native listener is slow to close, so you never end up with an orphaned dev server rebuilding in the background.
-
-## `toiljs build`
-
-Produces the optimized production build. Run this before you deploy or before `toiljs start`.
-
-```bash
-npm run build
-# or build only the server:
-npx toiljs build --server
-```
-
-### What it produces
-
-A full build runs in a careful order so the pieces line up:
-
-```mermaid
-flowchart LR
-    A["Your project"] --> S["1. Compile the server<br/>(toilscript)"]
-    S --> W["build/server/release.wasm"]
-    S --> R["shared/server.ts<br/>(typed client, regenerated)"]
-    R --> C["2. Bundle the client<br/>(Vite)"]
-    C --> O["build/client/<br/>(HTML, JS, CSS, assets)"]
-    C --> X["3. Prerender + SEO<br/>(SSG pages, robots.txt,<br/>sitemap.xml, llms.txt)"]
-```
-
-1. **The server is built first.** toilscript compiles every decorated server file (not just the entry) into `build/server/release.wasm`, and regenerates `shared/server.ts`. Doing this first means the client always bundles against a current, correct typed server client. A project that also declares `@stream` or `@daemon` surfaces compiles those into their own artifacts (`release-stream.wasm`, `release-cold.wasm`).
-2. **The client is bundled** by Vite into `build/client/` (your HTML, JavaScript, CSS, and optimized assets). The dev toolbar and error overlay are stripped out of the production bundle.
-3. **Static pages and SEO files are generated**: any route that opts into static generation is prerendered to HTML, and if you configured `client.seo`, toiljs writes `robots.txt`, `sitemap.xml`, and `llms.txt`. Routes that opt into server-side rendering get their HTML-with-holes templates baked for the edge.
-
-### build options
-
-| Flag | Meaning |
-| --- | --- |
-| `--server` | Build **only** the server (recompile the wasm and regenerate `shared/server.ts`), and skip the client bundle. Fast when you only touched backend code. This is what `npm run build:server` runs. |
-| `--root <dir>` | Run against a project in another directory. |
-
-A client-only project (no `toilconfig.json`) skips step 1 and just bundles the client.
-
-## `toiljs start`
-
-Self-hosts the app you just built, on a fast production HTTP server (hyper-express, backed by uWebSockets.js). It serves your static client, runs your `server.wasm` for dynamic requests, does server-side rendering, supports daemons, and exposes a `/_toil` websocket channel. Use it to run your app on your own machine or server instead of deploying to the Dacely edge.
-
-```bash
-npm run build      # start needs a build to serve
-npx toiljs start
-npx toiljs start --port 8080 --host 0.0.0.0 --threads 4
-```
-
-`start` fails fast if there is no build yet (it looks for `build/client/index.html`), so run `toiljs build` first.
-
-### start options
-
-| Flag | Meaning |
-| --- | --- |
-| `--port <n>` | Port to listen on. Default `3000` (or `client.port`). |
-| `--host <host>` | Address to bind. Default `127.0.0.1` (loopback only). Pass `0.0.0.0` to accept connections from other machines. |
-| `--threads <n>` | Number of HTTP worker processes. Default is automatic (one per available CPU). Pass `1` to disable the worker pool. `--workers` is an accepted alias. This can also be set as `server.threads` in your config. |
-| `--root <dir>` | Run against a project in another directory. |
-
-## `toiljs configure`
-
-Toggles a project's client styling features (the CSS preprocessor and Tailwind) after the fact, on an existing app. It detects your current setup, asks what you want, then rewrites the stylesheets and your app entry's imports, edits `package.json`, and syncs `node_modules` so removed packages are actually uninstalled.
-
-```bash
-# Interactive.
-npx toiljs configure
-
-# Non-interactive: switch to Sass and turn Tailwind on.
-npx toiljs configure --style sass --tailwind
-```
-
-### configure options
-
-| Flag | Meaning |
-| --- | --- |
-| `--style <css\|sass\|less\|stylus>` | Switch the CSS preprocessor. |
-| `--tailwind` / `--no-tailwind` | Turn Tailwind on or off. |
-| `--images` / `--no-images` | Turn build-time image optimization on or off (sets `client.images` in your config). |
-| `--no-install` | Edit the files but do not run the package manager. You then run install yourself. |
-| `--root <dir>` | Run against a project in another directory. |
-
-Passing any of `--style`, `--tailwind`, or `--images` makes the command non-interactive (it skips the prompts you did not answer with a flag). See [Styling](../frontend/styling.md) for the full picture.
-
-## `toiljs doctor`
-
-Read-only project diagnostics. It gathers facts from disk (your `package.json`, lockfiles, the resolved config, your app entry, `index.html`, your routes, and the server target), runs a set of checks, and prints a grouped report. It never changes anything unless you pass `--fix`, and it never crashes on a partial or non-toiljs project (missing pieces just become warnings or failures). It exits with a non-zero status when any check **fails** (warnings do not fail), so it is safe to run in CI.
-
-```bash
-# Human-readable report.
-npx toiljs doctor
-
-# Machine-readable, for CI.
-npx toiljs doctor --json
-
-# Auto-repair the common wiring.
-npx toiljs doctor --fix
-```
-
-### What it checks
-
-The report is grouped:
-
-| Group | Example checks |
-| --- | --- |
-| **Environment** | Node.js version, that `toiljs` and its peer dependencies (React and so on) are installed and new enough, that your TypeScript is a supported 6.x rather than the unsupported native 7.x, that a lockfile exists, and that your scripts do not wrap `toiljs` in a stray `npx`. |
-| **Project + routing** | The `client/` and `routes/` folders exist, `index.html` has a `<div id="root">`, your app entry calls `mount(...)` with the `slots` argument, at least one route exists, no two routes collide on the same URL, and no asset paths are written in a way that 404s on nested routes. |
-| **Config + assets** | Your `toil.config` loads, the base path is well formed, `client.seo` has a `url` if SEO is configured, and your styling packages are actually installed. |
-| **Server / WASM** | The `toilconfig.json` and its entry files exist, `toilscript` is installed, a compiled `.wasm` exists, the typed-RPC wiring is in place, your `@rest` controllers are actually dispatched, the Prettier and editor plugins are wired, and a `migrations/` folder exists. |
-| **Security** | If your server uses auth, whether `AUTH_SESSION_SECRET` is set (an unset secret means sessions fall back to a published dev key, which is forgeable). |
-
-### What `--fix` repairs
-
-`--fix` pins an unsupported TypeScript (the native 7.x, which ships no compiler API) back to `^6.0.3` in any project. The rest only touch a server project (one with a `toilconfig.json`), repairing the wiring that is easy to get wrong or that older projects predate:
-
-- adds `--rpcModule shared/server.ts` to your server build scripts,
-- adds `shared` and the `shared/*` path alias to `tsconfig.json`,
-- adds `shared/server.ts` to `.gitignore`,
-- lifts the `toilscript` version floor if it is too old,
-- adds the `toiljs/prettier-plugin` to your Prettier config (so Prettier does not choke on server decorators),
-- adds the toilscript language-service plugin to your server `tsconfig.json` and points VS Code at the workspace TypeScript (so the editor stops false-flagging `@database` collections and `@data` members),
-- refreshes the editor-only server globals declaration file.
-
-It is idempotent: it only writes files it actually needs to change, and it tells you which ones changed and which need a manual edit (for example a `tsconfig.json` that contains comments). If it changed `package.json`, run your installer afterward.
-
-### doctor options
-
-| Flag | Meaning |
-| --- | --- |
-| `--json` | Emit machine-readable JSON instead of the human report (the banner is suppressed so stdout stays valid JSON). |
-| `--fix` | Repair the server wiring in place, as above. |
-| `--root <dir>` | Run against a project in another directory. |
-
-## `toiljs update`
-
-A friendly wrapper over `npm-check-updates`. It checks the registry for newer versions of your dependencies, groups them by how big the jump is (major, minor, patch), lets you pick which to apply (or `-y` to apply all), bumps `package.json`, and runs your package manager's install. It also makes sure your `server/migrations/` folder exists (older projects predate it). `npm-check-updates` runs via `npx`, so it never becomes a permanent dependency of your project.
-
-Upgrades into a major toiljs does not support are held back and listed separately, so neither the picker nor `-y` can install one. Today that means **TypeScript 7**, the native port, which ships no JavaScript compiler API (see [Installation](../getting-started/installation.md)). Bumps inside TypeScript 6 are still offered.
-
-```bash
-# Interactive picker.
-npx toiljs update
-
-# Apply everything, non-interactively.
-npx toiljs update --yes
-
-# Only patch-level updates.
-npx toiljs update --target patch
-```
-
-### update options
-
-| Flag | Meaning |
-| --- | --- |
-| `-y, --yes` | Apply all available updates without the picker. |
-| `--target <latest\|minor\|patch\|newest\|greatest>` | How far to bump. Default `latest`. |
-| `--root <dir>` | Run against a project in another directory. |
-
-## `toiljs db`
-
-Manages the local dev database: the on-disk ToilDB store your dev server writes to `.toil/devdata.json`. Use it to inspect data, wipe a corrupt state, save a snapshot to share as a fixture, or restore one. The snapshot is exactly the JSON the dev database uses, so an exported file imports cleanly.
-
-```bash
-# See what is stored.
-npx toiljs db status
-
-# Wipe all dev data.
-npx toiljs db reset
-
-# Save a snapshot (to a file, or to stdout if you omit the file).
-npx toiljs db export fixture.json
-
-# Restore a snapshot.
-npx toiljs db import fixture.json
-
-# Print the on-disk path (scriptable).
-npx toiljs db path
-```
-
-### db actions
-
-| Action | What it does |
-| --- | --- |
-| `status` (alias `info`) | Show the database path, its size, and per-family row counts. |
-| `reset` (alias `purge`) | Delete all dev data (removes `devdata.json`). |
-| `export [file]` | Write a formatted snapshot to `file`, or to stdout if you omit it (pipe-friendly). |
-| `import <file>` | Replace the dev database with the snapshot in `file`. It refuses a file that is not a valid snapshot. |
-| `path` | Print the `devdata.json` path and nothing else. |
-
-The dev database is per-project and lives under `.toil/`, which is gitignored. See [Database setup](../database/setup.md) for what actually populates it.
-
-## The dev, build, and deploy flow
-
-Here is how the commands fit together across your workflow.
-
-```mermaid
-flowchart LR
-    subgraph Develop
-      D["toiljs dev<br/>(hot reload, local edge + DB)"]
-    end
-    subgraph Ship
-      B["toiljs build<br/>(client bundle + server.wasm)"]
-    end
-    subgraph Run
-      ST["toiljs start<br/>(self-host locally)"]
-      DP["deploy to the Dacely edge"]
-    end
-    D --> B
-    B --> ST
-    B --> DP
-```
-
-- **Develop** with `toiljs dev`. Everything runs locally and reloads as you type.
-- **Ship** with `toiljs build`. This produces the artifacts: the client bundle in `build/client/` and the server WebAssembly in `build/server/`.
-- **Run** the build two ways: `toiljs start` self-hosts it on your own machine, or you deploy the same build to the Dacely edge to serve it worldwide.
-
-## Gotchas
-
-- **`start` needs a build.** `toiljs start` serves what is in `build/`. Run `toiljs build` first, or it exits with an error.
-- **Run `toiljs`, not `npx toiljs`, inside npm scripts.** Under `npm run`, `node_modules/.bin` is already on your PATH, so an extra `npx` layer is redundant and can leave your terminal in a broken input mode after `Ctrl+C`. `doctor` warns about this; the scaffold gets it right.
-- **`--host` and `--threads` are `start`-only.** `toiljs dev` always binds locally and does not take `--host` or `--threads`.
-- **`--server` builds the backend only.** Use it while iterating on server code, but run a full `toiljs build` before you deploy so the client bundle is current.
-- **The update notice is not an error.** The "newer toiljs available" line is informational and prints to stderr. Set `TOILJS_NO_UPDATE_CHECK=1` to hide it.
-
-## Related
-
-- [Installation](../getting-started/installation.md) and [Create a project](../getting-started/create-project.md)
-- [Project structure](../getting-started/project-structure.md)
-- [Configuration reference (`toil.config.ts`)](../concepts/config.md)
-- [Styling](../frontend/styling.md)
-- [Database setup](../database/setup.md) and the [database overview](../database/README.md)
-- [Compute tiers (L1 to L4)](../concepts/tiers.md)

package/docs/concepts/ai-guide.md

@@ -1,132 +0,0 @@
-# Writing toiljs correctly
-
-This is a fast, high-signal cheat-sheet for writing toiljs and toilscript code that compiles and behaves. It is aimed at AI assistants generating code (and at humans in a hurry): the patterns to follow, the mistakes to avoid, and a link to the deep page whenever you need more. It does not re-teach the framework; each section points you at the authoritative doc.
-
-## Project shape
-
-A toiljs project has three top-level folders, and knowing which one a file belongs to tells you which rules apply:
-
-- **`client/`**: your React app that runs in the browser. Pages live under `client/routes/`, one file per URL, and each route file `export default`s its component. See [Frontend](../frontend/README.md) and [Routing](../frontend/routing.md).
-- **`shared/`**: a generated typed bridge (`shared/server.ts`) that lets the browser call the backend with full types. It is regenerated on every build, so **never hand-edit it**.
-- **`server/`**: your backend, written in TypeScript but compiled by **toilscript** to WebAssembly. It runs on the Dacely edge, not in Node or the browser. See [Backend](../backend/README.md).
-
-Most code runs on the L1 request tier. Long-lived connections (`@stream`) and scheduled work (`@daemon`) are opt-in tiers in their own entry files. See [Compute tiers](./tiers.md).
-
-## Client rules (the browser, React side)
-
-**Call the backend only through the generated `Server` client.** This is the number one rule. Use `Server.REST.<controller>.<route>(args)` for `@rest` HTTP controllers, or `Server.<service>.<method>(args)` / `Server.<remote>(args)` for RPC. Raw `fetch` to your own backend throws away the type safety, the argument and result decoding, and the binary wire codec, and it silently breaks when a route is renamed. `fetch` is only for third-party URLs (an external API, a CDN). See [Fetching data](../frontend/data-fetching.md).
-
-```ts
-// WRONG: raw fetch to your own backend
-await fetch('/account/session', { method: 'POST' });
-
-// RIGHT: the typed client (renames become compile errors; args + result typed)
-await Server.REST.account.session();
-```
-
-**Use the ambient `Toil.*` globals with no import.** `Toil` is the `toiljs/client` package exposed as a global and typed via a generated `toil-env.d.ts`, so it autocompletes with no import: `Toil.Link` / `Toil.NavLink` for navigation, `Toil.useParams`, `Toil.useLoaderData`, `Toil.Image`, `Toil.useHead` / `Toil.Head`, `Toil.Form` / `Toil.useAction`, and more. `Server` and `parseError` are also bare globals; `FastMap`, `FastSet`, `DataWriter`, and `DataReader` are bare globals too (write `new DataWriter()`, not `new Toil.DataWriter()`). Full index: [The Toil global](../frontend/toil-global.md).
-
-**Load page data with a `loader`, not a `useEffect` fetch.** A route file exports a `loader`, and the component reads its result with `Toil.useLoaderData`. The loader runs on navigation in parallel with the route chunk, integrates with `loading.tsx`, caching, and SSR hydration. A `useEffect` fetch runs only after mount (slower, invisible to the server).
-
-```tsx
-// client/routes/blog/[id].tsx
-export const loader = async ({ params }: Toil.LoaderArgs) => {
-  return Server.REST.blog.get({ params: { id: params.id } });
-};
-
-export default function BlogPost() {
-  const post = Toil.useLoaderData<typeof loader>();
-  return <article><h1>{post.title}</h1></article>;
-}
-```
-
-**Mutate with `Toil.useAction` or `<Toil.Form>`, then revalidate.** Both track pending and error state and refetch the affected loader data on success, so the page updates without a manual refetch. Use `<Toil.Form>` for form submits, `useAction` for anything else (a delete button, a toggle). Reach for `Toil.revalidate()` / `router.revalidate()` after a write that these do not cover.
-
-**Per-route SEO with `export const metadata`** (or `Toil.useHead` / `<Toil.Head>` from inside a component). Opt a route into edge SSR with `export const ssr = true`. See [Metadata and SEO](../frontend/metadata.md) and [Rendering and SSR](../frontend/rendering.md).
-
-**Typed hrefs.** `Toil.Link` `href`, `Toil.navigate`, and `router.push` are all type-checked against your real routes, so a typo is a compile error. Use `Toil.href(str)` only when a URL is assembled from data and TypeScript cannot prove it is a real route. See [Navigation](../frontend/navigation.md).
-
-**`getUser()` on the client is display-only.** It reads a readable session cookie with no network call, so it is instant but **forgeable**. Use it to render "logged in as ...", never to gate real access. The authoritative check is a server route guarded with `@auth`. See [Auth usage](../auth/usage.md).
-
-## Server rules (toilscript, compiles to WASM)
-
-The decorators, each doing one job (full list in [Decorators](./decorators.md)):
-
-- **`@data`** on a class: generates the binary and JSON codec so the value can cross the wire and the database. Every field needs a default; field order **is** the binary layout, so add new fields at the end. See [Data types](../backend/data.md).
-- **`@rest('name')`** on a class mounts an HTTP controller at `/name`; **`@get`/`@post`/`@put`/`@del`/`@patch`** on its methods declare routes (`@del`, not `@delete`, which is reserved). See [REST](../backend/rest.md).
-- **`@service`** + **`@remote`** expose typed RPC callable from your own frontend as `Server.<service>.<method>()`. See [RPC](../backend/rpc.md).
-- **`@user`** declares the authenticated-user shape and enables `AuthService.getUser()`. **Exactly one `@user` per project.** **`@auth`** guards a route or a whole `@rest` class. See [Auth](../auth/README.md).
-- **`@ratelimit(strategy, limit, window)`** caps how often a caller may hit a route, rejected at the edge before your code runs. See [Security](./security.md).
-- **`@database`** + **`@collection`** declare a ToilDB schema (below).
-
-```ts
-@rest('players')
-class Players {
-  @get('/:id')
-  public get(ctx: RouteContext): Response {
-    const id = ctx.param('id');
-    return Response.json(`{"id":"${id}"}`);
-  }
-}
-```
-
-**`@auth` rejects with 401 before your handler runs.** So inside an `@auth`-guarded handler, `AuthService.getUser()!` is guaranteed non-null and safe to assert. Without `@auth`, `getUser()` can be null, so null-check it instead. Either way the server re-verifies the signed session, so it (not the client cookie) is the real authorization boundary.
-
-```ts
-@auth
-@get('/settings')
-public settings(): Response {
-  const user = AuthService.getUser()!;   // safe: @auth guarantees a session
-  return Response.text('hi ' + user.username);
-}
-```
-
-**Server code is a strict, WASM-targeted dialect (AssemblyScript), not full TypeScript.** The real constraints, verified against the toilscript standard library:
-
-- **Use explicit value types**, never `number`: `i32` / `u32` / `i64` / `u64` / `f64` (and `i8`/`u8`/`i16`/`u16`/`f32`, plus `u128`..`u256`), `bool`, `string`, `Uint8Array`. Plain `number` resolves to `f64`, which is wrong for ids and counts. Integer math **wraps** on overflow (it never throws), and integer `/` truncates. See [The type system](./types.md).
-- **No `any`.** Every value has a concrete type; that is what lets it compile to WASM.
-- **No arbitrary npm.** Only the toilscript standard library plus the toiljs host APIs.
-- **Use `null`, not `undefined`** for "no value" (`T | null`, narrowed with `if (x != null)` or a `!` assertion).
-- **No usable built-in `RegExp`** (it is a host stub that throws). Parse strings by hand.
-- **Structured values are `@data` classes, not object literals.** Encode and decode raw binary with `DataWriter` / `DataReader` (imported on the server from the `data` module: `import { DataWriter, DataReader } from 'data';`). For dynamic JSON, use the ambient `JSON` value tree.
-- **Read config with `Environment.get(key)` and secrets with `Environment.getSecure(key)`** (each returns `string | null`; the two buckets are disjoint so a secret can never leak through `get`). See [Environment](../services/environment.md).
-- **Return a runtime `Response`** (`Response.json` / `.text` / `.html` / `.bytes` / `.notFound` / ...), or return a `@data` value and let toiljs serialize it.
-
-**ToilDB has seven collection families; pick the one that matches the job** (do not force everything into one). Declare each as a `static` `@collection` field on a `@database` class, typed by its family, and reach it statically (`AppDb.users.get(...)`). See [The database](../database/README.md) and [Setup](../database/setup.md).
-
-- **`Documents<K,V>`**: the default record store, looked up by id (users, posts, orders).
-- **`Unique<K,V>`**: a globally one-of-a-kind claim (usernames, emails, slugs).
-- **`Counter<K>`**: a running total many callers bump at once (likes, views); `add` a delta only.
-- **`Events<K,V>`**: an append-only log kept in order (feeds, audit trails).
-- **`Capacity<K>`**: a limited quantity handed out without overselling (tickets, seats).
-- **`Membership<K,M>`**: sets of who belongs to what (followers, tags, room members).
-- **`View<K,V>`**: a precomputed read-optimized snapshot (leaderboards, home pages).
-
-**Data access is gated by function kind.** A `@get` route is a read-only **Query**; a `@post` route is an **Action** (may write); a plain `@remote` defaults to read-only Query, so add **`@action`** to let it write. Scans (`events.latest`, `membership.list`) are barred from request handlers: do them in a `@derive` and have the request read the resulting `View`. The compiler enforces this and the edge re-checks it.
-
-## Common mistakes
-
-A short do-not list. Every one of these is a real, avoidable error:
-
-- **Raw `fetch` to your own backend.** Go through `Server.*` instead.
-- **Importing `Toil.*`.** They are ambient globals; importing them is wrong.
-- **Fetching page data in a `useEffect`.** Use a route `loader` + `Toil.useLoaderData`.
-- **A plain `<a>` for in-app links.** Use `Toil.Link` (a bare `<a>` triggers a full reload).
-- **More than one `@user`.** Exactly one per project.
-- **Trusting client `getUser()` for authorization.** It is display-only and forgeable; enforce on the server with `@auth`.
-- **`any`, `number`, or `RegExp` in server code.** Use explicit value types; there is no usable `RegExp`.
-- **Reordering `@data` fields** (or changing a field type) on a stored type. Field order is the layout; add at the end and use `@migrate` to evolve. See [Data types](../backend/data.md).
-- **Writing from a plain `@remote` or `@get`.** Reads are the default; a write needs `@action`.
-- **Calling a scan (`events.latest`, `membership.list`) from a request handler.** Do it in a `@derive`.
-- **Hand-editing `shared/server.ts` or `.toil/`.** They are generated; rebuild instead.
-
-## Where to go deeper
-
-- Concepts: [Decorators](./decorators.md), [Type system](./types.md), [Security](./security.md), [Compute tiers](./tiers.md).
-- Backend: [Overview](../backend/README.md), [REST](../backend/rest.md), [RPC](../backend/rpc.md), [Data types](../backend/data.md).
-- Frontend: [Overview](../frontend/README.md), [Fetching data](../frontend/data-fetching.md), [Routing](../frontend/routing.md), [Navigation](../frontend/navigation.md), [The Toil global](../frontend/toil-global.md).
-- Database: [ToilDB overview](../database/README.md), [Setup](../database/setup.md).
-- Auth: [Overview](../auth/README.md), [Usage](../auth/usage.md).
-- Services: [Environment](../services/environment.md), [Rate limiting](../services/ratelimit.md).
-</content>
-</invoke>