feat(core): add self-hosted pending remote login

.changeset/attach-positional-url.md

@@ -0,0 +1,6 @@
+---
+"@caplets/core": patch
+"caplets": patch
+---
+
+Make `caplets attach <url>` the primary remote attach command while keeping `--remote-url <url>` as a hidden compatibility alias.

.changeset/remote-pairing-ergonomics.md

@@ -0,0 +1,6 @@
+---
+"@caplets/core": patch
+"caplets": patch
+---
+
+Label hidden CLI prompts without echoing entered secrets, and document the pending self-hosted Remote Login requirements and implementation plan.

.changeset/self-hosted-pending-remote-login.md

@@ -0,0 +1,6 @@
+---
+"@caplets/core": patch
+"caplets": patch
+---
+
+Replace self-hosted Remote Login's operator-minted Pairing Code bootstrap with a client-started pending login flow. The client now starts `caplets remote login <url>`, displays a short operator code, waits for server-local approval, rotates pre-login material while pending, and stores final Remote Profile credentials only after approval. Remote attach recovery now reports revoked self-hosted credentials and Cloud workspace ambiguity with stable recovery guidance, and public docs/examples show the pending-login approval sequence without remote secrets in agent configuration.

CONCEPTS.md

@@ -84,13 +84,19 @@ Remote Attach uses Remote Profiles for trust and credentials. Long-lived attach
 
 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.
+Remote Login stores host credentials in Caplets-owned credential storage so agent configs can launch Remote Attach using stable host selectors without carrying remote secrets.
+
+### Pending Remote Login
+
+The self-hosted Remote Login state between client initiation and server-local operator approval or rejection.
+
+A Pending Remote Login separates the operator-visible Pairing Code from client-held pending material. Approval alone does not create reusable attach credentials; the initiating client must still complete the flow with its possession proof before a Remote Profile can be stored.
 
 ### Pairing Code
 
-A short-lived, one-time code minted by a self-hosted Caplets host and exchanged by a client during Remote Login.
+A short-lived, operator-visible approval code for a pending self-hosted Remote Login flow.
 
-Pairing Codes are bootstrap material only. They are not reusable client credentials.
+Pairing Codes prove that a server-local operator approved a specific pending login. They are not reusable client credentials, attach bearer credentials, or the flow's longer-lived pre-login refresh material.
 
 ### Remote Profile
 

README.md

@@ -127,15 +127,15 @@ For a remote or Cloud-backed MCP server, point the client at `caplets attach` in
 ```toml
 [mcp_servers.caplets]
 command = "caplets"
-args = ["attach"]
+args = ["attach", "https://caplets.example.com/caplets"]
 ```
 
 ```json
 {
   "mcpServers": {
     "caplets": {
       "command": "caplets",
-      "args": ["attach"]
+      "args": ["attach", "https://caplets.example.com/caplets"]
     }
   }
 }
@@ -150,7 +150,7 @@ host once, then launch attach or a native integration with only non-secret selec
 
 ```sh
 caplets remote login https://caplets.example.com/caplets
-caplets attach --remote-url https://caplets.example.com/caplets
+caplets attach https://caplets.example.com/caplets
 
 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

@@ -24,7 +24,7 @@ Codex:
 ```toml
 [mcp_servers.caplets]
 command = "caplets"
-args = ["attach", "--remote-url", "https://caplets.example.com/caplets"]
+args = ["attach", "https://caplets.example.com/caplets"]
 ```
 
 Generic MCP JSON:
@@ -34,32 +34,39 @@ Generic MCP JSON:
   "mcpServers": {
     "caplets": {
       "command": "caplets",
-      "args": ["attach", "--remote-url", "https://caplets.example.com/caplets"]
+      "args": ["attach", "https://caplets.example.com/caplets"]
     }
   }
 }
 ```
 
 ## Remote Login
 
-For a self-hosted remote, first create a short-lived Pairing Code on the server:
+For a self-hosted remote, start Remote Login from the client:
 
 ```sh
-caplets remote host pair --host-url https://caplets.example.com/caplets
+caplets remote login 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`.
-
-Then log in once on the client and configure the agent to launch attach:
+The command prints a short operator code and waits. On the host, a server-local
+operator reviews the pending login metadata and approves the code from the same
+server environment that owns the remote credential state:
 
 ```sh
-caplets remote login https://caplets.example.com/caplets
-caplets attach --remote-url https://caplets.example.com/caplets
+caplets remote host logins
+caplets remote host approve <code> --yes
 ```
 
-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.
+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`.
+The visible approval code is not an attach credential, but do not put Caplets access
+or refresh credentials in shell history, agent configs, or environment variables.
+
+After approval, configure the agent to launch attach:
+
+```sh
+caplets attach https://caplets.example.com/caplets
+```
 
 For Caplets Cloud native integrations, log in once and then set the Cloud URL selector:
 

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

@@ -152,7 +152,7 @@ Confirm the remote environment:
 ```sh
 caplets remote login https://caplets.example.com/caplets
 caplets doctor
-caplets attach --remote-url https://caplets.example.com/caplets
+caplets attach https://caplets.example.com/caplets
 ```
 
 If the URL belongs to Caplets Cloud, log in through Remote Login and keep the Cloud URL

apps/landing/src/data/landing.ts

@@ -92,9 +92,9 @@ export const whyCapletsProblems = [
 
 export const remoteCommands = {
   server: `caplets daemon install --start
-caplets remote host pair --host-url <url>`,
-  client: `caplets remote login <url> --code <pairing-code>
-caplets attach --remote-url <url>`,
+caplets remote host approve <code> --yes`,
+  client: `caplets remote login <url>
+caplets attach <url>`,
 } as const;
 
 export const remoteEndpoints = [