> 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/playlists/rulesets.md). # Rulesets Configure playlist synchronization behavior and advanced rules. Rulesets control direction, membership, ordering, aggregation, partitioning, capacities, and assignment. Use **Direct sync** for most setups. Choose **Custom** only when you need detailed settings. ### Presets * **Direct sync** — One-way, direct, managed membership, unordered, one target. * **Mirror source** — One-way, direct, mirrored membership, preserved order. * **Split large playlists** — Partitioned writes with capacity and stable assignments. * **Merge playlists** — Aggregate reads with direct writes. * **Limited account sharing** — Bidirectional aggregate reads and partitioned writes. * **Custom** — Exposes detailed ruleset fields. ### Membership #### Add only Adds missing source items to the destination. It never removes destination items. Use it when you also manage destination items manually. #### Managed only Adds missing source items and removes items CrossWatch previously managed. It leaves destination-only items unchanged. This is the normal **Direct sync** behavior. #### Mirror Makes destination membership match the source. It can remove destination items absent from the source. Use Mirror only when the source fully controls the destination. ### Ordering Use **Preserve** to request the source order on the destination. If reordering is unsupported, CrossWatch reports a warning. Mappings reject `preserve` when a destination is known to be unordered. ### Schema The current ruleset schema version is `1`. ``` direction: one_way | bidirectional initial_sync: source_authoritative read_mode: direct | aggregate write_mode: direct | partition membership: add_only | managed_only | mirror order: ignore | preserve deduplicate: canonical_id allocation: stable_first_fit rebalance: never overflow: block ``` Numeric fields: ``` per_endpoint_capacity aggregate_capacity maximum_targets ``` `track_assignments` controls stable item placement between runs. ### Aggregate, partition, and capacity Aggregate mode treats several playlist resources as one logical inventory. Partition mode distributes managed items across target endpoints. Advanced execution requires aggregate reads with partitioned writes. `stable_first_fit` assigns items predictably. `track_assignments` preserves those placements. `rebalance = never` avoids moving assigned items only to equalize targets. `overflow = block` prevents silently exceeding logical capacity. `per_endpoint_capacity` limits each target. `aggregate_capacity` limits all targets. `maximum_targets` limits target count. These values are ruleset controls, not provider guarantees. ### Built-in TraktFree ruleset `TraktFree` uses: ``` direction = bidirectional initial_sync = source_authoritative read_mode = aggregate write_mode = partition membership = managed_only order = ignore deduplicate = canonical_id allocation = stable_first_fit rebalance = never overflow = block per_endpoint_capacity = 250 aggregate_capacity = 1000 maximum_targets = 5 track_assignments = true ``` These capacities describe CrossWatch configuration. They do not guarantee provider plan limits. ### Safety and execution Large removal plans use the shared mass-delete guard. The decision uses suspect thresholds and `allow_mass_delete`. Verify both snapshots, profile selection, and baseline before allowing mass deletion. Dry runs calculate additions, removals, and ordering without provider writes. Use dry runs after changing topology or destructive rulesets. Plans track source, target, resolved, unresolved, addition, removal, reorder, and warning counts. Applied results are stored as `last_result` and shown in the UI. Unresolved items do not always fail the entire run. They could not be safely written. ### Recommended approach 1. Start with **Direct sync** and `managed_only`. 2. Run a dry run after ruleset or topology changes. 3. Review unresolved items before allowing stricter removals. 4. Use Mirror only when destination-only items should be removed. 5. Use aggregate and partition rulesets only for real capacity constraints. --- # 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/crosswatch/main-dashboard/navigation/playlists/rulesets.md?ask=&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.