> ## Documentation Index
> Fetch the complete documentation index at: https://docs.getcargo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# State & Drift

> How cargo.state.json links your code to deployed Cargo resources, why you commit it, the lock file, and detecting changes made outside the CDK with cdk refresh.

## `cargo.state.json`

Every deploy writes `cargo.state.json` — a map from each code resource
(`kind:slug`) to the real uuid Cargo assigned it, plus its outputs and a content
hash:

```json theme={null}
{
  "version": 1,
  "workspaceUuid": "fbe3...",
  "resources": {
    "connector:hubspot": { "hash": "sha256:…", "uuid": "9c26…", "outputs": { "uuid": "9c26…", "datasetUuid": "f12c…" } }
  }
}
```

It's the authoritative link from code to deployed infra. Connectors and models
are slug-addressable and self-heal, but **plays, agents, tools, files and MCP
servers have no slug** — their stored uuid is the only way to re-find them.

<Warning>
  **Commit `cargo.state.json`.** If you lose it, uuid-only resources orphan and a
  re-deploy creates duplicates. Recover a lost link with
  `cargo-ai cdk import <id> <uuid>`.
</Warning>

It records only uuids, hashes and outputs — **never secret values**.

### Lock file

During a deploy/destroy/import the CDK writes sibling files next to
`cargo.state.json` — a `cargo.state.lock` (serializes concurrent runs), a
`cargo.state.bak.json` (rollback snapshot), and a `cargo.state.audit.jsonl`
(run log). Only `cargo.state.json` is committed; **git-ignore the rest**:

```gitignore theme={null}
cargo.state.lock
cargo.state.bak.json
cargo.state.audit.jsonl
```

A lock left by a dead process is reclaimed automatically; `--force` overrides one
you believe is stale.

## Drift

The CDK compares your code against state. It can also compare against the live
workspace to catch changes made **outside** the CDK (e.g. someone edits an agent
in the Cargo UI, or deletes a folder).

### Detect (read-only)

```bash theme={null}
cargo-ai cdk refresh
```

Re-reads every state-tracked resource and reports each as `unchanged`,
`modified externally`, or `deleted externally`. It changes nothing.

### Correct

```bash theme={null}
cargo-ai cdk deploy --refresh
```

Folds the drift into the plan before applying:

* **Modified externally** → re-applies your code over it (**code wins**).
* **Deleted externally** → recreates it.

<Note>
  Drift is measured against the state captured at the last deploy, not guessed
  from code — so it reflects real changes to the live resource. A transient read
  error is reported as `unknown`, never as a deletion, so a network blip can't
  trigger a mass re-create.
</Note>

## Secrets and drift

Because `secret()` values are excluded from the content hash, **rotating a secret
does not show as drift** and a plain `deploy` won't push the new value (nothing
changed). To roll a rotated secret, re-apply the resource (make any other change,
or use `--refresh`). Use `env()` instead if you *want* a config value tracked in
the hash.