# Server Sync and Remote Execution

The `PlanSyncClient` synchronizes local resources (actions, skills, tools,
projects) with a remote CleverAgents server and supports remote plan
execution, apply, and status queries.

## Configuration

Sync uses the same server connection configured via the
[HTTP client](server_client_http.md) settings (`CLEVERAGENTS_SERVER_BASE_URL`,
`CLEVERAGENTS_SERVER_API_TOKEN`).

## Sync Scope

By default, sync transfers the minimal set of resources required for
a plan.  Use scope flags to control which entity types are synchronized:

| Flag | Entity type |
|---|---|
| `--actions` | Actions |
| `--skills` | Skills |
| `--tools` | Tools |
| `--projects` | Projects |

## Conflict Resolution

When a local entity and a server entity share the same name but differ
in content, the conflict resolution policy determines the outcome:

| Policy | Behaviour |
|---|---|
| `local_wins` | Local version overwrites the server version |
| `server_wins` | Server version is kept; local changes are discarded |

If no policy is set and a conflict is detected, the client raises a
`ValueError` with an explanatory message.

## Dry-Run Mode

Pass `dry_run=True` to `sync_all()` to preview what would be
synchronized without executing any mutations on the server.

## Sync Summary

After a sync operation the client returns a `SyncSummary` with counts:

| Field | Meaning |
|---|---|
| `created` | Items created on the server |
| `updated` | Items updated on the server |
| `skipped` | Items unchanged (already in sync) |
| `errors` | Items that failed to sync |

## Remote Execution

```python
from cleveragents.client.sync_client import PlanSyncClient

sync = PlanSyncClient(http_client)
result = sync.execute_plan("PLAN001")
print(result.status, result.remote_plan_id)
```

## Error Handling

Sync and execution errors propagate from the underlying HTTP client.
See [Server HTTP Client — Connection Errors](server_client_http.md#connection-errors).