vortex-cli 6.4.0__tar.gz → 7.0.0__tar.gz

{vortex_cli-6.4.0 → vortex_cli-7.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: vortex_cli
-Version: 6.4.0
+Version: 7.0.0
 Summary: Vortex CLI
 Author-email: Jordan Amos <jordan.amos@gmail.com>
 License: MIT License
@@ -99,8 +99,8 @@ While it is possible to use without it, this software has been purposefully desi
    password = mypassword ; Optional - Prompted at runtime if not provided
    ; Optional
    puakma_db_conn_id = 13 ; Optional - discovered from the server when omitted
-   backend = soap ; 'soap' (default) or 'gateway' - see The Agent Gateway below
-   gateway_path = vortex/gateway.pma ; only used when backend = gateway
+   backend = soap ; 'soap' (default) or 'gateway' - see The Gateway Backend below
+   gateway_path = vortex/gateway.pma ; only used when backend = gateway - blank (or not installed on the server) = webdesign directly
    clone_with_resources = html,css,js ; resources with these extensions are always cloned - 'clone --get-resources' still clones ALL resources
    lib_path = ; optional extra jars to add to the classpath (the server's own jars are downloaded automatically - see 'vortex libs')
    workspace_folders = ~/dev/shared,notes ; extra folders to mount in the generated .code-workspace files. Relative paths resolve against the workspace root. Under [DEFAULT] they are added to every workspace; here they apply to this server's workspace (and the global one)
@@ -108,33 +108,47 @@ While it is possible to use without it, this software has been purposefully desi
    java_environment_name = JavaSE-17 ; Java Execution Environment name https://docs.osgi.org/reference/eenames.html
    ```
 
-## Upgrading to 6.3
-
-- **`vortex push` only uploads what changed.** On a `backend = gateway` server the push first
-  reads the server's element hashes and skips every file that already matches - a full-app push
-  that used to re-send (and journal) hundreds of identical files now sends the few that differ.
-  `--all` restores the old push-everything behaviour; `backend = soap` still pushes everything.
-- **Uploads run concurrently** - up to `--jobs N` elements at once (default 8; `-j 1` is the
-  old one-at-a-time push). A Java element's source and class still go in that order, and a
-  failed source stops that element's class from being uploaded over it.
-- **`push --name` prefers an exact match.** Previously `--name dashboard` also pushed a
-  `Dashboard` element; now the case-insensitive match only applies when nothing matches exactly.
+## Upgrading to 7.0
+
+7.0 replaces the gateway backend with a pass-through to webdesign and removes commands.
+
+`backend = gateway` still means the **`vortex/gateway`** Puakma application at `gateway_path`
+(default `vortex/gateway.pma`), but that application has been replaced: it is now a
+permission wrapper around `system/webdesign`'s `vortex` JSON API, reached at
+`{gateway_path}/api/...`. The old gateway's own endpoints (the undo journal, element hashes,
+windowed downloads, status, agenda, render) are gone. `backend = soap` is unchanged.
+
+- **The gateway is optional.** On a server where nothing answers at `gateway_path` (or it is
+  blank), `backend = gateway` talks to `system/webdesign`'s `vortex` API directly. A server
+  still running the OLD gateway has no `api` action there, so it is treated the same way -
+  install the new gateway to get its role checks back.
+- **Removed commands:** `push`, `pull`, `undo`, `status`, `agenda` (and
+  `config --show-server`), `render`, and `compile` with its `build` alias. The gateway keeps no
+  server-side journal and no element hashes, so there is no undo and no incremental pull (a
+  fresh `vortex clone` replaces it). On a gateway server **`vortex watch` is the deploy
+  path**; the `.class` files it uploads come from the IDE's build into `zbin/`.
+- **`vortex import` works on `backend = gateway`** (the gateway's `import` route): it always
+  creates a new application, and its scheduled actions start disabled.
+- **`vortex list`** keeps the Version column but loses Last Modified, and on a gateway
+  server it cannot hide inactive applications (the inventory has no `DisableApp` flag).
+- **`vortex db --sql`** runs through the application that owns the connection, so that
+  application must be cloned. There is no server dry run for `--update`.
+- **Roles** are `Admin`, `GatewayDesignRead`, `GatewayDesignWrite`, `GatewayDBRead`,
+  `GatewayDBWrite` and `GatewaySystem` (`GatewayLogRead` is gone - the log needs
+  `GatewaySystem`). `vortex config --check-gateway` shows which ones you hold.
 
 ## Upgrading to 6.0
 
 6.0 is additive - **the default behaviour is unchanged**. Every server keeps using the SOAP
 designer path unless you opt it in.
 
-- **New optional backend: the agent gateway.** Set `backend = gateway` on a server definition
-  to route supported operations through the `vortex/gateway` Puakma application instead of
-  SOAPDesigner. The default is `backend = soap`, which never contacts the gateway at all - so
-  servers without it installed are unaffected. See [The Agent Gateway](#the-agent-gateway).
-- **New commands**: `status`, `agenda`, `push`, `pull`, `render` and `undo`. `agenda`, `pull`,
-  `render` and `undo` require `backend = gateway`; `status` and `push` fall back to the
-  existing paths.
-- **`puakma_db_conn_id` is now optional.** When omitted it is discovered from the server on
-  both backends. Existing configs that set it explicitly keep working.
-- **`vortex list` gains Version and Last Modified columns** when run against a gateway server.
+- **New optional backend: the gateway.** Set `backend = gateway` on a server definition to
+  route operations through a gateway Puakma application instead of SOAPDesigner. The default
+  is `backend = soap`, which never contacts the gateway at all - so servers without it
+  installed are unaffected. See [The Gateway Backend](#the-gateway-backend).
+- **`puakma_db_conn_id` is now optional.** When omitted it is discovered from the server
+  (over SOAP - nothing on the gateway backend needs it). Existing configs that set it
+  explicitly keep working.
 
 ## Upgrading to 5.0
 
@@ -147,9 +161,6 @@ designer path unless you opt it in.
 - **`vortex watch` now watches every cloned app across all servers** and uploads each change to
   the server it was cloned from. Use `--server` for the old single-server behaviour, and mark
   production definitions `protected = true` so they are never watched by accident.
-- **`vortex compile` now uses the Eclipse compiler (ecj)** - the same compiler the VS Code Java
-  extension uses - downloaded once per workspace. `--javac PATH` forces javac. `compile
-  --upload` is now a full refresh (uploads every compiled class, not just changed ones).
 - `find`, `grep` and `vortex list --local` now search all cloned apps unless `--server` is
   given, and ID-taking commands infer their server from local clones (see below).
 
@@ -166,19 +177,9 @@ For a full list of commands see `--help`.
 - `watch`: Watch the workspace for changes to Design Objects and automatically upload them to the server each app was cloned from. Watches all servers at once unless `--server` is given.
 - `clean`: Delete the locally cloned Puakma Application directories in the workspace.
   Takes optional `APP_ID`s to clean just those clones (all of the server's, if none are
-  given). Deletes immediately and needs no network - there is no undo. With `--check`
-  it first asks the server for its design element hashes and refuses to delete a clone
-  holding local changes the server doesn't have, naming each file; that needs a
-  reachable `backend=gateway` server, and a clone it can't verify is refused rather
-  than silently deleted.
-- `config`: View and manage configuration. `--check-gateway` reports the agent gateway negotiation and which gateway roles your identity holds.
+  given). Deletes immediately and needs no network - there is no undo.
+- `config`: View and manage configuration. `--check-gateway` shows the server's backend and, for `backend = gateway`, who the gateway thinks you are and which gateway roles you hold.
 - `log`: View the server log.
-- `status`: Show the server status - via the agent gateway when available, otherwise the raw console `status` output.
-- `agenda`: List every scheduled action with its decoded schedule, last and next run, and whether it is overdue (read-only, gateway only).
-- `push`: Upload local design files (source, compiled classes, pages, resources) to the server without a watch session - journaled and deploy-confirmed when routed via the gateway. On a gateway server only files whose content differs from the server's are uploaded (compared by the server's element hashes; `--all` pushes everything), and elements upload concurrently (`--jobs N`, default 8) while each Java element's source always lands before its class. `--name` matches exactly first, case-insensitively only when nothing matches exactly.
-- `pull`: Refresh cloned applications in place via the gateway's incremental sync - only elements changed since the last sync are downloaded. Refuses to overwrite locally modified files without `--force`.
-- `render`: Render a PAGE server-side as your identity and print it (or `--out FILE`) - see a change without a browser login (gateway only).
-- `undo`: The server-side undo journal. No arguments lists journal entries; with an entry id it dry-runs a restore, and `--confirm` writes the journaled version back (gateway only).
 - `find`: Find Design Objects of cloned applications by name.
 - `grep`: Search the contents of cloned Design Objects using a Regular Expression.
 - `new`: Create new Design Objects, Applications, or Keywords. Use `--update <ID>` to update instead. Run without flags to launch an interactive wizard.
@@ -187,16 +188,16 @@ For a full list of commands see `--help`.
 - `delete`: Delete Design Objects by ID.
 - `db`: Interact with Database Connections. Accepts `--server`/`-s` like other commands for one-off queries against another server.
 - `schema`: Manage the Puakma data dictionary (PMATABLE/ATTRIBUTE): record table/column definitions and print the DDL to run by hand. Never executes DDL.
-- `compile` (or `build`): Compile an application's Java Design Objects into `zbin/` using the Eclipse compiler (ecj).
 - `libs`: Show or refresh the per-server Java library cache (each server's `puakma.jar` and shared libraries, downloaded from the server itself).
 - `docs`: Open the Tornado Server Blackbook.
-- `execute`: Execute a command on the server.
+- `execute`: Execute a command on the server (e.g. `vortex execute status`).
+- `export` / `import`: Export applications as `.pmx` files, and create an application from one.
 
 ### Keyword values and secrets
 
 Keywords are an application's live configuration, and in practice they hold credentials in
 cleartext - API keys, passwords, vendor secrets, signing keys. `vortex keyword` therefore
-**redacts by default**, following the same precedent as `vortex config --show-server`:
+**redacts by default**:
 
 ```
 vortex keyword 9                      # list every Keyword (secrets redacted)
@@ -222,8 +223,9 @@ vortex keyword 9 --reveal             # print secret values in full
 
 An update always prints the prior value beside the new one and waits for `[Y/y]` on stdin
 before writing; on a `protected = true` server the server name must also be typed back
-(`--yes` does not bypass that). The write uses the gateway's keyword upsert, so it never
-inserts a duplicate KEYWORD row.
+(`--yes` does not bypass that). The write is an upsert done by vortex: it never inserts a
+duplicate KEYWORD row, and it folds any existing duplicates of the name into the oldest one.
+`keyword` needs `backend = gateway`.
 
 Reading does **not** require the application to be cloned locally - diagnosing a bad
 configuration value should not depend on having a working copy.
@@ -268,7 +270,7 @@ apps from several servers at the same time:
   server it was cloned from. One terminal, all servers. Log lines are prefixed
   with the server name (e.g. `[dev] Upload DATA of ...`). Use `--server` to
   watch a single server only.
-- Commands that take IDs (`clone`, `export`, `compile`, `delete`, `copy`) work
+- Commands that take IDs (`clone`, `export`, `delete`, `copy`) work
   out the server on their own: IDs can be qualified as `SERVER:ID`
   (e.g. `vortex export dev:123`), and unqualified IDs are resolved against your
   locally cloned apps. If an ID exists on more than one server, vortex stops
@@ -279,11 +281,8 @@ apps from several servers at the same time:
   a time, and cloning or cleaning is refused while a watch is running (stop
   the watch first - a clone under a running watch adds directories the
   watcher doesn't know about). Finer-grained commands that alter design
-  elements (`delete`, `copy`, `new`, `compile --upload`) lock
-  per-application: they are refused for apps a watch is watching and run
-  concurrently otherwise. `push` and `pull` lock the same way - per
-  application, never workspace-wide - so they can run against one app while
-  a watch holds others.
+  elements (`delete`, `copy`, `new`) lock per-application: they are refused
+  for apps a watch is watching and run concurrently otherwise.
 - In VS Code, app folders are listed in per-server blocks (`dev: group/app`,
   ...) with the server's jars on the Java classpath (see them in the Java
   Projects view). vscode-java's classpath settings are
@@ -321,29 +320,31 @@ Set `protected = true` on a server definition (e.g. production) to make it
 hard to change by accident:
 
 - Write operations (`delete`, `copy`, `new`, `import`, `db --update`,
-  `execute`, `schema` changes, `compile --upload`) require the server name to
+  `execute`, `keyword --values`, `schema` changes) require the server name to
   be typed back to continue. This is deliberately **not** bypassed by `--yes`.
 - `vortex watch` skips protected servers unless `--include-protected` is
   given, so saving a file can never hot-deploy to production by accident.
 
-### The Agent Gateway
-
-The **agent gateway** is a JSON API served by the Puakma server itself - a companion Puakma
-application (`vortex/gateway`) that you deploy to a server. Where SOAPDesigner is a transport,
-the gateway is a transport *plus* the guarantees only server-side code can enforce:
-
-- **Role-gated operations** - every endpoint requires one declared application role, checked on
-  the server. Roles are rows in *that server's* copy of the app, so a grant on dev confers
-  nothing on prod.
-- **An undo journal** - destructive design writes snapshot the element first (bytes, metadata,
-  design params). `vortex undo` lists those snapshots and restores any of them; deleted
-  elements are recreatable.
-- **Dry-run by default** - `undo`, element deletes, single-statement DML and whole-server
-  refresh do nothing without an explicit confirmation.
-- **Deploy confirmation** - writes reply with the sizes and hashes of what is really on the
-  server now.
-- **Database guardrails** - the Puakma system database is unreachable through it, and DDL is
-  never executed, only generated as text.
+### The Gateway Backend
+
+`backend = gateway` sends every request through **the gateway** - a small Puakma application
+(`vortex/gateway`) that you deploy to a server - or, where it is not installed, straight to
+`system/webdesign` (see below). The gateway is `system/webdesign`'s `vortex`
+JSON API at a different address: a request to `https://<host>/vortex/gateway.pma/api/<path>`
+is webdesign's `/system/webdesign.pma/vortex/<path>` - same path, method, body and reply -
+with three things added in front of it:
+
+- **Role checks.** Every route needs one role, checked on the server: `GatewayDesignRead`
+  (inventory, clone, keywords, libraries), `GatewayDesignWrite` (design, keyword and
+  dictionary writes), `GatewayDBRead` (`SELECT`, connections), `GatewayDBWrite` (`INSERT`,
+  `UPDATE`, `DELETE`), `GatewaySystem` (log, console, export, import) and `Admin` (everything,
+  including creating applications). Write implies read. Roles are rows in *that server's*
+  copy of the app, so a grant on dev confers nothing on prod. A route the gateway does not map
+  is refused.
+- **Guards.** The gateway never addresses the Puakma system database, never lets an id from
+  one application be used under another, and runs exactly one `SELECT`/`INSERT`/`UPDATE`/`DELETE` per SQL request (DDL, `WITH`, and any
+  `;` are refused).
+- **Its own routes** for the server log, console, `.pmx` export/import and `whoami`.
 
 Opt in per server:
 
@@ -354,67 +355,70 @@ backend = gateway            ; default is 'soap', which never contacts the gatew
 ; gateway_path = vortex/gateway.pma   (this is the default)
 ```
 
-With `backend = gateway`, `watch`/`push` uploads, `delete`, `log`, `status`, `db`, `execute`
-and the journal commands route through it, and `agenda`, `pull`, `render` and `undo` become
-available. Everything the gateway does not offer goes to the **webdesign vortex API** (the
-JSON action served by `system/webdesign`) - see [SOAP-free on backend = gateway](#soap-free-on-backend--gateway).
-A `backend = gateway` server never talks to SOAPDesigner at all. Check what you are talking
-to and what you may do:
+A `backend = gateway` server never talks to SOAPDesigner. Check what you are talking to and
+what you may do:
 
 ```
 vortex config --check-gateway -s dev
 ```
 
-**There is no fallback in either direction, by design.** A gateway refusal (for example, your
-identity lacks the required role) is reported as an error - vortex never quietly retries the
-same operation over SOAP, because that would let anyone with SOAP access bypass every role,
-journal and guardrail above. Likewise `backend = soap` never contacts the gateway. The one
-deliberate exception is the gateway application's *own* deployments, which never go through
-the gateway (webdesign on `backend = gateway`, SOAP on `backend = soap`) so that a broken
-gateway deploy never needs the gateway to fix itself.
+**The gateway is optional; it is a pass-through with role checks.** The first command that
+needs it asks the gateway's `whoami`, once per run:
+
+- **The gateway answers:** every request goes through it.
+- **Nothing is installed at `gateway_path`** (a plain HTTP 404), or `gateway_path` is blank:
+  every request goes straight to `system/webdesign`'s `vortex` API instead. That grants
+  nothing extra - webdesign's own access control still applies. The commands that exist
+  only in the gateway (`log`, `execute`, `import`) fail with a message saying they need it;
+  `export` uses webdesign's `ExportPMX` directly.
+- **The gateway is installed but says no or is down** (a refusal, a login page, a 5xx, a
+  timeout): that is an error, never a detour around it. A refusal names the code and, for a
+  missing role, the role.
+
+There is never a fallback to SOAP, and `backend = soap` never contacts the gateway. Platform
+applications (`system/*`, `vortex/*` - the gateway itself included - and `puakma`) are not
+special-cased: `GatewayDesignWrite` writes them like any other application, which is how the
+gateway is redeployed through itself.
 
-The gateway application is **not bundled with this CLI** - deploy it to a server with
-`vortex export` / `vortex import`, then run its `Setup` scheduled action. It ships its own
-`API.md`, `README.md` and `DECISIONS.md` as DOCUMENTATION design elements, so once installed
-the running server documents its own endpoints, roles and setup steps.
+There is **no undo**: the gateway keeps no journal of what a write replaced. Deletes and uploads
+are final.
+
+The gateway is **not bundled with this CLI** - deploy it to a server with `vortex export` /
+`vortex import` and grant its roles in webdesign's security UI. Its DOCUMENTATION element
+describes every route, role and refusal code.
 
 > **Note:** the gateway's roles are only a real boundary for an identity whose *sole* route to
 > the server is the gateway. Any identity that can reach `system/webdesign` or deploy code can
 > grant itself any role. Keep webdesign access for operators; agent identities should not have
 > it.
 
-### SOAP-free on `backend = gateway`
-
-SOAPDesigner is legacy. On a `backend = gateway` server the commands the gateway does not
-cover use the JSON API of `system/webdesign`'s `vortex` action instead - with the same
-credentials, and the webdesign app's own ACL. SOAP is used only when a server is explicitly
-`backend = soap`. The data dictionary (`schema`, `db --list/--schema`) is the exception that
-proves the rule: the gateway's `dictionary` endpoint runs that same webdesign `vortex` action
-server-side behind `GatewayDBRead`/`GatewayDBWrite`, so an agent identity with no webdesign
-access gets a clean role answer rather than a login page, and a change to `vortex.java`
-needs no change to the gateway.
-
-| Command | `backend = gateway` | `backend = soap` |
+| Command | `backend = gateway` (through the gateway, or webdesign directly without it) | `backend = soap` |
 |---|---|---|
-| `push`, `watch` (modify), `compile --upload` | gateway `upload` (journalled); the gateway app itself: webdesign `PUT design` | SOAP `uploadDesign` |
-| `watch` (create / delete) | webdesign `POST` / `DELETE design` | SOAP |
-| `delete` | gateway `delete` (journalled); the gateway app itself: webdesign | SOAP |
-| `copy`, `new object` | webdesign `POST`/`PUT design`, `PUT design/params` | SOAP |
-| `new app` | webdesign `POST vortex` | SOAP `saveApplication` |
-| `new keyword` | gateway `keyword` (upsert) | SOAP `saveKeyword` |
-| `keyword` (read) | gateway `download` (metadata window; `GatewayDesignRead`) | **unsupported** - SOAP has no keyword read call |
-| `keyword --values` (write) | gateway `keyword` (upsert) | **unsupported** |
-| `schema`, `db --list`, `db --schema` | gateway `dictionary` (webdesign's `database`/`table`/`column` routes run server-side; `GatewayDBRead`/`GatewayDBWrite`) | SOAP SQL + `savePuakma*` |
-| `export` | webdesign `ExportPMX` action | SOAP `downloadPmx` |
-| `import` | **still SOAP** - webdesign has no import route yet | SOAP `uploadPmx` |
-| `db --sql`, `list`, `log`, `execute`, `status`, `clone`, `pull` | gateway | SOAP |
-
-Where the webdesign API behaves differently from SOAP, the CLI compensates so the commands
+| `clone` | `GET {app}` - the whole application in one request | SOAP |
+| `list` | `GET` inventory | SOAP SQL |
+| `watch` (modify) | `GET` + `PUT {app}/design/{id}` | SOAP `uploadDesign` |
+| `watch` (create / delete), `copy`, `new object` | `POST`/`PUT`/`DELETE {app}/design`, `PUT design/params` | SOAP |
+| `delete` | `DELETE {app}/design/{id}` | SOAP |
+| `new app` | `POST` (Admin) | SOAP `saveApplication` |
+| `keyword`, `new keyword` | `{app}/keywords` routes; the upsert is done by vortex | read **unsupported** - SOAP has no keyword read call; `new keyword` SOAP `saveKeyword` |
+| `schema`, `db --list`, `db --schema` | `{app}/database/{conn}/table[/column]` routes | SOAP SQL + `savePuakma*` |
+| `db --sql` | `POST {app}/database/{conn}/sql` (the owning app must be cloned) | SOAP |
+| `log` | `GET logs` (needs the gateway) | SOAP SQL |
+| `execute` | `POST console` (needs the gateway) | SOAP |
+| `export` | `GET export` (webdesign `ExportPMX` without the gateway) | SOAP `downloadPmx` |
+| `import` | `POST import` (needs the gateway; always a new app; scheduled actions start disabled) | SOAP `uploadPmx` |
+| `libs` | `GET libraries`, `GET systemjar` | webdesign's `vortex` API directly |
+
+Where webdesign's API behaves differently from SOAP, the CLI compensates so the commands
 behave as they did. The differences that remain visible:
 
 - **Design element writes are whole-row.** The CLI reads the row back first and re-sends what
   it does not model (the other blob, `Options`), so a `DATA`-only upload never wipes source.
   One consequence: every write is one extra `GET`.
+- **A clone transfers every resource.** `GET {app}` has no filter, so `clone_with_resources`
+  and `--get-resources` only decide what is written to disk and kept in the manifest.
+- **A clone has no Java class version**, so `watch` does not check a `.class` file's version
+  against the server's on a gateway server.
 - **Renaming with `new object --update --name` does not rewrite references.** SOAP's
   `updateDesignObject` also updated design params in the app that referred to the old name;
   the webdesign route does not. Fix `OpenAction`/`ParentPage`-style params by hand after a rename.
@@ -423,16 +427,16 @@ behave as they did. The differences that remain visible:
   `savePuakmaAttribute2` had them). `--default`/`--position` are refused with a message;
   `--ref TABLE.COLUMN` records the table and warns. Updates leave existing values untouched.
   Extend `POST`/`PUT .../column` in webdesign's `vortex.java` to lift this.
+- **`db --sql` runs one statement and has no dry run.** Only a `SELECT` runs without
+  `--update`; row columns may come back in any order.
+- **`list` shows inactive applications** (the inventory has no `DisableApp` flag), and a group
+  clone skips only inherited applications.
 - **Every write flushes the application's design cache**, where SOAP flushed one element.
-- **No per-application `Developer` role check** - the webdesign app's ACL is the boundary. An
-  identity that can reach `system/webdesign` can edit every application through it.
 - **`db --list` orders by table name** (SOAP's `SELECT DISTINCT` had no order); `--schema`
   output is identical.
 - **Database-name resolution is app-scoped.** `schema`/`db --list` find the connection whose
   dictionary holds the tables (as SOAP did by `pmatable` count), asking locally cloned
   applications first and scanning the server inventory only if none of them has it.
-- **`import` remains SOAP** on every backend until webdesign gains a PMX import route
-  (`SaveImportPMX` is a multipart UI form, not an API).
 
 ### Interactive Wizards
 
@@ -466,49 +470,32 @@ vortex -y new object --name MyAction --app-id 10 --type action
 Note: `--yes` never bypasses the typed confirmation for servers marked
 `protected = true`.
 
-### Compiling Java Design Objects
-
-`vortex compile` (alias `build`) compiles an application's Java Design Objects into `zbin/`
-with the **Eclipse compiler (ecj)** - the same compiler the VS Code Java extension uses,
-downloaded once per workspace into `config/.tools/`. It runs via the `java` from `java_home`
-in the server config, then `$JAVA_HOME`, then `PATH`; `--release` is derived from the
-application's Java class version. ecj matters because Tornado loads each class from its own
-design element: `'$'` **classes (`Foo$1.class`) are never uploaded to the server**, and unlike
-javac, ecj compiles a `switch` over an enum into the class itself rather than a synthetic
-`Foo$1.class`. Classes that still produce `$` files (genuine anonymous/inner classes) are
-reported and **excluded from upload** - they would throw `NoClassDefFoundError` on the server.
-If ecj can't be downloaded (offline), javac is used with a warning; `--javac PATH` forces
-javac explicitly.
-
-```
-vortex compile              # compile all locally cloned apps for the server
-vortex compile 13           # compile one app
-vortex compile 13 --upload  # also upload ALL compiled classes (full server refresh)
-```
+### Java Design Objects and `zbin/`
 
-While `vortex watch` is running, `--upload` isn't needed: saving a Java source uploads the
-SOURCE, and the VS Code Java extension's incremental build (which **is** the Eclipse
-compiler, ecj - the same compiler `vortex compile` downloads) writes the class files into
-`zbin/`, where watch picks them up and uploads the DATA - always, even when the bytes are
-unchanged, so a source change is always paired with its class on the server. `'$'`
-nested-class files are never uploaded - a class compiled alongside `$` siblings is refused
-with an error since it would fail on the server.
-Use `vortex compile` for full-application rebuilds without the IDE.
+The server runs compiled classes, not source. While `vortex watch` is running, saving a Java
+source uploads the SOURCE, and the VS Code Java extension's incremental build (the Eclipse
+compiler) writes the class files into `zbin/`, where watch picks them up and uploads the
+DATA. It always does, even when the bytes are unchanged, so a source change is always paired
+with its class on the server. `'$'` nested-class files (`Foo$1.class`) are never uploaded - Tornado
+loads each class from its own design element - and a class compiled alongside `$` siblings is
+refused with an error, since it would fail on the server. Refactor anonymous/inner classes
+into top-level SHARED_CODE classes.
 
 ### Server-Provided Java Libraries
 
-Compilation and IDE IntelliSense need the Puakma framework jar and the server's shared
+The IDE's Java build and IntelliSense need the Puakma framework jar and the server's shared
 libraries on the classpath. Instead of maintaining local copies, vortex downloads them from
 each server's `webdesign` application (the `vortex` API's `systemjar` and `libraries`
-endpoints) and caches them per server under `<workspace>/<host>/.lib/`:
+endpoints - through the gateway on `backend = gateway` when it is installed, which needs
+`GatewayDesignRead`) and
+caches them per server under `<workspace>/<host>/.lib/`:
 
-- The cache is filled automatically the first time it's needed - on `clone`, `watch` and
-  `compile` - and never re-downloaded unless you ask.
+- The cache is filled automatically the first time it's needed - on `clone` and `watch` -
+  and never re-downloaded unless you ask.
 - `vortex libs` shows what's cached for each server; `vortex libs --refresh` re-downloads
   (add `-s <server>` for one server), e.g. after a server upgrade.
-- `javac` (via `vortex compile`) and each app folder's VS Code Java settings use the app's
-  own server's cached jars, so identical class names on different servers/versions never
-  cross-contaminate.
+- Each server's VS Code workspace (`vortex code -s <server>`) uses that server's own cached
+  jars, so identical class names on different servers/versions never cross-contaminate.
 - Servers whose `webdesign` app doesn't provide the `vortex` API yet fall back to the
   `puakma.jar` bundled with vortex-cli plus any `lib_path` entries, with a warning.
 - `vortex clean` keeps each host's `.lib` cache so the jars don't need
@@ -530,6 +517,6 @@ vortex schema mydb --ddl invoice    # print CREATE TABLE from the dictionary
 ```
 
 On a `backend = gateway` server the dictionary is reached through webdesign's vortex API via
-the gateway's `dictionary` endpoint (`GatewayDBRead` to read, `GatewayDBWrite` to change).
-That API cannot record `--default` or `--position` (refused) nor the column half of `--ref`
-(warned) - see [SOAP-free on backend = gateway](#soap-free-on-backend--gateway).
+the gateway (`GatewayDBRead` to read, `GatewayDesignWrite` to change - dictionary rows are design
+metadata; no DDL ever runs). That API cannot record `--default` or `--position` (refused) nor
+the column half of `--ref` (warned) - see [The Gateway Backend](#the-gateway-backend).