From 29eccd00d29f2a8ac2b9c367a04d3244b5452378 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 29 Sep 2026 01:49:47 +0000
Subject: [PATCH] Use the published package name @cap2ui5/cds-plugin, and
 document the samples

cap2UI5 0.3.0 is published as @cap2ui5/cds-plugin, and the unscoped package
cap2ui5 was withdrawn from npm. Every install command, import and dependency
line on the site named the withdrawn package, so a reader following the
quickstart could no longer install anything. They now name
@cap2ui5/cds-plugin; what kept its name (cds.requires.cap2ui5,
cds add cap2ui5, npx cap2ui5 abap2js, cap2ui5.Drafts, the cap2ui5 logger)
is left as it is, and so are the historical records (ROADMAP.md, the
0.1.0 warning on the views page).

0.3.0 also serves apps a dependency brings, and @cap2ui5/samples is the
first such package. The quickstart gains a short section on adding the
samples, project-structure explains apps from a package, the ecosystem page
lists the new repository and package, and the quickstart tells a project
that has the old package how to swap it.

verify-refs checked imports, requires and dependency ranges against the
name "cap2ui5". It now checks them against @cap2ui5/cds-plugin, and reports
the old name the way it reports the port's dead abap2UI5 package, so a
stale import cannot pass silently.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NwpbkojNzGmuJrFdbwo5JF
---
 .github/workflows/check.yml           |  2 +-
 AGENTS.md                             | 33 +++++++++-----
 HANDOVER.md                           |  5 +++
 README.md                             |  2 +-
 docs/api/app-interface.md             |  2 +-
 docs/examples/external-odata.md       |  2 +-
 docs/examples/hello-world.md          |  4 +-
 docs/examples/list.md                 |  2 +-
 docs/examples/selection-screen.md     |  2 +-
 docs/examples/static-xml-view.md      |  2 +-
 docs/guide/ecosystem.md               | 16 ++++---
 docs/guide/getting-started.md         | 60 +++++++++++++++++++------
 docs/guide/lifecycle.md               |  2 +-
 docs/guide/migration-from-abap2ui5.md |  2 +-
 docs/guide/persistence.md             |  2 +-
 docs/guide/project-structure.md       | 38 +++++++++++++---
 docs/guide/roadmap.md                 |  2 +-
 docs/guide/troubleshooting.md         |  4 +-
 docs/guide/user-exit.md               |  2 +-
 docs/guide/what-is-cap2ui5.md         |  4 +-
 docs/guide/where-it-comes-from.md     |  2 +-
 docs/index.md                         |  2 +-
 docs/reference/configuration.md       |  8 ++--
 docs/reference/deployment.md          | 10 ++---
 scripts/verify-refs.mjs               | 65 +++++++++++++++++----------
 25 files changed, 186 insertions(+), 89 deletions(-)

diff --git a/.github/workflows/check.yml b/.github/workflows/check.yml
index fab7aa3..22fa71a 100644
--- a/.github/workflows/check.yml
+++ b/.github/workflows/check.yml
@@ -30,7 +30,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       # The documented targets. verify-refs checks every path, class, app id,
-      # plugin option and `require("cap2ui5")` on this site against real
+      # plugin option and `require("@cap2ui5/cds-plugin")` 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
diff --git a/AGENTS.md b/AGENTS.md
index 6b0e17d..99d9f32 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -16,9 +16,10 @@ VitePress build. It is also what CI runs, on every pull request
 - 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")` or `import { … } from "cap2ui5"` **inside a code
-  fence** names only what the package really exports (and the port's
-  `abap2UI5/…` package is reported, in either form),
+- every `require("@cap2ui5/cds-plugin")` or `import { … } from
+  "@cap2ui5/cds-plugin"` **inside a code fence** names only what the package
+  really exports (and two dead packages are reported, in either form: the
+  port's `abap2UI5/…` and the plugin's withdrawn old name `cap2ui5`),
 - 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.
@@ -55,13 +56,19 @@ against the repos, don't guess):
 
 | Repo | Role |
 |---|---|
-| [cap2UI5/cap2UI5](https://github.com/cap2UI5/cap2UI5) | the npm package `cap2ui5`: a CAP plugin that hosts upstream's transpiled runtime. Also the home of the decision records (`docs/adr/`) |
+| [cap2UI5/cap2UI5](https://github.com/cap2UI5/cap2UI5) | the npm package `@cap2ui5/cds-plugin`: a CAP plugin that hosts upstream's transpiled runtime. Also the home of the decision records (`docs/adr/`) |
+| [cap2UI5/samples](https://github.com/cap2UI5/samples) | the npm package `@cap2ui5/samples`: abap2UI5's samples as cap2UI5 apps, which a project adds as a (dev) dependency |
 | [abap2UI5/abap2UI5](https://github.com/abap2UI5/abap2UI5) | the framework itself, in ABAP. Downported and transpiled, it is published as `@abap2ui5/node-runtime` |
 | [cap2UI5/docs](https://github.com/cap2UI5/docs) | this site |
 
-Both packages are on npm since 2026-09-27: `cap2ui5@0.1.0` (Node ≥ 20, peer
-`@sap/cds` ≥ 9) and `@abap2ui5/node-runtime@1.145.0` (Node ≥ 22), which
-`cap2ui5` pins **exactly**. The runtime package was renamed from
+On npm since 2026-09-29: `@cap2ui5/cds-plugin@0.3.0` (Node ≥ 22, peer
+`@sap/cds` ≥ 9), published by the npm organisation `cap2ui5`, and
+`@cap2ui5/samples@0.1.0`. The plugin pins `@abap2ui5/node-runtime@1.145.0`
+(on npm since 2026-09-27) **exactly**. Up to 0.2.0 the plugin was the unscoped
+package `cap2ui5`; it is withdrawn from npm (0.2.0 never reached it), so the
+site names it only as the old name. What did NOT change name: the
+configuration `cds.requires.cap2ui5`, `cds add cap2ui5`, the bin
+`npx cap2ui5 abap2js`, the entity `cap2ui5.Drafts` and the logger `cap2ui5`. The runtime package was renamed from
 `@abap2ui5/runtime` before its first publish — the old name never existed on
 npm, and on the site it appears only in prose that says it is the old name.
 
@@ -83,7 +90,8 @@ Path conventions inside cap2UI5:
 
 - `plugin/` — the package: `cds-plugin.js` (the route, the auth guard, the
   startup lines naming each app's address), `index.cds` (the `cap2ui5.Drafts`
-  entity), `index.js` (what `import`/`require` of `cap2ui5` returns) and `lib/`
+  entity), `index.js` (what `import`/`require` of `@cap2ui5/cds-plugin`
+  returns) and `lib/`
   (`define-app.js`, `define-exit.js`, `draft-store.js`, `hints.js`,
   `runtime.js`)
 - `examples/bookshop/` — a CAP project using it, with the test suite. Its apps
@@ -94,11 +102,12 @@ Path conventions inside cap2UI5:
 - `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 (whose GET page
+confused with the above: they install `@cap2ui5/cds-plugin`, write apps in
+`srv/apps/` (configurable via `cds.cap2ui5.apps`), may add packages that bring
+apps (`@cap2ui5/samples` for one), and get the route (whose GET page
 embeds the UI5 frontend) and the draft entity from the plugin. A project from
 `cds init --nodejs` is an ES module project, so the site's examples `import`
-from `cap2ui5`; a `require` in a `.js` file there fails the whole runtime
+from `@cap2ui5/cds-plugin`; a `require` in a `.js` file there fails the whole runtime
 boot. `srv/`, `db/` and `app/` in the prose are
 therefore **their** paths, which is why verify-refs does not check them
 against the cap2UI5 repository.
@@ -109,7 +118,7 @@ against the cap2UI5 repository.
 - The framework's own classes are **not a supported import**. Importing
   `@abap2ui5/node-runtime/output/…` technically works — the package exports
   `./output/*` — but it couples an app to transpiler output. A JS app imports
-  `cap2ui5` and nothing else; `c.raw` is the escape hatch to the transpiled
+  `@cap2ui5/cds-plugin` and nothing else; `c.raw` is the escape hatch to the transpiled
   `z2ui5_if_client`. An app that wants the framework's ABAP API (the view
   builder, for one) is written in ABAP and transpiled — see the views guide.
 - Measure before documenting a framework behaviour. The runtime is upstream's
diff --git a/HANDOVER.md b/HANDOVER.md
index 5aec7e9..b5e9722 100644
--- a/HANDOVER.md
+++ b/HANDOVER.md
@@ -1,5 +1,10 @@
 # Handover — what is left
 
+> **2026-09-29:** the plugin is published as `@cap2ui5/cds-plugin` 0.3.0 now,
+> next to `@cap2ui5/samples` 0.1.0; the unscoped `cap2ui5` is withdrawn from
+> npm. The site uses the new name. Below, `cap2ui5` is the name at the time
+> each line was written.
+
 Both packages are **on npm** since 2026-09-27: `cap2ui5@0.1.0` and
 `@abap2ui5/node-runtime@1.145.0`, which `cap2ui5` pins exactly. The two steps
 this file used to list — publish the runtime package, then point cap2UI5 at
diff --git a/README.md b/README.md
index bfd5402..5792310 100644
--- a/README.md
+++ b/README.md
@@ -2,7 +2,7 @@
 
 VitePress documentation for [**cap2UI5**](https://github.com/cap2UI5/cap2UI5) — the CAP / Node.js port of the [abap2UI5](https://github.com/abap2UI5/abap2UI5) concept. Published at **[cap2ui5.github.io/docs](https://cap2ui5.github.io/docs/)**.
 
-To try it, follow the [Quickstart](https://cap2ui5.github.io/docs/guide/getting-started): a CAP project, `npm install cap2ui5`, `cds watch`.
+To try it, follow the [Quickstart](https://cap2ui5.github.io/docs/guide/getting-started): a CAP project, `npm add @cap2ui5/cds-plugin`, `cds watch`.
 
 ## Develop locally
 
diff --git a/docs/api/app-interface.md b/docs/api/app-interface.md
index ce55f0c..c68488a 100644
--- a/docs/api/app-interface.md
+++ b/docs/api/app-interface.md
@@ -1,7 +1,7 @@
 # API: `defineApp` and `t`
 
 ```js
-import { defineApp, defineExit, t } from "cap2ui5";
+import { defineApp, defineExit, t } from "@cap2ui5/cds-plugin";
 ```
 
 `defineApp` registers a class as an app; `t` declares the field types that
diff --git a/docs/examples/external-odata.md b/docs/examples/external-odata.md
index f2af53f..abbf41f 100644
--- a/docs/examples/external-odata.md
+++ b/docs/examples/external-odata.md
@@ -45,7 +45,7 @@ plain CAP.
 ```js
 // srv/apps/northwind.js
 import cds from "@sap/cds";
-import { defineApp, t } from "cap2ui5";
+import { defineApp, t } from "@cap2ui5/cds-plugin";
 const { SELECT } = cds.ql;
 
 defineApp("ZCL_NORTHWIND", class {
diff --git a/docs/examples/hello-world.md b/docs/examples/hello-world.md
index d7fb71a..fb82446 100644
--- a/docs/examples/hello-world.md
+++ b/docs/examples/hello-world.md
@@ -7,7 +7,7 @@ browser test on every CI run.
 
 ```js
 // srv/apps/hello.js
-import { defineApp } from "cap2ui5";
+import { defineApp } from "@cap2ui5/cds-plugin";
 
 defineApp("ZCL_JS_HELLO", class {
   name = "";
@@ -37,7 +37,7 @@ http://localhost:4004/rest/root/z2ui5?app_start=ZCL_JS_HELLO
 
 | | |
 |---|---|
-| `import { … } from "cap2ui5"` | the plugin's export surface: `defineApp`, `t`, and `defineExit` for the [user exit](../guide/user-exit) |
+| `import { … } from "@cap2ui5/cds-plugin"` | the plugin's export surface: `defineApp`, `t`, and `defineExit` for the [user exit](../guide/user-exit) |
 | `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` |
diff --git a/docs/examples/list.md b/docs/examples/list.md
index ce47d28..9f5b26f 100644
--- a/docs/examples/list.md
+++ b/docs/examples/list.md
@@ -8,7 +8,7 @@ rather than sketched.
 ```js
 // srv/apps/books.js
 import cds from "@sap/cds";
-import { defineApp, t } from "cap2ui5";
+import { defineApp, t } from "@cap2ui5/cds-plugin";
 const { SELECT, INSERT } = cds.ql;
 
 defineApp("ZCL_JS_BOOKS", class {
diff --git a/docs/examples/selection-screen.md b/docs/examples/selection-screen.md
index b84b25d..8a393f6 100644
--- a/docs/examples/selection-screen.md
+++ b/docs/examples/selection-screen.md
@@ -13,7 +13,7 @@ closest to is [`books.js`](./list).
 ```js
 // srv/apps/orders.js
 import cds from "@sap/cds";
-import { defineApp, t } from "cap2ui5";
+import { defineApp, t } from "@cap2ui5/cds-plugin";
 const { SELECT } = cds.ql;
 
 defineApp("ZCL_ORDERS", class {
diff --git a/docs/examples/static-xml-view.md b/docs/examples/static-xml-view.md
index f69f454..59641aa 100644
--- a/docs/examples/static-xml-view.md
+++ b/docs/examples/static-xml-view.md
@@ -40,7 +40,7 @@ Two kinds of placeholder are in there, and the difference matters:
 
 ```js
 import fs from "node:fs";
-import { defineApp, t } from "cap2ui5";
+import { defineApp, t } from "@cap2ui5/cds-plugin";
 
 // read once at load, not per roundtrip; the path is relative to this file
 const XML = fs.readFileSync(new URL("./views/orders.xml", import.meta.url), "utf8");
diff --git a/docs/guide/ecosystem.md b/docs/guide/ecosystem.md
index 0e54419..9660df3 100644
--- a/docs/guide/ecosystem.md
+++ b/docs/guide/ecosystem.md
@@ -8,7 +8,8 @@ owns what saves time when something breaks.
 | | |
 |---|---|
 | [**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 a stand-in for `@abap2ui5/node-runtime` that the repository's own tests build from upstream |
+| [**cap2UI5/cap2UI5**](https://github.com/cap2UI5/cap2UI5) | the plugin. `plugin/` is the npm package `@cap2ui5/cds-plugin`; `examples/bookshop` is a CAP project using it; `runtime/` is a stand-in for `@abap2ui5/node-runtime` that the repository's own tests build from upstream |
+| [**cap2UI5/samples**](https://github.com/cap2UI5/samples) | abap2UI5's samples as cap2UI5 apps, each translated from its ABAP original by `npx cap2ui5 abap2js` — the npm package `@cap2ui5/samples` |
 | [**cap2UI5/docs**](https://github.com/cap2UI5/docs) | this site |
 
 The decisions that led to the current design are in the plugin repository,
@@ -19,19 +20,22 @@ The four repositories of the earlier port — `builder-abap2UI5-js`, which
 transpiled abap2UI5 into JavaScript, and `builder-cap2UI5`,
 `builder-cap2UI5-web` and `web-cap2UI5-build`, which generated an application
 and a playground from it — are archived or being archived. Nothing consumes
-their output: `cap2ui5` depends on `@abap2ui5/node-runtime` from npm, which
+their output: `@cap2ui5/cds-plugin` depends on `@abap2ui5/node-runtime` from npm, which
 abap2UI5 builds itself.
 
 ## The packages
 
 | | |
 |---|---|
-| `cap2ui5` | the plugin — about 640 lines of code. Mounts the route, implements the draft store over a CDS entity, turns a JS class into something the runtime can call |
+| `@cap2ui5/cds-plugin` | the plugin — about 640 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/node-runtime` | abap2UI5: upstream's ABAP, downported and transpiled over open-abap, with the UI5 frontend embedded in the page its GET answers with — backend and frontend from one commit |
+| `@cap2ui5/samples` | abap2UI5's samples as cap2UI5 apps. Optional: added to a project, they run beside its own apps — see [Apps from a package](./project-structure#apps-from-a-package) |
 
-Both are on npm: `cap2ui5` 0.1.0 (Node ≥ 20, `@sap/cds` ≥ 9 as a peer) and
-`@abap2ui5/node-runtime` 1.145.0 (Node ≥ 22), which `cap2ui5` pins exactly.
-`npm install cap2ui5` installs both — see the [Quickstart](./getting-started).
+All three are on npm: `@cap2ui5/cds-plugin` 0.3.0 (Node ≥ 22, `@sap/cds` ≥ 9 as a peer),
+`@abap2ui5/node-runtime` 1.145.0 (Node ≥ 22), which the plugin pins exactly,
+and `@cap2ui5/samples` 0.1.0. `npm add @cap2ui5/cds-plugin` installs the first two — see the
+[Quickstart](./getting-started). Up to 0.2.0 the plugin was the unscoped
+package `cap2ui5`, which is withdrawn from npm.
 
 ## What the plugin does and does not own
 
diff --git a/docs/guide/getting-started.md b/docs/guide/getting-started.md
index cfdbce2..40e01dd 100644
--- a/docs/guide/getting-started.md
+++ b/docs/guide/getting-started.md
@@ -6,8 +6,8 @@ already have, or to a brand new one. There is no cap2UI5 project to clone.
 
 ## Prerequisites
 
-- **Node.js 22 or later** — `@abap2ui5/node-runtime`, which the plugin depends
-  on, requires it (`cap2ui5` itself says ≥ 20)
+- **Node.js 22 or later** — the plugin, `@cap2ui5/cds-plugin`, and
+  `@abap2ui5/node-runtime`, which it depends on, both require it
 - **`@sap/cds-dk`** installed globally, for the `cds` command
 - Internet access — the page loads UI5 from the SAP CDN
 
@@ -23,8 +23,8 @@ It must print `v22` or higher.
 
 ## 1. A CAP project and the plugin
 
-Skip `cds init` if you already have a CAP project and run the `npm install cap2ui5`
-line in it.
+Skip `cds init` if you already have a CAP project and run the
+`npm add @cap2ui5/cds-plugin` line in it.
 
 ```bash
 npm i -g @sap/cds-dk
@@ -40,7 +40,7 @@ not help. Then create the project and add the plugin:
 cds init my-cap2ui5-app --nodejs --add tiny-sample
 cd my-cap2ui5-app
 npm install
-npm install cap2ui5
+npm add @cap2ui5/cds-plugin
 ```
 
 `--add tiny-sample` gives the project something to read later: a service
@@ -48,8 +48,8 @@ npm install cap2ui5
 books in `db/data/CatalogService.Books.csv`.
 
 ::: details Optional: check the CAP project before adding the plugin
-Run `cds watch` after the first `npm install` and before `npm install cap2ui5`,
-and open <http://localhost:4004>. CAP's index page lists the service endpoint
+Run `cds watch` after the first `npm install` and before
+`npm add @cap2ui5/cds-plugin`, and open <http://localhost:4004>. CAP's index page lists the service endpoint
 `/odata/v4/catalog` with `Books`; the link answers the five books as JSON.
 That is a plain CAP project working. Stop the server with `Ctrl+C` and go on.
 :::
@@ -59,9 +59,9 @@ Two things about `cds init` that cost time when missed. Without `--nodejs`,
 to install the plugin into. And it fails in a folder whose name contains a
 space.
 
-`npm install cap2ui5` is the whole installation. It brings two packages from
-npm — `cap2ui5` and the `@abap2ui5/node-runtime` release it pins — and on the
-next `cds watch` these exist that did not before:
+`npm add @cap2ui5/cds-plugin` is the whole installation. It brings two
+packages from npm — `@cap2ui5/cds-plugin` and the `@abap2ui5/node-runtime`
+release it pins — and on the next `cds watch` these exist that did not before:
 
 | | |
 |---|---|
@@ -71,6 +71,20 @@ next `cds watch` these exist that did not before:
 Your own `server.js`, if you have one, is not touched. Nothing is generated
 into your repository, and there are no frontend files to serve.
 
+::: info Coming from the package `cap2ui5`
+Up to 0.2.0 the plugin was the unscoped package `cap2ui5`, which is withdrawn
+from npm. A project that has it swaps it:
+
+```bash
+npm rm cap2ui5 && npm add @cap2ui5/cds-plugin
+```
+
+and its app modules import `@cap2ui5/cds-plugin` instead of `cap2ui5`.
+Everything else keeps its name: the configuration `cds.requires.cap2ui5`,
+`cds add cap2ui5`, `npx cap2ui5 abap2js`, the entity `cap2ui5.Drafts` and the
+log `[cap2ui5]`.
+:::
+
 ## 2. Your first app
 
 One file in `srv/apps/` — the directory the plugin scans. It does not exist
@@ -85,7 +99,7 @@ yet in a new project:
 
 ```js
 // srv/apps/hello.js
-import { defineApp } from "cap2ui5";
+import { defineApp } from "@cap2ui5/cds-plugin";
 
 defineApp("HELLO", class {
   name  = "";
@@ -113,14 +127,14 @@ defineApp("HELLO", class {
 
 ::: warning `import`, not `require` — in this project
 `cds init --nodejs` creates an **ES module** project (`"type": "module"` in
-`package.json`), so a `.js` file there must `import`. A `require("cap2ui5")`
+`package.json`), so a `.js` file there must `import`. A `require("@cap2ui5/cds-plugin")`
 in it does not fail on its own line: it fails the **whole runtime boot** —
 the log says `[cap2ui5] runtime failed to boot: ReferenceError: require is not
 defined in ES module scope`, and every roundtrip, for every app, answers 500
 "roundtrip failed".
 
 In a CommonJS project (no `"type": "module"`), or in a file ending in `.cjs`,
-`const { defineApp } = require("cap2ui5")` is correct and works the same way.
+`const { defineApp } = require("@cap2ui5/cds-plugin")` is correct and works the same way.
 The examples on this site use `import`, because that is what `cds init` gives
 you.
 :::
@@ -209,7 +223,7 @@ step 1 — save it as `srv/apps/books.js`, next to `hello.js`:
 ```js
 // srv/apps/books.js
 import cds from "@sap/cds";
-import { defineApp, t } from "cap2ui5";
+import { defineApp, t } from "@cap2ui5/cds-plugin";
 
 const { SELECT } = cds.ql;
 
@@ -271,6 +285,24 @@ Open it: five books. Search for `Raven` and one row is left, with a toast
 - **Column names are UPPERCASE in the view** — `{TITLE}`, not `{title}`. The
   model carries field names uppercase; see [Data Binding](./data-binding#tables).
 
+## The samples
+
+abap2UI5's samples are a package too, `@cap2ui5/samples` — every sample a
+cap2UI5 app, translated from its ABAP original line for line. Add it to the
+project as a devDependency:
+
+```bash
+npm add -D @cap2ui5/samples
+cds watch
+```
+
+The startup lines now list every sample beside `HELLO` and `BOOKS`, each under
+its ABAP class name. As a devDependency the samples are there in development
+only; a production start leaves them out. How a package brings apps is in
+[Project Structure](./project-structure#apps-from-a-package), the list of
+samples in the [cap2UI5/samples](https://github.com/cap2UI5/samples)
+repository.
+
 ## What is in the database
 
 `cds watch` runs on an **in-memory SQLite** and deploys every table at each
diff --git a/docs/guide/lifecycle.md b/docs/guide/lifecycle.md
index c2175e9..22c2fc8 100644
--- a/docs/guide/lifecycle.md
+++ b/docs/guide/lifecycle.md
@@ -4,7 +4,7 @@ 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
-import { defineApp } from "cap2ui5";
+import { defineApp } from "@cap2ui5/cds-plugin";
 
 defineApp("ZCL_HELLO", class {
   name = "";
diff --git a/docs/guide/migration-from-abap2ui5.md b/docs/guide/migration-from-abap2ui5.md
index e826e06..2f965fd 100644
--- a/docs/guide/migration-from-abap2ui5.md
+++ b/docs/guide/migration-from-abap2ui5.md
@@ -33,7 +33,7 @@ ENDMETHOD.
 
 ```js
 // cap2UI5
-import { defineApp } from "cap2ui5";
+import { defineApp } from "@cap2ui5/cds-plugin";
 
 defineApp("ZCL_MY_APP", class {
   name = "";
diff --git a/docs/guide/persistence.md b/docs/guide/persistence.md
index 8204cf1..f7beb1c 100644
--- a/docs/guide/persistence.md
+++ b/docs/guide/persistence.md
@@ -113,7 +113,7 @@ start:
 ```
 [cds] - loaded model from 2 file(s):
   srv/cat-service.cds
-  node_modules/cap2ui5/index.cds
+  node_modules/@cap2ui5/cds-plugin/index.cds
 [cds] - connect to db > sqlite { url: ':memory:' }
 ```
 
diff --git a/docs/guide/project-structure.md b/docs/guide/project-structure.md
index e5cbf5d..691b731 100644
--- a/docs/guide/project-structure.md
+++ b/docs/guide/project-structure.md
@@ -19,7 +19,7 @@ my-project/
 │   │   ├── hello.js
 │   │   └── books.js
 │   └── server.js           # optional, and NOT touched by the plugin
-└── package.json            # "cap2ui5": "^x.y.z"
+└── package.json            # "@cap2ui5/cds-plugin": "^x.y.z"
 ```
 
 `examples/bookshop` in the [cap2UI5 repository](https://github.com/cap2UI5/cap2UI5)
@@ -36,7 +36,7 @@ that gives you:
 | `cap2ui5.Drafts` | a CDS entity contributed through `package.json#cds.requires`, so `cds deploy` creates it next to your own tables |
 
 None of this appears in your working tree. There is nothing to regenerate, no
-vendored folder, no sync pipeline. Upgrading is `npm update cap2ui5`.
+vendored folder, no sync pipeline. Upgrading is `npm update @cap2ui5/cds-plugin`.
 
 ## `srv/apps/` — the one directory that is yours
 
@@ -46,7 +46,7 @@ more than once.
 
 ```js
 // srv/apps/pick.js — two apps in one file is fine
-import { defineApp } from "cap2ui5";
+import { defineApp } from "@cap2ui5/cds-plugin";
 
 defineApp("ZCL_PICK",     class { /* … */ });
 defineApp("ZCL_PICK_ONE", class { /* … */ });
@@ -63,14 +63,42 @@ To put apps somewhere else, point the plugin at it:
 
 See [Configuration](../reference/configuration) for the rest of the knobs.
 
+## Apps from a package
+
+A dependency can bring apps of its own, and they run beside the project's —
+the way abap2UI5's samples run in the system they are pulled into.
+`@cap2ui5/samples` is one such package:
+
+```bash
+npm add -D @cap2ui5/samples
+```
+
+A package says where its app modules are in its `package.json`, and names the
+plugin as a peer dependency, so that its apps and the project's run on the
+same one:
+
+```json
+{
+  "cap2ui5": { "apps": "srv/apps" },
+  "peerDependencies": { "@cap2ui5/cds-plugin": "^0.3.0" }
+}
+```
+
+The plugin finds such packages the way CAP finds its plugins: among the
+project's `dependencies`, and outside production among its `devDependencies`
+too — so `npm add -D` brings a package's apps to development only. They load
+after the project's own apps, and the log names every package it loaded apps
+from. An app whose name the project already uses stays the project's, with a
+warning.
+
 ## Where the framework actually lives
 
 In `node_modules`, in two packages, and you own neither:
 
 | | |
 |---|---|
-| `cap2ui5` | the plugin — about 1,050 lines in 0.1.0, of which about 640 are code. `cds-plugin.js`, `index.cds`, `index.js`, `lib/` |
-| `@abap2ui5/node-runtime` | abap2UI5 itself: upstream's ABAP, downported and transpiled over open-abap, with the UI5 frontend embedded in the page its GET answers with. `cap2ui5` pins one exact release |
+| `@cap2ui5/cds-plugin` | the plugin — about 1,050 lines in 0.1.0, of which about 640 are code. `cds-plugin.js`, `index.cds`, `index.js`, `lib/` |
+| `@abap2ui5/node-runtime` | abap2UI5 itself: upstream's ABAP, downported and transpiled over open-abap, with the UI5 frontend embedded in the page its GET answers with. the plugin pins one exact release |
 
 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
diff --git a/docs/guide/roadmap.md b/docs/guide/roadmap.md
index 17e5334..273ea8a 100644
--- a/docs/guide/roadmap.md
+++ b/docs/guide/roadmap.md
@@ -66,7 +66,7 @@ background pages may still carry the port's mechanics; if a page contradicts
 ## What's next
 
 **Drop the approuter exception.** Once abap2UI5/abap2UI5#2802 is in an
-upstream release, pin `cap2ui5` to it, and the route CAP generates works
+upstream release, pin the plugin to it, and the route CAP generates works
 unchanged.
 
 **Grow the facade where use shows it is needed** — driven by real apps rather
diff --git a/docs/guide/troubleshooting.md b/docs/guide/troubleshooting.md
index 6cf31d0..952f225 100644
--- a/docs/guide/troubleshooting.md
+++ b/docs/guide/troubleshooting.md
@@ -87,9 +87,9 @@ startup lines:
 
 The project is an **ES module project** (`"type": "module"` in
 `package.json`, which is what `cds init --nodejs` creates), and an app file in
-it uses `require("cap2ui5")`. The plugin imports the apps as part of booting
+it uses `require("@cap2ui5/cds-plugin")`. The plugin imports the apps as part of booting
 the runtime, so one such file fails the boot, and the route has nothing to
-answer with. Write `import { defineApp } from "cap2ui5"` instead — or rename
+answer with. Write `import { defineApp } from "@cap2ui5/cds-plugin"` instead — or rename
 the file to `.cjs`, where `require` stays valid.
 
 ## The draft cannot be restored
diff --git a/docs/guide/user-exit.md b/docs/guide/user-exit.md
index 8594ee7..85b8852 100644
--- a/docs/guide/user-exit.md
+++ b/docs/guide/user-exit.md
@@ -9,7 +9,7 @@ A project has **one**, registered with `defineExit`:
 
 ```js
 // srv/apps/exit.js
-import { defineExit } from "cap2ui5";
+import { defineExit } from "@cap2ui5/cds-plugin";
 
 defineExit({
   onPage(cfg, ctx) {                 // the bootstrap page, once per page load
diff --git a/docs/guide/what-is-cap2ui5.md b/docs/guide/what-is-cap2ui5.md
index b9f3922..180337e 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 `manifest.json`, no second build pipeline. One file in `srv/apps/` is one app, and `npm i cap2ui5` is the whole installation.
+**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 add @cap2ui5/cds-plugin` 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).
 
@@ -62,7 +62,7 @@ A cap2UI5 app is **a single JavaScript class**, registered with `defineApp`:
 
 ```js
 // srv/apps/hello.js
-import { defineApp } from "cap2ui5";
+import { defineApp } from "@cap2ui5/cds-plugin";
 
 defineApp("ZCL_HELLO", class {
 
diff --git a/docs/guide/where-it-comes-from.md b/docs/guide/where-it-comes-from.md
index a671429..e1a1f9a 100644
--- a/docs/guide/where-it-comes-from.md
+++ b/docs/guide/where-it-comes-from.md
@@ -90,7 +90,7 @@ The decisions, and the measurements behind them, are recorded in the plugin
 repository's [`docs/adr/`](https://github.com/cap2UI5/cap2UI5/tree/main/docs/adr).
 The port's repositories — the transpiler with its conformance gate, and the
 three that generated the application and the playground — are archived or being
-archived. Nothing consumes their output any more: `cap2ui5` depends on
+archived. Nothing consumes their output any more: `@cap2ui5/cds-plugin` depends on
 `@abap2ui5/node-runtime` from npm, which abap2UI5 builds itself.
 
 ## Why the ABAP names remain
diff --git a/docs/index.md b/docs/index.md
index 136d818..446bbf9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -23,7 +23,7 @@ features:
   - title: One dependency, no scaffolding
     icon: 🔌
     details: >-
-      npm i cap2ui5 is the whole installation. The roundtrip route, whose
+      npm add @cap2ui5/cds-plugin is the whole installation. The roundtrip route, whose
       page embeds the UI5 frontend, and the cap2ui5.Drafts entity arrive
       through cds-plugin.js — your
       own server.js is untouched, and nothing is generated into your repository.
diff --git a/docs/reference/configuration.md b/docs/reference/configuration.md
index 1cfe4d2..5eb43c7 100644
--- a/docs/reference/configuration.md
+++ b/docs/reference/configuration.md
@@ -22,7 +22,7 @@ These ship in the plugin's own `package.json` and apply until you override one:
 
 | 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 |
+| `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 of its own. Apps a dependency brings come on top — see [Apps from a package](../guide/project-structure#apps-from-a-package) |
 | `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. A GET on a route answers with the page that embeds the whole UI5 frontend — there is no separate static route to configure |
 
@@ -81,8 +81,8 @@ run behind it under `xsuaa` and `ias` and not only under `mocked`.
 
 ## The runtime
 
-`cap2ui5` depends on `@abap2ui5/node-runtime` **pinned exactly** — `1.145.0`
-for `cap2ui5` 0.1.0 — so `npm install cap2ui5` already gives you one known
+`@cap2ui5/cds-plugin` depends on `@abap2ui5/node-runtime` **pinned exactly** — `1.145.0`
+for 0.3.0 — so `npm add @cap2ui5/cds-plugin` already gives you one known
 runtime release. There is nothing to add to your own `package.json`.
 
 The plugin resolves the runtime from **your project** (`cds.root`) first and
@@ -105,7 +105,7 @@ exit, registered with `defineExit`:
 
 ```js
 // srv/apps/exit.js
-import { defineExit } from "cap2ui5";
+import { defineExit } from "@cap2ui5/cds-plugin";
 
 defineExit({
   onPage(cfg, ctx) { cfg.theme = "sap_horizon_dark"; },
diff --git a/docs/reference/deployment.md b/docs/reference/deployment.md
index e991f70..6fce5bc 100644
--- a/docs/reference/deployment.md
+++ b/docs/reference/deployment.md
@@ -37,15 +37,15 @@ then `cds deploy` once. `cap2ui5.Drafts` is created along with your own tables.
 | **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** | `cap2ui5` pins `@abap2ui5/node-runtime` exactly (`1.145.0` for 0.1.0). Commit your `package-lock.json` and a redeploy installs the same release |
+| **The runtime** | `@cap2ui5/cds-plugin` pins `@abap2ui5/node-runtime` exactly (`1.145.0` for 0.3.0). Commit your `package-lock.json` and a redeploy installs the same release |
 
 ## Pin the plugin
 
 ```json
-{ "dependencies": { "cap2ui5": "^0.1.0" } }
+{ "dependencies": { "@cap2ui5/cds-plugin": "^0.3.0" } }
 ```
 
-`cap2ui5` is on npm, and it depends on one exact `@abap2ui5/node-runtime`
+`@cap2ui5/cds-plugin` is on npm, and it depends on one exact `@abap2ui5/node-runtime`
 release, so backend, UI5 frontend and wire version move only when the plugin
 version does. Nothing else needs pinning.
 
@@ -101,7 +101,7 @@ With that route **every roundtrip is refused**. `@sap/approuter` requires an
 authenticated route whose `csrfProtection` is not `false`, and answers
 `403` with `x-csrf-token: Required` otherwise (read in approuter 23.0.0,
 `lib/middleware/xsrf-token-handler.js`). The abap2UI5 frontend up to and
-including runtime `1.145.0` — the release `cap2ui5` 0.1.0 pins — sends no
+including runtime `1.145.0` — the release `@cap2ui5/cds-plugin` 0.3.0 pins — sends no
 such token. The first page loads, because it is a GET; the first click fails.
 
 What works today is a route for the roundtrip path **in front of** the
@@ -133,7 +133,7 @@ use this route.
 ::: info Pending upstream: abap2UI5/abap2UI5#2802
 That pull request teaches the frontend the standard `X-CSRF-Token`
 fetch-and-send handshake. It was merged on 2026-09-27, after the release
-`cap2ui5` pins, and no abap2UI5 release carries it yet. Once `cap2ui5` pins a
+the plugin pins, and no abap2UI5 release carries it yet. Once the plugin pins a
 runtime release that does, the extra route can go and the generated catch-all works as
 it is. Until then, keep the route above.
 :::
diff --git a/scripts/verify-refs.mjs b/scripts/verify-refs.mjs
index 1956d0b..ae14b2a 100644
--- a/scripts/verify-refs.mjs
+++ b/scripts/verify-refs.mjs
@@ -26,7 +26,7 @@
  * 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
+ *     ids `?app_start=` may name, for what `require("@cap2ui5/cds-plugin")` 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
@@ -50,16 +50,18 @@
  *      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")` or `import { … } from "cap2ui5"` in a
- *      FENCED CODE BLOCK names only what the package actually exports, and
- *      a "cap2ui5/<sub>" specifier lands on a file that exists. Stale
- *      "abap2UI5/…" — the port's package, which no longer exists — is
- *      reported by name, in either form.
+ *   4. every `require("@cap2ui5/cds-plugin")` or `import { … } from
+ *      "@cap2ui5/cds-plugin"` in a FENCED CODE BLOCK names only what the
+ *      package actually exports, and a "@cap2ui5/cds-plugin/<sub>" specifier
+ *      lands on a file that exists. Two dead packages are reported by name,
+ *      in either form: "abap2UI5/…", the port's package, and "cap2ui5", the
+ *      plugin's name up to 0.2.0, withdrawn from npm.
  *   5. every plugin option named as `cds.cap2ui5.<key>` is a key the plugin
  *      really defines, every three-part release number (1.x.y) is the runtime
  *      release the checkout pins or an allowlisted historical number, and a
- *      `"cap2ui5": "^x.y.z"` a page tells a reader to write is a range the
- *      plugin's own version actually falls in.
+ *      `"@cap2ui5/cds-plugin": "^x.y.z"` a page tells a reader to write is a
+ *      range the plugin's own version actually falls in (and a dependency on
+ *      the withdrawn `"cap2ui5"` is reported whatever its range).
  *
  * 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
@@ -141,7 +143,7 @@ if (haveApp) {
   }
 }
 
-/** what `require("cap2ui5")` hands back — read from the package, not guessed */
+/** what `require("@cap2ui5/cds-plugin")` hands back — read from the package, not guessed */
 const PLUGIN_EXPORTS = (() => {
   if (!haveApp) return null;
   const idx = path.join(APP, "plugin", "index.js");
@@ -201,7 +203,7 @@ const PINNED_RELEASE = (() => {
 })();
 
 /* The PLUGIN's own version, for the same reason one level down. A deployment
- * page telling a reader to pin `"cap2ui5": "^0.1.0"` is a claim about a
+ * page telling a reader to pin `"cap2ui5": "^0.1.0"` (the name then) is a claim about a
  * package that has to exist in that range - and it did not: the package
  * carried the placeholder 0.0.0 for as long as the page said ^0.1.0, so a
  * reader copying the line would have asked for a version npm could not
@@ -213,14 +215,17 @@ const PLUGIN_VERSION = (() => {
     return JSON.parse(fs.readFileSync(path.join(APP, PLUGIN_SOURCE), "utf8")).version ?? null;
   } catch { return null; }
 })();
-const CAP2UI5_DEP_RE = /"cap2ui5"\s*:\s*"[~^]?(\d+\.\d+)\.[\dx]+"/g;
+const CAP2UI5_DEP_RE = /"@cap2ui5\/cds-plugin"\s*:\s*"[~^]?(\d+\.\d+)\.[\dx]+"/g;
+// The unscoped package `cap2ui5` was withdrawn from npm with 0.3.0 - a
+// dependency on it is a line a reader cannot install, whatever its range.
+const WITHDRAWN_DEP_RE = /"cap2ui5"\s*:\s*"[~^]?\d/g;
 const minor = (v) => String(v).split(".").slice(0, 2).join(".");
 
 if (LIST) {
   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(`@cap2ui5/cds-plugin 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"}`);
   console.log(`plugin version: ${PLUGIN_VERSION ?? "NOT FOUND"}`);
@@ -256,17 +261,21 @@ const RELEASE_RE = /\b1\.\d{2,3}\.\d+\b/g;
 // `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("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;
+// require("@cap2ui5/cds-plugin"), require("@cap2ui5/cds-plugin/lib/…"), and two
+// dead packages: the port's `abap2UI5` and the plugin's own old name `cap2ui5`,
+// withdrawn from npm with 0.3.0.
+const PKG = "@cap2ui5/cds-plugin";
+const REQUIRE_RE = /require\(\s*["'`](@cap2ui5\/cds-plugin|cap2ui5|abap2UI5)(?:\/([^"'`]+))?["'`]\s*\)/gi;
+// `const { defineApp, t } = require("@cap2ui5/cds-plugin")` — the names, not just the path
+const DESTRUCTURE_RE = /(?:const|let|var)\s*\{([^}]*)\}\s*=\s*require\(\s*["'`]@cap2ui5\/cds-plugin["'`]\s*\)/g;
 // The same two claims in ES module form. `cds init --nodejs` makes an ES
 // module project, where a require() in an app file fails the whole runtime
 // boot — so the examples import, and an import line is the claim a reader
-// copies. `import { a, b as c } from "cap2ui5"` names what must be exported;
-// `import x from "cap2ui5/<sub>"` (any form) must land on a file.
-const IMPORT_RE = /\bimport\s+(?:[^"'`;]*?\s+from\s+)?["'`](cap2ui5|abap2UI5)(?:\/([^"'`]+))?["'`]/gi;
-const IMPORT_NAMES_RE = /\bimport\s*\{([^}]*)\}\s*from\s*["'`]cap2ui5["'`]/g;
+// copies. `import { a, b as c } from "@cap2ui5/cds-plugin"` names what must be
+// exported; `import x from "@cap2ui5/cds-plugin/<sub>"` (any form) must land on
+// a file.
+const IMPORT_RE = /\bimport\s+(?:[^"'`;]*?\s+from\s+)?["'`](@cap2ui5\/cds-plugin|cap2ui5|abap2UI5)(?:\/([^"'`]+))?["'`]/gi;
+const IMPORT_NAMES_RE = /\bimport\s*\{([^}]*)\}\s*from\s*["'`]@cap2ui5\/cds-plugin["'`]/g;
 // `cds.cap2ui5.apps`, `cap2ui5.routes` 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.
@@ -304,11 +313,16 @@ for (const file of markdownFiles(DOCS)) {
     if (PLUGIN_VERSION) {
       for (const m of line.matchAll(CAP2UI5_DEP_RE)) {
         if (m[1] === minor(PLUGIN_VERSION) || IGNORE.has(`cap2ui5@${m[1]}`)) continue;
-        add(file, n, `tells a reader to depend on cap2ui5 ${m[1]}.x, but the package `
+        add(file, n, `tells a reader to depend on ${PKG} ${m[1]}.x, but the package `
           + `is ${PLUGIN_VERSION} (${PLUGIN_SOURCE}) - nothing would resolve in that range`);
       }
     }
 
+    for (const m of line.matchAll(WITHDRAWN_DEP_RE)) {
+      add(file, n, `tells a reader to depend on "cap2ui5", which was withdrawn from npm `
+        + `- the package is "${PKG}"`);
+    }
+
     // release numbers are claims wherever they stand, prose or example
     if (PINNED_RELEASE) {
       for (const m of line.matchAll(RELEASE_RE)) {
@@ -337,7 +351,12 @@ for (const file of markdownFiles(DOCS)) {
         if (IGNORE.has(spec.toLowerCase())) continue;
         if (pkg.toLowerCase() === "abap2ui5") {
           add(file, n, `${how} "${spec}" is the RETIRED port package - the plugin is `
-            + `"cap2ui5", and the framework's own classes are not importable`);
+            + `"${PKG}", and the framework's own classes are not importable`);
+          continue;
+        }
+        if (pkg.toLowerCase() === "cap2ui5") {
+          add(file, n, `${how} "${spec}" is the plugin's OLD name, withdrawn from npm - `
+            + `the package is "${PKG}"`);
           continue;
         }
         if (!haveApp || !sub) continue;                  // bare require checked below
@@ -355,7 +374,7 @@ for (const file of markdownFiles(DOCS)) {
         for (const raw of list.split(",")) {
           const name = raw.split(alias)[0].trim();
           if (!name || PLUGIN_EXPORTS.has(name) || IGNORE.has(name.toLowerCase())) continue;
-          add(file, n, `${how} from "cap2ui5" names ${name}, which the package does not export `
+          add(file, n, `${how} from "${PKG}" names ${name}, which the package does not export `
             + `(it exports ${[...PLUGIN_EXPORTS].join(", ")})`);
         }
       }