From a92f10b9f414614f14254cd9792998833820d6ff Mon Sep 17 00:00:00 2001 From: os-zhuang Date: Wed, 10 Jun 2026 20:08:13 +0500 Subject: [PATCH] docs(packages): install is an in-environment action, not a publish flag Follow-up to #20. The Installing table led with the CLI `os package publish --env --install` one-liner, which framed install as a publish-time flag. That's backwards: a person installs from inside the target environment's Marketplace (no env id, confirmed by their environment login). Lead with the Console marketplace path; demote `--env --install` to a clearly labelled CI shortcut. Co-Authored-By: Claude Opus 4.8 --- content/docs/build/packages.mdx | 13 +++++++++++-- 1 file changed, 11 insertions(+), 2 deletions(-) diff --git a/content/docs/build/packages.mdx b/content/docs/build/packages.mdx index baaf200..9ae6c40 100644 --- a/content/docs/build/packages.mdx +++ b/content/docs/build/packages.mdx @@ -112,13 +112,22 @@ the compiled `dist/objectstack.json` directly to the target install ## Installing +Installing is an **in-environment** action — distinct from publishing. You +publish a package once (to the catalog), then install it from *inside* the +target environment, where the install is confirmed and authorized by your +environment login. You never need to know an environment id to install. + | Path | How | |---|---| -| CLI (cloud-managed) | `os package publish --env --install [--seed-sample-data]` — publish a version and install it into a cloud environment in one step | -| Console | Marketplace tab → pick package → Install | +| Console (recommended) | Sign in to the environment → **Marketplace** → pick the package → **Install**. Installs into the current environment. | | REST | `POST /api/v1/marketplace/install-local` (body: `{ packageId, versionId? }`) | | Air-gapped | Mount the compiled `dist/objectstack.json` artifact (see [Air-gapped](/docs/deploy/air-gapped)) | +> **CI shortcut.** Pipelines that deploy to a *known* environment can publish +> and install in one step: `os package publish --env --install +> [--seed-sample-data]`. This is a convenience for automation, not the path a +> person uses — interactive installs happen in the environment's Marketplace. + Install merges the package's metadata into the live kernel, registers its objects with ObjectQL, and seeds initial data on first install — no restart needed. Cached installs are re-registered on the next boot,