acrylblends 0.11.0 → 1.0.0

package/docs/framework/agents/index.md

@@ -25,7 +25,7 @@ with SQLite, small state on the `kv` port with one JSON file, the Node server, t
 
 ## What an agent can do inside a running app
 
-The `acryl-app` template (a Cordis app) also lets an agent change the app while it runs:
+The `agent` template (a Cordis app; `acryl-app` is its old name and still works) also lets an agent change the app while it runs:
 
 1. The agent writes a plugin into `plugins/<name>/index.ts`. The plugin may import `acrylblends` and the other subpaths by name.
 2. The app installs it as a child plugin, runs its `check(ctx)` with the plugin's own context, and keeps the previous version if the new one fails to start or to pass its check.

package/docs/framework/api/acryl.md

@@ -1,4 +1,4 @@
-# App - Acryl
+# Acryl
 
 `Acryl` is the primary object.
 It will be imported first and used until the end.
@@ -9,7 +9,7 @@ import { Acryl } from 'acrylblends'
 const app = new Acryl()
 //...
 
-export default app // for Cloudflare Workers or Bun
+export default app // a Bun server, or a value a Cordis plugin mounts; see Node.js for the Node entry
 ```
 
 ## Methods
@@ -64,25 +64,13 @@ app.onError((err, c) => {
 
 ## fire()
 
-> **Warning.** **`app.fire()` is deprecated**. Use `fire()` from `acrylblends/service-worker` instead. See the Service Worker documentation for details.
-
-`app.fire()` automatically adds a global `fetch` event listener.
-
-This can be useful for environments that adhere to the [Service Worker API](https://developer.mozilla.org/en-US/docs/Web/API/Service_Worker_API), such as [non-ES module Cloudflare Workers](https://developers.cloudflare.com/workers/reference/migrate-to-module-workers/).
-
-`app.fire()` executes the following for you:
-
-```ts
-addEventListener('fetch', (event: FetchEventLike): void => {
-  event.respondWith(this.dispatch(...))
-})
-```
+> **Warning.** **`app.fire()` is deprecated**, and the Service Worker adapter is not part of the package in 1.0. It adds a global `fetch` event listener, which only a Service Worker-style host reads; use `app.fetch` in an entry point of your own instead.
 
 ## fetch()
 
 `app.fetch` will be the entry point of your application.
 
-For Cloudflare Workers, you can use the following:
+As the `fetch` method of an object a host calls:
 
 ```ts twoslash
 import { Acryl } from 'acrylblends'
@@ -230,7 +218,7 @@ const app = new Acryl({ router: new RegExpRouter() })
 
 ## Generics
 
-You can pass Generics to specify the types of Cloudflare Workers Bindings and variables used in `c.set`/`c.get`.
+You can pass Generics to specify the type of the environment the host passes and the variables used in `c.set`/`c.get`.
 
 ```ts twoslash
 import { Acryl } from 'acrylblends'

package/docs/framework/api/context.md

@@ -362,81 +362,32 @@ app.get('/pages/my-hobbies', (c) => {
 
 ## executionCtx
 
-You can access Cloudflare Workers' specific [ExecutionContext](https://developers.cloudflare.com/workers/runtime-apis/context/).
+A host that embeds the app can pass an execution context: `waitUntil(promise)` keeps work alive after the response has been sent, and `passThroughOnException()` lets the host take over when the handler throws. The Node server passes none, so read it only in an app whose host provides one.
 
 ```ts twoslash
 import { Acryl } from 'acrylblends'
-const app = new Acryl<{
-  Bindings: {
-    KV: any
-  }
-}>()
-declare const key: string
-declare const data: string
-// ---cut---
-// ExecutionContext object
-app.get('/foo', async (c) => {
-  c.executionCtx.waitUntil(c.env.KV.put(key, data))
-  // ...
-})
-```
-
-The `ExecutionContext` also has an [`exports`](https://developers.cloudflare.com/workers/runtime-apis/context/#exports) field. To get autocomplete with Wrangler's generated types, you can use module augmentation:
-
-```ts
-import 'acrylblends'
-
-declare module 'acrylblends' {
-  interface ExecutionContext {
-    readonly exports: Cloudflare.Exports
-  }
-}
-```
-
-## event
-
-You can access Cloudflare Workers' specific `FetchEvent`. This was used in "Service Worker" syntax. But, it is not recommended now.
-
-```ts twoslash
-import { Acryl } from 'acrylblends'
-declare const key: string
-declare const data: string
-type KVNamespace = any
+const app = new Acryl()
+declare const sendReceipt: Promise<void>
 // ---cut---
-// Type definition to make type inference
-type Bindings = {
-  MY_KV: KVNamespace
-}
-
-const app = new Acryl<{ Bindings: Bindings }>()
-
-// FetchEvent object (only set when using Service Worker syntax)
-app.get('/foo', async (c) => {
-  c.event.waitUntil(c.env.MY_KV.put(key, data))
-  // ...
+// Work that must finish after the response, when the host provides a context
+app.get('/orders/:id', async (c) => {
+  c.executionCtx.waitUntil(sendReceipt)
+  return c.json({ ok: true })
 })
 ```
 
 ## env
 
-In Cloudflare Workers Environment variables, secrets, KV namespaces, D1 database, R2 bucket etc. that are bound to a worker are known as bindings.
-Regardless of type, bindings are always available as global variables and can be accessed via the context `c.env.BINDING_KEY`.
+`c.env` is the environment the host hands the app. The Node server passes `process.env`, so `c.env.MY_KEY` is the variable `MY_KEY`. A host that passes something else gives the app a type parameter, and then `c.env` is that shape.
 
 ```ts twoslash
 import { Acryl } from 'acrylblends'
-type KVNamespace = any
 // ---cut---
-// Type definition to make type inference
-type Bindings = {
-  MY_KV: KVNamespace
-}
+const app = new Acryl<{ Bindings: { REGION: string } }>()
 
-const app = new Acryl<{ Bindings: Bindings }>()
-
-// Environment object for Cloudflare Workers
-app.get('/', async (c) => {
-  c.env.MY_KV.get('my-key')
-  // ...
+app.get('/', (c) => {
+  const region = c.env.REGION
+  return c.text(region)
 })
 ```
 

package/docs/framework/api/presets.md

@@ -57,6 +57,6 @@ this.router = new PatternRouter()
 
 | Preset       | Suitable platforms                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `acrylblends`       | This is highly recommended for most use cases. Although the registration phase may be slower than `acrylblends/quick`, it exhibits high performance once booted. It's ideal for long-life servers built with **Deno**, **Bun**, or **Node.js**. It is also suitable for **Fastly Compute**, as route registration occurs during the app build phase on that platform. For environments such as **Cloudflare Workers**, **Deno Deploy**, where v8 isolates are utilized, this preset is suitable as well because the isolations persist for a certain amount of time after booting. |
+| `acrylblends`       | This is highly recommended for most use cases. Although the registration phase may be slower than `acrylblends/quick`, it exhibits high performance once booted. It's ideal for a long-life server on **Node.js** (the verified runtime) or **Bun** (experimental). |
 | `acrylblends/quick` | This preset is designed for environments where the application is initialized for every request.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
 | `acrylblends/tiny`  | This is the smallest router package and it's suitable for environments where resources are limited.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |

package/docs/framework/api/request.md

@@ -364,9 +364,9 @@ app.get('/about/me', async (c) => {
 The raw [`Request`](https://developer.mozilla.org/en-US/docs/Web/API/Request) object.
 
 ```ts
-// For Cloudflare Workers
-app.post('/', async (c) => {
-  const metadata = c.req.raw.cf?.hostMetadata?
+// Hand the raw Request to an API that takes one, such as a Web-standard parser
+app.post('/upload', async (c) => {
+  const bytes = await c.req.raw.arrayBuffer()
   // ...
 })
 ```

package/docs/framework/api/summary.md

@@ -10,7 +10,7 @@ import { Acryl } from 'acrylblends'
 import { trimTrailingSlash } from 'acrylblends/trailing-slash'
 import { schemaValidator, type StandardSchema } from 'acrylblends/schema-validator'
 import { streamSSE } from 'acrylblends/streaming'
-import type {} from 'acryl-state'
+import type {} from 'acrylblends/cordis/state'
 
 export const name = 'orders'                 // the package name and the Loader row id
 export const inject = ['router', 'state']    // the plugin waits (PENDING) until both exist

package/docs/framework/concepts/web-standard.md

@@ -4,8 +4,8 @@ Acryl uses only **Web Standards** like Fetch.
 They were originally used in the `fetch` function and consist of basic objects that handle HTTP requests and responses.
 In addition to `Requests` and `Responses`, there are `URL`, `URLSearchParam`, `Headers` and others.
 
-Cloudflare Workers, Deno, and Bun also are built upon Web Standards.
-For example, a server that returns "Hello World" could be written as below. This could run on Cloudflare Workers and Bun.
+Bun is built on Web Standards the same way.
+For example, a server that returns "Hello World" can be written as below, and it runs on Node.js and Bun.
 
 ```ts twoslash
 export default {
@@ -15,23 +15,13 @@ export default {
 }
 ```
 
-Acryl uses only Web Standards, which means that Acryl can run on any runtime that supports them.
-In addition, we have a Node.js adapter. Acryl runs on these runtimes:
+Acryl uses only Web Standards, so the same application code is expected to run wherever a `fetch`-style handler can run: a platform that can call `app.fetch(request)` can serve an Acryl app. In 1.0 the framework builds, exports and gates two runtimes:
 
-- Cloudflare Workers (`workerd`)
-- Deno
-- Bun
-- Fastly Compute
-- AWS Lambda
-- Node.js
-- Vercel (edge-light)
-- WebAssembly (w/ [WebAssembly System Interface (WASI)][wasi] via [`wasi:http`][wasi-http])
+- **Node.js** (`acrylblends/node-server`): the verified runtime, on Node 22 and 24, on Linux, macOS and Windows.
+- **Bun** (`acrylblends/bun`): experimental, with one smoke gate.
 
-It also works on Netlify and other platforms.
+The adapters the upstream project had for Cloudflare Workers and Pages, Deno, Fastly Compute, AWS Lambda, Lambda@Edge, Vercel, Netlify and service workers are not part of the 1.0 package: no gate of ours deploys to them. Their ported sources stay in the repository and may return as separate plugins, each with its own gate. See [Other runtimes](../getting-started/other-runtimes.md).
 The same code runs on all platforms.
 
 Cloudflare Workers, Deno, Shopify, and others launched [WinterCG](https://wintercg.org) to discuss the possibility of using the Web Standards to enable "web-interoperability".
 Acryl will follow their steps and go for **the Standard of the Web Standards**.
-
-[wasi]: https://github.com/WebAssembly/wasi
-[wasi-http]: https://github.com/WebAssembly/wasi-http

package/docs/framework/cordis/acryl-in-a-cordis-app.md

@@ -126,7 +126,7 @@ smallest one to copy is `examples/acryl-framework-starter`.
 
 ```ts
 import { Context } from '@deepseek-ai/cordis'
-import * as router from 'acryl-router'
+import * as router from 'acrylblends/cordis/router'
 import * as todo from '../src/index.ts'
 
 const ctx = new Context()
@@ -139,13 +139,18 @@ expect(await response.json()).toEqual({ id: '42' })
 
 ## Package map
 
-| Package | Responsibility |
-| --- | --- |
-| `acryl-router` | the application API and the Cordis `router` service |
-| `acryl-router-http` | serving router prefixes on the ACRYL Host's web server |
-| `acryl-node-server` | serving the whole router from a standalone Node.js process |
-| `acryl-state` | shared application state across surfaces |
-| `acryl-inspect` | runtime inspection of mounts, routes and plugins |
+The framework plugins are published as subpaths of the `acrylblends` package (the Cordis forms); an app made by `acrylblends init` carries their source under `plugins/` instead, with the same names.
+
+| Plugin | Published as | Responsibility |
+| --- | --- | --- |
+| `acryl-router` | `acrylblends/cordis/router` | the application API and the Cordis `router` service |
+| `acryl-router-http` | `acrylblends/cordis/router-http` | serving router prefixes on the ACRYL Host's web server, with WebSocket upgrades owned by the mounting plugin |
+| `acryl-node-server` | `acrylblends/cordis/node-server` | serving the whole router from a standalone Node.js process |
+| `acryl-state` | `acrylblends/cordis/state` | shared application state across surfaces |
+| `acryl-inspect` | `acrylblends/cordis/inspect` | runtime inspection of mounts, routes and plugins |
+| `acryl-db`, `acryl-db-sqlite` | `acrylblends/cordis/db`, `acrylblends/cordis/db-sqlite` | the `db` port and its SQLite provider |
+| `acryl-kv`, `acryl-kv-json`, `acryl-kv-db` | `acrylblends/cordis/kv`, `.../kv-json`, `.../kv-db` | the `kv` port and its providers |
+| `acryl-door` | `acrylblends/cordis/door` (experimental) | the door: an agent looks at the running app and acts on it, in development only |
 
 ## Next
 

package/docs/framework/cordis/migration-from-0-4.md

@@ -6,7 +6,7 @@ unchanged.
 
 | 0.4 | 0.5 |
 | --- | --- |
-| `import { App } from 'acryl-router'`, `new App()` | `import { Acryl } from 'acryl-router'`, `new Acryl()` |
+| `import { App } from 'acryl-router'`, `new App()` | `import { Acryl } from 'acrylblends/cordis/router'`, `new Acryl()` (`App` and `AppRequest` are removed in 1.0) |
 | `AppRequest` | `AcrylRequest` |
 
 `App` and `AppRequest` still work in 0.5, marked deprecated, and are removed in the next release. Code outside Cordis imports the same

package/docs/framework/cordis/migration-to-1-0.md

@@ -0,0 +1,45 @@
+# Migration to 1.0
+
+1.0 fixes the public surface of `acrylblends` and gives an app a way to move its copies of the framework plugins forward. This page is the one path from any 0.x app that was made by 0.9.1 or later; an older app is best made again with `npm create acrylblends@latest` and its own code moved over (its routes and plugins are plain `Acryl` code and Cordis plugins).
+
+## 1. Upgrade the app's copies of the framework plugins
+
+An app made by `acrylblends init` carries copies of the framework plugins (`acryl-router`, `acryl-node-server`, `acryl-door`, `extensions`, ...) in `plugins/`. `acrylblends upgrade` brings them to the version of the installed package:
+
+```sh
+npm install acrylblends@latest        # in an app that depends on the package; the agent template does not
+npx acrylblends upgrade --dry-run     # what would change, and the diff of every file you edited
+npx acrylblends upgrade               # do it
+npm install && npm run check && npm test
+```
+
+- A file nobody edited is replaced. A file the app edited stops the upgrade: nothing is changed, the diff of what would be lost is shown, and the command exits 1. Move your change out of the plugin (a plugin of your own in `plugins/<name>/` is never touched), or run `npx acrylblends upgrade --force`, which saves the edited versions in `.acrylblends/upgrade-backup/<time>/` before replacing them.
+- `--diff` prints the diff of every changed file, not only the edited ones. `acrylblends upgrade acryl-router extensions` upgrades only those plugins.
+- A file of your own inside a library plugin folder (a note, a test) is kept and reported. A plugin that a newer version needs and the app lacks is added.
+- How it tells an edit from an untouched file: since 1.0 `acrylblends init` and `add` record the hash of every copied file in `plugins/library.lock.json`; for an app made earlier, the package knows the hashes of the released versions (0.9.1, 0.9.2, 0.10.0, 0.11.0). A file that matches neither counts as edited, so a doubt always stops the upgrade instead of overwriting.
+- `package.json` gets the new `acrylblends` range when it has one, and the dependencies the new plugin versions need (existing ones are kept; run `npm install`).
+
+## 2. What changed in the public surface
+
+| Removed or changed | Do this |
+| --- | --- |
+| `App` and `AppRequest` (the 0.4 names, deprecated since 0.5) are removed | `Acryl` and `AcrylRequest`: `import { Acryl } from 'acrylblends'` |
+| `acrylblends/utils/*` and `acrylblends/acryl-base` are internal, not exported | Use the public helpers (`acrylblends/cookie`, `acrylblends/http-exception`, ...); the utilities are not promised |
+| The adapters for AWS Lambda, Lambda@Edge, Cloudflare Workers and Pages, Vercel, Netlify and Service Workers are not exported | An app is plain `fetch` code (`app.fetch(request)`), so a platform that calls a `fetch` handler can call it. Their ported sources stay in the repository; they may return as separate plugins, each with a gate. See [Other runtimes](../getting-started/other-runtimes.md) |
+| `acrylblends/bun` is experimental | The one Bun gate runs it on Bun; no promise beyond that |
+| The door (`door/*`, `cordis/door`), the agent panel and the PTY driver are experimental and development-only | They start nothing with `NODE_ENV=production` (the door plugin now checks it itself; `allowInProduction: true` for a host that means it); see [what runs in production](../guides/production.md) |
+| `HTTPException` is `acrylblends/http-exception`, not the root | `import { HTTPException } from 'acrylblends/http-exception'` |
+| `acrylblends/cordis/*` are the published forms of the framework plugins | In code that uses the package (not an app's own copies), import `acrylblends/cordis/router` where an old guide wrote `acryl-router` |
+| One template list: `blank`, `nodejs`, `notes`, `chat`, `todo`, `agent` in both `create-acrylblends` and `acrylblends init` | `acryl-app` still means `agent` |
+
+Node.js 22.19 or newer. Bun is optional and experimental; Deno is not supported.
+
+## 3. Check
+
+```sh
+npx acrylblends check-deps
+npm run check
+npm test
+```
+
+An app on the vendored plugins keeps working without the package's own newer subpaths; moving to the package's `acrylblends/cordis/*` forms in place of the copies is a separate, optional step.

package/docs/framework/cordis/node-server.md

@@ -9,8 +9,8 @@ The server is a Cordis plugin that provides the `nodeServer` service:
 
 ```ts
 import { Context } from '@deepseek-ai/cordis'
-import * as router from 'acryl-router'
-import * as nodeServer from 'acrylblends/node-server'
+import * as router from 'acrylblends/cordis/router'
+import * as nodeServer from 'acrylblends/cordis/node-server'
 import * as todo from './todo.ts'
 
 const root = new Context()

package/docs/framework/getting-started/basic.md

@@ -1,11 +1,11 @@
 # Getting Started
 
-Using Acryl is easy. You set up the project, write code, develop with a local server, and run it. The same application code works on every verified runtime, with a different
-entry point for each. This page shows the basic usage.
+Using Acryl is easy. You set up the project, write code, develop with a local server, and run it. The same application code runs on Node.js, the verified runtime, and on Bun,
+which is experimental; only the entry point differs. This page shows the basic usage.
 
 ## Starter
 
-Starter templates are available for each runtime. Use the "create-acrylblends" command.
+A starter is a Cordis app that arrives already wired: `blend.yaml`, its plugins in `plugins/`, and a test. Use the "create-acrylblends" command.
 
 **npm**
 
@@ -34,12 +34,17 @@ bun create acrylblends@latest my-app
 You are asked which template you want:
 
 ```
-? Which template do you want to use?
-❯   nodejs
-    acryl-app
+Templates:
+  blank   the router, a server and one route: the smallest app
+  nodejs  a web app with a page and a client component
+  notes   a multi-user notes app on the db port (sign-up, log-in, sessions)
+  chat    a chat app that streams an answer over server-sent events
+  todo    a to-do list on the router and state
+  agent   the blank app with an offline agent that builds plugins into the running app
+Which template do you want to use? [nodejs]:
 ```
 
-Every template is a Cordis app: `blend.yaml` lists its plugins and every plugin is a folder in `plugins/`. `nodejs` is a web app with a page and a client component, `notes` and `chat` add a database, and `acryl-app` adds an agent that can extend it while it
+Every template is a Cordis app: `blend.yaml` lists its plugins and every plugin is a folder in `plugins/`. `blank` is the smallest app, `nodejs` is a web app with a page and a client component, `notes` and `chat` add a database, `todo` is a to-do list, and `agent` adds an agent that can extend the app while it
 runs (see [Acryl in a Cordis app](../cordis/acryl-in-a-cordis-app.md)). Pass `--template` to skip the question, see [create-acrylblends](../guides/create-acrylblends.md).
 
 The template is created in `my-app`: go to it, install the dependencies and start the local server.
@@ -52,9 +57,9 @@ npm run dev
 
 ## Hello World
 
-Write your first application in `src/index.ts`. The example below is a starter Acryl application.
+In a generated app the routes live in `src/routes.ts`, which builds an `Acryl` app and mounts it with `ctx.router.route`; `src/main.ts` picks where the app lives and starts it. The app on its own is plain:
 
-The `import` and the final `export default` are the same on every runtime; what differs is how the runtime starts the app (see [Node.js](nodejs.md) and [Bun](bun.md)).
+The `import` and the final `export default` are the same on Node.js and on Bun; what differs is how the runtime starts the app (see [Node.js](nodejs.md) and [Bun](bun.md)).
 
 ```ts twoslash
 import { Acryl } from 'acrylblends'
@@ -131,7 +136,7 @@ app.get('/', (c) => {
 })
 ```
 
-[JSX](../guides/jsx.md) is not yet available.
+JSX works too: `acrylblends/jsx` renders on the server and in the browser, and the `nodejs` template ships a `.tsx` page. See [JSX](../guides/jsx.md).
 
 ## Return raw Response
 

package/docs/framework/getting-started/desktop.md

@@ -1,7 +1,7 @@
 # Desktop
 
 An Acryl app also runs as a desktop app: an Electron window opens on the app's own server. It is the same app and the same code as `npm run dev`; nothing in the app changes. This page covers a plain Acryl app (the `nodejs`
-template) and a Blend app (the `acryl-app` template or `acrylblends init`). It runs from source today: packaging a distributable app (dmg, exe, deb) is not part of it yet.
+template) and a Blend app (the `agent` template or any other `acrylblends init` template). It runs from source today: packaging a distributable app (dmg, exe, deb) is not part of it yet.
 
 ## Add it
 

package/docs/framework/getting-started/other-runtimes.md

@@ -2,24 +2,20 @@
 
 Acryl is built on Web Standards, so the same application code is expected to run wherever a `fetch`-style handler can run. Node.js ([guide](nodejs.md)) is the runtime the framework is verified on. Bun is experimental ([guide](bun.md)).
 
-## Hosting platforms with an adapter
+## Runtimes with an adapter
 
-These platforms have an adapter in acrylblends, ported from the upstream adapters with their tests. Each is called with the platform's own events in the framework's release check; the ACRYL team has not deployed to these platforms, so try a first deploy on a test project.
+| Runtime | Guide | Import | Status |
+| --- | --- | --- | --- |
+| Node.js | [Node.js](nodejs.md) | `acrylblends/node-server` | Primary. Verified on Node 22 and 24, on Linux, macOS and Windows. |
+| Bun | [Bun](bun.md) | `acrylblends/bun` | Experimental. One smoke gate: the Bun adapter is run on Bun (a static file, the client address, a WebSocket echo). |
 
-| Platform | Guide | Import |
-| --- | --- | --- |
-| AWS Lambda (API Gateway, ALB, Function URLs, VPC Lattice) | [AWS Lambda](aws-lambda.md) | `acrylblends/aws-lambda` |
-| Lambda@Edge (CloudFront) | [Lambda@Edge](lambda-edge.md) | `acrylblends/lambda-edge` |
-| Cloudflare Workers | [Cloudflare Workers](cloudflare-workers.md) | `acrylblends/cloudflare-workers` |
-| Cloudflare Pages | [Cloudflare Pages](cloudflare-pages.md) | `acrylblends/cloudflare-pages` |
-| Vercel | [Vercel](vercel.md) | `acrylblends/vercel` |
-| Netlify | [Netlify](netlify.md) | `acrylblends/netlify` |
-| Service Worker | [Service Worker](service-worker.md) | `acrylblends/service-worker` |
-| Bun | [Bun](bun.md) | `acrylblends/bun` |
+## Removed in 1.0
+
+The upstream also ships adapters for AWS Lambda, Lambda@Edge, Cloudflare Workers and Pages, Vercel, Netlify and Service Workers. They were part of 0.x, ported with their tests, but no gate of ours deploys to any of them, so a 1.0 package does not promise them: they are not built or exported. Their ported sources stay in `plugins/acryl-router/src/core/adapter/` in the repository and may come back as separate plugins, each with its own gate. An app written with `acrylblends` is still plain `fetch` code (`app.fetch(request)`), so a platform that calls a `fetch` handler can call it directly.
 
 ## Not yet verified
 
-The following runtimes and platforms have no adapter and no getting-started page yet:
+The following runtimes and platforms have no adapter and no getting-started page:
 
 - Deno, and Deno Deploy
 - Fastly Compute
@@ -31,4 +27,4 @@ The following runtimes and platforms have no adapter and no getting-started page
 - CloudBase
 - WebAssembly (WASI)
 
-A page is added here, with a getting-started guide, when a platform has an adapter and a test that calls it.
+A page is added here, with a getting-started guide, when a runtime has an adapter and a gate that runs it.

package/docs/framework/guides/create-acrylblends.md

@@ -7,10 +7,12 @@
 
 | Template | What you get |
 | --- | --- |
+| `blank` | the smallest app: the router, a server and one route, with a test |
 | `nodejs` | a web app: routes, a server-rendered JSX page and a client component, mounted by the app's own plugin; run with Node.js 22.19 or newer |
 | `notes` | a full-stack starter: accounts (scrypt, cookie session), notes in SQLite through the [`db` port](data.md) with numbered migrations, validated forms, search, a JSON API with a typed test client, csrf, a test for every route, a client-component counter |
 | `chat` | an AI chat starter: the answer streams token by token from an OpenAI-compatible API (DeepSeek by default, key only from `DEEPSEEK_API_KEY`), a client component with a Stop button that also stops the request to the model, history in SQLite through the [`db` port](data.md), tests with a mock model |
-| `acryl-app` | a Cordis app built from plugins, with an agent that can extend it while it runs (the same app `npx acrylblends init --template agent` creates) |
+| `todo` | a to-do list on the router and state: CRUD routes, a page, tests |
+| `agent` | the blank app with an offline agent that builds plugins into the running app, through the door (`acryl-app` is the old name for it and still works) |
 
 Every template is a Cordis app: `blend.yaml` lists the plugins that are mounted, every plugin is a folder in `plugins/`, and the app is started by `src/main.ts`. A bare template name after the directory is the same as `--template`: `npm create acrylblends@latest my-app notes`. `bun` is no longer a template; the framework still runs on Bun (see [Bun](../getting-started/bun.md)), but a new app is a Cordis app on Node.
 
@@ -51,7 +53,7 @@ bun create acrylblends@latest my-app --template nodejs
 | :-- | :-- | :-- |
 | `[directory]` | The folder to create. It must not exist or must be empty. Asked for when it is missing. | `my-app` |
 | `[source]` | A template from outside the package: `github:owner/repo[#ref]`, `@scope/name[@version]` or a packed `.tgz` file. See [Templates from a repository or a package](#templates-from-a-repository-or-a-package). | `github:acme/starter` |
-| `--template <template>` | One of `nodejs`, `notes`, `chat`, `acryl-app`. Skips the template question; a bare name after the directory means the same. | `--template notes` |
+| `--template <template>` | One of `blank`, `nodejs`, `notes`, `chat`, `todo`, `agent` (the same list as `acrylblends init --template`; `acryl-app` is accepted as `agent`). Skips the template question; a bare name after the directory means the same. | `--template notes` |
 | `--install` | Install the dependencies with the package manager after creating the project. For a template from a source, the install scripts it will run are listed first. | `--install` |
 | `--pm <packageManager>` | The package manager for `--install`: `npm`, `pnpm`, `yarn` or `bun`. Defaults to the one that started the initializer. | `--pm pnpm` |
 | `--yes`, `-y` | Ask nothing: use `nodejs` unless `--template` is given, and the directory `acryl-app`. | `-y` |

package/docs/framework/guides/data.md

@@ -289,7 +289,7 @@ applies the `migrations` folder, and provides `db`; a plugin declares `inject: [
 
 ```ts
 import type { Context } from '@deepseek-ai/cordis'
-import type {} from 'acryl-db'
+import type {} from 'acrylblends/cordis/db'
 
 export const name = 'notes'
 export const inject = ['db']

package/docs/framework/guides/faq.md

@@ -12,7 +12,7 @@ A `json` validation target reads the body only when the request has a JSON `Cont
 
 ## Which runtimes are verified?
 
-Node.js. Bun is experimental. The hosting platforms with an adapter (AWS Lambda, Lambda@Edge, Cloudflare Workers and Pages, Vercel, Netlify, Service Worker) and the ones without are listed on [Other runtimes](../getting-started/other-runtimes.md).
+Node.js. Bun is experimental. The other hosting platforms have no adapter in 1.0; they are listed on [Other runtimes](../getting-started/other-runtimes.md).
 
 ## Where are the parts marked "not yet available"?
 

package/docs/framework/guides/jsx-dom.md

@@ -277,7 +277,7 @@ export default function App() {
 On Node you can skip the bundler: [Client components without a bundler](client-modules.md) serves `.tsx` client modules to the browser with
 this runtime and one script tag, in development and in production.
 
-There is a small JSX Runtime for Client Components. Using this will result in smaller bundled results than using `acrylblends/jsx`. Specify `acrylblends/jsx/dom` in `tsconfig.json`. For Deno, modify the deno.json.
+There is a small JSX Runtime for Client Components. Using this will result in smaller bundled results than using `acrylblends/jsx`. Specify `acrylblends/jsx/dom` in `tsconfig.json`.
 
 ```json
 {

package/docs/framework/guides/production.md

@@ -0,0 +1,43 @@
+# What runs in production
+
+`acrylblends` has two kinds of parts: the ones an app is built from, which run in production, and the development tools that let an agent (or you) work on the running app, which do not. This page says which is which, and exactly what the safety checks around live plugin install do and do not promise. A test (`plugins/driver-pty/test/production.test.ts`) mounts every development tool in one app and checks the table below.
+
+## The table
+
+| Part | In development | With `NODE_ENV=production` |
+| --- | --- | --- |
+| Your routes and plugins, the router, the server, state, the `db` and `kv` ports and their providers | run | run |
+| **The door** (`acryl-door`: `.acryl/bin/acryl`, the page script, the operator routes) | **experimental**: starts when the server is up | starts nothing: no service, no route, no `.acryl/` folder, no script in the page. `ACRYL_DOOR=off` also turns it off. A host that means to run it in production sets `allowInProduction: true` in the plugin's config |
+| **The agent panel** (`agent-panel`) | **experimental**: a script tag on every HTML page and `/api/agent-panel/*` | does nothing (no tag, no routes). `ACRYL_DOOR=off` too |
+| **The PTY driver** (`driver-pty`) | **experimental**: terminal drivers in the panel, `/api/driver-pty/*` | does nothing. `ACRYL_DOOR=off` too |
+| **Live plugin install** (`extensions`, `builder`) | **experimental**: install, update, remove and reload plugins while the app runs | the `nodejs`, `notes` and `chat` templates leave the `extensions` row out; the `agent` template does not (see below) |
+| `acrylblends/bun` | **experimental**: one smoke gate runs it on Bun | the same |
+
+Experimental means: it works and is gated, its interface may still change in a minor version, and it is not for the public internet. The door and the panel are loopback and own-page only, with a per-run secret and an audit log; that is a convenience fence for a developer's machine, not an authentication system.
+
+## The `agent` template is a development app
+
+The `agent` template mounts an agent behind `POST /ask` that can write plugins into the running app (`builder`) and install them (`extensions`). Only its door is left out in production. Do not deploy it as it is: remove the `agent`, `builder` and `extensions` rows from `blend.yaml` (or start from `blank`, `nodejs`, `notes`, `chat` or `todo`), and if live install is wanted anywhere shared, set `approval: true` so an install waits for `POST /extensions/approve`.
+
+## What live plugin install does and does not promise
+
+Installing a plugin (`ctx.extensions.install`, the door's `plugin add`, the builder's `install_plugin`) is a **correctness check, not a security boundary**:
+
+- It stages a content-hashed copy, imports it, mounts it, and reports the real state (`active`, `pending` with what it waits for, or `failed` with the error). If an update fails to start, the previous version is mounted again. A ledger line records every change.
+- **The plugin's code runs inside the app's own process with the app's permissions**: it can read the app's files and environment, open sockets and start processes. Nothing in the install check stops that.
+- At start-up the app reinstalls what was installed, and installs a new folder only from a source trusted to `install` (the app's own `plugins/` is). Code that arrived through a `git pull` into an untrusted source is listed, not run.
+- `approval: true` holds an install until someone posts to `/extensions/approve`: it decides *whether* a plugin installs, not what an installed plugin can do.
+
+## What the sandbox does and does not stop
+
+`ctx.sandbox` runs code you do not trust, such as a **tool** an agent just wrote, in a separate Node process with the permission model on (`node --permission`):
+
+- It **stops**: reading any file outside the tool's own folder; writing files; starting child processes or workers; loading native addons; using the inspector. It gets an empty environment (no keys, no paths). It is killed after a time limit and capped in memory and output size. Calls are independent: nothing survives into the next one.
+- It **does not stop**: network access (Node 24 has no network permission: restrict egress outside the process where that matters), and it does not apply to plugins installed live (those are not run in the sandbox).
+
+## Checklist for a deployment
+
+1. `NODE_ENV=production` (the process manager or the Dockerfile sets it; the templates' Dockerfile does).
+2. Start from a template that is not `agent`, or remove the agent rows.
+3. Do not set `allowInProduction` on the door unless the host is a single-user desktop app.
+4. Keep `ACRYL_DOOR=off` in any environment where an agent should not be able to see the page.

package/docs/framework/guides/rpc.md

@@ -584,21 +584,13 @@ const route = app.put(
 
 ## Custom `fetch` method
 
-You can set the custom `fetch` method.
-
-In the following example script for Cloudflare Worker, the Service Bindings' `fetch` method is used instead of the default `fetch`.
-
-```toml
-# wrangler.toml
-services = [
-  { binding = "AUTH", service = "auth-service" },
-]
-```
+You can set the custom `fetch` method: anything with the `fetch` signature works in place of the global one, such as a client that adds a header or a test double.
 
 ```ts
 // src/client.ts
 const client = hc<CreateProfileType>('http://localhost', {
-  fetch: c.env.AUTH.fetch.bind(c.env.AUTH),
+  fetch: (input, init) =>
+    fetch(input, { ...init, headers: { ...init?.headers, authorization: `Bearer ${token}` } }),
 })
 ```