@frontfriend/sdk 1.2.4 → 1.2.5

package/README.md

@@ -326,7 +326,7 @@ npx frontfriend init --tag <tag-name-or-id>
 
 `--version` takes a Release ID, not an SDK version. A Studio refusal, such as a missing login or no access to the Design System, stops initialization.
 
-After the tokens, an online `init` registers the App named in `frontfriend.config.js` on its tag (`--tag`, then `tag`) with its `framework` and `primitive`, so `update` and the design reads find it. When Studio refuses the registration, `init` stops with the reason; the installed tokens stay. During an outage it keeps the tokens and asks you to run `init` again. When the App adopts contracts and `frontfriend.lock.json` pins a design snapshot, `init` also writes that snapshot's contracts to `.frontfriend/design/` and, when they are missing or belong to another snapshot, its rules to `.frontfriend/rules/`: the same files `update` writes.
+After the tokens, an online `init` signed in as a person registers the App named in `frontfriend.config.js` on its tag (`--tag`, then `tag`) with its `framework` and `primitive`, so `update` and the design reads find it. When Studio refuses the registration, `init` stops with the reason; the installed tokens stay. With a machine credential, or with `--no-register`, `init` installs the selected tokens and never registers the App or changes its Release tag (see [Builds and CI](#builds-and-ci)). During an outage it keeps the tokens and asks you to run `init` again. When the App adopts contracts and `frontfriend.lock.json` pins a design snapshot, `init` also writes that snapshot's contracts to `.frontfriend/design/` and, when they are missing or belong to another snapshot, its rules to `.frontfriend/rules/`: the same files `update` writes.
 
 `frontfriend.lock.json` lists its contract pins by slug, then kind, and its `adoptionDigest` does not depend on the order of the pins. A lock written by an earlier SDK in another order is still valid; `update` keeps its bytes until the adoption itself changes.
 
@@ -346,9 +346,19 @@ The default API uses the production token CDN automatically. For a custom API, s
 
 Downloads validate artifact identity and integrity. Access refusals and invalid data stop initialization. Token delivery does not update component files or publish changes; `init --offline` also does not register the application or write contracts. Run `init`, `connect` or `design sync` online for those operations. External fonts and images have their own availability.
 
-## CI authentication
+## Builds and CI
 
-Set `FF_AUTH_TOKEN` through your CI secret store for commands that need access to your workspace. Do not commit it to project configuration or print it in build logs. Online token delivery, private components and design rules require it; `init --offline` does not.
+Builds authenticate with a machine credential: create one with the `components:read` permission on the **API keys** page of the Workspace in Studio, and set it as `FF_AUTH_TOKEN` through your CI secret store. Do not commit it to project configuration or print it in build logs. Online token delivery, private components and design rules require it; `init --offline` does not.
+
+In CI or a Docker build, select the tag the build ships:
+
+```sh
+FF_AUTH_TOKEN=<machine credential> npx frontfriend init --tag <tag-name>
+```
+
+A machine credential is read-only for the App. `init` installs the tokens of the requested tag and prints `Build mode: App registration skipped (machine credential).`; it never registers the App or moves its Release tag in Studio, so a preview build on `next` does not move a production App off `base`. Pass `--no-register` to get the same behavior with any credential. Studio never changes an App for a machine credential either: it answers the registration of an earlier SDK with the App unchanged, so those builds also install the requested tag and leave the App on its own tag. If Studio refuses a registration with `MACHINE_CREDENTIAL_READ_ONLY`, `init` reports the registration as skipped and succeeds.
+
+`update`, `adopt`, `download` and `add` with a machine credential use the App's current Release tag. They stop with a message when the selection would bind the App or move it to another tag. `connect` stops at its login step: it registers the App, which needs a person's login (`frontfriend login`, with `FF_AUTH_TOKEN` unset). Change an App's tag in Studio or with a person's login.
 
 ## Existing Tailwind clients