@xemahq/xema 0.13.0 → 0.15.0

package/README.md

@@ -83,9 +83,33 @@ 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:
+
+```bash
+xema installation plan                    # deterministic redacted change plan
+xema installation apply --detach           # reconcile through the same launcher as `xema up`
+xema installation status                  # desired vs applied vs observed drift
+xema installation support-bundle          # redacted JSON + SHA-256 integrity manifest
+```
+
+Destructive transitions are refused unless explicitly reviewed and authorized
+with `--allow-destructive`; rejected identity/schema transitions and currently
+unsupported profiles remain fail-fast. Last-applied state is atomically stored
+under `~/.xema/installations/<installation-id>/`, while secret values are
+resolved before source or deployment side effects and are never persisted in
+plans or support bundles.
+
 ### Topology — `xema.config.yaml`
 
 The launcher reads an optional `xema.config.yaml` (or `~/.xema/config.yaml`)
@@ -96,17 +120,24 @@ provide the URL), or `disabled`:
 ```yaml
 edition: oss
 infra:
-  postgres:    { mode: managed }
-  redis:       { mode: managed }
-  etcd:        { mode: managed }
-  keycloak:    { mode: external, url: https://sso.corp/realms/xema, realm: xema }
+  postgres:
+    {
+      mode: external,
+      url: postgresql://xema@db.corp:5432,
+      secretRef: postgres-password,
+    }
+  redis: { mode: managed }
+  etcd: { mode: managed }
+  keycloak: { mode: external, url: https://sso.corp/realms/xema, realm: xema }
   objectStore: { mode: external, url: https://s3.corp }
-  search:      { mode: managed }
-  temporal:    { mode: managed }
+  search: { mode: managed }
+  temporal: { mode: managed }
+secrets:
+  postgres-password: { from: env, env: XEMA_POSTGRES_PASSWORD }
 app:
-  substrate: container        # container | native
-  include: [ all ]            # all | <tier> | [service ...]
-  features: []                # curated capability bundles
+  substrate: container # container | native
+  include: [all] # all | default | minimal | <tier> | [service ...]
+  features: [] # curated capability bundles
   web: { enabled: true }
 ```
 
@@ -114,14 +145,41 @@ app:
   (`imageRef:contentHash`) and runs them on a shared network, after bringing up
   and bootstrapping managed infra — works without a monorepo checkout.
 - **`native`**: runs services as host processes against a built monorepo (the
-  contributor inner loop). Equivalent: `xema serve --profile single-instance`.
+  contributor inner loop). Equivalent: `xema serve --substrate single-instance`.
 - **`helm`**: deploys to Kubernetes via `helm upgrade --install` (the appliance /
-  cluster target). Equivalent: `xema serve --profile 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
 degradation.
 
+Managed local PostgreSQL and object-store credentials are generated uniquely
+per installation and retained under
+`~/.xema/installations/<installation-id>/managed-local-credentials.json` with
+directory mode `0700` and file mode `0600`. Repeated and concurrent launches
+reuse the same credentials; values are not written to config or command
+arguments. `xema down` preserves them with the data volumes, while
+`xema down --purge` removes both. A named volume created by an older CLI with
+fixed development credentials fails fast and requires that explicit purge
+before its first launch with credential custody.
+
+External PostgreSQL credentials are never defaulted or persisted in the
+endpoint URL. Put the username in the URL and source the password through
+`secretRef`. A referenced secret must be declared under
+`secrets` and resolve from `env`, `file`, or an interactive masked `prompt`
+before Xema creates any deployment resources.
+
+Secret names that are valid environment-variable names are intentionally
+injected into every native/container service in the launch. Use a non-environment
+name such as `postgres-password` for launcher-only `secretRef` values. File
+sources must be regular, non-symlink files with no group/other permissions
+(`0600` or stricter); relative paths resolve from the directory containing
+`xema.config.yaml`. The Helm substrate does not accept launcher-resolved
+secrets: configure Kubernetes Secrets through each service chart instead.
+
 ### Realtime dev
 
 Xema always runs the `distributed` model: every service is its own process and
@@ -143,8 +201,8 @@ lone service still boots a correct graph:
 
 ```bash
 xema dev agent-session-api memory-api     # native: just these two (+ prerequisites)
-xema up   --only app-runtime-api          # container: one service (+ prerequisites)
-xema serve --profile cluster --only audit-log-api
+xema up   --only app-platform-api          # container: one service (+ prerequisites)
+xema serve --substrate cluster --only audit-log-api
 ```
 
 ### Biome sources — pull biomes from many origins
@@ -155,22 +213,22 @@ each with its own auth — declared in a `sources:` block:
 
 ```yaml
 sources:
-  - name: workspace                       # local working tree (monorepo): always wins
+  - name: workspace # local working tree (monorepo): always wins
     kind: workspace
-  - name: cultivars                       # a pinned edition lock
+  - name: cultivars # a pinned edition lock
     kind: distribution
     edition: cultivars
-  - name: acme                            # a client's OWN biome git repo (private)
+  - name: acme # a client's OWN biome git repo (private)
     kind: git
     url: https://github.com/acme/xema-biomes.git
     ref: v2.1.0
-    authTokenEnv: GIT_TOKEN_ACME          # env-var NAME, never the secret
+    authTokenEnv: GIT_TOKEN_ACME # env-var NAME, never the secret
 ```
 
 Precedence: **`workspace` > other sources (declared order) > base distribution**.
 In a monorepo checkout the workspace source always wins, so `xema dev` runs your
 local edits with **no publish** and **no token** required. Tokens for private
-sources are referenced by env-var *name* (the `biome-fetcher` convention) and
+sources are referenced by env-var _name_ (the `biome-fetcher` convention) and
 resolved from the environment or a git-ignored `~/.xema/credentials.env` — never
 inlined in config. `npm`/`oci` sources are install-time (the `xema biome install`
 path); `workspace`/`distribution`/`git` boot directly from `xema up`/`dev`.
@@ -189,8 +247,8 @@ Sources discover biomes by walking for `xema-biome.json` — a repo may hold ONE
 biome at its root or MANY nested; both are valid layouts of the **same
 standard**. A biome is a directory with a manifest at its root; its services
 live at the manifest-declared `ships.apis[].path` (convention `./api/<name>`).
-What a biome *does* (services, skills, capabilities, agents) is wholly open —
-only the bundle *shape* is standardized, so every author builds the same way and
+What a biome _does_ (services, skills, capabilities, agents) is wholly open —
+only the bundle _shape_ is standardized, so every author builds the same way and
 any source resolves the same way.
 
 ## Compose a distribution — `xema dist build`
@@ -202,6 +260,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
@@ -209,6 +268,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: