@antelopejs/dms-frontend 0.6.1 → 0.6.2

package/README.md

@@ -1,978 +1,94 @@
-# @antelopejs/dms-frontend
-
 <div align="center">
-<a href="./LICENSE"><img alt="License" src="https://img.shields.io/badge/license-Apache--2.0-blue?style=for-the-badge&labelColor=000000"></a>
-<a href="https://discord.gg/sjK28QHrA7"><img src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000" alt="Discord"></a>
-<a href="https://antelopejs.com"><img src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000" alt="Documentation"></a>
-</div>
 
-Frontend-agnostic loader for AntelopeJS DMS. The backend serves a frontend
-manifest and the matching frontend-module archives; the `ajs dms` CLI
-materializes them into a generated workspace for one renderer, builds it, and
-runs its Node frontend server. The `vue` renderer — Vue 3, Vite, Inertia, and
-SSR — is the one shipped today. The package itself installs a single executable,
-`ajs-dms`; `ajs dms` is the core CLI delegating to it, and is the name every
-project, script and document uses.
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/AntelopeJS/dms/main/packages/dms/frontend-vue/layers/dms-layout/public/images/antelope-logo/dark.svg">
+  <img alt="Antelope DMS" src="https://raw.githubusercontent.com/AntelopeJS/dms/main/packages/dms/frontend-vue/layers/dms-layout/public/images/antelope-logo/light.svg" height="72">
+</picture>
 
-## Renderers
-
-A renderer is the target framework a generated workspace is built for. The
-loader's contract with a renderer has three parts:
-
-- **Manifest negotiation.** `prepare`, `dev`, and `build` request the versioned
-  `/dms/frontend` manifest with `renderer=vue&rendererVersion=3`
-  (`src/manifest.ts`) and reject every module whose `renderer` does not match.
-  The backend side is renderer-keyed too: `AddFrontendModule` takes a
-  `renderer: { name, version }`, and each manifest module carries it back
-  (`ManifestModule.renderer` in `src/workspace.ts`).
-- **Workspace templates.** Every file of the generated workspace comes from
-  `templates/<renderer>/` — `templates/vue/` today. `TEMPLATE_FILES` in
-  `src/config.ts` lists what is copied verbatim, and `src/materialize.ts`
-  resolves the template root, copies it, materializes the frontend modules
-  under `frontend-modules/`, and writes the files derived from them
-  (`src/derived-outputs.ts`), `generated-frontend-modules.json` first, in
-  manifest-priority order.
-- **Generated server.** `templates/vue/server.mjs` and `templates/vue/server/`
-  become the Node server that `ajs dms start` runs from the built workspace:
-  Inertia visits, backend proxying, sessions, and email rendering.
+# @antelopejs/dms-frontend
 
-`vue` (version `3`) is the only renderer this package ships, and the loader
-rejects a manifest that declares any other. Renderers for other frameworks —
-React, Svelte, Solid — are a direction, not a promise: nothing in the package
-implements them yet. Adding one means a new `templates/<renderer>/` tree, plus
-making the template root (`src/materialize.ts`) and the manifest query
-(`src/manifest.ts`) renderer-aware instead of hardcoding `vue`. There is no
-`--renderer` flag and no renderer registry; the single-renderer assumption is
-deliberate until a second renderer exists. Whatever a renderer names its module
-entry is its own convention: `dms.frontend.ts` and the
-`#dms/frontend-module` alias belong to the Vue renderer, not to the
-loader.
+<a href="https://www.npmjs.com/package/@antelopejs/dms-frontend"><img alt="npm" src="https://img.shields.io/npm/v/@antelopejs/dms-frontend?style=for-the-badge&labelColor=000000&color=000000"></a>
+<a href="./LICENSE"><img alt="License" src="https://img.shields.io/npm/l/@antelopejs/dms-frontend?style=for-the-badge&labelColor=000000&color=000000"></a>
+<a href="https://discord.gg/sjK28QHrA7"><img alt="Discord" src="https://img.shields.io/badge/Discord-18181B?logo=discord&style=for-the-badge&color=000000"></a>
+<a href="https://dms.antelopejs.com/docs/frontend"><img alt="Documentation" src="https://img.shields.io/badge/Docs-18181B?style=for-the-badge&color=000000"></a>
 
-## Application ownership
+**The frontend of the AntelopeJS DMS: the `ajs dms` CLI, the Vue renderer and the frontend-module SDK.**
 
-The generated Inertia application owns page resolution, SSR, hydration, and the
-root Vue tree. Every frontend module explicitly owns its native
-`dms.frontend.ts` entry. That entry registers reusable pages, layouts,
-components, plugins, and middleware through the frontend SDK; the loader does
-not infer application ownership from other framework configuration.
+[Documentation](https://dms.antelopejs.com/docs/frontend) · [DMS](https://github.com/AntelopeJS/dms) · [Modules](https://dms.antelopejs.com/docs/modules)
 
-## Install
+</div>
 
-The loader is an official AntelopeJS CLI plugin: install it next to
-`@antelopejs/core` and run it as `ajs dms <command>`. That is the only supported
-way to invoke it — in a shell, in a package script, in CI and in a container
-alike.
+![The browser talks to the frontend server, which renders pages, answers module routes and proxies declared backend prefixes to the DMS backend; at build time ajs dms fetches the manifest and writes a workspace](./docs/images/architecture.svg)
 
-```bash
-# in a project (the usual case: both are already project dependencies)
-pnpm add @antelopejs/core @antelopejs/dms-frontend
+## What it does
 
-# or globally
-pnpm add -g @antelopejs/core @antelopejs/dms-frontend
-```
+- Asks a DMS backend which frontend modules it loads, materializes them into a generated workspace, builds it, and runs the frontend server.
+- Renders the dashboard with Vue 3, Vite, Inertia and server-side rendering.
+- Keeps the backend token on the server: the browser only holds a sealed, `HttpOnly` session cookie, and declared backend prefixes are proxied with the session's token.
+- Lets a module extend the dashboard with pages, components and plugins (`dms.frontend.ts`), server routes (`dms.server.ts`) and build-time declarations (`dms.frontend.build.ts`).
+- Serves development with hot reload, and production with pre-compressed assets.
 
-The plugin prints through the output module of `@antelopejs/core`
-(`@antelopejs/core/cli`), so it needs `@antelopejs/core` 1.13.2 or later.
-`npm install -g` works too; this repository and every generated workspace use
-pnpm. Inside a package script, `ajs` resolves from `node_modules/.bin`, and the
-`dms` command it delegates to resolves the project-local plugin, so a script
-never depends on a global install.
+## Install
 
-## Commands
+Add the package next to `@antelopejs/core`; the core `ajs` command runs it as `ajs dms`:
 
 ```bash
-ajs dms prepare -b http://localhost:5010
-ajs dms dev -b http://localhost:5010 -p 3001
-ajs dms build -b https://dms.example.com
-ajs dms start -b https://dms.example.com -p 3001
-ajs dms workspaces
-ajs dms workspaces --json
-ajs dms clean -b https://dms.example.com
-ajs dms clean --all
-ajs dms help environment
-```
-
-`ajs dms <command> --help` shows what a command does, its options and a few
-examples. `ajs dms help environment` lists every variable the CLI and the
-generated server read, from the environment or the project's `.env`.
-
-`--help`, `--version`, `workspaces` and `clean` run from any directory. `build` and `start`
-need a backend URL through `-b` or `DMS_API_BASE_URL`, and exit 2 without one.
-`dev` also discovers it from the enclosing antelope project's
-`.antelope/dev.json`, and exits 1 when there is none to discover.
-`verify-source` needs no backend: it runs in the project that installs `@antelopejs/dms`.
-
-`prepare` runs anywhere: when it cannot prepare the workspace it warns on
-stderr and exits 0, so a frontend module's `postinstall` hook never fails an
-install. The warning says whether prepare was skipped or failed. Skipped means
-no backend is in reach (no URL, an unreachable backend, `--offline` without a
-cached manifest), as in CI: the generated types are refreshed later from a
-development environment. Failed means something a later run will not fix: a
-refused credential, an incompatible manifest or renderer range, an invalid URL.
-A step that needs the types, such as a CI type-check, passes `--strict` (or
-sets `DMS_PREPARE_STRICT=1`): prepare then exits 1 in every one of these cases,
-and 2 when the backend URL is missing or invalid. On success, it says how many
-modules it found and how long it took.
-
-`build` ends with where it wrote the production frontend (the `dist`
-directory of the workspace), how long it took, and the `ajs dms start` command
-to run next, with the same backend URL and `DMS_SESSION_SECRET`. Its output is
-deployed, so it never builds silently from the cache: when the backend cannot
-be reached or fails, `build` exits 1, says whether a cached manifest exists and
-how old it is, and builds from it only when asked with `--offline`. `dev` and
-`prepare` still fall back to the cache, with a warning.
-
-The commands follow the output contract of `ajs`: what the CLI itself prints
-on stdout is only the help and the version, and everything else (progress,
-warnings, errors) goes to stderr. The dependency install and each step of the
-production build run as one progress line each: their output is kept and its
-last lines are shown when they fail, with paths into the generated workspace
-pointing at the frontend-module sources instead. The server `dev` and `start`
-run keeps its own output. A command exits 0 on success, 1 on a failure, 2 on a
-usage error (an unknown command or option, a missing or invalid argument, a
-missing configuration value) and 130 when stopped with Ctrl+C. `--no-color` or
-`NO_COLOR=1` turns colors off, and terminals that cannot draw Unicode, such as
-`TERM=dumb`, get ASCII symbols. `--verbose` or `ANTELOPEJS_VERBOSE` streams
-the full `pnpm` and Vite output, each line behind the name of the step, and adds
-the stack trace of the underlying error to a failure; `--verbose=<channels>`
-turns all of it on too, whatever the channels. `-q`, `--quiet` or
-`ANTELOPEJS_QUIET=1` prints only results, warnings and errors: no command
-header, progress, summary or update notice, and of the block a ready `dev` or
-`start` server prints, only its Local URL. `ajs --no-color dms …`,
-`ajs --verbose dms …`, `ajs --verbose=<channels> dms …` and `ajs -q dms …` set
-those variables for the plugin; the same flags are also accepted after the
-command, as in `ajs dms build -q`.
-
-The CLI checks npm for a newer release at most once a day and prints a one-line
-notice on stderr, only to a terminal: as the last line of a command that
-succeeded, or under the ready block of `dev` and `start`. Help, `--version`,
-`--json`, failed commands, pipes and `TERM=dumb` never show it. The lookup starts
-with the command and never delays its exit; a lookup that comes back empty —
-offline or throttled — is retried after an hour instead of counting as the day's
-attempt. The throttle stamp lives at
-`~/.antelopejs/dms-frontend/update-check.json`. Set `NO_UPDATE_NOTIFIER=1`, pass
-`--no-update-check`, or run under `CI` to turn the check off.
-
-Manifest negotiation and module materialization are the renderer contract described in [Renderers](#renderers).
-
-The generated Vue application uses `@inertiajs/vue3`, `@nuxt/ui/vite` with `{ router: "inertia" }`, and `@nuxt/ui/vue-plugin`. The Node server resolves each Inertia visit through `/dms/page?path=…`; the site layout it returns comes as a once prop the browser reuses for five minutes per account and workspace (see [Navigation and the site layout](#navigation-and-the-site-layout)). It proxies backend routes and manages authentication through server-side sessions. `DMS_BOOTSTRAP_SECRET` is used only by the CLI's server-to-server frontend manifest and module archive requests and is never sent by, or exposed to, browser traffic.
-
-Vue modules register through `dms.frontend.ts` and import the SDK from the `#dms/frontend-module` alias, which the loader resolves to the generated `frontend-module.ts`: `defineDmsPlugin`, `useDmsRouter`, the page and session types, and everything else a module needs from the host. Email templates register separately through `dms.email.ts`.
-
-An email entry exports `serverEmailTemplates` and may export a plain `appConfig` object, such as shared branding defaults. Email rendering merges these configurations with the layers' [app configs](#app-config-appappconfigts) and provides the result to `useDmsAppConfig` per render: module by module, in manifest-priority order, a module's email `appConfig` first, then its layers' `app/app.config.ts`. A higher-priority module's layers thus override a lower one's email `appConfig`, and a module's email `appConfig`, the more specific of its two, keeps the values it gives emails over its own layers. Public runtime options come from the module manifest; `DMS_CLIENT_BASE_URL` overrides `public.dms.clientBaseUrl`. Email entries must not import the browser frontend module. The rendered HTML carries no Vue hydration comments (`<!--[-->`, `<!---->`, teleport anchors): an email is never hydrated, so the renderer strips them, and keeps every other comment, Outlook's conditional comments included.
-
-Email builds ship complete merged translation catalogs as JSON under `dist/server/locales/`, separate from executable JavaScript. Deploy the entire `dist/server` directory. Each render loads only its requested language and the English fallback; arbitrary translation keys and module overrides remain available. Unknown languages fall back to English, while missing or corrupt files for a supported language fail rendering rather than silently dropping translations. The source harness keeps the 256 KiB JavaScript ceiling and reports locale-data bytes separately.
-
-`ajs-dms dev` builds the email bundle too, once the dev server is ready, and rebuilds it whenever an email template changes. The build runs in a separate low-priority process, so page reloads and HMR never wait on it; a render requested while a build is running waits for that build to finish.
-
-## Frontend modules
-
-Moving a module, or the DMS, from 0.5 to 0.6: see
-[Migrating to 0.6.0](docs/migration-0.6.md).
-
-A materialized module opts into the Vue adapter with a root `dms.frontend.ts`:
-
-```ts
-import MyBlock from "./components/MyBlock.vue";
-import MyPage from "./pages/MyPage.vue";
-import type { DmsFrontendModule } from "#dms/frontend-module";
-
-const frontendModule: DmsFrontendModule = {
-  setup(sdk) {
-    sdk.registerComponent("MyBlock", MyBlock);
-    sdk.registerPage("default", MyPage);
-  },
-};
-
-export default frontendModule;
-```
-
-The SDK also exposes `use` for Vue plugins. Entries execute by descending manifest priority, then stable module id. Modules without `dms.frontend.ts` are skipped by the generated loader. Registered page keys match a route's `fullSlug`, request path, or `default`; unregistered pages and components use the generic card renderer.
-
-Within one setup, the first module to register a name keeps it. `ajs-dms dev` sets every module up again each time a change to a layer reaches the server renderer, into empty registries, so the next server render uses the edited component without a restart. A `setup` may therefore run more than once in a process: it should only register, and keep no state of its own between runs.
-
-### App config (`app/app.config.ts`)
-
-Each layer of a module, or the module root when it has no `layers/` directory, may hold an `app/app.config.ts` whose default export is a plain object: branding, Nuxt UI's `ui` (colors, icons, component themes), anything the modules read through `useDmsAppConfig()`.
-
-```ts
-export default defineDmsAppConfig({
-  branding: { logo: { light: "/branding/logo.svg" } },
-  ui: { colors: { primary: "emerald" } },
-});
-```
-
-The loader merges every one of them with `defu` (records key by key, arrays concatenated) before the first module is set up, so `useDmsAppConfig()` already holds the result when a `setup` runs: modules in manifest-priority order, and within a module its layers from the last by name to the first, the order in which a contested `public/` file is resolved. A project's layer therefore overrides the DMS's, and the DMS fills in everything the project leaves out. A `setup` may still read and extend the config. Nuxt UI's own app config is merged from the result, and so are emails' (see above). The file is TypeScript only, and is imported in Node.js by the server renderer and the email bundle as well as in the browser: it must not touch browser globals when it loads.
-
-`ajs-dms dev` applies an edit at once: the next server render uses it, and the open page updates `useDmsAppConfig()` and Nuxt UI's app config in place, colors included, without a reload. What the modules' `setup` changed in the config stays on top of the edited values; adding or removing a config file is applied the same way.
-
-Up to 0.5.6, the loader applied none of these files: an entry merged its own into `useDmsAppConfig()` in its `setup`, as the DMS up to 0.8 does (`Object.assign(useDmsAppConfig(), defu(useDmsAppConfig(), appConfig))`). Such an entry keeps working, its values unchanged, but its config is now merged twice, and `defu` concatenates arrays: every array it declares, Nuxt UI's `compoundVariants` among them, holds its entries twice. Nuxt UI resolves the repeated classes through `tailwind-merge` to the same ones, so nothing changes on screen, but an entry should stop merging its own config once it requires a release of the loader that applies it. The DMS does so in a release coordinated with this one. Until then, an edit to a config its entry imports reloads the page instead of updating it in place, since the entry imports it too.
-
-### Component prefix
-
-Every registered component joins the application's global components and resolves by name anywhere, in templates and in backend page trees. To keep the components of two modules from colliding, a module declares a `componentPrefix`, put in front of the name of every component it registers:
-
-```ts
-const frontendModule: DmsFrontendModule = {
-  componentPrefix: "Acme",
-  setup(sdk) {
-    sdk.registerComponent("Banner", Banner); // registered as AcmeBanner
-  },
-};
-```
-
-The full name, prefix included, is the one a template uses (`<AcmeBanner>`) and a backend sends (`CustomComponent("AcmeBanner")`, or `acme-banner`). Names are compared ignoring case, a leading `lazy` and non-alphanumeric characters; a leading `Dms` is no longer dropped, since it is the DMS module's own prefix.
-
-When two modules register the same name, the module of higher priority keeps it and a warning names both. A module that means to replace another's component registers its full name without its own prefix, which is not reported:
-
-```ts
-sdk.registerComponent("AcmeBanner", MyBanner, { prefix: false });
-```
-
-A module's `app/build/` directory is never auto-imported (see below): its components are registered so backend pages can name them, but they are the module's internals, not a surface other modules should build on.
-
-### Auto-imports (`dms.frontend.build.ts`)
-
-Nothing a module ships is auto-imported unless the module declares it, in an optional `dms.frontend.build.ts` next to its `dms.frontend.ts`:
-
-```ts
-import { defineDmsFrontendBuild } from "#dms/frontend-build";
-
-export default defineDmsFrontendBuild((build) => {
-  build.registerAutoImports([
-    "layers/*/app/composables",
-    "layers/*/app/utils",
-    "layers/*/app/types",
-  ]);
-});
-```
-
-Each entry is a directory relative to the module root, glob patterns allowed; every export of the files under it becomes available to the whole application without an import, in scripts and templates. A module without the file has nothing auto-imported. `app/build/` holds a module's private code and is never auto-imported: it is left out of what a broader entry covers, and an entry naming it, or a directory outside the module, is ignored with a warning when Vite starts.
-
-The file runs in Node.js when Vite starts, under `ajs dms dev` and `ajs dms build`, not in the application: it may import `#dms/frontend-build` and Node.js built-ins, never the application's code. Vite restarts when one changes.
-
-Up to 0.3, every module's `app/composables`, `app/types`, `app/utils`, `app/build/composables` and `app/build/types` were auto-imported. A module that relies on auto-imports declares its public directories in `dms.frontend.build.ts`, and imports its `app/build/` code by path.
-
-### Server routes (`dms.server.ts`)
-
-A module serves routes from the frontend server, next to the session, in an optional `dms.server.ts` beside its `dms.frontend.ts`: a sign-in flow that writes cookies, a provider redirect, a render a backend asks for.
-
-```ts
-import { defineDmsServer } from "#dms/server";
-import { ping, startExport } from "./server/routes";
-
-export default defineDmsServer((server) => {
-  server.registerRoute("GET", "/api/_acme/ping", ping);
-  server.registerRoute("POST", "/api/_acme/exports/:kind", startExport);
-});
-```
-
-```ts
-// server/routes.ts
-import type { DmsServerEvent } from "#dms/server";
-
-export function ping() {
-  return { ok: true };
-}
-
-export async function startExport(event: DmsServerEvent) {
-  const input = await event.readJson<{ from: string }>();
-  return event.backend(`/api/acme/exports/${event.params.kind}`, {
-    method: "POST",
-    body: input,
-    token: event.session.read()?.accessToken,
-  });
-}
-```
-
-A handler takes the request and answers with a Web-standard `Response`, or with a value sent as JSON (`null` or nothing is an empty `204`). The event it receives carries:
-
-- `request`, `url`, `params` (the `:name` segments, decoded) and `readJson()`;
-- `session`: `read()`, `write()` (stamped with `updatedAt`, ends with the browser unless `persistent`), `clear()`, `useForRequest()`;
-- `cookies`: sealed cookies by logical name (`readSealed`, `writeSealed` with an optional `maxAge` and `path`, `clear`). The server scopes the name to its backend and sets `HttpOnly`, `SameSite=Lax` and `Secure`, so a module never depends on how cookies are named; the session cookie is only reachable through `session`. The `dms_*` names belong to the module that owns sign-in (the one whose `registerAuth` is used): another module naming one gets an error, and its own cookies are stored as `<module id>.<name>`, so no module reads or overwrites another's;
-- `backend(path, init)`: a JSON call to the backend that always carries the client's address and the headers the proxy relays; a refusal throws an error with the status and the backend's public `error.*` message, which reaches the client as is when the handler lets it through;
-- `backendUrl(path)`: the backend URL of a path, always on the backend's origin, for a call `backend` cannot make (a raw response);
-- `clientIp()`, `renderEmail(template, props, { locale })`, and `module`: this module's id, its options and its own `privateOptions`, never another module's.
-
-Every route gets the same defaults: a request with a state-changing method must carry the frontend's own `Origin` (`{ sameOrigin: false }` only for a route authenticated otherwise, such as by a service token), its body stops at 64 KiB (`bodyLimit`) with a `413`, and the answer is `Cache-Control: no-store` unless the handler sets its own. An error the handler lets through is answered like a backend failure: its status, and only a public `error.*` message.
-
-Paths are literal segments and `:name` parameters. Module routes are tried after the renderer's own (`/api/_dms/`, `/@…`, `/assets/`, which no module can declare) and before the backend proxy, literal paths before parameters. A route under `/api/` or `/dms/` outside a module namespace (`/api/_<module>/`) hides what the backend serves there, so the server warns unless the route passes `{ overridesBackend: true }`. When two modules declare the same method and path, the module of higher priority keeps it and a warning names both, the module id settling a tie; a module route answering a [public endpoint](#public-endpoints) is reported too. A malformed declaration is ignored with a warning naming its module.
-
-`dms.server.ts` runs in the frontend server's Node.js process, next to the session secret: it is trusted code, as the module's backend half is, not a sandbox. Every route reads the session (`event.session.read()`, access and refresh tokens included) and may write it; only install a module whose `dms.server.ts` you trust as much as the DMS's own. It may import `#dms/server`, Node.js built-ins, npm dependencies and the module's own server files (a `server/` directory is copied into the workspace for that), never the application's code (`.vue` files, `dms.frontend.ts`); nothing it imports reaches the browser bundle, and `verify-source` checks both. Under `ajs dms dev` the server loads it through Vite, so an edited handler answers on the next request; `ajs dms build` bundles it into `dist/server-modules`, and a workspace built without that bundle simply serves no module route. Import what a handler uses: auto-imports do not apply to server code.
-
-A module tests its routes through the same router, event and cookie jar with `serveModuleRoutes` from `@antelopejs/dms-frontend/templates/vue/server/module-testing.mjs`, which serves the default export of its `dms.server.ts` on a local port.
-
-#### Session hooks
-
-The server also runs session logic outside any route: it renews a session the backend refused on a page visit, puts the `user` and `session` page props together, and sends a signed-out visit to sign in. The module that owns sign-in provides it:
-
-```ts
-server.registerAuth({
-  signInPath: "/auth",
-  signInExempt: ["/auth/**", "/onboarding"],
-  refreshSession: renewSession, // (event, session) => the new session, or undefined
-  publicSession: (session) => ({
-    user: session.user,
-    session: { accountId: session.accountId, activeTenantId: session.activeTenantId },
-  }),
-});
+pnpm add -D @antelopejs/core @antelopejs/dms-frontend
 ```
 
-`refreshSession` is called once when the backend answers `401` to a signed-in page visit, which is then retried with the session it wrote (`event.session.write`). `publicSession` gives the page props of a signed-in session; the server adds `session.updatedAt`, the stamp of its last write, which the browser compares to drop a page restored from its cache (see [Interface language](#interface-language)), and `event.session.view()` returns the same props to a route. `signInExempt` patterns are `/x`, `/x/*` (one segment below) or `/x/**` (the page and everything below); left out, they are `<signInPath>/**` and `/onboarding`, so a custom `signInPath` is exempt on its own. The highest-priority module that registers them provides all of them; another one is reported and ignored.
-
-#### Route rules
-
-A module also declares how its pages are rendered and cached, by page pattern (`/x`, `/x/*` one segment below, `/x/**` the page and everything below):
-
-```ts
-server.registerRouteRules({
-  "/terms-of-use": { cache: { public: true, maxAge: 300, staleWhileRevalidate: 3600 } },
-  "/builder/**": { ssr: false },
-  "/reports/**": { headers: { "x-robots-tag": "noindex" } },
-});
-```
-
-- `cache`: page documents and Inertia answers default to `private, no-cache`, since they carry the visitor's session. A public `cache` replaces it, with `Vary: Cookie`, only for a `GET` of a page the backend serves to anyone (`publicAccess`), answered `200` to a request without any cookie and without `x-content-language`: such an answer holds nobody's data. Any other request keeps the private default. The frontend server itself stores nothing; the rule is for a shared cache or a CDN in front of it. `cache: false` keeps the default under a broader rule.
-- `ssr: false`: a document request gets the client-rendered shell instead of a server render; Inertia visits are unchanged.
-- `headers`: added to the page's document and Inertia answers; `cache-control`, `vary`, `set-cookie` and the content and Inertia headers stay the server's.
-
-The rules matching a page merge from the least to the most specific pattern; for one pattern, the highest-priority module's rule wins, with a warning. A rule never changes who may see a page.
-
-The renderer serves no route of its own besides its files and icons: the session, sign-in, OAuth and e-mail render routes are the DMS's (`dms.server.ts`), the API tester is the DMS API's. Without a module that registers auth hooks, pages carry no `user` and `session` and a refused session is not renewed.
-
-A module that ships `dms.server.ts` raises its [loader range](#declaring-the-loader-releases-a-module-supports) floor to the release that serves it: an older one never reads the file, so the routes would silently be missing.
-
-### Page loading state
-
-After a client navigation, the page renders under a `<Suspense>` until its chunk and any async `setup` resolve. `useDmsPageLoading()` (auto-imported) is `true` meanwhile, so a layout can show its own placeholder instead of an empty page body:
-
-```vue
-<script setup lang="ts">
-const pageLoading = useDmsPageLoading();
-</script>
-
-<template>
-  <slot />
-  <PageSkeleton v-if="pageLoading" />
-</template>
-```
-
-It stays `false` on the server and during hydration, which render the page resolved, for a page that does not suspend, and once a pending page is left.
-
-### Interface language
-
-The interface language follows the session (`useDmsUserSession().user.language`), not the props of the page on screen: the first render takes it from the session the page arrived with, and it changes when the session's language does, after `useDmsUserSession().fetch()` or a visit with a newer session. A page Inertia restores from history or serves from its prefetch cache carries the session it was fetched with: the frontend server stamps every session it writes (`session.updatedAt`), and a page carrying an older stamp of the same account updates neither the session nor the language. A session without a language, such as a signed-out one, keeps the language on screen; `$i18n.setLocale()` still switches it at any time. It also remembers a language the application offers in the `dms_locale` cookie (one year, `SameSite=Lax`), and a page without a signed-in user's language, such as a public sign-in page, first renders in that one: a visitor's choice survives a reload, while a signed-in user's own language still comes first.
-
-### Declaring the loader releases a module supports
+## Quick start
 
-A frontend module names the `@antelopejs/dms-frontend` releases it runs on in its own `package.json`, the way a package names the Node.js versions it supports:
-
-```json
-{
-  "name": "@acme/dms-billing-frontend-vue",
-  "engines": {
-    "@antelopejs/dms-frontend": ">=0.6.0 <0.7.0"
-  }
-}
-```
-
-`prepare`, `dev`, `build` and `verify-source` read it before they generate anything, whether the manifest was just fetched or replayed from the cache, and stop when this release falls outside a module's range: `dev`, `build` and `verify-source` exit 1, and `prepare` warns and exits 0, as it does for any setup it cannot complete, unless `--strict` is given. The message names each such module, its range and this release, rather than letting the build, the type-check or a render fail later on an API the release no longer has, or does not have yet. A prerelease is checked as the release it leads to: `0.4.0-next.1` is outside `<0.4.0`. A module that declares no range still loads, and a warning names it once. `start` checks nothing: it runs what `build` produced.
-
-Cap the range below the next breaking release, which is the next minor release while this package is 0.x, and widen it once the module has been checked against that release. A range left open to `<1.0.0` admits the very release that removes something the module calls.
-
-The range is an engine rather than a peer dependency: the generated workspace installs every module as a workspace package, and pnpm installs a workspace package's peer dependencies, optional ones included, so a peer on the loader would pull a copy of it into every workspace. Package managers ignore an engine they do not know, and so does a loader released before this check.
-
-### Redirecting typed access refusals
-
-A backend can refuse a whole surface with a typed 403 whose body is a machine-readable code, such as a tenant access gate blocking a suspended workspace. A module that owns such a code registers where a refused page visit goes instead of the error page:
-
-```ts
-sdk.registerAccessRedirect(
-  "saas.errors.workspace.access_blocked",
-  "/workspace-suspended",
-);
-```
-
-The server answers the refused visit, document or Inertia, with a redirect to that path before anything renders, so a reload lands there directly. The body may be the bare code or JSON (`"code"` or `{ "message": "code" }`). A destination refused in turn keeps the error page instead of looping. The first registration of a code wins, in manifest-priority order.
-
-### Components rendered inside `<svg>`
-
-Modules usually register their components lazily, with `defineAsyncComponent`, and the page is rendered under a `<Suspense>`. Vue mounts an async component that resolves under a `<Suspense>` with the `<Suspense>`'s element namespace rather than the namespace of the place it is rendered: a component resolved by name (`resolveComponent` or a template tag) whose root is an SVG element (`<path>`, `<g>`, …) is created as an HTML element inside the `<svg>`, and the browser draws nothing ([vuejs/core#15639](https://github.com/vuejs/core/issues/15639)). Import such components directly instead, for example the node and edge types passed to Vue Flow:
-
-```ts
-import { markRaw } from "vue";
-import RelationEdge from "./RelationEdge.vue";
-
-const edgeTypes = markRaw({ relation: RelationEdge });
-```
-
-### Layer aliases outside the workspace
-
-Every layer a module ships under `layers/<name>/` answers to `#<name>` inside
-the generated workspace. That convention is exported, so a module's own tooling
-can reuse it instead of restating it — a unit test runs the module's Vue
-sources outside the workspace, where nothing otherwise supplies `#dms-core` or
-`#dms-ui`:
-
-```ts
-// vitest.config.ts, in a DMS frontend module
-import { frontendLayerAliases } from "@antelopejs/dms-frontend/common";
-
-export default defineConfig({
-  resolve: {
-    alias: frontendLayerAliases(
-      resolve(__dirname, ".antelope/cache/@antelopejs/dms/frontend-vue"),
-    ),
-  },
-});
-```
-
-`frontendLayerAliases` reads a module root on disk and needs no backend,
-manifest or materialized workspace. `frontendLayerTypePaths` returns the same
-layers in tsconfig `paths` shape, and `resolveFrontendLayers` is the primitive
-behind both. Pass several module roots in increasing precedence to overlay
-them: when two modules expose a layer of the same name, the last one wins,
-which is the order the loader itself materializes them in.
-
-## Discovery, caching, and security
-
-In development, `ajs dms` discovers the backend from the nearest live `.antelope/dev.json`. It reads the local bootstrap credential from `.antelope/dms-dev.json` only when that discovered backend matches the destination URL. For production and CI, set `DMS_API_BASE_URL` and `DMS_BOOTSTRAP_SECRET` in the environment, or in the project's `.env`, rather than passing credentials on the command line.
-
-Each canonical backend URL gets an owner-only workspace under `~/.antelopejs/dms-frontend` (see [Workspaces](#workspaces) for how the key is derived). Manifest caches, private module configuration, and extracted archives retain restrictive permissions. `--offline` reuses the last successful manifest and archive; `dev` and `prepare` also fall back to them when the backend cannot be reached or fails, and `build` only with `--offline`. An authorization failure never falls back to privileged cached data.
-
-## Configuration
-
-Every command loads `.env.local` then `.env` from the **current working
-directory** before it parses its options, so a project can keep its
-configuration in a file instead of exporting variables by hand:
+In a DMS project started with `ajs project run -w`, serve the dashboard with hot reload:
 
 ```bash
-# .env
-DMS_API_BASE_URL=http://localhost:5010
-DMS_CLIENT_BASE_URL=http://localhost:3001
-DMS_BOOTSTRAP_SECRET=replace_with_a_strong_random_value
-DMS_SESSION_SECRET=replace_with_at_least_32_characters
-```
-
-Precedence is environment, then `.env.local`, then `.env`: a variable already
-present in the environment is never overwritten, so `DMS_API_BASE_URL=… ajs dms
-build` and a CI job's injected secrets always win over a file left in the
-checkout. A variable exported as an empty string counts as set. Only the
-current directory is read — never a parent directory, and never the generated
-workspace under `~/.antelopejs/dms-frontend`, which is this tool's own output
-and is handed its environment explicitly by the command that spawns it. The
-values loaded here reach the workspace build started by `build`, the dev server
-started by `dev`, and the production server started by `start`, because those
-child processes inherit the environment. A missing file is not an error; an
-unreadable one is reported and skipped.
-
-`ajs dms dev` generates a fresh ephemeral 32-byte secret when
-`DMS_SESSION_SECRET` is absent; all sessions are invalidated when that dev
-server restarts. An explicit value is preserved, but empty or shorter than 32
-characters is rejected. `build` and `start` require a configured secret and
-never generate one, which is required for production so sessions survive
-restarts. The generated server also validates the value as a safety net.
-Generate one with `openssl rand -hex 32`.
-
-### Opening a session from a module flow
-
-`/auth/login`, `/auth/signup` and `/auth/verify-2fa` are not the only ways a
-visitor becomes authenticated: a module can own a flow that ends in an
-authenticated user — a self-service registration completing after payment, an
-invitation being redeemed — and needs the session cookie opened at the end of
-it. `POST /auth/establish` is the generic form of those three routes.
-
-The browser names a backend endpoint and the payload to send it:
-
-```ts
-await $fetch("/auth/establish", {
-  method: "POST",
-  body: {
-    endpoint: "/api/saas/register/finalize",
-    payload: { /* whatever that backend route expects */ },
-  },
-});
+pnpm exec ajs dms dev
 ```
 
-The frontend server calls that endpoint itself over its own server-to-server
-channel to `DMS_API_BASE_URL`, exactly as it calls `/api/auth/login`, and
-writes the session from the token pair the backend answers with. The browser
-never sends a token and never receives one: it gets back the same
-`{ user, account }` body the login route returns, and the two-factor and
-tenant-assignment outcomes are handled identically.
-
-Because the route turns a backend endpoint into a login, it only calls the
-endpoints that were declared for it.
-
-Backend modules declare their own. A module registering its frontend names the
-routes that finish its flow, the DMS aggregates them into the frontend manifest
-it serves with the bootstrap secret, and `dev`/`build` write them into the
-workspace as it is materialized:
-
-```ts
-// in the backend module
-await AddFrontendModule({
-  name: "@antelopejs/dms-saas-frontend-vue",
-  sourcePath: path.join(__dirname, "../frontend-vue"),
-  renderer: { name: "vue", version: "3" },
-  authEstablishEndpoints: ["/api/saas/register/finalize"],
-});
-```
-
-A standard deployment therefore needs no configuration at all. The environment
-variable stays as an override, for a backend route no module declares — or one
-declared by a DMS too old to carry the field:
+For production, build against the backend, then start the frontend server, with `DMS_SESSION_SECRET` and `DMS_BOOTSTRAP_SECRET` set:
 
 ```bash
-# .env
-DMS_AUTH_ESTABLISH_ENDPOINTS=/api/invites/redeem
+pnpm exec ajs dms build -b https://dms.example.com
+pnpm exec ajs dms start -b https://dms.example.com -p 3001
 ```
 
-The effective allow-list is the union of the two. Every entry, from either
-source, is matched verbatim against absolute `/api/…` paths — no prefixes, no
-query strings, no traversal — so no backend route that happens to mint a token
-pair can be turned into a login by a request from the browser. An undeclared
-endpoint is answered `403` and never called. The route is `POST`-only and
-same-origin, like every other auth action.
-
-### Routing and the backend proxy
-
-The frontend server answers each path with one owner, whoever asks and
-whatever the method, in this order:
-
-1. **The renderer**: its icon endpoint (`/api/_dms/icons`), Vite's URLs, the
-   built assets, and any file it has (a development source, a built asset).
-2. **The module routes** of the modules' `dms.server.ts`, for every method: a
-   method the module does not declare on its path answers `405`, and a `HEAD`
-   reaches the `GET` route.
-3. **The backend proxies** the modules declare. The renderer proxies no path on
-   its own: the DMS declares `/api/**` and `/dms/**` in its `dms.server.ts`.
-4. **The pages**, for everything else; a method other than `GET` and `HEAD`
-   there is a `404`. A backend route outside every declared prefix (such as a
-   page's `<page>/pagelayout`) is never reached from the browser.
+`ajs dms --help` lists every command, and `ajs dms help environment` every environment variable.
 
-A frontend module declares a prefix in its `dms.server.ts`:
-
-```ts
-server.registerBackendProxy("/api/**"); // auth: "session", the default
-server.registerBackendProxy("/media/**", { auth: "none" });
-```
-
-A backend module declares one in the manifest, next to its `publicEndpoints`:
-
-```ts
-await AddFrontendModule({
-  // …
-  backendProxies: [{ path: "/webhooks/acme/**", auth: "none" }],
-});
-```
+## Compatibility
 
-- `auth: "session"` adds the session's access token to the request
-  (`Authorization: Bearer`), server-side: the token never reaches the browser,
-  which only holds the sealed, `HttpOnly` session cookie. A request with a
-  state-changing method must carry the frontend's own `Origin`, except a
-  public endpoint (below).
-- `auth: "none"` never sends the session, so it needs no `Origin`: for media,
-  or a webhook that authenticates its caller itself.
+| `@antelopejs/dms` | `@antelopejs/dms-frontend` |
+| --- | --- |
+| 0.9.1 and later | `>=0.6.1 <0.7.0` |
+| 0.9.0 | `>=0.6.0 <0.7.0` |
+| 0.6.0 – 0.8.3 | 0.5 (exact floor per release in the full table) |
 
-A pattern is `/x`, `/x/*` (one segment below) or `/x/**` (the path and
-everything below), its first segment literal, outside the renderer's own paths.
-Of two patterns covering a path, the more specific wins; for one pattern, the
-highest-priority frontend module's, then the manifest's, with a warning.
-`DMS_BACKEND_PROXIES` adds entries of the manifest's shape, as a JSON array,
-for an operator. The server lists the backend proxies, their owner and their
-auth when it starts, and the development server names the owner of each answer
-in an `x-dms-route-owner` header (`renderer`, `module:<id>`,
-`backend:<pattern>`, `page` or `not-found`).
+The 0.6 line needs Node.js 20.12 or later and `@antelopejs/core` `>=1.13.2 <2`. The [compatibility table](https://dms.antelopejs.com/docs/frontend/introduction#compatibility) lists every release.
 
-### Public endpoints
+## Documentation
 
-Every state-changing request the server proxies with the session must carry
-an `Origin` matching the frontend's own, and goes out with the signed-in
-user's session. A route meant for callers outside the dashboard — a mail provider's
-delivery webhook, a payment provider's callback — fails both ways: the caller
-sends no `Origin`, and its secret header is not among the few the proxy
-relays.
+- [Introduction](https://dms.antelopejs.com/docs/frontend/introduction) and [Installation](https://dms.antelopejs.com/docs/frontend/installation)
+- [CLI reference](https://dms.antelopejs.com/docs/frontend/cli/overview)
+- [Configuration and environment variables](https://dms.antelopejs.com/docs/frontend/configuration)
+- [Writing a frontend module](https://dms.antelopejs.com/docs/frontend/frontend-modules/anatomy)
+- [Rendering model](https://dms.antelopejs.com/docs/frontend/rendering/model)
+- [Deploying to production](https://dms.antelopejs.com/docs/frontend/deployment/production)
+- [Troubleshooting](https://dms.antelopejs.com/docs/frontend/troubleshooting)
 
-A backend module declares such a route public when it registers its
-frontend:
+The guide's sources live in [`docs/`](./docs). The package also ships the `dms-frontend` skill for coding agents in [`skills/`](./skills), declared under `antelopeJs.skills`.
 
-```ts
-await AddFrontendModule({
-  name: "@antelopejs/dms-mailing-frontend-vue",
-  sourcePath: path.join(__dirname, "../frontend-vue"),
-  renderer: { name: "vue", version: "3" },
-  publicEndpoints: [
-    {
-      path: "/api/mailing/events/*/*",
-      methods: ["POST"],
-      headers: ["x-mailing-webhook-secret"],
-    },
-  ],
-});
-```
-
-A request to a public endpoint:
-
-- needs no `Origin`;
-- is never sent the session, even from a signed-in browser, so a cross-site
-  form posting to it acts as nobody: the route authenticates its caller
-  itself (a shared secret, a signature);
-- carries the module's declared headers on top of the usual ones.
-
-`path` is an absolute `/api/` path whose first segment is literal (the
-module's own prefix, never `*`) and whose later `*` segments match exactly one
-segment; nothing else matches (no prefix, no query string, no `.` or `..`
-segment). The proxy matches the request's normalized path, the one it sends
-the backend, so `..`, `%2e%2e` or `\` cannot reach another route through a
-public one. `methods` defaults
-to `["POST"]`. `headers` names the module's own `x-` headers; the ones a proxy
-or the DMS gives a meaning to (`x-forwarded-*`, `x-real-ip`, `x-dms-*`,
-`x-inertia*`, method overrides) are refused, as are `authorization` and
-`cookie`. A malformed declaration is dropped whole, with a warning, never
-widened. `DMS_PUBLIC_ENDPOINTS` adds entries of the same shape, as a JSON
-array, for a route no module declares.
-
-Every proxied request also relays `If-Match`, so a backend route can refuse a
-write made from a stale copy (`412` or `409`), and the client's `Origin` and
-`Referer` as received, so a public route can check where a beacon comes from.
-The proxy sets `X-Forwarded-For`, `X-Forwarded-Proto` and `X-Forwarded-Host`
-itself, so a route can limit each client: the client's own `X-Forwarded-For`
-is extended with the socket's address only behind `DMS_TRUSTED_PROXY_HOPS`
-trusted proxies, and replaced by it otherwise.
-
-### Workspaces
-
-Each canonical backend URL gets its own owner-only workspace under
-`~/.antelopejs/dms-frontend/<sha256>/`; `build`, `start`, `clean -b` and
-`dev -b` all key on that URL, so one backend means one workspace shared by
-every command.
-
-`dev` without `-b` is the deliberate exception. It discovers the backend from
-the enclosing antelope project's `.antelope/dev.json` and keys its workspace on
-the **project directory** instead, because a development backend can land on a
-different port between runs and re-keying on the URL would discard
-`node_modules`, the manifest cache and the client-side appId scope every time it
-does. The consequence is that `ajs dms dev` followed by `ajs dms build -b <url>`
-against the same backend creates two workspaces of their own — several hundred
-megabytes each. Pass `-b` to `dev` to share a single one. `workspaces` lists
-both, with the project a workspace is keyed on, its size and its last use;
-`clean -b <url>` only reaches the URL-keyed one. `clean` takes its target from
-`-b` or `--all` only: it never reads `DMS_API_BASE_URL` from the environment or
-`.env`, so running it without either is an error rather than a deletion.
-
-`workspaces` prints an aligned table on a terminal. Piped, it prints one
-tab-separated line per workspace, without a header: id, backend URL, key type
-(`url` or `project`), project directory, size in bytes, last use (ISO 8601) and
-workspace directory. `--json` prints one JSON document with the same fields;
-everything else the command says goes to stderr.
-
-`clean --all` lists what it removes and asks before removing it. Without a
-terminal to ask on (a pipe, CI), it exits 2 unless `--yes` is given. Both forms
-of `clean` say how much space they freed.
-
-A `DMS_API_BASE_URL` line in `.env` counts as an explicit backend, so a project
-that configures one gets the single shared workspace and gives up autodiscovery
-— including its tolerance for the backend moving to another port. Leave the
-variable out of `.env` to keep autodiscovery for `dev`.
-
-## Rendering model
-
-The Node server renders full-page requests through the Vite SSR bundle and sends
-the matching Inertia page object to the browser for hydration. Subsequent
-`X-Inertia` visits receive page objects and render client-side. Client-only
-plugins and `DmsClientOnly` defer browser-only work while the same generated
-frontend-module registry drives server and client entries.
-
-Under `ajs dms dev`, an edit to a module's `i18n/locales/*.json` regenerates the
-merged catalogs the application imports: the next server render uses them, and
-the open page applies them in place, without a reload. Adding or removing a
-locale reloads the page instead.
-
-An edit to a layer's `app/app.config.ts` reaches the page the same way (see
-[App config](#app-config-appappconfigts)).
-
-The other files the workspace derives from every module follow their sources
-the same way. A file added to, changed in or removed from a module's `public/`
-is served, or no longer served, at once. Public files and catalogs are written
-before the other files saved with them, so an app config or a component that
-names a new logo or a new translation, saved at the same time, never finds it
-missing. Adding or removing an `app/config/shortcuts-registry.ts` or a
-`dms.frontend.ts` regenerates the aggregated shortcuts or the module loader,
-and the page reloads. Adding, changing or removing a `dms.frontend.build.ts`
-restarts Vite. A layer directory added to or removed from `layers/` is the
-exception: Vite reads the `#<layer>` aliases and the auto-imported directories
-at startup only, so the dev server says it needs a restart.
-
-A page whose render declares no icon, through `useHead`, gets an empty
-`<link rel="icon" href="data:,">`, which keeps the browser from asking for
-`/favicon.ico`. A page that declares its icons, one per color scheme for
-instance, gets only those.
-
-### Navigation and the site layout
-
-Every visit's page object carries the page (`page`: its route and layout), the
-session (`user`, `session`) and the site layout (`shared`: the menu with each
-entry's access, quick actions, modules). The site layout is most of that
-object, and the same from page to page, so it is an Inertia once prop:
-
-- The server sends it when the browser does not hold it for the session's
-  account and workspace, then asks the backend for the page alone
-  (`/dms/page?path=…&shared=false`) while the browser's copy is less than five
-  minutes old. Signing in, signing out, or switching account or workspace
-  changes the key the copy is held under, so the next visit brings the new
-  session's layout.
-- `router.reload({ only: ["shared"] })` reloads it at once, and `only` /
-  `except` name any of `page`, `shared`, `user` and `session`: the server
-  fetches only what is named. The DMS reloads the menu this way when the
-  backend announces a change.
-- The access a menu entry shows is for display: the backend checks access on
-  every request, whatever the menu says.
-
-A navigation that changes only the query or the hash of the page on screen
-(`useDmsRouter().push({ query })`, `navigateDms`, `DmsLink`) is an Inertia
-client-side visit: the URL and the history entry change, the page stays
-mounted with its props, and no request is made, since the page props depend
-on the path alone. Pass a server-only option (`only`, `data`, `headers`,
-`onStart`…) to make the request anyway; an error page is always left through
-the server.
-
-`DmsLink` prefetches the page it points to on hover; once Inertia has the
-props, the page, its layout and its block components start loading, so
-following the link waits for neither. A change of account or workspace, and
-signing out, drop the prefetched pages.
-
-### Data loading
-
-`useDmsAsyncData(key, handler, options)` loads data once for every component
-that shows `key`, with the semantics of Nuxt 4's `useAsyncData` and the
-deviations listed below (calls of one key joined, the data of the last success
-kept after a failure, the first `lazy` run started after the caller's turn):
-
-- **A server render waits for it.** A component's data is awaited before the
-  component renders, whether or not its setup awaits the call, and the browser
-  takes the result over while it hydrates instead of fetching it again. Keys a
-  setup does not await load in parallel. Data a plugin starts is awaited
-  before the page renders.
-- **The result works with or without `await`.** Its refs are there at once;
-  awaiting it waits for the data.
-- **`lazy: true`** spares client navigations the wait; a server render still
-  waits.
-- **`server: false`** leaves the data to the browser: the server renders the
-  default, and the browser fetches the data once the page is mounted.
-- **The handler receives `{ signal }`.** It is aborted when a newer run
-  replaces this one (`dedupe: "cancel"`, the default; `"defer"` waits for the
-  run in flight instead), when `clear()` resets the data, or when the last
-  component showing the key unmounts.
-- **A page renders once its middleware is done.** On a server, the page that
-  calls `defineDmsPageMeta` waits for the middleware it starts, so what a
-  middleware loads or sets (with `transfer: true`) is what the HTML shows and
-  the browser hydrates with; its redirect still answers the request. A
-  middleware that throws fails the page: the error page shows in its place,
-  and a server render answers with the error's status code. Middlewares run
-  in order; those registered with `{ parallel: true }` next to each other
-  start together (for checks that read nothing another middleware sets),
-  their results applying in registration order.
-- **The browser hydrates with what the HTML shows.** Data that settles once
-  the HTML is complete is left to the browser. A component receives the server's data when the server's
-  render did: once its setup awaits the call, or right before it renders. A
-  value its setup derives from data it did not await, in an immediate
-  watcher for instance, is then the one the server rendered.
-- **A failure is transferred too,** so hydration does not run the handler
-  again: an HTTP failure keeps its `statusCode`, `statusMessage`, `message`
-  and `data`, any other failure becomes a `500` whose cause only the server
-  logs. A fetch error's message names the backend's address on a server, so
-  its status text replaces it.
-- **`useDmsState(key, init, { transfer: true })`** hands the server's value
-  to the browser, which then starts from it instead of calling `init`. State
-  is never transferred unless a key opts in, and must never hold a token or
-  a secret: the value is written into the page.
-- One `<script id="dms-payload" type="application/json">` carries the data,
-  the failures and the transferred state, in
-  [devalue](https://github.com/sveltejs/devalue)'s format, which keeps a
-  `Set`, a `Map` or a `Date`, escaped like Inertia's page object. A value it
-  cannot write, such as a class instance, is left out and logged.
-- **Stale while revalidate.** In the browser, data loaded before shows at
-  once, and is read again in the background on each mount of a component
-  showing it and on each return of a reactive key to it; awaiting the call
-  does not wait for that read. The first mount after a server render does not
-  read again: its data is the server's, just read. Of the data no component
-  shows any more, the browser keeps the 50 most recently shown across
-  navigations, so a return to a page shows its data at once.
-- **`error` stays until the next answer.** A run in flight keeps the last
-  failure; a success clears it, a failure replaces it, and a failed refresh
-  keeps the data of the last success on screen.
-- **`key`** is the key the data is loaded under (a reactive key's current
-  one). `transform(value, { key })` receives it, and `useDmsFetch`'s
-  `transform(value, { key, url })` the URL the response answers too, even when
-  a reactive URL changed since. While a reactive key shows the previous key's
-  data, `placeholder` is `true`.
-- **`data` is a shallow ref** (`deep: false`, as in Nuxt 4): replace the value
-  to update it, or pass `deep: true` to track changes inside it.
-- **`immediate: false`** waits for `execute()` (a dialog, a drawer), and
-  **`refreshInterval: ms`** reads again on an interval in the browser, while a
-  component shows the data and the page is visible: every read of a module can
-  go through `useDmsAsyncData` or `useDmsFetch`. The interval may be a ref or
-  a getter: the polling follows it, and `0`, `null` or `undefined` stops it.
-- **A call outside a component** (a plugin, also past its first `await`, a
-  callback) belongs to the application: its watchers and its polling run for
-  as long as the application does, so a plugin can poll a status with
-  `refreshInterval` and stop it through a reactive interval.
-- **`useDmsPagedData(key, handler, { nextCursor, initialCursor })`** reads a
-  list page by page under one key ("load more", an infinite list). The
-  handler receives `{ cursor, index, signal }` and returns a page;
-  `nextCursor(page, pages)` gives the next page's cursor, or `null` at the
-  end. The first page loads like any data (a server render waits for it and
-  transfers it); `loadMore()` appends the next one, `pages`, `hasMore` and
-  `loadingMore` follow it, and a failure lands in `error` with the pages
-  kept. A revalidation (a mount, `refresh()`, `refreshDmsPageData()`, the
-  polling) reads every page loaded so far again and replaces them once all
-  are in. Put what filters the list in the key: a new key starts again from
-  its first page.
-- **`refreshDmsPageData()`** reads again the data the components on screen
-  show, after a save or on a realtime event; a call opts out with
-  `refreshOnPageRefresh: false`, and data waiting for `execute()` is left
-  alone. `refreshDmsData(keys?)` reads given keys again.
-- **`setDmsAsyncDataScope(scope)`** puts the keys in a scope, such as a digest
-  of the account and the workspace: the same key in another scope is another
-  entry, and moving to another scope drops the data of every key. Set it on
-  both sides before the page renders, with the same value: the scope is
-  written in the page with each key.
-- **A call without a key** (`useDmsAsyncData(handler)`, or `useDmsFetch` with
-  a body it cannot key, such as a `FormData`) cannot be transferred: the
-  server leaves it to the browser, as `server: false` does, so the page
-  hydrates with what it shows. A development render warns about it, and about
-  a backend read made outside any handler on the server (an immediate
-  watcher, a setup's own `await $fetch`), which the browser makes again.
-- **`useDmsFetch(url, options)`** is `useDmsAsyncData` around a request,
-  keyed on its method, base URL, URL, query and body (not its headers): the
-  callers of one request share it, and a server render transfers it. The URL,
-  `method`, `query`, `params` and `body` may each be a ref or a getter, read
-  again for each request: the caller moves to the key of each request, as in
-  Nuxt's `useFetch`. A URL that is `null` or `undefined` requests nothing
-  until it has a value, on the server as in the browser. `key` names a key
-  instead (a ref or a getter too: `null` requests nothing), and `$fetch`
-  replaces the fetch function, which receives the signal.
-- **`dmsRequestKey(url, { method, baseURL, query, params, body })`** is the
-  key `useDmsFetch` gives a request, without the scope: for
-  `refreshDmsData(keys)`, and for a test that looks for a response's entry
-  instead of computing the digest itself.
-- **A key that is `null` or `undefined`** (a ref or a getter for it) has
-  nothing to load: the caller holds its default, and runs nothing until the
-  key has a value.
-- **A new key is read where the first one would have been.** On a server,
-  `server: false` and `immediate: false` read nothing, whatever key the
-  render gives them. Another read follows a key its setup sets: the
-  component's render waits for it and transfers it, `lazy` or not. A key that
-  changes once that wait has started (the answer of another read of the
-  same component, a later component) is not read on the server: the HTML
-  shows the default, and the browser reads it once the component is mounted.
-  To render a read that depends on another one's answer, await the first one
-  in the setup.
-- **`useDmsData(key)`** gives the `data` another caller loads under `key`,
-  as Nuxt's `useNuxtData`: assigning it, or changing it in place (unless the
-  key is `deep: false`), updates every component showing the key without
-  reading it again. It is how a write's answer (an optimistic update, put
-  back if the write fails) or a realtime event patches data, including the
-  data of a key the component does not show. `data` is `undefined` until a
-  caller loads the key, while a reactive key still shows the previous key's
-  data, and once the browser lets the key go (past the 50 most recent keys
-  it keeps) or the account or workspace changes; a write to a key
-  nobody loaded is ignored. The key may be a ref or a getter, and a key
-  loaded by `useDmsFetch` is the `key` option it was given. It loads
-  nothing and keeps nothing alive: a component showing the data calls
-  `useDmsAsyncData` with the key. A run in flight still writes its answer
-  over an update, so a writer refreshes the key once the write is done.
-  In a server render, a component called after the caller's call waits for
-  its data, so it renders what the browser hydrates it with.
-
-### Icons
-
-The browser never asks a third party for an icon, so a Content-Security-Policy
-needs no exception for the Iconify API. Icons reach the page two ways:
-
-- **Bundled.** Nuxt UI's client bundle holds every icon its scanner finds in
-  the workspace's Vue, Markdown and YAML files, the TypeScript of each layer's
-  `app/` directory — `app.config.ts` and its `ui.icons` mappings included — and
-  Nuxt UI's own defaults.
-- **Served.** Any other icon, such as a page icon a backend module declares,
-  is fetched from the frontend server itself: `main.ts` points `@iconify/vue`
-  at `GET /api/_dms/icons/<prefix>.json?icons=<name>,…`, which answers in the
-  Iconify API format from the collections installed in the workspace
-  (`@iconify-json/<prefix>`, or `@iconify/json`). The workspace ships
-  `@iconify-json/lucide` and `@iconify-json/ph`; a module using another
-  collection depends on its `@iconify-json/*` package. An unknown collection
-  answers `404`, and a name outside Iconify's naming rule `400`. `ajs dms dev`
-  and `ajs dms start` run the same server, so both serve the route.
-
-The server render draws every icon, bundled or not: the frontend server loads
-each installed `@iconify-json/*` collection once and hands it to the renderer,
-and an icon is drawn in its first render as soon as its data is loaded, instead
-of after the component mounts. The data of each icon a render drew travels in
-the page, so the browser draws the same icons as it hydrates; an icon no
-installed collection holds stays empty on the server and is fetched in the
-browser as before.
-
-Each icon is drawn once per page: a hidden `<svg id="dms-icon-sprite">` holds
-one `<symbol>` per icon (and per flip or rotation), and every occurrence is an
-`<svg>` with a `<use>` of it, so an icon on each row of a table is sent once.
-The browser draws the same way, adding the symbols of the icons it draws later
-to the same sprite.
-
-## Options
-
-| Option | Environment | Purpose |
-| --- | --- | --- |
-| `-b, --backend-url` | `DMS_API_BASE_URL` (except `clean`) | DMS backend URL, `http://` or `https://` |
-| `-p, --port` | `PORT` | Frontend port from 1 to 65535, default `3001`; `dev` moves to the next free port, `start` stops when it is in use |
-| `-f, --force` | | Reinstall workspace dependencies; `build` also extracts the layers archive from scratch |
-| `--offline` | `DMS_OFFLINE` | Reuse cached manifest and archives; the only way `build` uses them |
-| `--strict` | `DMS_PREPARE_STRICT` | Make `prepare` fail instead of warning; see [Commands](#commands) |
-| `--bootstrap-secret` | `DMS_BOOTSTRAP_SECRET` | Backend bootstrap credential |
-| | `HOST` | Address the frontend server binds to: `127.0.0.1` by default for `ajs dms dev`, so only this machine reaches the development server (set `HOST=0.0.0.0` to open it to the network); `0.0.0.0` for `ajs dms start` |
-| | `DMS_COOKIE_SECURE` | Secure cookies (`true` by default; `ajs dms dev` defaults to `false`) |
-| | `DMS_TRUSTED_PROXY_HOPS` | Number of trusted, rightmost reverse-proxy hops (default `0`) |
-| | `DMS_COUNTRY_HEADER` | Client country header the server relays to the backend, set by a trusted reverse proxy (default `CF-IPCountry`; empty relays none). Name the same header in the backend's `auth.signInCountry.header`. Relayed only when `DMS_TRUSTED_PROXY_HOPS` is above `0`, like the client address |
-| | `DMS_SESSION_SECRET` | Session cookie encryption key, 32 characters or more (required for login) |
-| | `DMS_HTML_RENDER_SECRET` | Secret that verifies the backend's signed HTML/email render requests; without it, e-mail renders are refused. The `htmlRender.serviceSecret` the backend publishes in the frontend manifest wins; the variable is the fallback for a manifest without one |
-| | `DMS_OAUTH_RELAY_SECRET` | Secret the server presents to the backend's OAuth endpoints; without it, the backend refuses OAuth sign-in. The `oauth.relaySecret` the backend publishes in the frontend manifest wins; the variable is the fallback for a manifest without one |
-| | `DMS_AUTH_ESTABLISH_ENDPOINTS` | Extra backend endpoints `/auth/establish` may open a session from, on top of those the backend's modules declare (comma-separated, empty by default) |
-| | `DMS_BACKEND_PROXIES` | Extra backend prefixes the server proxies, on top of those the modules declare: a JSON array of `{ path, auth? }` (see [Routing and the backend proxy](#routing-and-the-backend-proxy)) |
-| | `DMS_PUBLIC_ENDPOINTS` | Extra backend routes the proxy serves to anyone, on top of those the backend's modules declare: a JSON array of `{ path, methods?, headers? }` (see [Public endpoints](#public-endpoints)) |
-| | `DMS_CLIENT_BASE_URL` | Public frontend URL used in generated links and emails |
-
-All of these can be set in the project's `.env` instead of the environment; see [Configuration](#configuration).
-
-`ajs dms dev` takes the two manifest secrets from the manifest it fetches, and `ajs dms start` from the manifest cached by `ajs dms build`. An explicitly set variable always wins over the manifest value. Before the server starts, both commands warn about each secret that is not set and what stops working without it; once the server is ready, they list where the others come from (the environment, the manifest or the build-time manifest), never their values. When several modules publish the same secret, the first one in manifest-priority order wins, and a module publishing a different value is named in a warning.
-
-Use pnpm for all repository and workspace operations.
-
-## Verify local frontend modules
-
-Use the packaged source verifier to validate unpublished DMS frontend modules against this exact adapter version. Run it from the project:
-
-```bash
-ajs dms verify-source
-```
-
-The modules are verified on top of the DMS core layer, the `frontend-vue` directory of `@antelopejs/dms`. The verifier finds the `@antelopejs/dms` the project installs the way Node does, from the current directory, and names it before it starts: `Verifying against @antelopejs/dms 0.5.5 (installed in this project)`. When the project does not install it, the verifier stops with the command that adds it as a development dependency (`pnpm add -D @antelopejs/dms`, or the equivalent for the project's package manager).
-
-Without `--module`, the verifier takes the current directory when it is a frontend module (it contains `dms.frontend.ts`), and its `frontend-vue` directory otherwise. `--module` names other ones and is repeatable, as is `--local-package`, which binds a local build of a package into the generated workspace. All supplied frontend packages are copied into the generated workspace and bound with `workspace:*`.
-
-```bash
-ajs dms verify-source --module ./admin-vue --module ./shop-vue
-```
+## Contributing
 
-`--layer` is for the DMS core layer's own development: it verifies an unpublished core layer instead of the installed one, here against a local build of `@antelopejs/dms`:
+Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a pull request.
 
 ```bash
-ajs dms verify-source \
-  --layer /path/to/dms/frontend-vue \
-  --local-package @antelopejs/dms=/path/to/dms
+pnpm install
+pnpm build
+pnpm lint          # oxlint, oxfmt, interface ranges and the docs reference check
+pnpm typecheck
+pnpm test
 ```
 
-The checks look for what the core layer ships: its lazily loaded chart and rich-text libraries, the pages every DMS serves and its e-mail templates. A `--layer` that holds no core layer, such as a project's own `frontend-vue`, is refused before anything is installed, with exit code 2 and the command that verifies the same folder with `--module` instead.
+`pnpm docs:reference` regenerates the environment-variable table of `docs/4.configuration.md` from the list `ajs dms help environment` prints; `pnpm lint` fails when the table is stale.
 
-A supplied package whose declared range excludes this adapter version is refused before anything is installed (see [Declaring the loader releases a module supports](#declaring-the-loader-releases-a-module-supports)). The verifier generates a temporary workspace, installs it, builds the client, SSR and email bundles while `vue-tsc` runs alongside them (it does not compress the client assets, which only a served build needs), checks what the client bundle loads, renders eight DMS email templates, and checks that the email bundle excludes browser-only modules. Each check is one line that ends in ✔ or ✖, and the run ends with `Verified <n> modules` and its duration, or with the first failure: a type or Vite error points at the file in the package you passed (`./frontend-vue/app/components/Callout.vue:17:7`), not at its copy in the workspace, and the command exits 1. `--verbose` streams the pnpm, Vite and `vue-tsc` output. The workspace is removed when the run ends. It does not start a backend or publish packages. Repository development can invoke the same runner through `pnpm test:real-source`, with `DMS_LAYER_SOURCE` set to a core layer root and `DMS_MODULE_SOURCES` to a JSON array of module roots.
+## License
 
-Refresh rotation is single-flight within one frontend process. Horizontally scaled deployments must use sticky routing so a browser reaches the same process, or replace this process-local behavior with an external session adapter. It does not provide a distributed rotation guarantee.
+[Apache-2.0](./LICENSE)