feat(core): add unified remote login profiles

.changeset/native-remote-background-auth.md

@@ -0,0 +1,5 @@
+---
+"@caplets/core": patch
+---
+
+Refresh native remote credentials before background polling, attach event reconnects, tool invokes, and stale-manifest retries so long-lived Remote Profile integrations do not reuse expired authorization headers.

.changeset/unified-remote-login.md

@@ -0,0 +1,8 @@
+---
+"@caplets/core": minor
+"caplets": minor
+"@caplets/opencode": minor
+"@caplets/pi": minor
+---
+
+Replace self-hosted remote env-token and Basic Auth setup with unified Remote Login profiles. Remote attach, hosted Cloud, OpenCode, and Pi now resolve Caplets-owned credentials from `caplets remote login <url>` and use `CAPLETS_REMOTE_URL` only as a non-secret selector.

CONCEPTS.md

@@ -53,3 +53,29 @@ Recovery References are separate from session handles. Possessing a session hand
 ### Progressive Exposure
 
 The Caplets exposure mode where agents discover and call backend operations through a small set of wrapper tools instead of receiving every downstream operation as a separate top-level tool.
+
+## Remote Attach
+
+### Remote Attach
+
+The process where a local agent-facing Caplets runtime connects to a trusted Caplets host and exposes that host's capabilities through local or native agent integrations.
+
+Remote Attach uses Remote Profiles for trust and credentials. Long-lived attach traffic treats credentials as refreshable runtime state rather than fixed startup state.
+
+### Remote Login
+
+The provider-neutral flow that trusts a local Caplets client to a Caplets host, whether the host is self-hosted or Caplets Cloud.
+
+Remote Login stores host credentials in Caplets-owned credential storage so agent configs can launch `caplets attach --remote-url ...` without carrying remote secrets.
+
+### Pairing Code
+
+A short-lived, one-time code minted by a self-hosted Caplets host and exchanged by a client during Remote Login.
+
+Pairing Codes are bootstrap material only. They are not reusable client credentials.
+
+### Remote Profile
+
+The stored local record for a trusted Caplets host, including the normalized host URL, host kind, selected workspace when applicable, and redacted credential status.
+
+Remote Profiles are the source of truth for request credentials. Long-lived clients resolve current profile state when sending remote traffic instead of copying credentials into agent config or one-time startup state.

README.md

@@ -145,15 +145,14 @@ Native integrations expose `caplets__code_mode` for multi-step TypeScript workfl
 generated `caplets.<id>` handles. Progressive exposure adds `caplets__<id>` tools; direct
 exposure adds operation-level tools such as `caplets__<id>__<operation>`.
 
-Remote mode is available with `caplets attach`, self-hosted HTTP service settings, or
-Caplets Cloud auth:
+Remote mode uses Remote Login for both self-hosted Caplets and Caplets Cloud. Trust the
+host once, then launch attach or a native integration with only non-secret selectors:
 
 ```sh
-export CAPLETS_MODE=remote
-export CAPLETS_REMOTE_URL=https://caplets.example.com/caplets
-export CAPLETS_REMOTE_TOKEN=...
+caplets remote login https://caplets.example.com/caplets
+caplets attach --remote-url https://caplets.example.com/caplets
 
-caplets cloud auth login
+caplets remote login https://cloud.caplets.dev
 CAPLETS_MODE=cloud CAPLETS_REMOTE_URL=https://cloud.caplets.dev opencode
 ```
 

apps/docs/src/content/docs/remote-attach.mdx

@@ -14,7 +14,7 @@ Caplets native integrations use the same mode names as `caplets attach`:
 | -------- | ------------------------------------------------------------------------------------------------------------------------- |
 | `local`  | The agent should start Caplets against local user and project config.                                                     |
 | `remote` | The agent should connect to a self-hosted Caplets service.                                                                |
-| `cloud`  | The agent should connect to Caplets Cloud with explicit `CAPLETS_REMOTE_*` or `CAPLETS_CLOUD_*` environment values.       |
+| `cloud`  | The agent should connect to Caplets Cloud through a saved Remote Profile.                                                 |
 | `auto`   | Caplets should use Cloud for Cloud URLs, self-hosted remote for non-Cloud URLs, and local mode when no remote URL is set. |
 
 ## MCP client config
@@ -24,7 +24,7 @@ Codex:
 ```toml
 [mcp_servers.caplets]
 command = "caplets"
-args = ["attach"]
+args = ["attach", "--remote-url", "https://caplets.example.com/caplets"]
 ```
 
 Generic MCP JSON:
@@ -34,40 +34,45 @@ Generic MCP JSON:
   "mcpServers": {
     "caplets": {
       "command": "caplets",
-      "args": ["attach"]
+      "args": ["attach", "--remote-url", "https://caplets.example.com/caplets"]
     }
   }
 }
 ```
 
-## Environment
+## Remote Login
 
-For a self-hosted remote:
+For a self-hosted remote, first create a short-lived Pairing Code on the server:
 
 ```sh
-export CAPLETS_MODE=remote
-export CAPLETS_REMOTE_URL=https://caplets.example.com/caplets
-export CAPLETS_REMOTE_TOKEN=...
+caplets remote host pair --host-url https://caplets.example.com/caplets
+```
+
+If the server uses a non-default credential state directory, pass the same directory with
+`--state-path` that the server uses for `caplets serve --remote-state-path`.
 
-caplets attach
+Then log in once on the client and configure the agent to launch attach:
+
+```sh
+caplets remote login https://caplets.example.com/caplets
+caplets attach --remote-url https://caplets.example.com/caplets
 ```
 
-Use `CAPLETS_REMOTE_USER` and `CAPLETS_REMOTE_PASSWORD` instead of
-`CAPLETS_REMOTE_TOKEN` when the remote uses Basic Auth.
+Enter the Pairing Code at the hidden prompt from `caplets remote login`. Use
+`--code-stdin` for automation instead of putting Pairing Codes in shell history.
 
-For Caplets Cloud native integrations, set the Cloud URL plus a workspace and token:
+For Caplets Cloud native integrations, log in once and then set the Cloud URL selector:
 
 ```sh
+caplets remote login https://cloud.caplets.dev
 export CAPLETS_MODE=cloud
 export CAPLETS_REMOTE_URL=https://cloud.caplets.dev
-export CAPLETS_REMOTE_WORKSPACE=...
-export CAPLETS_REMOTE_TOKEN=...
 
 opencode
 ```
 
-Saved Cloud auth from `caplets cloud auth login` is used by the `caplets attach` CLI path.
-Native integrations do not read the saved auth store directly.
+Saved Remote Profiles are used by `caplets attach` and native integrations. Agent configs
+should not contain Caplets remote tokens or passwords.
 
 Run a finite Project Binding smoke path before wiring an agent:
 

apps/docs/src/content/docs/troubleshooting.mdx

@@ -123,24 +123,18 @@ Expected symptom: remote mode starts, but attach cannot reach the runtime or aut
 Confirm the remote environment:
 
 ```sh
-export CAPLETS_MODE=remote
-export CAPLETS_REMOTE_URL=https://caplets.example.com/caplets
-export CAPLETS_REMOTE_TOKEN=...
+caplets remote login https://caplets.example.com/caplets
 caplets doctor
-caplets attach
+caplets attach --remote-url https://caplets.example.com/caplets
 ```
 
-If the remote requires auth, set either `CAPLETS_REMOTE_TOKEN` or
-`CAPLETS_REMOTE_USER` plus `CAPLETS_REMOTE_PASSWORD`. If the URL belongs to Caplets Cloud,
-check whether your environment expects `CAPLETS_REMOTE_*` or `CAPLETS_CLOUD_*` values and
-keep the family consistent for that shell. Cloud-native integrations also need the selected
-workspace:
+If the URL belongs to Caplets Cloud, log in through Remote Login and keep the Cloud URL
+selector consistent for that shell:
 
 ```sh
+caplets remote login https://cloud.caplets.dev
 export CAPLETS_MODE=cloud
 export CAPLETS_REMOTE_URL=https://cloud.caplets.dev
-export CAPLETS_REMOTE_WORKSPACE=...
-export CAPLETS_REMOTE_TOKEN=...
 caplets attach --once
 ```