> 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/getting-started/best-practices.md).

# Best practices

Recommended default

Use these defaults unless you have a reason to deviate.

CrossWatch (CW) is safest when you start small and keep runs predictable.

{% hint style="warning" %}
**Experimental providers:** Check the provider guide and support matrix for experimental status and restrictions. A version number alone does not guarantee full support.

Start with one-way syncs. Keep all adapter settings at their default values.
{% endhint %}

### Default setup (recommended)

* Direction: **Media server -> tracker**
* Watchlist: start **one-way**. Can be one-way or two-way.
* History: do a **one-way seed** once. Then disable History and use scrobbling.
* Ratings: keep **one-way** (Media server -> tracker), where both providers support ratings.
* Progress: keep **one-way** (Media server -> tracker)

{% hint style="warning" %}
Do not switch to **tracker -> media server** unless you have a clear reason.

Trackers can contain items your server does not have.

For most setups, **only sync data into a media server when the item already exists in that library.**

Related: [Trackers vs. Media Servers](https://wiki.crosswatch.app/related-information/trackers-vs.-media-servers.md) and [Tracker to Media Server](https://wiki.crosswatch.app/related-information/tracker-to-media-server.md)
{% endhint %}

CW supports **real bidirectional synchronization**. Changes on either platform can sync in both directions. That adds flexibility. It also adds risk. Because both sides can introduce changes, you are more likely to see:

* conflicts, duplicate items, unintended overwrites, propagated deletions

**Use bidirectional (two-way) sync carefully.**

It may look like the better option. For most users, **one-way** sync is still the safer and more predictable choice.

### Metadata agents (recommended)

Good metadata is the difference between stable ID matching and messy title guessing.

Use these defaults:

* **Plex Media Server**: use the default **Plex Movie** and **Plex TV Series** metadata agents.
* **Emby** and **Jellyfin**: use **TMDb** metadata.

For anime tracker pairs, enable **Anime ID Mapping**.

Guide: [Anime ID Mapping](https://wiki.crosswatch.app/crosswatch/settings/connections/metadata/anime-id-mapping.md)

### Changing pairs and resets

After changing direction, mode, or enabled features, review a dry run before applying changes.

#### When to rebuild sync state and retry provider items

Use **Rebuild sync state** when you deliberately need a fresh comparison. Use **Retry provider items** to retry previously unresolved items. If a plan looks unsafe, stop and check the pair settings and provider data before resetting anything.

Situations that need a careful review:

* You switch **one-way ↔ two-way**
* You change library filters or whitelists on an active pair
* You update CW and the first plan looks wrong
* You backfill history with old dates and the provider uses delta reads
* You see an unexpected large remove plan


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://wiki.crosswatch.app/getting-started/best-practices.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
