feat(core): add stacked remote runtime

.changeset/stacked-remote-runtime.md

@@ -0,0 +1,6 @@
+---
+"@caplets/core": minor
+"caplets": minor
+---
+
+Add stacked remote runtimes with `caplets serve --transport http --upstream-url <url>`, make `caplets attach <url>` stdio-only, and carry per-session project context through attach/native remote sessions.

CONCEPTS.md

@@ -86,6 +86,12 @@ The process where a local agent-facing Caplets runtime connects to a trusted Cap
 
 Remote Attach uses Remote Profiles for trust and credentials. Long-lived attach traffic treats credentials as refreshable runtime state rather than fixed startup state.
 
+### Stacked Remote Runtime
+
+A local HTTP Caplets runtime that serves local Caplets while composing an upstream Caplets host through a configured upstream URL.
+
+Stacked Remote Runtime keeps project context session-scoped. `caplets attach` supplies the project root for a client session, while the long-running runtime owns env, Remote Profile, Project Binding, health, and composition behavior.
+
 ### 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.

README.md

@@ -141,6 +141,16 @@ args = ["attach", "https://caplets.example.com/caplets"]
 }
 ```
 
+`caplets attach <url>` is always the stdio client command for MCP configs. To run a
+long-lived local HTTP runtime that composes local and project Caplets with an upstream
+host, start the runtime separately:
+
+```sh
+caplets serve --transport http --upstream-url https://caplets.example.com/caplets
+```
+
+Then point agents at that local runtime with `caplets attach <local-runtime-url>`.
+
 Native integrations expose `caplets__code_mode` for multi-step TypeScript workflows over
 generated `caplets.<id>` handles. Progressive exposure adds `caplets__<id>` tools; direct
 exposure adds operation-level tools such as `caplets__<id>__<operation>`.

apps/docs/src/content/docs/agent-integrations.mdx

@@ -74,3 +74,12 @@ Use:
 ```
 
 For remote-backed MCP, use `caplets attach` instead of `caplets serve`.
+
+`caplets attach <url>` is stdio-only. If you want one local HTTP runtime to own environment,
+Vault, Remote Login, reloads, and logs while still composing an upstream host, run:
+
+```sh
+caplets serve --transport http --upstream-url https://caplets.example.com/caplets
+```
+
+Then configure the MCP client with `caplets attach <local-runtime-url>`.

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

@@ -4,7 +4,12 @@ description: Connect an agent to a remote Caplets runtime.
 ---
 
 Use `caplets attach` when the agent should connect to a remote or Cloud-backed Caplets
-runtime instead of starting local backends.
+runtime instead of starting local backends. `caplets attach <url>` is a stdio MCP adapter;
+it does not run an HTTP server.
+
+Use `caplets serve --transport http --upstream-url <url>` for a long-running stacked
+runtime that composes local user/global Caplets, per-session project Caplets, and an
+upstream Caplets host.
 
 ## Modes
 
@@ -68,6 +73,16 @@ After approval, configure the agent to launch attach:
 caplets attach https://caplets.example.com/caplets
 ```
 
+For a stacked local runtime, run the HTTP service outside the agent process:
+
+```sh
+caplets serve --transport http --upstream-url https://caplets.example.com/caplets
+```
+
+Then configure the agent with `caplets attach <local-runtime-url>`. The attach adapter
+sends its current working directory as the session project root, so project Caplets are
+resolved per attached client instead of from the long-running server's startup directory.
+
 For Caplets Cloud native integrations, log in once and then set the Cloud URL selector:
 
 ```sh
@@ -97,6 +112,11 @@ check.
 remote capability needs project-local context while the agent still talks to one Caplets
 MCP server.
 
+Stacked runtimes also attempt upstream Project Binding automatically when an attach or
+native session supplies a project root and the upstream supports Project Binding. If the
+upstream binding path is unavailable, local project Caplets and non-project upstream
+Caplets remain available with a diagnostic.
+
 Attach connects to the runtime attach API at `/v1/attach`. Ordinary MCP clients that are
 not using attach continue to connect to `/v1/mcp`, which still honors the configured
 exposure mode for each Caplet.

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

@@ -168,6 +168,15 @@ caplets attach --once
 `caplets attach --once` validates the configured Project Binding WebSocket URL once and
 exits.
 
+If an old config uses `caplets attach --transport http` or attach HTTP bind flags, replace
+that server command with:
+
+```sh
+caplets serve --transport http --upstream-url https://caplets.example.com/caplets
+```
+
+Keep MCP client configs on `caplets attach <url>`.
+
 ### Attach URL or workspace is wrong
 
 Expected symptom: the agent connects to a stale workspace, or the runtime reports that the
@@ -201,6 +210,10 @@ Run the agent from the project root, then retry the smallest Code Mode script th
 project Caplet. If the capability needs setup commands, run the commands listed in the
 Caplet's `setup` metadata before asking the agent to call it.
 
+For stacked runtimes, project-local Caplets come from the attach or native session's project
+root. The long-running HTTP server startup directory is not used as the active project for
+every client.
+
 ## OSV no-auth smoke test
 
 If you need a public capability to separate Caplets setup from credential problems, install