> For the complete documentation index, see [llms.txt](https://wiki.crosswatch.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/editor.md).
# Editor
The **Editor** manages stored provider data and manual policy.
Use it to:
* review stored provider state
* correct titles, years, media types, IDs, ratings, watched dates, and progress
* add manual items or block future syncs
* import provider state or send selected rows directly
* edit supported playlist endpoints
{% tabs %}
{% tab title="End users" %}
### Quick start
{% stepper %}
{% step %}
### 1. Pick a source
Choose one of the following:
* **Current State** — provider baselines with manual policy
* **Manual Overrides** — saved manual additions, corrections, and blocks
* **Local Tracker** — CrossWatch Local Tracker data
* **Playlist Endpoint** — a configured provider playlist
{% endstep %}
{% step %}
### 2. Pick a dataset
Choose **Watchlist**, **History**, **Ratings**, or **Progress**.
Playlist Endpoint uses its configured playlist data.
{% endstep %}
{% step %}
### 3. Pick a scope
For **Current State** and **Manual Overrides**, select a provider and profile.
For **Local Tracker**, select a profile and workspace.
For **Playlist Endpoint**, select the configured endpoint.
{% endstep %}
{% step %}
### 4. Edit or select rows
Edit, add, block, or select rows.
{% endstep %}
{% step %}
### 5. Save or send
Use **Save changes** to persist changes for the current source.
Use **Send to** to write selected rows to other provider profiles.
{% endstep %}
{% endstepper %}
### Sources
#### Current State
Current State shows the latest stored baseline for a provider, together with manual additions, corrections, and blocks.
Current State does not query the provider live when you open the view. It shows the state stored by the most recent relevant sync or provider state import.
#### What you can do
1. Review a provider baseline
2. Block baseline rows
3. Add manual rows
4. Replace incorrect baseline items with manual corrections
5. Edit existing manual corrections
6. Inspect advanced item fields
7. Send selected rows to another provider
8. Import fresh provider state, when import is enabled
#### Saving Current State
Baseline rows are not directly rewritten by a normal Editor save.
When you save:
1. Deleted baseline rows become blocks
2. Added rows become manual additions
3. Replaced rows become manual corrections
4. Policy is written to `/config/state.manual.json`
5. Policy is also mirrored into the manual section of `/config/state.json`
This separation allows policy to survive a later rebuild of provider baselines, provided that `state.manual.json` is retained.
#### Manual Overrides
Manual Overrides shows only the policy stored for the selected provider, profile, and dataset.
It does not show the complete provider baseline.
Use this source when you want to review or manage:
1. Manual additions
2. Manual metadata corrections
3. Item blocks
Manual Overrides is useful when a provider baseline contains thousands of rows and you only want to inspect the changes introduced through Editor.
#### Saving Manual Overrides
Save writes the displayed additions and blocks to:
`/config/state.manual.json`
When `state.json` exists, the policy is also mirrored into its manual section.
Removing a manual addition removes that correction from policy. It does not remove an item from the connected provider.
#### Local Tracker
Local Tracker shows data stored by the CrossWatch provider module.
Local Tracker data is grouped by Profile and Workspace. A workspace normally represents a sync pair that uses Local Tracker.
Supported datasets depend on the files available in that workspace and can include:
Watchlist
History
Ratings
Progress
#### What Local Tracker changes mean
Local Tracker rows are read from the local tracker files.
Editor does not overwrite those tracker files when you click Save.
Instead, Save stores corrections and blocks as policy for the CrossWatch provider. These corrections are applied when Local Tracker is used as the source of a future one way sync.
Connected provider accounts are not changed by a Local Tracker save.
#### Local Tracker limitations
Local Tracker policy affects future one way syncs from Local Tracker.
It does not rewrite an existing provider account immediately.
Use Send to when selected Local Tracker rows should be written to a provider immediately.
#### Playlist Endpoint
Playlist Endpoint connects Editor to playlists configured on the Playlists page.
Unlike Current State, Manual Overrides, and Local Tracker, this source works directly with the provider playlist.
The available actions depend on the provider endpoint capabilities.
An endpoint may support:
1. Reading items
2. Adding items
3. Removing items
4. Reordering items
Smart or read only playlists cannot be edited.
#### Saving a Playlist Endpoint
Editor compares the displayed rows with the current provider playlist.
Depending on endpoint support, Save can:
1. Add new items
2. Remove missing items
3. Apply a new order
Provider warnings are shown where relevant. Some providers may require confirmation before removals.
Playlist changes are applied directly to the connected provider.
### Send to (selective sync)
Send to lets you send selected rows directly to one or more provider profiles.
This is a selective write operation. It does not run a complete sync pair and does not create a permanent sync rule.
| | |
| -------------------------------- | -------------------------------- |
|  |  |
#### Supported datasets
Send to supports:
Watchlist
History
Ratings
Progress
Playlist rows can also be selected and sent as Watchlist data.
#### How to use Send to
1. Open any Editor source
2. Select one or more active rows
3. Click Send to in the selection toolbar
4. Select one or more provider profiles
5. Click Send selected data
6. Review the result for each target
Only active rows are sent. Blocked or deleted rows are excluded.
#### Available targets
Editor only shows provider profiles that:
1. Are configured
2. Support writing the selected dataset
3. Are not the provider profile currently being viewed
Multiple profiles can be selected in one operation.
The selected targets are remembered separately for each dataset in the browser.
#### Data requirements
Watchlist rows require enough metadata to identify the item.
History rows require a watched timestamp.
Ratings rows require a rating from 1 to 10.
Progress rows require a stored progress value.
Items without sufficient data are reported as invalid and are not sent.
External IDs provide the most reliable matching. IMDb, TMDB, TVDB, Trakt, SIMKL, AniList, and MAL IDs may be used when supported by the source and target.
Title and year matching may be available for some providers, but it is less reliable.
#### What Send to changes
Send to calls the target provider write operation directly.
It only performs additions or updates supported by that dataset. It does not remove items from the destination.
Each selected target is processed independently. One target can succeed while another returns unresolved items or errors.
The result includes:
Sent
Attempted
Skipped
Unresolved
Errors
Invalid
Confirmed items are also reflected in the target profile baseline inside Current State. This keeps the stored state aligned with the direct send where confirmation is available.
Send to does not save unsaved Editor changes automatically. Save corrections first when the edited values must become part of policy.
### Import provider state
Current State can import live datasets from a configured provider profile.
The Import provider state panel is only shown when provider state import is enabled. This is normally controlled through debug or developer import settings.
Import can be used without creating a sync pair first.
#### Supported imports
Depending on provider support, you can import:
Watchlist
History
Ratings
Progress
Only configured providers and supported datasets are shown.
#### Import modes
Replace baseline, replaces the selected provider baseline for that dataset with the imported result
Merge, keeps existing baseline rows and adds or updates rows returned by the provider
#### How to import
1. Set Source to Current State
2. Expand Import provider state
3. Pick a Provider
4. Pick a Profile
5. Select one or more datasets
6. Choose Replace baseline or Merge
7. Click Import
Import reads from the provider API and writes the result into the appropriate baseline in `state.json`.
It does not modify the provider account.
Existing manual additions and blocks remain in `state.manual.json`.
Provider specific library filters and configured scopes are passed through the provider adapter. The exact filtering behavior therefore depends on the provider and dataset.
Large imports can take time. The Editor shows import progress while the request is running.
### Blocking items
Blocks are policy rules.
A block applies to a specific:
Provider
Provider profile
Dataset
Item key
When an item is blocked, it is excluded when that provider profile is used as the source of a future sync for that dataset.
A block does not delete the item from the provider.
#### Block one item
1. Set Source to Current State or Local Tracker
2. Pick a dataset
3. Pick the provider, profile, or workspace
4. Find a baseline row
5. Click the block icon
6. Click Save changes
Click the block icon again before saving to unblock the row.
#### Review blocked items
Enable the Blocked type chip to show only blocked baseline rows.
Manual Overrides also shows stored block entries, including blocks for rows that are no longer present in the current baseline.
### Block rules
Block rules provide a faster way to block or unblock all baseline rows of one media type.
The panel is available in policy sources for History, Ratings, and Progress.
#### Use Block rules
1. Open Current State, Manual Overrides, or Local Tracker
2. Select History, Ratings, or Progress
3. Expand Block rules
4. Choose a media type
5. Click Block all or Unblock all
6. Click Save changes
Block all only affects baseline rows of the selected type.
Manual additions are not converted into blocks by this operation.
### Manual additions
Manual additions represent items that should be treated as present in a source, even when they are not part of its current baseline.
#### Add an item
1. Click Add row
2. Enter or generate a unique Key
3. Select the media Type
4. Enter a Title and Year where available
5. Add external IDs
6. Enter the dataset specific value
7. Click Save changes
For History, enter a watched date.
For Ratings, enter a rating.
For Progress, enter playback progress.
A nonempty row must have a Key before it can be saved.
External IDs are strongly recommended. Rows based only on title and year may not be writable to every provider.
### Correcting baseline items
Baseline rows in policy sources are protected from direct editing.
This prevents accidental modification of the stored provider snapshot.
To correct a baseline item, use the replace or search action.
Editor then:
1. Creates a manual correction
2. Blocks the original key where required
3. Stores the correction in policy
This allows the original provider baseline to remain intact while future syncs use the corrected item.
### Advanced fields
Policy sources include an Advanced fields action.
This view shows:
1. The row source
2. The dataset
3. The canonical key
4. The row origin
5. The complete stored item data
Use Advanced fields to inspect IDs, show IDs, episode coordinates, timestamps, provider metadata, and other fields not displayed in the main table.
### Editing dataset values
#### Watchlist
Watchlist rows represent item presence.
Supported media types are normally Movie, Show, and Anime.
#### History
History rows include a watched timestamp.
The Extra column opens the watched date editor.
Season and episode rows may also include series metadata and episode coordinates.
#### Ratings
Ratings rows include a rating from 1 to 10.
The Extra column opens the rating editor.
#### Progress
Progress rows contain stored playback position or percentage data.
The Extra column opens the progress editor.
Progress shown in Current State or Local Tracker is stored state. It is not a live provider query.
Use Import provider state or run the relevant Progress sync to refresh it.
The Playback Progress Manager uses live provider queries and may therefore show different values.
### Episodes and seasons
Episode rows can display the series title together with season and episode coordinates, for example:
`Series Name, S01E02`
Search accepts formats such as:
`S01`
`S01E02`
Episode and season corrections can use the replacement workflow to select the correct item or coordinates.
### Filtering and sorting
#### Filter
The filter searches across:
Title
Series title
Season and episode code
Key
Media type
Year
External IDs
Multiple words can be entered. All entered terms must match the row search data.
#### Type filters
Available type filters include:
Movies
Shows
Anime
Seasons
Episodes
Blocked
Watchlist only uses Movie, Show, and Anime.
At least one regular media type remains enabled.
#### Sorting
Rows can be sorted by:
Key
Type
Title
Extra
Extra sorting depends on the dataset.
For Ratings, Extra sorts by rating.
For History, Extra sorts by watched date.
### Selection
Rows can be selected individually or by selecting the current page.
The table shows up to 100 rows per page.
Selection enables bulk actions:
Send to
Block or Delete
Unblock or Restore
Clear selection
Select page only selects rows on the current page.
Selection is cleared after a completed Send to operation.
### Saving
Save changes behaves differently for each source.
#### Current State
Saves manual additions, corrections, and blocks as policy.
Provider baselines are not overwritten.
#### Manual Overrides
Saves only the displayed policy additions and blocks.
Removing a row removes that manual override.
#### Local Tracker
Saves corrections and blocks as CrossWatch provider policy.
Local tracker data files are not overwritten.
#### Playlist Endpoint
Applies supported additions, removals, and reordering directly to the provider playlist.
### Policy backup and restore
Policy Backup protects manual additions, corrections, and blocks.
#### Export
Policy Export downloads:
`crosswatch-state-policy.json`
The export includes policy for provider profiles and Local Tracker profiles stored in `state.manual.json`.
It does not contain complete provider baselines.
#### Import
Policy Import merges the imported policy into the existing policy by default.
Imported policy is also mirrored into `state.json` when that file exists.
Use a policy backup when replacing `state.json`, moving CrossWatch to another installation, or testing large policy changes.
Importing policy does not modify connected providers directly.
{% endtab %}
{% tab title="Power users" %}
### File locations
#### Current State baseline
`/config/state.json`
Contains stored provider baselines, runtime state, and mirrored manual policy.
#### Manual policy
`/config/state.manual.json`
Contains persistent manual additions, corrections, and blocks.
#### Local Tracker
The root is configured through:
`crosswatch.root_dir`
The default Docker location is:
`/config/.cw_provider`
Additional Local Tracker profiles are stored below:
`/config/.cw_provider/profiles/`
Editor discovers Local Tracker workspaces from the available Watchlist, History, Ratings, and Progress files.
Editor reads these files but saves corrections separately as policy.
### Current State storage
Current State reads its provider baseline from:
`/config/state.json`
It reads manual policy from:
`/config/state.manual.json`
### Editor internals
Editor combines several data layers.
For Current State:
Provider baseline from `state.json`, plus policy from `state.manual.json`
For Manual Overrides:
Policy additions and blocks only
For Local Tracker:
Local tracker rows, plus CrossWatch provider policy
For Playlist Endpoint:
A live playlist snapshot from the provider
Normal Save updates policy for Current State, Manual Overrides, and Local Tracker.
Selective Send calls the provider add operation directly for each selected target.
Provider state import reads live provider indexes and stores them as baselines.
Playlist Endpoint Save uses provider playlist add, remove, and reorder operations according to endpoint capabilities.
{% endtab %}
{% endtabs %}
### Related topics
* [Quick Add](/crosswatch/main-dashboard/navigation/quick-add.md)
* [Watchlist](/crosswatch/main-dashboard/navigation/watchlist.md)
* [Main dashboard](/crosswatch/main-dashboard.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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, and the optional `goal` query parameter:
```
GET https://wiki.crosswatch.app/crosswatch/main-dashboard/navigation/editor.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
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.