Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript

docs(desktop-app): [R6-L1] document gated Profile handoff

Josué0479c67777a3
diff --git a/docs/how-to/desktop-setup-and-updates.md b/docs/how-to/desktop-setup-and-updates.md
index 213b2c4ad..f8e5a306b 100644
--- a/docs/how-to/desktop-setup-and-updates.md
+++ b/docs/how-to/desktop-setup-and-updates.md
@@ -54,13 +54,20 @@ environment at the forwarded External REST API.
### 2. From Profile UI, by deep link
-A member can hand the app its environment from the browser: in **Profile UI →
-Settings → Setup desktop app**, copy the External REST API and click **Open
-desktop app and setup**. That opens an `evenfire://desktop-environment` deep
-link the installed app handles — it saves or updates the environment, and if the
-External REST API was already saved, it updates the name and re-discovers the
-RPC proxy. Fleets can also be pre-seeded with a `CLERUM_DESKTOP_CONFIG_PATH`
-config file (see
+When Profile-to-Desktop handoff is enabled, a member can open the environment
+from **Profile UI → Settings → Setup desktop app**. Desktop selects a single
+saved environment with the exact External REST API URL. If the current session
+uses another REST URL, Desktop signs out before switching. If no exact match is
+saved, Desktop asks before adding the environment; after confirmation, the
+External REST API supplies the RPC proxy URL. Multiple saved exact matches are
+rejected for manual resolution.
+
+The handoff is disabled by default. A release operator can enable it by setting
+the `PROFILE_DESKTOP_HANDOFF_ENABLED` repository variable to `true` when
+building Profile UI, after releasing the updated Desktop client and retiring
+older supported clients. While it is disabled, copy the REST API URL from
+Profile UI Settings and add it from Desktop's sign-in screen. Fleets can also
+be pre-seeded with a `CLERUM_DESKTOP_CONFIG_PATH` config file (see
[Ship it to your users](../surfaces/desktop-app.md#ship-it-to-your-users)).
### 3. Through an invitation
diff --git a/docs/surfaces/desktop-app.md b/docs/surfaces/desktop-app.md
index da93088c6..1f96e0a30 100644
--- a/docs/surfaces/desktop-app.md
+++ b/docs/surfaces/desktop-app.md
@@ -198,8 +198,14 @@ user points the installed app at whatever instance they want — your hosted
service, a teammate's, or local `make`-forwarded services — from the app's own
**Environment** screen: name it, paste the External REST API URL, Save. The RPC
proxy address follows from that environment; there is no second URL to enter.
-Environments can also be pre-seeded for a fleet through Profile UI's
-`evenfire://desktop-environment` deep link or a `CLERUM_DESKTOP_CONFIG_PATH`
+When Profile-to-Desktop handoff is enabled, Profile UI's
+`evenfire://desktop-environment` link selects one exact saved REST URL or asks
+the user before adding it; the REST API supplies the RPC proxy URL. This
+producer is disabled by default. Release operators enable the
+`PROFILE_DESKTOP_HANDOFF_ENABLED` image-build variable only after releasing the
+updated Desktop client and retiring older supported clients. While the gate is
+off, users can copy the REST URL from Profile UI Settings and add it in Desktop.
+Fleets can also pre-seed environments with a `CLERUM_DESKTOP_CONFIG_PATH`
config file. Adding and switching environments, the invitation setup path, and
how a packaged app surfaces a **required** update are covered in
[Desktop setup & updates](../how-to/desktop-setup-and-updates.md).