diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
index 09344fc..fab7aa3 100644
--- a/.github/workflows/check.yml
+++ b/.github/workflows/check.yml
@@ -29,13 +29,19 @@ jobs:
     steps:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
-      # The documented target. verify-refs checks every path, class, sample id
-      # and `require("abap2UI5/…")` on this site against a real checkout, so
-      # without it the run proves only that the site builds — it skips itself
-      # and exits 0 when the checkout is missing, which is exactly the silent
-      # pass this job exists to prevent. Hence `check:ci` below, which passes
-      # --require-checkout: if this step is ever removed, renamed or fails to
-      # land the tree, the job goes red instead of quietly checking nothing.
+      # The documented targets. verify-refs checks every path, class, app id,
+      # plugin option and `require("cap2ui5")` on this site against real
+      # checkouts, so without them the run proves only that the site builds —
+      # it skips those checks when a checkout is missing, which is exactly the
+      # silent pass this job exists to prevent. Hence `check:ci` below, which
+      # passes --require-checkout: if a step is ever removed, renamed or fails
+      # to land the tree, the job goes red instead of quietly checking nothing.
+      #
+      # TWO checkouts since cap2UI5 became a plugin: cap2UI5 answers for repo
+      # paths, app ids, the plugin's exports and the pinned runtime release,
+      # while the FRAMEWORK CLASSES the docs name live in abap2UI5's ABAP —
+      # the runtime package is transpiled from it and is assembled rather than
+      # committed, so a fresh cap2UI5 checkout has none of those names.
       - name: Check out cap2UI5 (reference target)
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
@@ -44,6 +50,14 @@ jobs:
           path: .cap2ui5-ref
           fetch-depth: 1
 
+      - name: Check out abap2UI5 (the framework the runtime is built from)
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          repository: abap2UI5/abap2UI5
+          ref: main
+          path: .abap2ui5-ref
+          fetch-depth: 1
+
       - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: '22'
@@ -53,8 +67,9 @@ jobs:
       # verify-refs + vitepress build, in that order: a dead reference is
       # reported even when the site would have built fine around it. Same two
       # steps as the `npm run check` AGENTS.md tells a contributor to run —
-      # the :ci variant only refuses to skip the reference check.
+      # the :ci variant only refuses to skip the reference checks.
       - name: npm run check:ci
         run: npm run check:ci
         env:
           CAP2UI5_DIR: .cap2ui5-ref
+          ABAP2UI5_DIR: .abap2ui5-ref
diff --git a/AGENTS.md b/AGENTS.md
index e87c12e..b0d2bfe 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -12,74 +12,84 @@ Before committing, run `npm run check` — that is `verify-refs` followed by the
 VitePress build. It is also what CI runs, on every pull request
 (`.github/workflows/check.yml`) and on deploy. verify-refs checks that
 
-- every path, class and `?app_start=` named in the prose resolves in a real
-  cap2UI5 checkout,
-- every `require("abap2UI5/…")` **inside a code fence** resolves through the
-  exports map of `core/package.json` and onto a file that exists,
+- every path named in the prose exists in a cap2UI5 checkout,
+- every `?app_start=` names an app something registers with `defineApp`,
+- every `z2ui5_*` class or interface exists in the abap2UI5 source the hosted
+  runtime is transpiled from,
+- every `require("cap2ui5")` **inside a code fence** destructures names the
+  package really exports (and the port's `require("abap2UI5/…")` is reported),
+- every `cds.cap2ui5.<option>` is an option the plugin defines,
+- every `1.x.y` release number is the pinned runtime release,
 - every internal anchor exists.
 
-The verifier needs a checkout: `CAP2UI5_DIR=/path/to/cap2UI5`, or a sibling
-clone. It skips itself when there is none, so a green run without a checkout
-proves only that the site builds. That leniency is right on a laptop and wrong
-in CI, which does check cap2UI5 out — so CI runs `npm run check:ci`, the same
-two steps with `verify-refs --require-checkout`, and a missing checkout is a
-failure there rather than a silent pass.
+The verifier needs **two** checkouts: `CAP2UI5_DIR=/path/to/cap2UI5` and
+`ABAP2UI5_DIR=/path/to/abap2UI5`, or sibling clones. It skips the checks a
+missing checkout would need, so a green run without them proves only that the
+site builds. That leniency is right on a laptop and wrong in CI, which checks
+both out — so CI runs `npm run check:ci`, the same two steps with
+`verify-refs --require-checkout`, and a missing checkout is a failure there
+rather than a silent pass.
 
-## Generated pages
-
-`docs/guide/samples.md` is **generated** — do not edit it by hand. It comes
-from `scripts/gen-samples.mjs`, which reads the sample gallery's own catalogue
-table out of `z2ui5_cl_smp_app_000` in a cap2UI5 checkout:
-
-```
-CAP2UI5_DIR=/path/to/cap2UI5 npm run gen:samples    # rewrite the page
-node scripts/gen-samples.mjs --check                # fail if it is out of date
-```
-
-The result is committed like any other page, so the docs build without a
-checkout and a reviewer sees the diff a sync causes. Regenerate it when the
-sample set changes.
+Why two: cap2UI5 is a plugin, and the framework classes the docs name are not
+in it. They are abap2UI5's ABAP, transpiled into `@abap2ui5/runtime`, whose
+content is assembled by `scripts/assemble-runtime.sh` and gitignored — a fresh
+cap2UI5 checkout has none of those names. Resolving classes against an
+assembled runtime would pass on a laptop and check nothing in CI.
 
 Exceptions — placeholder class names, paths in other repos — go in
 `docs/.verify-refs-ignore`, **with a reason**. An unexplained entry there is
 indistinguishable from suppressing a real defect.
 
-## Ground truth — the cap2UI5 repo layout (since the monorepo split, 2026-07)
+## Generated pages
+
+None. `docs/guide/samples.md` and `scripts/gen-samples.mjs` were deleted with
+the plugin cutover: the sample catalogue they mirrored belongs to abap2UI5's
+sample repository, not to this site.
+
+## Ground truth — the cap2UI5 repo layout (since the plugin cutover, 2026-09)
 
 When documenting paths or linking sources, these are the facts (verify
 against the repos, don't guess):
 
 | Repo | Role |
 |---|---|
-| [cap2UI5/cap2UI5](https://github.com/cap2UI5/cap2UI5) | the deployable CAP app at the repo root — **generated** by builder-cap2UI5; framework vendored at `core/` (npm package `abap2UI5`, dep `"file:./core"`) |
-| [cap2UI5/builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js) | ABAP→JS transpiler + sync pipelines (update_samples/update_backend/update_frontend); generates the core package |
-| [cap2UI5/builder-cap2UI5](https://github.com/cap2UI5/builder-cap2UI5) | assembles the app from its `src/` + the mirrored core; `update_cap` publishes into the app repo |
-| [cap2UI5/builder-cap2UI5-web](https://github.com/cap2UI5/builder-cap2UI5-web) | browser-build tooling (formerly `web-cap2UI5`) |
-| [cap2UI5/web-cap2UI5-build](https://github.com/cap2UI5/web-cap2UI5-build) | the built static site; GitHub Pages: https://cap2ui5.github.io/web-cap2UI5-build/ |
-
-Path conventions inside the app repo:
-
-- framework classes: `core/srv/z2ui5/` — exactly three layers: `00/` utils,
-  `01/` core plumbing (including the shipped apps in `01/04/` since the
-  2026-08 upstream rename) and `02/` public API. There is no `99/`: upstream's
-  frozen legacy package is deliberately not carried into the port, so
-  `z2ui5_cl_xml_view`, `z2ui5_cl_xml_view_cc` and the `z2ui5_cl_pop_*` popups
-  do not exist here. The one view builder is `z2ui5_cl_ui5_view_builder`.
-- the vendored release is pinned: `z2ui5_if_app.version` says which one
-  (1.142.0 today). On it `_bind` is one-way and `_bind_edit` two-way —
-  upstream merged the two in 1.143.0, so upstream material can disagree with
-  what this core does.
-- bundled demo samples (pipeline-owned, flat): `core/srv/app/samples/`
-- user apps: `srv/app/` (or any folder via `Z2UI5_APP_DIRS` /
-  `require("abap2UI5/register-apps")(dir)`)
-- webapp: `app/z2ui5/webapp/`; service: `srv/z2ui5-service.cds/.js`;
-  server wiring: `srv/server.js`; draft table: `db/schema.cds`
-  (`cap2ui5.z2ui5_t_01`)
+| [cap2UI5/cap2UI5](https://github.com/cap2UI5/cap2UI5) | the npm package `cap2ui5`: a CAP plugin that hosts upstream's transpiled runtime |
+| [abap2UI5/abap2UI5](https://github.com/abap2UI5/abap2UI5) | the framework itself, in ABAP. Downported and transpiled, it is published as `@abap2ui5/runtime` |
+| [cap2UI5/builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js) | the ABAP→JS transpiler pipelines |
+
+The three builder repos that generated the old CAP application
+(`builder-cap2UI5`, `builder-cap2UI5-web`, `web-cap2UI5-build`) are archived.
+There is no generated app, no vendored `core/`, no mirrored `app/z2ui5/webapp`.
+
+Path conventions inside cap2UI5:
+
+- `plugin/` — the package: `cds-plugin.js` (the route, the static shell, the
+  auth guard), `index.cds` (the `cap2ui5.Drafts` entity), `index.js` (what
+  `require("cap2ui5")` returns) and `lib/` (`define-app.js`, `define-exit.js`,
+  `draft-store.js`, `runtime.js`)
+- `examples/bookshop/` — a CAP project using it, with the test suite. Its apps
+  are in `examples/bookshop/srv/apps/`
+- `runtime/` — `@abap2ui5/runtime`. Only `package.json` and `README.md` are
+  committed; `output/`, `setup/` and `webapp/` are **assembled** and gitignored
+- `docs/adr/` — the decisions, ADR-008 being the cutover
+
+What a READER's project looks like is a different thing and must not be
+confused with the above: they install `cap2ui5`, write apps in `srv/apps/`
+(configurable via `cds.cap2ui5.apps`), and get the route, the UI5 shell and
+the draft entity from the plugin. `srv/`, `db/` and `app/` in the prose are
+therefore **their** paths, which is why verify-refs does not check them
+against the cap2UI5 repository.
 
 ## Rules
 
-- Recommend `srv/app/` (never the samples folder) as the place for user
-  apps — pipeline-owned folders are overwritten on every sync/publish.
-- Deep links must use the new repo roots (no `cap2UI5/cap2UI5/…/cap2UI5/…`
-  monorepo-subfolder links); verify every linked path exists.
-- Run `npx vitepress build docs` before committing — it catches dead links.
+- Recommend `srv/apps/` as the place for apps — it is the plugin's default.
+- The framework's own classes are **not importable**. An app requires
+  `cap2ui5` and nothing else; `c.raw` is the escape hatch to the transpiled
+  `z2ui5_if_client`.
+- Measure before documenting a framework behaviour. The runtime is upstream's
+  ABAP running on open-abap, and not everything upstream does works here —
+  the user exit is discovered by a class-repository lookup in ABAP and had to
+  be given a host-side registration (`defineExit`) instead. Boot the runtime
+  and check rather than porting a claim from abap2UI5's documentation.
+- Run `npm run check` before committing — verify-refs catches stale
+  references, the VitePress build catches dead links.
diff --git a/docs/.verify-refs-ignore b/docs/.verify-refs-ignore
index 3a61d4d..5e51dba 100644
--- a/docs/.verify-refs-ignore
+++ b/docs/.verify-refs-ignore
@@ -8,7 +8,7 @@
 # Format: <token> # <reason>
 
 # --- paths in OTHER repositories -------------------------------------------
-app/webapp              # the upstream abap2UI5 repo's frontend folder, which cap2UI5 mirrors
+app/webapp              # the upstream abap2UI5 repo's frontend folder, which @abap2ui5/runtime ships
 
 # --- illustrative paths the READER creates ---------------------------------
 srv/app/View1.view.xml  # a static view file the getting-started example tells you to add
@@ -19,19 +19,19 @@ z2ui5_cl_app_xyz        # stands for "your app class" in the interface descripti
 my_first_app            # the class the getting-started walkthrough has you write
 my_app                  # same, in the why-cap2ui5 pitch
 my_app_name             # stands for "your class" in the ?app_start= URL on the navigation page
+zcl_my_app              # stands for "the name you gave defineApp" in the why-cap2UI5 pitch
 ClassName               # literal placeholder in the URL-parameter description
 
-# --- classes that exist UPSTREAM and deliberately not here -----------------
-# cap2UI5 does not carry abap2UI5's frozen src/99 (see guide/vs-abap2ui5). The
-# names are named there precisely to say they are absent, so the checker must
-# not read the mention as a claim that they exist.
-z2ui5_cl_xml_view       # upstream's retired view builder — replaced here by z2ui5_cl_ui5_view_builder
-z2ui5_cl_xml_view_cc    # its custom-control decorator, retired with it
-z2ui5_cl_pop_bal        # one of upstream's frozen built-in popups, superseded by the popups add-on
+# Upstream's frozen src/99 needs no entries any more: the plugin hosts
+# upstream's whole transpiled runtime, so z2ui5_cl_xml_view and its siblings
+# ARE in it (measured in the assembled output) and resolve like any other
+# class. They are still not what to write new code against — see
+# guide/vs-abap2ui5 — but "do not use this" is a recommendation, and this file
+# is only about what exists.
 
-# --- release numbers that are NOT the pinned framework release --------------
-# The pin itself (1.142.0 today) is read from the checkout and never listed
+# --- release numbers that are NOT the pinned runtime release ----------------
+# The pin itself (1.144.0 today) is read from the checkout and never listed
 # here — listing it would keep the old number green after a pin move, which
 # is the one defect the release check exists to catch.
 1.143.0                 # the upstream release where _bind/_bind_edit merged — history, stays true whatever the pin says
-1.113.0                 # the OpenUI5 release served locally — a UI5 number, not a framework release
+1.113.0                 # an OpenUI5 release — a UI5 number, not a framework release
diff --git a/docs/.vitepress/config.mjs b/docs/.vitepress/config.mjs
index 3f01cbd..a99fb27 100644
--- a/docs/.vitepress/config.mjs
+++ b/docs/.vitepress/config.mjs
@@ -62,12 +62,10 @@ export default defineConfig({
       { text: 'Examples', link: '/examples/hello-world' },
       { text: 'API', link: '/api/client' },
       { text: 'Reference', link: '/reference/architecture' },
-      { text: 'Playground', link: 'https://cap2ui5.github.io/web-cap2UI5-build/' },
       {
         text: 'Links',
         items: [
           { text: 'GitHub (cap2UI5)',     link: 'https://github.com/cap2UI5/cap2UI5' },
-          { text: 'GitHub (builder-cap2UI5-web)', link: 'https://github.com/cap2UI5/builder-cap2UI5-web' },
           { text: 'GitHub (docs)',        link: 'https://github.com/cap2UI5/docs' },
           { text: 'abap2UI5',             link: 'https://github.com/abap2UI5/abap2UI5' }
         ]
@@ -81,17 +79,15 @@ export default defineConfig({
           items: [
             { text: 'What is cap2UI5?',            link: '/guide/what-is-cap2ui5' },
             { text: 'Why cap2UI5?',                link: '/guide/why-cap2ui5' },
-            { text: 'Try It in the Browser',       link: '/guide/playground' },
             { text: 'Quickstart',                  link: '/guide/getting-started' },
-            { text: 'Project Structure',           link: '/guide/project-structure' },
-            { text: 'Sample Catalogue',            link: '/guide/samples' }
+            { text: 'Project Structure',           link: '/guide/project-structure' }
           ]
         },
         {
           text: 'Concepts',
           items: [
             { text: 'App Lifecycle',        link: '/guide/lifecycle' },
-            { text: 'View Builder',         link: '/guide/views' },
+            { text: 'Views',                link: '/guide/views' },
             { text: 'Data Binding',         link: '/guide/data-binding' },
             { text: 'Events',               link: '/guide/events' },
             { text: 'Navigation',           link: '/guide/navigation' },
@@ -142,8 +138,7 @@ export default defineConfig({
         {
           text: 'API Reference',
           items: [
-            { text: 'client',               link: '/api/client' },
-            { text: 'View Builder',         link: '/api/view-builder' },
+            { text: 'c — the client facade', link: '/api/client' },
             { text: 'App Interface',        link: '/api/app-interface' }
           ]
         }
diff --git a/docs/api/app-interface.md b/docs/api/app-interface.md
index f98dd85..c3e62e8 100644
--- a/docs/api/app-interface.md
+++ b/docs/api/app-interface.md
@@ -1,98 +1,106 @@
-# API: App Interface
-
-Every cap2UI5 app must extend `z2ui5_if_app`. Source: [`core/srv/z2ui5/02/z2ui5_if_app.js`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/z2ui5/02/z2ui5_if_app.js).
-
-## Definition
+# API: `defineApp` and `t`
 
 ```js
-const z2ui5_if_app = require("abap2UI5/z2ui5_if_app");
-
-class my_app extends z2ui5_if_app {
-  async main(client) {
-    // ...
-  }
-}
+const { defineApp, defineExit, t } = require("cap2ui5");
 ```
 
-## Mandatory method
-
-### `async main(client)`
+`defineApp` registers a class as an app; `t` declares the field types that
+cannot be inferred from a literal; `defineExit` registers the one user exit —
+it has [a page of its own](../guide/user-exit).
 
-Called on **every roundtrip**. Receives the `client` object as the only argument. Must be `async` (or return a promise).
+## `defineApp(name, class, opts?)`
 
 ```js
-async main(client) {
-  if (client.check_on_init()) { /* ... */ }
-  if (client.check_on_event(...)) { /* ... */ }
-}
+defineApp("ZCL_HELLO", class {
+  name = "";
+
+  main(c) { /* … */ }
+});
 ```
 
-## Reserved fields (framework)
+| | |
+|---|---|
+| `name` | the app's name **on the wire** — what `?app_start=` takes and `c.navTo()` resolves. Uppercased. The file name is irrelevant |
+| `class` | a plain class with a `main(c)` method and its state as fields |
+| `opts.interfaces` | rarely needed; defaults to `["Z2UI5_IF_APP", "IF_SERIALIZABLE_OBJECT"]` |
 
-These properties are predefined on the base class. **Don't override** them and don't use them as your own app state:
+It returns the wrapped class and registers it, so `defineApp` may be called
+more than once per file.
 
-| Property | Type | Meaning |
-|---|---|---|
-| `id_draft` | `string` | Draft ID, managed internally |
-| `id_app` | `string` | App ID, managed internally |
-| `check_initialized` | `boolean` | Set to `true` after the first `main()` — controls `check_on_init()` |
-| `check_sticky` | `boolean` | If `true`, sticky session active |
+Without a `main`, it throws:
+
+```
+defineApp(ZCL_HELLO): the class needs a main( client ) method
+```
 
-The binding engine explicitly excludes these fields from the reference lookup (`_FRAMEWORK_FIELDS` in `z2ui5_cl_ui5_client.js`).
+### `main(c)` is synchronous
 
-## Static constants
+No `async`, no `await` for anything the framework offers. Make it `async` only
+when **your app** does I/O:
 
 ```js
-z2ui5_if_app.version    // "1.142.0"
-z2ui5_if_app.origin     // "https://github.com/abap2UI5/abap2UI5"
-z2ui5_if_app.authors    // link to contributors page
-z2ui5_if_app.license    // "MIT"
+async main(c) {
+  this.books = await SELECT.from(cds.entities("my.bookshop").Books);
+}
 ```
 
-## Validation
+The wrapper awaits it either way.
 
-On the first roundtrip, `z2ui5_cl_ui5_app_cont.validate(oApp)` is called — if your class does not extend `z2ui5_if_app`, it throws:
+### State is the fields
 
-```
-my_app must extend z2ui5_if_app (INTERFACES z2ui5_if_app)
-```
+Every field with an initial value becomes part of the model and survives the
+roundtrip. A field the plugin cannot type is left out and **named in a
+warning**, never silently dropped.
 
-## Persistence annotations
+## `t` — the type declarations
 
-There are currently **no annotations** to exclude fields from persistence. If you need transient fields, declare them as **local variables in `main()`** instead of as app properties. The only hard-coded skip list is `["client"]` in `z2ui5_cl_ui5_srv_draft.js`.
+A field's type comes from its initial value where that is unambiguous. Where it
+is not, declare it:
 
-Suggestion if you need this — patch `SKIP_PROPS`:
+| | |
+|---|---|
+| `t.string()` | `string` — same as `""` |
+| `t.int()` | integer — same as `0` |
+| `t.float()` | float — same as `1.5` |
+| `t.bool()` | `abap_bool`; the app sees `true`/`false` — same as `false` |
+| `t.char(len)` | fixed-width character |
+| `t.packed(len, dec)` | **packed decimal.** Use this for money |
+| `t.struct({…})` | a structure. A plain object literal is one implicitly |
+| `t.table(row)` | a table; the argument is one **row** |
 
 ```js
-// core/srv/z2ui5/01/01/z2ui5_cl_ui5_srv_draft.js
-static SKIP_PROPS = new Set(["client", "_my_transient_field"]);
+price = t.packed(9, 2);
+books = t.table({ ID: 0, title: "", price: t.packed(9, 2) });
+addr  = { street: "", zip: 0 };            // t.struct is implicit here
 ```
 
-(Keeping in mind that your patch may be lost on the next sync.)
+Numbers are the ambiguity worth knowing: ABAP has `I`, `P` and `F` and they
+render with different decimals, so an integer literal becomes `I`, a fractional
+one `F`, and a decimal amount has to say so with `t.packed()`. Guessing would
+produce a view with the wrong number of decimals and nothing to point at.
 
-## Constructor
+Structures and tables nest, to a depth of 8 — a cycle guard rather than a
+judgement. See [Data Binding](../guide/data-binding).
 
-The base class has a constructor that **forbids direct instantiation**:
+## `defineExit(exit)`
 
-```js
-new z2ui5_if_app();   // ❌ throws
-```
-
-It also checks that your subclass implements `main` as a function:
+The framework's configuration hook — the CSP, the security headers, the UI5
+bootstrap URL, the theme, the draft expiry, the CSRF gate. One per project,
+registered from a file in the apps directory:
 
 ```js
-class broken extends z2ui5_if_app { /* main() missing */ }
-new broken();  // ❌ "broken must implement async main(client)"
+defineExit({
+  onPage(cfg, ctx) { /* the bootstrap page */ },
+  onRoundtrip(cfg, ctx) { /* every roundtrip */ },
+});
 ```
 
-## Lifecycle
-
-→ see [App Lifecycle](../guide/lifecycle).
-
-## Convention: naming
+Both hooks are optional, `cfg` arrives with the framework's defaults, and only
+what you change is written back. The fields, the defaults and why the exit is
+registered rather than discovered: [The User Exit](../guide/user-exit).
 
-abap2UI5 convention is `z2ui5_cl_app_xyz`. cap2UI5 sticks to that for library apps (Startup, Hello World, Pop helpers), but **your own apps** can be named however you like. Important:
+## Next
 
-- **Class name === file name** (otherwise the class lookup won't find the class on reload).
-- The file must live in one of the lookup paths: the framework folders (`core/srv/z2ui5/01/04/`, `core/srv/z2ui5/02/`), the core package's app folder (`core/srv/app/`, incl. the bundled `samples/`), a directory registered via `z2ui5_cl_util.register_app_dir(...)` / `require("abap2UI5/register-apps")(dir)` — like the project's own `srv/app/` — or a path listed in `Z2UI5_APP_DIRS` — see [Persistence](../guide/persistence#class-restoration).
-- Class names should be **case-sensitive unique** — the lookup forces lowercase, so `MyApp` and `myapp` collide.
+- [**`c` — the client facade**](./client) — what `main` receives
+- [**Data Binding**](../guide/data-binding) — the types in practice
+- [**The User Exit**](../guide/user-exit) — `defineExit` in full
diff --git a/docs/api/client.md b/docs/api/client.md
index 8bec161..6696a94 100644
--- a/docs/api/client.md
+++ b/docs/api/client.md
@@ -1,140 +1,89 @@
-# API: `client`
+# API: `c` — the client facade
 
-The `client` object is the only interface your app has to the outside world during a roundtrip. It is passed as the sole argument to `main(client)`.
+The single argument `main` receives. Every member is **synchronous**: queries
+are resolved before `main` runs, commands are recorded and replayed after it.
 
-> Source: [`core/srv/z2ui5/01/02/z2ui5_cl_ui5_client.js`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/z2ui5/01/02/z2ui5_cl_ui5_client.js)
+```js
+defineApp("ZCL_X", class {
+  main(c) { /* c is this page */ }
+});
+```
 
-## Lifecycle checks
+## Lifecycle
 
-| Method | Returns | Description |
-|---|---|---|
-| `check_on_init()` | `boolean` | `true` on the first `main()` of a fresh app instance |
-| `check_on_event(name?)` | `boolean` | `true` if the given event is current (or, without an argument, whether _any_ event is present) |
-| `check_on_navigated()` | `boolean` | `true` directly after `nav_app_call`/`nav_app_leave` |
-| `check_app_prev_stack()` | `boolean` | `true` when the nav stack is not empty |
-
-## Data binding
-
-| Method | Returns | Description |
-|---|---|---|
-| `_bind(value, opts?)` | `string` | One-way binding → `{/PATH}` |
-| `_bind_edit(value, opts?)` | `string` | Two-way binding → `{/XX/PATH}` |
-| `_bind_local(value)` | `string` | Local binding without an app property → `{/__local_N}` |
+| | |
+|---|---|
+| `c.isFirstRun` | `true` on the first roundtrip of **this app instance**, and only that one. Seed state here |
+| `c.isDisplay` | `true` on the first roundtrip **and** every time this app gets the screen back — a called app leaving, a value help closing, a bookmark restored. **Render here** |
+| `c.canGoBack` | `true` if there is an app to return to. Guard `navBack` with it |
+| `c.eventName` | the event this roundtrip answers; `""` on an app start |
+| `c.eventArg(i)` | the *i*-th event argument, **1-based**. The first 8 are resolved up front; beyond that use `c.raw` |
+| `c.prevApp` | the app on the other side of the last navigation, as plain values — how a called app's result is read |
 
-Paths are uppercased (`this.user_name` → `/XX/USER_NAME`) and mapped back onto the real property case-insensitively when the delta returns.
+`isFirstRun` implies `isDisplay`. See [App Lifecycle](../guide/lifecycle) for
+why confusing them produces a screen that silently does not refresh.
 
-::: info The two are one method upstream — but not here
-On the framework release cap2UI5 pins (**1.142.0**, `z2ui5_if_app.version`) these are genuinely two bindings: `_bind` writes into the model root and is read-only on the frontend, `_bind_edit` writes into the `XX` namespace the frontend can write back through. That is what `z2ui5_cl_ui5_srv_bind` does in the shipped code, and what this documentation describes throughout.
+## Binding and events
 
-abap2UI5 resolved the split in **1.143.0**: there `_bind_edit` is an alias of `_bind`, and the reverse-formatter options are accepted but ignored. If you are reading upstream material, that is the difference you are looking at. → [cap2UI5 vs. abap2UI5](../guide/vs-abap2ui5)
-:::
+| | |
+|---|---|
+| `c.bind(field)` | the binding path for a declared field. Takes the field **name** as a string. Throws, listing the known fields, if it is not one |
+| `c.event(name, args = [])` | the wire string for an event handler. `args` travel with it and come back as `c.eventArg(1..n)` |
 
-**`opts`** for `_bind` / `_bind_edit`:
-- `path: true` → returns the bare path without `{...}`
-- `path: "name"` → explicit path, no reference lookup
-- `name: "s_screen-city"` → resolve a member inside a bound structure by name
-- `custom_mapper: ".fmt"` → formatter function name
-- `custom_mapper_back: ".fmtBack"` → reverse formatter (only `_bind_edit`)
-- `custom_filter: ".f"` / `custom_filter_back: ".fb"` → aliases
-- `view: "POPUP"` → target view (rarely needed)
+```js
+`<Input value="${c.bind("name")}"/>`
+`<Button press="${c.event("TAKE", ["red"])}"/>`
+```
 
-## Events
+The value `c.event` returns is a handler expression — embed it, do not parse or
+compare it.
 
-| Method | Returns | Description |
-|---|---|---|
-| `_event(name, args?, ctrl?, data?)` | `string` | Backend event (roundtrip) |
-| `_event_client(name, args?)` | `string` | Frontend-only event |
-| `_event_nav_app_leave()` | `string` | Special event for the page back button |
+## Screen
 
-`ctrl` options: `{ bypass_busy, force_main_model }`.
+| | |
+|---|---|
+| `c.view(xml)` | render the main view. An `mvc:View` |
+| `c.popup(xml)` | a dialog on top. A `core:FragmentDefinition` |
+| `c.popupClose()` | close it |
+| `c.nest(into, xml, {insert, clear})` | render a fragment **into** a control of the main view. `into` is that control's id; `insert`/`clear` default to `addContent`/`removeAllContent` |
+| `c.nestClose()` | clear the nested slot. There is exactly one, so it takes no argument |
+| `c.messageBox(text)` | a dialog with an OK button |
+| `c.messageToast(text)` | a transient toast |
 
-`get_event_arg(n)` reads 1-based like ABAP — JS-style goes via `client.get().T_EVENT_ARG[index]`.
+Commands are replayed **in the order you called them**.
 
-## Request context
+## Navigation
 
-| Method | Description |
+| | |
 |---|---|
-| `get()` | returns `{ EVENT, T_EVENT_ARG, S_CONFIG, S_DRAFT, CHECK_LAUNCHPAD_ACTIVE, CHECK_ON_NAVIGATED, _S_NAV, R_EVENT_DATA }` |
-| `get_event_arg(n)` | n-th event arg (1-based) |
-| `get_frontend_data()` | raw `S_FRONT` object |
-| `get_app(id?)` | current app instance (or `null` with an ID) |
-| `get_app_prev()` | previous app (before nav-leave) |
+| `c.navTo(app)` | show another app on top of this one. Takes a registered name, a `defineApp` class, or an instance |
+| `c.navBack(opts)` | hand the screen back. `{ event, data, app }`, all optional |
 
-## View slots
+Both are scheduled for the end of the roundtrip.
 
-| Method | Description |
-|---|---|
-| `view_display(xml, anno?, modelPath?)` | Render main view |
-| `view_model_update()` | Render only the model delta |
-| `view_destroy()` | Remove main view |
-| `nest_view_display(xml, id, m_ins, m_dest?)` | Nested view 1 |
-| `nest_view_model_update()` / `nest_view_destroy()` | ditto |
-| `nest2_view_display(...)` / ... | Nested view 2 |
-| `popup_display(xml)` | Open popup |
-| `popup_model_update()` / `popup_destroy()` | ditto |
-| `popover_display(xml, byId)` | Show popover |
-| `popover_model_update()` / `popover_destroy()` | ditto |
-
-## Messages
-
-| Method | Description |
-|---|---|
-| `message_toast_display(text, opts?)` | Short toast |
-| `message_box_display(text, type?, title?, ...)` | Modal MessageBox |
+## Escape hatch
 
-`opts` for toast: `duration, width, my, at, of, offset, collision, animation_duration, animation_timing_function, onclose, autoclose, closeonbrowsernavigation, class`.
+| | |
+|---|---|
+| `c.raw` | the underlying `z2ui5_if_client`, unwrapped. **Async** — every call needs `await` |
 
-`message_box_display` arguments in order: `text, type, title, styleclass, onclose, actions, emphasizedaction, initialfocus, textdirection, icon, details, closeonnavigation`.
+Use it for anything the facade does not cover. Its methods are the ABAP ones
+with `~` written as `$`:
 
-## Navigation
+```js
+await c.raw.z2ui5_if_client$set_session_stateful({ val: abap.builtin.abap_true });
+```
 
-| Method | Description |
-|---|---|
-| `nav_app_call(app)` | Forward — push `app` onto the stack |
-| `nav_app_leave(app?)` | Back — stack top or explicit app |
-| `nav_app_home()` | Back to startup |
-| `nav_app_back()` | Identical to `nav_app_leave()` but explicitly marked as "back" |
+## Removed, and why
 
-## State setters
+Both throw an error naming the replacement rather than quietly changing meaning:
 
-| Method | Description |
+| | |
 |---|---|
-| `set_session_stateful(bool)` | Activate sticky session |
-| `set_app_state_active(bool)` | Activate app state on the frontend |
-| `set_nav_back(bool)` | Browser back-button behavior |
-| `set_push_state(value)` | Browser history push |
-| `follow_up_action(rawString)` | Queue arbitrary `eF` action |
+| `c.isInitial` | it was wired to `check_on_navigated()` and named after `check_on_init()`. Use `c.isDisplay` / `c.isFirstRun` |
+| `c.modelUpdate()` | it called `view_model_update()`, which the framework declares **obsolete and does nothing** |
 
-## Frontend convenience methods
+## Next
 
-All queue `eF` calls into `_follow_up_actions[]`. They are sent in the response as `S_FOLLOW_UP_ACTION.CUSTOM_JS`, and the frontend driver runs them sequentially.
-
-| Method | Effect |
-|---|---|
-| `clipboard_copy(text)` | Copy text |
-| `clipboard_copy_app_state()` | Copy current deep-link URL |
-| `file_download(b64Url, filename)` | Download file |
-| `open_new_tab(url)` | Open tab |
-| `location_reload(url)` | Page reload to URL |
-| `history_back()` | `history.back()` |
-| `system_logout(url?)` | Logout via FLP / URL |
-| `popup_close()`, `popover_close()` | Close current popup/popover |
-| `cross_app_nav_to_prev_app()` | FLP: back |
-| `cross_app_nav_to_ext(target, params, mode?)` | FLP: external |
-| `storage_set(type, prefix, key, value)` | Browser storage set |
-| `storage_remove(type, prefix, key)` | Browser storage remove |
-| `set_odata_model(url, name?, anno?)` | Set OData model |
-| `set_size_limit(view, limit)` / `reset_size_limit(view)` | Size limit |
-| `url_helper_redirect(url, new_window?)` | URLHelper.redirect |
-| `url_helper_email({email, subject?, body?, cc?, bcc?, new_window?})` | mailto: |
-| `url_helper_sms({telephone, message?})` | SMS link |
-| `url_helper_tel(telephone)` | Tel link |
-
-## Constants
-
-| | Value |
-|---|---|
-| `client.cs_event` (instance getter) | `CS_EVENT` (see [Events](../guide/events#event-client)) |
-| `client.cs_view` | `{ MAIN, NESTED, NESTED2, POPUP, POPOVER }` |
-| Static `z2ui5_cl_ui5_client.CS_BIND_TYPE` | `{ one_way, two_way }` |
-| Static `z2ui5_cl_ui5_client.EVENT_NAV_APP_LEAVE` | Reserved event name |
+- [**App Interface**](./app-interface) — `defineApp` and `t`
+- [**App Lifecycle**](../guide/lifecycle) — when each branch runs
diff --git a/docs/api/view-builder.md b/docs/api/view-builder.md
deleted file mode 100644
index 70fa2cf..0000000
--- a/docs/api/view-builder.md
+++ /dev/null
@@ -1,130 +0,0 @@
-# API: View Builder
-
-Views are built in JavaScript and rendered to UI5 XML. There is one builder:
-`z2ui5_cl_ui5_view_builder`. It is generic — it knows XML elements and
-attributes, not the UI5 control catalogue — which is why the transpiler
-targets it and why every one of the
-[bundled samples](../guide/samples) is written against it.
-
-Source: [`core/srv/z2ui5/02/z2ui5_cl_ui5_view_builder.js`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/z2ui5/02/z2ui5_cl_ui5_view_builder.js).
-
-::: info A second builder used to ship here
-Earlier versions also shipped a per-control builder (`view.Page({ title })`).
-It was a port of a class upstream had already retired, and cap2UI5 stopped carrying upstream's frozen legacy package in
-2026-08 — see [The Ecosystem](../guide/ecosystem). Everything it did, the
-builder below does; the difference is that you name the control.
-:::
-
-## Getting started
-
-```js
-const z2ui5_cl_ui5_view_builder = require("abap2UI5/z2ui5_cl_ui5_view_builder");
-
-const view = z2ui5_cl_ui5_view_builder.factory()
-  .ele({ n: `View`, ns: `mvc` })
-  .a({ n: `xmlns`,     v: `sap.m` })
-  .a({ n: `xmlns:mvc`, v: `sap.ui.core.mvc` });
-
-const page = view.ele(`Shell`).ele(`Page`).a({ n: `title`, v: `Hello` });
-
-page.ele(`Button`)
-  .a({ n: `text`,  v: `Press me` })
-  .a({ n: `press`, v: client._event(`BUTTON_PRESS`) });
-
-client.view_display(view.stringify());
-```
-
-```xml
-<mvc:View xmlns="sap.m" xmlns:mvc="sap.ui.core.mvc">
-  <Shell><Page title="Hello"><Button text="Press me" press="..."/></Page></Shell>
-</mvc:View>
-```
-
-## Methods
-
-| Method | Meaning |
-|---|---|
-| `factory()` | static — a new, empty tree |
-| `.ele({n, ns})` | append a child element and **descend into it** (the return value is the child) |
-| `.tag({n, ns})` | append a child element and **stay** on the current node (the return value is `this`) |
-| `.a({n, v})` | set attribute `n` on the current node — or on the last child added with `.tag()` |
-| `.a({n, b})` | same, for a boolean: `b` is rendered as `"true"` / `"false"` |
-| `.end()` | go back up to the parent node |
-| `.stringify()` | render the whole tree to an XML string |
-
-Every method accepts its main argument positionally as well, so
-`.ele("Page")` is the same as `.ele({ n: "Page" })` — the samples mix both.
-
-## `.ele()` vs `.tag()`
-
-This is the one thing worth internalising, because the two look
-interchangeable and are not:
-
-```js
-page.ele(`Button`).a({ n: `text`, v: `A` });   // now positioned ON the button
-page.tag(`Button`).a({ n: `text`, v: `B` });   // still positioned on the page
-```
-
-Use `.ele()` for containers you want to nest into (and `.end()` to come back
-out), `.tag()` for leaves. A chain that has silently descended one level too
-far is the usual cause of controls ending up nested inside their sibling.
-
-## Namespaces are yours to declare {#namespaces}
-
-The builder does not know which UI5 library a control belongs to, so **you**
-declare the namespace and prefix the element. This is the single most common
-way to break a view, and it breaks it hard: an unprefixed tag resolves against
-the default `xmlns`, so `<SimpleForm>` under `xmlns="sap.m"` becomes a request
-for `sap/m/SimpleForm.js` and the whole view fails to **load** — no partial
-render, just a `ModuleError` in the console.
-
-```js
-const view = z2ui5_cl_ui5_view_builder.factory()
-  .ele({ n: `View`, ns: `mvc` })
-  .a({ n: `xmlns`,      v: `sap.m` })
-  .a({ n: `xmlns:mvc`,  v: `sap.ui.core.mvc` })
-  .a({ n: `xmlns:core`, v: `sap.ui.core` })
-  .a({ n: `xmlns:form`, v: `sap.ui.layout.form` });
-
-view.ele(`Shell`).ele(`Page`)
-  .ele({ n: `SimpleForm`, ns: `form` })      // sap.ui.layout.form
-  .ele({ n: `content`,    ns: `form` })      // …and so is its aggregation
-  .tag({ n: `Title`,      ns: `core` })      // sap.ui.core
-  .a({ n: `text`, v: `Hi` });
-```
-
-Aggregations take the namespace of the control that owns them — `content` on
-a `form:SimpleForm` is `form:content`, `items` on a `List` is unprefixed like
-the `List` itself.
-
-## Popups
-
-A popup is a fragment, not a view, so the root element differs:
-
-```js
-const view = z2ui5_cl_ui5_view_builder.factory()
-  .ele({ n: `FragmentDefinition`, ns: `core` })
-  .a({ n: `xmlns`,      v: `sap.m` })
-  .a({ n: `xmlns:core`, v: `sap.ui.core` });
-
-view.ele(`Dialog`).a({ n: `title`, v: `Confirm` });
-client.popup_display(view.stringify());
-```
-
-## Custom controls
-
-Custom controls live in the `z2ui5` namespace, declared as `z2ui5.cc`:
-
-```js
-view.a({ n: `xmlns:z2ui5`, v: `z2ui5.cc` });
-view.tag({ n: `Info`, ns: `z2ui5` }).a({ n: `ui5_version`, v: client._bind(this.version) });
-```
-
-## Constraints
-
-- `.a()` asserts that the attribute is not already set on the node — setting
-  the same attribute twice throws rather than quietly winning last.
-- `.a()` also asserts the node is a real element; attributes cannot be set on
-  the tree root before the first `.ele()`.
-- There are no `.content()` / `.items()` shorthands: an aggregation is an
-  ordinary element you write yourself.
diff --git a/docs/examples/external-odata.md b/docs/examples/external-odata.md
index 298d7be..99e75e6 100644
--- a/docs/examples/external-odata.md
+++ b/docs/examples/external-odata.md
@@ -1,139 +1,109 @@
-# External OData Service
+# Calling an External Service
 
-cap2UI5 apps have full access to the CAP connection pool. You can consume any **external OData service** — the call goes _inside_ your `main()` via the normal `cds.connect.to(...)` API.
+An app is a CAP handler in every way that matters, so calling a remote service
+is CAP's job rather than cap2UI5's: import the service, declare it in
+`cds.requires`, `cds.connect.to` it, and run a query.
 
-## Configuration
+::: warning Not exercised by this project's test suite
+Everything here is standard CAP remote-service usage, and it works from an app
+because an app is ordinary handler code with `cds` in scope. But there is no
+test in the repository that calls a remote service, so treat this page as the
+shape rather than as a measured recipe — unlike [Hello World](./hello-world)
+and [List & Detail](./list), which are files the CI runs.
+:::
 
-In `package.json`:
+## Import the service
+
+Once, with CAP's own tooling:
+
+```bash
+cds import https://services.odata.org/V2/Northwind/Northwind.svc/\$metadata \
+  --as cds --out srv/external
+```
+
+and declare it:
 
 ```json
 {
   "cds": {
     "requires": {
-      "northwind": {
+      "Northwind": {
         "kind": "odata-v2",
-        "model": "srv/external/northwind",
-        "credentials": {
-          "url": "https://services.odata.org/V2/Northwind/Northwind.svc/"
-        }
+        "model": "srv/external/Northwind",
+        "credentials": { "url": "https://services.odata.org/V2/Northwind/Northwind.svc" }
       }
     }
   }
 }
 ```
 
-The CSN model is generated as usual with `cds import https://services.odata.org/V2/Northwind/Northwind.svc/` and saved at `srv/external/northwind.csn`.
+In production the `credentials` come from a destination binding instead — again,
+plain CAP.
 
-## App code
+## The app
 
 ```js
-// srv/app/read_odata.js
-const cds                       = require("@sap/cds");
-const z2ui5_if_app              = require("abap2UI5/z2ui5_if_app");
-const z2ui5_cl_ui5_view_builder = require("abap2UI5/z2ui5_cl_ui5_view_builder");
-
-class read_odata extends z2ui5_if_app {
-
-  customers = [];
-
-  async main(client) {
-
-    if (client.check_on_init()) {
-      const northwind = await cds.connect.to("northwind");
-      this.customers  = await northwind.run(SELECT.from("Customers").limit(50));
-
-      const view = z2ui5_cl_ui5_view_builder.factory()
-        .ele({ n: `View`, ns: `mvc` })
-        .a({ n: `xmlns`,     v: `sap.m` })
-        .a({ n: `xmlns:mvc`, v: `sap.ui.core.mvc` });
-
-      const tab = view.ele(`Shell`).ele(`Page`)
-        .a({ n: `title`, v: `Northwind - Customers` })
-        .ele(`Table`)
-        .a({ n: `items`, v: client._bind_edit(this.customers) });
-
-      const cols = tab.ele(`columns`);
-      cols.ele(`Column`).tag(`Text`).a({ n: `text`, v: `CompanyName` });
-      cols.ele(`Column`).tag(`Text`).a({ n: `text`, v: `ContactName` });
-      cols.ele(`Column`).tag(`Text`).a({ n: `text`, v: `Country` });
-
-      tab.ele(`items`).ele(`ColumnListItem`).ele(`cells`)
-        .tag(`Input`).a({ n: `value`, v: `{COMPANYNAME}` }).a({ n: `enabled`, b: true })
-        .tag(`Input`).a({ n: `value`, v: `{CONTACTNAME}` }).a({ n: `enabled`, b: true })
-        .tag(`Text`).a({ n: `text`, v: `{COUNTRY}` });
-
-      client.view_display(view.stringify());
+// srv/apps/northwind.js
+const cds = require("@sap/cds");
+const { SELECT } = cds.ql;
+const { defineApp, t } = require("cap2ui5");
+
+defineApp("ZCL_NORTHWIND", class {
+  country  = "";
+  products = t.table({ ProductID: 0, ProductName: "", UnitPrice: t.packed(11, 2) });
+  status   = "";
+
+  async main(c) {
+    if (c.eventName === "LOAD") {
+      try {
+        const nw = await cds.connect.to("Northwind");
+        this.products = await nw.run(SELECT.from("Products").limit(20));
+        this.status   = `${this.products.length} products`;
+      } catch (e) {
+        // a remote call fails in ways a local one does not
+        this.status = "the service did not answer";
+        c.messageBox(`Northwind unreachable: ${e.message}`);
+      }
+    }
 
-    } else if (client.check_on_event("SAVE_BACK")) {
-      const northwind = await cds.connect.to("northwind");
-      // … this.customers contains the user edits thanks to two-way binding
-      // … run an UPDATE on the service for each row
+    if (c.isDisplay) {
+      c.view(
+        `<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m" displayBlock="true" height="100%">` +
+        `<Shell><Page title="Northwind">` +
+        `<Button text="Load" press="${c.event("LOAD")}"/>` +
+        `<Text text="${c.bind("status")}"/>` +
+        `<Table items="${c.bind("products")}">` +
+        `<columns><Column><Text text="Product"/></Column><Column><Text text="Price"/></Column></columns>` +
+        `<items><ColumnListItem><cells>` +
+        `<Text text="{PRODUCTNAME}"/><ObjectNumber number="{UNITPRICE}"/>` +
+        `</cells></ColumnListItem></items></Table>` +
+        `</Page></Shell></mvc:View>`);
     }
   }
-}
-
-module.exports = read_odata;
-```
-
-## What's new here
-
-### 1. CDS connection inline
-
-```js
-const northwind = await cds.connect.to("northwind");
-this.customers  = await northwind.run(SELECT.from("Customers").limit(50));
-```
-
-The same code you would write in a `srv/z2ui5-service.js` handler. **Anything Node.js allows is allowed inside `main()`** — fetch, OData, file system, Redis, MQ.
-
-### 2. Two-way on a list
-
-```js
-const tab = page.ele(`Table`).a({ n: `items`, v: client._bind_edit(this.customers) });
-
-tab.ele(`items`).ele(`ColumnListItem`).ele(`cells`)
-  .tag(`Input`).a({ n: `value`, v: `{COMPANYNAME}` }).a({ n: `enabled`, b: true });
+});
 ```
 
-Because the array is two-way bound via `_bind_edit`, UI5 writes user edits **on every item property** back into the XX delta. On the next roundtrip `this.customers` holds the modified state. The item-relative paths are uppercase (`{COMPANYNAME}`, not `{CompanyName}`): the model is written with uppercase names and mapped back onto your properties case-insensitively.
+## Three things a remote call needs that a local one does not
 
-### 3. Persistence caveat
+**Catch.** A remote service is down, slow or rate-limited in ways your own
+database is not. An unhandled error answers `roundtrip failed (<id>)` and the
+user sees nothing useful; catching it lets you say what happened.
 
-The entire `this.customers` array is serialized and deserialized between roundtrips. With 50 rows: no problem. With 50,000 rows: noticeable. Rules of thumb:
+**Expect a wait.** The call happens inside the roundtrip, so the user waits for
+it. Fetch on an explicit event rather than in the render branch, and `limit`
+generously.
 
-- **Reload fresh in `check_on_init()`** instead of holding the array as long-lived app state.
-- For **read-heavy** lists with sort/filter/paging: the `set_odata_model` pattern (see [Events](../guide/events#convenience-server-triggered-frontend-actions)) — then the array lives in the frontend driver, not the app instance.
+**Watch the field names.** The row fields in the view are the **uppercased**
+names of what the service returns — `{PRODUCTNAME}` for `ProductName`. Declare
+the row with the names as they arrive (`ProductName`), and bind them uppercased.
 
-Example with an OData-backed table:
+## Where the data goes
 
-```js
-async main(client) {
-  if (client.check_on_init()) {
-    client.set_odata_model("/odata/v4/admin/NorthwindCustomers");
-
-    const view = z2ui5_cl_ui5_view_builder.factory()
-      .ele({ n: `View`, ns: `mvc` })
-      .a({ n: `xmlns`,     v: `sap.m` })
-      .a({ n: `xmlns:mvc`, v: `sap.ui.core.mvc` });
-
-    view.ele(`Shell`).ele(`Page`).a({ n: `title`, v: `Customers (OData)` })
-      .ele(`Table`)
-      .a({ n: `items`, v: `{/NorthwindCustomers}` })
-      // ↑ no _bind_edit, but a static OData path binding
-      .ele(`columns`).ele(`Column`).tag(`Text`).a({ n: `text`, v: `Company` });
-
-    client.view_display(view.stringify());
-  }
-}
-```
+Into a declared field, like any other state — so it is in the draft and survives
+the roundtrip. Which also means you fetch **once** and the table stays filled
+until you refresh it deliberately.
 
-You then need your own CAP service action `NorthwindCustomers` in `z2ui5-service.js`:
-
-```js
-srv.on("READ", "NorthwindCustomers", async (req) => {
-  const northwind = await cds.connect.to("northwind");
-  return northwind.run(req.query);
-});
-```
+## Next
 
-→ Continue with [**Static XML View**](./static-xml-view).
+- [**List & Detail**](./list) — the same shape against your own entities, tested
+- [**Data Binding**](../guide/data-binding) — declaring the row type
diff --git a/docs/examples/hello-world.md b/docs/examples/hello-world.md
index 650c6ad..5507c6c 100644
--- a/docs/examples/hello-world.md
+++ b/docs/examples/hello-world.md
@@ -1,119 +1,95 @@
 # Hello World
 
-The simplest variation of a cap2UI5 app: an input field, a button, a confirmation box.
-
-## Code
-
-This is `core/srv/z2ui5/01/04/z2ui5_cl_ui5_app_hi_world.js`, the app the framework ships and the one `?app_start=z2ui5_cl_ui5_app_hi_world` starts — quoted as it stands:
+The smallest complete cap2UI5 app. This is
+[`examples/bookshop/srv/apps/hello.js`](https://github.com/cap2UI5/cap2UI5/blob/main/examples/bookshop/srv/apps/hello.js)
+verbatim — it is exercised by the wire tests, the cold-restart test and the
+browser test on every CI run.
 
 ```js
-const z2ui5_cl_ui5_view_builder = require("../../02/z2ui5_cl_ui5_view_builder");
-const z2ui5_if_app = require("../../02/z2ui5_if_app");
-
-class z2ui5_cl_ui5_app_hi_world extends z2ui5_if_app {
-  name = ``;
-
-  async main(client) {
-    if (client.check_on_init()) {
-      const view = z2ui5_cl_ui5_view_builder.factory()
-        .ele({ n: `View`, ns: `mvc` })
-        .a({ n: `xmlns`, v: `sap.m` })
-        .a({ n: `xmlns:mvc`, v: `sap.ui.core.mvc` })
-        .a({ n: `xmlns:core`, v: `sap.ui.core` })
-        // SimpleForm and its content aggregation live in sap.ui.layout.form
-        .a({ n: `xmlns:form`, v: `sap.ui.layout.form` });
-
-      const form = view
-        .ele({ n: `Shell` })
-        .ele({ n: `Page` })
-        .a({ n: `title`, v: `abap2UI5 - Hello World` })
-        .ele({ n: `SimpleForm`, ns: `form` })
-        .a({ n: `editable`, b: true })
-        .ele({ n: `content`, ns: `form` });
-
-      form
-        .tag({ n: `Title`, ns: `core` })
-        .a({ n: `text`, v: `Enter a value and send it to the server...` })
-        .tag({ n: `Label` })
-        .a({ n: `text`, v: `Name` })
-        .tag({ n: `Input` })
-        .a({ n: `value`, v: client._bind_edit(this.name) })
-        .tag({ n: `Button` })
-        .a({ n: `text`, v: `Send` })
-        .a({ n: `press`, v: client._event(`BUTTON_POST`) });
-
-      client.view_display(view.stringify());
-    } else if (client.check_on_event(`BUTTON_POST`)) {
-      client.message_box_display(`Your name is ${this.name}`);
+// srv/apps/hello.js
+const { defineApp } = require("cap2ui5");
+
+defineApp("ZCL_JS_HELLO", class {
+  name = "";
+
+  main(c) {
+    if (c.isDisplay) {
+      c.view(
+        `<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m" displayBlock="true" height="100%">` +
+        `<Shell><Page title="cap2UI5 - JS app">` +
+        `<Input value="${c.bind("name")}"/>` +
+        `<Button text="Go" press="${c.event("GO")}"/>` +
+        `</Page></Shell></mvc:View>`);
+      return;
     }
+    if (c.eventName === "GO") c.messageBox(`Hello ${this.name}`);
   }
-}
-
-module.exports = z2ui5_cl_ui5_app_hi_world;
+});
 ```
 
-::: tip The two import lines are the one thing you write differently
-This file lives *inside* the core package, so it reaches its neighbours by relative path. Your own app sits outside the package and imports through its exports map:
+Run it:
 
-```js
-const z2ui5_cl_ui5_view_builder = require("abap2UI5/z2ui5_cl_ui5_view_builder");
-const z2ui5_if_app = require("abap2UI5/z2ui5_if_app");
 ```
-
-Everything below those two lines is identical.
-:::
-
-## The view it renders
-
-```xml
-<mvc:View xmlns="sap.m" xmlns:mvc="sap.ui.core.mvc" xmlns:core="sap.ui.core" xmlns:form="sap.ui.layout.form">
-  <Shell>
-    <Page title="abap2UI5 - Hello World">
-      <form:SimpleForm editable="true">
-        <form:content>
-          <core:Title text="Enter a value and send it to the server..."/>
-          <Label text="Name"/>
-          <Input value="{/XX/NAME}"/>
-          <Button text="Send" press="..."/>
-        </form:content>
-      </form:SimpleForm>
-    </Page>
-  </Shell>
-</mvc:View>
+http://localhost:4004/rest/root/z2ui5?app_start=ZCL_JS_HELLO
 ```
 
-Two details of the builder are visible here and are worth taking with you:
-
-- **`.ele()` descends, `.tag()` stays.** `Shell`, `Page`, `SimpleForm` and `content` are containers, so they get `.ele()`. The four controls inside `content` are leaves added to the *same* parent, so they get `.tag()` — and `.a()` after a `.tag()` sets the attribute on that last child, not on `content`.
-- **You name the namespace.** `SimpleForm`, its `content` aggregation and `Title` are not in `sap.m`. An unprefixed `<SimpleForm>` would resolve to `sap/m/SimpleForm.js` and the view would fail to *load*. → [Namespaces are yours to declare](../api/view-builder#namespaces)
+## Line by line
 
-## What happens
-
-| Phase | What runs |
+| | |
 |---|---|
-| **Initial load** | Frontend POSTs an empty body. Server has no `S_FRONT.ID`, falls back to the startup app. User clicks the "Hello World" link. |
-| **App start** | New `app_start=z2ui5_cl_ui5_app_hi_world` starts. `check_on_init() === true`, view is rendered. |
-| **User types** | Two-way binding via `client._bind_edit(this.name)` — value flows into the XX delta. |
-| **User clicks "Send"** | Frontend sends `S_FRONT.EVENT = "BUTTON_POST"` + XX delta with `NAME`. Server applies the delta to `this.name` and calls `main()`. |
-| **`check_on_event("BUTTON_POST")`** | True → `message_box_display(...)` with the current name. |
+| `require("cap2ui5")` | the plugin's only export surface: `defineApp` and `t` |
+| `defineApp("ZCL_JS_HELLO", …)` | the first argument is the name **on the wire** — what `?app_start=` takes. The file name does not matter |
+| `name = ""` | app state. An empty string types it as `string`, and it survives the roundtrip because the instance is written to `cap2ui5.Drafts` |
+| `main(c)` | synchronous — no `async`, no `await` |
+| `c.isDisplay` | the render branch. True on the first roundtrip **and** whenever the app gets the screen back |
+| `c.bind("name")` | the binding path — two-way, so what the user types arrives on `this.name` |
+| `c.event("GO")` | the handler expression; the next roundtrip has `c.eventName === "GO"` |
+| `c.messageBox(…)` | a dialog with an OK button |
 
-## Launch
+## What happens when you click
 
-```
-http://localhost:4004/z2ui5/webapp/index.html?app_start=z2ui5_cl_ui5_app_hi_world
-```
+1. the browser POSTs `{ID, APP, EVENT: "GO", MODEL: {NAME: "Ada"}}`;
+2. the server loads the draft, rebuilds the instance, applies `MODEL` — so
+   `this.name` is `"Ada"` **before** `main` runs;
+3. `main` takes the `GO` branch and queues a message box;
+4. the response carries the action and a **new** draft id.
 
-Or, without installing anything, in the [browser playground](../guide/playground):
+No controller, no manifest, no model code, no OData service.
 
+## Adding state
+
+```js
+defineApp("ZCL_JS_HELLO", class {
+  name  = "";
+  count = 0;
+
+  main(c) {
+    if (c.isDisplay) {
+      c.view(
+        `<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m" displayBlock="true" height="100%">` +
+        `<Shell><Page title="Hello">` +
+        `<Input value="${c.bind("name")}"/>` +
+        `<Text text="clicks: ${c.bind("count")}"/>` +
+        `<Button text="Go" press="${c.event("GO")}"/>` +
+        `</Page></Shell></mvc:View>`);
+      return;
+    }
+    if (c.eventName === "GO") {
+      this.count++;
+      c.messageToast(`Hello ${this.name}, click ${this.count}`);
+    }
+  }
+});
 ```
-https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_ui5_app_hi_world
-```
 
-## What you can take away from this
+`count` needs no re-render: changed **bound data** is pushed to the view on its
+own. You call `c.view()` again only when the view's *structure* changes.
+
+The counter also survives a server restart — the state is a row in your
+database, not memory. See [Persistence](../guide/persistence).
 
-- **One file = one app.** Class names match file names.
-- **Two phases.** `check_on_init()` for the initial view, `check_on_event(...)` for events.
-- **Reference-equality bindings.** `client._bind_edit(this.name)` finds the path `/XX/NAME` itself.
-- **Pure JavaScript.** No manifest, no component, no OData layer.
+## Next
 
-→ Continue with [**Selection Screen**](./selection-screen) for a richer form with various control types.
+- [**List & Detail**](./list) — a table filled from your own CDS entity
+- [**App Lifecycle**](../guide/lifecycle) — `isDisplay` vs. `isFirstRun`
+- [**Data Binding**](../guide/data-binding) — the types
diff --git a/docs/examples/list.md b/docs/examples/list.md
index f763abe..c309a73 100644
--- a/docs/examples/list.md
+++ b/docs/examples/list.md
@@ -1,127 +1,109 @@
 # List & Detail
 
-A list with a selection-change event that reacts to a row selection. Shows the pattern for **table/list bindings** and how an item click is handled on the server side.
-
-## Code
+A table filled from your own CDS entity, and a row that can be written back.
+This is [`examples/bookshop/srv/apps/books.js`](https://github.com/cap2UI5/cap2UI5/blob/main/examples/bookshop/srv/apps/books.js)
+— the app the coexistence test drives, so both directions below are measured
+rather than sketched.
 
 ```js
-// srv/app/my_list.js
-const z2ui5_if_app              = require("abap2UI5/z2ui5_if_app");
-const z2ui5_cl_ui5_view_builder = require("abap2UI5/z2ui5_cl_ui5_view_builder");
-
-class my_list extends z2ui5_if_app {
-
-  t_tab = [];
-
-  async main(client) {
-
-    if (client.check_on_init()) {
-
-      this.t_tab = [
-        { title: "row_01", descr: "Description 1", icon: "sap-icon://account", info: "completed",   selected: false },
-        { title: "row_02", descr: "Description 2", icon: "sap-icon://account", info: "incompleted", selected: false },
-        { title: "row_03", descr: "Description 3", icon: "sap-icon://account", info: "working",     selected: false },
-        { title: "row_04", descr: "Description 4", icon: "sap-icon://account", info: "working",     selected: false },
-        { title: "row_05", descr: "Description 5", icon: "sap-icon://account", info: "completed",   selected: false },
-      ];
-
-      const view = z2ui5_cl_ui5_view_builder.factory()
-        .ele({ n: `View`, ns: `mvc` })
-        .a({ n: `xmlns`,     v: `sap.m` })
-        .a({ n: `xmlns:mvc`, v: `sap.ui.core.mvc` });
-
-      const page = view.ele(`Shell`).ele(`Page`)
-        .a({ n: `title`,          v: `abap2UI5 - List` })
-        .a({ n: `navButtonPress`, v: client._event_nav_app_leave() })
-        .a({ n: `showNavButton`,  b: client.check_app_prev_stack() });
-
-      page.ele(`List`)
-        .a({ n: `headerText`,      v: `Items` })
-        .a({ n: `items`,           v: client._bind_edit(this.t_tab) })
-        .a({ n: `mode`,            v: `SingleSelectMaster` })
-        .a({ n: `selectionChange`, v: client._event(`SELCHANGE`) })
-        .tag(`StandardListItem`)
-        .a({ n: `title`,       v: `{TITLE}` })
-        .a({ n: `description`, v: `{DESCR}` })
-        .a({ n: `icon`,        v: `{ICON}` })
-        .a({ n: `info`,        v: `{INFO}` })
-        .a({ n: `press`,       v: client._event(`ITEM_PRESS`) })
-        .a({ n: `selected`,    v: `{SELECTED}` });
-
-      client.view_display(view.stringify());
-
-    } else if (client.check_on_event("SELCHANGE")) {
-      const sel = this.t_tab.find((row) => row.selected);
-      client.message_box_display(`Details for: ${sel?.title ?? ""}`);
-
-    } else if (client.check_on_event("ITEM_PRESS")) {
-      // click on item — could navigate to a detail view
-      client.message_toast_display("Item clicked");
+// srv/apps/books.js
+const cds = require("@sap/cds");
+const { SELECT, INSERT } = cds.ql;
+const { defineApp, t } = require("cap2ui5");
+
+defineApp("ZCL_JS_BOOKS", class {
+  search = "";
+  hits   = 0;
+  books  = t.table({ ID: 0, title: "", author: "", price: t.packed(9, 2) });
+
+  async main(c) {
+    if (c.isDisplay) {
+      c.view(
+        `<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m" displayBlock="true" height="100%">` +
+        `<Shell><Page title="cap2UI5 - Books">` +
+        `<SearchField value="${c.bind("search")}" search="${c.event("SEARCH")}"/>` +
+        `<Table items="${c.bind("books")}">` +
+        `<columns><Column><Text text="Title"/></Column><Column><Text text="Author"/></Column>` +
+        `<Column><Text text="Price"/></Column></columns>` +
+        `<items><ColumnListItem><cells><Text text="{TITLE}"/><Text text="{AUTHOR}"/>` +
+        `<ObjectNumber number="{PRICE}"/></cells></ColumnListItem></items></Table>` +
+        `<Text text="${c.bind("hits")} hits"/>` +
+        `<Button text="Add" press="${c.event("ADD")}"/>` +
+        `</Page></Shell></mvc:View>`);
+      return;
     }
-  }
-}
-
-module.exports = my_list;
-```
-
-## Important spots
 
-### Bindings for aggregation slots
+    if (c.eventName === "SEARCH") {
+      const { Books } = cds.entities("my.bookshop");
+      this.books = await SELECT.from(Books).where`title like ${"%" + this.search + "%"}`;
+      this.hits  = this.books.length;
+      c.messageToast(`${this.hits} found`);
+    }
 
-```js
-page.ele(`List`)
-  .a({ n: `items`, v: client._bind_edit(this.t_tab) })
-  .tag(`StandardListItem`)
-  .a({ n: `title`,       v: `{TITLE}` })   // ← path relative to the item
-  .a({ n: `description`, v: `{DESCR}` })
-  .a({ n: `selected`,    v: `{SELECTED}` });
+    if (c.eventName === "ADD") {
+      const { Books } = cds.entities("my.bookshop");
+      const max = await SELECT.one.from(Books).columns("max(ID) as m");
+      await INSERT.into(Books).entries({
+        ID: (max?.m ?? 0) + 1, title: this.search, author: "the app", stock: 1, price: 1.0,
+      });
+      c.messageToast(`added ${this.search}`);
+    }
+  }
+});
 ```
 
-`items` gets the top-level binding (`{/XX/T_TAB}`). Inside `StandardListItem`, all paths are **relative to the item** — `{TITLE}` refers to `t_tab[N].title`.
+## The three things worth copying
 
-::: tip Why the uppercase paths
-Model paths are uppercased on the way out (`this.t_tab` → `/XX/T_TAB`, the column `title` → `{TITLE}`) — the abap2UI5 wire format, where component names are ABAP identifiers. The write-back maps them onto your real, lowercase properties case-insensitively, so `this.t_tab[0].title` is what you read in `main()`. Write the relative paths uppercase and they will match.
-:::
+**`main` is `async` here** — because the *app* does I/O. The framework calls
+still need no `await`; `SELECT` does.
 
-There is no `items` element in the chain: `items` is the default aggregation of `List`, so a child added with `.tag()` lands in it. An aggregation that is *not* the default one (a `Table`'s `columns`, a `Page`'s `footer`) is written out as an element of its own.
+**The table is declared, not inferred.** `t.table({…})` names the row, and
+`t.packed(9, 2)` makes `price` a decimal. An empty array carries no type, so a
+bare `books = []` would be left out of the model and named in a warning.
 
-### `selectionChange` vs. `press`
+**Assign the whole array.** `this.books = await SELECT…` replaces the table and
+the plugin rebuilds the rows. Mutating the array you read back does not write
+through.
 
-- `selectionChange` fires in **selection mode** (SingleSelectMaster, MultiSelect). The `selected` property of items is updated two-way in the model, so on the server you can check via `find(row => row.selected)`.
-- `press` fires on **item click** regardless of selection mode. Useful when you want an "open detail" click without a selection.
+## Row fields are uppercase
 
-### Master-detail with navigation
+Inside the table's template the cells bind `{TITLE}`, `{AUTHOR}`, `{PRICE}` —
+uppercase, and relative to the row, so they take no `c.bind`. Component names
+are stored lowercase, as the transpiler does, and appear uppercase in the model.
 
-Extension — navigate to the detail app on click:
+## `cds.ql` is the whole data layer
+
+There is no cap2UI5 data API. You use exactly what a CAP handler uses, with the
+same tagged templates and therefore the same parameterization:
 
 ```js
-} else if (client.check_on_event("ITEM_PRESS")) {
-  const sel = this.t_tab.find((r) => r.selected);
-  if (sel) {
-    const detail = new my_detail();
-    detail.parent_id = sel.title;     // simple "params" pattern
-    client.nav_app_call(detail);
-  }
-}
+await SELECT.from(Books).where`title like ${"%" + this.search + "%"}`
 ```
 
-In `my_detail.js`:
+The `${…}` is a bound parameter, not string concatenation.
 
-```js
-class my_detail extends z2ui5_if_app {
+## Both directions, measured
 
-  parent_id = "";   // set by the caller
-  payload   = null;
+`coexistence.test.mjs` drives an ordinary OData service beside this app and
+asserts:
 
-  async main(client) {
-    if (client.check_on_init()) {
-      this.payload = await this.load_payload(this.parent_id);
-      this.render(client);
-    }
-  }
-}
-```
+- a row the app writes through `INSERT` is there for the OData client **at
+  once** — same transaction, same database;
+- a row POSTed through OData is found by the app's next `SEARCH`;
+- `cap2ui5.Drafts` is **not** reachable through that service — 404, and absent
+  from `$metadata`.
+
+That last one is asserted rather than assumed: session state reachable through
+somebody's OData service would be the worst kind of surprise.
+
+## A detail screen
+
+For a second screen with its own state, call another app rather than growing
+this one — see [Navigation](../guide/navigation). The callee's result comes back
+through `c.prevApp`.
 
-Because apps are **classes**, you simply pass parameters as fields. The caller sets them before `nav_app_call`, the callee reads them in `check_on_init`.
+## Next
 
-→ Continue with [**External OData**](./external-odata).
+- [**Selection Screen**](./selection-screen) — a filter form
+- [**Data Binding**](../guide/data-binding) — tables, structures, nesting
+- [**Navigation**](../guide/navigation) — the detail screen
diff --git a/docs/examples/selection-screen.md b/docs/examples/selection-screen.md
index 1d57cde..8422e70 100644
--- a/docs/examples/selection-screen.md
+++ b/docs/examples/selection-screen.md
@@ -1,216 +1,101 @@
 # Selection Screen
 
-A classic input mask with combobox, DatePicker, checkbox, switch — comparable to an ABAP `SELECTION-SCREEN`. Shows the pattern for **structured app fields** (`s_screen` as a container) and how you bind sub-paths _within_ a structure.
+A filter form over a CDS entity: a few inputs, a Go button, a result table.
+The classic internal-tool shape, and the one cap2UI5 is best at.
 
-## Code
+::: info Built from tested parts, assembled here
+Every piece below — bound fields, `t.table`, `cds.ql`, the render branch — is
+exercised in the repository's test suite. This particular assembly is
+illustrative rather than a file you will find there; the shipped app it is
+closest to is [`books.js`](./list).
+:::
 
 ```js
-// srv/app/selection_screen.js
-const z2ui5_if_app              = require("abap2UI5/z2ui5_if_app");
-const z2ui5_cl_ui5_view_builder = require("abap2UI5/z2ui5_cl_ui5_view_builder");
-
-class selection_screen extends z2ui5_if_app {
-
-  s_screen = {
-    check_is_active: false,
-    colour:          "",
-    combo_key:       "",
-    segment_key:     "",
-    date:            "",
-    date_time:       "",
-    time_start:      "",
-    time_end:        "",
-    check_switch_01: false,
-    check_switch_02: false,
-  };
-
-  t_suggestions = [];
-  t_combo       = [];
-
-  async main(client) {
-
-    if (client.check_on_init()) {
-      this.on_init();
-      this.render(client);
-      return;
+// srv/apps/orders.js
+const cds = require("@sap/cds");
+const { SELECT } = cds.ql;
+const { defineApp, t } = require("cap2ui5");
+
+defineApp("ZCL_ORDERS", class {
+  customer = "";
+  minTotal = 0;
+  onlyOpen = false;
+  rows     = t.table({ ID: 0, customer: "", total: t.packed(11, 2), open: false });
+  hits     = 0;
+
+  async main(c) {
+    if (c.eventName === "GO") {
+      const { Orders } = cds.entities("my.shop");
+      let q = SELECT.from(Orders);
+      if (this.customer) q = q.where`customer like ${"%" + this.customer + "%"}`;
+      if (this.minTotal) q = q.and`total >= ${this.minTotal}`;
+      if (this.onlyOpen) q = q.and`open = ${true}`;
+
+      this.rows = await q;
+      this.hits = this.rows.length;
+      c.messageToast(`${this.hits} orders`);
     }
 
-    if (client.check_on_event()) {
-      this.on_event(client);
-      this.render(client);
-    }
-  }
-
-  on_init() {
-    this.s_screen = {
-      check_is_active: true,
-      colour:          "BLUE",
-      combo_key:       "GRAY",
-      segment_key:     "GREEN",
-      date:            "2025-12-07",
-      date_time:       "2025-12-23T19:27:20",
-      time_start:      "05:24:00",
-      time_end:        "17:23:57",
-      check_switch_01: false,
-      check_switch_02: false,
-    };
-
-    this.t_suggestions = [
-      { descr: "Green", value: "GREEN" },
-      { descr: "Blue",  value: "BLUE"  },
-      { descr: "Black", value: "BLACK" },
-      { descr: "Gray",  value: "GRAY"  },
-    ];
-
-    this.t_combo = [
-      { key: "BLUE",  text: "blue"  },
-      { key: "GREEN", text: "green" },
-      { key: "BLACK", text: "black" },
-      { key: "GRAY",  text: "gray"  },
-    ];
-  }
-
-  on_event(client) {
-    switch (client.get().EVENT) {
-      case "BUTTON_SEND":
-        client.message_box_display("Values sent to the server");
-        break;
-      case "BUTTON_CLEAR":
-        for (const k of Object.keys(this.s_screen)) {
-          this.s_screen[k] = typeof this.s_screen[k] === "boolean" ? false : "";
-        }
-        client.message_toast_display("View reset");
-        break;
+    if (c.isDisplay) {
+      c.view(
+        `<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m" xmlns:f="sap.ui.layout.form"` +
+        ` displayBlock="true" height="100%">` +
+        `<Shell><Page title="Orders">` +
+
+        `<f:SimpleForm editable="true" layout="ResponsiveGridLayout">` +
+        `<f:content>` +
+        `<Label text="Customer"/><Input value="${c.bind("customer")}"/>` +
+        `<Label text="Minimum total"/><Input value="${c.bind("minTotal")}"/>` +
+        `<Label text="Open only"/><CheckBox selected="${c.bind("onlyOpen")}"/>` +
+        `</f:content></f:SimpleForm>` +
+
+        `<Button text="Go" type="Emphasized" press="${c.event("GO")}"/>` +
+        `<Text text="${c.bind("hits")} hits"/>` +
+
+        `<Table items="${c.bind("rows")}">` +
+        `<columns><Column><Text text="Customer"/></Column>` +
+        `<Column><Text text="Total"/></Column><Column><Text text="Open"/></Column></columns>` +
+        `<items><ColumnListItem><cells>` +
+        `<Text text="{CUSTOMER}"/><ObjectNumber number="{TOTAL}"/><CheckBox selected="{OPEN}" editable="false"/>` +
+        `</cells></ColumnListItem></items></Table>` +
+
+        `</Page></Shell></mvc:View>`);
     }
   }
+});
+```
 
-  render(client) {
-    const view = z2ui5_cl_ui5_view_builder.factory()
-      .ele({ n: `View`, ns: `mvc` })
-      .a({ n: `xmlns`,      v: `sap.m` })
-      .a({ n: `xmlns:mvc`,  v: `sap.ui.core.mvc` })
-      .a({ n: `xmlns:core`, v: `sap.ui.core` })
-      .a({ n: `xmlns:form`, v: `sap.ui.layout.form` })
-      .a({ n: `xmlns:l`,    v: `sap.ui.layout` });
-
-    const page = view.ele(`Shell`).ele(`Page`)
-      .a({ n: `title`,          v: `abap2UI5 - Selection Screen` })
-      .a({ n: `navButtonPress`, v: client._event_nav_app_leave() })
-      .a({ n: `showNavButton`,  b: client.check_app_prev_stack() });
-
-    // 1) pull out the path to s_screen → manually build sub-paths
-    const screenPath = client._bind_edit(this.s_screen, { path: true });
-    const screen = (k) => `{${screenPath}/${k.toUpperCase()}}`;
-
-    const grid = page.ele({ n: `Grid`, ns: `l` })
-      .a({ n: `defaultSpan`, v: `L6 M12 S12` })
-      .ele({ n: `content`, ns: `l` });
-
-    const sf1 = grid.ele({ n: `SimpleForm`, ns: `form` })
-      .a({ n: `title`,    v: `Input` })
-      .a({ n: `editable`, b: true })
-      .ele({ n: `content`, ns: `form` });
-
-    sf1.tag(`Label`).a({ n: `text`, v: `Color (with suggestions)` });
-    sf1.ele(`Input`)
-      .a({ n: `value`,           v: screen(`colour`) })
-      .a({ n: `placeholder`,     v: `Enter your favorite color` })
-      .a({ n: `suggestionItems`, v: client._bind(this.t_suggestions) })
-      .a({ n: `showSuggestion`,  b: true })
-      .ele(`suggestionItems`)
-      .tag({ n: `ListItem`, ns: `core` })
-      .a({ n: `text`,           v: `{VALUE}` })
-      .a({ n: `additionalText`, v: `{DESCR}` });
-
-    const sf2 = grid.ele({ n: `SimpleForm`, ns: `form` })
-      .a({ n: `title`,    v: `Time Inputs` })
-      .a({ n: `editable`, b: true })
-      .ele({ n: `content`, ns: `form` });
-
-    sf2.tag(`Label`).a({ n: `text`, v: `Date` })
-      .tag(`DatePicker`).a({ n: `value`, v: screen(`date`) })
-      .tag(`Label`).a({ n: `text`, v: `Date / Time` })
-      .tag(`DateTimePicker`).a({ n: `value`, v: screen(`date_time`) })
-      .tag(`Label`).a({ n: `text`, v: `Time Start / End` })
-      .tag(`TimePicker`).a({ n: `value`, v: screen(`time_start`) })
-      .tag(`TimePicker`).a({ n: `value`, v: screen(`time_end`) });
-
-    const content = page.ele({ n: `Grid`, ns: `l` })
-      .a({ n: `defaultSpan`, v: `L12 M12 S12` })
-      .ele({ n: `content`, ns: `l` })
-      .ele({ n: `SimpleForm`, ns: `form` })
-      .a({ n: `title`,    v: `Selection` })
-      .a({ n: `editable`, b: true })
-      .ele({ n: `content`, ns: `form` });
-
-    content.tag(`Label`).a({ n: `text`, v: `Active` })
-      .tag(`CheckBox`)
-      .a({ n: `selected`, v: screen(`check_is_active`) })
-      .a({ n: `text`,     v: `Active` })
-      .a({ n: `enabled`,  b: true });
-
-    content.tag(`Label`).a({ n: `text`, v: `Combo` });
-    content.ele(`ComboBox`)
-      .a({ n: `selectedKey`, v: screen(`combo_key`) })
-      .a({ n: `items`,       v: client._bind(this.t_combo) })
-      .tag({ n: `Item`, ns: `core` })
-      .a({ n: `key`,  v: `{KEY}` })
-      .a({ n: `text`, v: `{TEXT}` });
-
-    content.tag(`Label`).a({ n: `text`, v: `Segmented` });
-    const seg = content.ele(`SegmentedButton`)
-      .a({ n: `selectedKey`, v: screen(`segment_key`) });
-    seg.tag(`SegmentedButtonItem`)
-      .a({ n: `key`, v: `BLUE` }).a({ n: `icon`, v: `sap-icon://accept` }).a({ n: `text`, v: `blue` })
-      .tag(`SegmentedButtonItem`)
-      .a({ n: `key`, v: `GREEN` }).a({ n: `icon`, v: `sap-icon://add-favorite` }).a({ n: `text`, v: `green` })
-      .tag(`SegmentedButtonItem`)
-      .a({ n: `key`, v: `BLACK` }).a({ n: `icon`, v: `sap-icon://attachment` }).a({ n: `text`, v: `black` });
-
-    content.tag(`Label`).a({ n: `text`, v: `Switch 1` })
-      .tag(`Switch`).a({ n: `state`, v: screen(`check_switch_01`) })
-      .tag(`Label`).a({ n: `text`, v: `Switch 2` })
-      .tag(`Switch`).a({ n: `state`, v: screen(`check_switch_02`) });
-
-    const footer = page.ele(`footer`).ele(`OverflowToolbar`);
-    footer.tag(`ToolbarSpacer`);
-    footer.tag(`Button`)
-      .a({ n: `text`,  v: `Clear` })
-      .a({ n: `press`, v: client._event(`BUTTON_CLEAR`) })
-      .a({ n: `type`,  v: `Reject` })
-      .a({ n: `icon`,  v: `sap-icon://delete` });
-    footer.tag(`Button`)
-      .a({ n: `text`,  v: `Send` })
-      .a({ n: `press`, v: client._event(`BUTTON_SEND`) })
-      .a({ n: `type`,  v: `Success` });
-
-    client.view_display(view.stringify());
-  }
-}
+## Why the event branch comes first
 
-module.exports = selection_screen;
-```
+`GO` runs, *then* the render branch runs in the same roundtrip. The order
+matters: the table the view binds is the one the query just produced. Writing
+the render branch first with a `return` would show the user the previous result.
 
-## The sub-path pattern
+## The types the form needs
 
-The most important trick:
+| field | declared as | why |
+|---|---|---|
+| `customer` | `""` | `string` |
+| `minTotal` | `0` | integer. A decimal threshold would be `t.packed(11, 2)` |
+| `onlyOpen` | `false` | `abap_bool`; your code still sees `true`/`false` |
+| `rows` | `t.table({…})` | an empty array carries no type |
 
-```js
-const screenPath = client._bind_edit(this.s_screen, { path: true });
-//                                                   ^^^^^^^^^^^
-//                                                   "give me the bare path,
-//                                                    not wrapped in {...}"
+A `CheckBox` binds `selected`, an `Input` binds `value` — ordinary UI5.
 
-const screen = (k) => `{${screenPath}/${k.toUpperCase()}}`;
-//             screen("colour") === "{/XX/S_SCREEN/COLOUR}"
-```
+## Building the query conditionally
 
-`_bind_edit(this.s_screen)` returns the path to the entire structure object via reference equality. With `{ path: true }` you get it unwrapped — and can then append sub-paths yourself. The sub-path is uppercased because model paths are: the framework writes `s_screen` into the model as `S_SCREEN` and maps the delta back onto your lowercase property when the roundtrip returns.
+`cds.ql` composes, so the filter is plain JavaScript: add a `where` only for the
+fields the user filled. The `${…}` holes are **bound parameters**, so a customer
+name containing a quote is a value and not a syntax error.
 
-This saves you from **binding every sub-field individually** — a single lookup, many bindings.
+## Keeping the criteria
 
-## Two `BUTTON_*` events in a switch
+They persist for free. `customer`, `minTotal` and `onlyOpen` are declared
+fields, so they are in the draft: come back to the app after a navigation and
+the form is still filled in — including after a server restart.
 
-In `on_event()` the pattern shows up when you have **many** events — a `switch` over `client.get().EVENT` is usually more readable than ten `if (check_on_event(...))` blocks.
+## Next
 
-→ Continue to [**List & Detail**](./list).
+- [**List & Detail**](./list) — the tested version of the table half
+- [**Data Binding**](../guide/data-binding) — the type table in full
+- [**Navigation**](../guide/navigation) — a value help for the customer field
diff --git a/docs/examples/static-xml-view.md b/docs/examples/static-xml-view.md
index ceb3e1a..80c3435 100644
--- a/docs/examples/static-xml-view.md
+++ b/docs/examples/static-xml-view.md
@@ -1,107 +1,91 @@
-# Static XML View
+# A View From a File
 
-If you already have a UI5 view **as an XML file** — exported from a designer, copied from an existing app, or because your designer prefers reading XML over JS — you can use it 1:1 without going through the view builder.
+The view is a string, which means it does not have to be a template literal in
+the middle of your logic. For a large screen, keep the XML in its own file and
+read it once.
 
-## Code
+::: info Illustrative
+`c.view()` taking any string is the tested part. Loading it from disk is
+ordinary Node — shown here because it is the question that comes up as soon as a
+view passes a screenful.
+:::
 
-```js
-// srv/app/read_view.js
-const fs                = require("fs");
-const path              = require("path");
-const z2ui5_if_app      = require("abap2UI5/z2ui5_if_app");
-
-class read_view extends z2ui5_if_app {
-
-  async main(client) {
-    const viewPath    = path.join(__dirname, "View1.view.xml");
-    const viewContent = fs.readFileSync(viewPath, "utf8");
-    client.view_display(viewContent);
-  }
-}
-
-module.exports = read_view;
-```
-
-## `View1.view.xml`
-
-Place the file right next to your app class (`srv/app/View1.view.xml`):
+## The view
 
 ```xml
-<mvc:View
-    controllerName="Quickstart.App"
-    displayBlock="true"
-    xmlns:mvc="sap.ui.core.mvc"
-    xmlns:l="sap.ui.layout"
-    xmlns:core="sap.ui.core"
-    xmlns:tnt="sap.tnt"
-    xmlns="sap.m">
-  <App id="app">
-    <Page title="Create Enterprise-ready Web Apps with Ease">
-      <l:BlockLayout background="Light">
-        <l:BlockLayoutRow>
-          <l:BlockLayoutCell>
-            <core:Icon color="#1873B4" src="sap-icon://sap-ui5" size="5rem" class="sapUiSmallMarginBottom" width="100%"/>
-            <Title level="H1" titleStyle="H1" text="This is UI5!" width="100%" textAlign="Center"/>
-          </l:BlockLayoutCell>
-        </l:BlockLayoutRow>
-        <l:BlockLayoutRow>
-          <l:BlockLayoutCell>
-            <FlexBox items="{/features}" justifyContent="Center" wrap="Wrap">
-              <tnt:InfoLabel text="{}" class="sapUiSmallMarginTop sapUiSmallMarginEnd"/>
-            </FlexBox>
-          </l:BlockLayoutCell>
-        </l:BlockLayoutRow>
-      </l:BlockLayout>
+<!-- srv/apps/views/orders.xml -->
+<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m" displayBlock="true" height="100%">
+  <Shell>
+    <Page title="Orders">
+      <Input value="{CUSTOMER_PATH}"/>
+      <Button text="Go" press="{GO_HANDLER}"/>
+      <Table items="{ROWS_PATH}">
+        <columns><Column><Text text="Customer"/></Column></columns>
+        <items><ColumnListItem><cells><Text text="{CUSTOMER}"/></cells></ColumnListItem></items>
+      </Table>
     </Page>
-  </App>
+  </Shell>
 </mvc:View>
 ```
 
-## When does this make sense?
-
-✅ **Migrating an existing classical UI5 app.** You want to switch it from "three-layer OData CRUD" to cap2UI5. You can leave the XML views in place for now and only move the controller logic into `main()`.
-✅ **Wireframe designs from a WYSIWYG tool.** If your UX team works with [SAP Build](https://sap.com/products/build.html) or a similar designer, you'll have XML output.
-✅ **Complex static layouts** where the builder gets cumbersome (e.g. deeply nested BlockLayouts with many custom classes).
+Two kinds of placeholder are in there, and the difference matters:
 
-## When not?
+- `{CUSTOMER}` inside the table's template is a **UI5 row binding**. It is
+  relative to the row, needs nothing from you, and must survive to the browser
+  untouched.
+- `{CUSTOMER_PATH}` and `{GO_HANDLER}` are **yours** — they stand where
+  `c.bind()` and `c.event()` go.
 
-❌ When you have **dynamic** UIs (showing/hiding fields based on state). In the JS builder that's `if`/`switch`; in XML you need `visible="{= ...}"` expressions or custom data.
-❌ When you have to **rebuild your form per user input**. The builder thrives on the fact that you reassemble a tree in `main()`.
+## The app
 
-## Bindings in static XML
-
-The XML view may use any bindings the view builder would generate:
-
-```xml
-<Input value="{/XX/username}" />
-<Text  text="{/customer_count}" />
-<Button text="Save" press=".eB([['SAVE','','','']])" />
+```js
+const fs   = require("node:fs");
+const path = require("node:path");
+const { defineApp, t } = require("cap2ui5");
+
+// read once at load, not per roundtrip
+const XML = fs.readFileSync(path.join(__dirname, "views", "orders.xml"), "utf8");
+
+defineApp("ZCL_ORDERS_FILE", class {
+  customer = "";
+  rows     = t.table({ customer: "" });
+
+  main(c) {
+    if (c.isDisplay) {
+      c.view(XML
+        .replace("{CUSTOMER_PATH}", c.bind("customer"))
+        .replace("{GO_HANDLER}",    c.event("GO")));
+      return;
+    }
+    if (c.eventName === "GO") { /* … */ }
+  }
+});
 ```
 
-That is brittle, however — the `.eB(...)` strings are the internal wire format that the builder normally generates for you via `client._event(...)`. **My tip:** even in the static-view case, fetch the event strings from `client._event()` and inject them into the view via model bindings, e.g. like this:
+`String.replace` with a string pattern replaces the **first** occurrence, which
+is what you want for a placeholder that appears once. For one that repeats, use
+`replaceAll` — and pick placeholder names that cannot collide with a UI5 binding
+(`{GO_HANDLER}`, not `{GO}`).
 
-```js
-const eventSave = client._event("SAVE");
-client.view_display(viewContent.replace("__EVENT_SAVE__", eventSave));
-```
+## Why read it at load
 
-This keeps the wire format encapsulated and you stay safe across updates.
+`readFileSync` at module scope runs once, when the plugin imports the file.
+Reading per roundtrip would put a synchronous disk read on every click for a
+file that never changes.
 
-## Hybrid: view builder + static XML snippets
+While developing, `cds watch` restarts on a change to the `.js` — but **not** on
+a change to the `.xml`, since nothing imports it. Touch the app file, or read
+inside `main` until you are done.
 
-Sometimes you only want a **piece** of the view to come from a file — a static footer, say. The builder has no "embed this XML here" method: it renders a tree of elements it built itself, and `stringify()` is the only way out of it. So the seam is the string, not the builder:
+## When to bother
 
-```js
-// … build the dynamic part with the builder, and mark the seam with an
-// element you can find again in the output:
-page.tag(`Text`).a({ n: `text`, v: `__FOOTER__` });
-
-const footer = fs.readFileSync(path.join(__dirname, "footer.xml"), "utf8");
-client.view_display(
-  view.stringify().replace(`<Text text="__FOOTER__"/>`, footer),
-);
-```
+| | |
+|---|---|
+| a screenful of XML | keep it inline. The template literal is easier to follow |
+| a large form, or a view a designer edits | a file, with your editor's XML support |
+| a view assembled from repeated pieces | neither — build it with functions, see [Views](../guide/views) |
 
-Build the dynamic part with the builder, put a placeholder element where the static part goes, and splice the file in before `view_display`. Nothing in the framework has to know the difference — the frontend renderer sees one XML string either way.
+## Next
 
-→ You're now through all the examples. Continue to the [**API reference**](../api/client) for full method listings.
+- [**Views**](../guide/views) — composing XML in JavaScript
+- [**Selection Screen**](./selection-screen) — a form inline
diff --git a/docs/guide/data-binding.md b/docs/guide/data-binding.md
index 3cfbbc7..2a927c1 100644
--- a/docs/guide/data-binding.md
+++ b/docs/guide/data-binding.md
@@ -1,214 +1,142 @@
 # Data Binding
 
-Data binding is the trick that lets cap2UI5 work without model boilerplate. This page explains **how it works** and **when you use what**.
-
-## The two bindings
-
-```js
-client._bind(value)        // → "{/PATH}"     one-way (read-only on the frontend)
-client._bind_edit(value)   // → "{/XX/PATH}"  two-way (frontend can write back)
-```
-
-Paths come back **uppercased** — `this.username` binds as `/XX/USERNAME`. That is the abap2UI5 wire format (ABAP component names are uppercase), and the delta is mapped back onto your lowercase property when the roundtrip returns. Write literal, relative paths uppercase and they will line up.
-
-Both methods take a **value**, look in `client.oApp` (= your app instance) to find **which property that value is**, and return a UI5 binding path.
+A field of your class is a bound model field. `c.bind("name")` gives you the
+binding path to put in the view; the browser sends the value back, and the
+framework applies it to the instance before your `main` runs.
 
 ```js
-class my_app extends z2ui5_if_app {
+defineApp("ZCL_HELLO", class {
+  name = "";
 
-  username = "Alice";
-
-  async main(client) {
-    const path1 = client._bind(this.username);       // → "{/USERNAME}"
-    const path2 = client._bind_edit(this.username);  // → "{/XX/USERNAME}"
+  main(c) {
+    if (c.isDisplay) {
+      c.view(`<Input value="${c.bind("name")}"/>`);
+      return;
+    }
+    if (c.eventName === "GO") c.messageBox(`Hello ${this.name}`);   // already applied
   }
-}
+});
 ```
 
-## Reference equality
+No model, no manifest, no `setProperty`. Binding is two-way; there is no
+separate "read-only bind".
 
-The lookup is **by reference equality**: `Object.is(this.username, value)`. For primitive values (`string`, `number`, `boolean`) this works because the same primitive value identity holds — as long as you pass the value out of the app instance:
+## `c.bind` takes a field NAME
 
 ```js
-client._bind_edit(this.username);          // ✓ finds "username"
-client._bind_edit("Alice");                // ✗ also matches (value is "Alice"),
-                                           //   BUT: the engine iterates all fields
-                                           //   and the FIRST one with value "Alice" wins
-                                           //   → unreliable
+c.bind("name")     // ✅
+c.bind(this.name)  // ❌ — an empty string, and every field is one
 ```
 
-For **objects and arrays** it is unambiguous:
+A name is used rather than a value because a value cannot identify a field: two
+empty strings are indistinguishable. A name that is not a bindable field throws
+and lists the ones that are:
 
-```js
-this.users = [...];
-client._bind_edit(this.users);             // ✓ finds "users" (array identity)
 ```
-
-::: warning Multiple fields with the same default
-If two fields both have `""` as the initial value, the engine doesn't know which one you mean:
-
-```js
-class app extends z2ui5_if_app {
-  first_name = "";
-  last_name  = "";
-  /* ... */
-  client._bind_edit(this.last_name);       // → matches 'first_name'!
-}
+c.bind("nmae"): not a bindable field of this app — known: name, count, books
 ```
 
-**Solution:** set different defaults (even a single space is enough), or _explicitly_ pass the path:
-
-```js
-client._bind_edit(this.last_name, { path: "last_name" });
-```
-:::
+## The types
 
-## What happens on the wire?
+A field's ABAP type comes from its **initial value**. The mapping is narrow on
+purpose and refuses rather than guesses:
 
-A cap2UI5 response contains a `MODEL` object that is set as the **default model** in the frontend's JSONModel. It has two areas:
+| you write | you get |
+|---|---|
+| `name = ""` | `string` |
+| `count = 0` | integer (`I`) |
+| `ratio = 1.5` | float (`F`) |
+| `flag = false` | `abap_bool`, and the app sees `true`/`false` |
+| `price = t.packed(9, 2)` | packed decimal — **declare this one** |
+| `code = t.char(3)` | fixed-width character |
+| `addr = { street: "", zip: 0 }` | a structure |
+| `rows = t.table({ sku: "", qty: 0 })` | a table whose row is that structure |
+
+Numbers are the real ambiguity — ABAP has `I`, `P` and `F` and they render with
+different decimals — so an integer becomes `I`, a fractional literal `F`, and a
+decimal amount has to say so with `t.packed()`. Guessing would produce views
+with the wrong number of decimals and nothing to point at.
+
+## Tables
 
-```json
-{
-  "MODEL": {
-    "USERS": [/* ... */],          // ← one-way bindings (top level)
-    "TITLE": "Hello",
-    "XX": {
-      "USERNAME": "Alice",         // ← two-way bindings (XX namespace)
-      "IS_ACTIVE": true
+```js
+defineApp("ZCL_BOOKS", class {
+  books = t.table({ ID: 0, title: "", price: t.packed(9, 2) });
+
+  async main(c) {
+    if (c.isDisplay) {
+      c.view(
+        `<Table items="${c.bind("books")}">` +
+        `<columns><Column><Text text="Title"/></Column><Column><Text text="Price"/></Column></columns>` +
+        `<items><ColumnListItem><cells>` +
+        `<Text text="{TITLE}"/><ObjectNumber number="{PRICE}"/>` +
+        `</cells></ColumnListItem></items></Table>`);
+      return;
+    }
+    if (c.eventName === "SEARCH") {
+      this.books = await SELECT.from(cds.entities("my.bookshop").Books);
     }
   }
-}
+});
 ```
 
-When the user types in an `Input`, UI5 writes the value back to `/XX/USERNAME`. On the next roundtrip the frontend sends an **XX delta** with all changed values to the server. The server engine (`z2ui5_cl_ui5_srv_model.main_json_to_attri`) applies this delta to the deserialized app instance **before** `main()` is called — meaning: in `main()`, `this.username` is already the new value the user typed.
+Two things to note:
 
-## Options
+- **the row fields are UPPERCASE in the view** — `{TITLE}`, `{PRICE}`. Component
+  names are stored lowercase, as the transpiler does, and appear uppercase in
+  the model;
+- **assign the whole array.** `this.books = await SELECT…` replaces the table;
+  the plugin rebuilds the rows. Pushing into the array you read back does not
+  write through.
 
-```js
-client._bind_edit(value, opts);
-```
-
-| Option | Meaning |
-|---|---|
-| `path: true` | returns the **raw path** (`"/XX/USERNAME"`), not wrapped in `{...}` |
-| `path: "myField"` | skips the reference lookup and uses the given path |
-| `name: "s_screen-city"` | resolves a member *inside* a bound structure by name |
-| `custom_mapper: ".fmt"` | formatter function name → output: `{path: '...', formatter: '.fmt'}` |
-| `custom_mapper_back: ".fmtBack"` | reverse formatter (two-way only) |
-| `view: "POPUP"` | target view — rarely needed |
+## Structures, and nesting
 
-Examples:
+Structures nest, and tables nest inside them:
 
 ```js
-// raw path for relative bindings (table items)
-const tabPath = client._bind_edit(this.users, { path: true });
-// "/XX/USERS"
-
-// inside the table item structure, fields are relative:
-const tab = page.ele(`Table`).a({ n: `items`, v: client._bind_edit(this.users) });
-tab.ele(`items`).ele(`ColumnListItem`).ele(`cells`)
-  .tag(`Text`).a({ n: `text`, v: `{NAME}` });   // ← '{NAME}' relative to the item
+order = {
+  id: "",
+  customer: { name: "", city: "" },
+  lines: t.table({ sku: "", qty: 0, price: t.packed(9, 2) }),
+};
 ```
 
-## Local bindings
-
-Sometimes you want a view-internal variable that should _not_ live as an app property:
+The model carries `ORDER.CUSTOMER.CITY` and `ORDER.LINES[].PRICE`, decimals
+included, through the draft and back. Read the whole tree as plain values:
 
 ```js
-client._bind_local(initialValue);   // → "{/__local_3}"  (the one path that is not uppercased)
+const city = this.order.customer.city;
+this.order = { ...this.order, customer: { name: "Ada", city: "London" } };
 ```
 
-Creates an anonymous path with the given initial value. Useful for visual helper state that the server never needs.
-
-## Reacting to clicks: `_event`
+::: info This was documented as unsupported for a while. It was not.
+Three pages said nested state could not be done. It could — the limitation was
+one guard in the plugin's own type derivation, written when only scalars had
+been tried. "Unsupported" must say whose limitation it is.
+:::
 
-Bindings are one half; the other is `_event`:
+The depth limit is **8**, and it is a cycle guard rather than a judgement: an
+object containing itself would otherwise recurse until the stack goes. A field
+that cannot be typed is reported **by its path** and left out:
 
-```js
-page.tag(`Button`)
-  .a({ n: `text`,  v: `Save` })
-  .a({ n: `press`, v: client._event(`BUTTON_SAVE`) });
 ```
-
-`_event(name)` builds the UI5 press handler string that sends the event back to the server via the roundtrip. The actual `BUTTON_SAVE` then shows up in `client.get().EVENT`.
-
-→ More under [Events](./events).
-
-## Frontend-only events: `_event_client`
-
-When the event should run **only on the frontend** (no server roundtrip):
-
-```js
-page.tag(`Button`).a({
-  n: `press`,
-  v: client._event_client(client.cs_event.OPEN_NEW_TAB, [`https://sap.com`]),
-});
+order.self.self.self.self.self.self.self.a is nested more than 8 levels deep.
 ```
 
-The frontend handler dispatches it locally. Very similar to `client.open_new_tab()`, which terminates the roundtrip — the difference: `_event_client` does it _on a click_, `open_new_tab` does it _as a side effect of this roundtrip_.
+## Fields with no type
 
-→ List of all `cs_event` constants in [API: client](../api/client).
+`null`, `undefined` and `[]` carry no type. Such a field is left out of the
+model and **named in a warning** rather than silently dropped:
 
-## Example: complete form
+```
+[defineApp] ZCL_ORDER: these fields are NOT part of the model —
+  total has no ABAP type: null, undefined and an empty array carry none.
+```
 
-```js
-class profile extends z2ui5_if_app {
-
-  first_name = " ";    // ← different defaults so the lookup is unambiguous
-  last_name  = "  ";
-  email      = "";
-  active     = false;
-  validation = { email_state: "None", email_text: "" };
-
-  async main(client) {
-
-    if (client.check_on_init()) this.render(client);
-
-    if (client.check_on_event("SAVE")) {
-      if (!this.email.includes("@")) {
-        this.validation.email_state = "Error";
-        this.validation.email_text  = "Please enter a valid email";
-      } else {
-        client.message_toast_display("Saved");
-      }
-      this.render(client);
-    }
-  }
+Give it an initial value, or declare it with `t.table(…)` / `t.packed(…)`.
 
-  render(client) {
-    const view = z2ui5_cl_ui5_view_builder.factory()
-      .ele({ n: `View`, ns: `mvc` })
-      .a({ n: `xmlns`,      v: `sap.m` })
-      .a({ n: `xmlns:mvc`,  v: `sap.ui.core.mvc` })
-      .a({ n: `xmlns:form`, v: `sap.ui.layout.form` });
-
-    const form = view.ele(`Shell`).ele(`Page`)
-      .a({ n: `title`, v: `Profile` })
-      .ele({ n: `SimpleForm`, ns: `form` })
-      .a({ n: `editable`, b: true })
-      .ele({ n: `content`, ns: `form` });
-
-    const validation = client._bind(this.validation, { path: true });
-
-    form.tag(`Label`).a({ n: `text`, v: `First name` })
-      .tag(`Input`).a({ n: `value`, v: client._bind_edit(this.first_name) })
-      .tag(`Label`).a({ n: `text`, v: `Last name` })
-      .tag(`Input`).a({ n: `value`, v: client._bind_edit(this.last_name) })
-      .tag(`Label`).a({ n: `text`, v: `Email` })
-      .tag(`Input`)
-      .a({ n: `value`,          v: client._bind_edit(this.email) })
-      .a({ n: `valueState`,     v: `{${validation}/EMAIL_STATE}` })
-      .a({ n: `valueStateText`, v: `{${validation}/EMAIL_TEXT}` })
-      .tag(`Label`).a({ n: `text`, v: `Active` })
-      .tag(`CheckBox`).a({ n: `selected`, v: client._bind_edit(this.active) })
-      .tag(`Button`)
-      .a({ n: `text`,  v: `Save` })
-      .a({ n: `press`, v: client._event(`SAVE`) })
-      .a({ n: `type`,  v: `Emphasized` });
-
-    client.view_display(view.stringify());
-  }
-}
-```
+## Next
 
-→ Continue with [**Events**](./events).
+- [**Events**](./events) — `c.event` and its arguments
+- [**View Builder**](./views) — what goes inside `c.view`
+- [**Persistence**](./persistence) — what survives the roundtrip
diff --git a/docs/guide/devtools.md b/docs/guide/devtools.md
index ed818e3..1d63f83 100644
--- a/docs/guide/devtools.md
+++ b/docs/guide/devtools.md
@@ -58,12 +58,11 @@ has it.
 
 ## Turning it off
 
-There is no switch. The tools are part of the shipped webapp, and the webapp
-is a generated artifact mirrored from upstream abap2UI5 — patching it out
-locally would be overwritten by the next sync. If you must remove them, do it
-in the pipeline: the frontend is assembled by
-[builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js) (see
-[Ecosystem](./ecosystem)).
+There is no switch. The tools are part of abap2UI5's own UI5 shell, which
+cap2UI5 serves straight out of `@abap2ui5/runtime` — patching it locally would
+be undone by the next `npm update`. If you need them gone, that is a request
+for [abap2UI5](https://github.com/abap2UI5/abap2UI5/issues) rather than for
+this project (see [Ecosystem](./ecosystem#where-to-report)).
 
 Worth knowing before you try: the tools expose nothing the browser could not
 already read. The payloads they show are this session's own requests and
diff --git a/docs/guide/ecosystem.md b/docs/guide/ecosystem.md
index 1d24ead..cf548e3 100644
--- a/docs/guide/ecosystem.md
+++ b/docs/guide/ecosystem.md
@@ -1,79 +1,65 @@
-# The cap2UI5 Ecosystem
+# The Ecosystem
 
-cap2UI5 is not one repository. It is a chain of six — plus the upstream project
-they all descend from — and almost every file you can see is generated by the
-one before it. That matters the moment you want to change something or report a
-bug: editing the obvious place usually means editing a build output, and your
-change disappears on the next sync.
+cap2UI5 is a small project sitting on a larger one. Knowing which repository
+owns what saves time when something breaks.
 
 ## The repositories
 
-The first row is the upstream project; the six below it are the cap2UI5 chain.
-
-| Repository | What it is | Hand-written? |
-|---|---|---|
-| [abap2UI5/abap2UI5](https://github.com/abap2UI5/abap2UI5) + [abap2UI5/samples](https://github.com/abap2UI5/samples) | the upstream ABAP original and its sample catalogue | yes — but that is a different project |
-| [builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js) | mirrors upstream, transpiles ABAP→JS, assembles the platform-neutral core package `abap2UI5` | `src/`, `scripts/`, `test/` |
-| [builder-cap2UI5](https://github.com/cap2UI5/builder-cap2UI5) | assembles the CAP app from its own `src/` plus the mirrored core, then publishes it | `src/`, `scripts/`, `test/` |
-| [cap2UI5](https://github.com/cap2UI5/cap2UI5) | **the deployable CAP app** — what you clone to run it | no, except `.github/` |
-| [builder-cap2UI5-web](https://github.com/cap2UI5/builder-cap2UI5-web) | bundles the app into a static, backend-less site | yes |
-| [web-cap2UI5-build](https://github.com/cap2UI5/web-cap2UI5-build) | the built [playground](https://cap2ui5.github.io/web-cap2UI5-build/) | no |
-| [docs](https://github.com/cap2UI5/docs) | this site | yes |
-
-## How a change flows through
-
-```
-abap2UI5 (ABAP)
-     │  nightly mirror + transpile
-     ▼
-builder-abap2UI5-js ── core package `abap2UI5` ──┐
-                                                 │ mirror
-                                                 ▼
-                                        builder-cap2UI5
-                                                 │ assemble + publish 1:1
-                                                 ▼
-                                            cap2UI5  ← the app you deploy
-                                                 │ trigger
-                                                 ▼
-                                       builder-cap2UI5-web
-                                                 │ esbuild bundle
-                                                 ▼
-                                        web-cap2UI5-build → GitHub Pages
-```
-
-Each hop is a scheduled GitHub Actions workflow. A change in upstream ABAP
-reaches the playground without anyone touching a keyboard — and so does a
-mistake, which is why every hop has a gate (transpile parse gate, load gate,
-unit-test ratchet, app test suite, browser smoke test).
-
-## Where do I report this? {#where-to-report}
-
-| The problem | The repository |
+| | |
 |---|---|
-| an app behaves wrong, a control renders wrong | [abap2UI5](https://github.com/abap2UI5/abap2UI5) if it reproduces there too, otherwise [builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js) |
-| a transpiled class is wrong or missing | [builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js) |
-| the CAP app: server wiring, service, database, deployment descriptors | [builder-cap2UI5](https://github.com/cap2UI5/builder-cap2UI5) (**not** the app repo — it is overwritten) |
-| the playground is broken or stale | [builder-cap2UI5-web](https://github.com/cap2UI5/builder-cap2UI5-web) |
-| these docs are wrong | [docs](https://github.com/cap2UI5/docs) |
+| [**abap2UI5/abap2UI5**](https://github.com/abap2UI5/abap2UI5) | the framework itself: the ABAP sources and the UI5 shell. Everything cap2UI5 runs comes from here |
+| [**cap2UI5/cap2UI5**](https://github.com/cap2UI5/cap2UI5) | the plugin. `plugin/` is the npm package `cap2ui5`; `examples/bookshop` is a CAP project using it; `runtime/` is where `@abap2ui5/runtime` is assembled until it is published |
+| [**cap2UI5/docs**](https://github.com/cap2UI5/docs) | this site |
+| [**cap2UI5/builder-abap2UI5-js**](https://github.com/cap2UI5/builder-abap2UI5-js) | the conformance gate and the ADRs that led to the current design. Historical: the build pipelines it ran are retired |
 
-Rule of thumb: if the file you want to change lives in a repository that says
-"generated" above, the fix belongs one hop upstream. Each generated repo's
-`AGENTS.md` names its source explicitly.
+## The packages
 
-## What this means for your own apps
+| | |
+|---|---|
+| `cap2ui5` | the plugin — ~485 lines of code. Mounts the route, implements the draft store over a CDS entity, turns a JS class into something the runtime can call |
+| `@abap2ui5/runtime` | abap2UI5: upstream's ABAP, downported and transpiled over open-abap, plus the UI5 shell — backend and frontend from one commit |
+
+Neither is on npm yet; both are published from a release that has not been cut.
+See the box in the [Quickstart](./getting-started).
+
+## What the plugin does and does not own
+
+**Owns:** the CAP route and its authentication guard, `cap2ui5.Drafts` and the
+draft store over it, `defineApp` and the `c` facade, the two ABI gates.
+
+**Does not own:** views, the wire format, the model service, the lifecycle, the
+UI5 shell, the frontend actions — all upstream's, running unmodified. The plugin
+deliberately contains no framework logic, which is what makes drift impossible.
+
+## Where to report it {#where-to-report}
+
+Decide by **which layer produced the symptom**:
+
+| symptom | where |
+|---|---|
+| the route 401s, the draft is not found, an app is not registered, a `c.…` member misbehaves | [cap2UI5/cap2UI5](https://github.com/cap2UI5/cap2UI5/issues) |
+| a control renders wrong, an event does not fire, the frontend throws, a framework method misbehaves | [abap2UI5/abap2UI5](https://github.com/abap2UI5/abap2UI5/issues) — it is the same bug an ABAP user would see |
+| a page here is wrong or out of date | [cap2UI5/docs](https://github.com/cap2UI5/docs/issues) |
+
+Unsure? Open it on cap2UI5 and say what you saw. Moving it costs a comment.
+
+::: tip This routing is not bureaucracy
+A framework bug fixed upstream reaches every ABAP user too, and comes back here
+on the next runtime bump. The codepage bug this project found was exactly that:
+discovered on a transpiled Node runtime, fixed at the source, and now fixed for
+everyone.
+:::
 
-Everything the pipeline owns is overwritten. Your code must live somewhere it
-does not reach:
+## abap2UI5's own ecosystem
 
-- **`srv/app/`** in the app repo — but note this folder ships from
-  builder-cap2UI5 and is replaced on every publish, so it suits demos, not
-  real projects.
-- **an external folder** registered at startup — the safe option:
+The [samples](https://github.com/abap2UI5/samples),
+[samples-controls](https://github.com/abap2UI5/samples-controls) and the
+documentation at [abap2ui5.org](https://www.abap2ui5.org) are ABAP, but the
+framework calls are the same ones. The
+[translation table](./migration-from-abap2ui5#the-translation-table) maps them
+onto the JavaScript facade, so a sample there is still a worked example here.
 
-  ```js
-  require("abap2UI5/register-apps")(__dirname + "/my-apps");
-  // or:  Z2UI5_APP_DIRS=/abs/path/to/my-apps cds-serve
-  ```
+## Next
 
-- **never** `core/` or `core/srv/app/samples/` — both are replaced wholesale
-  by the nightly sync.
+- [**Where cap2UI5 Comes From**](./where-it-comes-from) — why it is a host and not a port
+- [**Architecture**](../reference/architecture) — the layers in one picture
diff --git a/docs/guide/events.md b/docs/guide/events.md
index f770324..934aa0e 100644
--- a/docs/guide/events.md
+++ b/docs/guide/events.md
@@ -1,163 +1,96 @@
 # Events
 
-Events are **the only way for the frontend to tell the server something** (besides the silent XX delta for two-way bindings). When the user clicks, swipes, makes a selection, or hits Enter, the frontend sends an event object to the server in the roundtrip.
-
-## Backend events: `_event(name)`
+`c.event("NAME")` produces the wire string a control's event attribute needs.
+The next roundtrip answers with `c.eventName === "NAME"`.
 
 ```js
-view.Button({
-  text:  "Save",
-  press: client._event("SAVE")
+defineApp("ZCL_HELLO", class {
+  name  = "";
+  count = 0;
+
+  main(c) {
+    if (c.isDisplay) {
+      c.view(
+        `<Input value="${c.bind("name")}"/>` +
+        `<Button text="Go" press="${c.event("GO")}"/>`);
+      return;
+    }
+
+    if (c.eventName === "GO") {
+      this.count++;
+      c.messageToast(`Hello ${this.name}, click ${this.count}`);
+    }
+  }
 });
 ```
 
-On the server side you receive the event in the next `main()` round:
-
-```js
-if (client.check_on_event("SAVE")) {
-  /* ... */
-}
-```
-
-`_event(name)` internally builds a UI5 binding string of the form:
+`c.eventName` is `""` on an app start, so `if (c.eventName === "GO")` is safe
+without a guard.
 
-```
-.eB([['SAVE','','','']],...)
-```
+## Arguments — how two buttons share one event
 
-The frontend handler `eB` (= "event Backend") calls the roundtrip endpoint with the event name and optional arguments.
-
-## Event arguments
+A handler cannot know which control fired unless the wire carries it. That is
+what the second parameter is for:
 
 ```js
-.Button({ press: client._event("ITEM_DELETE", [item.id, item.kind]) })
-```
+c.view(
+  `<Button text="red"  press="${c.event("TAKE", ["red"])}"/>` +
+  `<Button text="blue" press="${c.event("TAKE", ["blue"])}"/>`);
 
-Server side:
-
-```js
-if (client.check_on_event("ITEM_DELETE")) {
-  const id   = client.get().T_EVENT_ARG[0];
-  const kind = client.get().T_EVENT_ARG[1];
+// next roundtrip
+if (c.eventName === "TAKE") {
+  this.colour = c.eventArg(1);        // "red" or "blue"
 }
 ```
 
-Or (if you prefer the ABAP pattern):
-
-```js
-const id   = client.get_event_arg(1);   // 1-based like ABAP
-const kind = client.get_event_arg(2);
-```
-
-Arguments are **always strings** on the wire — the frontend/backend engine doesn't take them apart in a type-safe way.
-
-## Event control flags
-
-Optionally you can pass control flags:
-
-```js
-client._event("SAVE", [], {
-  bypass_busy:      true,    // dispatch event even when the app is busy
-  force_main_model: true     // force binding on the main view model
-});
-```
-
-## Event data (object payload)
+`c.eventArg(i)` is **1-based**, like the ABAP table it reads. The first eight
+arguments are resolved up front; `c.eventArg(9)` throws and tells you to use
+`c.raw` for a longer list.
 
-Sometimes you need **more than just strings**. With the 4th argument of `_event` you can attach arbitrary data:
+::: info This was missing, and the wire tests could not see it
+`c.event` took no arguments for a while, and the test suite was green: the wire
+tests play the frontend's part by hand and had been feeding the argument table
+themselves — simulating a browser that would never have sent it. The **browser**
+test found it. A facade method that composes view XML needs a browser test, not
+only a wire test.
+:::
 
-```js
-client._event("SUBMIT", [], {}, { complex: { payload: [1, 2, 3] } });
-```
+## Where an event string goes
 
-Server side:
+Anywhere UI5 takes an event handler:
 
 ```js
-const data = client.get().R_EVENT_DATA;
+`<Button press="${c.event("SAVE")}"/>`
+`<SearchField search="${c.event("SEARCH")}"/>`
+`<List selectionChange="${c.event("PICK")}"/>`
 ```
 
-## Frontend-only events: `_event_client(name, args)` {#event-client}
-
-Some events should **never** reach the server — e.g. "open this URL in a new tab", "copy this value to the clipboard". For those there is `_event_client`:
+The value you get back is a handler expression, not a plain name — embed it,
+do not parse or compare it. Between `c.event(…)` and the end of `main` it is in
+fact a placeholder token that is substituted for the real wire string on the
+way out; embedding is what it is for.
 
-```js
-.Button({
-  text:  "Open SAP",
-  press: client._event_client(client.cs_event.OPEN_NEW_TAB, ["https://sap.com"])
-});
-```
+## Dispatching
 
-A frontend action handler dispatches it, no roundtrip.
-
-### Available `cs_event` constants
-
-From `z2ui5_cl_ui5_client.js`:
-
-| Constant | Effect |
-|---|---|
-| `OPEN_NEW_TAB` | Open URL in a new tab |
-| `LOCATION_RELOAD` | Reload page on URL |
-| `HISTORY_BACK` | `history.back()` |
-| `CLIPBOARD_COPY` | Copy text to clipboard |
-| `CLIPBOARD_APP_STATE` | Deep link of the current app to clipboard |
-| `DOWNLOAD_B64_FILE` | Download a base64 data URL as a file |
-| `SYSTEM_LOGOUT` | Logout (FLP / URL redirect) |
-| `STORE_DATA` | Value to browser storage |
-| `SET_ODATA_MODEL` | Set the view's default OData model |
-| `SET_SIZE_LIMIT` | JSONModel.setSizeLimit |
-| `URLHELPER` | URLHelper.redirect / triggerEmail / triggerSms / triggerTel |
-| `NAV_CONTAINER_TO` | Change NavContainer destination |
-| `POPUP_CLOSE`, `POPOVER_CLOSE` | Close current popup/popover |
-| `IMAGE_EDITOR_POPUP_CLOSE` | Close image editor |
-
-## Convenience: server-triggered frontend actions
-
-Sometimes you want to trigger a frontend action **as a side effect of your server code** — not in response to a click but, for example, after a successful save:
+With more than a few events, a switch reads better than a chain:
 
 ```js
-if (client.check_on_event("SAVE")) {
-  await this.persist();
-  client.clipboard_copy_app_state();    // ← puts deep link in the clipboard
-  client.message_toast_display("Saved + link copied");
+main(c) {
+  switch (c.eventName) {
+    case "SEARCH": return this.search(c);
+    case "ADD":    return this.add(c);
+    case "":       break;                 // an app start
+  }
+  if (c.isDisplay) c.view(/* … */);
 }
 ```
 
-These methods on `client` are the server-side counterparts of `_event_client`:
-
-| Method | What happens |
-|---|---|
-| `clipboard_copy(text)` | Copy text |
-| `clipboard_copy_app_state()` | Copy current deep-link URL |
-| `file_download(b64, filename)` | Download file |
-| `open_new_tab(url)` | Open new tab |
-| `location_reload(url)` | Reload to URL |
-| `history_back()` | History back |
-| `system_logout(url?)` | Logout |
-| `popup_close()`, `popover_close()` | Close current popups |
-| `cross_app_nav_to_prev_app()` | FLP: back |
-| `cross_app_nav_to_ext(target, params, mode?)` | FLP: external |
-| `storage_set(type, prefix, key, value)` | Browser storage set |
-| `storage_remove(type, prefix, key)` | Browser storage remove |
-| `set_odata_model(url, name?, anno?)` | Set OData model |
-| `set_size_limit(view, limit)` / `reset_size_limit(view)` | Size limit |
-| `url_helper_redirect(url, new_window?)` | URLHelper.redirect |
-| `url_helper_email({email, subject, body, cc, bcc, new_window?})` | mailto: |
-| `url_helper_sms({telephone, message})` | SMS link |
-| `url_helper_tel(telephone)` | Tel link |
-
-These all collect into `S_FOLLOW_UP_ACTION` of the response and the frontend driver runs them sequentially.
-
-## Special event: nav-app-leave
-
-For the page back button there is a convenience helper:
-
-```js
-view.Page({
-  navButtonPress: client._event_nav_app_leave(),
-  showNavButton:  client.check_app_prev_stack()
-});
-```
+Note that a handler often wants to fall through to the render branch rather than
+`return` — after an event that changed the view's *structure* you render again.
+Changed **bound data** needs no re-render; it is pushed on its own.
 
-The event is **intercepted** by the framework before `main()` runs — your app never sees it. Instead the handler executes a `nav_app_leave()`, jumping to the previous app on the stack. → More in [Navigation](./navigation).
+## Next
 
-→ Continue with [**Navigation**](./navigation).
+- [**Data Binding**](./data-binding) — `c.bind` and the types
+- [**Popups & Toasts**](./popups) — `messageBox`, `messageToast`, `popup`
+- [**Navigation**](./navigation) — events that hand the screen to another app
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index fd8ccbc..65cec05 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -1,159 +1,183 @@
 # Quickstart
 
-This page takes you from "empty directory" to "clickable cap2UI5 app" in under five minutes.
-
-::: tip No installation at all?
-If you just want to *see* cap2UI5 first, open the [**browser playground**](./playground) — the whole stack, including all sample apps, runs on GitHub Pages.
-:::
+From an empty directory to a clickable cap2UI5 app. cap2UI5 is a **CAP plugin**:
+you add it to a CAP project you already have, or to a brand new one. There is
+no cap2UI5 project to clone.
 
 ## Prerequisites
 
-- **Node.js ≥ 22** (the app declares it in `engines` and `.nvmrc`)
-- Internet access (the frontend loads SAPUI5 from the SAP CDN)
+- **Node.js ≥ 22**
+- A CAP project (`cds init` makes one in seconds)
+- Internet access — the frontend loads SAPUI5 from the SAP CDN
 
-That's it. No database setup (CAP starts an in-memory SQLite automatically), no global CLI installs (`@sap/cds-dk` is a dev dependency of the project).
+No database setup: CAP starts SQLite for you. No global installs.
 
-## 1. Clone the project
+## 1. A CAP project
 
-Clone the reference project — the repo root **is** the CAP application:
+Skip this if you already have one.
 
 ```bash
-git clone https://github.com/cap2UI5/cap2UI5.git
-cd cap2UI5
-npm install
+npm init -y && npm add @sap/cds @cap-js/sqlite
+npx cds init
 ```
 
-The repository is a complete, self-contained CAP project:
+## 2. Add the plugin
 
+```bash
+npm add cap2ui5
 ```
-cap2UI5/
-├── srv/
-│   ├── z2ui5-service.cds       # service definitions incl. the z2ui5 action
-│   ├── z2ui5-service.js        # service handler bindings
-│   ├── server.js               # CAP bootstrap (HTML + CSRF endpoints)
-│   └── app/                    # your own apps go here
-├── db/
-│   └── schema.cds              # CDS entity z2ui5_t_01 for persistence
-├── app/
-│   └── z2ui5/                  # static UI5 frontend (don't touch)
-├── core/                       # vendored framework package (don't touch)
-│   └── srv/app/samples/        # ~105 demo apps (from abap2UI5/samples)
-└── package.json                # "abap2UI5": "file:./core"
-```
 
-## 2. Start
+That is the whole installation. On the next `cds watch` three things exist that
+did not before:
+
+| | |
+|---|---|
+| the roundtrip route | `/sap/bc/z2ui5` and `/rest/root/z2ui5` |
+| the UI5 shell | `/z2ui5/webapp/` — served from the runtime package, not copied into your project |
+| `cap2ui5.Drafts` | a CDS entity for session state, created by `cds deploy` next to your own |
+
+Your own `server.js`, if you have one, is not touched. Nothing is generated
+into your repository.
+
+::: danger Neither package is on npm yet — the one step that does not work as written
+`npm add cap2ui5` answers **404** today, and so would `@abap2ui5/runtime`, which
+the plugin depends on. Both are published from a release that has not been cut
+yet. Verified while writing this page, so that the line above is what you *will*
+run and not what you can run now.
+
+Until then, work from the repository — `examples/bookshop` in it is a complete
+CAP project using the plugin:
 
 ```bash
-npx cds watch
-# or: start and open the app in the browser right away
-npm run watch-z2ui5
-```
+git clone https://github.com/cap2UI5/cap2UI5 && cd cap2UI5
 
-The server listens on [http://localhost:4004](http://localhost:4004):
+# fill runtime/ from an upstream build (once, ~3 minutes)
+git clone https://github.com/abap2UI5/abap2UI5 /tmp/ref
+(cd /tmp/ref && npm ci && npm run deps && npm run auto_downport && npm run auto_transpile)
+scripts/assemble-runtime.sh /tmp/ref
 
-| URL | What you get |
-|---|---|
-| [`/z2ui5/webapp/index.html`](http://localhost:4004/z2ui5/webapp/index.html) | the app — without a parameter, the startup launcher is shown |
-| [`/z2ui5/webapp/index.html?app_start=z2ui5_cl_ui5_app_hi_world`](http://localhost:4004/z2ui5/webapp/index.html?app_start=z2ui5_cl_ui5_app_hi_world) | start a specific app class directly — works for every sample, e.g. `z2ui5_cl_smp_app_000` |
-| `/rest/root/z2ui5` | the roundtrip endpoint the frontend talks to |
+npm install && npm start
+```
 
-Click around the demo apps first — everything you see in `core/srv/app/samples/` can be started via `?app_start=<class_name>`.
+The workspace links `plugin/` into the example, so `require("cap2ui5")` resolves
+exactly as it will from npm. Everything below this box is accurate today — only
+the `npm add` line waits on the release.
+:::
 
-## 3. Your first own app
+## 3. Your first app
 
-Create a new file `my_first_app.js` in `srv/app/`:
+One file in `srv/apps/` — the directory the plugin scans:
 
 ```js
-// srv/app/my_first_app.js
-const z2ui5_if_app              = require("abap2UI5/z2ui5_if_app");
-const z2ui5_cl_ui5_view_builder = require("abap2UI5/z2ui5_cl_ui5_view_builder");
-
-class my_first_app extends z2ui5_if_app {
+// srv/apps/hello.js
+const { defineApp } = require("cap2ui5");
 
-  who   = "World";
+defineApp("ZCL_HELLO", class {
+  name  = "";
   count = 0;
 
-  async main(client) {
-
-    if (client.check_on_init()) {
-      this.render(client);
+  main(c) {
+    if (c.isDisplay) {
+      c.view(
+        `<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m" displayBlock="true" height="100%">` +
+        `<Shell><Page title="My first cap2UI5 app">` +
+        `<Input value="${c.bind("name")}"/>` +
+        `<Text text="clicks: ${c.bind("count")}"/>` +
+        `<Button text="Say hello" press="${c.event("GO")}" type="Emphasized"/>` +
+        `</Page></Shell></mvc:View>`);
       return;
     }
 
-    if (client.check_on_event("CLICK")) {
+    if (c.eventName === "GO") {
       this.count++;
-      client.message_toast_display(`Hi, ${this.who}! You clicked ${this.count}x.`);
-      this.render(client);
+      c.messageToast(`Hi, ${this.name}! You clicked ${this.count}x.`);
     }
   }
+});
+```
 
-  render(client) {
-    const view = z2ui5_cl_ui5_view_builder.factory()
-      .ele({ n: `View`, ns: `mvc` })
-      .a({ n: `xmlns`,      v: `sap.m` })
-      .a({ n: `xmlns:mvc`,  v: `sap.ui.core.mvc` })
-      .a({ n: `xmlns:form`, v: `sap.ui.layout.form` });
-
-    const form = view.ele(`Shell`).ele(`Page`)
-      .a({ n: `title`, v: `My first cap2UI5 app` })
-      .ele({ n: `SimpleForm`, ns: `form` })
-      .a({ n: `editable`, b: true })
-      .ele({ n: `content`, ns: `form` });
-
-    form.tag(`Label`).a({ n: `text`, v: `Your name` })
-      .tag(`Input`).a({ n: `value`, v: client._bind_edit(this.who) })
-      .tag(`Label`).a({ n: `text`, v: `Clicks` })
-      .tag(`Text`).a({ n: `text`, v: client._bind(this.count) })
-      .tag(`Button`)
-      .a({ n: `text`,  v: `Click me` })
-      .a({ n: `press`, v: client._event(`CLICK`) })
-      .a({ n: `type`,  v: `Emphasized` });
-
-    client.view_display(view.stringify());
-  }
-}
+Four things worth knowing, and each of them is a rule rather than a style:
+
+- **`main` is synchronous.** No `async`, no `await`. Make it `async` only when
+  *your app* does I/O — reading your own entities with `await SELECT.from(Books)`.
+- **`c.isDisplay` is the render branch, not `c.isFirstRun`.** `isDisplay` is
+  also true every time the app gets the screen back from a navigation or a
+  value help. An app that renders only on `isFirstRun` works perfectly until
+  something navigates back into it, and then leaves the previous screen
+  standing with no error anywhere. `isFirstRun` is for seeding state once.
+- **State is ordinary fields.** `name = ""` and `count = 0` are the app's
+  model; `c.bind("name")` binds one into the view. They survive the roundtrip
+  because the plugin stores the instance in `cap2ui5.Drafts`.
+- **The first argument of `defineApp` is the app's name on the wire** — it is
+  what `?app_start=` takes. The file name does not matter.
 
-module.exports = my_first_app;
+## 4. Run it
+
+```bash
+npx cds watch
 ```
 
-Two things worth noting:
+Then open:
 
-- The imports use the vendored core package's exports (`require("abap2UI5/...")`, resolved via the `"abap2UI5": "file:./core"` dependency) — no fragile relative paths. All bundled samples use the same style.
-- **File name = class name.** That convention is how the framework finds your class (see [Persistence](./persistence)).
+```
+http://localhost:4004/rest/root/z2ui5?app_start=ZCL_HELLO
+```
 
-## 4. Launch it
+That is the **roundtrip route**, not a static page: the framework answers a GET
+on it with the composed HTML that boots UI5 and starts the app named in
+`app_start` — measured at 346 KB against 950 bytes for the shell's own
+`index.html`, which is why the distinction matters. `/sap/bc/z2ui5?app_start=…`
+is the same door under its ABAP-side name; `/z2ui5/webapp/` serves the shell's
+assets and is not an entry point.
 
-Open [http://localhost:4004/z2ui5/webapp/index.html?app_start=my_first_app](http://localhost:4004/z2ui5/webapp/index.html?app_start=my_first_app) — done. (`cds watch` picks the new file up automatically.)
+You will be asked to log in: the plugin requires an authenticated user by
+default, and `cds watch` uses CAP's mocked auth, so any configured user works
+(`alice` with an empty password in a stock project). See
+[Configuration](../reference/configuration) to open the route to anonymous
+callers — and what that costs.
 
 ## What you just built
 
-In one file you built a **stateful UI5 app** that:
+A **stateful UI5 app** in one file that
 
-- Two-way-binds `who` to an input field (you type, the server receives it)
-- Persists `count` across roundtrips — the click counter even survives a browser refresh, because the server stores the app instance in the database
-- Needed no OData service, no manifest, no controller, no frontend build
+- binds `name` two-way — you type, the server receives it;
+- keeps `count` across roundtrips, and across a server restart, because the
+  state is a row in your database rather than memory;
+- needed no OData service, no manifest, no controller, no frontend build.
 
-## Where do my apps live long-term?
+## Reading your own data
 
-`srv/app/` is user-owned and scanned automatically — unlike `core/srv/app/samples/`, where the sync pipeline maintains the transpiled abap2UI5 demos (overwritten on every sync). Beyond `srv/app/` you can keep apps in **any folder** and register it:
+The point of running inside CAP. `main` may be `async` when the app does I/O,
+and `cds.ql` works exactly as it does in a handler:
 
 ```js
-// srv/server.js (or any file loaded at startup)
-require("abap2UI5/register-apps")(__dirname + "/my-apps");
-```
+const cds = require("@sap/cds");
+const { SELECT } = cds.ql;
+const { defineApp, t } = require("cap2ui5");
 
-or via environment variable, without touching code:
+defineApp("ZCL_BOOKS", class {
+  search = "";
+  books  = t.table({ ID: 0, title: "", price: t.packed(9, 2) });
 
-```bash
-Z2UI5_APP_DIRS=/abs/path/to/my-apps npx cds watch
+  async main(c) {
+    if (c.isDisplay) { c.view(/* … a Table bound to c.bind("books") … */); return; }
+
+    if (c.eventName === "SEARCH") {
+      const { Books } = cds.entities("my.bookshop");
+      this.books = await SELECT.from(Books).where`title like ${"%" + this.search + "%"}`;
+    }
+  }
+});
 ```
 
-Registered directories are searched recursively; the file-name-equals-class-name convention still applies.
+`t.table({…})` declares the row type; `t.packed(9, 2)` a decimal. The whole
+tree — structures, tables, nested ones — goes through the draft and comes back
+as plain values.
 
 ## Next steps
 
-- [**Project Structure**](./project-structure) — what lives where
-- [**App Lifecycle**](./lifecycle) — `check_on_init`, `check_on_event`, `check_on_navigated`
-- [**View Builder**](./views) — everything you can render
-- [**Data Binding**](./data-binding) — `_bind` vs. `_bind_edit`, the reference-equality pattern
-- [**Examples**](../examples/hello-world) — from Hello World to Selection Screen
+- [**Project Structure**](./project-structure) — what the plugin adds, and what stays yours
+- [**App Lifecycle**](./lifecycle) — `isFirstRun` vs. `isDisplay`, events, navigation
+- [**Data Binding**](./data-binding) — `c.bind`, tables, structures
+- [**Persistence**](./persistence) — `cap2ui5.Drafts` and the owner binding
+- [**Configuration**](../reference/configuration) — routes, the auth default, the apps directory
diff --git a/docs/guide/lifecycle.md b/docs/guide/lifecycle.md
index 20cfed9..37e51ba 100644
--- a/docs/guide/lifecycle.md
+++ b/docs/guide/lifecycle.md
@@ -1,227 +1,116 @@
 # App Lifecycle
 
-A cap2UI5 app is a JavaScript class with a single mandatory method: `async main(client)`. When exactly it is called, what happens the first time, what happens on subsequent roundtrips — that is the app lifecycle.
-
-## The `main(client)` method
+An app is a class. Each roundtrip rebuilds an instance of it from the draft,
+applies what the browser sent, and calls `main(c)` exactly once.
 
 ```js
-class my_app extends z2ui5_if_app {
+const { defineApp } = require("cap2ui5");
 
-  some_field = "";
+defineApp("ZCL_HELLO", class {
+  name = "";
 
-  async main(client) {
-    // called on EVERY roundtrip
+  main(c) {
+    // called on EVERY roundtrip — the branches below decide what happens
   }
-}
+});
 ```
 
-It is called **on every roundtrip** — initial load, button click, selection change, navigation, popup close, … everything goes through `main()`. You differentiate via the `check_*` methods of the `client` object.
+`main` is **synchronous**. Make it `async` only when your app does I/O; the
+framework calls need no `await` either way.
 
-## The three main states
+## The two predicates, and the one that trips people
 
 ```js
-async main(client) {
-
-  if (client.check_on_init()) {
-    // first call of the app instance
-    return;
-  }
-
-  if (client.check_on_navigated()) {
-    // app was just activated after a nav_app_call/leave
-    return;
+main(c) {
+  if (c.isFirstRun) {
+    // the first roundtrip of THIS app instance, and only that one.
+    // Seed state here.
   }
 
-  if (client.check_on_event("MY_EVENT")) {
-    // a specific event has occurred
+  if (c.isDisplay) {
+    // the first roundtrip AND every time this app gets the screen back:
+    // a called app leaving, a value help closing, a bookmark restored.
+    // RENDER here.
+    c.view(/* … */);
     return;
   }
-}
-```
-
-### `check_on_init()`
-
-Returns `true` **only on the first** `main()` call of a fresh app instance. This is the moment when you:
-
-- Set default values
-- Load external data (`cds.connect.to(...)`)
-- Render the initial view
-
-```js
-if (client.check_on_init()) {
-  this.customers = await (await cds.connect.to("northwind"))
-    .run(SELECT.from("Customers").limit(50));
-  this.render(client);
-  return;
-}
-```
-
-Internally: `check_on_init()` returns `true` as long as `oApp.check_initialized` is falsy **and** there is no event name. After `main()`, the handler sets `check_initialized = true`, persists the instance, and returns the response. On the next roundtrip the instance is loaded from the DB — by then `check_initialized` is already `true` and `check_on_init()` returns `false`.
-
-### `check_on_event(name?)`
-
-With argument: tests whether the given event is currently active.
-
-```js
-if (client.check_on_event("BUTTON_SAVE")) {
-  await this.save();
-}
-```
-
-Without argument: tests whether _any_ event is active.
-
-```js
-if (client.check_on_event()) {
-  switch (client.get().EVENT) {
-    case "BUTTON_SAVE":   /* ... */ break;
-    case "BUTTON_CANCEL": /* ... */ break;
-  }
-}
-```
-
-Which style is nicer is a matter of taste — both work identically.
-
-### `check_on_navigated()`
 
-Returns `true` directly after a `nav_app_call(...)` or `nav_app_leave(...)`. In the navigated-into app you can use it to react to the result of a popup or a sub-app:
-
-```js
-if (client.check_on_navigated()) {
-  const prev = client.get_app_prev();
-  if (prev instanceof MyPopup && prev.result?.confirmed) {
-    this.selected_id = prev.result.id;
-  }
+  if (c.eventName === "GO") { /* … */ }
 }
 ```
 
-→ More in [Navigation](./navigation).
+::: danger Render on `isDisplay`, not on `isFirstRun`
+`isFirstRun` implies `isDisplay`, so `if (c.isDisplay)` is the whole display
+condition — no `||`.
 
-## What happens between roundtrips
+An app that renders only on `isFirstRun` works perfectly until something
+navigates back into it, and then **leaves the previous screen standing with no
+error anywhere**. Nothing throws, nothing logs, the user just sees the wrong
+page. It is the framework's most common app bug, and `z2ui5_if_client`'s own
+documentation says so.
+:::
 
-The lifecycle of an app instance:
+Underneath they are `check_on_init()` and `check_on_navigated()`. The facade
+renames them because the original names suggest the opposite of what they do —
+`check_on_navigated` reads like "arrived by navigation" and is in fact also true
+on the very first run.
 
-```
-            ┌──────────────────────────────────────┐
-            │ First GET → frontend loads           │
-            │ First POST (S_FRONT.ID = "")         │
-            ▼                                      │
-        action_factory                             │
-        → factory_first_start (?app_start=…)       │
-        → factory_system_startup                   │
-            │                                      │
-            ▼                                      │
-        new MyApp()                                │
-            │                                      │
-            ▼                                      │
-        apply XX delta (initial = empty)           │
-            │                                      │
-            ▼                                      │
-        main(client)  ← check_on_init() === true   │
-            │                                      │
-            ▼                                      │
-        check_initialized = true                   │
-            │                                      │
-            ▼                                      │
-        DB.saveApp() → new UUID generated          │
-            │                                      │
-            ▼                                      │
-        Response: { S_FRONT: { ID: <uuid>, … } }   │
-            │                                      │
-            ▼                                      │
-        Browser shows view                         │
-            │                                      │
-            ▼                                      │
-        User clicks button                         │
-            │                                      │
-            ▼                                      │
-        POST { S_FRONT: { ID: <uuid>, EVENT, … }, XX: { … delta … } }
-            │                                      │
-            ▼                                      │
-        action_factory → DB.loadApp(uuid)          │
-            │                                      │
-            ▼                                      │
-        deserialize → my_app instance with old state
-            │                                      │
-            ▼                                      │
-        apply XX delta (user inputs flow in)       │
-            │                                      │
-            ▼                                      │
-        main(client)  ← check_on_event(...) === true
-            │                                      │
-            ▼                                      │
-        DB.saveApp() → new UUID                    │
-            └──────────────────────────────────────┘
-```
+## The full surface
 
-Important:
+Everything `c` offers, which is everything an app needs before reaching for
+`c.raw`:
 
-1. **The app instance only lives for one roundtrip** in memory. Afterwards it is serialized.
-2. **Fields that are JSON-serializable survive.** Functions, closures, DOM refs, external connection objects → do not.
-3. **Properties like `client` are skipped** (see `SKIP_PROPS` in `z2ui5_cl_ui5_srv_draft.js`) so that no cyclic graph is created.
+| | |
+|---|---|
+| **lifecycle** | `isFirstRun`, `isDisplay`, `canGoBack`, `eventName`, `eventArg(i)`, `prevApp` |
+| **binding** | `bind(field)`, `event(name, [args])` |
+| **screen** | `view(xml)`, `popup(xml)` / `popupClose()`, `nest(into, xml, opts)` / `nestClose()` |
+| **messages** | `messageBox(text)`, `messageToast(text)` |
+| **navigation** | `navTo(app)`, `navBack({event, data, app})` |
+| **escape hatch** | `raw` — the underlying async client |
 
-## Pattern: fields ↔ reference-equality bindings
+## A typical app
 
 ```js
-class search_form extends z2ui5_if_app {
-
-  search    = "";    // ← bind_edit finds 'search' via reference equality
-  results   = [];
-  page_size = 25;
-
-  async main(client) {
-    if (client.check_on_init()) { /* ... */ }
-    if (client.check_on_event("DO_SEARCH")) {
-      this.results = await this.search_db(this.search, this.page_size);
+defineApp("ZCL_ORDER", class {
+  customer = "";
+  lines    = t.table({ sku: "", qty: 0 });
+  loaded   = false;
+
+  async main(c) {
+    if (c.isFirstRun) {
+      this.customer = c.raw ? "" : "";      // seed once
     }
-    this.render(client);
-  }
-
-  render(client) {
-    const view = z2ui5_cl_ui5_view_builder.factory()
-      .ele({ n: `View`, ns: `mvc` })
-      .a({ n: `xmlns`,     v: `sap.m` })
-      .a({ n: `xmlns:mvc`, v: `sap.ui.core.mvc` });
 
-    view.ele(`Shell`).ele(`Page`).a({ n: `title`, v: `Search` })
-      .tag(`Input`).a({ n: `value`, v: client._bind_edit(this.search) })
-      .tag(`Button`).a({ n: `press`, v: client._event(`DO_SEARCH`) })
-      .tag(`Table`).a({ n: `items`, v: client._bind(this.results) });
+    if (c.eventName === "LOAD") {
+      const { Orders } = cds.entities("my.shop");
+      this.lines = await SELECT.from(Orders);
+      this.loaded = true;
+    }
 
-    client.view_display(view.stringify());
+    if (c.isDisplay || c.eventName === "LOAD") {
+      c.view(/* … */);
+    }
   }
-}
+});
 ```
 
-Fields you expose via bindings **must be direct properties** of the app. `_bind_edit(this.deep.path.field)` does _not_ work for deeply nested values — you would expose `this.deep` and bind the sub-path as a string:
+Note the last branch: after an event that changed what is on screen you render
+again. Changed **bound data** is pushed on its own — you only re-render when the
+view's *structure* changes.
 
-```js
-const path = client._bind_edit(this.deep, { path: true });
-// path = "/XX/DEEP"      ← model paths are uppercased
-page.tag(`Input`).a({ n: `value`, v: `{${path}/PATH/FIELD}` });
-```
+## Two members that used to exist and now throw
 
-→ Full explanation in [Data Binding](./data-binding).
+Both throw an error naming the replacement rather than quietly changing meaning:
 
-## Framework fields (don't use yourself)
-
-These properties on `z2ui5_if_app` are reserved:
-
-```js
-id_draft          = "";
-id_app            = "";
-check_initialized = false;
-check_sticky      = false;
-```
-
-Don't override — the binding engine explicitly excludes them from the reference lookup (`_FRAMEWORK_FIELDS` in `z2ui5_cl_ui5_client.js`), but don't use them as your own app state either.
-
-## Stickiness (optional)
-
-```js
-this.check_sticky = true;
-client.set_session_stateful(true);
-```
+| gone | why |
+|---|---|
+| `c.isInitial` | it was wired to `check_on_navigated()` and named after `check_on_init()`. Use `c.isDisplay` to render, `c.isFirstRun` to seed |
+| `c.modelUpdate()` | it called `view_model_update()`, which the framework declares **obsolete and does nothing**. Changed bound data is pushed automatically — to an open popup and a nested view too |
 
-Sets a sticky session — the frontend driver then serializes roundtrips more strictly back-to-back. Useful for apps with critical ordering or file upload sequences, otherwise unnecessary.
+## Next
 
-→ Continue with [**View Builder**](./views).
+- [**Data Binding**](./data-binding) — `c.bind`, tables, structures
+- [**Events**](./events) — `c.event`, arguments, `c.eventName`
+- [**Navigation**](./navigation) — `navTo`, `navBack`, `prevApp`
+- [**Persistence**](./persistence) — why the instance survives at all
diff --git a/docs/guide/migration-from-abap2ui5.md b/docs/guide/migration-from-abap2ui5.md
index 8f4cea5..b89170e 100644
--- a/docs/guide/migration-from-abap2ui5.md
+++ b/docs/guide/migration-from-abap2ui5.md
@@ -1,175 +1,124 @@
 # Migrating from abap2UI5
 
-An abap2UI5 app and a cap2UI5 app are the same app in two languages. The wire
-protocol is identical, the frontend is byte-identical, and the API is the same
-method for method — so migration is mechanical rather than a redesign. What
-changes is the language, the data access, and the outbound calls.
-
-This page is the per-construct mapping. For the wider comparison — why a
-second implementation exists, which one to pick — see
-[cap2UI5 vs. abap2UI5](./vs-abap2ui5).
-
-## The five steps
-
-1. **Rewrite the ABAP class as a JS class**, method for method. Or let the
-   transpiler do a first pass: in a
-   [builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js)
-   checkout, `npm run transpile -- path/to/z2ui5_cl_my_app.clas.abap --stdout`
-   emits JavaScript and marks what it could not translate as
-   `// TODO(abap2js)` comments instead of dropping it.
-2. **Rebuild the view** if it was built on the retired `z2ui5_cl_xml_view` —
-   the one builder here is `z2ui5_cl_ui5_view_builder`.
-3. **Convert data access** from OpenSQL to CDS queries.
-4. **Convert outbound calls** from `cl_http_client` to `fetch` or
-   `cds.connect.to`.
-5. **Drop the file into** [`srv/app/`](./project-structure#srv-app) and run it.
-   The same static frontend renders it without changes.
-
-## Construct by construct
-
-### The app class
+If you know abap2UI5, you already know cap2UI5. Same pattern, same roundtrip,
+same frontend, same framework — literally the same framework, since the plugin
+runs upstream's own runtime. What changes is the **language your app is written
+in** and **where its state is stored**.
+
+## The mental model does not change
+
+Roundtrips, the draft chain, the app stack, value helps as apps, one class per
+app — all identical, because it is the same code answering.
+
+## What an app looks like on each side
+
+```abap
+" abap2UI5
+CLASS zcl_my_app DEFINITION PUBLIC.
+  PUBLIC SECTION.
+    INTERFACES z2ui5_if_app.
+    DATA name TYPE string.
+ENDCLASS.
+
+METHOD z2ui5_if_app~main.
+  IF client->check_on_init( ).
+    client->view_display( ... ).
+    RETURN.
+  ENDIF.
+  IF client->get( )-event = 'GO'.
+    client->message_box_display( |Hello { name }| ).
+  ENDIF.
+ENDMETHOD.
+```
+
+```js
+// cap2UI5
+const { defineApp } = require("cap2ui5");
+
+defineApp("ZCL_MY_APP", class {
+  name = "";
+
+  main(c) {
+    if (c.isDisplay) {
+      c.view(/* … */);
+      return;
+    }
+    if (c.eventName === "GO") c.messageBox(`Hello ${this.name}`);
+  }
+});
+```
+
+## The translation table
 
 | abap2UI5 | cap2UI5 |
 |---|---|
-| `CLASS … DEFINITION PUBLIC` / `INTERFACES z2ui5_if_app` | `class … extends z2ui5_if_app` |
-| `METHOD z2ui5_if_app~main` | `async main(client)` |
-| `DATA name TYPE string` (class attribute) | `name = ""` (class field) |
-| `me->name` | `this.name` |
-| the class name is the ADT/CCDIR object name | the class name **must** match the file name — the RTTI lookup is name-based |
-
-App state is the instance's own fields in both worlds: whatever you assign to
-`this` survives the roundtrip, because the framework serialises the instance
-into the draft. See [App Lifecycle](./lifecycle).
-
-### Views
-
-| abap2UI5 | cap2UI5 |
-|---|---|
-| `z2ui5_cl_ui5_view_builder=>factory( )` | `z2ui5_cl_ui5_view_builder.factory()` |
-| `z2ui5_cl_xml_view` (frozen upstream) | **not carried** — rebuild on `z2ui5_cl_ui5_view_builder` |
-| `z2ui5_cl_xml_view_cc` (custom-control decorator) | **not carried** — the `z2ui5.cc` namespace is declared on the view like any other |
-| the built-in popups `z2ui5_cl_pop_*` | **not carried** — see [Popups & Toasts](./popups) |
-| `view->ele( n = 'View' ns = 'mvc' )` — named arguments | `view.ele({ n: "View", ns: "mvc" })` — one object |
-| `)->a( n = 'title' v = 'Hello' )` chained with `->` | `.a({ n: "title", v: "Hello" })` chained with `.` |
-| `view->stringify( )` | `view.stringify()` |
-
-Named arguments are the one place every line changes shape. ABAP names each
-argument (`n = … v = …`); JavaScript passes a single object literal with the
-same keys. Positional shorthand survives where ABAP had it: `view->ele( 'Page' )`
-becomes `view.ele("Page")`. The methods themselves —
-[`ele`, `tag`, `a`, `end`, `stringify`](../api/view-builder#methods) — are
-unchanged.
-
-The absent classes are absent on purpose, not by omission: cap2UI5 does not
-carry abap2UI5's frozen `src/99` package at all
-([why](./vs-abap2ui5#commonalities)). An old sample that still compiles
-upstream can therefore fail here on the import alone.
-
-### Binding
-
-| abap2UI5 | cap2UI5 |
-|---|---|
-| `client->_bind( name )` | `client._bind(this.name)` |
-| `client->_bind_edit( name )` | `client._bind_edit(this.name)` |
-| `client->_event( 'BUTTON_POST' )` | `client._event("BUTTON_POST")` |
-
-::: warning `_bind` vs `_bind_edit` — check which release your source targets
-cap2UI5 pins abap2UI5 **1.142.0** (`static version` on `z2ui5_if_app`, in
-`core/srv/z2ui5/02/z2ui5_if_app.js`). On that release the two calls are two
-different bindings:
-
-- `_bind()` is **one-way** — the value is rendered, and changes in the browser
-  are not read back.
-- `_bind_edit()` is **two-way** — the value is rendered *and* the frontend
-  writes it back into the attribute on the next roundtrip. An `Input` whose
-  value you intend to read needs this one.
-
-Upstream merged the two in **1.143.0**: from there on `_bind_edit()` is an
-alias of `_bind()`, and everything is two-way. So an app written against
-1.143.0 or later that relies on `_bind()` writing back **will silently not
-write back here** — the field simply stays at its old value. Migrating such an
-app means changing those calls to `_bind_edit()`.
-
-Coming the other way, from an older app: `_bind_edit()` keeps working on both
-releases, which makes it the safe choice while the two releases coexist.
-:::
-
-In both languages the binding call receives the attribute and the framework
-works out *which* attribute that was. In JavaScript it does so by value
-identity, so pass `this.name` itself — a copy, a literal or an expression can
-resolve to a different attribute holding the same value. See
-[Data Binding](./data-binding#reference-equality) for what to do when two
-fields legitimately share a value.
-
-### Data structures
-
-| abap2UI5 | cap2UI5 |
-|---|---|
-| `TYPES: BEGIN OF ty_s_row … END OF ty_s_row` | no declaration — a plain object `{ … }` |
-| `DATA s_row TYPE ty_s_row` | `s_row = { carrid: "", connid: "" }` |
-| `DATA t_tab TYPE STANDARD TABLE OF ty_s_row` | `t_tab = []` |
-| `APPEND s_row TO t_tab` | `t_tab.push(s_row)` |
-| `READ TABLE t_tab INTO s_row INDEX 1` | `s_row = t_tab[0]` |
-| `LOOP AT t_tab INTO s_row` | `for (const s_row of t_tab)` |
-| `CLEAR` / `IS INITIAL` | `= ""` / `= []` / a falsy check |
-| field names are case-insensitive, upper-cased in the model | **object keys are case-sensitive** — keep them lower-case and consistent |
-
-The last row is the one that bites. ABAP does not care whether you wrote
-`CARRID` or `carrid`; JavaScript does, and a binding path that disagrees with
-the object key by one character renders empty rather than failing.
-
-### Data access
-
-| abap2UI5 | cap2UI5 |
-|---|---|
-| `SELECT * FROM scarr INTO TABLE @DATA(t)` | `const t = await SELECT.from("my.Carriers")` |
-| `SELECT SINGLE … WHERE id = @lv_id` | `await SELECT.one.from("my.Carriers").where({ id })` |
-| `SELECT … UP TO 100 ROWS` | `.limit(100)` |
-| `INSERT`/`UPDATE`/`DELETE` | `INSERT.into(…)`, `UPDATE(…)`, `DELETE.from(…)` |
-| `sy-subrc` after the statement | an empty array / `undefined`, or a thrown error |
-| implicit client handling, authorisation checks | CAP's `@requires` / `@restrict` on the service |
-
-CDS queries are **asynchronous**. That is the one structural change migration
-forces: a method that reads data becomes `async`, and every caller up to
-`main` has to `await` it. `main` is already `async` in cap2UI5, which is why
-the chain terminates cleanly.
-
-### Outbound calls
-
-| abap2UI5 | cap2UI5 |
-|---|---|
-| `cl_http_client=>create_by_url( … )` | `await fetch(url, { … })` |
-| `client->send( )` / `client->receive( )` | the awaited `fetch` promise |
-| `lo_response->get_cdata( )` | `await res.text()` |
-| `/ui2/cl_json=>deserialize( )` | `await res.json()` |
-| RFC / service consumer / destination | `await cds.connect.to("service")` |
-| SM59 destination | a CAP destination or a plain URL |
-
-See [External OData Call](../examples/external-odata) for a worked example.
-
-### Everything else
-
-| abap2UI5 | cap2UI5 |
-|---|---|
-| `sy-uname` | the identity provider — `engine.set_identity(…)`, see [Configuration](../reference/configuration#identity) |
-| `sy-datum` / `sy-uzeit` | `new Date()` |
-| `MESSAGE`/`cx_root` exceptions | `throw new Error(…)` / `try…catch` |
-| `z2ui5_cl_ui5_user_exit` (config exit) | the same class, same two hooks — see [The User Exit](./user-exit) |
-| DB table `Z2UI5_T_01` | CDS entity `cap2ui5.z2ui5_t_01`, see [Database Model](../reference/database) |
-| transport / abapGit pull | `npm install`, `cds build`, `cf deploy` |
-
-## What does not need migrating
-
-- **The frontend.** cap2UI5 serves the same `app/z2ui5/webapp/` UI5 bundle
-  abap2UI5 does, custom controls included. Nothing you built on the frontend
-  side changes.
-- **The wire protocol.** `POST /rest/root/z2ui5` with the same
-  `{ S_FRONT, XX, MODEL }` payload. A frontend cannot tell the two backends
-  apart, which is why the same app can be deployed in both worlds during a
-  transition.
-- **The mental model.** Roundtrips, the draft chain, `check_on_init` /
-  `check_on_event` / `check_on_navigated`, `nav_app_call` — all identical.
-
-→ Next: the [**Sample Catalogue**](./samples) — the whole abap2UI5 demo
-collection, already transpiled, is the largest set of before/after pairs
-available.
+| `CLASS … INTERFACES z2ui5_if_app` | `defineApp("NAME", class { … })` |
+| `DATA name TYPE string` | `name = ""` |
+| `DATA amount TYPE p LENGTH 9 DECIMALS 2` | `amount = t.packed(9, 2)` |
+| `DATA rows TYPE ty_t_row` | `rows = t.table({ … })` |
+| `z2ui5_if_app~main` | `main(c)` |
+| `client->check_on_init( )` | `c.isFirstRun` |
+| `client->check_on_navigated( )` | `c.isDisplay` ← **render on this one** |
+| `client->get( )-event` | `c.eventName` |
+| `client->get_event_arg( 1 )` | `c.eventArg(1)` |
+| `client->_bind( name )` | `c.bind("name")` — a **name**, not a value |
+| `client->_bind_edit( name )` | `c.bind("name")` — binding is two-way; there is no separate variant |
+| `client->_event( 'GO' )` | `c.event("GO")` |
+| `client->view_display( xml )` | `c.view(xml)` |
+| `client->popup_display( xml )` | `c.popup(xml)` |
+| `client->message_box_display( t )` | `c.messageBox(t)` |
+| `client->message_toast_display( t )` | `c.messageToast(t)` |
+| `client->nav_app_call( app )` | `c.navTo(app)` |
+| `client->nav_app_leave( )` | `c.navBack({ event, data })` |
+| `client->get_app_prev( )` | `c.prevApp` |
+| anything else on `z2ui5_if_client` | `c.raw.z2ui5_if_client$<method>( … )`, async |
+
+## The three differences that actually bite
+
+**`_bind` takes a name, not a value.** In ABAP, `client->_bind( name )` passes
+the attribute and the framework matches it by reference. JavaScript cannot do
+that — two empty strings are indistinguishable — so the facade takes the field
+name and resolves the binding for you.
+
+**Render on `isDisplay`, not `isFirstRun`.** The same trap as in ABAP, with
+clearer names: `check_on_init( )` is this instance's first roundtrip only, and
+`check_on_navigated( )` is also every return from a navigation. The JS facade
+renames them to say which is which.
+
+**Views are XML strings.** abap2UI5's fluent builder exists in the runtime, but
+the facade does not expose it: in JavaScript a template literal is shorter than
+a chain. See [Views](./views).
+
+```abap
+client->view_display( z2ui5_cl_ui5_view_builder=>factory(
+  )->ele( `Page` )->tag( `Input` )->a( ... )->stringify( ) ).
+```
+
+```js
+c.view(`<Page><Input value="${c.bind("name")}"/></Page>`);
+```
+
+## What is genuinely different
+
+| | abap2UI5 | cap2UI5 |
+|---|---|---|
+| state lives in | `Z2UI5_T_01`, an ABAP table | `cap2ui5.Drafts`, a CDS entity in **your** database |
+| identity | `sy-uname` | `cds.context.user.id` |
+| data access | Open SQL | `cds.ql` — and CAP's remote services |
+| deployment | abapGit into a system | `npm i` into a CAP project |
+
+## Porting an existing app
+
+There is no automatic converter, and the honest reason is that the interesting
+part — Open SQL to `cds.ql`, ABAP types to declared fields — is exactly the part
+a converter would get wrong. The table above covers the framework calls; the
+rest is your business logic, which you are better placed to translate.
+
+Start with the smallest app you have. The structure carries over almost
+untouched, and the first one takes an afternoon.
+
+## Next
+
+- [**App Lifecycle**](./lifecycle) — the predicates, in detail
+- [**Data Binding**](./data-binding) — the type declarations
+- [**cap2UI5 vs. abap2UI5**](./vs-abap2ui5) — when to use which
diff --git a/docs/guide/navigation.md b/docs/guide/navigation.md
index 0a12d13..3571d34 100644
--- a/docs/guide/navigation.md
+++ b/docs/guide/navigation.md
@@ -1,166 +1,101 @@
 # Navigation
 
-cap2UI5 apps can navigate between each other — the server keeps a **stack** of app instances, so forward and back navigation work naturally.
+Navigation in cap2UI5 is one app **calling another**. The caller keeps its
+state, the callee runs with its own, and when the callee leaves, the caller gets
+the screen back and can read what the callee produced.
 
-## Forward: `nav_app_call(newApp)`
+## Calling an app
 
 ```js
-if (client.check_on_event("OPEN_DETAILS")) {
-  const detail = new my_detail_app();
-  detail.id = this.selected_id;
-  client.nav_app_call(detail);
+// ZCL_PICK
+if (c.eventName === "CHOOSE") {
+  c.navTo("ZCL_PICK_ONE");
+  return;
 }
 ```
 
-This **pushes the current app onto the stack** and makes `detail` the new main app. The handler loop will call `main()` of `detail` directly within the same roundtrip — `check_on_init()` is `true` there.
+`c.navTo` takes the name you gave `defineApp`, a `defineApp` class, or an
+instance you built yourself. A name that resolves to nothing is refused **here**,
+where you can see which name it was, rather than as a `NAV_APP_TARGET_NOT_BOUND`
+later.
 
-## Back: `nav_app_leave()`
+Navigation is scheduled for the end of the roundtrip, so it is usually the last
+thing a branch does.
 
-```js
-if (client.check_on_event("CANCEL")) {
-  client.nav_app_leave();
-}
-```
-
-**Pops** the topmost app off the stack. If the stack is empty, the framework falls back to the startup app.
-
-Optionally you can specify an **explicit app** to jump back to:
+## Coming back
 
 ```js
-client.nav_app_leave(some_specific_app);
-```
-
-## Convenience: page back button
-
-Practically every app wants a page back button that jumps to the previous app:
-
-```js
-view.Page({
-  title:          "Detail",
-  navButtonPress: client._event_nav_app_leave(),
-  showNavButton:  client.check_app_prev_stack()
-});
+// ZCL_PICK_ONE
+if (c.eventName === "TAKE") {
+  this.colour = c.eventArg(1);
+  if (c.canGoBack) c.navBack({ event: "PICKED" });
+  return;
+}
 ```
 
-`_event_nav_app_leave()` builds a special event that **the framework intercepts** — your `main()` never sees it. It performs `nav_app_leave()` directly.
+`c.navBack(opts)` hands the screen back. Guard it with `c.canGoBack` — there may
+be nothing to go back to.
 
-`check_app_prev_stack()` returns `true` when the stack is not empty — useful so the button is only shown when it makes sense.
+| option | |
+|---|---|
+| `event` | the event the caller's `main` sees on its next run |
+| `data` | a value for the caller; a string goes as is, anything else is JSON |
+| `app` | leave to a *different* app than the one that called |
 
-## Pop result: `get_app_prev()`
+## Reading what the callee produced
 
-The classic pattern: an app opens a "selector" that returns a selection.
+Back in the caller, `c.prevApp` is the app on the other side of the last
+navigation — the instance that just returned, with its fields as plain values:
 
 ```js
-// main app
-if (client.check_on_event("PICK_USER")) {
-  const picker = new user_picker();
-  picker.search_term = this.search;
-  client.nav_app_call(picker);
+// ZCL_PICK again, after the callee left
+if (c.eventName === "PICKED" && c.prevApp) {
+  this.chosen = c.prevApp.colour ?? "";
+  this.picks += 1;
 }
 
-// after returning from picker
-if (client.check_on_navigated()) {
-  const prev = client.get_app_prev();
-  if (prev instanceof user_picker && prev.result?.confirmed) {
-    this.selected_user = prev.result.user;
-  }
+if (c.isDisplay) {
+  c.view(/* … shows this.chosen … */);
 }
 ```
 
-`get_app_prev()` returns the **just-left** app (not the stack top). It is readable for exactly one roundtrip after a back-nav — afterwards it is discarded.
+::: danger This is where `isDisplay` earns its name
+When the callee leaves, the caller's `main` runs again with **`isDisplay` true
+and `isFirstRun` false**. An app that renders only on `isFirstRun` shows the
+user its *old* screen — the pick never appears, and nothing anywhere reports an
+error.
 
-## App home & app back
+That is the single most common way to get a screen that does not refresh. See
+[App Lifecycle](./lifecycle).
+:::
 
-Two more convenience methods:
+## The stack is in the database
 
-```js
-client.nav_app_home();   // ← jumps to startup, clears the stack
-client.nav_app_back();   // ← single pop; falls back to home if empty
-```
-
-Difference from `nav_app_leave()`: `nav_app_back()` additionally sets the flag `_navTargetIsLeave = true`, so the stack pointer is not pushed again.
+`c.navTo` does not keep a call stack in memory. The draft rows carry it —
+`id_prev`, `id_prev_app`, `id_prev_app_stk` — which is why navigation survives a
+restart.
 
-## Routing via URL
+Measured: a server is **SIGKILLed while inside the called app**, and a fresh
+process takes the callee's event, unwinds a stack it never built, runs the
+caller's `main` again and carries the value home:
 
-You can directly start a specific app via URL parameter:
-
-```
-/z2ui5/webapp/index.html?app_start=my_app_name
 ```
-
-This works through `factory_first_start` in `z2ui5_cl_ui5_action.js` — on the first roundtrip without `S_FRONT.ID` the handler looks at the query string, finds the class via RTTI, and instantiates it.
-
-## Browser history
-
-If you want to couple the history with the browser history:
-
-```js
-client.set_push_state(true);
+B roundtrip 2  MODEL={"CHOSEN":"red","PICKS":1}
+RESULT: the app STACK survived the restart
 ```
 
-Pushes the current server state into `history.pushState`. With this the browser back button works — it then triggers a reload with the previous `S_FRONT.ID`.
+## Popup or navigation?
 
-## Stack persistence
+| | |
+|---|---|
+| a dialog that belongs to this app's state | [`c.popup`](./popups) |
+| a screen with its own state, reusable from several places | `c.navTo` |
 
-The nav stack survives across roundtrips because:
+A value help is usually the second: it is an app, and its result comes back
+through `c.prevApp`.
 
-1. On `db_save` of the current app, all apps in the `_navStack` are also persisted.
-2. Their IDs are stored in `oApp.__navStackIds`.
-3. On the next load, `_rehydrate_nav_stack` reads these IDs and reloads the stack apps.
-
-Meaning: a user can refresh the browser and the entire navigation history is restored.
-
-## Example: master-detail with picker
-
-```js
-class my_master extends z2ui5_if_app {
-
-  selected_user_id  = "";
-  selected_username = "";
-
-  async main(client) {
-    if (client.check_on_init()) this.render(client);
-
-    if (client.check_on_navigated()) {
-      const prev = client.get_app_prev();
-      if (prev instanceof my_user_picker && prev.confirmed) {
-        this.selected_user_id  = prev.result_id;
-        this.selected_username = prev.result_name;
-      }
-      this.render(client);
-    }
-
-    if (client.check_on_event("PICK")) {
-      client.nav_app_call(new my_user_picker());
-    }
-  }
-
-  render(client) { /* ... */ }
-}
-```
-
-```js
-class my_user_picker extends z2ui5_if_app {
-
-  confirmed   = false;
-  result_id   = "";
-  result_name = "";
-
-  async main(client) {
-    if (client.check_on_init()) this.render(client);
-
-    if (client.check_on_event("CONFIRM")) {
-      this.confirmed   = true;
-      this.result_id   = client.get_event_arg(1);
-      this.result_name = client.get_event_arg(2);
-      client.nav_app_leave();
-    }
-
-    if (client.check_on_event("CANCEL")) client.nav_app_leave();
-  }
-
-  render(client) { /* ... */ }
-}
-```
+## Next
 
-→ Continue with [**Persistence & Sessions**](./persistence).
+- [**App Lifecycle**](./lifecycle) — `isDisplay` vs. `isFirstRun`
+- [**Popups & Toasts**](./popups) — the lighter alternatives
+- [**Persistence**](./persistence) — why the stack survives
diff --git a/docs/guide/persistence.md b/docs/guide/persistence.md
index d1eaec4..cbda1d3 100644
--- a/docs/guide/persistence.md
+++ b/docs/guide/persistence.md
@@ -1,147 +1,106 @@
 # Persistence & Sessions
 
-cap2UI5 apps are **stateful**: their fields survive a roundtrip, a browser refresh, sometimes even a server restart. This page explains how persistence works and where its limits are.
+A cap2UI5 app is **stateful across roundtrips** and stateless in memory. Your
+fields keep their values between clicks, and they do so because the server
+writes the app instance to the database after every roundtrip — not because
+anything stays alive between them.
 
-## The persistence table
+That distinction is the whole design, and it is what makes the apps survive a
+restart, a second server behind a load balancer, and a scale-to-zero.
 
-In `db/schema.cds`:
+## What happens per click
 
-```cds
-namespace cap2ui5;
-
-entity z2ui5_t_01 {
-  key id      : UUID;
-  id_prev     : UUID;          // ← predecessor ID, builds the history
-  data        : LargeString;   // ← serialized app instance
-}
+```
+browser  ──POST /rest/root/z2ui5 {id, event, model}──▶  CAP
+                                                        │  load draft <id>
+                                                        │  rebuild the app instance
+                                                        │  apply the model the browser sent
+                                                        │  call your main(c)
+                                                        │  write a NEW draft, new id
+         ◀──{S_FRONT:{ID:…}, actions, model}────────────┘
 ```
 
-On every roundtrip:
-
-1. The app instance is **serialized** (`z2ui5_cl_ui5_srv_draft.serialize`).
-2. A new UUID is generated.
-3. An `INSERT` is made into `z2ui5_t_01` — `id_prev` points to the previous instance.
-4. The new UUID goes back in the response (`S_FRONT.ID`).
-5. The frontend sends this ID along on the next roundtrip.
-6. The server loads the instance again and applies the XX delta before `main()`.
-
-This is an **append-only history**. If you want, you can traverse the past via `id_prev` — for example, to build an "undo" mechanism.
-
-## What gets serialized?
-
-The engine walks `Object.getOwnPropertyNames(oApp)` and includes anything that:
+Every roundtrip writes a **new** draft with a fresh uuid and a pointer to the
+previous one. Nothing is mutated in place, which is why the browser's back
+button and a restored bookmark land on a consistent state rather than a
+half-updated one.
 
-- Is **not a function**
-- Is **not in the `SKIP_PROPS` set** (`["client"]`)
-- Is JSON-serializable
+## What is persisted
 
-That means: your **data fields** survive, **bound methods** and **closures** do not.
+Your declared fields, and only those:
 
 ```js
-class my_app extends z2ui5_if_app {
-
-  username    = "Alice";        // ✓ persisted
-  preferences = { lang: "de" }; // ✓ persisted
-  computed    = null;           // ✓ persisted (even when null)
+defineApp("ZCL_ORDER", class {
+  id       = "";
+  customer = { name: "", city: "" };
+  lines    = t.table({ sku: "", qty: 0, price: t.packed(9, 2) });
 
-  client      = null;           // ← skipped (in SKIP_PROPS)
-
-  helper      = () => { … };    // ✗ function — not persisted
-  __cache     = new Map();      // ✗ Map is not JSON round-trippable
-  conn        = await cds.connect.to(...); // ✗ connection object
-}
+  main(c) { /* … */ }
+});
 ```
 
-::: tip Rule of thumb
-Keep app fields **JSON pure**: strings, numbers, booleans, arrays, plain objects. If you need maps, sets, connections, or streams, declare them as _local variables in `main()`_ — they then live for exactly one roundtrip.
-:::
-
-## Class restoration
+All three survive. Structures and tables nest as deeply as you like — the model
+carries `ORDER.CUSTOMER.CITY` and `ORDER.LINES[].PRICE`, decimals included, and
+the app reads the whole tree back as plain values on a later roundtrip.
 
-Serialization writes two meta fields into the output:
+A field the plugin cannot type is **left out of the model and named in a
+warning** rather than silently dropped:
 
-```json
-{
-  "__className": "my_app",
-  "__filePath": "../../../app/samples/my_app.js",
-  "username": "Alice",
-  /* ... */
-}
+```
+[defineApp] ZCL_ORDER: these fields are NOT part of the model —
+  total has no ABAP type: null, undefined and an empty array carry none.
+  Give it a value, or declare it with t.table(…) / t.packed(…).
 ```
 
-On deserialization, `__filePath` is resolved and `require()`d, then a new instance is created and populated with `Object.assign`.
-
-`__filePath` is determined by the class lookup in `z2ui5_cl_util`. It searches, in order (first hit wins):
-
-1. Framework built-ins: `core/srv/z2ui5/01/04/` and `core/srv/z2ui5/02/`
-2. The core package's app folder, including the bundled samples: `core/srv/app/` + `core/srv/app/samples/`
-3. Directories registered at runtime via `z2ui5_cl_util.register_app_dir(dir)` — shortcut: `require("abap2UI5/register-apps")(dir)`; the project's own `srv/app/` is registered this way in `srv/server.js`
-4. Directories listed in the `Z2UI5_APP_DIRS` environment variable
-
-All directories are searched **recursively**; within one directory, a file at the top level wins over one in a subfolder. Classes registered directly via `z2ui5_cl_util.register_app_class(name, Cls)` bypass the filesystem entirely (that's how the [browser playground](./playground) works without a filesystem).
-
-::: warning File name = class name
-The lookup matches files by name, so a class is only found (and reloadable after a roundtrip) if its file is named `<className>.js` and lives in one of the paths above. If reloading fails, this convention is the first thing to check.
-:::
-
-## Database backend
-
-CAP-typically this is covered by your `cds.requires.db` driver:
-
-- **`@cap-js/sqlite`** in dev (`npx cds w` automatically starts an in-memory SQLite)
-- **HANA / HANA Cloud** in prod
-- **PostgreSQL** via `@cap-js/postgres`
+`null`, `undefined` and `[]` carry no type, so declare them: `t.table({…})` for
+a table, `t.packed(9, 2)` for a decimal, `t.char(3)` for a fixed-width string.
 
-The engine uses only `INSERT.into(...)` and `SELECT.one.from(...)` — all CDS service backends work.
+## What is NOT persisted
 
-## Cleanup
+Anything that is not a declared field. A value stashed on `this` inside `main`
+with no initializer at construction time is not part of the model and will be
+gone on the next roundtrip. If you want it to survive, declare it.
 
-Since every roundtrip writes a new entry into `z2ui5_t_01`, **the table grows linearly**. In production you need a cleanup strategy. Two ways:
+## It survives a restart — measured
 
-**1. CAP periodic job** (simple):
+`cold-test.mjs` is not a unit test. It starts a server, does a roundtrip,
+**SIGKILLs the process**, starts a fresh one and continues the session:
 
-```js
-// srv/cleanup.js
-const cds = require("@sap/cds");
-
-cds.on("served", () => {
-  setInterval(async () => {
-    const { z2ui5_t_01 } = cds.entities("cap2ui5");
-    const cutoff = new Date(Date.now() - 24*60*60*1000).toISOString();
-    await DELETE.from(z2ui5_t_01).where(`createdAt < '${cutoff}'`);
-  }, 60*60*1000);
-});
+```
+VERDICT  control=ok  js-app-cold-restart=true  nav-stack-cold-restart=true
 ```
 
-(Assumes you have enabled `@cds.persistence.journal` or the `cuid` aspect with `createdAt`, or are logging the time yourself in `data`.)
-
-**2. DB-side job** with your DB operator tooling, e.g. a nightly cron on HANA that deletes older rows.
-
-There is **currently no built-in cleanup** — that is intentional, because the right strategy is project-specific.
-
-## Sticky sessions
+The third case is the sharp one: the kill happens *inside a called app*, so the
+new process has to take the callee's event, unwind an app stack it never built,
+run the caller's `main` again and carry the result home. It answers
+`{CHOSEN:"red", PICKS:1}` — only reachable if the caller, the callee and the
+stack between them all came out of `cap2ui5.Drafts`.
 
-Some apps need to ensure that roundtrips arrive **strictly serially** — e.g. a wizard where step 2 must never finish before step 1:
+Had any of it lived in memory, the new process would have answered the caller's
+start state with no error anywhere. That silence is why this is a test rather
+than an assumption.
 
-```js
-this.check_sticky = true;
-client.set_session_stateful(true);
-```
+## Concurrency
 
-This sets a flag on the frontend that waits on the next click until the previous roundtrip is done — preventing race conditions for fast clickers.
+Three users interleaved in one process each get their own answer — one draft
+chain per session, no shared state, nothing to lock. `concurrency.test.mjs`
+drives exactly that.
 
-## What happens on server restart?
+## Sessions belong to their user
 
-- **Apps in the DB survive** (they're persisted).
-- **In-flight promises are lost** (logical).
-- The frontend doesn't notice — it sends its ID as usual, and the server reloads the app from the DB.
+A draft answers to the user who created it and to nobody else, with the same
+"not found" a missing draft gives. The details, and the defect that once made an
+ownerless row everybody's, are in [Database Model](../reference/database).
 
-Meaning: cap2UI5 apps are **inherently stateless on the server level** (in the sense of "no in-memory state per user"). You can scale them horizontally, as long as all instances share the same DB backend.
+## Retention
 
-## Performance tips
+Drafts older than four hours are swept on the next roundtrip. A session left
+open over lunch is fine; one left open overnight starts fresh. Both the sweep
+and the framework's willingness to resume follow the same number, and your
+[user exit](./user-exit#onroundtrip) sets it.
 
-- **Keep app instances small**: persist only what you really need for subsequent roundtrips. Reload database results fresh in `check_on_init()` instead of caching them in the app.
-- **Avoid huge arrays as fields**: 10,000 rows in `this.users` means 10,000 rows per roundtrip in the DB — that adds up.
-- **Use backed queries for tables**: bind `items` to an OData service via `set_odata_model` rather than to an app array.
+## Next
 
-→ Continue with [**Popups & Toasts**](./popups).
+- [**Database Model**](../reference/database) — the entity and the owner binding
+- [**App Lifecycle**](./lifecycle) — which branch runs when
+- [**Navigation**](./navigation) — the app stack the drafts encode
diff --git a/docs/guide/playground.md b/docs/guide/playground.md
deleted file mode 100644
index 32c03c4..0000000
--- a/docs/guide/playground.md
+++ /dev/null
@@ -1,59 +0,0 @@
-# Try It in the Browser
-
-You can explore cap2UI5 **without installing anything** — no Node.js, no CAP server, no clone. The complete stack (frontend *and* backend, including all sample apps) runs as a static site on GitHub Pages:
-
-<div style="font-size: 1.15em; margin: 1em 0;">
-
-**→ [https://cap2ui5.github.io/web-cap2UI5-build/](https://cap2ui5.github.io/web-cap2UI5-build/)**
-
-</div>
-
-Start a specific app with the same `app_start` parameter you'd use against a real CAP server:
-
-```
-https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_ui5_app_hi_world
-https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_000
-```
-
-The `z2ui5_cl_smp_app_*` samples are the transpiled abap2UI5 demo collection — a browsable cookbook of tables, forms, popups, charts, and more. The [**Sample Catalogue**](./samples) lists every one of them with a link straight into the playground.
-
-## Wait — didn't you say the backend renders the view?
-
-Yes, and that's exactly what makes this playground fun: cap2UI5's backend is **plain JavaScript with no hard CAP dependency in the hot path**. So the [builder-cap2UI5-web](https://github.com/cap2UI5/builder-cap2UI5-web) build bundles the entire backend — framework core plus all sample apps — into a single ~520 KB JS file (~115 KB gzipped, which is what a visitor actually downloads) and loads it **into the browser tab**:
-
-```
-Browser tab
-├── index.html + webapp     the unchanged UI5 frontend (UI5 from CDN)
-│      │
-│      │  still calls fetch("/rest/root/z2ui5", { method: "POST", … })
-│      ▼
-└── z2ui5-web.js            the bundled "server"
-    ├── fetch interceptor   answers /rest/root/z2ui5 in-process,
-    │                       passes everything else to the network
-    ├── framework core      the same core/srv/z2ui5 code that runs on CAP
-    ├── all sample apps     registered at build time
-    └── in-memory drafts    a Map instead of the database
-```
-
-The frontend doesn't know the difference — it POSTs to the same endpoint and gets the same responses. Every roundtrip that would normally hit your CAP server is answered inside the tab.
-
-For comparison: abap2UI5 has the same kind of twin ([abap2UI5-web](https://github.com/abap2UI5/abap2UI5-web)), but it has to ship an ABAP runtime and a WASM database to the browser (~12 MB). Because cap2UI5's backend is already JavaScript, the whole site here — bundle, webapp, everything — is about 1.1 MB, roughly a tenth of that; the backend bundle alone is a twentieth.
-
-## What it's good for
-
-- **Kicking the tires** before you install anything.
-- **Browsing the sample apps** as a live catalog next to their source in [`core/srv/app/samples/`](https://github.com/cap2UI5/cap2UI5/tree/main/core/srv/app/samples) — the [Sample Catalogue](./samples) is the index.
-- **Sharing a demo link** with colleagues.
-
-## What it's *not* {#what-its-not}
-
-- **Not a production topology.** cap2UI5's security model — UI logic and state stay on the server — obviously doesn't apply when the "server" is shipped to the client. It's a demo artifact.
-- **Sessions live in the tab.** Reload = fresh state. On a real CAP server, drafts persist in the database.
-- **Server-only features are off.** Samples that call external OData services (e.g. Northwind) or need real CAP services/destinations won't work here.
-- **Internet still required** — UI5 itself loads from the SAP CDN.
-
-The site is rebuilt automatically from the latest cap2UI5 sources by the [builder-cap2UI5-web](https://github.com/cap2UI5/builder-cap2UI5-web) repository and published to [web-cap2UI5-build](https://github.com/cap2UI5/web-cap2UI5-build). The rebuild is **event-driven**: every push to builder-cap2UI5-web's `main` runs it, and cap2UI5's sync pipeline pushes a trigger commit there after each framework change — so the playground follows the framework rather than a calendar. A weekly cron remains as a safety net, and a manual run is always possible.
-
-Every deployment is one commit in [web-cap2UI5-build](https://github.com/cap2UI5/web-cap2UI5-build), and its `BUILD_INFO.json` names the exact cap2UI5 commit the site was built from — so you can always tell what you are looking at.
-
-→ Ready for the real thing? Head to the [**Quickstart**](./getting-started) — you'll have the same apps running on a local CAP server in five minutes.
diff --git a/docs/guide/popups.md b/docs/guide/popups.md
index c0e5730..5ec4ccc 100644
--- a/docs/guide/popups.md
+++ b/docs/guide/popups.md
@@ -1,203 +1,94 @@
 # Popups & Toasts
 
-Beyond the main view, a cap2UI5 app can fill four additional UI slots: **popup** (dialog), **popover**, **message toast**, and **message box**. There are also **nested views** (two levels) for master-detail layouts.
+Four ways to put something on the screen that is not the main view.
 
-## Message toast
+## Messages
 
 ```js
-client.message_toast_display("Data saved");
+c.messageToast("saved");                 // transient, bottom of the screen
+c.messageBox("Hello " + this.name);      // a dialog with an OK button
 ```
 
-A short message that fades out automatically. Optionally with control parameters:
+Both are recorded and replayed in the order you wrote them, so two toasts arrive
+in that order.
 
-```js
-client.message_toast_display("Save failed", {
-  duration:                 5000,
-  width:                    "20em",
-  closeonbrowsernavigation: false,
-  class:                    "myToast"
-});
-```
-
-## Message box
-
-```js
-client.message_box_display("Really delete?", "warning", "Confirm delete");
-```
-
-Arguments in order: `text, type, title, styleclass, onclose, actions, emphasizedaction, initialfocus, textdirection, icon, details, closeonnavigation`.
-
-Possible `type` values: `"information"`, `"success"`, `"warning"`, `"error"`, `"confirm"`.
-
-With action buttons (e.g. confirm dialog):
+## A popup — a fragment on top of the view
 
 ```js
-client.message_box_display(
-  "Really delete?",
-  "confirm",
-  "Confirmation",
-  "",                                        // styleclass
-  client._event("DELETE_CONFIRMED"),         // onclose
-  ["Yes", "No"],                             // actions
-  "Yes"                                      // emphasizedaction
-);
-```
-
-`onclose` is an event string — when the user clicks "Yes", the event comes back as a roundtrip and you can react in `client.check_on_event("DELETE_CONFIRMED")`.
-
-## Popup (dialog)
-
-A **popup** is a second view overlaid as a modal dialog. It is a *fragment*, not a view, so the root element is `core:FragmentDefinition` instead of `mvc:View` — everything else is the ordinary builder:
+if (c.eventName === "HELP") {
+  c.popup(
+    `<core:FragmentDefinition xmlns:core="sap.ui.core" xmlns="sap.m">` +
+    `<Dialog title="Help">` +
+    `<Text text="Choose picks a colour."/>` +
+    `<beginButton><Button text="Close" press="${c.event("HELP_CLOSE")}"/></beginButton>` +
+    `</Dialog></core:FragmentDefinition>`);
+  return;
+}
 
-```js
-const popup = z2ui5_cl_ui5_view_builder.factory()
-  .ele({ n: `FragmentDefinition`, ns: `core` })
-  .a({ n: `xmlns`,      v: `sap.m` })
-  .a({ n: `xmlns:core`, v: `sap.ui.core` })
-  .a({ n: `xmlns:form`, v: `sap.ui.layout.form` });
-
-const dialog = popup.ele(`Dialog`)
-  .a({ n: `title`,        v: `Edit User` })
-  .a({ n: `afterClose`,   v: client._event(`CLOSE_DIALOG`) })
-  .a({ n: `contentWidth`, v: `30em` });
-
-dialog.ele({ n: `SimpleForm`, ns: `form` })
-  .a({ n: `editable`, b: true })
-  .ele({ n: `content`, ns: `form` })
-  .tag(`Label`).a({ n: `text`, v: `Name` })
-  .tag(`Input`).a({ n: `value`, v: client._bind_edit(this.user_name) })
-  .tag(`Label`).a({ n: `text`, v: `Role` })
-  .tag(`Input`).a({ n: `value`, v: client._bind_edit(this.user_role) });
-
-dialog.ele(`endButton`).tag(`Button`)
-  .a({ n: `text`,  v: `Save` })
-  .a({ n: `type`,  v: `Emphasized` })
-  .a({ n: `press`, v: client._event(`SAVE_USER`) });
-dialog.ele(`beginButton`).tag(`Button`)
-  .a({ n: `text`,  v: `Cancel` })
-  .a({ n: `press`, v: client._event(`CANCEL_DIALOG`) });
-
-client.popup_display(popup.stringify());
+if (c.eventName === "HELP_CLOSE") {
+  c.popupClose();
+  return;
+}
 ```
 
-::: warning `stringify()` renders the whole tree, always
-`stringify()` starts at the root of the tree, not at the node you call it on — `dialog.stringify()` and `popup.stringify()` produce the same string. Keep the root in a variable and hand *that* to `popup_display`, so the intent is visible.
-:::
-
-In subsequent roundtrips:
+A popup is a **`FragmentDefinition`**, not an `mvc:View` — that is the shape UI5
+expects here. It shares the main view's model, so `c.bind()` and `c.event()`
+work inside it exactly as they do outside.
 
-- `client.popup_close()` → closes the dialog (frontend action)
-- `client.popup_destroy()` → marks it as destroyed (server side)
-- `client.popup_model_update()` → sends only the model delta, not the entire view
+Close it with `c.popupClose()`. Changed bound data is pushed into an open popup
+automatically; you do not re-render it to refresh a value.
 
-## Popover
+## A nested view — a fragment INSIDE the main view
 
-Very similar, but anchored to a UI5 control in the main view:
+For a region of the page that changes while the rest stays put:
 
 ```js
-client.popover_display(view.stringify(), "buttonId");
-```
-
-The second argument is the ID of a control in the main view next to which the popover appears. There is no convenience helper for a "please confirm" popover — build it like any other fragment:
+c.view(
+  `<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m">` +
+  `<Shell><Page title="pick">` +
+  `<Button text="Detail" press="${c.event("DETAIL")}"/>` +
+  `<VBox id="slot"/>` +                                   // ← the receiving control
+  `</Page></Shell></mvc:View>`);
+
+// later
+if (c.eventName === "DETAIL") {
+  c.nest("slot",
+    `<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m">` +
+    `<VBox><Text text="chosen: ${c.bind("chosen")}"/>` +
+    `<Button text="Hide" press="${c.event("DETAIL_HIDE")}"/></VBox></mvc:View>`);
+  return;
+}
 
-```js
-const popover = z2ui5_cl_ui5_view_builder.factory()
-  .ele({ n: `FragmentDefinition`, ns: `core` })
-  .a({ n: `xmlns`,      v: `sap.m` })
-  .a({ n: `xmlns:core`, v: `sap.ui.core` });
-
-popover.ele(`Popover`)
-  .a({ n: `placement`, v: `Right` })
-  .a({ n: `showHeader`, b: false })
-  .tag(`Text`).a({ n: `text`, v: `Really save?` })
-  .a({ n: `class`, v: `sapUiSmallMargin` })
-  .tag(`Button`)
-  .a({ n: `text`,  v: `Yes` })
-  .a({ n: `type`,  v: `Emphasized` })
-  .a({ n: `press`, v: client._event(`CONFIRM`) });
-
-client.popover_display(popover.stringify(), "saveButtonId");
+if (c.eventName === "DETAIL_HIDE") c.nestClose();
 ```
 
-## Nested views
+The main view stays as it is; only the fragment re-renders on the next `nest`.
 
-Some layouts have **two or three views side by side** — e.g. a classic master-detail setup. cap2UI5 supports this with `nest_view_display`:
+`c.nest(into, xml, opts)` takes the receiving control's `id`, and `opts` names
+the UI5 mutators for its aggregation:
 
-```js
-// 1. main view with two containers
-client.view_display(masterView.stringify());
-
-// 2. inject detail view into the right panel
-client.nest_view_display(
-  detailView.stringify(),
-  "rightPanel",      // ID of the container control
-  "addItem",         // method to insert (e.g. "addItem", "addContent", …)
-  "removeAllItems"   // optional: method to clean up
-);
-```
-
-There is a second level (`nest2_view_display`) if you need to nest deeper — e.g. a FlexibleColumnLayout with three columns.
+| | default | when to change it |
+|---|---|---|
+| `insert` | `addContent` | `addItem` for a `List`, etc. |
+| `clear` | `removeAllContent` | `removeAllItems` for a `List` |
 
-`nest_view_destroy()` and `nest_view_model_update()` round it out.
+**Without `clear`, every call adds one more fragment.** The defaults fit a
+`Page` or a `VBox`.
 
-## Overview of UI slots
+There is exactly **one** nested slot, and `c.nestClose()` takes no argument: it
+clears that slot rather than a named one.
 
-| Slot | Display method | Update method | Destroy method |
-|---|---|---|---|
-| Main view | `view_display(xml)` | `view_model_update()` | `view_destroy()` |
-| Nested 1   | `nest_view_display(xml, id, m_ins, m_dest)` | `nest_view_model_update()` | `nest_view_destroy()` |
-| Nested 2   | `nest2_view_display(...)` | `nest2_view_model_update()` | `nest2_view_destroy()` |
-| Popup      | `popup_display(xml)` | `popup_model_update()` | `popup_destroy()` |
-| Popover    | `popover_display(xml, by_id)` | `popover_model_update()` | `popover_destroy()` |
-| Toast      | `message_toast_display(text, opts?)` | – | – |
-| Box        | `message_box_display(text, type, ...)` | – | – |
+## Which one do I want?
 
-Multiple slots in one roundtrip are allowed — e.g. "update the toast AND update the popup model".
+| | |
+|---|---|
+| a short confirmation | `messageToast` |
+| something the user must acknowledge | `messageBox` |
+| a modal that takes input or a decision | `popup` |
+| a region of the page that updates independently | `nest` |
+| a whole second screen with its own state | [navigation](./navigation) — a separate app |
 
-## Example: confirm pattern
-
-```js
-async main(client) {
-
-  if (client.check_on_init()) this.render(client);
-
-  if (client.check_on_event("DELETE")) {
-    this.show_confirm_dialog(client);
-  }
-
-  if (client.check_on_event("DELETE_CONFIRMED")) {
-    await this.do_delete();
-    client.popup_close();
-    client.message_toast_display("Deleted");
-    this.render(client);
-  }
-
-  if (client.check_on_event("DELETE_CANCELLED")) {
-    client.popup_close();
-  }
-}
-
-show_confirm_dialog(client) {
-  const popup = z2ui5_cl_ui5_view_builder.factory()
-    .ele({ n: `FragmentDefinition`, ns: `core` })
-    .a({ n: `xmlns`,      v: `sap.m` })
-    .a({ n: `xmlns:core`, v: `sap.ui.core` });
-
-  const dialog = popup.ele(`Dialog`)
-    .a({ n: `title`,        v: `Confirmation` })
-    .a({ n: `contentWidth`, v: `20em` });
-
-  dialog.tag(`Text`).a({ n: `text`, v: `Really delete entry?` });
-  dialog.ele(`endButton`).tag(`Button`)
-    .a({ n: `text`,  v: `Delete` })
-    .a({ n: `type`,  v: `Reject` })
-    .a({ n: `press`, v: client._event(`DELETE_CONFIRMED`) });
-  dialog.ele(`beginButton`).tag(`Button`)
-    .a({ n: `text`,  v: `Cancel` })
-    .a({ n: `press`, v: client._event(`DELETE_CANCELLED`) });
-
-  client.popup_display(popup.stringify());
-}
-```
+## Next
 
-→ That wraps up the concepts section. Have a look at the [**examples**](../examples/hello-world) for end-to-end apps.
+- [**Navigation**](./navigation) — when a popup is really another app
+- [**Events**](./events) — the handlers the buttons above use
diff --git a/docs/guide/project-structure.md b/docs/guide/project-structure.md
index ca54d55..8403d17 100644
--- a/docs/guide/project-structure.md
+++ b/docs/guide/project-structure.md
@@ -1,198 +1,92 @@
 # Project Structure
 
-A cap2UI5 project is a **completely ordinary CAP project** with two additional building blocks: the vendored framework package at `core/` and the static frontend under `app/z2ui5/`. This page shows what lives where and why.
+There is no cap2UI5 project layout. cap2UI5 is a **CAP plugin**, so the project
+is *your* CAP project, and the plugin adds three things to it without putting a
+single file in your repository.
 
-## Top level
+## What your project looks like
+
+An ordinary CAP project. The only cap2UI5-specific thing in it is the
+dependency and one directory:
 
 ```
-cap2UI5/
-├── app/
-│   └── z2ui5/                  # ← static UI5 frontend (read-only, synced)
+my-project/
 ├── db/
-│   └── schema.cds              # ← persistence table z2ui5_t_01
+│   └── schema.cds          # your entities
 ├── srv/
-│   ├── z2ui5-service.cds       # ← CDS service definitions
-│   ├── z2ui5-service.js        # ← service handlers
-│   ├── server.js               # ← CAP bootstrap
-│   ├── app/                    # ← your own apps (user-owned)
-│   └── external/               # ← imported external service models
-├── core/                       # ← the vendored abap2UI5 framework package
-├── test/                       # ← jest suite
-├── mta.yaml                    # ← Cloud Foundry deployment
-├── xs-security.json
-└── package.json                # ← depends on "abap2UI5": "file:./core"
+│   ├── catalog-service.cds # your services — untouched by cap2UI5
+│   ├── apps/               # ← your cap2UI5 apps, one file each
+│   │   ├── hello.js
+│   │   └── books.js
+│   └── server.js           # optional, and NOT touched by the plugin
+└── package.json            # "cap2ui5": "^x.y.z"
 ```
 
-::: info Generated repository
-The whole [cap2UI5 repository](https://github.com/cap2UI5/cap2UI5) is **generated** by [builder-cap2UI5](https://github.com/cap2UI5/builder-cap2UI5). Hand-written changes to the app skeleton belong in `builder-cap2UI5`'s `src/`; changes to the framework belong in [builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js)'s `src/`. In your **own** project, `srv/app/` (and your own services) are of course yours to edit.
-:::
-
-## `srv/z2ui5-service.cds` — the service
-
-The file declares two services. The first (`AdminService`) is optional — it is the "normal" CDS interface for external OData consumers. The second (`rootService`) is the **heart of cap2UI5**:
-
-```cds
-@protocol: 'rest'
-service rootService {
+`examples/bookshop` in the [cap2UI5 repository](https://github.com/cap2UI5/cap2UI5)
+is exactly this and nothing more.
 
-    @open
-    type object {};
+## What the plugin adds at runtime
 
-    action z2ui5(value : object) returns object;
+CAP loads `cds-plugin.js` from every dependency that has one. On `cds watch`
+that gives you:
 
-}
-```
+| | where it comes from |
+|---|---|
+| `/sap/bc/z2ui5`, `/rest/root/z2ui5` | the roundtrip route, mounted behind CAP's own middleware chain |
+| `/z2ui5/webapp/` | the UI5 shell, served **out of the runtime package** — not copied, not generated, not yours to maintain |
+| `cap2ui5.Drafts` | a CDS entity contributed through `package.json#cds.requires`, so `cds deploy` creates it next to your own tables |
 
-A single action `z2ui5(value)` — the entire roundtrip runs through here. CAP itself automatically exposes it under `POST /rest/root/z2ui5`.
+None of this appears in your working tree. There is nothing to regenerate, no
+vendored folder, no sync pipeline. Upgrading is `npm update cap2ui5`.
 
-→ More in [HTTP Protocol](../reference/protocol).
+## `srv/apps/` — the one directory that is yours
 
-## `srv/z2ui5-service.js` — the handler
+Every `.js`, `.mjs` or `.cjs` file in it is loaded once the runtime is up. A
+file is not special in any way: it just calls `defineApp`, and it may call it
+more than once.
 
 ```js
-const cds = require("@sap/cds");
-const z2ui5_cl_ui5_http_handler = require("abap2UI5/z2ui5_cl_ui5_http_handler");
+// srv/apps/pick.js — two apps in one file is fine
+const { defineApp } = require("cap2ui5");
 
-module.exports = cds.service.impl(async function (srv) {
-  srv.on("z2ui5", z2ui5_cl_ui5_http_handler);
-  // … your own READ/CREATE/etc. handlers go here
-});
+defineApp("ZCL_PICK",     class { /* … */ });
+defineApp("ZCL_PICK_ONE", class { /* … */ });
 ```
 
-One line wires the action up to the framework handler. Any additional service handlers you add here continue to run normally.
-
-## `srv/server.js` — the bootstrap
-
-CDS REST actions only understand POST, so `server.js` registers two extra routes on CAP's `bootstrap` event:
-
-- `GET /rest/root/z2ui5` — delivers the bootstrap HTML (with security headers, theme, and CSP resolved through the framework's exit/config mechanism, mirroring abap2UI5's `_http_get`)
-- `HEAD /rest/root/z2ui5` — answers the frontend's CSRF prefetch
-
-It also serves the local UI5 runtime at `/resources` and injects the CAP-backed draft store into the framework engine. You rarely need to touch this file — except to [register your own app directories](#srv-app).
+The **first argument to `defineApp` is the name on the wire** — what
+`?app_start=` takes and what `c.navTo()` resolves. The file name is irrelevant.
 
-## `db/schema.cds` — the persistence
-
-```cds
-namespace cap2ui5;
-
-entity z2ui5_t_01 {
-  key id      : UUID;
-  id_prev     : UUID;
-  data        : LargeString;
-}
-```
-
-This is where the **serialized app instances** land between roundtrips. Every response contains the new `id`, which the frontend sends along on the next call — the server uses it to reload the app and apply the frontend delta.
-
-→ Details in [Database Model](../reference/database).
-
-## `core/` — the framework
-
-The framework is a **vendored npm package** named `abap2UI5`, wired up as an ordinary dependency in `package.json`:
+To put apps somewhere else, point the plugin at it:
 
 ```json
-"dependencies": {
-  "abap2UI5": "file:./core"
-}
-```
-
-```
-core/                                        # npm package "abap2UI5"
-├── package.json                             # exports map for require("abap2UI5/…")
-├── app/
-│   └── z2ui5/webapp/                        # frontend source (mirrored to app/z2ui5/)
-└── srv/
-    ├── app/
-    │   └── samples/                         # bundled demo apps (pipeline-owned)
-    └── z2ui5/
-        ├── 00/                              # pure utilities (ajson, sorting, util)
-        │   └── 03/z2ui5_cl_util.js          # RTTI / class lookup / app registry
-        ├── 01/                              # core plumbing
-        │   ├── 01/z2ui5_cl_ui5_srv_draft.js   # serialize / DB persistence
-        │   ├── 02/z2ui5_cl_ui5_handler.js     # roundtrip orchestrator
-        │   ├── 02/z2ui5_cl_ui5_client.js      # the client class (your API)
-        │   ├── 02/z2ui5_cl_ui5_srv_bind.js    # _bind / _bind_edit implementation
-        │   ├── 02/…                            # action, model, event services
-        │   ├── 03/z2ui5_cl_ui5f_index_html.js   # bootstrap HTML as a JS module
-        │   └── 04/                          # the apps the framework ships
-        │       ├── z2ui5_cl_ui5_app_start.js    # built-in launcher
-        │       ├── z2ui5_cl_ui5_app_hi_world.js # mini example
-        │       └── z2ui5_cl_ui5_user_exit.js    # config hook (theme, CSP, headers)
-        ├── 02/                              # public API
-        │   ├── z2ui5_if_app.js              # base class for apps
-        │   ├── z2ui5_if_client.js           # the client contract (constants)
-        │   ├── z2ui5_cl_ui5_http_handler.js # CDS action adapter
-        │   └── z2ui5_cl_ui5_view_builder.js # view builder
-        ├── engine.js                        # platform-neutral surface (roundtrip, bootstrap, ports)
-        └── register-apps.js                 # convenience hook for external app repos
+{ "cds": { "cap2ui5": { "apps": "srv/my-apps" } } }
 ```
 
-The numbering `00/`, `01/`, `02/` mirrors the abap2UI5 layering (see [Where cap2UI5 comes from](./where-it-comes-from)) — those three are all there is:
+See [Configuration](../reference/configuration) for the rest of the knobs.
 
-- **`00/`** — pure utilities, no dependencies into the system
-- **`01/`** — core plumbing (persistence, handler, binding engine, HTML bootstrap) plus the shipped apps in `01/04/`
-- **`02/`** — everything app developers **import directly**
+## Where the framework actually lives
 
-As an app developer you almost always need exactly two imports, via the package's exports:
+In `node_modules`, in two packages, and you own neither:
 
-```js
-const z2ui5_if_app              = require("abap2UI5/z2ui5_if_app");
-const z2ui5_cl_ui5_view_builder = require("abap2UI5/z2ui5_cl_ui5_view_builder");
-```
+| | |
+|---|---|
+| `cap2ui5` | the plugin — ~770 lines, of which 485 are code. `cds-plugin.js`, `index.cds`, `lib/` |
+| `@abap2ui5/runtime` | abap2UI5 itself: upstream's ABAP, downported and transpiled over open-abap, plus the UI5 shell. 1,244 transpiled files |
 
-(The package is named `abap2UI5` and linked into the project via `"abap2UI5": "file:./core"` — a real, vendored dependency. Requires like `require("abap2UI5/z2ui5_if_app")` resolve through the exports map in `core/package.json`, and external app repos can depend on the same package the same way.)
+That split is the whole design. The plugin is a **host**: it mounts a route,
+implements the draft store over a CDS entity, and turns a JavaScript class into
+something the runtime can call. It contains no framework logic, which is why it
+cannot drift from abap2UI5 — see [Architecture](../reference/architecture).
 
-::: warning Hands off the framework tree
-`core/` is generated by [builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js) and refreshed by the [sync pipeline](./where-it-comes-from#how-the-port-actually-works). Treat it as a library: read it, learn from it, but don't edit it.
+::: info The repository is not the product
+[`cap2UI5/cap2UI5`](https://github.com/cap2UI5/cap2UI5) holds `plugin/` (the
+package), `examples/bookshop` (a project that uses it) and `runtime/` (where
+`@abap2ui5/runtime` is assembled until it is on npm). You consume the package;
+you do not clone the repository — unless you are working on cap2UI5 itself.
 :::
 
-## `srv/app/` — your apps and the bundled demos {#srv-app}
-
-This is where **your own** app files go: a folder of `*.js` files, each containing _one_ app class. Convention: **file name = class name**. It is scanned automatically (registered in `srv/server.js` via `engine.register_app_dir(...)`), is not touched by the sync workflows, and ships with `z2ui5_cl_app_read_odata.js` as a starting point.
-
-The framework additionally bundles over a hundred `z2ui5_cl_smp_app_*` classes under `core/srv/app/samples/` — the transpiled [abap2UI5 samples](https://github.com/abap2UI5/samples), a live cookbook you can start via `?app_start=z2ui5_cl_smp_app_000` etc. Note that the sync pipeline owns that folder: it is overwritten on every upstream sync — keep your own files in `srv/app/` (or a registered folder) instead.
-
-The class lookup searches, in order:
-
-1. Framework built-ins (`core/srv/z2ui5/01/04/`, `core/srv/z2ui5/02/`)
-2. The core package's app folder, including the bundled samples (`core/srv/app/` + `core/srv/app/samples/`)
-3. Directories registered at runtime via `z2ui5_cl_util.register_app_dir(dir)` — or the shortcut `require("abap2UI5/register-apps")(dir)`; the project's `srv/app/` is registered this way in `srv/server.js`
-4. Directories in the `Z2UI5_APP_DIRS` environment variable (path-separated list)
-
-All directories are searched **recursively**, so you can organize your apps in subfolders. There is also `z2ui5_cl_util.register_app_class(name, Cls)` to register a class directly without any filesystem lookup — that's the hook the [browser playground](./playground) uses.
-
-## `app/z2ui5/` — the frontend
-
-A **finished, static** UI5 webapp, mirrored 1:1 from [abap2UI5](https://github.com/abap2UI5/abap2UI5)'s `app/webapp` folder by the sync pipeline (via the core package's `core/app/z2ui5/webapp/`). You don't touch it; upstream updates flow in automatically. CAP serves it at `/z2ui5/webapp/`.
-
-Only two values are cap2UI5-specific and get patched in during the sync (no locally maintained copies):
-
-- the UI5 **bootstrap URL** in `index.html` (points at the server's local `/resources` runtime)
-- the **`/rest/root/z2ui5` data source** in `manifest.json`
-
-## `package.json` — the configuration
-
-Look at the `cds.requires` block:
-
-```json
-"cds": {
-  "requires": {
-    "northwind": {
-      "kind": "odata-v2",
-      "model": "srv/external/northwind",
-      "credentials": {
-        "url": "https://services.odata.org/V2/Northwind/Northwind.svc/"
-      }
-    }
-  },
-  "destinations": true,
-  "html5-repo": true,
-  "workzone": true
-}
-```
-
-You declare external services as usual and call them from your apps via `cds.connect.to(...)`. See the Northwind example under [External OData](../examples/external-odata).
-
-Also note the `"abap2UI5": "file:./core"` dependency — together with the `exports` map in `core/package.json` it's what makes the `require("abap2UI5/…")` imports work, both inside the project and for external app repositories.
+## Next
 
-→ Continue to the [**App Lifecycle**](./lifecycle).
+- [**Configuration**](../reference/configuration) — routes, authentication, the apps directory
+- [**Persistence & Sessions**](./persistence) — `cap2ui5.Drafts`
+- [**Architecture**](../reference/architecture) — what runs where, and why there is no port any more
diff --git a/docs/guide/roadmap.md b/docs/guide/roadmap.md
index 17fde6b..ff3cc2f 100644
--- a/docs/guide/roadmap.md
+++ b/docs/guide/roadmap.md
@@ -1,155 +1,93 @@
 # Roadmap
 
-Where cap2UI5 is going, and — more usefully — what is limited today. No dates:
-this is a small project with an automated pipeline, and work lands when it
-lands. What follows is the order of intent, not a schedule.
+Where cap2UI5 is, what is limited today, and what is intended. No dates.
 
 ::: tip How to read this
-Anything under **Known limits today** is true of the current build. Anything
-under **What's next** is intended, not promised. If a limit matters to your
-project, it is worth checking the
-[cap2UI5 issues](https://github.com/cap2UI5/cap2UI5/issues) before you build
-around it.
+**Known limits today** is true of the current build. **What's next** is
+intended, not promised. If a limit matters to your project, check the
+[issues](https://github.com/cap2UI5/cap2UI5/issues) before you build around it.
 :::
 
+## What just changed
+
+cap2UI5 stopped being a hand-written JavaScript port of abap2UI5 and became a
+**CAP plugin that hosts abap2UI5's own runtime**. That retired the largest
+limitation this page used to carry — and it retired the pipelines, the vendored
+core and 82,804 lines of generated code with it. The reasoning and the
+measurements are in [Where cap2UI5 Comes From](./where-it-comes-from).
+
 ## Known limits today
 
-### Getting a project started
-
-There is no supported way to *start* a cap2UI5 project other than cloning the
-generated [cap2UI5](https://github.com/cap2UI5/cap2UI5) repository and writing
-your apps into [`srv/app/`](./project-structure#srv-app). The framework is
-vendored inside that repository at `core/`; it is not on the public npm
-registry, so `npm install` cannot pull it into an existing CAP project. This is
-the single biggest gap and the one most of the work below serves.
-
-### One process, one session
-
-State that survives a roundtrip lives in the draft table, but the *sticky*
-handler that answers consecutive requests from one browser tab is held in the
-process that answered the first one. There is no session affinity and no shared
-handler store, so **running more than one instance can lose state
-intermittently** — which is why the Cloud Foundry descriptor declares a single
-instance. Horizontal scaling waits on either affinity or a shared sticky store.
-Two tabs of the same user share one sticky slot, too, so a second tab can
-disturb the first.
-
-Concurrency inside one session is not guarded either: two roundtrips answered at
-the same time fork the draft chain silently rather than failing.
-
-### Pinned versions
-
-- **abap2UI5 1.142.0.** The port pins one upstream release; `static version` on
-  `z2ui5_if_app` says which. Upstream material written against a later release
-  can disagree with what runs here — most visibly `_bind` and `_bind_edit`,
-  which are still two different bindings on 1.142.0. See
-  [Migrating from abap2UI5](./migration-from-abap2ui5#binding).
-- **OpenUI5 1.113.0**, served locally. Newer UI5 controls and properties are
-  not available. The pin is deliberately excluded from automated dependency
-  updates: moving it is a compatibility decision about which UI5 releases the
-  framework supports, not a routine bump.
-
-### Not everything upstream ships is here
-
-cap2UI5 deliberately does not carry abap2UI5's frozen legacy package, so
-`z2ui5_cl_xml_view`, its custom-control decorator and the built-in `z2ui5_cl_pop_*`
-popups do not exist here — an old upstream sample can fail on the import alone.
-That is a decision, not a backlog item; the detail is on
-[cap2UI5 vs. abap2UI5](./vs-abap2ui5).
-
-Beyond that, a number of transpiled framework internals still carry
-`TODO(abap2js)` markers where an ABAP construct has no finished JavaScript
-equivalent — mostly in runtime type introspection. The common paths are
-exercised by the whole sample suite on every sync, but the corners are real.
-
-The one limit you are most likely to meet is not a TODO but a language
-difference: because JavaScript has no reference to a field, `_bind` identifies
-*which* attribute you meant by the value you passed, so two attributes holding
-the same value are ambiguous. [Data Binding](./data-binding#reference-equality)
-explains the workaround — pass the path explicitly.
-
-### BTP deployment
-
-The Cloud Foundry deployment descriptor ships and is documented
-([Deployment](../reference/deployment)), but it is exercised by far less
-automation than the local path. Treat a first BTP rollout as something to
-verify end to end rather than assume.
+### The two packages are not on npm yet
+
+`npm i cap2ui5` answers **404**, and so does `@abap2ui5/runtime`. Both are
+published from a release that has not been cut. Until then the route is the
+repository — see the box in the [Quickstart](./getting-started).
+
+This is the single biggest gap, and the only work item between here and a
+`npm i` that just works.
+
+### The facade does not cover everything
+
+`c` covers views, popups, nested views, navigation, messages, event arguments
+and nested state. Everything else lives behind `c.raw`, which is the full
+`z2ui5_if_client` — async, and under its original ABAP names. That is a real
+escape hatch rather than a placeholder, but a method used often enough deserves
+a facade member.
+
+### The apps are JavaScript, and so are the errors
+
+A mistyped field name throws at runtime, not at edit time. `c.bind("nmae")`
+tells you the known fields, and an untypeable field is named in a warning — but
+there is no type checking across your app, and the TypeScript story is
+unwritten.
+
+### UI5 comes from the CDN, and only from the CDN
+
+The plugin serves the abap2UI5 shell, not UI5 itself: the page bootstraps from
+`sdk.openui5.org`, and there is no local `/resources` route to fall back to. A
+server without outbound internet access renders nothing until you host a UI5
+distribution yourself and point `cfg.src` at it in a
+[user exit](./user-exit#onpage). Shipping a local copy in the plugin is open.
+
+The browser test follows the same road: it renders against the CDN, and where
+there is none it answers the CDN's requests from a local `openui5-dist` — so a
+control introduced after that fallback's release is covered by a CDN run and
+not by a sandboxed one.
+
+### The documentation is mid-migration
+
+The plugin merged and this site is catching up. The entry points, the concept
+guides, the reference and the examples describe the plugin. A handful of
+background pages may still carry the port's mechanics; if a page contradicts
+[Architecture](../reference/architecture), the architecture page is right.
 
 ## What's next
 
-### Distribution — making `npm install` work
-
-The intent is that a CAP developer can adopt cap2UI5 without ever seeing the
-build pipeline: install a published package into an existing project, add a
-plugin entry, write one class. That means publishing the core to the public
-registry under a real version, and shipping a CAP plugin that contributes the
-service, the bootstrap and the draft wiring on its own — replacing today's
-hand-copied `srv/server.js` and `srv/z2ui5-service.cds` skeleton. A template or
-scaffold would then be the recommended way to start, and the generated
-repository becomes the demo rather than the delivery mechanism.
-
-### Security defaults
-
-The principle is that the defaults should be safe when nobody configures
-anything, and the work is closing what is left between that and what ships.
-The 2026-08 pass moved several settings onto that footing: the CSRF
-gate is on by default (see [The User Exit](./user-exit#csrf)), security headers
-are applied to the roundtrip and OData responses rather than only to the
-bootstrap page, the roundtrip has an explicit body-size cap, and the
-authorisation scope the app declares is enforced on the endpoint — so a
-deployment now needs the role assigned, not merely defined.
-
-What is *not* solved is the multi-instance state problem above: an honest
-single-instance deployment is the current answer, not a shared store. The
-[Deployment](../reference/deployment) page carries the operational detail as it
-changes.
-
-### Types
-
-Hand-written type definitions for the top of the API — `client`,
-`z2ui5_if_app`, `z2ui5_cl_ui5_view_builder` — so that editors complete the
-builder chain instead of guessing. A fluent chain is the API most improved by
-completion, and it is the one you write most.
-
-### Playground
-
-The [browser playground](./playground) runs the whole stack in a tab. Two things
-would make it a genuinely better front door: a landing page that lists the
-samples instead of requiring a hand-typed class name (the
-[Sample Catalogue](./samples) is the documentation half of that), and an in-tab
-editor that registers a class you wrote yourself — write a class, run it,
-without installing anything. The engine already supports registering a class
-directly, so this is a tooling question rather than a framework one.
-
-### Keeping up with abap2UI5
-
-The port tracks a fast-moving upstream through an automated transpile pipeline.
-The work here is less about features than about alarms: making divergence from
-upstream a visible check rather than something discovered by a user, and
-carrying upstream's own deprecations through instead of having classes quietly
-appear and vanish between releases.
+**Publish the packages.** `@abap2ui5/runtime` from upstream's release build,
+then `cap2ui5`. Everything else is downstream of this.
 
-## What is deliberately not planned
+**Pin the runtime by default.** Once it is on npm, `^X.Y.Z` instead of `*`, so
+a project gets a known framework rather than the newest one.
+
+**Grow the facade where use shows it is needed** — driven by real apps rather
+than by completing a table.
 
-- **A named frontend action API.** Upstream has parked that design space; the
-  port will not invent a competing one.
-- **Carrying the frozen legacy classes.** See above — an npm package has no
-  installed base to protect, which is exactly why they were dropped.
-- **Divergence from the wire protocol.** The frontend is shared with abap2UI5
-  byte for byte, and staying protocol-compatible is what makes the same app
-  deployable in both worlds.
+**Finish this documentation**, including a page on writing an app against
+`c.raw` when the facade does not reach.
+
+## What is deliberately not planned
 
-## Where the real backlog lives
+**A cap2UI5 view builder.** Views are UI5 XML strings; a template literal is
+shorter and clearer than a fluent chain in JavaScript. abap2UI5's builder is in
+the runtime and reachable through `c.raw` if you want it.
 
-This page is a summary written for people *using* cap2UI5. The working plans
-live with the code, in each repository's issues and `AGENTS.md`:
+**A second implementation of anything upstream owns.** The whole point of the
+current design is that there is one implementation of the framework. A feature
+that belongs in abap2UI5 belongs upstream, where it also reaches every ABAP
+user — the four seams and a bug fix went that way already.
 
-| | |
-|---|---|
-| the app, and the framework as delivered | [cap2UI5/cap2UI5](https://github.com/cap2UI5/cap2UI5) |
-| transpiler and core build | [builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js) |
-| app assembly and publishing | [builder-cap2UI5](https://github.com/cap2UI5/builder-cap2UI5) |
-| the browser playground | [builder-cap2UI5-web](https://github.com/cap2UI5/builder-cap2UI5-web) |
-| this site | [cap2UI5/docs](https://github.com/cap2UI5/docs) |
+## Next
 
-[The Ecosystem](./ecosystem) explains how those fit together.
+- [**Where cap2UI5 Comes From**](./where-it-comes-from) — the change of strategy
+- [**Architecture**](../reference/architecture) — what the plugin is and is not
diff --git a/docs/guide/samples.md b/docs/guide/samples.md
deleted file mode 100644
index 3e4929f..0000000
--- a/docs/guide/samples.md
+++ /dev/null
@@ -1,243 +0,0 @@
-<!-- GENERATED by scripts/gen-samples.mjs — do not edit by hand. -->
-<!-- Regenerate with: CAP2UI5_DIR=/path/to/cap2UI5 npm run gen:samples -->
-
-# Sample Catalogue
-
-The framework ships 105 sample apps in `core/srv/app/samples/` — the abap2UI5 demo collection, transpiled to JavaScript. 98 of them are listed in the built-in gallery, and this page is that gallery's own table: it is generated from `z2ui5_cl_smp_app_000`, the sample browser the framework itself renders, so it cannot drift from what the playground offers.
-
-Every title links into the [browser playground](./playground) — no install, no server. The same apps run on your own CAP server under the same names: `?app_start=<class>`, or `client.nav_app_call()` from an app of your own.
-
-→ Prefer to browse in the app itself? Open [`z2ui5_cl_smp_app_000`](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_000) — the same catalogue with a search field.
-
-Two markers are carried over from the upstream gallery: **(A)** marks a sample that drives the frontend through a client action, **(C)** one that uses a custom control from the `z2ui5.cc` namespace.
-
-## Categories
-
-[Basics](#basics) · [Binding](#binding) · [Browser](#browser) · [Control Behaviour](#control-behaviour) · [CSS](#css) · [Device](#device) · [Event](#event) · [File](#file) · [Focus](#focus) · [Formatter](#formatter) · [Grid Table](#grid-table) · [List](#list) · [Menu](#menu) · [Message](#message) · [Navigation](#navigation) · [Nested View](#nested-view) · [Popover](#popover) · [Popup](#popup) · [Scroll](#scroll) · [Table](#table) · [Templating](#templating) · [Timer](#timer) · [Tree](#tree)
-
-## Basics
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Hello World, the Smallest App](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_493) | [`z2ui5_cl_smp_app_493`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_493.js) | hello world smallest first app minimal start here template |
-| [Data Binding: Input and Button](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_494) | [`z2ui5_cl_smp_app_494`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_494.js) | binding _bind model attribute value input button serialize |
-| [Lifecycle: Init, Event, Navigated](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_495) | [`z2ui5_cl_smp_app_495`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_495.js) | lifecycle roundtrip main dispatcher state serialize check_on_init check_on_event check_on_navigated |
-| [Events, Views and Roundtrips](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_004) | [`z2ui5_cl_smp_app_004`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_004.js) | roundtrip restart second view uncaught error controller basics |
-| [The Developer Tools (Ctrl+F12)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_496) | [`z2ui5_cl_smp_app_496`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_496.js) | developer tools devtools ctrl f12 debug inspect payload previous request response view xml view model source code log error adt export |
-
-## Binding
-
-| Sample | Class | Topics |
-|---|---|---|
-| [A View Built From RTTI, No Field Named](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_497) | [`z2ui5_cl_smp_app_497`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_497.js) | rtti generic view runtime columns get_components describe_by_data no field name itab structure column cell binding |
-| [Currency Amounts (sap.ui.model.type.Currency)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_067) | [`z2ui5_cl_smp_app_067`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_067.js) | amount decimals leading zeros number format |
-| [Dynamic Table Typed at Runtime (RTTI)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_061) | [`z2ui5_cl_smp_app_061`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_061.js) | generic data reference create data ddic dynamic itab |
-| [Expression Binding, Types and Composite Parts](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_027) | [`z2ui5_cl_smp_app_027`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_027.js) | formatter parts conditional regexp visible enabled syntax |
-| [Model setSizeLimit for Large Tables (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_071) | [`z2ui5_cl_smp_app_071`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_071.js) | combobox jsonmodel size limit large itab 100 entries |
-| [Single Table Cell (tab_index)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_144) | [`z2ui5_cl_smp_app_144`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_144.js) | cell input internal table row field level |
-| [Structure Fields and INCLUDEs](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_166) | [`z2ui5_cl_smp_app_166`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_166.js) | structure component include flat form level |
-| [Types for Integer, Decimal, Date and Time](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_047) | [`z2ui5_cl_smp_app_047`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_047.js) | type conversion sum amount number field |
-
-## Browser
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Copy to Clipboard (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_325) | [`z2ui5_cl_smp_app_325`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_325.js) | clipboard paste copy text area |
-| [Local and Session Storage (A,C)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_327) | [`z2ui5_cl_smp_app_327`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_327.js) | localstorage sessionstorage persist store_data offline |
-| [Logout from the Client (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_361) | [`z2ui5_cl_smp_app_361`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_361.js) | logoff signout icf session end fiori launchpad |
-| [Open a URL in a New Tab (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_073) | [`z2ui5_cl_smp_app_073`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_073.js) | url window open_new_tab link target |
-| [Open Mail, Phone and SMS Links (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_316) | [`z2ui5_cl_smp_app_316`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_316.js) | mailto tel sms urlhelper redirect native link |
-| [Reload the Page (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_492) | [`z2ui5_cl_smp_app_492`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_492.js) | reload refresh restart location_reload url |
-| [Set the Tab Favicon (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_491) | [`z2ui5_cl_smp_app_491`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_491.js) | favicon icon tab image data uri |
-| [Set the Tab Title (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_125) | [`z2ui5_cl_smp_app_125`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_125.js) | document.title tab caption headline set_title |
-| [Soft Keyboard Mode on Mobile (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_352) | [`z2ui5_cl_smp_app_352`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_352.js) | mobile numeric keypad keyboard_set_mode phone input |
-
-## Control Behaviour
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Expand a Panel by ID (setExpanded) (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_448) | [`z2ui5_cl_smp_app_448`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_448.js) | panel collapse expand setexpanded control_by_id whitelisted |
-| [MultiInput with Tokens (C)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_078) | [`z2ui5_cl_smp_app_078`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_078.js) | multiinput token tokens suggestion custom control |
-| [Open the PDF Viewer by ID (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_449) | [`z2ui5_cl_smp_app_449`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_449.js) | pdfviewer pdf document viewer popup control_by_id whitelisted |
-| [Switch NavContainer Page by ID (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_088) | [`z2ui5_cl_smp_app_088`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_088.js) | navcontainer icontabbar icontabheader page switch control_by_id whitelisted |
-| [Wizard with Steps (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_202) | [`z2ui5_cl_smp_app_202`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_202.js) | wizard step branching discardprogress setnextstep control_by_id |
-
-## CSS
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Color Table Cells from the Backend](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_305) | [`z2ui5_cl_smp_app_305`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_305.js) | color background conditional formatting style data attribute |
-| [FlexBox Layouts with Custom Classes](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_255) | [`z2ui5_cl_smp_app_255`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_255.js) | flexbox layout responsive navigation tile panel |
-| [Ship Your Own CSS with the View](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_050) | [`z2ui5_cl_smp_app_050`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_050.js) | style stylesheet inline html class own design |
-
-## Device
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Camera, Take Photos (C)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_306) | [`z2ui5_cl_smp_app_306`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_306.js) | camera photo picture webcam capture facing mode |
-| [Device Model: Phone, Tablet, Desktop (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_445) | [`z2ui5_cl_smp_app_445`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_445.js) | sap.ui.device responsive orientation resize media model |
-| [Frontend Info: UI5 Version, Theme, OS, Browser](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_122) | [`z2ui5_cl_smp_app_122`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_122.js) | client info ui5 version theme os user agent device |
-| [Geolocation from the Browser (C)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_120) | [`z2ui5_cl_smp_app_120`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_120.js) | gps position latitude longitude altitude location |
-
-## Event
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Control Objects in t_arg (FacetFilter)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_197) | [`z2ui5_cl_smp_app_197`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_197.js) | facetfilter filter object marshalling selected items |
-| [Extra Arguments with t_arg](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_167) | [`z2ui5_cl_smp_app_167`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_167.js) | argument parameter payload event data fixed value |
-| [Keyboard Shortcuts, Ctrl+S (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_471) | [`z2ui5_cl_smp_app_471`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_471.js) | shortcut hotkey ctrl key combination keyboard_shortcut |
-| [Link with preventDefault (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_472) | [`z2ui5_cl_smp_app_472`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_472.js) | link href default action check_prevent_default |
-
-## File
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Download to the Browser (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_186) | [`z2ui5_cl_smp_app_186`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_186.js) | export save base64 attachment xstring document |
-| [Upload to the Backend (C)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_074) | [`z2ui5_cl_smp_app_074`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_074.js) | fileuploader base64 attachment import picture document |
-
-## Focus
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Focus a Table Cell by Column and Row (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_421) | [`z2ui5_cl_smp_app_421`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_421.js) | table cell column row aggregation set_focus |
-| [Jump to the Next Input on Enter (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_189) | [`z2ui5_cl_smp_app_189`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_189.js) | cursor enter tab next field form set_focus |
-| [Set Focus and Select Text in an Input (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_133) | [`z2ui5_cl_smp_app_133`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_133.js) | cursor set_focus selection position textfield |
-
-## Formatter
-
-| Sample | Class | Topics |
-|---|---|---|
-| [ABAP Date and Time Strings (DATS/TIMS)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_450) | [`z2ui5_cl_smp_app_450`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_450.js) | dats tims conversion initial date 00000000 sy-datum |
-| [Date Object for the DatePicker](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_457) | [`z2ui5_cl_smp_app_457`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_457.js) | datepicker datevalue javascript date object iso |
-| [Date Objects for the PlanningCalendar](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_456) | [`z2ui5_cl_smp_app_456`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_456.js) | planningcalendar appointment javascript date object iso |
-| [Inline Icons in a Text](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_466) | [`z2ui5_cl_smp_app_466`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_466.js) | icon glyph placeholder text status expandinlineicons |
-| [When Not to Use One: Compute in ABAP](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_453) | [`z2ui5_cl_smp_app_453`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_453.js) | no formatter computed backend thin frontend prepare |
-
-## Grid Table
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Events on Cell Level](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_160) | [`z2ui5_cl_smp_app_160`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_160.js) | cell enter row index event grid alv |
-| [Full Example with sap.ui.table](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_070) | [`z2ui5_cl_smp_app_070`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_070.js) | grid alv dynamicpage column row action currency search sort filter |
-| [Keep Column Filters on Refresh (C)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_143) | [`z2ui5_cl_smp_app_143`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_143.js) | column filter reset refresh uitableext grid alv |
-
-## List
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Filter and Sort the Binding from ABAP (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_454) | [`z2ui5_cl_smp_app_454`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_454.js) | binding_call getbinding sorter filter follow_up_action |
-| [Live Filter on the Client, No Roundtrip (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_455) | [`z2ui5_cl_smp_app_455`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_455.js) | binding_call live search client side no roundtrip filter |
-| [StandardListItem, Highlight and Events](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_048) | [`z2ui5_cl_smp_app_048`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_048.js) | sap.m.list standardlistitem highlight infostate press selection |
-
-## Menu
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Full Path of the Selected Item (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_473) | [`z2ui5_cl_smp_app_473`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_473.js) | menuitem nested submenu textpath controller path |
-| [Menu Button with core:require](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_163) | [`z2ui5_cl_smp_app_163`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_163.js) | menubutton menuitem popover messagetoast require module |
-
-## Message
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Message Model and MessageManager (C)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_467) | [`z2ui5_cl_smp_app_467`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_467.js) | messagemanager validation target field state central model |
-| [MessageBox from SY, BAPIRET2 or Exception](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_008) | [`z2ui5_cl_smp_app_008`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_008.js) | t100 message class number exception cx_root error abend |
-| [MessageBox, Types and Custom Actions](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_382) | [`z2ui5_cl_smp_app_382`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_382.js) | confirm warning error success information dialog action |
-| [MessagePopover URL Policy (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_474) | [`z2ui5_cl_smp_app_474`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_474.js) | url policy link security validator relative allow deny |
-| [MessageToast, Text and Duration](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_381) | [`z2ui5_cl_smp_app_381`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_381.js) | toast notification duration position animation |
-| [MessageView and MessagePopover (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_452) | [`z2ui5_cl_smp_app_452`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_452.js) | messagepopover messageitem dialog grouped message list |
-
-## Navigation
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Call and Leave Apps (nav_app_call)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_024) | [`z2ui5_cl_smp_app_024`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_024.js) | nav_app_call nav_app_leave sub app stack call back |
-| [Data Loss Protection on Leaving (A,C)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_279) | [`z2ui5_cl_smp_app_279`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_279.js) | dirty unsaved changes leave confirmation warning |
-| [Return Data and Events to the Caller](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_488) | [`z2ui5_cl_smp_app_488`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_488.js) | r_data result get_app_prev return event payload |
-| [Uncaught Error and Error Popup](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_464) | [`z2ui5_cl_smp_app_464`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_464.js) | exception dump error handling debugtool restart retry |
-
-## Nested View
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Basic Example (nest_view_display)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_065) | [`z2ui5_cl_smp_app_065`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_065.js) | nest_view_display rerender model refresh sub view |
-| [Embed Another App's View](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_104) | [`z2ui5_cl_smp_app_104`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_104.js) | sub app class embed instantiate another app rtti |
-| [Master-Detail with FlexibleColumnLayout](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_097) | [`z2ui5_cl_smp_app_097`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_097.js) | fcl master detail list report two column split |
-| [Three Columns with FlexibleColumnLayout](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_098) | [`z2ui5_cl_smp_app_098`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_098.js) | fcl three column detail detail deep navigation |
-
-## Popover
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Basic Example with Placement](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_026) | [`z2ui5_cl_smp_app_026`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_026.js) | placement anchor button confirm cancel popover_display |
-| [Open from a Table Row](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_052) | [`z2ui5_cl_smp_app_052`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_052.js) | list report dynamicpage row link details table |
-| [Open Together with the View Build](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_490) | [`z2ui5_cl_smp_app_490`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_490.js) | initial render one roundtrip anchor button |
-| [QuickView Contact Card](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_109) | [`z2ui5_cl_smp_app_109`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_109.js) | quickview contact card links grouped fields |
-| [Select from a List](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_081) | [`z2ui5_cl_smp_app_081`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_081.js) | list selection placement anchor |
-| [Toggle by ID (toggleBy) (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_465) | [`z2ui5_cl_smp_app_465`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_465.js) | toggleby open close control_by_id whitelisted |
-
-## Popup
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Dialog inside a Dialog](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_161) | [`z2ui5_cl_smp_app_161`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_161.js) | nested stack popup in popup second dialog |
-| [Element Binding to the Selected Row (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_470) | [`z2ui5_cl_smp_app_470`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_470.js) | element binding relative path aggregation dialog row |
-| [Navigate between Dialogs (NavContainer) (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_170) | [`z2ui5_cl_smp_app_170`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_170.js) | navcontainer dialog pages back forward |
-| [Value Help: Suggestions and F4 Dialog](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_009) | [`z2ui5_cl_smp_app_009`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_009.js) | f4 search help suggestion input dialog select |
-| [Ways to Open a Dialog (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_012) | [`z2ui5_cl_smp_app_012`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_012.js) | dialog sub app destroy rerender background view |
-
-## Scroll
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Scroll a Control into View (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_363) | [`z2ui5_cl_smp_app_363`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_363.js) | scroll_into_view control id validation jump |
-| [Scroll to a Pixel Position (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_362) | [`z2ui5_cl_smp_app_362`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_362.js) | position pixel scroll_to restore refresh toolbar |
-
-## Table
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Drag and Drop Rows (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_459) | [`z2ui5_cl_smp_app_459`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_459.js) | dnd dragdropinfo reorder rows move |
-| [Editable Cells, Add and Delete Rows](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_011) | [`z2ui5_cl_smp_app_011`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_011.js) | edit input add row delete multiselect toolbar |
-| [Filter Rows in the Backend](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_045) | [`z2ui5_cl_smp_app_045`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_045.js) | filter server side form growing where |
-| [Large Table with Growing and ScrollContainer](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_006) | [`z2ui5_cl_smp_app_006`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_006.js) | growing 10000 rows sticky toolbar sort performance |
-| [Live Search with Parallel Requests](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_059) | [`z2ui5_cl_smp_app_059`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_059.js) | live search parallel requests busy queue typing |
-| [Search in the Backend (SearchField)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_053) | [`z2ui5_cl_smp_app_053`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_053.js) | search go enter server side where |
-| [Selection Modes: Single and Multi Select](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_019) | [`z2ui5_cl_smp_app_019`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_019.js) | selectionmode none single multi segmentedbutton checkbox |
-
-## Templating
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Build Columns Dynamically (template:repeat)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_173) | [`z2ui5_cl_smp_app_173`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_173.js) | template repeat runtime generated columns if then else |
-| [Dynamic Content in a Nested View](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_176) | [`z2ui5_cl_smp_app_176`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_176.js) | template repeat runtime generated nested nest_view_display |
-
-## Timer
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Progress Indicator during a Backend Call (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_064) | [`z2ui5_cl_smp_app_064`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_064.js) | progressindicator busy wait long running backend |
-| [Refresh the View Every n Seconds (A)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_028) | [`z2ui5_cl_smp_app_028`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_028.js) | interval polling auto refresh follow_up_action seconds |
-
-## Tree
-
-| Sample | Class | Topics |
-|---|---|---|
-| [Drag and Drop Nodes (A,C)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_461) | [`z2ui5_cl_smp_app_461`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_461.js) | dnd move node hierarchy binding context |
-| [Editable Nodes with CustomTreeItem (C)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_463) | [`z2ui5_cl_smp_app_463`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_463.js) | customtreeitem rename input binding write back |
-| [Inside a Dialog (C)](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_462) | [`z2ui5_cl_smp_app_462`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_462.js) | popup expand state hierarchy nodes |
-| [Nested ABAP Table in a sap.m.Tree](https://cap2ui5.github.io/web-cap2UI5-build/?app_start=z2ui5_cl_smp_app_460) | [`z2ui5_cl_smp_app_460`](https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples/z2ui5_cl_smp_app_460.js) | hierarchy nodes nested json items |
-
-## Not in the gallery
-
-6 further classes ship in the same folder without a catalogue entry — they are the sub-apps the listed samples call (dialogs, detail views, nested apps), not entries in their own right. They run the same way if you name one directly:
-
-`z2ui5_cl_smp_app_020`, `z2ui5_cl_smp_app_025`, `z2ui5_cl_smp_app_105`, `z2ui5_cl_smp_app_112`, `z2ui5_cl_smp_app_469`, `z2ui5_cl_smp_app_489`
-
-## Where they come from
-
-The samples are machine-transpiled from the ABAP originals in [abap2UI5-samples](https://github.com/abap2UI5/abap2UI5-samples) by the [builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js) pipeline, and land in `core/srv/app/samples/` on every sync. That folder is pipeline-owned: edits to it are overwritten on the next publish. Copy a sample into [`srv/app/`](./project-structure#srv-app) before you change it.
-
-Some samples need a real server: those that call external OData services or CAP destinations will not work in the browser playground. See [what the playground is not](./playground#what-its-not).
-
-→ Ready to write your own? Start with [Hello World](../examples/hello-world), or read the [App Lifecycle](./lifecycle).
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index a7883ed..b5c6f15 100644
--- a/docs/guide/troubleshooting.md
+++ b/docs/guide/troubleshooting.md
@@ -6,21 +6,29 @@ roundtrip sent and received, and whether something threw.
 
 ## "App with name X not found"
 
-The class lookup matches **files by name**, so:
-
-1. **The file must be named exactly `<className>.js`.** A class
-   `my_app` in `apps.js` is invisible.
-2. **The file must be in a searched directory.** In order: the framework
-   folders (`core/srv/z2ui5/01/04/`, `02/`, `99/02/`), the core's app folder
-   (`core/srv/app/`, including `samples/`), anything registered via
-   `register_app_dir` / `register-apps`, and everything in `Z2UI5_APP_DIRS`.
-   Subfolders are searched recursively.
-3. **Names are case-insensitive.** `MyApp` and `myapp` collide — the lookup
-   lowercases both.
-
-Check the **System → Registry** tab: it lists exactly what the lookup can
-resolve. If your class is not in that list, it is a path or naming problem,
-not a code problem.
+Apps are registered by **`defineApp`**, not found by file name:
+
+1. **The name is the first argument to `defineApp`**, uppercased —
+   `defineApp("ZCL_HELLO", …)` is started with `?app_start=ZCL_HELLO`. The file
+   name is irrelevant, and one file may register several apps.
+2. **The file must be in the scanned directory** — `srv/apps` by default, or
+   whatever `cds.cap2ui5.apps` points at. Every `.js`, `.mjs` and `.cjs` in it
+   is imported once the runtime is up.
+3. **The plugin says how many it loaded.** On startup:
+
+   ```
+   [cap2ui5] 5 app module(s) loaded from srv/apps
+   ```
+
+   A count of `0`, or no line at all, is a path problem rather than a code
+   problem — the directory does not exist where the plugin looked.
+
+4. **A `defineApp` that throws takes its file with it.** A class without a
+   `main( client )` method throws at registration, and the message names the
+   app.
+
+`c.navTo()` on an unknown name is refused where you called it, listing what is
+registered — rather than failing later as `NAV_APP_TARGET_NOT_BOUND`.
 
 ## The draft cannot be restored
 
@@ -31,38 +39,38 @@ scratch on every interaction.
   not readable by anyone else — by design (see [Database](../reference/database)).
   A draft id from someone else's session, or from before you logged in as
   someone else, will not load.
-- **The row expired.** Retention deletes drafts older than
-  `Z2UI5_DRAFT_TTL_HOURS` (24h default). Set it to `0` while debugging.
-- **The class moved.** Restoring deserializes into the class named in the row;
-  if the file has been renamed or moved out of the lookup path since it was
-  written, the row can be read but not revived.
-- **No store is injected.** If the log says *"no draft store injected — using
-  a volatile in-memory store"*, drafts die with the process. The CAP app wires
-  one in `srv/server.js`; a custom host has to call `engine.set_store(...)`.
+- **The row expired.** Drafts older than `draft_exp_time_in_hours` (4 hours by
+  default) are deleted on the next roundtrip. Raise it in your
+  [user exit](./user-exit#onroundtrip) while debugging — the cleanup follows
+  the same number, so the rows stay as long as the framework will resume them.
+- **The app class is gone.** Restoring revives the app named in the row; if
+  the `defineApp` id has been renamed, or the file no longer loads, the row is
+  readable but not revivable.
+- **The table is empty after a restart.** `cap2ui5.Drafts` is an ordinary CDS
+  entity, so it lives wherever your project's database does. With an in-memory
+  SQLite (`cds.requires.db.kind: sql` in development) every restart is a fresh
+  database — which is a database setting, not a cap2UI5 one.
 
 ## A white page
 
 The bootstrap HTML arrived but UI5 never started.
 
-- **Open the browser console first** — a CSP violation or a 404 on
-  `/resources/sap-ui-core.js` shows there immediately.
-- **`/resources` 404s.** The local UI5 runtime comes from `openui5-dist`,
-  which the framework declares as an *optional peer* dependency — in your own
-  project you install it yourself (cap2UI5 carries it as a devDependency). Run
-  `npm ci`, or `npm i -D openui5-dist@1.113.0` if your project never declared
-  it. Its absence is not fatal — the server logs
-  `[z2ui5] openui5-dist not resolvable — /resources not served; bootstrap
-  from a CDN instead` once at startup and keeps going, so check the server
-  log for that line before hunting elsewhere.
-- **`/resources` 404s on BTP.** Different cause: there the runtime is not
-  served by the CAP module at all. The approuter routes `/resources` to the
-  `ui5` destination (`https://ui5.sap.com`) and the production build leaves
-  `openui5-dist` out of the pushed module, so a 404 means the destination is
-  missing or misconfigured, not a missing dependency.
-- **The app uses commercial SAPUI5 controls.** `openui5-dist` ships only the
-  open-source libraries. Anything under `sap.suite.*`, `sap.gantt`,
-  `sap.ui.comp` needs the SAPUI5 CDN — point `s_config.src` at it in your
-  [user exit](../reference/configuration#the-user-exit).
+- **Open the browser console first** — a CSP violation or a failed load of
+  `sap-ui-core.js` shows there immediately.
+- **The server has no outbound internet access.** The plugin serves the
+  abap2UI5 shell, not UI5 itself: the page bootstraps from
+  `https://sdk.openui5.org/…/sap-ui-core.js`, and there is no `/resources`
+  route to fall back to. In an air-gapped or egress-restricted deployment,
+  host a UI5 distribution yourself and point `cfg.src` at it in your
+  [user exit](./user-exit#onpage) — the CSP has to
+  allow that origin too.
+- **A proxy or the CSP blocks the CDN.** The default policy allow-lists the
+  SAP and OpenUI5 hosts; if you tightened it, or a corporate proxy rewrites
+  the origin, the console says which directive refused.
+- **The app uses commercial SAPUI5 controls.** `sdk.openui5.org` serves the
+  open-source libraries only. Anything under `sap.suite.*`, `sap.gantt`,
+  `sap.ui.comp` needs the SAPUI5 CDN — point `cfg.src` at it in your
+  [user exit](./user-exit#onpage).
 - **A CSP `EvalError` on old UI5.** The 1.71 `ui5loader` needs
   `'unsafe-eval'`; if you tightened the policy, that is why.
 
@@ -86,25 +94,34 @@ absent in 1.71 and UI5 renders nothing rather than complaining.
 
 ## 401 on the roundtrip
 
-`POST /rest/root/z2ui5` and the OData services require an authenticated user;
-`GET`/`HEAD` do not (they serve only the bootstrap shell). In development the
-mocked users from `package.json` apply — the reference project ships `alice`
-and `bob`. In BTP the approuter must forward the token
-(`HTML5.ForwardAuthToken`).
+The route requires an authenticated user by default — `cds.cap2ui5.requires` is
+`"authenticated-user"`. In development CAP's mocked auth applies, so any
+configured user works (`alice` with an empty password in a stock project). In
+BTP the approuter must forward the token (`HTML5.ForwardAuthToken`).
+
+The decision happens **before** the body is read, so an unauthenticated POST is
+refused without the payload being buffered. To open the route deliberately, set
+`requires` to `null` — and read what that costs in
+[Configuration](../reference/configuration).
 
 ## Two users see each other's state
 
-That is a misconfiguration, not the design. Retained sticky app state is keyed
-per session by the identity provider; with no provider installed every user
-shares one key. Check that `engine.set_identity(...)` is wired — see
-[Configuration](../reference/configuration#identity).
+Almost always one cause: **`cds.cap2ui5.requires` is `null`.** Every caller is
+then CAP's anonymous user, and the draft store binds a session to
+`cds.context.user.id` — so all anonymous visitors share one owner and therefore
+each other's sessions. That is the documented consequence of turning
+authentication off, not a defect.
+
+With authentication on, a draft answers to its creator and to nobody else. If
+you see otherwise with `requires` set, that is a bug worth reporting — check
+the `owner` column of `cap2ui5.Drafts` first:
 
-## The playground behaves differently from my app
+```sql
+SELECT id, owner FROM cap2ui5_Drafts ORDER BY createdAt DESC LIMIT 5;
+```
 
-The [playground](./playground) is the same framework with no backend: drafts
-live in browser memory (bounded, so deep back-navigation eventually drops the
-oldest), there is no database, no OData, and no remote calls. Differences in
-persistence and anything server-side are expected there.
+An `owner` reading `anonymous` where you expected a user name means the caller
+was not authenticated, not that the binding failed.
 
 ## Still stuck
 
diff --git a/docs/guide/user-exit.md b/docs/guide/user-exit.md
index a546c8a..832b8c7 100644
--- a/docs/guide/user-exit.md
+++ b/docs/guide/user-exit.md
@@ -1,222 +1,218 @@
 # The User Exit
 
-Everything the framework renders or sends — the tab title, the theme, the tab
-icon, the UI5 bootstrap URL, the Content-Security-Policy, the response headers,
-how long drafts live, whether the CSRF gate is armed — comes from one config
-object. The **user exit** is the one supported way to change it.
+Everything the framework renders or sends that is not an app's business — the
+theme, the UI5 bootstrap URL, the Content-Security-Policy, the response
+headers, how long drafts live, whether the CSRF gate is armed — comes from one
+config structure. The **user exit** is the one supported way to change it.
 
-It is a single class implementing `z2ui5_if_exit`, and it is the framework's
-only extension point of this kind: there is no config file, no environment
-variable for these values, and nothing to register. You write the class, the
-framework finds it.
-
-## The smallest exit
+A project has **one**, registered with `defineExit`:
 
 ```js
-// srv/app/my_exit.js
-class my_exit {
-
-  set_config_http_get(s_context, s_config) {
-    s_config.title = "Order Management";
-    s_config.theme = "sap_horizon_dark";
-    return s_config;
-  }
-
-  set_config_http_post(s_context, s_config) {
-    return s_config;
-  }
-}
-
-module.exports = my_exit;
+// srv/apps/exit.js
+const { defineExit } = require("cap2ui5");
+
+defineExit({
+  onPage(cfg, ctx) {                 // the bootstrap page, once per page load
+    cfg.theme = "sap_horizon_dark";
+  },
+  onRoundtrip(cfg, ctx) {            // every roundtrip after it
+    cfg.draft_exp_time_in_hours = 24;
+  },
+});
 ```
 
-That is the whole contract. Both methods must exist, but either may simply hand
-back what it was given.
+Both hooks are optional; register the one you need. The file goes in your apps
+directory (`srv/apps/` by default) and is loaded with the apps, before the
+first request.
 
-::: warning `z2ui5_if_exit` is a contract, not a base class
-Unlike `z2ui5_if_app`, it is **not** something to `extend` — it is a plain
-object holding the method names, and `class my_exit extends z2ui5_if_exit`
-throws at load time. The framework matches an exit by those method names alone.
-If you want the check written down, assert it explicitly:
+`cfg` arrives **fully populated** with the framework's defaults, so you
+override what you care about and leave the rest alone. Only the fields you
+actually change are written back.
 
-```js
-const z2ui5_if_exit = require("abap2UI5/z2ui5_if_exit");
-z2ui5_if_exit.check_implements(my_exit.prototype);   // throws if one is missing
-```
+::: warning One exit, not one per concern
+The exit decides the Content-Security-Policy and every security header, so
+which one wins must not depend on module load order. A second `defineExit`
+call throws rather than silently replacing the first. Merge them.
 :::
 
-## How the framework finds it
-
-`z2ui5_cl_ui5_user_exit` is the framework's own implementation of the same
-interface. On the first request it scans the registered app directories for
-**any other** class implementing `z2ui5_if_exit`, instantiates the one it
-finds, and keeps it for the life of the process.
-
-- The scan uses the same app-directory search as app classes, so put the exit
-  where your apps are: [`srv/app/`](./project-structure#srv-app), or any
-  directory named in `Z2UI5_APP_DIRS` / registered via
-  `require("abap2UI5/register-apps")`.
-- The file name must match the class name, as it must for app classes.
-- **If more than one exit exists, exactly one wins** — the first by class name,
-  sorted. That is deliberate rather than a race: the chosen exit controls the
-  CSP and every security header, so which one wins must not depend on the order
-  the file system happens to return. Ship one exit.
-- If none exists, the framework defaults apply unchanged.
-
-The framework runs its own defaults **first** and calls your exit **after**, so
-`s_config` arrives fully populated. You override what you care about and leave
-the rest alone. ABAP's `CHANGING` semantics map to either style in JavaScript:
-mutate `s_config` in place, return it, or both — the framework accepts all
-three.
+## Why you register it instead of the framework finding it
+
+In ABAP, abap2UI5 *discovers* the exit: it asks the class repository which
+classes implement `z2ui5_if_ui5_exit` and instantiates the one it finds. That
+lookup is `SEO_INTERFACE_IMPLEM_GET_ALL` on standard ABAP and XCO on cloud —
+and [open-abap](./where-it-comes-from), which the transpiled runtime runs on,
+has neither. The call raises, the framework's own `CATCH cx_root` turns that
+into "no exit configured", and the shipped defaults stand.
+
+Measured, before `defineExit` existed: with an exit class sitting in the
+runtime's class table, `get_user_exit_class( )` answered the empty string and
+`get_instance( )` handed back the default exit. Every value on this page was
+unreachable from a CAP project.
+
+So the host binds the exit rather than being asked for it — the same seam the
+[draft store](../reference/database) uses, and the same static the framework's
+own `exit_instantiate( )` writes to. `examples/bookshop/test/exit.test.mjs`
+measures the effects over the wire: the theme on the page, an added header on
+both the page and the roundtrip response, and the CSRF gate still armed
+because the exit did not touch it.
 
 ## The request context
 
-The first argument describes the request being answered:
+The second argument describes the request being answered:
 
 | Field | What it is |
 |---|---|
 | `path` | the request path |
-| `method` | the HTTP method |
+| `app_start` | the `?app_start=` value — trimmed, upper-cased, namespace unpacked |
 | `t_params` | the URL query parameters, as `[{ n, v }]` |
-| `app_start` | the `?app_start=` value, lifted out of `t_params` for convenience |
-| `session_id` | the session key the framework isolates state by |
-| `tenant` | the tenant, when the platform supplies one |
-| `body` | the raw request body |
 
-So the config can depend on the request — a different theme per app, for
-instance:
+So the config can depend on the request — a different theme per app:
 
 ```js
-set_config_http_get(s_context, s_config) {
-  if (s_context.app_start === "z2ui5_cl_smp_app_000") {
-    s_config.theme = "sap_horizon";
-  }
-  return s_config;
+onPage(cfg, ctx) {
+  if (ctx.app_start === "ZCL_JS_BOOKS") cfg.theme = "sap_horizon_dark";
 }
 ```
 
-The context is **per request**, not process-global: two roundtrips in flight at
-the same time each see their own, so an exit cannot read the other request's
-parameters.
+::: tip `app_start` is empty on a POST
+The frontend posts to the manifest URI, and an app named by the hash route
+never reaches the server at all. `app_start` is a hint for the page request,
+not the authority on which app is running — do not branch security decisions
+on it.
+:::
 
-## `set_config_http_get` — the bootstrap page
+## `onPage` — the bootstrap page {#onpage}
 
 This hook builds the HTML page that boots UI5. It runs once per full page
 load, not once per roundtrip.
 
 | Field | Default | Effect |
 |---|---|---|
-| `title` | `abap2UI5` | the browser tab title |
+| `src` | `https://sdk.openui5.org/resources/sap-ui-cachebuster/sap-ui-core.js` | the UI5 bootstrap — the OpenUI5 CDN |
 | `theme` | `sap_horizon` | any UI5 theme id |
-| `favicon` | an inline SVG data URI | the tab icon; set your own, or clear it and the page emits no icon link at all (the browser then falls back to `/favicon.ico`) |
-| `src` | `/resources/sap-ui-core.js` | the UI5 bootstrap — the locally served runtime by default, which is what keeps the stack working offline |
 | `content_security_policy` | a full `<meta>` tag | see below |
-| `t_security_header` | 7 headers | `[{ n, v }]`, applied to the bootstrap response |
-| `t_add_config` | — | extra `data-sap-ui-*` bootstrap attributes, as `[{ n, v }]` |
-
-::: tip Escaping
-Values are escaped for the context they land in — text, attribute or URI — so a
-title with an apostrophe or an ampersand renders as written. Attribute *names*
-in `t_add_config` are restricted rather than escaped: a name outside
-`[A-Za-z_][A-Za-z0-9_:.-]*` is dropped.
+| `t_security_header` | 5 headers | `[{ n, v }]`, applied to **every** response the handler sends, the roundtrip POST included |
+| `t_add_config` | `[]` | extra `data-sap-ui-*` bootstrap attributes, as `[{ n, v }]` |
+| `styles_css` | `""` | CSS injected into the page |
+| `custom_js` | `""` | JavaScript injected into the page |
+| `title` | `""` | **no longer read.** The page carries a constant `<title>`; an app sets the tab title itself, with `cs_event-set_title`. The field stays because it is part of the published contract — assigning it compiles, runs, and does nothing |
+
+::: warning UI5 comes from the CDN
+The plugin serves the abap2UI5 shell (`/z2ui5/webapp`), not UI5 itself —
+there is no `/resources` route, and `src` points at `sdk.openui5.org` out of
+the box. **A server without outbound internet access renders nothing.** If
+that is your deployment, host a UI5 distribution yourself and point `src` at
+it; the CSP has to allow that origin too.
 :::
 
 ### Content-Security-Policy
 
-The default policy allows `'unsafe-eval'` for one specific reason: the OpenUI5
-1.71 `ui5loader` evaluates module source as a string, and without it that
-bootstrap fails with a CSP `EvalError`. Modern UI5 does not need it. If you pin
-a modern release, tighten the policy:
+The default allows `'unsafe-eval'` for one specific reason: the OpenUI5
+`ui5loader` evaluates module source as a string, and without it the bootstrap
+fails with a CSP `EvalError`. It allow-lists the SAP and OpenUI5 hosts,
+permits `data:` and `blob:`, and closes `object-src` and `base-uri`.
+
+If you pin a UI5 release that does not need `eval`, tighten it:
 
 ```js
-set_config_http_get(s_context, s_config) {
-  s_config.content_security_policy = s_config.content_security_policy
-    .replace(" 'unsafe-eval'", "");
-  return s_config;
+onPage(cfg) {
+  cfg.content_security_policy =
+    cfg.content_security_policy.replace(" 'unsafe-eval'", "");
 }
 ```
 
-The policy also allow-lists the public UI5 CDNs plus jsDelivr and cdnjs, and
-permits `data:` — which is what makes the default inline-SVG favicon work. If
-you serve everything locally, those hosts can go too.
+Serving UI5 yourself? Then the CDN hosts can go too — build the tag rather
+than patching it, so what the page carries is what you wrote.
 
 ### Security headers
 
-The seven defaults are `cache-control: no-cache, no-store, must-revalidate`,
-`Pragma: no-cache`, `Expires: 0`, `X-Content-Type-Options: nosniff`,
-`X-Frame-Options: SAMEORIGIN`, `Referrer-Policy: strict-origin-when-cross-origin`
-and a `Permissions-Policy` allowing geolocation, microphone and camera for the
-same origin only. Replace or extend the array to add your own — HSTS, for
-instance, on a deployment that terminates TLS itself.
+The five defaults are `X-Content-Type-Options: nosniff`,
+`X-Frame-Options: SAMEORIGIN`,
+`Referrer-Policy: strict-origin-when-cross-origin`, a `Permissions-Policy`
+allowing geolocation, microphone and camera for the same origin only, and
+`Cross-Origin-Resource-Policy: same-origin`. (The caching headers on the
+response come from the handler itself, not from here.)
 
-## `set_config_http_post` — the roundtrip
+Append rather than replace, unless dropping one is the point:
 
-This hook runs on the roundtrip endpoint, the POST that every user interaction
-goes through.
+```js
+onPage(cfg) {
+  cfg.t_security_header = [
+    ...cfg.t_security_header,
+    { n: "Strict-Transport-Security", v: "max-age=31536000; includeSubDomains" },
+  ];
+}
+```
+
+## `onRoundtrip` — every request after the page {#onroundtrip}
 
 | Field | Default | Effect |
 |---|---|---|
 | `draft_exp_time_in_hours` | `4` | how long a draft stays resumable |
 | `check_csrf_active` | `true` | the cross-origin POST gate |
+| `check_trust_forwarded_host` | `true` | whether `X-Forwarded-Host` is trusted when the gate compares origins |
+| `check_hide_error_details` | `false` | answer framework errors with a generic 500 instead of the exception text |
 
 ### Draft expiry
 
 ```js
-set_config_http_post(s_context, s_config) {
-  s_config.draft_exp_time_in_hours = 24;
-  return s_config;
-}
+onRoundtrip(cfg) { cfg.draft_exp_time_in_hours = 24; }
 ```
 
-A value of zero or less is ignored and the default restored — an expiry of
-"never" is not something a typo should be able to configure.
-
-::: tip One knob, not two
-The CAP app's retention job deletes draft rows on the same clock: it asks this
-exit for `draft_exp_time_in_hours` and follows it, so raising the expiry here
-also keeps the rows around longer. `Z2UI5_DRAFT_TTL_HOURS` overrides both when
-it is set — see [Configuration](../reference/configuration).
-:::
+This governs how long the framework will *resume* a draft. Deleting the rows
+is a separate job on its own clock — see [Database](../reference/database).
 
 ### CSRF
 
-The gate compares the `Origin` header — falling back to `Referer` — against the
-app's own `Host`, and rejects a mismatch with `403 Forbidden`. The frontend
+The gate compares the `Origin` header — falling back to `Referer` — against
+the app's own host, and rejects a mismatch with `403 Forbidden`. The frontend
 posts from the same origin, so first-party traffic is unaffected.
 
 Two properties are worth knowing before you rely on it:
 
-- It is **on by default** since the 2026-08 security pass. It used to be
-  opt-in, and nothing opted in. If you are looking at a core vendored before
-  that change, `set_config_http_post` in
-  `core/srv/z2ui5/01/04/z2ui5_cl_ui5_user_exit.js` tells you which one you
-  have.
 - It is **lenient when there is nothing to compare**: a request carrying
   neither `Origin` nor `Referer` is allowed through, so that proxies which
   strip those headers do not lock users out. It is a defence against
-  cross-origin form posts, not a complete CSRF defence, and it does not replace
-  authentication.
-
-Turn it off — in front of your own gateway, say — the same way you turn
-anything else off:
+  cross-origin form posts, not a complete CSRF defence, and it does not
+  replace authentication.
+- Behind a reverse proxy the "own host" is the `X-Forwarded-Host` the proxy
+  wrote, and that header is client-suppliable. If your deployment is **not**
+  behind a proxy that sets it, harden the gate:
 
 ```js
-set_config_http_post(s_context, s_config) {
-  s_config.check_csrf_active = false;
-  return s_config;
-}
+onRoundtrip(cfg) { cfg.check_trust_forwarded_host = false; }
 ```
 
+Turning the gate off — in front of your own gateway, say — is
+`cfg.check_csrf_active = false`.
+
+### Error detail
+
+`check_hide_error_details` applies to errors the **framework** answers with.
+Errors the plugin's own route catches are already generic: the detail goes to
+the server log and the caller gets a correlation id, because CDS and driver
+messages carry entity names, SQL fragments and deployment paths.
+
 ## What the exit is not for
 
-- **Not app configuration.** It is called for every request, for every app. App
-  state belongs on the app instance; see [App Lifecycle](./lifecycle).
+- **Not app configuration.** It is called for every request, for every app.
+  App state belongs on the app instance; see [App Lifecycle](./lifecycle).
 - **Not a request filter.** It shapes config, it does not accept or reject
   requests. Authentication and authorisation belong on the CAP service
-  (`@requires`, `@restrict`) — see [Deployment](../reference/deployment).
-- **Not a place for per-user secrets.** The instance is created once and shared
-  by every request in the process; only the context argument is per request.
+  (`@requires`, `@restrict`) and on `cds.cap2ui5.requires` — see
+  [Deployment](../reference/deployment).
+- **Not a place for per-user secrets.** The object is registered once and
+  shared by every request in the process; only the context argument is per
+  request.
+
+::: tip A hook that throws does not take the request down
+The framework's defaults are already in `cfg` when your hook runs, so a hook
+that raises is logged and the request is answered with those defaults. That is
+deliberate — a typo in a theme name must not make the app unreachable — but it
+means a hook you rely on for a *security* header can fail quietly. Check the
+server log, and assert the header in a test, as the example does.
+:::
 
-→ Related: [Configuration](../reference/configuration) for environment
-variables, identity and the draft store; [Architecture](../reference/architecture)
-for where `z2ui5_cl_ui5_user_exit` sits in the stack.
+→ Related: [Configuration](../reference/configuration) for the plugin's own
+options; [Architecture](../reference/architecture) for where the exit sits in
+the stack.
diff --git a/docs/guide/views.md b/docs/guide/views.md
index 062e625..3c9eb59 100644
--- a/docs/guide/views.md
+++ b/docs/guide/views.md
@@ -1,145 +1,90 @@
-# View Builder
+# Views
 
-Instead of maintaining UI5 views as XML files, you assemble them in JavaScript with a fluent builder that produces the XML in the background. The output is always an XML string that goes to the frontend.
-
-There is one builder, `z2ui5_cl_ui5_view_builder`. It is deliberately generic: it knows XML elements and attributes, not the UI5 control catalogue. You name the control, it builds the tree. That is why the transpiler targets it, and why every bundled sample is written against it.
-
-## The simplest case
+A view is **UI5 XML, as a string**, handed to `c.view()`.
 
 ```js
-const z2ui5_cl_ui5_view_builder = require("abap2UI5/z2ui5_cl_ui5_view_builder");
-
-const view = z2ui5_cl_ui5_view_builder.factory()
-  .ele({ n: `View`, ns: `mvc` })
-  .a({ n: `xmlns`,     v: `sap.m` })
-  .a({ n: `xmlns:mvc`, v: `sap.ui.core.mvc` });
-
-view.ele(`Shell`).ele(`Page`).a({ n: `title`, v: `Hello` })
-  .tag(`Input`).a({ n: `value`, v: `world` });
-
-client.view_display(view.stringify());
+c.view(
+  `<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m" displayBlock="true" height="100%">` +
+  `<Shell><Page title="My app">` +
+  `<Input value="${c.bind("name")}"/>` +
+  `<Button text="Go" press="${c.event("GO")}" type="Emphasized"/>` +
+  `</Page></Shell></mvc:View>`);
 ```
 
-```xml
-<mvc:View xmlns="sap.m" xmlns:mvc="sap.ui.core.mvc">
-  <Shell><Page title="Hello"><Input value="world"/></Page></Shell>
-</mvc:View>
-```
+That is the whole API. There is no builder to learn, no control catalogue to
+wait for, and nothing between you and UI5: anything you can write in a UI5 XML
+view, you can write here, including controls the framework has never heard of.
 
-## Four methods
+## The two holes you fill
 
-| Method | What it does |
+| | |
 |---|---|
-| `.ele({n, ns})` | add a child element and **move into it** |
-| `.tag({n, ns})` | add a child element and **stay where you are** |
-| `.a({n, v})` | set an attribute (`{n, b}` for a boolean) |
-| `.end()` | move back up to the parent |
-
-`.ele()` and `.tag()` are the pair worth internalising, because they look interchangeable and are not:
-
-```js
-page.ele(`Button`).a({ n: `text`, v: `A` });   // now positioned ON the button
-page.tag(`Button`).a({ n: `text`, v: `B` });   // still positioned on the page
-```
-
-Containers you want to nest into get `.ele()`; leaves get `.tag()`. A chain that silently descended one level too far is the usual reason a control ends up inside its sibling instead of next to it.
-
-Each method also takes its main argument positionally, so `.ele("Page")` and `.ele({ n: "Page" })` are the same thing — the samples mix both freely.
-
-## Aggregations are ordinary elements
-
-There is no `.content()` or `.items()` shorthand. An aggregation is an element like any other, which means you write it yourself — **and give it the namespace of the control that owns it**:
-
-```js
-const content = view.ele(`Shell`).ele(`Page`)
-  .ele({ n: `SimpleForm`, ns: `form` })   // sap.ui.layout.form
-  .a({ n: `editable`, b: true })
-  .ele({ n: `content`, ns: `form` });     // …and so is its aggregation
-
-content.tag(`Label`).a({ n: `text`, v: `Name` });
-content.tag(`Input`).a({ n: `value`, v: client._bind_edit(this.name) });
-```
+| `${c.bind("field")}` | a binding path to one of your fields |
+| `${c.event("NAME")}` | a handler expression; `["arg"]` as a second parameter travels with it |
 
-::: warning Namespaces are the one thing that fails hard
-An element in the wrong XML namespace does not render wrong — the view fails to **load**. UI5 resolves an unprefixed tag against the default `xmlns`, so `<SimpleForm>` under `xmlns="sap.m"` becomes a request for `sap/m/SimpleForm.js` and the whole view dies with a `ModuleError`, with nothing rendered and nothing useful in the message.
+Everything else is plain UI5.
 
-Declare every namespace you use on the root, and prefix every element that is not in the default one:
+## The shape
 
-```js
-.a({ n: `xmlns`,      v: `sap.m` })
-.a({ n: `xmlns:mvc`,  v: `sap.ui.core.mvc` })
-.a({ n: `xmlns:core`, v: `sap.ui.core` })          // Title, Icon, …
-.a({ n: `xmlns:form`, v: `sap.ui.layout.form` })   // SimpleForm + its content
-.a({ n: `xmlns:z2ui5`, v: `z2ui5.cc` })            // custom controls
-```
-:::
+- a **view** is an `mvc:View`, usually `<Shell><Page>…</Page></Shell>`;
+- a **popup** is a `core:FragmentDefinition` — see [Popups](./popups);
+- a **nested view** is an `mvc:View` again, rendered into a control of the main
+  view.
 
-## Values: raw, bound, or expression
+Declare the namespaces you use on the root element. `xmlns="sap.m"` for the
+common controls, `xmlns:mvc="sap.ui.core.mvc"`, plus whatever else you reach
+for (`sap.ui.layout.form`, `sap.ui.table`, …).
 
-```js
-.a({ n: `value`, v: `Hello` })                                  // literal string
-.a({ n: `value`, v: client._bind_edit(this.name) })             // two-way: {/XX/NAME}
-.a({ n: `value`, v: client._bind(this.name) })                  // one-way: {/NAME}
-.a({ n: `value`, v: `{= ${client._bind(this.name)} }` })        // expression binding
-.a({ n: `value`, v: `{path: '/NAME', formatter: '.fmt'}` })     // classical binding
-```
+## Template literals are the point
 
-Whatever you pass as a string lands 1:1 in the XML attribute — the bind helpers are pure string builders. Booleans have their own form, `.a({ n: "editable", b: true })`, which renders `"true"` / `"false"`.
-
-## Custom controls
-
-Custom controls live in the `z2ui5.cc` namespace:
+The view is a string, so composing it is ordinary JavaScript:
 
 ```js
-view.a({ n: `xmlns:z2ui5`, v: `z2ui5.cc` });
-
-page.tag({ n: `Geolocation`, ns: `z2ui5` })
-  .a({ n: `finished`,  v: client._event(`GEO_DONE`) })
-  .a({ n: `longitude`, v: client._bind_edit(this.lng) })
-  .a({ n: `latitude`,  v: client._bind_edit(this.lat) });
+const column = (t) => `<Column><Text text="${t}"/></Column>`;
+
+c.view(
+  `<Table items="${c.bind("books")}">` +
+  `<columns>${["Title", "Author", "Price"].map(column).join("")}</columns>` +
+  `<items><ColumnListItem><cells>` +
+  `<Text text="{TITLE}"/><Text text="{AUTHOR}"/><ObjectNumber number="{PRICE}"/>` +
+  `</cells></ColumnListItem></items></Table>`);
 ```
 
-Available custom controls (selection): camera picture/selector, Chart.js, file uploader, geolocation, barcode generator, frontend info, scrolling, timer, websocket, storage, spreadsheet export, extended MultiInputs. They are implemented in the webapp under [`app/z2ui5/webapp/cc/`](https://github.com/cap2UI5/cap2UI5/tree/main/app/z2ui5/webapp/cc).
-
-## Popups
+Row fields inside a table's template are **uppercase** — `{TITLE}` — and are
+bound relative to the row, so they need no `c.bind`.
 
-A popup is a fragment, not a view, so the root element differs — everything else is the same:
+::: warning Interpolating user input into markup is an injection
+`${c.bind(…)}` and `${c.event(…)}` are framework-produced and safe. A value a
+user typed is not:
 
 ```js
-const view = z2ui5_cl_ui5_view_builder.factory()
-  .ele({ n: `FragmentDefinition`, ns: `core` })
-  .a({ n: `xmlns`,      v: `sap.m` })
-  .a({ n: `xmlns:core`, v: `sap.ui.core` });
-
-view.ele(`Dialog`).a({ n: `title`, v: `Confirm` });
-client.popup_display(view.stringify());
+c.view(`<Text text="${this.name}"/>`);          // ❌ the user writes the markup
+c.view(`<Text text="${c.bind("name")}"/>`);     // ✅ bound, escaped by UI5
 ```
 
-→ More in [Popups & Toasts](./popups).
-
-## Embedding static XML
-
-If you already have a view as XML (exported from a designer, say), bypass the builder entirely:
-
-```js
-const fs = require("fs");
-const path = require("path");
+Bind it. If you genuinely need a value in the markup rather than in the model,
+escape it yourself first.
+:::
 
-const xml = fs.readFileSync(path.join(__dirname, "MyView.view.xml"), "utf8");
-client.view_display(xml);
-```
+## When to re-render
 
-The roundtrip works the same way — the frontend renderer does not care how the XML was produced.
+- **changed bound data** → nothing to do. It is pushed to the view, and to an
+  open popup or nested view, on its own.
+- **changed view structure** — a column appears, a button becomes visible → call
+  `c.view()` again.
 
-→ Example: [Static XML View](../examples/static-xml-view).
+There is no `modelUpdate()`. It existed, called a framework method documented as
+*obsolete and does nothing*, and now throws an error saying so.
 
-## Two nested views (master-detail)
+## The ABAP view builder
 
-```js
-client.view_display(masterView.stringify());
-client.nest_view_display(detailView.stringify(), "containerId", "addItem");
-```
+abap2UI5 ships `z2ui5_cl_ui5_view_builder`, a fluent builder for the same XML.
+It is in the runtime and ABAP apps use it — but the plugin's facade does not
+expose it, because in JavaScript a template literal is shorter and clearer than
+a builder chain. If you want it, it is reachable through `c.raw`.
 
-`nest_view_display` injects a second view into a specific container of the main view. There are two nesting levels (`nest_view_display`, `nest2_view_display`) for deeper layouts.
+## Next
 
-→ Full method list: [View Builder API](../api/view-builder). Continue with [**Data Binding**](./data-binding).
+- [**Data Binding**](./data-binding) — the types behind `c.bind`
+- [**Events**](./events) — the handlers behind `c.event`
+- [**Popups & Toasts**](./popups) — fragments and nested views
diff --git a/docs/guide/vs-abap2ui5.md b/docs/guide/vs-abap2ui5.md
index 3598326..b4d265a 100644
--- a/docs/guide/vs-abap2ui5.md
+++ b/docs/guide/vs-abap2ui5.md
@@ -1,158 +1,102 @@
 # cap2UI5 vs. abap2UI5
 
-cap2UI5 is a **JavaScript port** of the [abap2UI5](https://github.com/abap2UI5/abap2UI5) framework. If you know one, you know the other 90%. This page shows the commonalities, the differences, and why a second implementation exists in the first place. (New to abap2UI5 entirely? Start with [Where cap2UI5 comes from](./where-it-comes-from).)
-
-## Commonalities
-
-- **Identical frontend bundle.** cap2UI5 pulls the `app/webapp/` directory from the abap2UI5 repo via the automated [sync pipeline](./where-it-comes-from#how-the-port-actually-works). That means: same UI5 bundle, same custom controls, same `app/z2ui5/webapp/core/actions/` handlers, same index HTML boot pattern.
-- **Identical wire protocol.** `POST /rest/root/z2ui5` with `{ S_FRONT, XX, MODEL }` — the frontend cannot tell whether ABAP or Node.js is responding.
-- **The same API, method for method.** Class names, methods and patterns (`check_on_init`, `_event`, `nav_app_call`, the view builder chain) carry over one to one; an ABAP method call and its JS counterpart differ only in language idiom.
-- **Identical custom control set.** `geolocation`, `chartjs`, `file_uploader`, … all run identically on the frontend — the server only has to render the XML correctly.
-
-::: warning Same shape — but not the same release, and not the same class set
-Two qualifications on "identical", both worth knowing before you copy an upstream sample.
-
-**cap2UI5 carries one pinned framework release, and it is 1.142.0.** The number is in the shipped code: `static version` on `z2ui5_if_app` (`core/srv/z2ui5/02/z2ui5_if_app.js`). Upstream has moved on, and one of the moves changes what an example means:
-
-- **Here, on 1.142.0**, `_bind()` and `_bind_edit()` are two different bindings — one-way and two-way. Every example on this site uses them that way, because that is what the shipped `z2ui5_cl_ui5_srv_bind` does.
-- **Upstream, from 1.143.0 on**, the split is gone: `_bind_edit()` is an alias of `_bind()`, and `custom_mapper_back` / `custom_filter_back` are still accepted but no longer evaluated. See abap2UI5's [deprecations page](https://abap2ui5.github.io/docs/resources/deprecations.html).
-
-**cap2UI5 does not ship upstream's frozen legacy package at all.** abap2UI5 keeps its `src/99` for one reason — abapGit installs a repository, not a folder, so deleting those objects would break existing installations. An npm package has no such installed base, so since 2026-08 nothing from `src/99` enters the port. Concretely, these exist upstream and do **not** exist here:
-
-| upstream (frozen, still shipped) | cap2UI5 |
-|---|---|
-| `z2ui5_cl_xml_view`, `z2ui5_cl_xml_view_cc` | not carried — the only builder is `z2ui5_cl_ui5_view_builder` |
-| the built-in popups `z2ui5_cl_pop_*` | not carried — upstream's own successor is the separate [popups add-on](https://github.com/abap2UI5-addons/popups) |
-| the retired `z2ui5_cl_util*` of `99/01` | not carried (the `z2ui5_cl_util` here is the transpiler runtime, an unrelated class of the same name) |
-
-So an old abap2UI5 sample that still compiles upstream can fail here on the import alone — and that is deliberate, not a gap waiting to be filled.
+They are the same framework. The question is not which framework you want but
+**which runtime your code should live in** — and that is usually decided for you
+by where your data is.
+
+## What is identical
+
+Not "compatible" — identical, because it is the same code:
+
+- **the same frontend.** The UI5 shell ships inside `@abap2ui5/runtime`,
+  straight from upstream's repository. Same bundle, same custom controls, same
+  frontend actions, same boot;
+- **the same backend.** Upstream's ABAP, downported and transpiled over
+  open-abap. Not a port of it — it;
+- **the same wire.** One `PROTOCOL` version, stamped by the same code that
+  reads it;
+- **the same concepts.** Roundtrips, the draft chain, the app stack, value
+  helps as apps, one class per app.
+
+The browser cannot tell which side answers.
+
+::: info This used to be a longer and more careful section
+It listed the framework version this project had pinned, the API differences
+that version implied, and which examples were affected. None of that applies
+any more: there is no separate version to pin, because there is no second
+implementation to keep in step. See
+[Where cap2UI5 Comes From](./where-it-comes-from).
 :::
 
-## Differences
-
-### Language & type system
+## What differs
 
 | | abap2UI5 | cap2UI5 |
 |---|---|---|
-| Language | ABAP OO | JavaScript |
-| Types   | static, with interface contracts | dynamic, JSDoc + duck typing |
-| Class lookup | RTTI via CCDIR | RTTI via file system + `require` |
-| Persistence | DB table Z2UI5_T_01 in HANA | CDS entity `z2ui5_t_01` (CAP DB) |
-
-### Backend hosting
+| language | ABAP | JavaScript |
+| runs on | an SAP system (NetWeaver, S/4, BTP ABAP) | Node.js, as a CAP plugin |
+| deployment | abapGit into a system | `npm i` into a CAP project |
+| data access | Open SQL | `cds.ql`, and CAP's remote services |
+| session state | `Z2UI5_T_01` | `cap2ui5.Drafts`, a CDS entity in your database |
+| identity | `sy-uname` | `cds.context.user.id` |
+| view | the fluent builder | a UI5 XML string — the builder is there, the facade just does not need it |
+| lifecycle predicates | `check_on_init( )` / `check_on_navigated( )` | `c.isFirstRun` / `c.isDisplay` |
 
-| | abap2UI5 | cap2UI5 |
-|---|---|---|
-| Server | SAP NetWeaver / S/4 / RAP / BTP-ABAP | Node.js / CAP / Cloud Foundry |
-| Endpoint | ICF service (e.g. `/sap/bc/z2ui5`) | CDS REST action (`/rest/root/z2ui5`) |
-| Auth | SAP user, X.509, OAuth via SICF | XSUAA, IAS, mock auth |
-| External calls | `cl_http_client`, RFC, service consumer | `cds.connect.to`, `fetch`, `axios` |
-| Data access | OpenSQL, AMDP | CDS queries (`SELECT.from(...)`), HANA CCL |
+The full mapping is in
+[Migrating from abap2UI5](./migration-from-abap2ui5#the-translation-table).
 
-### Build & deployment
-
-| | abap2UI5 | cap2UI5 |
-|---|---|---|
-| Build | abapGit pull, transport | `npm install`, `cds build` |
-| Deploy | STMS / abapGit / GCTS | `cf deploy mta_archives/...` |
-| Sticky sessions | ABAP session stickiness | Cloud Foundry `RouteServiceUrl` |
-| Hot-reload dev | incremental activation | `npx cds w` |
-
-### Tooling
-
-abap2UI5 apps are written in SAP GUI / ADT. cap2UI5 apps are written in **VS Code, JetBrains, Cursor** — with all modern JS tooling (ESLint, Prettier, Jest, debugger, source maps).
-
-## Which should I choose?
-
-That **doesn't** depend on which framework is "better" — they solve the same problem the same way. It depends on **which server stack fits your project**:
-
-- You have an **existing ABAP system** and don't want a second platform → **abap2UI5**.
-- You're building a **new cloud application** on BTP / Cloud Foundry / Kyma → **cap2UI5**.
-- You need **CAP features** (multi-tenancy, OData v4 out of the box, JS toolchain, async event mesh) → **cap2UI5**.
-- You work in a **mixed landscape** and want a UI component that looks the same in both worlds → you can deploy _exactly the same_ app in both frameworks, since the wire is compatible.
-
-## Code comparison
-
-ABAP version — the same app on current abap2UI5, built with `z2ui5_cl_ui5_view_builder`:
+## The same app, twice
 
 ```abap
-CLASS z2ui5_cl_ui5_app_hi_world DEFINITION PUBLIC.
-  PUBLIC SECTION.
-    INTERFACES z2ui5_if_app.
-    DATA name TYPE string.
-ENDCLASS.
-
-CLASS z2ui5_cl_ui5_app_hi_world IMPLEMENTATION.
-  METHOD z2ui5_if_app~main.
-    IF client->check_on_init( ).
-      DATA(view) = z2ui5_cl_ui5_view_builder=>factory( ).
-      view->ele( n = `View` ns = `mvc`
-        )->a( n = `xmlns`     v = `sap.m`
-        )->a( n = `xmlns:mvc` v = `sap.ui.core.mvc` ).
-
-      DATA(page) = view->ele( `Shell`
-        )->ele( `Page` )->a( n = `title` v = `Hello World` ).
-
-      page->tag( `Input`  )->a( n = `value` v = client->_bind( name )
-        )->tag( `Button` )->a( n = `text`  v = `Send`
-        )->a( n = `press` v = client->_event( `BUTTON_POST` ) ).
-
-      client->view_display( view->stringify( ) ).
-    ELSEIF client->check_on_event( `BUTTON_POST` ).
-      client->message_box_display( |Your name is { name }| ).
-    ENDIF.
-  ENDMETHOD.
-ENDCLASS.
+" abap2UI5
+METHOD z2ui5_if_app~main.
+  IF client->check_on_navigated( ).
+    client->view_display( ... ).
+    RETURN.
+  ENDIF.
+  IF client->get( )-event = 'GO'.
+    client->message_box_display( |Hello { name }| ).
+  ENDIF.
+ENDMETHOD.
 ```
 
-JS version (cap2UI5):
-
 ```js
-class z2ui5_cl_ui5_app_hi_world extends z2ui5_if_app {
-
-  name = "";
-
-  async main(client) {
-    if (client.check_on_init()) {
-      const view = z2ui5_cl_ui5_view_builder.factory()
-        .ele({ n: `View`, ns: `mvc` })
-        .a({ n: `xmlns`,     v: `sap.m` })
-        .a({ n: `xmlns:mvc`, v: `sap.ui.core.mvc` });
-
-      const page = view.ele(`Shell`).ele(`Page`).a({ n: `title`, v: `Hello World` });
-
-      page.tag(`Input`).a({ n: `value`, v: client._bind_edit(this.name) })
-        .tag(`Button`)
-        .a({ n: `text`,  v: `Send` })
-        .a({ n: `press`, v: client._event(`BUTTON_POST`) });
-
-      client.view_display(view.stringify());
-
-    } else if (client.check_on_event("BUTTON_POST")) {
-      client.message_box_display(`Your name is ${this.name}`);
-    }
+// cap2UI5
+main(c) {
+  if (c.isDisplay) {
+    c.view(/* … */);
+    return;
   }
+  if (c.eventName === "GO") c.messageBox(`Hello ${this.name}`);
 }
 ```
 
-The structure is the same, method for method. The two places the languages part company are visible above: ABAP names its arguments (`n = … v = …`) where JavaScript passes one object, and the binding call differs — `_bind` upstream, `_bind_edit` here, because on the pinned 1.142.0 that is still the two-way one. Everything else maps line by line, which is exactly what makes machine transpilation of the samples possible.
+Structure for structure. The languages part company in two places: ABAP names
+its arguments where JavaScript passes an object, and `_bind( name )` becomes
+`c.bind("name")` because JavaScript cannot match a value by reference.
 
-## How the two stay in sync
+## Which one do I want?
 
-cap2UI5 is not a one-time fork. The [builder-abap2UI5-js repository](https://github.com/cap2UI5/builder-abap2UI5-js) runs automated pipelines that mirror abap2UI5 and **transpile the ABAP sources to JavaScript** with *abap2js* (built on the [@abaplint](https://github.com/abaplint/abaplint) parser):
+**Your data is in an SAP system** → abap2UI5. Running the UI where the data is
+avoids an integration you would otherwise have to build and secure.
 
-- the **frontend** is taken over 1:1 (only the bootstrap URL and the backend endpoint are patched),
-- the **sample apps** are fully machine-transpiled — that's why `core/srv/app/samples/` contains over a hundred `z2ui5_cl_smp_app_*` classes,
-- the **framework core** under `core/srv/z2ui5/` is generated from a hand-maintained adaptation (the builder's `src/`); transpiled classes are only ever *added*, never overwrite the curated files.
+**Your data is in CAP** → cap2UI5. Your apps read it with `cds.ql`, share the
+project's authentication, and a plain OData service can sit beside them on the
+same tables.
 
-[builder-cap2UI5](https://github.com/cap2UI5/builder-cap2UI5) then assembles the finished CAP app from the published core and publishes it into the [cap2UI5 repository](https://github.com/cap2UI5/cap2UI5).
+**Both** → both. The frontend is the same, the concepts are the same, and a
+developer moving between them is reading the same documentation.
 
-A jest suite gates every sync — only a green build is committed.
+## Does the CAP side lag behind?
 
-## Migration ABAP → CAP
+Not structurally. The runtime is a dependency: a new abap2UI5 release is a
+version bump, and it brings the backend and the frontend together. There is no
+port to catch up, no pipeline to re-run, nothing to re-transpile by hand.
 
-Because the wire format and API are compatible, migrating an existing abap2UI5 app to cap2UI5 is mechanical: rewrite the class method for method, convert data access from OpenSQL to CDS queries and outbound calls from `cl_http_client` to `fetch`, drop the file into `srv/app/`, run it. The same static frontend renders both without changes.
+What can lag is the **facade** — `c` covers the common surface, and something
+newly added upstream may need a member here before it is convenient. `c.raw`
+reaches it in the meantime, under its original name.
 
-→ [**Migrating from abap2UI5**](./migration-from-abap2ui5) is the full walkthrough, with a per-construct mapping table for classes, views, binding, structures, data access and outbound calls.
+## Next
 
-→ Or have a look at the [**examples**](../examples/hello-world) and jump straight to the [**API reference**](../api/client).
+- [**Migrating from abap2UI5**](./migration-from-abap2ui5) — the translation table
+- [**Where cap2UI5 Comes From**](./where-it-comes-from) — why this is a host and not a port
diff --git a/docs/guide/what-is-cap2ui5.md b/docs/guide/what-is-cap2ui5.md
index 67fb294..0aa09b9 100644
--- a/docs/guide/what-is-cap2ui5.md
+++ b/docs/guide/what-is-cap2ui5.md
@@ -1,6 +1,6 @@
 # What is cap2UI5?
 
-**cap2UI5** lets you build complete SAPUI5 applications **inside your CAP backend (Node.js)** — as plain JavaScript classes. No separate frontend project, no hand-written XML views, no `manifest.json`, no second build pipeline. One class in `srv/` = one app.
+**cap2UI5** lets you build complete SAPUI5 applications **inside your CAP backend (Node.js)** — as plain JavaScript classes. No separate frontend project, no `manifest.json`, no second build pipeline. One file in `srv/apps/` is one app, and `npm i cap2ui5` is the whole installation.
 
 It is the CAP/Node.js twin of [abap2UI5](https://github.com/abap2UI5/abap2UI5), a popular open-source framework from the ABAP world. Never heard of abap2UI5? That's expected — it lives on the other side of the SAP fence. The short version: it lets ABAP developers write UI5 apps purely in ABAP, and it's been very successful at that. cap2UI5 brings the exact same concept to CAP. The full story, including how the two stay in sync, is on [Where cap2UI5 comes from](./where-it-comes-from).
 
@@ -58,45 +58,53 @@ So it is **not** classical SSR (no HTML pages are re-sent) and **not** an SPA (t
 
 ## What you write
 
-A cap2UI5 app is **a single JavaScript class** extending `z2ui5_if_app`:
+A cap2UI5 app is **a single JavaScript class**, registered with `defineApp`:
 
 ```js
-const z2ui5_if_app              = require("abap2UI5/z2ui5_if_app");
-const z2ui5_cl_ui5_view_builder = require("abap2UI5/z2ui5_cl_ui5_view_builder");
-
-class my_hello_world extends z2ui5_if_app {
-
-  name = "";        // ← app state, persisted automatically
-
-  async main(client) {
-    if (client.check_on_init()) {
-      // first call: render the view
-      const view = z2ui5_cl_ui5_view_builder.factory()
-        .ele({ n: `View`, ns: `mvc` })
-        .a({ n: `xmlns`,     v: `sap.m` })
-        .a({ n: `xmlns:mvc`, v: `sap.ui.core.mvc` });
-
-      view.ele(`Shell`).ele(`Page`).a({ n: `title`, v: `Hello World` })
-        .tag(`Input`).a({ n: `value`, v: client._bind_edit(this.name) })
-        .tag(`Button`)
-        .a({ n: `text`,  v: `Send` })
-        .a({ n: `press`, v: client._event(`BUTTON_POST`) });
-
-      client.view_display(view.stringify());
+// srv/apps/hello.js
+const { defineApp } = require("cap2ui5");
+
+defineApp("ZCL_HELLO", class {
+
+  name = "";                      // ← app state, persisted automatically
+
+  main(c) {                       // ← synchronous: no async, no await
+    if (c.isDisplay) {
+      c.view(
+        `<mvc:View xmlns:mvc="sap.ui.core.mvc" xmlns="sap.m" displayBlock="true" height="100%">` +
+        `<Shell><Page title="Hello World">` +
+        `<Input value="${c.bind("name")}"/>` +
+        `<Button text="Send" press="${c.event("GO")}"/>` +
+        `</Page></Shell></mvc:View>`);
+      return;
+    }
 
-    } else if (client.check_on_event("BUTTON_POST")) {
-      // button clicked: this.name already contains the user's input
-      client.message_box_display(`Hello, ${this.name}!`);
+    if (c.eventName === "GO") {
+      // the button was clicked; this.name already holds what the user typed
+      c.messageBox(`Hello, ${this.name}!`);
     }
   }
-}
-module.exports = my_hello_world;
+});
 ```
 
-That's the whole app. No `manifest.json`, no `Component.js`, no controller file, no i18n setup. The class fields are your state, `main(client)` is your logic, and the view builder produces the UI.
+That is the whole app. No `manifest.json`, no `Component.js`, no controller
+file, no i18n setup. The class fields are your state, `main(c)` is your logic,
+and the view is UI5 XML with two holes in it: `c.bind()` for a field and
+`c.event()` for a handler.
+
+::: tip Render on `isDisplay`
+`c.isDisplay` is true on the first roundtrip **and** whenever the app gets the
+screen back — from a called app, a value help, a restored bookmark. Rendering
+only on `c.isFirstRun` produces an app that silently shows its previous screen
+after a navigation. See [App Lifecycle](./lifecycle).
+:::
 
-::: tip About those class names
-`z2ui5_cl_ui5_view_builder`, `check_on_init`, `_bind_edit` — the naming comes from abap2UI5's ABAP conventions and is kept intentionally, so every abap2UI5 sample and doc maps 1:1 to cap2UI5. It looks unusual in JS at first; you get used to it within an hour.
+::: tip About the names
+`ZCL_HELLO`, and `z2ui5_if_client` behind `c.raw` — the framework running under
+the plugin *is* ABAP, so its identifiers are ABAP's. The facade renames the
+handful you meet daily (`c.isDisplay`, `c.bind`, `c.event`); everything else
+keeps its original name, which is what lets every abap2UI5 sample and document
+still map onto what you are doing.
 :::
 
 ## The gap this closes {#the-gap}
@@ -122,13 +130,13 @@ There was **nothing in between** — no lightweight way to get a free-form UI5 U
 - **Not a UI5 replacement.** It *uses* UI5, in its full breadth — Page, Table, SimpleForm, charts, file upload, camera, geolocation. Only the view *definition* moves to the server.
 - **Not a replacement for CAP services.** Your `srv/*.cds` services keep running unchanged. cap2UI5 is one additional REST action alongside them; OData consumers never see it.
 - **Not classical server-side rendering.** The server sends view XML + a JSON delta, not finished HTML pages.
-- **Not a big framework dependency.** It's a pattern plus a vendored library package (`core/`) that travels inside your CAP project.
+- **Not a big framework dependency.** It is a CAP plugin: two packages in `node_modules`, nothing generated into your repository.
 
 ## When is cap2UI5 the right choice?
 
 ✅ **Internal tools, admin backends, workflow apps** — quickly assembled, one developer is enough, no frontend build setup.
 ✅ **Migration and data-maintenance UIs** — you're writing CAP services anyway and need a small UI on top.
-✅ **Prototyping** — from idea to clickable UI in minutes; try it in the [browser playground](./playground) right now.
+✅ **Prototyping** — from idea to clickable UI in minutes.
 ✅ **Wizards and state-heavy flows** — the next screen depends on previous inputs? That's an `if` statement here, not an annotation puzzle.
 
 And what it costs, plainly:
@@ -141,10 +149,11 @@ And what it costs, plainly:
 
 | Piece | Where | Who touches it? |
 |---|---|---|
-| Backend library (handler, view builder, persistence) | [`cap2UI5/cap2UI5`](https://github.com/cap2UI5/cap2UI5) → `core/srv/z2ui5/` | nobody — carried along as-is |
-| Your apps | `srv/app/` or your own folder | **you** — this is where you work |
-| Static UI5 frontend | `app/z2ui5/webapp/` — mirrored 1:1 from [abap2UI5](https://github.com/abap2UI5/abap2UI5) | nobody — synced automatically |
+| The framework (handler, views, persistence) | `@abap2ui5/runtime` — upstream's own ABAP, transpiled | nobody: it is a dependency |
+| Your apps | `srv/apps/` or a folder you configure | **you** — this is where you work |
+| The UI5 shell | served from the same `@abap2ui5/runtime` package, at `/z2ui5/webapp` | nobody — it ships with the framework |
+| UI5 itself | the OpenUI5 CDN, unless your [user exit](./user-exit#onpage) points elsewhere | you, if your server has no internet access |
 
-The frontend is **wire-format compatible** with abap2UI5: the browser cannot tell whether ABAP or Node.js answers. Every upstream frontend improvement flows into cap2UI5 automatically via a [sync pipeline](./where-it-comes-from#how-the-port-actually-works).
+The frontend is not merely *compatible* with abap2UI5's — it **is** abap2UI5's, shipped in the same package as the backend that answers it, from the same upstream commit. The browser cannot tell whether ABAP or Node.js is on the other side, and backend and frontend cannot drift apart. See [Where cap2UI5 Comes From](./where-it-comes-from).
 
 → Continue with [**Why cap2UI5?**](./why-cap2ui5) for the case in your own project's terms, or jump straight to the [**Quickstart**](./getting-started).
diff --git a/docs/guide/where-it-comes-from.md b/docs/guide/where-it-comes-from.md
index 74a2bd5..e410b41 100644
--- a/docs/guide/where-it-comes-from.md
+++ b/docs/guide/where-it-comes-from.md
@@ -1,58 +1,107 @@
 # Where cap2UI5 Comes From
 
-If you're a CAP developer, chances are you've never heard of **abap2UI5** — it lives in the ABAP world. But cap2UI5 is a direct descendant of it, and knowing the family history explains many of its design decisions (and its unusual class names like `z2ui5_cl_ui5_view_builder`). Don't worry: **you never need to read or write a single line of ABAP** to use cap2UI5.
+cap2UI5 is a direct descendant of **abap2UI5**, and today it is more than a
+descendant: it *runs* abap2UI5. Knowing the family history explains the unusual
+names you will meet (`ZCL_…`, `z2ui5_if_client`) and why the design looks the
+way it does. You never need to read or write a line of ABAP to use it.
 
 ## The abap2UI5 story
 
-[abap2UI5](https://github.com/abap2UI5/abap2UI5) is a popular open-source community project from the SAP/ABAP ecosystem. Its promise: **write complete SAPUI5 apps purely in ABAP classes** — no JavaScript, no XML views to deploy, no separate frontend artifacts, no BSP/UI5 repository uploads. One ABAP class = one app.
+[abap2UI5](https://github.com/abap2UI5/abap2UI5) is an open-source project from
+the SAP/ABAP world. Its promise: **write complete SAPUI5 apps purely in ABAP
+classes** — no JavaScript, no XML views to deploy, no separate frontend
+artifacts, no BSP or UI5 repository uploads. One ABAP class, one app.
 
-It works with the [server-driven UI pattern](./what-is-cap2ui5#server-driven-ui), with an ABAP class in place of the JavaScript one: a generic UI5 frontend is served to the browser once, every interaction is one HTTP roundtrip, and the ABAP class builds the view as XML, binds data and handles events.
+It works by the [server-driven UI pattern](./what-is-cap2ui5#server-driven-ui):
+a generic UI5 frontend is served to the browser once, every interaction is one
+HTTP roundtrip, and the class builds the view, binds data and handles events.
 
-The project became successful because it removed an entire deployment and tooling layer for internal tools and utility apps — the same gap that exists on the CAP side. Over the years it grew a large sample collection ([abap2UI5-samples](https://github.com/abap2UI5/samples)), add-ons, and a community, all documented at [abap2UI5.org](https://www.abap2ui5.org). **cap2UI5 is that concept ported to CAP/Node.js**: instead of an ABAP class on NetWeaver, a JavaScript class in your CAP project's `srv/` folder.
+It removed an entire deployment and tooling layer for internal tools — the same
+gap that exists on the CAP side. That is the gap cap2UI5 fills.
 
-## How the port actually works
+## How it used to work: a port
 
-This is the interesting part, and it's more than a one-time copy. cap2UI5 stays **continuously in sync** with abap2UI5 through automated pipelines in two build repositories — [builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js) (the framework build) and [builder-cap2UI5](https://github.com/cap2UI5/builder-cap2UI5) (the app build):
+For most of this project's life, cap2UI5 was a **hand-written JavaScript port**
+of abap2UI5, kept in sync by build pipelines:
+
+- a transpiler of our own (`abap2js.js`, 4,286 lines) turned upstream's ABAP
+  into JavaScript;
+- a port of the framework (12,588 lines) filled the gaps it could not;
+- nightly pipelines mirrored upstream, rebuilt the core and published a
+  ready-made CAP app into this repository.
+
+It worked, and it had a structural problem: **two implementations of one
+protocol drift.** A conformance gate built to measure that drift found 17
+differences — including the one that mattered, that this project's *frontend*
+and its *backend* had come to speak different protocols. Upstream had moved to a
+new response envelope; the port still wrote the superseded one; the frontend
+looked for a key the backend no longer produced and rendered its empty result,
+silently.
+
+No test could have caught it, because each half was consistent with itself.
+
+## How it works now: a host
+
+So the strategy changed. cap2UI5 stopped porting abap2UI5 and became a **CAP
+plugin that hosts it**:
 
 ```
-abap2UI5 (ABAP sources + UI5 frontend)          abap2UI5/samples
-        │                                              │
-        ▼                                              ▼
-┌──────────── builder-abap2UI5-js sync pipelines ───────────────────────┐
-│ update_backend   mirror → transpile ABAP → JS with abap2js            │
-│                  (parser: @abaplint) → core/srv/z2ui5                 │
-│ update_frontend  mirror → take the UI5 webapp 1:1, patch two          │
-│                  config values → core/app/z2ui5/webapp                │
-│ update_samples   mirror → transpile the demo apps                     │
-│                  → core/srv/app/samples                               │
-│ build_core       overlay the generated trees on the hand-written      │
-│                  src/ → publish the core package into core/           │
-│                  jest suite gates the commit — only green gets pushed │
-└────────────────────────────────┬───────────────────────────────────────┘
-                                 ▼
-┌──────────── builder-cap2UI5 update_cap ────────────────────────────────┐
-│ mirror the published core → assemble the CAP app (src/ + vendored     │
-│ core) → test → publish 1:1 into the deployable cap2UI5/cap2UI5 repo   │
-└─────────────────────────────────────────────────────────────────────────┘
+abap2UI5 (the real ABAP sources)
+        │  npm run auto_downport      ← to 7.02-compatible ABAP
+        │  npm run auto_transpile     ← @abaplint/transpiler, over open-abap
+        ▼
+@abap2ui5/runtime          the backend AND the UI5 shell, one package, one commit
+        │
+        ▼
+cap2ui5 (this plugin)      mounts the route, implements the draft store over a
+                           CDS entity, turns a JS class into something the
+                           runtime can call — and contains no framework logic
 ```
 
-Three different sync policies keep the pieces healthy:
+The numbers, since they are the argument:
 
-| Piece | Where it lands | Policy |
+| | port | host |
 |---|---|---|
-| **Frontend** (`app/webapp` from abap2UI5) | `core/app/z2ui5/webapp` → mirrored to the app's `app/z2ui5/webapp` | replaced 1:1 — only the UI5 bootstrap URL in `index.html` and the backend endpoint in `manifest.json` are patched |
-| **Framework core** (transpiled ABAP classes) | `core/srv/z2ui5/` | *fill-in only*: the hand-maintained adaptation in builder-abap2UI5-js's `src/` wins; transpiled classes are added but never overwrite the curated files |
-| **Samples** (transpiled demo apps) | `core/srv/app/samples/` | fully machine-owned: overwritten on every sync |
+| framework code maintained here | 16,874 lines | **774**, of which 485 are code |
+| wire drift against abap2UI5 | 17 measured | structurally impossible — same code |
+| frontend/backend pairing | assembled by us | one upstream commit |
+
+Drift is not *reduced*. It cannot happen: there is only one implementation, and
+both halves ship together.
+
+## What upstream had to open
+
+Hosting the framework outside an SAP system needed four small, additive changes
+in abap2UI5 — none of them CAP-specific, all merged upstream:
+
+| | |
+|---|---|
+| `z2ui5_if_ui5_draft_store` | session state behind an interface, so a host can put it in a CDS entity instead of an ABAP table |
+| `z2ui5_if_ui5_serializer` | app-state serialization behind an interface, because `CALL TRANSFORMATION` has no counterpart outside ABAP |
+| a guarded codepage fallback | **a bug fix.** On a runtime with neither codepage class, a failure escaped from inside an exception handler and took the view builder down before any app code ran. It presented as a *hang* |
+| `c_protocol` | the wire carries its own version, and the shell refuses a mismatch loudly instead of rendering an empty result |
+
+The third one is the reason to read that list twice: it was found here, on a
+transpiled Node runtime, and fixed at the source for everybody.
+
+## What is left of the port
+
+The conformance gate that found the drift, and the measurements that made the
+decision, live in
+[builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js) together
+with the ADRs. The app-building pipelines are archived: nothing is generated any
+more.
 
-The transpiler (**abap2js**, built on the open-source ABAP parser [@abaplint/core](https://github.com/abaplint/abaplint)) converts ABAP classes into plain JavaScript. Anything outside its supported subset is emitted as a visible `// TODO(abap2js): …` comment instead of being silently dropped, and tracked in a transpile report.
+## Why the ABAP names remain
 
-## What this means for you
+`ZCL_HELLO`, `z2ui5_if_client`, `check_on_init` — the runtime *is* ABAP, so its
+identifiers are ABAP's. The plugin's facade renames the handful an app author
+meets every day (`c.isDisplay`, `c.bind`, `c.event`), and `c.raw` reaches the
+rest under their original names. Every abap2UI5 sample and document therefore
+still maps onto what you are doing.
 
-- **The frontend is battle-tested.** You're running the exact UI5 app that thousands of abap2UI5 installations use — every upstream bugfix and new custom control (charts, camera, geolocation, …) flows in automatically.
-- **The wire format is identical.** The frontend cannot tell whether ABAP or Node.js is answering. That's why the whole ecosystem of abap2UI5 knowledge, samples, and patterns applies 1:1.
-- **The naming is inherited.** `z2ui5_cl_ui5_view_builder`, `check_on_init`, `_bind_edit` — these names come from ABAP conventions (`z` = customer namespace, `cl` = class, `if` = interface). They look unusual in JavaScript, but they keep the two worlds mappable line-by-line: any abap2UI5 sample can be ported (or auto-transpiled) to cap2UI5 mechanically.
-- **Not everything upstream ships comes along.** The port carries one pinned framework release and deliberately leaves upstream's frozen legacy package behind — see [cap2UI5 vs. abap2UI5](./vs-abap2ui5) for what that means when you copy an older sample.
-- **Hundreds of ready samples.** The `core/srv/app/samples/` folder ships the transpiled abap2UI5 demo apps (`z2ui5_cl_smp_app_*`) — a huge, browsable cookbook. Try them in the [browser playground](./playground) without installing anything.
-- **You still write normal JavaScript.** The sync pipeline is a maintainer concern. As an app developer you just `require` two classes and write a JS class — see the [Quickstart](./getting-started).
+## Next
 
-→ Next: [**Try it in the browser**](./playground) — zero-install playground, or the [**Quickstart**](./getting-started).
+- [**What is cap2UI5?**](./what-is-cap2ui5) — the pattern itself
+- [**Architecture**](../reference/architecture) — how host and runtime fit together
+- [**cap2UI5 vs. abap2UI5**](./vs-abap2ui5) — what differs in practice
diff --git a/docs/guide/why-cap2ui5.md b/docs/guide/why-cap2ui5.md
index 81dacdb..d37d8b2 100644
--- a/docs/guide/why-cap2ui5.md
+++ b/docs/guide/why-cap2ui5.md
@@ -39,18 +39,17 @@ With cap2UI5 the structure shrinks to:
 
 ```
 my-cap-project/
-├── srv/
-│   ├── z2ui5-service.cds            # ← + 4 lines for the z2ui5 action
-│   ├── z2ui5-service.js             # ← + 1 line srv.on('z2ui5', handler)
-│   ├── server.js                    # ← + bootstrap HTML mount
-│   └── app/
-│       └── my_app.js                # ← your app. One file.
-├── core/                            # ← vendored library (carried along unchanged)
-└── app/
-    └── z2ui5/                       # ← static frontend (carried along unchanged)
+├── package.json                     # ← + 1 dependency: cap2ui5
+└── srv/
+    └── apps/
+        └── my_app.js                # ← your app. One file.
 ```
 
-A new UI = **a new JS file in `srv/app/`** (or any [registered app folder](./project-structure#srv-app)). Available immediately via `?app_start=my_app`.
+Nothing else. No service definition to extend, no `server.js` to touch, no
+frontend folder: the route, the UI5 shell and the draft entity arrive with the
+plugin, and `cds deploy` creates the table next to your own.
+
+A new UI = **a new JS file in `srv/apps/`**. Available immediately via `?app_start=ZCL_MY_APP` — the name you gave `defineApp`.
 
 ## Concrete advantages
 
@@ -76,21 +75,23 @@ class CustomerEdit extends z2ui5_if_app {
   is_dirty      = false;
   validation    = { name: "None", email: "None" };
 
-  async main(client) { /* ... */ }
+  async main(c) { /* ... */ }
 }
 ```
 
-After every roundtrip the entire instance is **persisted automatically in the CDS entity `z2ui5_t_01`**. On the next roundtrip it is deserialized, the frontend delta (XX) is applied, and `main()` runs again. You don't need to manage a JSONModel, write a reducer, or build a "service worker" for offline state — the server holds everything.
+After every roundtrip the entire instance is **persisted automatically in the CDS entity `cap2ui5.Drafts`**. On the next roundtrip it is rebuilt, the browser's model is applied, and `main(c)` runs again. You don't need to manage a JSONModel, write a reducer, or build a "service worker" for offline state — the server holds everything.
 
-### 3. Reference-equality bindings
+### 3. Bindings without a model
 
 This is the core pattern that makes cap2UI5 (and abap2UI5) lightweight code in the first place:
 
 ```js
-form.tag(`Input`).a({ n: `value`, v: client._bind_edit(this.name) });
+`<Input value="${c.bind("name")}"/>`
 ```
 
-`_bind_edit(this.name)` looks at your app instance to find **which property corresponds to the passed value** and returns the path as a UI5 binding expression `{/XX/NAME}`. When the user types, the value flows back through the delta into `this.name`. No manual mapping, no property strings, no sync code.
+`c.bind("name")` returns the UI5 binding path for that field. Binding is two-way: when the user types, the value arrives on `this.name` **before** your next `main(c)` runs. No JSONModel, no property mapping, no sync code.
+
+(In abap2UI5 the ABAP call passes the attribute itself and the framework matches it by reference. JavaScript cannot do that — two empty strings are indistinguishable — so the facade takes the field name instead.)
 
 → Details under [Data Binding](./data-binding).
 
@@ -115,7 +116,7 @@ Inside `main()` you can do **anything** Node.js allows — including, of course,
 
 ```js
 async main(client) {
-  if (client.check_on_init()) {
+  if (c.isDisplay) {
     const northwind = await cds.connect.to("northwind");
     this.customers = await northwind.run(SELECT.from("Customers"));
     /* ... view ... */
@@ -137,7 +138,7 @@ The UI5 bundle is loaded once. After that every roundtrip returns only **a bit o
 
 ## Where it gets unfair
 
-The trade-offs are listed on [What is cap2UI5?](./what-is-cap2ui5#the-gap) — offline, pixel-perfect design systems, read-heavy filtering. One of them is worth a second sentence here, because it is the one that bites in a CAP project: a **live search filter over millions of rows** sends every keystroke's filter change to the server, where a Fiori Elements list filters locally in the JSONModel or pages server-side through the OData driver. If that is your screen, use the OData model (see [set_odata_model](../examples/external-odata#3-persistence-caveat)) or build that one screen with Fiori Elements.
+The trade-offs are listed on [What is cap2UI5?](./what-is-cap2ui5#the-gap) — offline, pixel-perfect design systems, read-heavy filtering. One of them is worth a second sentence here, because it is the one that bites in a CAP project: a **live search filter over millions of rows** sends every keystroke's filter change to the server, where a Fiori Elements list filters locally in the JSONModel or pages server-side through the OData driver. If that is your screen, use the OData model (see [set_odata_model](../examples/external-odata#where-the-data-goes)) or build that one screen with Fiori Elements.
 
 For **UI-centric back-office apps**, which are the typical CAP use case, cap2UI5 is almost always the more ergonomic choice.
 
diff --git a/docs/index.md b/docs/index.md
index f623cbf..329a9e3 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -4,7 +4,10 @@ layout: home
 hero:
   name: "cap2UI5"
   text: "Server-driven UI5 for CAP"
-  tagline: Build complete SAPUI5 apps directly from your CAP backend in JavaScript — no separate frontend project, no hand-crafted XML, no manifest tuning.
+  tagline: >-
+    A CAP plugin that hosts abap2UI5's own runtime. Write complete SAPUI5 apps
+    as plain JavaScript classes in your CAP project — no separate frontend, no
+    XML by hand, no manifest tuning.
   image:
     src: /logo.jpeg
     alt: cap2UI5
@@ -12,32 +15,45 @@ hero:
     - theme: brand
       text: Quickstart
       link: /guide/getting-started
-    - theme: alt
-      text: Try it in the browser
-      link: https://cap2ui5.github.io/web-cap2UI5-build/
     - theme: alt
       text: What is cap2UI5?
       link: /guide/what-is-cap2ui5
 
 features:
-  - title: Pure JavaScript apps
-    details: Define view, state and behavior in a single JS class inside srv/. No tooling overhead, no UI5 build, no duplicated data modeling.
+  - title: One dependency, no scaffolding
+    icon: 🔌
+    details: >-
+      npm i cap2ui5 is the whole installation. The roundtrip route, the UI5
+      shell and the cap2ui5.Drafts entity arrive through cds-plugin.js — your
+      own server.js is untouched, and nothing is generated into your repository.
+  - title: Apps are plain JavaScript
     icon: 🟨
-  - title: Born from abap2UI5
-    details: The proven abap2UI5 concept, ported to CAP — same frontend, same protocol, kept in sync automatically by an ABAP→JS transpiler pipeline.
+    details: >-
+      defineApp("ZCL_HELLO", class { name = ""; main(c) { … } }) — synchronous,
+      no async, no await, no ABAP. State is ordinary fields, and c.bind("name")
+      binds one into the view.
+  - title: It IS abap2UI5, not a copy of it
     icon: 🔗
-  - title: Automatic data binding
-    details: client._bind(this.field) finds the property by reference equality on the app instance — no model boilerplate. On the pinned 1.142.0 core, _bind_edit is the two-way variant.
-    icon: 🔄
-  - title: Native CAP integration
-    details: The roundtrip runs as a CDS REST action. CAP services, OData connections, auth, destinations — everything remains available.
+    details: >-
+      The backend is upstream's own ABAP, downported and transpiled over
+      open-abap and shipped as @abap2ui5/runtime. Backend, frontend and wire
+      version come from one commit, so drift is structurally impossible.
+  - title: A guest in your CAP project
     icon: 🧩
-  - title: Stateful sessions included
-    details: Apps are persisted between roundtrips (CDS entity z2ui5_t_01). Navigation stack, draft history, and popup results out of the box.
+    details: >-
+      One authorization for both doors. The apps read and write through cds.ql
+      like any handler, and a plain OData service beside them sees the same
+      rows — proven by a coexistence test rather than asserted.
+  - title: Sessions in your database
     icon: 💾
-  - title: A live sample for every feature
-    details: The transpiled abap2UI5 demo collection ships in core/srv/app/samples/ — and runs zero-install in the browser playground on GitHub Pages.
-    icon: 🎨
-    link: /guide/samples
-    linkText: Browse the sample catalogue
+    details: >-
+      App state lives in cap2ui5.Drafts, an ordinary CDS entity — same
+      connection, same transaction, same authorization as everything else. Each
+      draft answers to the user who created it and to nobody else.
+  - title: Measured, not claimed
+    icon: 📐
+    details: >-
+      14 ms per roundtrip. State survives SIGKILL, navigation stack included.
+      Three users interleaved in one process, every answer to its owner.
+      Rendered in real Chromium on every CI run.
 ---
diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md
index 5337900..f11421d 100644
--- a/docs/reference/architecture.md
+++ b/docs/reference/architecture.md
@@ -1,237 +1,113 @@
 # Architecture
 
-This page shows in detail **how a roundtrip flows through the system** — from the click in the browser to DB persistence and back.
+cap2UI5 does not reimplement abap2UI5. It **hosts** it.
 
-## Component overview
+That sentence is the whole architecture, and it is a change from what this
+project used to be — see [Where cap2UI5 Comes From](../guide/where-it-comes-from).
 
-```
-┌────────── Browser ──────────┐
-│  Static UI5 bundle          │
-│  (from abap2UI5 mirror)     │
-│   ├ index.html              │
-│   ├ Component.js            │
-│   ├ actions/*.js (eF/eB)    │
-│   └ JSONModel               │
-└────────────┬────────────────┘
-             │ POST /rest/root/z2ui5
-             │ { S_FRONT, XX, MODEL }
-             ▼
-┌──────── CAP server ─────────┐
-│  Express + @sap/cds         │
-│  z2ui5-service.cds          │
-│   action z2ui5(value)       │
-│  z2ui5-service.js           │
-│   srv.on('z2ui5', handler)  │
-└────────────┬────────────────┘
-             │
-             ▼
-┌─ z2ui5_cl_ui5_http_handler ─┐
-│  unwrap req.data.value      │
-└────────────┬────────────────┘
-             │
-             ▼
-┌──── z2ui5_cl_ui5_handler ───┐
-│  1. action.factory_main     │── ▶ DB.loadApp(id)
-│  2. validate                │
-│  3. apply XX delta          │
-│  4. await app.main(client)  │── ▶ your app class
-│  5. nav loop (if active)    │
-│  6. db_save                 │── ▶ DB.saveApp
-│  7. build response          │
-└────────────┬────────────────┘
-             │
-             ▼
-┌────── CDS persistence ──────┐
-│  Entity z2ui5_t_01          │
-│  (UUID, id_prev, data)      │
-└─────────────────────────────┘
-```
-
-## Roundtrip in detail
-
-### 1. HTTP reception
-
-The `z2ui5-service.cds` declares:
-
-```cds
-@protocol: 'rest'
-service rootService {
-  @open type object {};
-  action z2ui5(value : object) returns object;
-}
-```
-
-CAP automatically exposes this under `POST /rest/root/z2ui5`. The body lands as the CDS action parameter `value` (type `object`).
-
-In addition, `server.js` registers via `cds.on("bootstrap", ...)`:
-
-- `GET /rest/root/z2ui5` → returns the bootstrap HTML via `engine.bootstrap_html(...)`
-- `HEAD /rest/root/z2ui5` → CSRF token prefetch and sap-terminate ack
-
-### 2. CDS action handler
-
-In `z2ui5-service.js`:
-
-```js
-srv.on("z2ui5", z2ui5_cl_ui5_http_handler);
-```
-
-`z2ui5_cl_ui5_http_handler` only does the action wrapper unwrapping:
-
-```js
-const oBody = req?.data?.value ?? req?.data ?? req;
-const oHandler = new z2ui5_cl_ui5_handler();
-const responseJson = await oHandler.main(oBody);
-return JSON.parse(responseJson);
-```
-
-It unwraps the abap2UI5-compatible body from the CDS action wrapper. With that, `oBody` is exactly what the abap2UI5 ICF interface receives directly.
-
-### 3. Roundtrip orchestrator
-
-`z2ui5_cl_ui5_handler.main(body)` runs through seven phases:
-
-#### Phase 1 — app resolution
-
-```js
-let oApp = await Action.factory_main(oReq, oClient);
-```
-
-`z2ui5_cl_ui5_action.factory_main` determines which app serves this roundtrip:
-
-1. `oClient._navTarget` (in-memory, from a previous hop) — rare
-2. `oReq.S_FRONT.ID` — DB load
-3. `?app_start=ClassName` URL parameter — RTTI lookup
-4. **Fallback**: `z2ui5_cl_ui5_app_start` (built-in launcher)
+## The three pieces
 
-It also rehydrates the nav stack from `oApp.__navStackIds`.
-
-#### Phase 2 — validation
-
-```js
-z2ui5_cl_ui5_app_cont.validate(oApp);
 ```
-
-Throws if the app does not extend `z2ui5_if_app`.
-
-#### Phase 3 — apply XX delta
-
-```js
-z2ui5_cl_ui5_srv_model.main_json_to_attri(oApp, oReq.XX);
-```
-
-The `XX` object on the request contains the user edits from two-way bindings (e.g. `{XX: { username: "Alice" }}`). The engine applies them to the app instance (deep merge).
-
-#### Phase 4 — call `main()`
-
-```js
-await oApp.main(oClient);
-oApp.check_initialized = true;
+  your CAP project
+  ├── srv/apps/*.js          your apps          ← you write this
+  ├── db/, srv/*.cds         your model          ← you write this
+  └── node_modules/
+      ├── cap2ui5            the plugin          ← ~485 lines of code
+      │   ├── cds-plugin.js    mounts the route, serves the shell
+      │   ├── index.cds        cap2ui5.Drafts
+      │   └── lib/
+      │       ├── define-app.js    a JS class → something the runtime can call
+      │       ├── draft-store.js   the draft store, over a CDS entity
+      │       └── runtime.js       locate and boot the runtime
+      └── @abap2ui5/runtime  abap2UI5 itself     ← 1,244 transpiled files
+          ├── output/            upstream's ABAP, downported + transpiled
+          └── webapp/            the UI5 shell, from the same commit
 ```
 
-This is where your own app logic runs. While `main()` runs, it writes slots into `oClient` via `client.view_display(...)`, `client.message_toast_display(...)` etc.
-
-#### Phase 5 — nav loop
+The plugin contains **no framework logic**. No view builder, no wire format, no
+lifecycle, no model service — all of that is upstream's code running unmodified.
 
-If `main()` triggered a `nav_app_call(...)` or `nav_app_leave()`, `oClient._navTarget` is set. The handler "takes one step further":
+## Why that removes a whole class of bug
 
-```js
-while (oClient._navTarget) {
-  // ... push / pop stack ...
-  await z2ui5_cl_ui5_app_cont.run(navApp, oClient, oReq, true);
-}
-```
+The runtime is built from one upstream commit and carries the backend *and* the
+frontend. A response and the page that reads it can therefore never be of
+different ages — which was not a hypothetical: the previous design paired a
+hand-maintained backend with a separately synced frontend, and they drifted into
+speaking different protocols without anything noticing.
 
-That means: up to N nested navigations can take place in **a single** roundtrip — e.g. "open picker → user immediately clicks a default → close picker → return".
+Upstream also stamps each response with a wire version, and the shell refuses a
+mismatch loudly. See [HTTP Protocol](./protocol).
 
-#### Phase 6 — persistence
+## A roundtrip, end to end
 
-```js
-const generatedId = await z2ui5_cl_ui5_app_cont.db_save(oApp, oClient, previousId);
 ```
-
-First the stack apps, then the final app. Stack IDs are recorded on `oApp.__navStackIds`.
-
-#### Phase 7 — build response
-
-```js
-const oResponse = {
-  S_FRONT: { APP, ID: generatedId, PARAMS: { S_VIEW, S_POPUP, ... } },
-  MODEL:   z2ui5_cl_ui5_srv_model.main_json_stringify(oClient.aBind)
-};
-return JSON.stringify(oResponse);
+POST /rest/root/z2ui5
+  │
+  ├─ cds.middlewares.before        ← context, auth: cds.context.user now exists
+  ├─ guard                         ← cap2ui5.requires, before the body is read
+  ├─ express.raw                   ← up to 10 MB
+  └─ cl_express_icf_shim.run       ← upstream's own express adapter
+        │
+        ├─ load the draft          ← ZCL_CDS_DRAFT_STORE → cap2ui5.Drafts
+        ├─ rebuild the app instance
+        ├─ apply the browser's model
+        ├─ call your main(c)       ← defineApp's wrapper
+        ├─ compose the response    ← upstream's handler
+        └─ write the next draft
 ```
 
-`MODEL` is built from the `aBind` entries that the builder registered during `main()`. That's the JSONModel that runs as the default model on the frontend.
-
-## Class architecture
-
-The `core/srv/z2ui5/` library mirrors **abap2UI5's layered model**:
-
-```
-00 — Pure utilities (no framework dependencies)
-├─ 00/cl_abap_*                  ABAP runtime shims the transpiled code needs
-├─ 01/z2ui5_cl_ajson_*           JSON tree (the ajson port)
-├─ 02/z2ui5_cl_srt_*             Serialization helpers
-├─ 03/z2ui5_cl_util              RTTI, class lookup, URL builder
-├─ 03/z2ui5_cl_util_http         Request/response facade
-└─ 03/02/z2ui5_cl_util_api*      Context, conversions, UUIDs
-
-01 — Core
-├─ 01/z2ui5_cl_ui5_srv_draft    Serialize / deserialize / DB
-├─ 02/z2ui5_cl_ui5_handler      Roundtrip orchestrator
-├─ 02/z2ui5_cl_ui5_action       App resolution
-├─ 02/z2ui5_cl_ui5_app_cont          Lifecycle helper
-├─ 02/z2ui5_cl_ui5_client       The client class (your API)
-├─ 02/z2ui5_cl_ui5_srv_bind     _bind / _bind_edit implementation
-├─ 02/z2ui5_cl_ui5_srv_event    _event string builder
-├─ 02/z2ui5_cl_ui5_srv_model    XX delta + response model
-├─ 02/z2ui5_if_ui5_types        internal type containers
-└─ 03/z2ui5_cl_ui5f_index_html    bootstrap HTML as a JS module
-
-01/04 — The apps the framework ships
-├─ z2ui5_cl_ui5_app_start        Built-in launcher
-├─ z2ui5_cl_ui5_app_hi_world     Mini example
-├─ z2ui5_cl_ui5_app_select       Value-help app
-├─ z2ui5_cl_ui5_app_error        Error view
-└─ z2ui5_cl_ui5_user_exit        Config hook (theme, CSP, security headers)
-
-02 — Public API (app developer imports)
-├─ z2ui5_if_app                  Base class for your apps
-├─ z2ui5_if_client               The client contract (cs_event / cs_view constants)
-├─ z2ui5_cl_ui5_http_handler     CDS action adapter
-└─ z2ui5_cl_ui5_view_builder     View Builder
-```
+Two of those steps are the plugin's, and both are *seams upstream opened* rather
+than patches:
 
-Those three numbers are the whole tree: `core/srv/z2ui5/` has `00/`, `01/` and `02/` and nothing else. The layering is **no accident** — it's the abap2UI5 convention, ported to JS. If you read into one of these files, you'll find the same layout in the abap2UI5 repo.
+| seam | what it lets a host do |
+|---|---|
+| `z2ui5_if_ui5_draft_store` | put session state wherever it lives — here, a CDS entity |
+| `z2ui5_if_ui5_serializer` | serialize the app container without `CALL TRANSFORMATION` |
 
-## Wire-format compatibility
+Both default to upstream's original code paths, so an SAP system behaves exactly
+as before.
 
-The **frontend webapp** under `app/z2ui5/webapp` is mirrored 1:1 from the abap2UI5 repo by the [sync pipeline](../guide/where-it-comes-from#how-the-port-actually-works) in [builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js) (workflow `update_frontend`, or locally `npm run mirror_app && npm run prepare_app && npm run build_core`); [builder-cap2UI5](https://github.com/cap2UI5/builder-cap2UI5)'s `update_cap` workflow then publishes it into the app repo. Only the UI5 bootstrap URL in `index.html` and the `/rest/root/z2ui5` data source in `manifest.json` are patched. This means: every patch in the abap2UI5 frontend code flows over here automatically.
+## `defineApp` — the part that earns its keep
 
-For that to work, cap2UI5's backend must speak **bit-exact the same wire format** as abap2UI5's ABAP backend:
+The runtime expects what `@abaplint/transpiler` emits: static `ATTRIBUTES` and
+`METHODS` maps, `constructor_()`, `~` becoming `$` in interface method names,
+values boxed in `abap.types.*`. `defineApp` bridges a plain JavaScript class to
+that:
 
-- `S_FRONT.ID`, `S_FRONT.EVENT`, `S_FRONT.T_EVENT_ARG` — all uppercase
-- `MODEL.XX.<path>` for two-way, `MODEL.<path>` for one-way
-- `S_VIEW.XML`, `S_POPUP.XML`, `S_POPOVER.XML`
-- `S_FOLLOW_UP_ACTION.CUSTOM_JS` as an array
-- `S_MSG_TOAST`, `S_MSG_BOX` with ABAP-typical `"X"`/`""` booleans
+- it **boxes** each declared field at construction and derives the RTTI schema
+  from the same pass, because `_bind()` matches a value by *identity* among the
+  object's attributes — there is no name parameter;
+- it hands `main` a **Proxy** whose reads unwrap the boxes and whose writes write
+  through, so your code sees plain values while the framework keeps its boxes;
+- it makes `main` **synchronous**: queries are resolved before it runs, commands
+  are recorded and replayed after, and event tokens are substituted once the
+  async call can be awaited.
 
-This is visible in the code (see `z2ui5_cl_ui5_handler.main` at the bottom).
+## The hazards, and what guards each
 
-## CAP-specific notes
+Neither coupling surface is a published contract, so both have a gate whose job
+is to fail there rather than on the wire.
 
-- **CDS REST action instead of custom Express routing**: makes the z2ui5 endpoint an ordinary CAP service entry — auth, auditing, tracing apply automatically.
-- **CDS entity instead of a custom SQL table**: app persistence uses the normal CAP DB connection. Deploy on SQLite (dev), HANA (cloud), Postgres — works without code changes.
-- **`cds.connect.to(...)` in `main()`**: your apps have immediate access to all declared external services, without separate connection registration.
+| | guarded by |
+|---|---|
+| what the **transpiler emits** — the statics, the boxes, the `$` naming | `abi-gate.test.mjs`: every touchpoint named and checked against a class the transpiler itself produced |
+| **`@sap/cds` internals** — above all `cds.middlewares.before`, which is a *mixed* array of functions and `{factory}` objects | `cap-abi.test.mjs`: the chain read per auth kind, asserting the auth middleware is a plain function and the rest are inert |
 
-## Extension hooks
+Both are verified to discriminate: break the thing they pin, and they go red
+naming it.
 
-Two additive hooks decouple the framework core from Node/CAP specifics:
+## What is measured
 
-- **`z2ui5_cl_util.register_app_class(name, Cls)` / `register_app_dir(dir)`** — plug app classes or directories into the class lookup without touching framework files (see [Persistence](../guide/persistence#class-restoration)).
-- **`z2ui5_cl_ui5_srv_draft.set_store(store)`** — swap the draft persistence backend (default: the CDS entity `z2ui5_t_01`).
+| | |
+|---|---|
+| Roundtrip | **14 ms**, sequential, HTTP, SQLite |
+| The runtime's private SQLite | **no SQL at all** once the CDS store is installed — only `rollback`/`endTransaction` |
+| Restart | state and the navigation stack survive SIGKILL |
+| Concurrency | three users interleaved in one process, every answer to its owner |
+| Browser | real Chromium on every CI run, against the CDN |
 
-These two hooks are all it takes to run the entire backend **without CAP and without a filesystem** — that's how the [browser playground](../guide/playground) bundles the stack into a static site.
+## Next
 
-→ Continue with the [HTTP Protocol](./protocol).
+- [**HTTP Protocol**](./protocol) — what goes over the wire
+- [**Database Model**](./database) — `cap2ui5.Drafts`
+- [**Configuration**](./configuration) — the knobs
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index e9539e7..c9ea266 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -1,164 +1,132 @@
 # Configuration
 
-Two mechanisms cover almost everything you can configure: **environment
-variables** for the platform wiring, and the **user exit** for anything the
-framework renders or sends.
-
-## Environment variables
-
-| Variable | Default | Effect |
-|---|---|---|
-| `Z2UI5_APP_DIRS` | — | extra directories to search for app classes, separated by the platform path separator |
-| `Z2UI5_DRAFT_TTL_HOURS` | the exit's `draft_exp_time_in_hours` | how long draft rows are kept; `0` disables the retention job entirely |
-| `Z2UI5_DRAFT_RETENTION_INSTANCE` | `0` | which Cloud Foundry instance runs the retention loop; `*` for all of them |
-| `PORT` | `4004` (CAP) | the port the server listens on |
-
-```bash
-Z2UI5_APP_DIRS=/srv/my-apps:/srv/more-apps npx cds-serve
-Z2UI5_DRAFT_TTL_HOURS=24 npx cds watch
+Everything the plugin reads lives under `cds.cap2ui5` and is a plain CAP
+configuration value: `package.json#cds`, a `.cdsrc.json`, an environment
+variable, a profile — whatever you already use.
+
+## The defaults
+
+These ship in the plugin's own `package.json` and apply until you override one:
+
+```json
+{
+  "cds": {
+    "cap2ui5": {
+      "apps": "srv/apps",
+      "requires": "authenticated-user",
+      "routes": ["/sap/bc/z2ui5", "/rest/root/z2ui5"],
+      "webapp": "/z2ui5/webapp"
+    }
+  }
+}
 ```
 
-Retention has **one** clock, not two. Unset, `Z2UI5_DRAFT_TTL_HOURS` follows
-the framework's own draft expiry — `draft_exp_time_in_hours` from the user exit,
-4 hours by default — so rows are not deleted while the framework still considers
-the session live. Set, it overrides both. An unparseable value falls back to the
-framework expiry rather than disabling cleanup: a typo must not silently turn
-retention off.
+| key | what it does |
+|---|---|
+| `apps` | the directory scanned for app modules, relative to `cds.root`. Every `.js`/`.mjs`/`.cjs` in it is imported once the runtime is up. A project without the directory simply has no JavaScript apps |
+| `requires` | the role the route demands. `null` lets anonymous callers in — read the box below first |
+| `routes` | the paths the roundtrip answers on. Both defaults exist so that a frontend or a bookmark written for either name works |
+| `webapp` | where the UI5 shell is mounted, served straight from the runtime package |
 
-Outside Cloud Foundry every process runs the retention loop, which is the right
-answer for a single server. On CF only the instance whose `CF_INSTANCE_INDEX`
-matches `Z2UI5_DRAFT_RETENTION_INSTANCE` does — the same hourly `DELETE` run by
-N instances is the same work done N times.
+## Overriding
 
-## Registering app directories in code
+In your project's `package.json`:
 
-The equivalent of `Z2UI5_APP_DIRS`, for when the path is known at startup:
-
-```js
-// srv/server.js
-require("abap2UI5/register-apps")(__dirname + "/my-apps");
+```json
+{
+  "cds": {
+    "cap2ui5": {
+      "apps": "srv/ui",
+      "routes": ["/ui5"]
+    }
+  }
+}
 ```
 
-Both are additive and searched recursively; a file at the top level of a
-directory wins over one in a subfolder. Classes can also be registered
-directly, bypassing the filesystem entirely — that is how the browser
-playground works with no filesystem at all:
+or per profile, the usual CAP way:
 
-```js
-const engine = require("abap2UI5/engine");
-engine.register_app_class(MyApp);              // by constructor name
-engine.register_app_class("my_alias", MyApp);  // under a chosen name
+```json
+{ "cds": { "[production]": { "cap2ui5": { "requires": "MyUi5Role" } } } }
 ```
 
-## The user exit
+## Authentication — and what `null` costs
 
-The user exit is a class implementing `z2ui5_if_exit`. The framework finds it
-by scanning for an implementation — you do not register it anywhere. Its two
-methods are called after the framework defaults, so you receive a fully
-populated config object and change only what you care about.
+The route runs **behind CAP's own middleware chain**, so whatever
+`cds.requires.auth` is configured to has already identified the caller by the
+time the plugin's guard decides. That is not a detail: `cds.context`, and with
+it `cds.context.user`, only exists where CAP's middlewares ran.
 
-This section is the summary; [**The User Exit**](../guide/user-exit) is the
-full treatment — discovery, the request context, and every field.
+The guard is one line: the caller must satisfy `cap2ui5.requires`.
 
-```js
-// srv/app/my_exit.js
-class my_exit {
-  set_config_http_get(s_context, s_config) {
-    s_config.title = "My Application";
-    s_config.theme = "sap_horizon_dark";
-    return s_config;
-  }
+::: warning Setting `requires: null` opens more than the door
+With `null`, every caller is CAP's anonymous user — and the draft store binds
+each session to `cds.context.user.id`. So *all* anonymous visitors share one
+owner and therefore each other's sessions. That is the documented consequence
+of turning authentication off, not a defect, but a public demo and a shared
+staging system are very different things.
+:::
 
-  set_config_http_post(s_context, s_config) {
-    return s_config;
-  }
-}
-module.exports = my_exit;
-```
-
-`z2ui5_if_exit` is a contract, not a base class: an exit is any class carrying
-both methods, and `extends z2ui5_if_exit` throws. Both must be present, even
-when one only hands back what it was given.
+Verified for **every** auth kind, not just the development ones — the chain is
+read in a child process per kind in `cap-abi.test.mjs`:
 
-### What `set_config_http_get` controls
+```
+mocked  ["cds_context","OBJ:[]","basic_auth","OBJ:[]"]
+basic   ["cds_context","OBJ:[]","basic_auth","OBJ:[]"]
+dummy   ["cds_context","OBJ:[]","dummy_auth","OBJ:[]"]
+jwt     ["cds_context","OBJ:[]","jwt_auth","OBJ:[]"]
+xsuaa   ["cds_context","OBJ:[]","jwt_auth","OBJ:[]"]
+ias     ["cds_context","OBJ:[]","ias_auth","OBJ:[]"]
+```
 
-| Field | Default | Notes |
-|---|---|---|
-| `title` | `abap2UI5` | the browser tab title |
-| `theme` | `sap_horizon` | any UI5 theme id |
-| `favicon` | an inline SVG data URI | the tab icon; clear it and the page emits no icon link at all |
-| `src` | `/resources/sap-ui-core.js` | the UI5 bootstrap — the local runtime by default, so the stack works offline |
-| `content_security_policy` | a full `<meta>` tag | see below |
-| `t_security_header` | 7 headers | `[{n, v}]`, applied to the bootstrap response |
-| `t_add_config` | — | extra `data-sap-ui-*` bootstrap attributes, as `[{n, v}]` |
+The auth middleware is a plain function in all six, so the route really does
+run behind it under `xsuaa` and `ias` and not only under `mocked`.
 
-The default security headers are `cache-control: no-cache, no-store,
-must-revalidate`, `Pragma: no-cache`, `Expires: 0`,
-`X-Content-Type-Options: nosniff`, `X-Frame-Options: SAMEORIGIN`,
-`Referrer-Policy: strict-origin-when-cross-origin` and a `Permissions-Policy`
-that allows geolocation/microphone/camera for same-origin only.
+## The runtime
 
-### CSP
+`@abap2ui5/runtime` is resolved from **your project** (`cds.root`), not from
+the plugin's own `node_modules`. The version you install is the version that
+runs; the plugin only declares the range.
 
-The default policy allows `'unsafe-eval'` for one specific reason: the
-OpenUI5 1.71 `ui5loader` evaluates module source as a string, and without it
-the 1.71 bootstrap fails with a CSP `EvalError`. Modern UI5 releases do not
-need it. If you pin a modern UI5, tighten the policy in your exit:
+Pin it in production:
 
-```js
-set_config_http_get(s_context, s_config) {
-  s_config.content_security_policy = s_config.content_security_policy
-    .replace(" 'unsafe-eval'", "");
-  return s_config;
-}
+```json
+{ "dependencies": { "@abap2ui5/runtime": "1.144.0" } }
 ```
 
-The policy also allow-lists the public UI5 CDNs and jsDelivr/cdnjs. If you
-serve everything locally you can strip those hosts too.
+Backend, UI5 shell and wire protocol version come from that one package, which
+is what makes a frontend/backend mismatch impossible. See
+[HTTP Protocol](./protocol).
 
-### `set_config_http_post`
+## What the plugin does not configure
 
-The same idea for the roundtrip. Two fields: `draft_exp_time_in_hours` (default
-`4`) and `check_csrf_active`, the cross-origin POST gate, which is **on by
-default** — turn it off only when something in front of the app already covers
-it:
+Everything the **framework** decides about a response — the UI5 bootstrap URL,
+the Content-Security-Policy, the security headers, the theme, the draft expiry
+and the CSRF gate — is not a `cds.cap2ui5` option. It comes from the user
+exit, registered with `defineExit`:
 
 ```js
-set_config_http_post(s_context, s_config) {
-  s_config.draft_exp_time_in_hours = 24;
-  s_config.check_csrf_active = false;
-  return s_config;
-}
-```
-
-## Identity
-
-Who the framework thinks it is acting for — `sy-uname`, the draft `owner`
-column, and the key that isolates retained sticky app state per session:
+// srv/apps/exit.js
+const { defineExit } = require("cap2ui5");
 
-```js
-// srv/server.js — what the CAP app wires
-engine.set_identity(() => ({
-  user: cds.context?.user?.id,
-  tenant: cds.context?.tenant,
-}));
+defineExit({
+  onPage(cfg, ctx) { cfg.theme = "sap_horizon_dark"; },
+  onRoundtrip(cfg) { cfg.draft_exp_time_in_hours = 24; },
+});
 ```
 
-The provider is called **per use**, not once at wiring time, so it can read a
-request-scoped context and one installed provider serves every concurrent
-request. Without one, identity falls back to the OS account of the server
-process — fine for a single-user demo, wrong for anything with more than one
-user, because every user then shares one identity.
+One per project, and the whole surface is on [The User Exit](../guide/user-exit).
 
-## Draft store
+## Errors
 
-```js
-engine.set_store({
-  load: async (id) => /* → {id, id_prev, data} | null */,
-  save: async (entry) => { /* persist */ },
-});
-```
+An unhandled error in the roundtrip answers `roundtrip failed (<id>)`, where
+`<id>` is `cds.context.id`. The detail — the stack, the SQL, the entity names —
+goes to the server log under the same id. That is deliberate: CDS and driver
+messages carry entity names, SQL fragments and deployment paths, and none of it
+belongs in an HTTP response.
+
+## Next
 
-The CAP app wires this to the `cap2ui5.z2ui5_t_01` table; the other adapters
-use an in-memory Map. Without injection the framework uses a volatile
-in-memory fallback and warns once — correct for tests, wrong for production.
+- [**Deployment**](./deployment) — what changes when this leaves your laptop
+- [**Database Model**](./database) — `cap2ui5.Drafts`
+- [**The User Exit**](../guide/user-exit) — the CSP, the headers, the draft expiry
+- [**Architecture**](./architecture) — how the pieces fit
diff --git a/docs/reference/database.md b/docs/reference/database.md
index 7de1e09..d96e878 100644
--- a/docs/reference/database.md
+++ b/docs/reference/database.md
@@ -1,159 +1,130 @@
 # Database Model
 
-cap2UI5 uses **a single CDS entity** for app persistence: `z2ui5_t_01`. This page describes it and gives hints on cleanup, scaling, and backend choice.
+cap2UI5 adds **one entity** to your model. That is the whole persistence
+footprint.
 
-## Entity definition
-
-`db/schema.cds`:
+## `cap2ui5.Drafts`
 
 ```cds
 namespace cap2ui5;
 
-entity z2ui5_t_01 {
-  key id      : UUID;
-  id_prev     : UUID;          // ← predecessor ID (app history)
-  owner       : String(255);   // ← the user the draft belongs to
-  data        : LargeString;   // ← serialized app instance (JSON)
-  createdAt   : Timestamp @cds.on.insert: $now;
+entity Drafts {
+  key id              : String(36);
+      id_prev         : String(36);
+      id_prev_app     : String(36);
+      id_prev_app_stk : String(36);
+      owner           : String(120) not null;
+      createdAt       : Timestamp;
+      data            : LargeString;
 }
 ```
 
-Every roundtrip performs an `INSERT.into(z2ui5_t_01)` with:
+It arrives through the plugin's `package.json#cds.requires`, so `cds deploy`
+creates it beside your own tables — same database, same connection, same
+transaction, same authorization.
 
-- `id` — newly generated (UUID v4)
-- `id_prev` — the ID the frontend driver passed along as `S_FRONT.ID`
-- `owner` — `cds.context.user.id`, from the identity provider
-- `data` — `JSON.stringify(oApp)` plus `__className` + `__filePath`
-- `createdAt` — set by CAP, and what the retention job prunes on
+| column | |
+|---|---|
+| `id` | the draft's uuid; the frontend carries it and sends it back on the next roundtrip |
+| `id_prev` | the draft this one continues — the chain that makes back-navigation work |
+| `id_prev_app`, `id_prev_app_stk` | the app stack: who called whom, and who gets the screen back |
+| `owner` | who created it. `not null`, and the reason is below |
+| `createdAt` | when, for the retention sweep |
+| `data` | the serialized app instance — the state your fields hold |
 
-`owner` is not bookkeeping. A row holds the complete serialized state of a
-session, so it is bound to its creator in two independent places: the OData
-projection is `@readonly` with `where: 'owner = $user'`, and the draft store
-filters on the owner again when loading. A draft id travels through request
-bodies, logs and browser history — it is not treated as a secret.
+## The owner binding
 
-## Data format in `data`
+A draft is not a small object: it carries the serialized model of a running
+app. So a read answers **only** to the user who created it:
 
-```json
-{
-  "__className": "my_app",
-  "__filePath":  "../../../app/samples/my_app.js",
-  "id_draft":    "",
-  "id_app":      "",
-  "check_initialized": true,
-  "check_sticky":      false,
-  "username":          "Alice",
-  "preferences":       { "language": "de" },
-  "__navStackIds":     ["xyz-789", "abc-123"]
-}
+```js
+if (r.owner !== who()) throw notFound();
 ```
 
-`__className` and `__filePath` are used for the reload. `__navStackIds` contains the IDs of the stacked apps (see [Persistence](../guide/persistence)).
+and the refusal is the *same* `NO_DRAFT_ENTRY_OF_PREVIOUS_REQUEST_FOUND` a
+missing draft produces — deliberately, so a caller cannot tell a foreign draft
+from an absent one. A shared bookmark degrades to a fresh app start rather than
+to somebody else's session.
+
+::: danger Why the column is `not null`, and why the comparison is `!==`
+An earlier version wrote `if (r.owner && r.owner !== who())`. That is the same
+check with a hole in it: a row whose `owner` was `NULL` or `""` passed it, so it
+belonged to **everybody** rather than to nobody. A security review found it and
+a proof of concept confirmed it — one user replayed another's draft id against
+a blanked row and was handed her running app.
+
+An authorization check compares presence, never truthiness. `&&` in front of a
+comparison in an access decision turns a missing value into a wildcard. The
+column is `not null` now, the comparison is `!==`, the `UPDATE` carries `owner`
+in its `WHERE`, and the test for it discriminates — red on the old condition,
+green on the new.
+:::
 
-The engine is **cycle-safe** — a built-in `WeakSet` tracker prevents accidental circular references from breaking stringify.
+## What is NOT reachable
 
-## Database backends
+`cap2ui5.Drafts` is in your model, which is what lets `cds deploy` create it —
+but a CAP service exposes only what it *projects*. Unless you write a
+projection over it (do not), it is not reachable through any OData service.
 
-CAP supports several persistence backends. All work with cap2UI5:
+Measured rather than assumed, because session state reachable through somebody's
+OData service would be the worst kind of surprise: in `coexistence.test.mjs`,
+`/odata/v4/catalog/Drafts` answers **404** and the service metadata names no
+draft entity.
 
-| Backend | Driver | When |
-|---|---|---|
-| SQLite (in-memory) | `@cap-js/sqlite` | Dev default (`npx cds w`) |
-| SQLite (file) | `@cap-js/sqlite` | Local testing with persistence |
-| HANA / HANA Cloud | `@cap-js/hana` | Production on BTP |
-| PostgreSQL | `@cap-js/postgres` | Self-hosted Cloud Foundry / Kubernetes |
+## Retention
 
-In `package.json`:
+`cleanup()` runs once per roundtrip and deletes drafts older than
+`draft_exp_time_in_hours` — four hours unless your
+[user exit](../guide/user-exit#onroundtrip) says otherwise:
 
-```json
-{
-  "cds": {
-    "requires": {
-      "db": { "kind": "sqlite", "credentials": { "url": ":memory:" } }
-    }
-  }
-}
+```sql
+DELETE FROM cap2ui5_Drafts WHERE createdAt < <now - draft_exp_time_in_hours>
 ```
 
-Switching to HANA in production goes via the `@sap/cds` `profile` mechanism, no code changes.
+It asks the exit the same way the framework's own store does, so raising the
+expiry keeps the rows as long as the framework will resume them. Hard-coding
+the sweep at four hours made the two disagree: a 20-hour-old draft the
+framework was willing to restore had already been deleted.
 
-## Indexes & performance
+It never raises — a failed sweep must not fail a roundtrip. It is not scoped by
+owner, because it is a retention policy rather than an access decision; in a
+multitenant CAP app it is scoped by the tenant like every other `cds.run`.
 
-The default schema generation has **only the primary key** on `id`. For production loads I recommend:
+::: warning SQLite: give it a busy timeout
+Every roundtrip writes a draft, so a cap2UI5 app writes to the database far
+more often than a typical OData service. On a **file-backed SQLite** with more
+than one process — a second worker, a test suite, a second `cds watch` —
+`@cap-js/sqlite` 3 (which uses node's built-in `node:sqlite`) fails the write
+immediately with *database is locked*, because its busy timeout defaults to
+zero. WAL is on, so readers are fine; writers are the ones that collide.
 
-- **Index on `id_prev`** if you ever want to traverse (undo, audit). Not needed otherwise.
-- With many parallel users: the `INSERT` is called often enough that HANA with indexes enabled becomes noticeable — keep your indexes minimal.
-
-The schema already carries `createdAt` (that is what retention prunes on) and
-`owner`. If you want CAP's full audit set, swap in the `managed` aspect:
-
-```cds
-entity z2ui5_t_01 : managed {  // ← adds createdAt/createdBy/modifiedAt/modifiedBy
-  key id      : UUID;
-  id_prev     : UUID;
-  owner       : String(255);
-  data        : LargeString;
-}
+```json
+{ "cds": { "requires": { "db": {
+  "kind": "sqlite",
+  "credentials": { "url": "db.sqlite" },
+  "client": { "timeout": 5000 }
+} } } }
 ```
 
-The `managed` aspect requires no code patch in cap2UI5 — the engine ignores the additional fields during deserialization since it only reads `data`.
-
-## Cleanup strategy
-
-::: warning Table grows linearly
-**Each roundtrip = one new row.** A 50-click session = 50 rows. 1,000 users with 50 clicks each = 50,000 rows per day.
+`client` goes straight to the driver. Measured in this project's own example:
+five of six suite runs failed without it, six of six passed with it. On HANA
+or Postgres the question does not arise.
 :::
 
-### Option 1: the retention job that already ships
+## Your own tables
 
-You do not have to write this one — it ships inside the framework package
-(`core/srv/cap/retention.js`) and is started by its `cds-plugin`, so it is
-running in any project that installs cap2UI5, not only in this repository. It
-deletes rows past their TTL once at startup and hourly after that, on an
-`unref`'d timer so it never holds the process open.
+Untouched. The apps read and write them through `cds.ql` exactly like a
+handler, and a plain OData service beside the apps sees the same rows:
 
-Configure it with one environment variable:
-
-| Variable | Default | Meaning |
-|---|---|---|
-| `Z2UI5_DRAFT_TTL_HOURS` | the framework's own `draft_exp_time_in_hours` (`4`) | how long a draft row is kept; `0` disables cleanup entirely |
-| `Z2UI5_DRAFT_RETENTION_INSTANCE` | `0` | which Cloud Foundry instance runs the cleanup loop; `*` lets every instance run it |
-
-```bash
-Z2UI5_DRAFT_TTL_HOURS=2 npx cds watch     # shorter retention
-Z2UI5_DRAFT_TTL_HOURS=0 npx cds watch     # keep everything (debugging)
-```
-
-Anything unparseable falls back to the framework's own TTL rather than
-disabling cleanup —
-a typo in the variable must not silently turn retention off.
-
-### Option 2: DB-side job
-
-Strongly recommended in production: a nightly cron on the DB deletes older rows.
-
-```sql
--- HANA procedure (simplified)
-DELETE FROM "MY_DOMAIN_Z2UI5_T_01"
-WHERE "CREATEDAT" < ADD_DAYS(CURRENT_TIMESTAMP, -1);
+```js
+const { Books } = cds.entities("my.bookshop");
+this.books = await SELECT.from(Books).where`title like ${"%" + this.search + "%"}`;
 ```
 
-### Option 3: limit per user
-
-If you have a user ID (via `cds.context.user.id`), you can enforce a user-specific LIMIT in the handler — delete the oldest rows per user.
-
-This requires extending the schema with `user_id` and patching `z2ui5_cl_ui5_srv_draft.saveApp` — currently not built in.
-
-## Important caveats
-
-- **Rows are immutable.** Never `UPDATE` an existing row — the engine assumes that every ID identifies **a specific app instance**.
-- **`id_prev` is NOT unique.** If a user tries two different "next steps" via browser back, there are two rows with the same `id_prev`. That is intentional — it's a forking history.
-- **No foreign-key constraint.** `id_prev` points to `id`, but CAP won't enforce that if you leave the schema unchanged. Cleanup jobs can orphan arbitrary sub-trees.
-
-## Scaling to multi-tenant
-
-cap2UI5 is **multi-tenant capable** out of the box, because CAP is. With `@sap/cds-mtxs` each tenant DB runs separately — no code patch needed.
+Both directions are tested: a row the app writes is there for the OData client
+at once, and a row POSTed through OData is found by the app's next search.
 
-Per tenant you then see your own `z2ui5_t_01` table. Cleanup strategies run per tenant.
+## Next
 
-→ Continue with [Deployment](./deployment).
+- [**Persistence & Sessions**](../guide/persistence) — what this means while writing an app
+- [**Configuration**](./configuration) — the auth default the owner binding depends on
diff --git a/docs/reference/deployment.md b/docs/reference/deployment.md
index 18c3833..9961170 100644
--- a/docs/reference/deployment.md
+++ b/docs/reference/deployment.md
@@ -1,229 +1,96 @@
 # Deployment
 
-cap2UI5 apps deploy like any other CAP project — with a few caveats around the frontend bundle. This page shows the standard Cloud Foundry path.
+A cap2UI5 project deploys like **any other CAP project**, because it is one.
+The plugin adds a dependency, an entity and a route — nothing that needs its own
+module, its own build step or its own pipeline.
+
+::: warning What is verified here, and what is not
+Everything on this page about the *plugin's* behaviour is measured: the entity,
+the route, the shell, and the authentication chain under `xsuaa` and `ias`. The
+Cloud Foundry topology below is the standard CAP one and has **not** been
+exercised end to end for this plugin. Treat it as the shape to expect rather
+than as a tested recipe, and tell us if it bites.
+:::
 
 ## Locally
 
 ```bash
-npx cds w
-# or
-npm start
+npx cds watch
 ```
 
-The default is in-memory SQLite. That fits dev — all app instances vanish on restart.
-
-If you want **persistent local**:
+In-memory SQLite by default, so every session vanishes on restart — which is
+usually what you want while developing. For persistence across restarts:
 
 ```json
-"cds": {
-  "requires": {
-    "db": { "kind": "sqlite", "credentials": { "url": "db.sqlite" } }
-  }
-}
-```
-
-Run `cds deploy` once, done.
-
-## Cloud Foundry (BTP)
-
-The reference project contains an `mta.yaml` with all standard modules:
-
-```yaml
-modules:
-- name: abap2UI5-srv               # CAP service
-- name: abap2UI5-db-deployer       # HDI container (the draft table)
-- name: abap2UI5                   # HTML5 module with the frontend
-- name: abap2UI5-app-deployer      # HTML5 repo push
-- name: abap2UI5-destinations      # FLP destinations
-
-resources:
-- name: abap2UI5-destination       # destination service
-- name: abap2UI5-html5-repo-host   # HTML5 repo
-- name: abap2UI5-auth              # XSUAA
-```
-
-Build & deploy:
-
-```bash
-npm run build       # → mbt build, produces mta_archives/archive.mtar
-npm run deploy      # → cf deploy mta_archives/archive.mtar
-```
-
-### What the production build has to do
-
-`mbt build` runs the project's `before-all`, which is `npm ci` followed by
-`npm run build:production` — **not** a bare `cds build --production`. The CDS
-build stages the server module into `gen/srv` and copies the app's dependency
-on the vendored framework (`"abap2UI5": "file:./core"`) along with it, but not
-the folder that specifier points at. `scripts/vendor-core.js` is the second
-half: it puts the vendored core into `gen/srv/core`, so the pushed module can
-resolve `abap2UI5/engine`. Skip it and the archive still builds, `cf deploy`
-still succeeds, and the instance crash-loops on
-`Cannot find module 'abap2UI5/engine'`.
-
-`openui5-dist` is not pushed either. It is the UI5 runtime `cds watch` serves
-at `/resources` locally; on BTP the approuter routes `/resources` to the `ui5`
-destination, so the CAP module never serves it — and the package is a
-deprecated 611 MB tree of release tooling that carried 43 advisories, 3 of
-them critical. The framework declares it as an *optional peer* dependency and
-cap2UI5 carries it as a devDependency, so `npm ci --omit=dev` in the staged
-module leaves it out: 19 MB, no advisories. (The vendor step also prunes it
-defensively, for a framework version that still declares it.)
-
-If you build your own CAP project around the core package rather than
-deploying this one, the same rule applies to any `file:` dependency you vendor:
-`cds build` will not stage it for you. The alternative CAP supports is npm
-workspaces plus `cds build --ws-pack`, which packs the workspace dependency
-into a tarball and rewrites the specifier.
-
-Prerequisites:
-
-- **Multi-Target Build Tool**: `npm i -g mbt`
-- **CF CLI** with MTA plugin: `cf install-plugin multiapps`
-- BTP subaccount with permissions for destination + HTML5 apps + XSUAA
-
-After deploy, the app is reachable via the FLP URL (standard pattern: `https://<subdomain>.launchpad.cfapps.<region>.hana.ondemand.com`).
-
-## Kyma / Kubernetes
-
-CAP supports direct Kyma deployment since `@sap/cds ^7`. Setup:
-
-1. CAP-typical container build (multi-stage Dockerfile)
-2. HANA Cloud connection via `cds.requires.db.kind = "hana"`
-3. XSUAA service binding via the Kyma operator pattern
-
-The `app/z2ui5/` frontend files can either:
-
-- **Be served as static assets** in the same container (Express static)
-- **Be hosted by a separate Nginx pod** with a reverse proxy to the CAP service
-
-In the simplest case: `srv/server.js` lets CAP serve the `app/` directory statically. The `GET /rest/root/z2ui5` returns the bootstrap HTML, which references relative UI5 paths (CDN or local bundle).
-
-## Self-hosted Express
-
-If you want to live without BTP plumbing entirely:
-
-```bash
-node srv/server.js
+{ "cds": { "requires": { "db": { "kind": "sqlite", "credentials": { "url": "db.sqlite" } } } } }
 ```
 
-This runs CAP as a normal Node.js server on port 4004. Behind an Nginx or directly — either works.
-
-You then need:
+then `cds deploy` once. `cap2ui5.Drafts` is created along with your own tables.
 
-- Host the DB yourself (Postgres / SQLite file / HANA Express)
-- Implement auth yourself (`cds.requires.auth.kind = "mocked"` for local, something else for prod)
-- Serve frontend assets (Express static on `app/`)
+## What changes in production, and what does not
 
-## Frontend update
+| | |
+|---|---|
+| **The shell** | served by your CAP server from `node_modules/@abap2ui5/runtime/webapp`. There is no separate frontend project to build, no HTML5 module to push, no UI5 tooling in the pipeline |
+| **The entity** | `cap2ui5.Drafts` deploys through your normal `db` module, HDI container included. Nothing special |
+| **Authentication** | whatever `cds.requires.auth` is — the route runs behind CAP's own chain. Verified for `jwt`, `xsuaa` and `ias`, not only for the development kinds |
+| **Scaling** | app state is in the database, not in memory, so a second instance is a second instance. No sticky sessions, no shared cache |
+| **The runtime** | `@abap2ui5/runtime` is an ordinary dependency. **Pin it.** |
 
-The `app/z2ui5/webapp` directory is **not maintained by hand** — it's a 1:1 mirror of abap2UI5's `app/webapp`, refreshed by the sync pipeline in [builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js):
+## Pin the runtime
 
-```bash
-# in a builder-abap2UI5-js checkout
-npm run mirror_app        # snapshot the abap2UI5 webapp into the input mirror
-npm run prepare_app       # webapp + patches → prepared output
-npm run build_core        # assemble + publish → core/app/z2ui5/webapp
+```json
+{ "dependencies": { "@abap2ui5/runtime": "1.144.0", "cap2ui5": "^0.1.0" } }
 ```
 
-Only two values are patched in (`scripts/patch-frontend.js`): the UI5 bootstrap URL in `index.html` and the `/rest/root/z2ui5` data source in `manifest.json`. Everything else stays identical to upstream.
+Backend, UI5 shell and wire version come from that one package. Pinning it is
+what stops a redeploy from silently pairing your app with a different framework.
 
-In CI the `update_frontend` workflow (mirror → prepare → build core) runs nightly and can be dispatched manually; [builder-cap2UI5](https://github.com/cap2UI5/builder-cap2UI5)'s `update_cap` workflow then rebuilds the CAP app and publishes it 1:1 into the [cap2UI5 repo](https://github.com/cap2UI5/cap2UI5). A jest suite gates the sync commit — only a green build is pushed. See [Where cap2UI5 comes from](../guide/where-it-comes-from#how-the-port-actually-works) for the full picture.
-
-## Sticky session recommendation
+## Cloud Foundry (BTP)
 
-If your apps have file uploads, wizards with tight roundtrips, or similar, the frontend driver wants to serialize roundtrips. On Cloud Foundry that goes via:
+The usual CAP modules, with one fewer than a hand-built UI5 app needs:
 
 ```yaml
-# mta.yaml — abap2UI5-srv
-parameters:
-  routes:
-    - route: my-app.cfapps.eu10.hana.ondemand.com
-      route_service_url: https://stickysession.cfapps.eu10.hana.ondemand.com
-```
+modules:
+  - name: my-srv                 # the CAP service — serves the apps AND the shell
+  - name: my-db-deployer         # HDI container, incl. cap2ui5.Drafts
+  - name: my-approuter           # if you want one in front
 
-Or via a Cloud Foundry sticky cookie: the default XSUAA login setup already sets `JSESSIONID`, which is enough for sticky routing.
+resources:
+  - name: my-uaa                 # xsuaa
+  - name: my-hdi                 # HANA
+```
 
-## Auth & XSUAA
+There is **no HTML5 module for the frontend** and no app-repo push, because the
+shell is a static directory inside a dependency of the service.
 
-The reference project is authenticated by default — XSUAA in production,
-mocked users in development:
+If an approuter sits in front, route the two POST paths and the shell to the
+CAP service:
 
 ```json
 {
-  "cds": {
-    "requires": {
-      "auth": {
-        "[production]": "xsuaa",
-        "[development]": { "kind": "mocked", "users": { "alice": { "password": "alice" } } }
-      }
-    }
-  }
+  "routes": [
+    { "source": "^/sap/bc/z2ui5.*",  "destination": "srv-api", "authenticationType": "xsuaa" },
+    { "source": "^/rest/root/z2ui5.*", "destination": "srv-api", "authenticationType": "xsuaa" },
+    { "source": "^/z2ui5/webapp/.*", "destination": "srv-api", "authenticationType": "xsuaa" }
+  ]
 }
 ```
 
-Both services carry the requirement, so the roundtrip and the OData entities
-are unreachable without a token:
+Adjust the paths if you changed `cds.cap2ui5.routes` or `webapp`.
 
-```cds
-@(requires: 'authenticated-user')
-service rootService { ... }        // POST /rest/root/z2ui5
-@(requires: 'authenticated-user')
-service AdminService { ... }       // the draft table, Northwind
-```
+## Scale-to-zero and restarts
 
-`GET`/`HEAD /rest/root/z2ui5` stay public on purpose: they serve the static
-UI5 bootstrap shell and the CSRF ack, carry no user data, and keeping them
-open preserves the offline/dev flow. In BTP the approuter authenticates
-before the frontend can reach them at all.
+Both are fine, and tested rather than argued: a process can be **SIGKILLed
+mid-session** and a fresh one continues it, navigation stack included. See
+[Persistence & Sessions](../guide/persistence).
 
-### Separating users
-
-Authentication alone does not separate users — that is what the identity port
-is for. `srv/server.js` injects CAP's request user into the framework:
-
-```js
-engine.set_identity(() => ({
-  user: cds.context?.user?.id,
-  tenant: cds.context?.tenant,
-}));
-```
+## Health
 
-That one injection drives all three separation mechanisms: `sy-uname` inside
-apps, the `owner` column each draft row is stamped with and filtered by, and
-the per-session keying of retained sticky app state. Without it every user
-shares one identity and, with it, one another's drafts.
-
-::: warning Before going productive
-Two things the reference project leaves at demo level: the services require
-`authenticated-user` rather than the `User` scope declared in
-`xs-security.json` (so every subaccount user passes, role assigned or not),
-and the framework's CSRF gate is opt-in through the user exit and off by
-default.
-:::
-
-## CI/CD
-
-For GitHub Actions a sample workflow:
-
-```yaml
-# .github/workflows/deploy.yml
-name: Deploy
-on: { push: { branches: [main] } }
-jobs:
-  build:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: '22' }
-      - run: npm ci
-      - run: npm run build
-      - run: cf api $CF_API && cf auth $CF_USER $CF_PASSWORD
-      - run: cf target -o $CF_ORG -s $CF_SPACE
-      - run: npm run deploy
-```
+The roundtrip route requires an authenticated user by default, so it is a poor
+health probe. Use CAP's own (`/health`) or a service of yours.
 
-The secrets (CF_USER, CF_PASSWORD, …) come from the GitHub repo settings.
+## Next
 
-→ You're now through the entire reference set. Back to the [**examples**](../examples/hello-world) or to the [**API reference**](../api/client).
+- [**Configuration**](./configuration) — routes, authentication, the runtime
+- [**Database Model**](./database) — what lands in the HDI container
diff --git a/docs/reference/protocol.md b/docs/reference/protocol.md
index 2b1a054..a934211 100644
--- a/docs/reference/protocol.md
+++ b/docs/reference/protocol.md
@@ -1,217 +1,111 @@
 # HTTP Protocol
 
-::: danger This page documents a protocol upstream has moved off
-Verified 2026-09-18 by diffing live responses from upstream's own Node runtime
-against cap2UI5 (`scripts/conformance.js` in
-[builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js), ADR-006).
-
-The response shape below — `S_FRONT.PARAMS.S_VIEW.XML` and friends — is what
-**cap2UI5 emits today**, so it is accurate for debugging this backend. It is
-**no longer what abap2UI5 emits**. Upstream delivers frontend instructions as an
-ordered action table:
-
-```json
-"S_FRONT": { "S_ACTION": { "T_SYSTEM": [["VIEW_SLOTS","display","MAIN","<mvc:View …>"]] } }
-```
-
-and it has flattened two-way bindings out of `MODEL.XX` (`{/NAME}`, not
-`{/XX/NAME}`). The bundled frontend is mirrored 1:1 from upstream and therefore
-reads `S_ACTION`.
-
-So the claim this page opened with — that the wire format is *identical* to
-abap2UI5 — is currently false, and the mismatch is tracked as a P0. Treat this
-page as "the protocol cap2UI5 speaks", not "the protocol abap2UI5 speaks", until
-ADR-006's worklist items 1–2 are closed.
+One endpoint, one POST per interaction, JSON both ways. The protocol is
+**abap2UI5's own** — cap2UI5 does not define it, translate it or version it
+independently, because the backend answering it *is* abap2UI5.
+
+::: tip This page used to carry a warning. It no longer needs to.
+It used to say that the page described what cap2UI5 emitted and not what
+abap2UI5 emitted — the two had drifted apart, and a hand-maintained port was
+still writing a superseded envelope. That cannot happen now: the backend and
+the shell come from one upstream commit. The measurements below are from a
+running server rather than from a specification.
 :::
 
-The wire format between the frontend and the cap2UI5 backend was designed to be
-identical to abap2UI5. This page documents it for reference — you don't need to know it as an app developer, but it's helpful when debugging or when swapping out the frontend.
+## The endpoint
 
-## Endpoints
+| | |
+|---|---|
+| `POST /rest/root/z2ui5` | a roundtrip |
+| `POST /sap/bc/z2ui5` | the same door, under its ABAP-side name |
+| `GET  /rest/root/z2ui5?app_start=<APP>` | the composed HTML page that boots UI5 and starts an app |
+| `GET  /z2ui5/webapp/**` | the shell's assets, straight from the runtime package |
 
-| Method | Path | Effect |
-|---|---|---|
-| `GET`  | `/rest/root/z2ui5` | Bootstrap HTML (loads UI5 + Component) |
-| `HEAD` | `/rest/root/z2ui5` | CSRF token prefetch (`X-CSRF-Token: disabled`) |
-| `POST` | `/rest/root/z2ui5` | Roundtrip — JSON body see below |
+Both POST paths are configurable — see [Configuration](./configuration).
 
-Mounts:
-
-- `GET`/`HEAD` are registered in `srv/server.js` via `cds.on("bootstrap", ...)`.
-- `POST` is automatically exposed by CAP because `z2ui5-service.cds` declares the action `z2ui5(value: object)`.
-
-## Request body
-
-The frontend driver always sends `Content-Type: application/json`. Body structure:
+## Request
 
 ```json
 {
   "value": {
     "S_FRONT": {
-      "ID":            "<UUID of the predecessor app instance, or empty>",
-      "APP":           "<class name of the currently loaded app>",
-      "EVENT":         "<event name or empty string>",
-      "T_EVENT_ARG":   ["arg1", "arg2", ...],
-      "R_EVENT_DATA":  { /* optional object payload */ },
-      "ORIGIN":        "https://my-host.cf.eu10.hana.ondemand.com",
-      "PATHNAME":      "/rest/root/z2ui5",
-      "SEARCH":        "?app_start=...",
-      "HASH":          "",
-      "CONFIG":        { /* ComponentData */ }
+      "ID": "<the draft id of the previous roundtrip, empty on a start>",
+      "APP": "ZCL_JS_HELLO",
+      "EVENT": "GO",
+      "T_EVENT_ARG": ["red"],
+      "SEARCH": "?app_start=ZCL_JS_HELLO",
+      "PATHNAME": "/rest/root/z2ui5",
+      "ORIGIN": "http://localhost:4004",
+      "HASH": "",
+      "CONFIG": {}
     },
-    "XX":    { /* two-way bindings: user edits */ },
-    "MODEL": { /* current model state on the frontend */ }
+    "XX": {},
+    "MODEL": { "NAME": "Ada" }
   }
 }
 ```
 
-CDS requires, through the action signature `z2ui5(value: object)`, that the actual oBody be wrapped as `value`. The `z2ui5_cl_ui5_http_handler` unwraps it again.
-
-### `S_FRONT` fields
-
-| Field | Type | Description |
-|---|---|---|
-| `ID` | `string` | UUID of the most recently persisted app instance; empty on the first roundtrip |
-| `APP` | `string` | Class name of the current app (informational) |
-| `EVENT` | `string` | Event name from `_event(...)`. Empty on init call. |
-| `T_EVENT_ARG` | `string[]` | Event arguments from `_event(name, args)` |
-| `R_EVENT_DATA` | `any` | Optional object payload from `_event(name, args, ctrl, data)` |
-| `ORIGIN` / `PATHNAME` / `SEARCH` / `HASH` | `string` | Browser `location` |
-| `CONFIG.ComponentData.startupParameters` | `object` | FLP startup parameters |
+| | |
+|---|---|
+| `ID` | which draft to continue. Empty starts a new app |
+| `EVENT`, `T_EVENT_ARG` | what the user did, and the arguments the control carried — `c.eventName` and `c.eventArg(i)` |
+| `MODEL` | the bound data as the browser has it; applied to the app instance before `main` runs |
 
-### `XX` (two-way delta)
+## Response
 
-Plain JSON object with the fields the user edited. Example:
-
-```json
-"XX": {
-  "username": "Alice",
-  "preferences": { "language": "de" },
-  "is_active": true
-}
-```
-
-The engine applies it to the deserialized app via `main_json_to_attri`.
-
-## Response body
+Measured against the example, a start of `ZCL_JS_HELLO`:
 
 ```json
 {
   "S_FRONT": {
-    "APP":   "<class name>",
-    "ID":    "<new UUID>",
-    "PARAMS": {
-      "S_MSG_TOAST":         { "TEXT": "...", "AUTOCLOSE": "X", ... } | null,
-      "S_MSG_BOX":           { "TEXT": "...", "TYPE": "warning", ... } | null,
-      "S_VIEW":              { "XML": "<mvc:View>..." } | null,
-      "S_VIEW_NEST":         { "XML": "...", "ID": "...", "METHOD_INSERT": "..." } | null,
-      "S_VIEW_NEST2":        { ... } | null,
-      "S_POPUP":             { "XML": "..." } | null,
-      "S_POPOVER":           { "XML": "...", "OPEN_BY_ID": "..." } | null,
-      "S_FOLLOW_UP_ACTION":  { "CUSTOM_JS": [".eF('OPEN_NEW_TAB','...')", ...] } | null,
-      "SET_PUSH_STATE":      <any> | null,
-      "SET_APP_STATE_ACTIVE":"X" | null,
-      "SET_NAV_BACK":        "X" | null,
-      "S_STATEFUL":          { "ACTIVE": true } | null
-    }
+    "APP": "ZCL_JS_HELLO",
+    "ID": "D46139087B1241DBBD701D4DC02F13AA",
+    "PROTOCOL": 2,
+    "S_ACTION": { "T_SYSTEM": [["VIEW_SLOTS", "display", "<mvc:View …>"]] }
   },
-  "MODEL": {
-    /* one-way bindings on top level */
-    "users": [...],
-    "title": "...",
-    "XX": {
-      /* two-way bindings */
-      "username": "...",
-      ...
-    }
-  }
+  "MODEL": { "NAME": "" }
 }
 ```
 
-### `MODEL` structure
+| | |
+|---|---|
+| `ID` | the **new** draft id — every roundtrip writes a new one and the browser carries it forward |
+| `PROTOCOL` | the wire version, see below |
+| `S_ACTION.T_SYSTEM` | ordered framework actions: render a view, open a popup, show a message box, navigate |
+| `S_ACTION.T_CUSTOM` | app-issued frontend actions |
+| `MODEL` | the bound data as the server has it after `main` |
 
-The engine builds `MODEL` from the `aBind` array:
+`S_ACTION` is an **ordered list**, which is why two `c.messageToast()` calls
+arrive in the order you wrote them.
 
-```js
-client.aBind = [
-  { name: "users",    val: [...], type: "one_way" },
-  { name: "username", val: "...", type: "two_way" },
-  ...
-];
-```
+## `PROTOCOL` — the wire carries its own version
 
-One-way entries land directly under `MODEL`; two-way entries under `MODEL.XX`. The frontend JSONModel is set as the default model on the view, from which the bindings (`{/...}` and `{/XX/...}`) resolve.
+`S_FRONT.PROTOCOL` is stamped from `z2ui5_if_ui5_types=>c_protocol` and the
+shell compares it against its own before reading anything else. It is **not**
+the product version and does not move with a release; it moves when a response
+can no longer be read by a frontend written for the previous number.
 
-## Sample roundtrip
+It exists because of exactly the failure this project hit: the `S_ACTION`
+envelope replaced an older `S_FRONT.PARAMS` shape, and a frontend written for
+the old one looked for a key the backend no longer wrote — then rendered its
+empty result, silently. A mismatch is now reported to the user.
 
-### Initial roundtrip (init)
+A response *without* the field is let through: a backend older than the field
+cannot be told apart from one that is merely older.
 
-**Request:**
-```json
-{ "value": {
-  "S_FRONT": { "ID": "", "EVENT": "", "ORIGIN": "...", "PATHNAME": "/rest/root/z2ui5", "SEARCH": "?app_start=z2ui5_cl_ui5_app_hi_world" },
-  "XX": {},
-  "MODEL": {}
-}}
-```
+For a cap2UI5 project the check is belt and braces — both halves come from one
+`@abap2ui5/runtime` — but it protects anyone pairing them by hand.
 
-**Response:**
-```json
-{
-  "S_FRONT": {
-    "APP": "z2ui5_cl_ui5_app_hi_world",
-    "ID": "abc-123",
-    "PARAMS": {
-      "S_VIEW": { "XML": "<mvc:View>...<Input value=\"{/XX/NAME}\"/>...</mvc:View>" }
-    }
-  },
-  "MODEL": { "XX": { "NAME": "" } }
-}
-```
+## Errors
 
-### Button-click roundtrip
+An unhandled error answers `500` with `roundtrip failed (<cds.context.id>)`.
+The detail goes to the server log under the same id; see
+[Configuration](./configuration).
 
-**Request:**
-```json
-{ "value": {
-  "S_FRONT": { "ID": "abc-123", "EVENT": "BUTTON_POST", "T_EVENT_ARG": [] },
-  "XX": { "NAME": "Alice" },
-  "MODEL": {}
-}}
-```
-
-**Response:**
-```json
-{
-  "S_FRONT": {
-    "APP": "z2ui5_cl_ui5_app_hi_world",
-    "ID": "def-456",
-    "PARAMS": {
-      "S_MSG_BOX": { "TEXT": "Your name is Alice", "TYPE": "information" }
-    }
-  },
-  "MODEL": { "XX": { "NAME": "Alice" } }
-}
-```
-
-## Frontend action strings (`eB`/`eF`)
-
-Action strings travel from the server to the frontend driver in the UI5 binding slot (`press="..."`):
-
-- **`eB(...)`** = "event Backend" → triggers a roundtrip
-- **`eF(...)`** = "event Frontend" → runs only in the frontend
-
-Format:
-
-```
-.eB([['EVENT_NAME', '', '', '']], 'arg1', 'arg2')
-                  ↑    ↑    ↑   ↑
-                  |    |    |   force_main_model (truthy)
-                  |    |    bypass_busy (truthy)
-                  |    reserved
-                  event name
-```
+Authentication is decided **before** the body is read: an unauthenticated
+caller gets `401` without the server buffering the payload.
 
-`_event(name, args, ctrl)` builds this automatically — you only need the internals if you extend the frontend yourself.
+## Next
 
-→ Continue with the [Database Model](./database).
+- [**Architecture**](./architecture) — what sits behind the endpoint
+- [**Configuration**](./configuration) — routes and authentication
diff --git a/package-lock.json b/package-lock.json
index 8fa71bf..3cff6b9 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -7,8 +7,12 @@
     "": {
       "name": "cap2ui5-docs",
       "version": "0.1.0",
+      "license": "MIT",
       "devDependencies": {
         "vitepress": "^1.6.3"
+      },
+      "engines": {
+        "node": ">=22"
       }
     },
     "node_modules/@algolia/abtesting": {
diff --git a/package.json b/package.json
index b76a3e4..1840009 100644
--- a/package.json
+++ b/package.json
@@ -22,8 +22,7 @@
     "docs:preview": "vitepress preview docs",
     "verify": "node scripts/verify-refs.mjs",
     "check": "npm run verify && npm run docs:build",
-    "check:ci": "node scripts/verify-refs.mjs --require-checkout && node scripts/gen-samples.mjs --check && npm run docs:build",
-    "gen:samples": "node scripts/gen-samples.mjs"
+    "check:ci": "node scripts/verify-refs.mjs --require-checkout && npm run docs:build"
   },
   "devDependencies": {
     "vitepress": "^1.6.3"
diff --git a/scripts/gen-samples.mjs b/scripts/gen-samples.mjs
deleted file mode 100644
index e274702..0000000
--- a/scripts/gen-samples.mjs
+++ /dev/null
@@ -1,222 +0,0 @@
-#!/usr/bin/env node
-/**
- * gen-samples — generate docs/guide/samples.md from the shipped sample gallery.
- *
- * WHY THIS EXISTS
- * ---------------
- * cap2UI5 ships over a hundred sample apps, and until this page existed the
- * only way into them was to already know a class name and hand-type it into
- * `?app_start=`. A hand-written index would have been a second copy of a list
- * that changes on every sync — stale within a week, and invisible to
- * verify-refs until a class actually disappeared.
- *
- * So the page is generated from the gallery itself. `z2ui5_cl_smp_app_000` is
- * the sample browser that ships with the framework; its `get_catalog()` holds
- * one `{ group, header, sub, keywords, path, app }` entry per sample. That
- * table is the same source the in-app gallery renders from, which makes it the
- * only list that cannot disagree with what the playground actually offers.
- *
- * Usage:
- *   CAP2UI5_DIR=/path/to/cap2UI5 node scripts/gen-samples.mjs
- *   node scripts/gen-samples.mjs           # defaults to ../cap2UI5
- *   node scripts/gen-samples.mjs --check   # fail if the page is out of date
- *
- * The result is committed like any other page: the docs must build without a
- * cap2UI5 checkout, and a reviewer should see the diff a sync causes.
- */
-import fs from "node:fs";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
-
-const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
-const APP = path.resolve(process.env.CAP2UI5_DIR || path.join(ROOT, "..", "cap2UI5"));
-const SAMPLES = path.join(APP, "core", "srv", "app", "samples");
-const GALLERY = "z2ui5_cl_smp_app_000";
-const OUT = path.join(ROOT, "docs", "guide", "samples.md");
-const CHECK = process.argv.includes("--check");
-
-const PLAYGROUND = "https://cap2ui5.github.io/web-cap2UI5-build/";
-const SOURCE = "https://github.com/cap2UI5/cap2UI5/blob/main/core/srv/app/samples";
-
-if (!fs.existsSync(path.join(SAMPLES, `${GALLERY}.js`))) {
-  console.error(`gen-samples: no sample gallery at ${SAMPLES}/${GALLERY}.js`);
-  console.error(`             set CAP2UI5_DIR or clone cap2UI5/cap2UI5 next to this repo.`);
-  process.exit(1);
-}
-
-// The catalogue is one long array literal of object literals, all fields in a
-// fixed order because the file is machine-generated by the transpiler. Parsing
-// it with a regex is fine for exactly that reason — and if the shape ever
-// changes, the count check below turns the surprise into a failure.
-const ENTRY_RE =
-  /\{ group: `([^`]*)`, header: `([^`]*)`, sub: `([^`]*)`, keywords: `([^`]*)`, path: `([^`]*)`, app: `([^`]*)` \}/g;
-
-const src = fs.readFileSync(path.join(SAMPLES, `${GALLERY}.js`), "utf8");
-const entries = [...src.matchAll(ENTRY_RE)].map((m) => ({
-  group: m[1],
-  header: m[2],
-  sub: m[3],
-  keywords: m[4],
-  app: m[6],
-}));
-
-if (entries.length < 50) {
-  console.error(`gen-samples: only ${entries.length} catalogue entries parsed from ${GALLERY}.js`);
-  console.error(`             the gallery table's shape probably changed — fix ENTRY_RE.`);
-  process.exit(1);
-}
-
-const files = new Set(
-  fs
-    .readdirSync(SAMPLES)
-    .filter((f) => f.endsWith(".js"))
-    .map((f) => f.slice(0, -3)),
-);
-
-const missing = entries.filter((e) => !files.has(e.app));
-if (missing.length) {
-  console.error(`gen-samples: the gallery lists ${missing.length} class(es) with no file:`);
-  for (const e of missing) console.error(`  ${e.app}`);
-  process.exit(1);
-}
-
-// The `group` field separates the upstream sample repositories (samples,
-// controls, stack). Only one of them is carried into the port today, so
-// grouping by it yields a single bucket — the useful axis is `header`, the
-// category the in-app gallery prints above each block. Both are honoured:
-// groups first (in catalogue order), categories inside them.
-//
-// One presentation liberty: the gallery numbers its introductory tiles
-// `Basics I` … `Basics V`, one sample each. Five one-row tables is noise on a
-// page you scroll rather than search, so they collapse into one `Basics`
-// section — in catalogue order, which is the order they are meant to be read.
-const categoryOf = (header) => (/^Basics\b/.test(header) ? `Basics` : header);
-
-const groups = [];
-for (const e of entries) {
-  let g = groups.find((x) => x.name === e.group);
-  if (!g) groups.push((g = { name: e.group, categories: [] }));
-  const name = categoryOf(e.header);
-  let c = g.categories.find((x) => x.name === name);
-  if (!c) g.categories.push((c = { name, rows: [] }));
-  c.rows.push(e);
-}
-
-const md = (s) => s.replace(/\|/g, "\\|");
-const anchor = (s) =>
-  s
-    .toLowerCase()
-    .replace(/[^\w\- ]+/g, "")
-    .replace(/ /g, "-");
-
-const categories = groups.flatMap((g) => g.categories);
-const uncatalogued = [...files].filter((f) => f !== GALLERY && !entries.some((e) => e.app === f)).sort();
-
-const out = [];
-out.push(`<!-- GENERATED by scripts/gen-samples.mjs — do not edit by hand. -->`);
-out.push(`<!-- Regenerate with: CAP2UI5_DIR=/path/to/cap2UI5 npm run gen:samples -->`);
-out.push(``);
-out.push(`# Sample Catalogue`);
-out.push(``);
-out.push(
-  `The framework ships ${files.size} sample apps in \`core/srv/app/samples/\` — the ` +
-    `abap2UI5 demo collection, transpiled to JavaScript. ${entries.length} of them are ` +
-    `listed in the built-in gallery, and this page is that gallery's own table: it is ` +
-    `generated from \`${GALLERY}\`, the sample browser the framework itself renders, so it ` +
-    `cannot drift from what the playground offers.`,
-);
-out.push(``);
-out.push(
-  `Every title links into the [browser playground](./playground) — no install, no server. ` +
-    `The same apps run on your own CAP server under the same names: ` +
-    `\`?app_start=<class>\`, or \`client.nav_app_call()\` from an app of your own.`,
-);
-out.push(``);
-out.push(
-  `→ Prefer to browse in the app itself? Open ` +
-    `[\`${GALLERY}\`](${PLAYGROUND}?app_start=${GALLERY}) — the same catalogue with a search field.`,
-);
-out.push(``);
-out.push(
-  `Two markers are carried over from the upstream gallery: **(A)** marks a sample that ` +
-    `drives the frontend through a client action, **(C)** one that uses a custom control ` +
-    `from the \`z2ui5.cc\` namespace.`,
-);
-out.push(``);
-out.push(`## Categories`);
-out.push(``);
-out.push(
-  categories.map((c) => `[${c.name}](#${anchor(c.name)})`).join(" · "),
-);
-out.push(``);
-
-for (const c of categories) {
-  out.push(`## ${c.name}`);
-  out.push(``);
-  out.push(`| Sample | Class | Topics |`);
-  out.push(`|---|---|---|`);
-  for (const r of c.rows) {
-    out.push(
-      `| [${md(r.sub)}](${PLAYGROUND}?app_start=${r.app}) ` +
-        `| [\`${r.app}\`](${SOURCE}/${r.app}.js) ` +
-        `| ${md(r.keywords)} |`,
-    );
-  }
-  out.push(``);
-}
-
-if (uncatalogued.length) {
-  out.push(`## Not in the gallery`);
-  out.push(``);
-  out.push(
-    `${uncatalogued.length} further classes ship in the same folder without a catalogue ` +
-      `entry — they are the sub-apps the listed samples call (dialogs, detail views, ` +
-      `nested apps), not entries in their own right. They run the same way if you name ` +
-      `one directly:`,
-  );
-  out.push(``);
-  out.push(uncatalogued.map((a) => `\`${a}\``).join(", "));
-  out.push(``);
-}
-
-out.push(`## Where they come from`);
-out.push(``);
-out.push(
-  `The samples are machine-transpiled from the ABAP originals in ` +
-    `[abap2UI5-samples](https://github.com/abap2UI5/abap2UI5-samples) by the ` +
-    `[builder-abap2UI5-js](https://github.com/cap2UI5/builder-abap2UI5-js) pipeline, and ` +
-    `land in \`core/srv/app/samples/\` on every sync. That folder is pipeline-owned: ` +
-    `edits to it are overwritten on the next publish. Copy a sample into ` +
-    `[\`srv/app/\`](./project-structure#srv-app) before you change it.`,
-);
-out.push(``);
-out.push(
-  `Some samples need a real server: those that call external OData services or CAP ` +
-    `destinations will not work in the browser playground. See ` +
-    `[what the playground is not](./playground#what-its-not).`,
-);
-out.push(``);
-out.push(
-  `→ Ready to write your own? Start with [Hello World](../examples/hello-world), ` +
-    `or read the [App Lifecycle](./lifecycle).`,
-);
-out.push(``);
-
-const text = out.join("\n");
-
-if (CHECK) {
-  const current = fs.existsSync(OUT) ? fs.readFileSync(OUT, "utf8") : "";
-  if (current !== text) {
-    console.error(`gen-samples: ${path.relative(ROOT, OUT)} is out of date — run npm run gen:samples`);
-    process.exit(1);
-  }
-  console.log(`gen-samples: OK — ${path.relative(ROOT, OUT)} matches ${APP}`);
-  process.exit(0);
-}
-
-fs.writeFileSync(OUT, text);
-console.log(
-  `gen-samples: wrote ${path.relative(ROOT, OUT)} — ` +
-    `${entries.length} catalogued samples in ${categories.length} categories ` +
-    `(${files.size} files in ${path.relative(APP, SAMPLES)})`,
-);
diff --git a/scripts/verify-refs.mjs b/scripts/verify-refs.mjs
index 7931836..f9dddde 100644
--- a/scripts/verify-refs.mjs
+++ b/scripts/verify-refs.mjs
@@ -13,21 +13,49 @@
  *
  * None of that is caught by `vitepress build`: it validates that internal
  * MARKDOWN links resolve, and nothing at all about the world outside the
- * docs. The three builder repos each have a freshness watchdog; this is the
- * docs' equivalent — it reads the same ground truth AGENTS.md declares and
- * fails when prose and repository disagree.
+ * docs. This is the docs' equivalent — it reads the same ground truth
+ * AGENTS.md declares and fails when prose and repository disagree.
+ *
+ * WHAT CHANGED WITH THE PLUGIN (2026-09)
+ * --------------------------------------
+ * cap2UI5 used to be a generated CAP application with the framework vendored
+ * at `core/`, and this checker knew that shape: repo paths under `core/`,
+ * `srv/`, `db/`, `app/`; classes as FILES in the checkout; imports resolved
+ * through `core/package.json`'s exports map. None of that exists any more.
+ * cap2UI5 is a CAP plugin that hosts upstream's own transpiled runtime, so
+ * the ground truth moved and split in two:
+ *
+ *   - the cap2UI5 checkout still answers for repository paths, for the app
+ *     ids `?app_start=` may name, for what `require("cap2ui5")` exports and
+ *     for which runtime release is pinned;
+ *   - the FRAMEWORK CLASSES the docs name (z2ui5_cl_…, z2ui5_if_…) are not
+ *     in cap2UI5 at all. They are abap2UI5's ABAP, transpiled into
+ *     @abap2ui5/runtime — whose content is assembled, gitignored, and absent
+ *     from a fresh checkout. So the class inventory is read from the abap2UI5
+ *     source tree, which is where those names are actually defined.
+ *
+ * Resolving classes against the assembled runtime instead would have made the
+ * check pass on a laptop (where runtime/output exists) and silently check
+ * nothing in CI (where it does not) — the precise failure mode
+ * --require-checkout was added to prevent, one level down.
  *
  * WHAT IT CHECKS
  * --------------
- *   1. repository paths in backticks (`core/srv/…`, `srv/…`, `db/…`, …)
- *      exist in a cap2UI5 checkout
- *   2. every `?app_start=<class>` names a class that actually resolves
- *   3. every z2ui5 class named in backticks exists somewhere in the app
- *   4. every `require("abap2UI5/…")` in a FENCED CODE BLOCK resolves through
- *      the exports map of core/package.json, and onto a file that exists
- *   5. every three-part release number (1.x.y) the docs mention is the
- *      framework release the checkout actually pins (`static version` on
- *      z2ui5_if_app), or an allowlisted historical/UI5 number
+ *   1. repository paths in backticks (`plugin/…`, `examples/…`, …) exist in
+ *      a cap2UI5 checkout. Reader-owned paths (`srv/apps/…`, `db/…`) are NOT
+ *      claims about this repository and are deliberately not matched.
+ *   2. every `?app_start=<id>` names an app that is registered somewhere —
+ *      with `defineApp("ID", …)` in the cap2UI5 checkout, or in the same
+ *      documentation page (a page that teaches an app may name it).
+ *   3. every z2ui5 class named in backticks exists in the abap2UI5 source
+ *      the hosted runtime is built from.
+ *   4. every `require("cap2ui5")` in a FENCED CODE BLOCK destructures names
+ *      the package actually exports, and `require("cap2ui5/<sub>")` lands on
+ *      a file that exists. Stale `require("abap2UI5/…")` — the port's package,
+ *      which no longer exists — is reported by name.
+ *   5. every plugin option named as `cds.cap2ui5.<key>` is a key the plugin
+ *      really defines, and every three-part release number (1.x.y) is the
+ *      runtime release the checkout pins, or an allowlisted historical number.
  *
  * Check 4 exists because the first three did not see the largest defect this
  * site ever had. Fenced blocks were skipped wholesale as "examples, not
@@ -37,17 +65,18 @@
  * line above the example, and that line is a claim about the package.
  *
  * Usage:
- *   CAP2UI5_DIR=/path/to/cap2UI5 node scripts/verify-refs.mjs
- *   node scripts/verify-refs.mjs            # defaults to ../cap2UI5
+ *   CAP2UI5_DIR=… ABAP2UI5_DIR=… node scripts/verify-refs.mjs
+ *   node scripts/verify-refs.mjs            # defaults to ../cap2UI5, ../abap2UI5
  *   node scripts/verify-refs.mjs --list     # print the resolved inventory
  *   node scripts/verify-refs.mjs --require-checkout   # missing checkout = error
  *
- * Exits 1 on the first broken claim, with the file and line to fix. When no
- * checkout is available it says so and exits 0 — a missing checkout is a
- * setup gap, not a documentation defect. That leniency is right on a laptop
- * and wrong in CI: a workflow that checks cap2UI5 out and then silently loses
- * it would go on passing while checking nothing. `--require-checkout` turns
- * the skip into a failure, and .github/workflows/check.yml passes it.
+ * Exits 1 on the first broken claim, with the file and line to fix. When a
+ * checkout is missing it says so and skips the checks that need it — a missing
+ * checkout is a setup gap, not a documentation defect. That leniency is right
+ * on a laptop and wrong in CI: a workflow that checks the repos out and then
+ * silently loses one would go on passing while checking nothing.
+ * `--require-checkout` turns every skip into a failure, and
+ * .github/workflows/check.yml passes it.
  */
 import fs from "node:fs";
 import path from "node:path";
@@ -56,83 +85,124 @@ import { fileURLToPath } from "node:url";
 const ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), "..");
 const DOCS = path.join(ROOT, "docs");
 const APP = path.resolve(process.env.CAP2UI5_DIR || path.join(ROOT, "..", "cap2UI5"));
+const UPSTREAM = path.resolve(process.env.ABAP2UI5_DIR || path.join(ROOT, "..", "abap2UI5"));
 const LIST = process.argv.includes("--list");
 const REQUIRE_CHECKOUT = process.argv.includes("--require-checkout");
 
-if (!fs.existsSync(path.join(APP, "package.json"))) {
+const missing = [];
+const haveApp = fs.existsSync(path.join(APP, "plugin", "package.json"));
+const haveUpstream = fs.existsSync(path.join(UPSTREAM, "src"));
+if (!haveApp) missing.push([`cap2UI5`, APP, `CAP2UI5_DIR`, `cap2UI5/cap2UI5`]);
+if (!haveUpstream) missing.push([`abap2UI5`, UPSTREAM, `ABAP2UI5_DIR`, `abap2UI5/abap2UI5`]);
+
+if (missing.length) {
+  const how = missing
+    .map(([n, at, env, repo]) => `  ${n}: nothing at ${at} — set ${env}, or clone ${repo} next to this repo`)
+    .join("\n");
   if (REQUIRE_CHECKOUT) {
-    console.error(`verify-refs: no cap2UI5 checkout at ${APP} — required by --require-checkout.`);
-    console.error(`             set CAP2UI5_DIR or clone cap2UI5/cap2UI5 next to this repo.`);
+    console.error(`verify-refs: missing reference checkout(s) — required by --require-checkout.\n${how}`);
     console.error(`\nSkipping here would mean the run checked nothing while reporting success.`);
     process.exit(1);
   }
-  console.log(`verify-refs: no cap2UI5 checkout at ${APP} — skipping.`);
-  console.log(`             set CAP2UI5_DIR or clone cap2UI5/cap2UI5 next to this repo.`);
-  process.exit(0);
+  console.log(`verify-refs: skipping the checks that need a checkout.\n${how}`);
+  if (missing.length === 2) process.exit(0);
 }
 
-// ---- inventory of the app repo -------------------------------------------
-/** every file path in the app, repo-relative, excluding installs */
+// ---- inventory of the plugin repo -----------------------------------------
+/** every file path in a repo, repo-relative, excluding installs and anything
+ *  that is ASSEMBLED rather than committed — a path only a laptop has would
+ *  otherwise pass here and fail in CI, or worse, the other way round. */
 function inventory(dir, base = dir, out = new Set()) {
+  const SKIP = new Set(["node_modules", ".git", "gen", "dist", ".vitepress"]);
   for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
-    if (e.name === "node_modules" || e.name === ".git" || e.name === "gen") continue;
+    if (SKIP.has(e.name)) continue;
     const p = path.join(dir, e.name);
-    out.add(path.relative(base, p).split(path.sep).join("/"));
+    const rel = path.relative(base, p).split(path.sep).join("/");
+    if (/^runtime\/(output|setup|webapp)$/.test(rel)) continue;   // assembled, gitignored
+    out.add(rel);
     if (e.isDirectory()) inventory(p, base, out);
   }
   return out;
 }
 
-const files = inventory(APP);
-/** class name (lowercase) → repo-relative path */
-const classes = new Map();
-for (const f of files) {
-  const b = path.basename(f);
-  if (b.endsWith(".js")) classes.set(b.slice(0, -3).toLowerCase(), f);
+const files = haveApp ? inventory(APP) : new Set();
+
+/** app ids: what defineApp( ) registers in the checkout, lowercased */
+const appIds = new Set();
+if (haveApp) {
+  for (const f of files) {
+    if (!/\.(c|m)?js$/.test(f)) continue;
+    const src = fs.readFileSync(path.join(APP, f), "utf8");
+    for (const m of src.matchAll(/defineApp\(\s*["'`]([A-Za-z0-9_]+)["'`]/g)) appIds.add(m[1].toLowerCase());
+  }
 }
 
-// ---- the core package's exports map ---------------------------------------
-// `require("abap2UI5/x")` does not resolve to a path, it resolves through the
-// "exports" block of core/package.json — so a subpath that is not in that map
-// is a broken import even when a file of that name exists somewhere in the
-// tree, and a subpath that IS in the map still has to land on a real file.
-const CORE_PKG = path.join(APP, "core", "package.json");
-const EXPORTS = fs.existsSync(CORE_PKG)
-  ? JSON.parse(fs.readFileSync(CORE_PKG, "utf8")).exports || {}
-  : null;
+/** what `require("cap2ui5")` hands back — read from the package, not guessed */
+const PLUGIN_EXPORTS = (() => {
+  if (!haveApp) return null;
+  const idx = path.join(APP, "plugin", "index.js");
+  if (!fs.existsSync(idx)) return null;
+  const src = fs.readFileSync(idx, "utf8");
+  const m = /module\.exports\s*=\s*\{([^}]*)\}/.exec(src);
+  if (m) return new Set(m[1].split(",").map((s) => s.split(":")[0].trim()).filter(Boolean));
+  // `module.exports = require("./lib/x")` — read the names off that module
+  const re = /module\.exports\s*=\s*require\(\s*["'`](\.[^"'`]+)["'`]\s*\)/.exec(src);
+  if (!re) return null;
+  const lib = path.join(APP, "plugin", re[1].replace(/^\.\//, "").replace(/\.js$/, "") + ".js");
+  const inner = /module\.exports\s*=\s*\{([^}]*)\}/.exec(fs.readFileSync(lib, "utf8"));
+  return inner ? new Set(inner[1].split(",").map((s) => s.trim()).filter(Boolean)) : null;
+})();
 
-/**
- * Resolve `abap2UI5/<subpath>` (or bare `abap2UI5`) the way node does:
- * an exact key wins, otherwise the pattern key with the longest prefix.
- * Returns the repo-relative path it lands on, or null when nothing matches.
- */
-function resolveExport(subpath) {
-  if (!EXPORTS) return null;
-  const key = subpath ? `./${subpath}` : `.`;
-  const inApp = (target) => `core/${target.replace(/^\.\//, "")}`;
-
-  if (typeof EXPORTS[key] === "string") return inApp(EXPORTS[key]);
-
-  let best = null;
-  for (const [k, target] of Object.entries(EXPORTS)) {
-    const star = k.indexOf("*");
-    if (star === -1 || typeof target !== "string") continue;
-    const pre = k.slice(0, star);
-    const post = k.slice(star + 1);
-    if (!key.startsWith(pre) || !key.endsWith(post)) continue;
-    if (key.length < pre.length + post.length) continue;
-    if (best && pre.length <= best.pre.length) continue;
-    best = { pre, post, target, star: key.slice(pre.length, key.length - post.length) };
-  }
-  if (!best) return null;
-  return inApp(best.target.replace(`*`, best.star));
+/** the plugin's own configuration keys, from package.json#cds.cap2ui5 */
+const PLUGIN_OPTIONS = (() => {
+  if (!haveApp) return null;
+  try {
+    const pkg = JSON.parse(fs.readFileSync(path.join(APP, "plugin", "package.json"), "utf8"));
+    return new Set(Object.keys(pkg.cds?.cap2ui5 ?? {}));
+  } catch { return null; }
+})();
+
+// ---- inventory of the framework's classes ---------------------------------
+// From abap2UI5's ABAP, which is what @abap2ui5/runtime is transpiled from.
+// Both z2ui5_cl_* and z2ui5_if_* land here; upstream's frozen src/99 is
+// included because the hosted runtime carries it (measured: the assembled
+// output has z2ui5_cl_xml_view.clas.mjs). A name being present is not a
+// recommendation, only a statement that it exists.
+const classes = new Set();
+if (haveUpstream) {
+  const walk = (dir) => {
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+      const p = path.join(dir, e.name);
+      if (e.isDirectory()) { walk(p); continue; }
+      const m = /^([a-z0-9_]+)\.(clas|intf)\.abap$/.exec(e.name);
+      if (m && !e.name.includes(".testclasses.")) classes.add(m[1].toLowerCase());
+    }
+  };
+  walk(path.join(UPSTREAM, "src"));
 }
 
+// ---- the pinned runtime release -------------------------------------------
+/* The site names the runtime release in prose ("@abap2ui5/runtime 1.144.0"),
+ * and the day the pin moves, every mention goes stale at once — the exact
+ * defect class the path and class checks exist for, one level up. The ground
+ * truth is the package the plugin hosts. Numbers that are NOT that pin live in
+ * .verify-refs-ignore with a reason: historical upstream releases stay true
+ * whatever the pin says, and UI5 numbers are not framework releases at all.
+ * Two-part floors like 1.71 are UI5 talk and deliberately not matched. */
+const VERSION_SOURCE = "runtime/package.json";
+const PINNED_RELEASE = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(APP, VERSION_SOURCE), "utf8")).version ?? null;
+  } catch { return null; }
+})();
+
 if (LIST) {
-  console.log(`${files.size} paths, ${classes.size} classes in ${APP}`);
-  console.log(`exports map: ${EXPORTS ? Object.keys(EXPORTS).length + " subpaths" : "NOT FOUND"}`);
-  const samples = [...classes.keys()].filter((c) => c.startsWith("z2ui5_cl_smp_")).sort();
-  console.log(`samples (${samples.length}): ${samples.join(", ")}`);
+  console.log(`${files.size} paths in ${APP}`);
+  console.log(`${classes.size} framework classes/interfaces in ${UPSTREAM}/src`);
+  console.log(`app ids (${appIds.size}): ${[...appIds].sort().join(", ")}`);
+  console.log(`cap2ui5 exports: ${PLUGIN_EXPORTS ? [...PLUGIN_EXPORTS].join(", ") : "NOT FOUND"}`);
+  console.log(`plugin options: ${PLUGIN_OPTIONS ? [...PLUGIN_OPTIONS].join(", ") : "NOT FOUND"}`);
+  console.log(`pinned runtime: ${PINNED_RELEASE ?? "NOT FOUND"}`);
   process.exit(0);
 }
 
@@ -151,41 +221,30 @@ const problems = [];
 const add = (file, line, msg) =>
   problems.push(`${path.relative(ROOT, file)}:${line}  ${msg}`);
 
-// A backticked token that looks like a path INTO the app repo. Deliberately
-// narrow: only the roots the app actually has, so prose like `npm run build`
-// or a path in another repo is not mistaken for a claim about this one.
-const PATH_ROOTS = ["core/", "srv/", "db/", "app/", "test/"];
+// A backticked token that looks like a path INTO the cap2UI5 repository.
+// Deliberately narrow: only the roots that repository actually has. `srv/`,
+// `db/` and `app/` are NOT here — since the plugin, those are the READER's
+// project, and checking them against this repo would flag correct prose.
+const PATH_ROOTS = ["plugin/", "examples/", "runtime/", "scripts/", "docs/adr/"];
 const PATH_RE = /`([A-Za-z0-9_@./-]+\/[A-Za-z0-9_@./-]+)`/g;
 const APP_START_RE = /app_start=([a-z0-9_]+)/gi;
-/* Check 5: release numbers. The site names the pinned framework release in
- * NINE places across four pages ("Here, on 1.142.0", "cap2UI5 pins abap2UI5
- * **1.142.0**"), and the day the port moves its pin, every one of them goes
- * stale at once - the exact defect class checks 1-4 exist for, one level up.
- * The ground truth is the same place the prose itself points at: `static
- * version` on z2ui5_if_app in the checkout. Every three-part 1.x.y the docs
- * mention must be that version, or an entry in .verify-refs-ignore with a
- * reason - which is where the HISTORICAL numbers live (1.143.0, the upstream
- * release where the bindings merged, stays true whatever the pin says) and
- * the UI5 ones (1.113.0 is an OpenUI5 release, not a framework release).
- * Two-part floors like 1.71 are UI5 talk and deliberately not matched. */
 const RELEASE_RE = /\b1\.\d{2,3}\.\d+\b/g;
-const VERSION_SOURCE = "core/srv/z2ui5/02/z2ui5_if_app.js";
-const PINNED_RELEASE = (() => {
-  try {
-    return fs.readFileSync(path.join(APP, VERSION_SOURCE), "utf8")
-      .match(/static version = `(\d+\.\d+\.\d+)`/)?.[1] ?? null;
-  } catch {
-    return null;
-  }
-})();
 // A backticked span that STARTS with a z2ui5 class name. It deliberately does
 // not require the closing backtick to follow the identifier: the docs write
 // `z2ui5_cl_xml_view.js`, `z2ui5_cl_util.register_app_dir(dir)` and
 // `z2ui5_cl_xml_view=>factory( )`, and demanding a bare identifier meant every
 // one of those mentions was invisible to this checker.
 const CLASS_RE = /`(z2ui5_(?:cl|if|cx)_[a-z0-9_]+)(?![a-z0-9_])/gi;
-// require("abap2UI5"), require("abap2UI5/z2ui5_if_app"), … in a code fence.
-const REQUIRE_RE = /require\(\s*["'`]abap2UI5(?:\/([^"'`]+))?["'`]\s*\)/g;
+// require("cap2ui5"), require("cap2ui5/lib/…"), and the port's dead package.
+const REQUIRE_RE = /require\(\s*["'`](cap2ui5|abap2UI5)(?:\/([^"'`]+))?["'`]\s*\)/gi;
+// `const { defineApp, t } = require("cap2ui5")` — the names, not just the path
+const DESTRUCTURE_RE = /(?:const|let|var)\s*\{([^}]*)\}\s*=\s*require\(\s*["'`]cap2ui5["'`]\s*\)/g;
+// `cds.cap2ui5.apps`, `cap2ui5.webapp` in prose or a config block. Case
+// matters and the flag is deliberately absent: `cap2ui5.Drafts` is the CDS
+// ENTITY, which the docs name constantly and which is not an option at all.
+const OPTION_RE = /`(?:cds\.)?cap2ui5\.([a-z][a-z_]*)`/g;
+// which app ids a PAGE defines itself: a page teaching an app may name it
+const DEFINES_RE = /defineApp\(\s*["'`]([A-Za-z0-9_]+)["'`]/g;
 
 // Tokens the docs use that are not claims about this repository — other
 // repos' paths, files the reader creates, placeholder class names. Each is
@@ -201,22 +260,10 @@ const IGNORE = new Set(
     .filter(Boolean),
 );
 
-// Whole directory trees that belong to a different repo in the ecosystem.
-const NOT_IN_APP_REPO = [
-  /^src\//,            // builder-cap2UI5's source tree
-  /^run\//,            // builder run trees
-  /^adapters\//,       // builder-abap2UI5-js adapters
-  /^scripts\//,        // builder scripts
-  /^dist\//,           // web build output
-  /^gen\//,            // cds build output
-  /^docs\//,           // this repo
-  /^node_modules\//,
-  /^\.github\//,
-];
-
 for (const file of markdownFiles(DOCS)) {
   const text = fs.readFileSync(file, "utf8");
   const lines = text.split("\n");
+  const pageApps = new Set([...text.matchAll(DEFINES_RE)].map((m) => m[1].toLowerCase()));
 
   // Fenced code blocks show paths a reader will create, so the path check
   // stays out of them — but the imports and the `?app_start=` URLs in an
@@ -231,29 +278,45 @@ for (const file of markdownFiles(DOCS)) {
       for (const m of line.matchAll(RELEASE_RE)) {
         if (m[0] === PINNED_RELEASE || IGNORE.has(m[0])) continue;
         add(file, n, `names release ${m[0]}, but the checkout pins ${PINNED_RELEASE} `
-          + `(static version in ${VERSION_SOURCE}) - update the prose, or add the number `
+          + `(version in ${VERSION_SOURCE}) - update the prose, or add the number `
           + `to .verify-refs-ignore with the reason it stays`);
       }
     }
 
+    for (const m of line.matchAll(APP_START_RE)) {
+      const id = m[1].toLowerCase();
+      if (appIds.has(id) || pageApps.has(id) || IGNORE.has(id)) continue;
+      if (!haveApp) continue;
+      add(file, n, `?app_start names an app nothing registers: ${m[1]} `
+        + `(no defineApp("${m[1].toUpperCase()}") in the checkout or on this page)`);
+    }
+
     if (inFence) {
       for (const m of line.matchAll(REQUIRE_RE)) {
-        const sub = m[1] || ``;
-        const spec = `abap2UI5${sub ? `/${sub}` : ``}`;
-        if (/[*…]/.test(sub)) continue;            // a shape, not an import
+        const pkg = m[1];
+        const sub = m[2] || ``;
+        const spec = `${pkg}${sub ? `/${sub}` : ``}`;
+        if (/[*…]/.test(sub)) continue;                  // a shape, not an import
         if (IGNORE.has(spec.toLowerCase())) continue;
-        if (!EXPORTS) continue;                    // no core package to check against
-        const target = resolveExport(sub);
-        if (!target) {
-          add(file, n, `require("${spec}") has no match in the core exports map`);
-        } else if (!files.has(target)) {
+        if (pkg.toLowerCase() === "abap2ui5") {
+          add(file, n, `require("${spec}") is the RETIRED port package - the plugin is `
+            + `require("cap2ui5"), and the framework's own classes are not importable`);
+          continue;
+        }
+        if (!haveApp || !sub) continue;                  // bare require checked below
+        const target = path.join("plugin", sub.endsWith(".js") ? sub : `${sub}.js`);
+        if (!files.has(target.split(path.sep).join("/"))) {
           add(file, n, `require("${spec}") resolves to ${target}, which does not exist`);
         }
       }
-      for (const m of line.matchAll(APP_START_RE)) {
-        const cls = m[1].toLowerCase();
-        if (classes.has(cls) || IGNORE.has(cls)) continue;
-        add(file, n, `?app_start names a class that does not exist: ${m[1]}`);
+      for (const m of line.matchAll(DESTRUCTURE_RE)) {
+        if (!PLUGIN_EXPORTS) continue;
+        for (const raw of m[1].split(",")) {
+          const name = raw.split(":")[0].trim();
+          if (!name || PLUGIN_EXPORTS.has(name) || IGNORE.has(name.toLowerCase())) continue;
+          add(file, n, `require("cap2ui5") does not export ${name} `
+            + `(it exports ${[...PLUGIN_EXPORTS].join(", ")})`);
+        }
       }
       return;
     }
@@ -261,28 +324,25 @@ for (const file of markdownFiles(DOCS)) {
     for (const m of line.matchAll(PATH_RE)) {
       const p = m[1].replace(/^\.\//, "").replace(/\/$/, "");
       if (!PATH_ROOTS.some((r) => (p + "/").startsWith(r))) continue;
-      if (NOT_IN_APP_REPO.some((re) => re.test(p))) continue;
       if (IGNORE.has(p.toLowerCase())) continue;
       if (p.includes("*")) continue;             // globs describe a shape
-      if (files.has(p)) continue;
+      if (!haveApp || files.has(p)) continue;
       add(file, n, `path does not exist in cap2UI5: ${p}`);
     }
 
-    for (const m of line.matchAll(APP_START_RE)) {
-      const cls = m[1].toLowerCase();
-      if (classes.has(cls) || IGNORE.has(cls)) continue;
-      add(file, n, `?app_start names a class that does not exist: ${m[1]}`);
+    for (const m of line.matchAll(OPTION_RE)) {
+      if (!PLUGIN_OPTIONS) continue;
+      const key = m[1].toLowerCase();
+      if (PLUGIN_OPTIONS.has(key) || IGNORE.has(`cap2ui5.${key}`)) continue;
+      add(file, n, `cap2ui5.${m[1]} is not a plugin option `
+        + `(package.json#cds.cap2ui5 defines ${[...PLUGIN_OPTIONS].join(", ")})`);
     }
 
     for (const m of line.matchAll(CLASS_RE)) {
       const cls = m[1].toLowerCase();
       if (line[m.index + m[0].length] === "*") continue;   // glob: a family, not a class
-      if (classes.has(cls) || IGNORE.has(cls)) continue;
-      // Interfaces are not always separate files, and abstract/ABAP-only
-      // names appear when contrasting with abap2UI5 — only flag cl_ classes,
-      // which are concrete and must exist.
-      if (!cls.startsWith("z2ui5_cl_")) continue;
-      add(file, n, `class does not exist in cap2UI5: ${m[1]}`);
+      if (!haveUpstream || classes.has(cls) || IGNORE.has(cls)) continue;
+      add(file, n, `no such class or interface in abap2UI5: ${m[1]}`);
     }
   });
 }
@@ -354,10 +414,11 @@ for (const file of markdownFiles(DOCS)) {
 }
 
 if (problems.length) {
-  console.error(`verify-refs: ${problems.length} stale reference(s) against ${APP}\n`);
+  console.error(`verify-refs: ${problems.length} stale reference(s)\n`);
   for (const p of problems) console.error(`  ${p}`);
-  console.error(`\nThe docs describe the cap2UI5 repo — update the prose, or the path/class moved.`);
+  console.error(`\ncap2UI5: ${APP}\nabap2UI5: ${UPSTREAM}`);
+  console.error(`The docs describe these repos — update the prose, or the path/class moved.`);
   process.exit(1);
 }
 
-console.log(`verify-refs: OK — every documented path and class resolves in ${APP}`);
+console.log(`verify-refs: OK — every documented path, class, app id and option resolves`);