@fabrika/provider-zerops 0.4.2 → 0.4.4

package/src/installation/guide.md

@@ -16,24 +16,72 @@ message that names the flag or the variable to set. Read the message: it names t
 
 **Ask the human for these first.** You cannot produce them, and each one blocks a later step:
 
-| What                                                                           | Needed at  |
-| ------------------------------------------------------------------------------ | ---------- |
-| A Zerops personal access token, generated in the Zerops GUI                    | step 1     |
-| A `gh` login allowed to create a repository in the organization that owns it   | step 3     |
-| The administrator's e-mail, and the human to open the enrollment URL           | step 2     |
-| For a PRIVATE application repository: the GitHub App connected in the console  | step 5     |
-| The fabrika release tag to install, for example `v0.4.2` (a branch is refused) | steps 1, 3 |
+| What                                                                                  | Needed at  |
+| ------------------------------------------------------------------------------------- | ---------- |
+| A Zerops PERSONAL access token of a client OWNER, generated in the Zerops GUI         | step 1     |
+| A verified Zerops account (credit topped up once); an unverified one owns ONE project | step 5     |
+| A `gh` login allowed to create a repository in the organization that owns it          | step 3     |
+| The administrator's e-mail address, and the human to open the enrollment URL          | step 2     |
+| For a PRIVATE application repository: the GitHub App connected in the console         | step 5     |
+| The fabrika release tag to install, for example `v0.4.3` (a branch is refused)        | steps 1, 3 |
+| The four decisions below                                                              | steps 1, 5 |
+
+Every namespace is a Zerops project of its own, so the first one fails with `clientProjectCountLimitExceededTopUp`
+on an unverified account (observed 2026-10-15).
 
 Also needed on the machine: [Bun](https://bun.sh) ≥ 1.3, `git`, `gh`, `curl` and `jq`.
 
+## Decisions: ask the human, with the prices
+
+Each choice trades price against stability, and two of them cannot be undone. Show the human this section
+and let them choose; do not pick for them. Prices are Zerops' list prices as of 2026-10-15
+([zerops.io/pricing](https://zerops.io/pricing)): a shared core $0.60, a dedicated core $6.00, RAM $3.00 per
+GB, disk $0.10 per GB and object storage $0.01 per GB, each per 30 days and billed per minute. A Lightweight
+project core is free (15 build hours, 100 GB egress); a Serious one is $10 (150 build hours, 3 TB egress, a
+highly available balancer). The figures below are the idle FLOOR. Every service scales up under load, to 8
+cores and 48 GB per container, and costs more while it does.
+
+**1. Platform tier** (`platform install --tier`, step 1). Cannot be changed later: a project's core package
+is upgrade-only, and the data services differ.
+
+| Tier              | What runs                                                                                                                                                                           | Idle floor | Fails when                                               |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- | -------------------------------------------------------- |
+| `light` (default) | Lightweight core. One single-node PostgreSQL (`oltp-hobby`) and one bucket shared by IAM, control and Operations; one container each.                                               | about $6   | any one container or the database is down: sign-in stops |
+| `standard`        | Serious core. HA PostgreSQL (3 nodes, `oltp-production`, dedicated CPU) for IAM and control; a second HA PostgreSQL and bucket for Operations; two containers of IAM and the proxy. | about $100 | survives the loss of one node of each                    |
+
+Most of `standard`'s price is the identity database's dedicated floor (about $72). `light` is right for an
+evaluation and a small fleet that tolerates an outage; `standard` for sign-in that must stay up.
+
+**2. Namespace preset** (`control namespaces create --preset`, step 5). A namespace is the Zerops project
+applications run in. Each one adds its own proxy, about $1.08.
+
+| Preset          | Where an application's database lives                                   | Use with                             |
+| --------------- | ----------------------------------------------------------------------- | ------------------------------------ |
+| `cheap`         | One shared single-node PostgreSQL in the namespace, about $1.45 for all | `fabrika.cheap.config.ts`            |
+| `mid` (default) | Each application imports its own database into the namespace            | `fabrika.config.ts`                  |
+| `full`          | The namespace belongs to ONE application (`--exclusive-app=<id>`)       | an application that must be isolated |
+
+**3. The application's database** (the application's `fabrika.config.ts`, before step 5). The example
+declares `postgresql:single@18` at `oltp-hobby`, about $1.45, plus its runtime from about $1.08 per
+container. `postgresql:ha@18` survives a node failure: about $11 at `oltp-staging` (shared CPU), about $72 at
+`oltp-production` (dedicated). Single to HA later means a new service and a data migration.
+
+**4. Namespace core package** (`--core-package=LIGHT|SERIOUS`, step 5). `LIGHT` is free and the default on
+every environment. `SERIOUS` adds $10 per namespace and a highly available balancer in front of its proxy,
+and it can never be downgraded again.
+
 ## Secrets: rules for an agent
 
 - Every credential is read from the ENVIRONMENT ONLY. No command takes one as a flag.
 - Never print a credential, never put one in a command line you echo, never commit one.
-- Keep each one in its own file with mode `0600` (`umask 077` first) and pass it as
-  `NAME="$(cat <file>)" fabrika …`. Check a file with `wc -c`, never with `cat`.
-- The provisioning key from step 1 is printed ONCE. Capture it from the output into its file at once.
-  The only other copies are in the `iam` and `control` service environments.
+- `platform install` writes every credential it creates to `--secrets-file`, mode `0600`, before it places
+  the first one. That file is the ONLY readable copy. Zerops stores them as sensitive variables and answers
+  `REDACTED` when they are read back, so never try to read a secret from the Zerops API, and never ask the
+  human for sudo mode to do it. Back the file up where the human keeps credentials.
+- Load the file in a subshell, so its integration token never replaces the personal one in your shell:
+  `( set -a && . <secrets file> && set +a && fabrika … )`.
+- Keep any other credential in its own `0600` file (`umask 077` first) and pass it as `NAME="$(cat <file>)"`.
+  Check a file with `wc -c`, never with `cat`.
 
 ## Step 0. Get the CLI at the release tag
 
@@ -49,60 +97,73 @@ cd fabrika-platform && bun install --frozen-lockfile
 In this guide, `fabrika` means `bun <clone>/packages/cli/src/index.ts`. Do not edit the clone: a dirty
 checkout is refused, and a local commit is not on GitHub, so namespaces cannot fetch it.
 
+Install a released tag, not a branch. Every application build fetches `@fabrika/check` at the version of the
+checkout, so `install` and `deploy` refuse a checkout whose version npm does not have yet: `this checkout is
+version X, which is not published yet`. A `main` between a release's version bump and its publish is such a
+checkout.
+
 ## Step 1. Install the platform
 
 ```bash
 export FABRIKA_ZEROPS_ACCESS_TOKEN="$(cat <personal token file>)"
 curl -s -H "Authorization: Bearer $FABRIKA_ZEROPS_ACCESS_TOKEN" \
-  https://api.app-prg1.zerops.io/api/rest/public/user/info | jq '.clientUserList[] | {clientId, name: .client.accountName}'
-fabrika platform install --provider=zerops --create-project --client-id=<clientId> --env=<name> --source-dir=. --yes > install.log 2>&1
+  https://api.app-prg1.zerops.io/api/rest/public/user/info | jq '{email, clients: [.clientUserList[] | {clientId, name: .client.accountName, role: .roleCode}]}'
+fabrika platform install --provider=zerops --create-project --client-id=<clientId> --env=<name> --tier=<light|standard> \
+  --secrets-file=<path outside the clone> --source-dir=. --yes > install.log 2>&1
 ```
 
-- Run it from the clone root. It runs for many minutes: it imports six services, builds the proxy once to
-  learn the public hosts, then deploys everything.
+- Check the token kind first. The `email` of a personal token is the person's address, and its `role` on the
+  client is `OWNER`. An `email` of `token-<id>@zerops.io` is an INTEGRATION token. The install refuses one before
+  it creates anything, because an integration token may not mint the token the control plane needs. Ask the
+  human for a personal token instead.
+- Run it from the clone root. It runs for many minutes: it imports the tier's services, builds the proxy
+  once to learn the public hosts, then deploys everything.
 - `--yes` is required when stdin is not a terminal.
-- Capture the key right away and keep the log away from anything that publishes it:
-  `grep -o 'FABRIKA_IAM_PROVISIONING_KEY=px_[A-Za-z0-9_-]*' install.log | cut -d= -f2 > provisioning.key`
+- `--secrets-file` names a NEW file outside the clone, for example `~/fabrika-<env>.secrets.env`. An existing
+  file is refused. The log prints no credential.
 - The project id is printed BEFORE the long wait. If the run is interrupted, re-run with
   `--project-id=<id>` instead of `--create-project`.
 - A project that already holds generated secrets is refused. Do not try to force it: a second bring-up
   over the same project would destroy the vault key. Start over in a new empty project.
 - The account must be in the default region, or set `FABRIKA_ZEROPS_API_URL` for every command.
 
-**Check.** The log ends with `✓ iam <host>`, the console origin and the provisioning key box. Write down
-the three hosts: IAM, console and Operations.
+**Check.** The log ends with the `Hand off` step: where the credentials are, `The console answers at
+https://<console host>`, and an `ADMIT YOURSELF` box that holds the step 2 command with `--iam-host` filled
+in. The secrets file exists with mode `0600`. The three hosts are printed earlier, right after pass 1, as
+`✓ iam <host>`, `✓ console <host>` and `✓ operations <host>`. Write them down.
 
 ## Step 2. Admit the first administrator
 
 ```bash
-FABRIKA_IAM_PROVISIONING_KEY="$(cat provisioning.key)" \
-  fabrika platform admin --provider=zerops --email=<address> --iam-host=<IAM host from step 1>
+( set -a && . <secrets file> && set +a && \
+  fabrika platform admin --provider=zerops --email=<address> --iam-host=<IAM host from step 1> )
 ```
 
-It prints one enrollment URL. The URL is a credential: give it to the human only, and do not log it. The
-human opens it, sets a password and signs in at the console origin. A re-run creates nothing new;
-`--reissue` replaces an enrollment that expired unopened.
+It prints one enrollment URL and the time it expires. Nothing is e-mailed: the installation has no mail
+service, so do not tell the human to wait for a message. The URL is a credential: give it to the human only,
+and do not log it. The human opens it, sets a password and signs in at the console origin.
+
+The URL is valid for ONE HOUR. Hand it over at once. A re-run creates nothing new: while the enrollment is
+unused it only reports that one is outstanding, and it never prints the URL again. To get a new URL, after
+expiry or after a lost one, run the same command with `--reissue`. It replaces the old enrollment, so the old
+URL stops working.
 
 ## Step 3. Create the sidecar repository
 
 The sidecar is a GitHub repository the operator owns. Its workflow runs `platform deploy` at the pinned tag.
 
-Read the integration token that step 1 minted. Never use the personal token here:
+Steps 4 and 5 do not depend on this step: the installation from step 1 already runs. The sidecar is what
+upgrades it later (step 6). Run this step before or after step 5. Only `platform upgrade` needs it.
 
-```bash
-A=https://api.app-prg1.zerops.io/api/rest/public
-H="Authorization: Bearer $FABRIKA_ZEROPS_ACCESS_TOKEN"
-control=$(curl -s -H "$H" "$A/project/<project id>/service-stack?limit=100&offset=0" | jq -r '.list[] | select(.name=="control") | .id')
-curl -s -H "$H" "$A/service-stack/$control/env" | jq -r '.items[] | select(.key=="FABRIKA_ZEROPS_ACCESS_TOKEN") | .content' > integration.token
-```
-
-Then run `init` from a directory that is NOT inside any git repository. The fabrika clone is a repository,
-and a home directory under dotfiles version control is one too. Otherwise pass `--checkout=<dir>` outside one:
+`init` takes the integration token step 1 minted, never the personal one. The secrets file holds it as
+`FABRIKA_ZEROPS_ACCESS_TOKEN`, beside the provisioning key. Run `init` from a directory that is NOT inside
+any git repository. The fabrika clone is a repository, and a home directory under dotfiles version control is
+one too. Otherwise pass `--checkout=<dir>` outside one:
 
 ```bash
-FABRIKA_ZEROPS_ACCESS_TOKEN="$(cat integration.token)" FABRIKA_IAM_PROVISIONING_KEY="$(cat provisioning.key)" \
+( set -a && . <secrets file> && set +a && \
   fabrika platform init --provider=zerops <installation> --repo=<owner>/<name> --tag=<tag> \
-  --project-id=<project id> --env=<name from step 1> --yes < /dev/null
+  --project-id=<project id> --env=<name from step 1> --yes < /dev/null )
 ```
 
 - Without `--repo` the repository is `contember/fabrika-zerops-<installation>`. Pass `--repo` for any
@@ -115,14 +176,17 @@ FABRIKA_ZEROPS_ACCESS_TOKEN="$(cat integration.token)" FABRIKA_IAM_PROVISIONING_
 ## Step 4. Mint a machine key for `fabrika control`
 
 ```bash
-iam=$(curl -s -H "$H" "$A/project/<project id>/service-stack?limit=100&offset=0" | jq -r '.list[] | select(.name=="iam") | .id')
-curl -s -H "$H" "$A/service-stack/$iam/env" | jq -r '.items[] | select(.key=="FABRIKA_IAM_RPC_KEY") | .content' > iam-rpc.key
-FABRIKA_IAM_RPC_URL=https://<IAM host> FABRIKA_IAM_RPC_KEY="$(cat iam-rpc.key)" FABRIKA_IAM_PROVISIONING_KEY="$(cat provisioning.key)" \
+( umask 077 && set -a && . <secrets file> && set +a && FABRIKA_IAM_RPC_URL=https://<IAM host> \
   fabrika control key issue --label=<name> --permissions=app.manage,namespace.manage,deploy.trigger,deploy.read \
-  --expires-in=2592000 > control-key.out
-grep -o 'px_[A-Za-z0-9_-]*' control-key.out | head -1 > control.key && rm control-key.out
+  --expires-in=2592000 > control.key )
+wc -c control.key && ls -l control.key
 ```
 
+The secrets file supplies `FABRIKA_IAM_RPC_KEY` and `FABRIKA_IAM_PROVISIONING_KEY`.
+
+- stdout carries the key and nothing else; the credential id goes to stderr. Keep the redirect inside the
+  `umask 077` subshell: `control.key` is then created with mode `0600` (`-rw-------`). Outside it, the file
+  is readable by other users.
 - `FABRIKA_IAM_RPC_URL` is IAM's PUBLIC `https://` origin. The private `http://iam:3000` answers only inside
   the Zerops project.
 - A key expires after at most 30 days. Mint a new one when it does.
@@ -134,30 +198,59 @@ export FABRIKA_CONTROL_URL=https://<console host>
 FABRIKA_CONTROL_KEY="$(cat control.key)" fabrika control apps list
 ```
 
-**Check.** `apps list` answers, with an empty list on a fresh installation.
+**Check.** On a fresh installation `apps list` prints `no applications registered yet` (on stderr) and
+exits 0. An authentication error means the key or the console origin is wrong.
 
 ## Step 5. Deploy the first application
 
-The public example is [`contember/fabrika-example-zerops`](https://github.com/contember/fabrika-example-zerops).
+The example is [`contember/fabrika-example-zerops`](https://github.com/contember/fabrika-example-zerops).
 Its `fabrika.config.ts` places the app with its own database (`mid` preset), and `fabrika.cheap.config.ts`
 places it on the namespace's shared PostgreSQL (`cheap` preset). Use the config that matches the preset.
 
-1. **Create a namespace.** It is the Zerops project applications are placed in. Without a custom domain
-   bound to its proxy, pass `--public-access=zerops-subdomain`; the default is `custom-domain`, which serves
-   no host until you bind one.
+**Repository access decides how you register** (step 5.2). Check it first:
+`curl -s -o /dev/null -w '%{http_code}\n' https://api.github.com/repos/<owner>/<name>`.
+
+- `200`: the repository is public. Register it with `--installation-id=none`. Control reads it without a token.
+- `404`: GitHub hides it from an anonymous caller, so it is private (or the name is wrong). `register` refuses
+  it with `--installation-id=none`. Ask the human to connect the GitHub App in the console first (Settings →
+  Source, a browser flow), then register without `--installation-id`.
+
+**Use the installation's release in the application.** The application's `@fabrika/*` packages, the CLI
+among them, must be the version of the tag you installed: for `v0.4.3`, `^0.4.3`. Another version can build
+a manifest this installation's control refuses or reads differently. From the fabrika clone of step 0, run
+`bun scripts/release.ts example-pin <application checkout> --tag=<tag>`. It rewrites every `@fabrika/*` range
+and commits nothing. Commit and push the change in the application repository, then run `bun install` there.
+Check with `bun pm ls | grep @fabrika/cli`.
+
+1. **Create a namespace** with the preset and core package the human chose (see Decisions). Without a
+   custom domain bound to its proxy, pass `--public-access=zerops-subdomain`; the default is
+   `custom-domain`, which serves no host until you bind one.
 
    ```bash
-   fabrika control namespaces plan   --namespace=<id> --env=<name> --preset=mid --public-access=zerops-subdomain
-   fabrika control namespaces create --namespace=<id> --env=<name> --preset=mid --public-access=zerops-subdomain
+   fabrika control namespaces plan   --namespace=<id> --env=<name> --preset=<cheap|mid|full> --public-access=zerops-subdomain
+   fabrika control namespaces create --namespace=<id> --env=<name> --preset=<cheap|mid|full> --public-access=zerops-subdomain
    fabrika control namespaces get    --namespace=<id>
    ```
 
    `create` returns while the state is `pending`. Provisioning takes several minutes. Poll `get` every
-   30 seconds until it is `ready`, then pick a host it lists as `free`.
+   30 seconds until it is `ready`.
+
+   - If the state is `failed`, `get` prints the cause and the command that resumes it on stderr. Run
+     `fabrika control namespaces reconcile --namespace=<id>` and poll `get` again. Provisioning resumes from
+     where it stopped. Do not create a second namespace.
+   - `get` lists one host per line as `<host> <port> free` or `<host> <port> taken by <app>/<env>`. A
+     `zerops-subdomain` namespace has six hosts, one per public port of its proxy: 8080 and 8082–8086. No
+     port is special or reserved; 8081 is the proxy's health port and is never listed. Use ANY `free` host,
+     for example the first one. Each host serves exactly one application environment, so six is the limit
+     per namespace.
 
 2. **Build and register**, from the application's repository root. The repository must be pushed: control
    deploys the commit on GitHub, not your working tree.
 
+   `--app=<id>` is the application id the manifest carries: `jq -r .app.id fabrika.manifest.json` after the
+   build. The application's `fabrika.config.ts` sets it (`defineApp({ id })`); the example takes it from its
+   contract's vocabulary, and it is `notes`.
+
    ```bash
    bun install
    bunx fabrika app build --env=<name>                          # cheap: add --config=fabrika.cheap.config.ts
@@ -166,8 +259,10 @@ places it on the namespace's shared PostgreSQL (`cheap` preset). Use the config
      --namespace=<namespace id> --domain=<free host> --installation-id=none
    ```
 
-   - `--installation-id=none` is for a PUBLIC repository. A private one needs the GitHub App connected in
-     the console (Settings → Source, a browser flow for the human); then omit the flag.
+   - `--installation-id=none` works only for a repository GitHub serves without a token. `register` reads it
+     once and refuses one that is not publicly readable, so the failure shows here and not at deploy. A
+     private repository needs the GitHub App connected in the console first (Settings → Source, a browser
+     flow for the human); then omit the flag.
    - `register` CREATES and refuses a second registration. A changed manifest goes through
      `control apps environments put` with the same placement flags.
 
@@ -179,6 +274,9 @@ places it on the namespace's shared PostgreSQL (`cheap` preset). Use the config
    FABRIKA_CONTROL_KEY="$(cat control.key)" bunx fabrika control runs log --run=<run id>
    ```
 
+   A failed run's log ends with `deploy failed: <reason>`. For example, `source resolve failed
+   (ref_not_found)` means control could not read the repository or the ref.
+
    The deploy fails when the repository at the deployed commit does not match the registered manifest.
    Commit and push, rebuild the manifest, `apps environments put` it, and deploy again.
 
@@ -195,12 +293,31 @@ fabrika platform upgrade --provider=zerops --to=<newer tag> --sidecar=<sidecar c
 ```
 
 It commits the tag to the sidecar's `fabrika.ref`, pushes, and follows the workflow run it triggers. It
-needs only the `gh` login. Existing namespaces keep their proxy version.
+needs only the `gh` login. When the sidecar's `.github/workflows/platform.yml` differs from the one this CLI
+generates, the same commit rewrites it, so run `upgrade` with the newest CLI: a hand edit of that file does not
+survive. The workflow installs the Bun release the pinned tag names in its `.bun-version` (1.3.14 for a tag
+that has none), never the newest one. From 0.4.2 or earlier, skip 0.4.3: its deploy stops at "Compose the proxy
+manifest" because the proxy's `FABRIKA_PROXY_MANIFEST_JSON` is sensitive. Do not re-save that variable. Upgrade to a
+later tag: its deploy deletes the variable, and needs no sudo mode. Existing namespaces keep their proxy version. To move one to the proxy of the
+new release, after the run succeeded:
+
+```bash
+fabrika control namespaces update --namespace=<id> --proxy-source=current
+```
+
+It re-pins the namespace and queues the reconcile that rebuilds its proxy; poll `namespaces get` until it is
+`ready`. A namespace pinned to a release before the proxy manifest moved into the build archive carries it in a
+service variable, which Zerops caps at about 32 KB: when a deploy fails with `serviceEnvValueTooLarge`, this is
+the fix, and it also accepts a namespace in `failed`.
 
 ## When something fails
 
 - Every refusal names its flag or variable. Fix that one value and re-run. `init`, `admin`, `deploy` and
   `upgrade` are safe to re-run. `install` is not: see step 1.
+- A failed install pass 2 is finished with `platform deploy`, with the credentials from the secrets file. The
+  install prints the command.
+- Lost the secrets file? Nothing in fabrika can recover it, and Zerops will not hand the values back. Start a
+  new installation in a new project.
 - A Zerops build or deploy failure: read the service log in the Zerops GUI or with
   `zcli service log -S <service id> --show-build-logs`.
 - Do not work around a refusal by editing the clone or the generated sidecar. Report what failed, with the

package/src/installation/index.ts

@@ -13,6 +13,7 @@ import { fileURLToPath } from 'node:url'
 import { createZeropsApi, defaultSleep } from '../index'
 import { consoleAdminCollaborators, runPlatformAdmin } from './admin'
 import { parsePlatformAdminArgs, REISSUE_FLAG } from './admin-options'
+import { npmCheckerPublication } from './checker-release'
 import { deployPlatform, PLATFORM_CONCURRENT_DEPLOY, PLATFORM_DEPLOY_ORDER, PLATFORM_SEQUENTIAL_DEPLOY } from './deploy'
 import { parsePlatformDeployArgs } from './deploy-options'
 import { consoleInitCollaborators, runInit } from './init'
@@ -66,9 +67,9 @@ deploy that push triggers.
 
 ── platform install ──────────────────────────────────────────────────────────────────────────────
 
-The from-scratch bring-up. With \`--create-project\` it creates the project too, with core package
-LIGHT and \`envIsolation: service\` — the two settings Zerops accepts at project CREATION only and never
-afterwards. \`--project-id=<id>\` installs into an empty project you created yourself instead, with both
+The from-scratch bring-up. With \`--create-project\` it creates the project too, with the tier's core
+package (LIGHT or SERIOUS) and \`envIsolation: service\` — the two settings Zerops accepts at project
+CREATION only and never afterwards. \`--project-id=<id>\` installs into an empty project you created yourself instead, with both
 already right; nothing here can read \`envIsolation\` back or correct it.
 
 Interactive and laptop-side. It CONFIRMS before every step that leaves your machine: reading the
@@ -79,27 +80,30 @@ is not consent.
 
   1. create the project and wait for it to be ACTIVE (\`--create-project\`; its id is printed before
      the wait), or read the one you named — and refuse a core package the tier does not match
-  2. import ${PLATFORM_DEPLOY_ORDER.length + 2} services without code, and wait for the import's processes
+  2. import the tier's services without code, and wait for the import's processes
   3. generate six secrets and mint the control plane's Zerops INTEGRATION token
-     (client role NO_ACCESS, ADMIN on this project only — never your personal token)
+     (client role NO_ACCESS, ADMIN on this project only — never your personal token), and write
+     all of them to \`--secrets-file\` (mode 0600) before the first one is placed
   4. pass 1: give the proxy an EMPTY manifest and build it, so it publishes one public hostname per
      HTTP port; the three platform hosts are then READ off those, never composed
   5. write every remaining variable on all four runtime services
   6. pass 2: hand the whole ordered sequence to \`platform deploy\`
-  7. print the provisioning key — the CLI keeps no copy; it is held by iam and control in Zerops
+  7. print the next commands; they read their credentials from the secrets file. Zerops holds the
+     same values as SENSITIVE variables and does not hand them back, so that file is the only copy
 
 It REFUSES a project that already holds an installation's generated secrets: a second bring-up would
 roll a new vault key over the old one, which is unrecoverable, and new signing keys, which logs
 everyone out. Once every bootstrap variable is placed, \`platform deploy\` can update the installation
-or finish a failed pass 2. Read FABRIKA_IAM_PROVISIONING_KEY from iam or control and
-FABRIKA_ZEROPS_ACCESS_TOKEN from control in Zerops if the handoff was interrupted.
+or finish a failed pass 2, with the credentials from the secrets file.
 Neither deploy nor init completes a partial bootstrap. If interrupted after a generated secret was
 placed but before every bootstrap variable was placed, preserve the existing keys and arrange
 operator-owned recovery, or start a fresh installation in a separate empty project.
 Re-running install after any generated secret was placed is refused.
 
-Only the LIGHT tier can be installed this way — it is the one topology that emits a services-only
-import document. Authentication is PASSWORD ONLY; no administrator exists yet when this finishes.
+Two tiers, one project each. \`light\` (core LIGHT): one single-node PostgreSQL and one bucket shared by
+IAM, control and Operations, one container per service. \`standard\` (core SERIOUS): an HA PostgreSQL for
+IAM and control, a second HA PostgreSQL and bucket for Operations, two containers of IAM and the proxy.
+Authentication is PASSWORD ONLY; no administrator exists yet when this finishes.
 
 Options (a flag beats the environment variable beside it):
 
@@ -112,7 +116,8 @@ Options (a flag beats the environment variable beside it):
   --env=<name>                      FABRIKA_PLATFORM_ENVIRONMENT    written to every service as ENVIRONMENT
   --scheme=<http|https>             FABRIKA_PLATFORM_SCHEME         default https
   --source-dir=<checkout>           required                       clean full checkout running this CLI
-  --tier=light                      FABRIKA_PLATFORM_TIER           default light, and the only value
+  --tier=<light|standard>           FABRIKA_PLATFORM_TIER           default light
+  --secrets-file=<path>             FABRIKA_PLATFORM_SECRETS_FILE   required: a NEW file outside the checkout
   ${UNATTENDED_FLAG}                                                             answer every confirmation yes —
                                                                     required when stdin is not a terminal
 
@@ -248,23 +253,24 @@ commit availability before its effects; a local commit is not thereby published
 The first human. A fresh installation has none — nothing seeds an admission list, and this command is
 why it does not have to. It is unattended, prompts for nothing, and changes nothing on a re-run:
 
-  1. find the principal holding that mailbox, or invite one
+  1. find the principal holding that address, or create one
   2. grant it the CROSS-APP \`admin\` role, unless it already holds one
   3. issue ONE password enrollment and print its URL
 
 The grant is cross-app (\`app: null\`) and that is load-bearing: grants filter to the calling app, so an
 \`admin\` grant scoped to the console's own app id leaves Delivery and Operations working while the
-Access plane refuses. A re-run invites nobody twice, grants nothing twice and issues no second
+Access plane refuses. A re-run creates nobody twice, grants nothing twice and issues no second
 enrollment — a password that is already set, or an enrollment already outstanding, is REPORTED. Pass
 \`${REISSUE_FLAG}\` to replace an outstanding one, which is the way out when the first expired unopened.
 
-The enrollment URL is a credential: it is printed once, on a line of its own, and stored nowhere.
+Nothing is e-mailed: a Zerops installation has no mail service. Hand the URL to the administrator
+yourself. It is a credential: it is printed once, on a line of its own, and stored nowhere.
 
 \`install\` reports the host this needs as \`✓ iam <host>\` and ends with this command ready to run.
 
 Options (a flag beats the environment variable beside it):
 
-  --email=<address>                 FABRIKA_PLATFORM_ADMIN_EMAIL    the administrator's mailbox
+  --email=<address>                 FABRIKA_PLATFORM_ADMIN_EMAIL    the administrator's sign-in address
   --iam-host=<host>                 FABRIKA_PLATFORM_IAM_HOST       IAM's public hostname, as \`deploy\` names it
   --scheme=<http|https>             FABRIKA_PLATFORM_SCHEME         default https
   ${REISSUE_FLAG}                                                         replace an outstanding enrollment
@@ -347,6 +353,7 @@ const runDeploy = async (argv: readonly string[]): Promise<void> => {
 	const input = parsePlatformDeployArgs(argv, process.env)
 	await deployPlatform(input, {
 		prepareSource: prepareInstallationSource,
+		checkerPublished: npmCheckerPublication(),
 		uploadFetch: (url, init) => fetch(url, init),
 		api: createZeropsApi({
 			token: input.accessToken,

package/src/installation/init-options.ts

@@ -138,9 +138,9 @@ export const parseInitArgs = (argv: readonly string[], env: CommandEnv, cwd: str
 		accessToken: credential(
 			env,
 			'FABRIKA_ZEROPS_ACCESS_TOKEN',
-			"the Zerops INTEGRATION token `platform install` minted, read from the `control` service's environment",
+			'the Zerops INTEGRATION token `platform install` minted, from its secrets file',
 		),
-		provisioningKey: credential(env, 'FABRIKA_IAM_PROVISIONING_KEY', 'the px_ key `platform install` printed'),
+		provisioningKey: credential(env, 'FABRIKA_IAM_PROVISIONING_KEY', 'the px_ key from the secrets file `platform install` wrote'),
 		unattended: argv.includes(UNATTENDED_FLAG),
 		...(hosts === undefined ? {} : { hosts }),
 		...(apiBaseUrl === undefined ? {} : { apiBaseUrl }),

package/src/installation/init.ts

@@ -95,8 +95,14 @@ export const inspectPlatform = async (projectId: string, api: ZeropsApi, signal:
 	if (control === undefined || control.id === '') throw new Error(`Zerops project ${projectId} has no \`control\` service`)
 	const proxy = oneService(services, 'proxy')
 	if (proxy === undefined || proxy.id === '') throw new Error(`Zerops project ${projectId} has no \`proxy\` service`)
-	const readEnv = async (serviceId: string): Promise<Map<string, string>> =>
-		new Map((await api.listServiceEnv({ serviceId, signal })).map((item) => [item.key, item.content]))
+	// Only the readable values: everything init prints is derived from non-secret configuration.
+	const readEnv = async (serviceId: string): Promise<Map<string, string>> => {
+		const readable = new Map<string, string>()
+		for (const item of await api.listServiceEnv({ serviceId, signal })) {
+			if (!item.sensitive) readable.set(item.key, item.content)
+		}
+		return readable
+	}
 	return {
 		controlEnv: await readEnv(control.id),
 		proxyEnv: await readEnv(proxy.id),

package/src/installation/install-collaborators.ts

@@ -1,6 +1,7 @@
 import type { Confirmations } from '@fabrika/installation-init'
 import type { SchemaReconciler } from '@fabrika/provider-contract'
 import type { Sleeper, ZeropsApi } from '../index'
+import type { CheckerPublication } from './checker-release'
 import type { PlatformSourcePreparer } from './installation-source'
 import type { InitLog } from './log'
 import type { PlatformUploadFetch } from './platform-upload'
@@ -11,6 +12,7 @@ export type InstallPrompts = Confirmations
 /** Everything `runInstall` reaches the outside world through. */
 export interface InstallCollaborators {
 	readonly prepareSource: PlatformSourcePreparer
+	readonly checkerPublished: CheckerPublication
 	readonly uploadFetch: PlatformUploadFetch
 	readonly api: ZeropsApi
 	readonly reconcileSchema: SchemaReconciler
@@ -18,6 +20,8 @@ export interface InstallCollaborators {
 	readonly log: InitLog
 	readonly prompts: InstallPrompts
 	readonly signal: AbortSignal
+	/** Create the local secrets file (`--secrets-file`) with this text. Never logged. */
+	readonly storeSecrets: (text: string) => Promise<void>
 }
 
 export const assertRunning = (signal: AbortSignal): void => {