# Remote Project Support

The `RemoteProjectClient` resolves and executes projects hosted on a
remote CleverAgents server.  It provides namespace-aware project
resolution, execution request wiring, and a TTL-based project cache.

## Project Resolution

Projects are resolved by name using the following fallback order:

1. Exact match in the specified namespace
2. Exact match in the `default` namespace
3. `ResourceNotFoundError` with an explanatory message

Server aliases are also supported — a project can be referenced by its
alias rather than its full namespace-qualified name.

## Remote Execution

```python
from cleveragents.client.remote_project import RemoteProjectClient

client = RemoteProjectClient(http_client)
project = client.resolve_project("my-project", namespace="org")
result = client.request_execution(project.project_id)
```

## Caching

Resolved projects are cached with a configurable TTL (default 5 minutes)
to minimize repeated server calls.  Cache entries are keyed by
`(name, namespace)` tuples.

| Method | Description |
|---|---|
| `invalidate_cache()` | Clear all cached entries |
| `invalidate_cache(namespace="org")` | Clear cache for a specific namespace |

## CLI Scaffolding

| Command | Description |
|---|---|
| `agents project list --remote` | List projects available on the server |
| `agents plan use --remote` | Create a plan targeting a remote project |

Both commands require a configured server connection (see
[HTTP client configuration](server_client_http.md#configuration)).

## Error Handling

| Exception | Cause |
|---|---|
| `ResourceNotFoundError` | Project not found on the server |
| `ServerConnectionError` | Server unreachable |
| `AuthorizationError` | User lacks access to the requested project or namespace |