docs(cli): the README states the global flags and the os plugin group that the built os registers

.changeset/21310-cli-readme-flags.md

@@ -0,0 +1,15 @@
+---
+'@objectstack/cli': patch
+---
+
+The published README now describes the `os` that ships. Five things it said were false.
+
+Clause-②: no
+
+- **Short flags.** The README listed `-v, --version` and `-h, --help` as global options. `os -v` and `os -h` exit 2 with `command -v not found` / `command -h not found`, because only `--version` and `--help` are registered. It now lists `--version` and `--help` alone and says there is no short form. `-v` already belongs to commands of their own: it is `--verbose` on `os dev`, `os serve`, `os start` and `os doctor`, and `--version` on `os package publish` and `os package install`.
+- **The `os plugin` group.** The README said there is no `os plugin` command group. `os plugin build`, `os plugin sign` and `os plugin publish` are registered, and the README now lists them. It also says the group has no `install`, and that `os plugin` is a different thing from `os plugins`, which is not a command.
+- **Two command rows.** `os init [name]` creates a new directory of that name when a name is given, so it no longer says "in the current directory" for every case. `os dev` restarts the server after each rebuild, so it no longer says "with hot reload".
+- **Cloud credentials and flags.** The README said every cloud command takes its credentials from `os cloud login` or from `--token` / `OS_CLOUD_API_KEY` and `--server` / `OS_CLOUD_URL`. That holds only for `os package publish` and `os plugin publish`. `os environments list`, `show`, `create`, `bind` and `switch` take `-u, --url` (env `OS_CLOUD_URL`) and `-t, --token` (env `OS_TOKEN`), and otherwise use the `os login` session in `~/.objectstack/credentials.json` — never the `os cloud login` session. With only `os cloud login` done they exit 1 with `Authentication required`. The README now has a per-command table, and its typical publish flow says so at the `os environments create` step.
+- **`os serve --ui`.** The README said it enables "Studio UI". It enables the bundled Console portal at `/_console/` when `@object-ui/console` is installed, which is what `os serve --help` says.
+
+**What changes for an operator.** Nothing at runtime. No command, flag, environment variable, exit code or help page changes.

packages/cli/README.md

@@ -39,8 +39,8 @@ os compile
 
 | Command | Description |
 |---------|-------------|
-| `os init [name]` | Initialize a new ObjectStack project in the current directory |
-| `os dev [package]` | Start development mode with hot reload |
+| `os init [name]` | Initialize a new ObjectStack project — in a new directory of that name when `name` is given, otherwise in the current directory |
+| `os dev [package]` | Start development mode — watch sources, rebuild the artifact, and restart the server on change |
 | `os serve [config]` | Start the ObjectStack server with plugin auto-detection |
 
 ### Build & Validate
@@ -81,9 +81,8 @@ and keep loading through their barrel `index.ts`.
 ### Cloud — publish & install
 
 Push a locally-built package to ObjectStack Cloud and (optionally) install it
-into one of your environments in a single command. Credentials and server URL
-come from `os cloud login` (stored in `~/.objectstack/cloud.json`) or the
-`--token` / `OS_CLOUD_API_KEY` and `--server` / `OS_CLOUD_URL` flags.
+into one of your environments in a single command. The commands below do not
+share one session or one flag spelling — see [Credentials and server URL](#credentials-and-server-url).
 
 | Command | Description |
 |---------|-------------|
@@ -97,22 +96,54 @@ Typical flow (build → publish → install into an environment, seeding sample
 
 ```bash
 os compile                                 # → dist/objectstack.json
-os cloud login                             # one-time, stores the cloud session
-os environments create --org "$ORG" --name "Dev" --activate
+os cloud login                             # one-time; the session os package publish reads
+os environments create --org "$ORG" --name "Dev" --activate   # does NOT read that session — see below
 os package publish --env <env-id> --install --seed-sample-data
 ```
 
+`os environments create` does not use the session `os cloud login` stored: give
+it `--url` and `--token` (or `OS_CLOUD_URL` / `OS_TOKEN`), or an `os login`
+session. Without either it exits 1 with `Authentication required`.
+
 `os package publish` registers a `sys_package` (keyed by a reverse-domain
 `--manifest-id`, derived from the artifact when omitted), snapshots the
 artifact as a new `--version`, and — with `--env <id> --install` — installs
 that version into the environment. Useful flags: `--visibility private|org|
 marketplace`, `--note`, and for marketplace listings `--submit` (request
-review) or `--auto-approve` (platform admins only). Set `OS_CLOUD_URL` (or
-`--server`) to target a non-default control plane, e.g. a staging cloud.
+review) or `--auto-approve` (platform admins only). Set `OS_CLOUD_URL` to
+target a non-default control plane, e.g. a staging cloud. `os cloud login`,
+`os package publish` and `os environments` read it; the flag is `--server` on
+`os package publish` and `--url` on the other two.
+
+#### Credentials and server URL
+
+Two stored sessions exist, and each command authenticates with one of them:
+
+| Command | Server URL | Token | Stored session |
+|---------|------------|-------|-------------------------|
+| `os cloud login` | `-u, --url` (env `OS_CLOUD_URL`, default `https://cloud.objectos.ai`) | none — `-e, --email` / `-p, --password`, or the browser device flow | writes `~/.objectstack/cloud.json` |
+| `os cloud whoami` / `os cloud logout` | — | — | reads / deletes `~/.objectstack/cloud.json` |
+| `os package publish`, `os plugin publish` | `-s, --server` (env `OS_CLOUD_URL`); else the URL in `cloud.json`; else `https://cloud.objectos.ai` | `-t, --token` (env `OS_CLOUD_API_KEY`, then `OS_TOKEN`) | `~/.objectstack/cloud.json` — the `os cloud login` session |
+| `os environments list` / `show` / `create` / `bind` / `switch` | `-u, --url` (env `OS_CLOUD_URL`); else the URL in `credentials.json`; else `http://localhost:3000` | `-t, --token` (env `OS_TOKEN`) | `~/.objectstack/credentials.json` — the `os login` session, **not** `os cloud login`'s |
+
+`os package install` is not a cloud command: it installs into a running runtime
+(`-r, --runtime`, env `OS_RUNTIME_URL`, default `http://localhost:3000`) and signs
+in there with `--email` / `--password` (env `OS_RUNTIME_EMAIL` /
+`OS_RUNTIME_PASSWORD`).
 
 ### Plugin Management
 
-Runtime plugins (declared in `objectstack.config.ts` `plugins`) are loaded automatically by `os serve` / `os dev`. There is no `os plugin` command group in v1; runtime plugins are bundled into the build artifact. To distribute a build, publish it as a package with `os package publish` (see [Cloud — publish & install](#cloud--publish--install)); the `os environments bind <id> --artifact dist/objectstack.json` path still binds an artifact directly into an environment without going through the package registry.
+Runtime plugins (declared in `objectstack.config.ts` `plugins`) are loaded automatically by `os serve` / `os dev`. Runtime plugins are bundled into the build artifact. To distribute a build, publish it as a package with `os package publish` (see [Cloud — publish & install](#cloud--publish--install)); the `os environments bind <id> --artifact dist/objectstack.json` path still binds an artifact directly into an environment without going through the package registry.
+
+A code-bearing plugin — a directory carrying an `objectstack.plugin.json` manifest — is packaged and shipped through the `os plugin` command group (ADR-0025 §3.4, build → sign → publish):
+
+| Command | Description |
+|---------|-------------|
+| `os plugin build [dir]` | Compile a plugin into a signed-ready `.osplugin` artifact (`--entry`, `--out`, `--minify`) |
+| `os plugin sign <artifact> --key <pem>` | Sign a built `.osplugin` with a publisher Ed25519 key, writing a detached `<artifact>.sig` |
+| `os plugin publish [artifact]` | Publish a signed `.osplugin` to ObjectStack Cloud |
+
+The group has no `install`: ADR-0025 records the code-plugin install half (download, verify, materialize, load) as not yet implemented. `os plugin` (singular) is unrelated to `os plugins` (plural), oclif's plugin manager, which this package does not ship — see [`os plugins` and `os help`](#os-plugins-and-os-help-not-commands).
 
 ### Quality
 
@@ -176,8 +207,13 @@ Common variables: `OS_DATABASE_URL`, `OS_DATABASE_DRIVER`,
 
 ### Global
 
-- `-v, --version` — Show version number
-- `-h, --help` — Show help
+- `--version` — Show version number
+- `--help` — Show help (`os --help`, or `os <command> --help` for one command)
+
+There are no short forms: `os -h` and `os -v` exit 2 with `command -h not found` /
+`command -v not found`. `-v` is a command's own flag instead — `--verbose` on `os dev`,
+`os serve`, `os start` and `os doctor`, `--version <semver>` on `os package publish` and
+`os package install`.
 
 ### `os init`
 
@@ -200,7 +236,7 @@ Common variables: `OS_DATABASE_URL`, `OS_DATABASE_DRIVER`,
 
 - `-p, --port <port>` — Server port. Resolution: `--port` › `$OS_PORT` › `$PORT` › `3000`. With `--dev` a busy port auto-hops to the next free one; in production mode it's a hard error (never silently drifts).
 - `--dev` — Run in development mode (load devPlugins, pretty logging)
-- `--ui` — Enable Studio UI
+- `--ui` — Enable the bundled Console portal at `/_console/` when `@object-ui/console` is installed (default: true)
 - `--no-server` — Skip starting HTTP server plugin
 
 ### `os generate`