@arbol-ai/cli 1.20261018.212151 → 1.20261019.5745

package/README.md

@@ -12,7 +12,9 @@ npm install --global @arbol-ai/cli
 arbol --version
 ```
 
-It needs Node.js 26 or newer, whose `fetch` and `Temporal` the SDK uses.
+It needs Node.js 26 or newer, whose `fetch` and `Temporal` the SDK uses. The same command updates it.
+An `arbol` installed before the CLI was on npm comes first or blocks the install: remove it with
+`npm uninstall --global @getarbol/cli`, or delete `~/.local/bin/arbol` and `~/.local/share/arbol`.
 
 ## Profiles
 
@@ -145,6 +147,29 @@ bun run verify      # typecheck, tests and dist/
 `openapi.json` is downloaded at generation time and not committed, and `src/generated/generation.json`
 records which release, Forge commit and plugin wrote each file.
 
+## Releases
+
+A release of the API flows through three repositories, each started by the one before it:
+
+1. **project-arbol-gateway** publishes the OpenAPI at `https://api.getarbol.com/openapi.json` and sends
+   `openapi-release` to project-arbol-sdk-js.
+2. **project-arbol-sdk-js** regenerates `@arbol-ai/sdk` from it, publishes it to npm and sends
+   `sdk-release` (`{ "version": "<release>" }`) here.
+3. **Here**, [Generate](.github/workflows/generate.yml) releases only when the OpenAPI's content
+   changed: the SHA-256 of its canonical JSON without `info.version` (keys sorted, no whitespace; see
+   [`generation/openapi-hash.ts`](generation/openapi-hash.ts), the same hash sdk-js computes), compared
+   with `openapiContentSha256` in main's `src/generated/generation.json`. When it is equal, the run
+   stops and nothing is committed or published. Otherwise Generate pins `@arbol-ai/sdk` to exactly the
+   release sdk-js named, regenerates `src/generated/`, and when `bun run verify` passes commits
+   `Release <release>` to main and runs [Publish](.github/workflows/publish.yml) on that commit.
+
+Generate also runs every 6 hours and by hand, with the same hash check, pinning the SDK release the
+OpenAPI names once it is on npm. Its push uses an installation token of the organization's GitHub App
+(Arbol Bot: the variable `ARBOL_BOT_APP_ID` and the secret `ARBOL_BOT_PRIVATE_KEY`), so the commit runs
+Verify like any other. A change to the CLI's own code, which the OpenAPI does not carry, is released by
+running Publish by hand on main. npm receives the package with the organization's `NPM_TOKEN` and a
+provenance statement.
+
 ## License
 
 [Apache License 2.0](LICENSE)