# Editor

Editor lets you inspect and modify CrossWatch local data. It has two modes. Each mode writes to different files.

{% hint style="warning" %}
Editor can change the next sync plan. Back up before risky edits.
{% endhint %}

### Quick start

{% stepper %}
{% step %}

### Pick a mode

* **CW Tracker**: edit local backup data. Powered by the [CrossWatch module](/blueprint-architecture/sync/_mod_crosswatch.md).
* **Current State**: edit manual policy layered on top of provider state.
  {% endstep %}

{% step %}

### Pick a dataset

Choose **Kind**:

* Watchlist
* History
* Ratings
  {% endstep %}

{% step %}

### Pick a scope

* CW Tracker: pick a **Snapshot** (local tracker snapshot).
* Current State: pick a **Provider**.
  {% endstep %}

{% step %}

### Edit and save

Make changes in the grid, then click **Save**.
{% endstep %}
{% endstepper %}

### Modes (what they mean)

#### CW Tracker mode

Edits CrossWatch’s local backup state.

This is the data used by:

* [CrossWatch module](/blueprint-architecture/sync/_mod_crosswatch.md) (Sync layer)
* [Adapter: CrossWatch](/crosswatch/providers/synchronization/adapter-crosswatch.md) (UI + configuration)

Best for:

* fixing local tracker rows
* cleaning up snapshots and insights

#### Current State mode

Edits manual policy on top of provider baselines. It keeps your changes separate so they survive a rebuild.

Best for:

* blocking items from syncing out of a provider
* manual adds you want to “stick”
* importing a provider dataset before your first pair run

### CW Tracker mode

CW Tracker mode edits local tracker files.

What you can do:

* fix title/year/IDs
* adjust ratings
* adjust watched timestamps
* delete junk rows

Snapshot behavior:

* You can view **Latest** or an older snapshot.
* **Save** writes to the current state file for that kind.
* It does not modify older snapshot files.

{% hint style="info" %}
CW Tracker snapshots are local tracker backups. They are different from the **Captures** tool, which captures provider datasets for rollback.
{% endhint %}

#### Snapshot retention (CW Tracker)

CW Tracker snapshots use a simple retention policy:

* `max_snapshots`: default **64**
* `retention_days`: default **30**

Older snapshots are pruned automatically when you save/import and the limit is exceeded.

Snapshot filenames are timestamped (UTC) and include the kind, for example:

* `YYYYMMDDTHHMMSSZ-watchlist.json`
* `YYYYMMDDTHHMMSSZ-history.json`
* `YYYYMMDDTHHMMSSZ-ratings.json`

### Current State mode

Current State mode edits `state.json` safely by writing policy into a separate file.

#### What you are really editing

1. Provider baselines are read from `/config/state.json`
2. Your manual changes are stored in `/config/state.manual.json`
3. The editor applies your policy back into `state.json`, so a fresh `state.json` can be “retrained” from policy

#### Provider selector

In this mode the snapshot dropdown becomes **Provider**: Plex, SIMKL, Trakt, MDBList, Jellyfin, Emby, and any other providers present in your state.

#### Import datasets (populate `state.json`)

In **Current State**, you can import live datasets directly from a provider (without setting up a sync pair first). This populates the provider baseline inside `state.json`, so you can immediately review, edit, and block items before you run any syncs.

How to import:

1. Set **Data** to **Current State**
2. Expand **Import datasets**
3. Pick a **Provider**
4. Choose which datasets to import: **Watchlist**, **History**, **Ratings**
5. Choose **Replace baseline** (overwrite that provider’s baseline for selected datasets) or **Merge**
6. Click **Import**

Notes:

* The provider dropdown only shows providers that are available/configured.
* The dataset list only shows what that provider supports.
* For **Plex/Jellyfin/Emby**, **History** and **Ratings** imports follow your library whitelists.
  * If you whitelist specific libraries for a feature, the import includes **only items from those libraries**.
  * If you don’t configure whitelisting, imports include **all visible libraries**.
  * Guide: [Library Whitelisting](/crosswatch/library-whitelisting.md).
* Import runs against live provider APIs. It can take a while; the editor shows a progress indicator while it’s running.
* Import updates the baseline in `state.json`. Your policy still lives in `state.manual.json`.

#### Blocking items

Blocking is provider-global policy. If you block an item on a provider, it won’t sync out from that provider.

How to block, step by step:

1. Set **Data** to **Current State**
2. Pick **Kind**
3. Pick **Provider**
4. Find the item, click the **trash icon** on the baseline row
5. Click **Save**

Click the trash icon again to unblock, then save.

Important: blocking is policy. The orchestrator must apply policy during planning and execution for it to affect sync.

#### Bulk policy

Bulk policy is a faster way to block/unblock whole media types (per provider) in **Current State**.

1. Set **Data** to **Current State**
2. Expand **Bulk policy**
3. Choose a type (movie/show/etc.)
4. Click **Block all** or **Unblock all**
5. Click **Save**

#### Manual adds

Manual adds let you introduce items that should be treated as present on the selected provider, even if the baseline snapshot does not include them yet.

1. Click **Add row**
2. Fill a unique **Key**
3. Set **Type**: movie, show, episode
4. Fill **IDs** if possible (IMDb or TMDB strongly recommended)
5. Click **Save**

If you only provide title and year, matching can be weaker, and targets may not be writable without IDs.

#### Episodes show name

For episode rows, the editor shows the **series name** under the episode title when it is available in the data.

### Filtering, sorting, types

#### Filter

The filter searches across key, title, type, year, IDs, and series title for episodes.

#### Type chips

You can toggle Movies, Shows, Episodes. At least one type must stay enabled.

#### Sorting

You can sort by Key, Type, Title, Extra. Extra sorting depends on the kind.

### Table columns

<details>

<summary>Table columns</summary>

Columns:

1. Action (trash icon)
2. Key
3. Type
4. Title
5. Year
6. IMDb
7. TMDb
8. Trakt
9. Extra

Extra depends on Kind:

* Ratings: rating picker
* History: `watched_at` editor
* Watchlist: no extra field

</details>

### Saving

#### CW Tracker save

Save overwrites the current tracker state file for the selected kind and creates a snapshot if snapshotting is enabled.

#### Current State save

Save writes policy to `/config/state.manual.json`, then applies it into `/config/state.json`.

Provider baselines are not overwritten by this save (except when you explicitly use **Import datasets**).

### Backup and restore

#### CW Tracker backup, restore

Tracker backup exports a ZIP containing current tracker state files and all tracker snapshots.

Tracker import accepts:

1. A ZIP created by the tracker export
2. A JSON state file for a kind
3. A JSON snapshot file for a kind

#### Current State policy backup, restore

Policy backup exists so you do not lose blocks and manual adds when `state.json` is replaced.

1. **Policy Download** exports the policy JSON
2. **Policy Import** merges an imported policy into the current policy by default

If you start with a fresh `state.json`, import your policy backup to bring back your blocks and manual adds.

### File locations

Paths on disk

Current State:

* Snapshot: `/config/state.json`
* Policy: `/config/state.manual.json`

CW Tracker:

* Stored under CrossWatch’s local tracker root directory.
* Default root is derived from `crosswatch.root_dir`.
  * In Docker, this usually resolves under `/config` (example: `/config/.cw_provider/`).
* Key paths (defaults):
  * `state.json`: live tracker data
  * `state.manual.json`: manual overrides / policy
  * `pair.json`: ID mapping cache used for cross-provider pairing
  * `snapshots/`: timestamped tracker snapshots per kind
    * Example default: `/config/.cw_provider/snapshots/`

Easiest way to move it: use the Tracker ZIP export/import.

### Safety notes

* CW Tracker edits affect local backup data and insights.
* Current State policy can affect sync behavior (blocks and manual adds).
* Import datasets changes provider baselines in `state.json`.

If you break something, restore from backup or remove policy entries and save again.

### Editor internals (optional)

Implementation details are intentionally not documented here yet.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://wiki.crosswatch.app/crosswatch/tools/editor.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.