@xemahq/xema 0.14.0 → 0.15.1

package/README.md

@@ -46,6 +46,24 @@ lifecycle (restart, health, resource limits) to the substrate beneath it
 npm i -g @xemahq/xema
 ```
 
+### Client mode vs developer mode
+
+A fresh install starts in **client mode**, for people who USE a Xema deployment:
+`login`, `apply`, `plan`, `run`, `shell`, `objects`, `status`, `logs`.
+
+The commands that stand a platform up locally — **`up`, `dev`, `serve`**, which
+the rest of this document is largely about — are the platform contributor's inner
+loop. They are fully functional in client mode but **hidden from `xema --help`**,
+so following the sections below without turning developer mode on gives you
+working commands that `--help` never mentions:
+
+```bash
+xema config set dev on     # or: export XEMA_DEV=1
+```
+
+`xema --help` states this in both modes, and `xema config get` explains which
+input decided it.
+
 ## Scaffold a config — `xema init`
 
 Generate a `xema.config.yaml` tailored to your scenario. Run it with no flags for
@@ -83,9 +101,16 @@ xema up --all              # everything, including the frontend
 xema up --detach           # leave container workloads running and return
 xema down                  # stop everything (xema down --purge also deletes data volumes)
 xema status                # show launcher-owned workloads + health
-xema logs <service> -f     # stream a service's logs
+xema logs <service> -f     # stream a launcher-owned workload's logs
 ```
 
+Every verb works against the configured substrate — one verb set, pluggable
+target. `xema logs` streams from a launcher-owned container (`docker logs`) on
+the container substrate, from the owned release's Deployment
+(`kubectl logs deploy/<service>`) on the helm substrate, and on native points
+at the foreground `xema up` / `xema dev` console (that is where native
+services log).
+
 The launcher and automation use the same compiled desired state. The
 installation command group exposes that lifecycle directly:
 
@@ -140,7 +165,10 @@ app:
 - **`native`**: runs services as host processes against a built monorepo (the
   contributor inner loop). Equivalent: `xema serve --substrate single-instance`.
 - **`helm`**: deploys to Kubernetes via `helm upgrade --install` (the appliance /
-  cluster target). Equivalent: `xema serve --substrate appliance`.
+  cluster target). Equivalent: `xema serve --substrate appliance`. `xema
+  status` lists the installation's releases, `xema logs` streams them through
+  `kubectl` (or the `k3s kubectl` applet a k3s appliance ships), and `xema
+  down` uninstalls exactly the releases this installation owns.
 
 `xema up` fails fast on a missing required secret, an unreachable `external`
 dependency, or a disabled-but-mandatory infra component — never a silent
@@ -250,6 +278,7 @@ operator rules), then written as a distribution + a launch config:
 
 ```bash
 xema dist build --id acme-platform --base oss \
+  --platform linux/amd64 \
   --git acme=https://github.com/acme/xema-biomes.git \
   --source local=./my-biomes \
   --config-out acme.config.yaml
@@ -257,6 +286,16 @@ xema dist build --id acme-platform --base oss \
 #   --no-allow-third-party rejects non-first-party biomes (default: allowed)
 ```
 
+`--platform` is **required and has no default**. It declares the OCI platform(s)
+every runtime image of your distribution must be published for — the value
+delivery verifies against the real registry manifest. Pass it repeatedly or
+comma-separated (`--platform linux/amd64 --platform linux/arm64`, or
+`--platform linux/amd64,linux/arm64`); the closed set is `linux/amd64` and
+`linux/arm64`. It is not inherited from `--base`: a base edition's
+`distribution.lock.json` does not carry the platform set, and guessing one would
+silently commit an appliance composition to an architecture its hardware cannot
+run. State what your images are actually built for.
+
 It writes `~/.xema/distributions/<id>/{xema-distribution.json,distribution.lock.json}`
 (the composed recipe + resolved record) and, with `--config-out`, a
 `xema.config.yaml` (base edition + your sources). Then: