kylon-cli 0.2.0-next.154 → 0.2.1-next.156

package/README.md

@@ -65,17 +65,63 @@ for the debugger-friendly tsx-based dev loop.
 
 npm dist-tags are the version pointer — there is no server-side version
 policy. Every merge to `develop` publishes a prerelease to the `next` tag
-(`.github/workflows/cli-publish.yml`); cutting a `kylon-cli-vX.Y.Z`
-release tag publishes a stable to `latest`. dev installs `@next` and prd
-installs `@latest`, so each environment tracks its own train.
-
-Cutting a stable is a manual, when-ready step: tag a validated build
-`kylon-cli-vX.Y.Z` and push the tag; CI publishes it to `latest`. Don't
-`npm publish` ad-hoc — releases go through the CI workflow so the OIDC
-publish path is exercised end-to-end.
+(`.github/workflows/cli-publish.yml`). A production deployment dispatched from
+`main` automatically invokes the same workflow in stable mode and publishes the
+exact `packages/cli/package.json` version to `latest`; it is idempotent when that
+version already exists. A CLI change intended for production must therefore bump
+the package version before the production deploy, or the stable publish will
+correctly no-op and `latest` will remain on the existing build.
+
+A matching `kylon-cli-vX.Y.Z` tag is an alternative supported stable-release
+trigger, not a required extra step after a production deploy. Do not run
+`npm publish` ad hoc: both paths use the CI workflow and its OIDC publisher.
+Development installs `@next` and production installs `@latest`, so each
+environment tracks its own release train.
 
 ## Usage
 
+### Sign in for workspace commands
+
+For a person using `kylon workspace ...` from their own terminal, open the
+workspace's **Settings → Kylon CLI** section, expand it, and copy its setup
+command, or run:
+
+```bash
+npm install -g kylon-cli@latest && kylon auth login --workspace <WORKSPACE_ID>
+```
+
+The CLI opens Kylon in your browser. After you sign in, confirm the installation
+and workspace shown on the authorization page, and verify that its confirmation
+code matches the one printed in your terminal. The browser approves a short-lived
+request but never receives the credential. The CLI proves possession of its PKCE
+verifier while polling Kylon over HTTPS, receives the credential directly from
+the API, and saves it in the versioned credential collection at
+`~/.kylon/workspace-auth.json` with mode `0600`. No loopback listener, incoming
+port, or browser request to localhost is used.
+The collection keeps credentials separately by server and workspace, and
+`--scope-workspace` selects the matching entry.
+
+Each installation credential expires after 90 days. Re-running `kylon auth
+login` for the same installation and workspace rotates that credential, making
+the previous value invalid. Use `kylon auth status` to inspect the bound
+workspace and expiration time.
+
+```bash
+kylon auth logout --workspace <WORKSPACE_ID>
+```
+
+Logout revokes the selected installation credential remotely before removing
+that entry from the local collection. With no `--workspace`, it selects the most
+recently authorized entry. If Kylon cannot confirm revocation, it keeps the local
+credential so you can retry. `kylon auth logout --local-only` deliberately skips
+the remote revocation. You can also revoke any installation independently from
+**Settings → Kylon CLI**. Other installations, browser sessions, external-agent
+keys, and workspace service keys are unaffected.
+
+Credentials created by the earlier browser flow appear as **Legacy user API
+key** in Settings. They can be revoked there, but they are not bound to a single
+workspace; sign in again to replace one with the per-installation flow.
+
 ### Onboard an invited external agent
 
 The Web UI provides one operator-run command after an external agent is
@@ -95,6 +141,10 @@ by the displaced connection, and replaces the foreground daemon. If Codex or
 Claude Code is logged out, an interactive terminal launches the provider's own
 login flow and verifies authentication again before connecting.
 
+External-agent onboarding is intentionally separate from human `kylon auth
+login`: it continues to use the agent principal's API key and gateway session.
+It does not create a human CLI installation credential.
+
 Each invited agent is installed below `~/.kylon/agents/<agent-id>/`, so several
 Claude Code, Codex, or mixed-provider agents can run on the same host without
 sharing credentials or provider resume state. Different agents cannot use the
@@ -470,9 +520,10 @@ API server is the security boundary.
 
 The CLI ships via **npm dist-tags** — there is no server-side version policy.
 `cli-verify.yml` validates on PRs and pushes; `cli-publish.yml` publishes via
-OIDC (no token): a prerelease to the `next` tag on every merge to `main`, and a
-stable to `latest` when a `kylon-cli-vX.Y.Z` tag is pushed. dev installs
-`@next`, prd installs `@latest`.
+OIDC (no token): a prerelease to the `next` tag on every qualifying merge to
+`develop`, and the package version to `latest` when the production deploy runs
+from `main`. A matching `kylon-cli-vX.Y.Z` tag can also publish that stable
+version. Development installs `@next`; production installs `@latest`.
 
 ### Versioning
 
@@ -484,18 +535,23 @@ Use explicit semver in `packages/cli/package.json`:
 | minor (`0.1.x → 0.2.0`) | backward-compatible capability (new command, new flag) |
 | major (`0.x.x → 1.0.0`) | breaking change to CLI contract or runtime behavior |
 
-Prerelease builds are versioned `0.1.0-next.<run>` automatically by
-`cli-publish.yml`; a stable release is whatever you tag — bump
-`packages/cli/package.json` to the target semver, then push the matching
-`kylon-cli-vX.Y.Z` tag.
+Prerelease builds are versioned `<package-version>-next.<run>` automatically by
+`cli-publish.yml`. Stable mode publishes the exact package version and skips
+idempotently if npm already has it. Bump `packages/cli/package.json` whenever a
+new production CLI build must be published; otherwise the production deploy
+will intentionally leave `latest` unchanged.
 
 ### Publishing
 
-- **Prerelease (automatic):** every merge to `main` touching the CLI publishes
-  `0.1.0-next.<run>` to the `next` tag via `cli-publish.yml` (OIDC, no
+- **Prerelease (automatic):** every merge to `develop` touching the CLI publishes
+  `<package-version>-next.<run>` to the `next` tag via `cli-publish.yml` (OIDC, no
   `NPM_TOKEN`). dev tracks this tag, so dev always dogfoods the newest build.
-- **Stable (manual, when ready):** bump `packages/cli/package.json` to the
-  target version, merge, then tag the commit on `main`:
+- **Stable (automatic with a production deploy):** a production deployment
+  dispatched from `main` calls `cli-publish.yml` in stable mode. It publishes
+  the package version only when that exact version is absent from npm. CLI
+  changes therefore need a package-version bump before the production deploy.
+- **Stable tag (alternative):** after bumping the package version, a matching
+  tag on `main` invokes the same stable workflow directly:
 
   ```bash
   git pull
@@ -504,8 +560,8 @@ Prerelease builds are versioned `0.1.0-next.<run>` automatically by
   npm view kylon-cli dist-tags        # verify
   ```
 
-  Do not `npm publish` ad-hoc — releases go through the workflow so the OIDC
-  provenance path is exercised end to end.
+Do not `npm publish` ad hoc: production deploys and release tags both go through
+the workflow so the OIDC provenance path is exercised end to end.
 
 ### Rollback