kylon-cli 0.2.2-next.310 → 0.2.2-next.312

package/README.md

@@ -16,15 +16,21 @@ two distinct copy-paste entry points:
   installation for human workspace commands. Its **Use with Your Agents**
   prompt teaches Claude Code, Codex, Hermes, or OpenClaw to discover and use
   `kylon workspace` commands without assuming a provider-specific interface.
-- **An external agent's Settings page** (and the create-agent flow) shows
-  `npx --yes kylon-cli@<tag> connect --url '<setup url>'` — authorizes the
-  installation when needed, registers it as a computer, and assigns the named
-  agent in the same run. The setup URL carries intent only (workspace + agent),
-  never a credential, and expires after an hour.
-
-Both commands browser-authenticate the operator. Only `connect` enrolls the
-computer (minting a machine-scoped credential stored locally with mode `0600`)
-and starts the host daemon. In release builds on supported hosts a user-level
+- **An external agent's Onboarding tab** shows
+  `npx --yes kylon-cli@<version> agent link --url '<one-time link>'`. The link
+  embeds a short-lived credential, so the CLI does not open a browser or reuse
+  a human workspace credential. It checks that the selected Claude Code or
+  Codex CLI is installed and authenticated, shows the exact agent and
+  workspace for confirmation, registers this installation as a computer,
+  assigns the agent, and starts the host daemon. The credential expires after
+  30 minutes and can be redeemed only once; rerunning the same installation's
+  interrupted redemption is idempotent.
+
+`auth login` browser-authenticates the human operator for `kylon workspace`
+commands. `agent link` authenticates only the link operation with its embedded
+credential; it never creates a human CLI session. Linking mints or reuses a
+machine-scoped credential stored locally with mode `0600` and starts the host
+daemon. In release builds on supported hosts a user-level
 `launchd` / `systemd --user` service is installed so the daemon survives
 terminal exit, reboot, and sleep/wake; otherwise the daemon runs in the
 foreground until `Ctrl+C`.
@@ -37,7 +43,7 @@ Requirements: Node.js 22.15.0+ (npm ships with Node). Linux / macOS only
 
 ### One managed `kylon` for humans and agents
 
-Both bootstrap commands (`connect` and `auth login`) pin the CLI under
+The bootstrap commands (`agent link`, `connect`, and `auth login`) pin the CLI under
 `~/.kylon/bin`: the exact bundle the daemon and its agents execute, exposed as
 the `kylon` command. After the bootstrap they offer to add that directory to
 your shell PATH (a marker-wrapped `. "$HOME/.kylon/env"` line in your shell rc,
@@ -47,7 +53,7 @@ artifact, one version, one upgrade.
 
 A leftover npm-global or npx-cached copy stays harmless: when it starts and
 finds a strictly newer pinned install, it defers to it automatically
-(installer commands — `connect`, `gateway …` — always run as invoked, so a
+(installer commands — `agent …`, `connect`, and `gateway …` — always run as invoked, so a
 fresh `npx` can still install itself over an older pinned copy; set
 `KYLON_PINNED_TRAMPOLINE=0` to disable the deferral).
 
@@ -190,36 +196,31 @@ 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.
 
-### Connect a computer (and optionally an agent)
+### Register a computer for manual placement
 
-`kylon connect` is the single onboarding entrypoint.
+`kylon connect` remains the advanced computer-first entrypoint when the user
+explicitly wants to register a host before choosing an agent:
 
 ```bash
-# Register this machine directly, then assign agents from the web:
 npx --yes kylon-cli@latest connect --workspace <WORKSPACE_ID>
-
-# From an agent's page — register this machine AND assign that agent to it:
-npx --yes kylon-cli@latest connect --url 'https://api.kylon.io/docs/computer-setup/<opaque-token>'
 ```
 
-Both forms browser-authenticate the operator (same PKCE flow as
-`kylon auth login`), enroll the machine as a **computer** keyed on its stable
-install id (re-running is idempotent), persist the machine-scoped credential,
-and start the host daemon. The `--url` form resolves the setup link to a
-workspace + agent and, after enrollment, assigns that agent to this computer —
-authorized as the signed-in user, so an account that cannot manage the agent
-gets a clear error and the computer registration still stands.
+This browser-authenticates the operator (the same PKCE flow as `kylon auth
+login`), enrolls the machine as a **computer** keyed on its stable install id
+(re-running is idempotent), persists the machine-scoped credential, and starts
+the host daemon. New external-agent onboarding should use the agent-specific
+`agent link` command instead; creation never asks the user to select a computer.
 
 The daemon then reconciles the computer's assigned agents from the server:
 each agent gets an isolated state root under `~/.kylon/agents/<agent-id>/`,
 provider readiness (Codex / Claude Code install + authentication) is reported
 per agent, and assignments arrive over the computer's single SSE stream.
-Assigning, moving, or unassigning agents later happens in the web UI; the
-daemon picks the change up without re-running `connect`.
+Linking or relinking an agent later happens from that agent's Onboarding tab;
+the daemon picks the change up without re-running `connect`.
 
 Use `--no-start` to register without starting the daemon, `--json` for
 machine-readable output, and `--server-url` to target a non-default API origin
-(the `--url` form resolves the origin from the setup link itself).
+for direct computer registration.
 
 ### Run