# Best practices Use these defaults unless you have a reason to deviate. {% hint style="success" %} This page looks long because it covers edge-cases. Most users do not need to change much. If you want a safe setup, follow the defaults below. Start with **one pair** and **one feature**. {% endhint %} CrossWatch (CW) is safest when you start small and keep runs predictable. {% hint style="warning" %} CrossWatch is not the right tool for very large libraries. If your volumes are outside the recommended ranges, do not force it. Check [Limitations](/getting-started/limitations.md) first. {% endhint %} ### Default setup (recommended) * Direction: **Media server -> tracker** * Watchlist: start **one-way**. Optional: move to **two-way** after clean runs. * History: do a **one-way seed** once. Then disable History and use scrobbling. * Ratings: keep **one-way** (server -> tracker) {% hint style="warning" %} Do not switch to **tracker -> media server** unless you have a clear reason. Trackers often contain items your server does not have. That means History and Ratings can fail, stay unresolved, or create noisy plans. For most setups, only sync data into a media server when the item already exists in that library. Related: [Trackers vs. Media Servers](/related-information/trackers-vs.-media-servers.md) and [Tracker to Media Server](/related-information/tracker-to-media-server.md) {% endhint %} {% hint style="warning" %} CrossWatch 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 This gets worse when a provider returns delayed, partial, or inconsistent data. Use bidirectional sync carefully. It may look like the better option. For most users, **one-way** sync is still the safer and more predictable setup. {% endhint %} ### Golden rules * Pick a **source of truth** for each pair. * Expect conflicts. * **Source wins** on conflicts. * Start with **one pair** and **one feature**. * Enable only what you need. Default conflict policy: * If both sides changed an item, keep **Source**. * If Source removed and Target added, treat it as **remove**. ### 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. ### Watchlists Watchlists are the safest feature to run two-way. Still start one-way. Two-way is only sane when: * IDs are stable on both sides (TMDb/TVDB/IMDb). * You have multiple clean runs. * You tested adds and deletes in both directions. Optional: * Use a short grace period for just-added or just-removed items. * This reduces churn during premieres and rematches. ### History Default: **Media server -> tracker**. Recommended workflow: 1. Run History one-way once to seed the tracker. 2. Disable History in the pair. 3. Enable scrobbling for new plays. Avoid enabling **Remove** for History. It only makes sense in niche cases. ### Ratings Default: **Media server -> tracker**. Avoid two-way unless you accept noise: * Providers disagree on episodes, specials, and editions. * Rating scales differ (1–10 vs stars/hearts). If you do two-way: * Pick a source of truth. ### Changing pairs and resets Do not constantly tweak direction, mode, or enabled features. If you do, reset state so planning recalculates cleanly. #### When to reset state and provider cache Reset **both** when you make a major sync change or the next plan looks unsafe. Common triggers: * You switch **one-way ↔ two-way** * You change library filters or whitelists on an active pair * You update CrossWatch 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 If a run wants to remove far more than expected: 1. Stop 2. Restore from the provider’s own undo/history if needed 3. Clear local state and provider cache 4. Rerun in **Dry run** #### When to avoid resetting * You only changed schedules. * You only changed logging levels. * You only changed UI/runtime preferences that do not affect data. * Normal syncs look correct and item counts are stable {% hint style="warning" %} Resetting clears the planner memory. The next run rebuilds deltas from zero. With delta providers (example: SIMKL), avoid frequent resets. They defeat incremental syncing. They may also increase API pressure and risk throttling. {% endhint %} {% hint style="info" %} After a reset, treat the next run like a first run. Use **Dry run**. Start with one pair and one feature. {% endhint %} ### Scheduling * Avoid overlaps. * Keep runs predictable. ### Debugging * Use normal logs day to day. * Enable debug only while investigating. * Use **Analyzer** for missing IDs and broken matches. * Use **Editor** for manual policy and blocking. ### Related topics * [Trackers vs. Media Servers](/related-information/trackers-vs.-media-servers.md) - pick a sane source of truth * [Tracker to Media Server](/related-information/tracker-to-media-server.md) - why the direction is risky * [Media Server to Media Server](/related-information/media-server-to-media-server.md) - why cross-sync is fragile * [Limitations](/getting-started/limitations.md) - when CrossWatch is the wrong tool for the job * [Syncing](/getting-started/first-time-setup/what-do-you-need/syncing.md) - the step-by-step setup * [Webhook or Watcher](/getting-started/first-time-setup/what-do-you-need/webhook-or-watcher.md) - scrobbling setup ### Summary Start one-way. Prefer **media server -> tracker**. Seed History once. Then rely on scrobbling. Use dry runs, backups, and a clear source of truth. ### Next steps * Set up your pair toggles and safety controls: [Configure Pairs](/crosswatch/configure-pairs.md). * Configure predictable runs and avoid overlaps: [Scheduling](/crosswatch/scheduling.md). * Turn on real-time plays after the first history seed: [Watcher](/crosswatch/scrobble/watcher.md). * Debug mismatches and missing IDs: [Analyzer](/crosswatch/tools/analyzer.md). --- # 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/getting-started/best-practices.md?ask= ``` 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.