@verentis/cli 0.2.3 → 0.2.5

package/README.md

@@ -10,6 +10,21 @@ The Verentis CLI is three tools in one:
 npm install -g @verentis/cli
 ```
 
+## Staying up to date
+
+The CLI checks the npm registry for a newer release at most once a day (in the background, so it never
+slows a command down) and prints a one-line notice when one is available. Update in place with:
+
+```bash
+verentis update            # install the latest published version
+verentis update --check    # just report whether a newer version exists
+verentis update --to 0.3.0 # install a specific version
+```
+
+`update` detects your global package manager (npm/pnpm/yarn/bun). Silence the notice with
+`VERENTIS_NO_UPDATE_CHECK=1` (it is also skipped in CI, on non-interactive output, and with `--json`).
+Point `VERENTIS_UPDATE_REGISTRY` at a mirror if you install from a private registry.
+
 ## Sign in
 
 ```bash
@@ -116,10 +131,39 @@ verentis validate engine.yaml                          # manifest checks before
 
 `dev run` writes `.verentis/context.json` (mode 600 — contains a short-lived token; git-ignore `.verentis/`).
 
+### Standalone application launch
+
+Applications that can open without a selected file opt in through their manifest:
+
+```yaml
+spec:
+  entry: https://app.example.com
+  launch:
+    enabled: true
+    entry-point: home
+    pinnable: true
+  entry-points:
+    - id: home
+      route: /workspace
+```
+
+`verentis init <name> --kind application` includes a commented launch template.
+`verentis validate` verifies that `launch` is an object, `pinnable` is used only
+with `enabled`, the selected entry-point id exists, and the launch resolves to
+an absolute HTTP(S) iframe URL. Omit `spec.launch` for contextual file handlers
+and headless apps.
+
+At runtime this is still an iframe launch: the SDK receives
+`context.surface === 'workspace'`, a resolved entry point, and no file context.
+
 ## Marketplace publishing
 
 ```bash
 verentis publisher create --name acme --display-name "Acme Inc."
+verentis publisher create --name acme --display-name "Acme Inc." --logo ./brand/logo.png
+verentis publisher update --description "Tools for data teams" --website https://acme.example
+verentis publisher logo set ./brand/logo.svg
+verentis publisher logo remove
 verentis keygen                        # Ed25519 signing key + register public half
 verentis init my-app --kind application
 verentis pack                          # signed .vpkg (--encrypt seals the payload)
@@ -139,15 +183,53 @@ verentis yank my-app 1.0.3
 
 Published versions are `Submitted` for moderation; once approved the marketplace countersigns them and they become installable.
 
+### Marketplace presentation
+
+Applications, execution engines and bundles can add an optional top-level `marketplace` block:
+
+```yaml
+marketplace:
+  logo: ./marketplace/logo.png
+  hero:
+    source: ./marketplace/hero.webp
+    alt: Abstract blue background behind the package title
+  images:
+    - source: ./marketplace/editor.png
+      alt: Editor showing a completed workflow
+      caption: Optional visible caption
+  readme: ./README.md
+  changelog: ./CHANGELOG.md
+  assets:
+    - "marketplace/docs/**/*.{png,jpg,jpeg,webp,svg}"
+```
+
+Direct references are relative to the manifest directory and may not escape it. Hero and gallery `alt`
+text is required for accessibility. Images must be PNG, JPEG, WebP or passive SVG content. Logos are
+limited to 1 MiB; hero and gallery images are limited to 5 MiB each; galleries have at most 8 images.
+The hero does not count toward that gallery limit, but it does count toward the 25 MiB total for all
+unique presentation images. README and changelog Markdown files are each limited to 1 MiB.
+`verentis validate` checks these paths, formats and limits before publishing.
+
 ## The `.vpkg` format
 
-A gzip tarball: `manifest.yaml` + `files/**` payload + `.verentis/` metadata (package.yaml, sha256 digests, DSSE signatures). Manifest references like `./schemas/x.json` resolve against `files/` — and against the children of the installed manifest node after installation. See the platform docs (`marketplace/packaging`) for the full specification.
+A gzip tarball: `manifest.yaml` + `files/**` payload + optional plaintext `catalog/**` presentation
+content + `.verentis/` metadata (package.yaml, sha256 digests, DSSE signatures). Manifest references
+like `./schemas/x.json` resolve against `files/` — and against the children of the installed manifest
+node after installation. See the platform docs (`marketplace/packaging`) for the full specification.
 
 Packing behaviour:
 - `packaging.files` globs select the payload; without them, applications automatically include every `./…` schema `source` referenced by the manifest.
-- Digests cover every payload entry; the registry rejects tampered packages.
+- `pack --env production` merges `environments/production.yaml`; `--overlay <path>` selects an
+  explicit overlay, and `--version <version>` overrides the packed manifest version. `validate`
+  accepts the same overlay selectors.
+- Marketplace files are selected independently of `packaging.files` and written to deterministic,
+  content-addressed `catalog/assets/**` and `catalog/docs/**` entries described by
+  `catalog/index.json` (schema version 1).
+- Digests and signatures cover the manifest, every payload entry and every catalog entry; the registry rejects tampered packages.
 - With a configured signing key the digests document is DSSE-signed (Ed25519). Publishers with registered keys **must** sign uploads.
-- `pack --encrypt` seals the payload (AES-256-GCM, X25519 key wrapping per recipient — always including the `platform` escrow recipient so Verentis.Node can serve member reads).
+- `pack --encrypt` seals only `files/**` (AES-256-GCM, X25519 key wrapping per recipient — always
+  including the `platform` escrow recipient so Verentis.Node can serve member reads). `catalog/**`
+  remains plaintext so the marketplace can render the approved presentation.
 
 ## Output & scripting