Write the guide for the unmatched items, which is the question this plugin will be asked most

[iderex]

The most common report against this plugin will be that some items are not syncing. Nearly all of those will be items that did not match, and nearly all of those are metadata problems on one side that the operator can fix themselves.

The guide takes each unmatched reason this plugin records and says what causes it, how to confirm it on the server, what fixes it, and what does not. It also says plainly which cases have no fix: an item with no identifiers anywhere will not sync, and the guide does not offer a setting instead of the truth.

Done when

• Every unmatched reason has a section, and a check asserts the reasons in the code and the sections in the document are the same set.
• Each section names what the operator sees on the status page and what they should see afterwards.
• The two cases people ask about most are worked through in full: a series with different orderings on the two servers, and a film present on both with different scrapers.
• The guide states which fixes require a metadata refresh and which take effect at the next sweep.

Scope: docs/.

[iderex]

Left unstarted, and it is a document whose content is defined by code that does not exist.

Every section of the guide is one unmatched reason, and the reasons are declared by #26, which has not landed. The first bullet asks for a check asserting that the reasons in the code and the sections in the document are the same set, so the document cannot be written ahead of the vocabulary without the check being either absent or green over two empty sets.

The two worked examples in the third bullet do not depend on that vocabulary and are the part with the most value per line: a series with different orderings on the two servers, and a film present on both with different scrapers. Both are questions about what an operator does on their own server rather than about what this plugin records, and both could be written against docs/matching.md, which exists and already says which kinds carry state and by which key.

What the issue gets right and should not be softened when somebody takes it: it says plainly which cases have no fix, and that an item with no identifiers anywhere will not sync. The README now says the same thing in the reader's language. A guide that offers a setting instead of that truth is the failure this issue names, and it is the one a support thread will push for.

Nothing on the mainline was changed for this reading. It had no second reader.

[iderex]

Three of the four conditions are met on the mainline and the fourth is not mine to meet. #215 merged as 51bd370a1a2c8b57d57f7f5061fdf46b7d8b330d.

The one reading here says the guide cannot be written because the reasons are declared by #26 and that has not landed. That was accurate when it was written and it is not the state now. The reasons are in the sources, in two enumerations rather than one, and the guide is held to both:

git show origin/master:Jellyfin.Plugin.WatchSync/Matching/MatchKeyRefusal.cs | grep -cE '^    [A-Z][A-Za-z]+,'
8

git show origin/master:docs/unmatched.md | grep -cE '^### `'
9

Seven of those eight are a reason, None is not, and the two answers that are not a match bring the set to nine. UnmatchedGuideTests reads the vocabulary off the two enumerations rather than out of a list beside it, so a member added to either joins the set without anybody editing the test.

What the first condition now has

A section per reason, and a check refusing three sets disagreeing: the reasons in the sources, the sections of the guide, and the rows of the table that says when a repair takes effect. I deleted the NumberingBelowZero section and one leg turned red, then restored it and deleted the NoMatch row instead and a different leg turned red. One leg each time, which is what says the two are about the two halves of the document rather than one thing counted twice. The near-miss fixture carries the third direction, a heading misspelled by one character, with its repair beside it.

The third and fourth

Both worked cases are written in full. A series held under two different orderings is the one where the refusal looks most like a defect, and the guide says why the ordering travels inside the key and that the repair is on the series rather than on the episodes. A film both servers hold under different scrapers is the one that is usually a one field edit, and the guide says which identifier to add and why IMDb is the better choice where there is one.

The fourth condition is a table rather than a sentence, with two effects and no third. A repair on the item's own metadata takes effect after that item is refreshed. A repair to the library or on the peer takes effect at the next full pass. Neither the record nor the pass exists here, which the document says on its own page, so that column is the rule an implementation is held to and not a description of something running.

What holds this open

The second condition. It asks that each section names what the operator sees on the status page and what they should see afterwards, and there is no status page. #62 holds it and the record it would count is #26. Until those exist the guide can name the reason and the repair, and it cannot name a screen or say what a repaired item looks like on one. Writing that half now would be a description of a surface nobody can open, so the document states the absence instead.

That is the whole of what is left here, and it arrives with those two rather than with anything else in this issue.

Nobody else has read this. The commands above and the checks on #215 stand in place of a second reader.

[iderex]

The guide said in two places that the record this document is the operator's side of does not exist in this repository. It has since 2026-08-27, and #324 merged the repair as 13c0a84.

git log --format='%h %ad %s' --date=short -1 -- Jellyfin.Plugin.WatchSync/Records/UnmatchedRecords.cs
6b78509 2026-08-27 Keep the record of what did not match and why (#26, #74, #58)

That sentence was written into the section this issue's second condition is about, so a reader deciding whether a reason is something the plugin can already name was reading it. Both passages now say what is actually absent, which is narrower and still an absence: nothing outside the collection that holds the records ever puts an item into one.

grep -rn 'new UnmatchedRecord(' --include=*.cs Jellyfin.Plugin.WatchSync/
Jellyfin.Plugin.WatchSync/Records/UnmatchedRecords.cs:386:            unmatched = new UnmatchedRecord(itemId, kind, refusal, answer, lastAttemptedAt);

What is unchanged

The second condition, where the reading above leaves it. It asks that each section name what an operator sees on the status page and what they should see afterwards, and there is no status page; #62 holds it. Nothing in docs/ can meet that, and nothing here pretends to.

The sweep half of the same section is unchanged and still says nothing runs. #55 landed the interval a sweep would run at and not the sweep, so no pass re-derives a key for a repaired item:

grep -rn 'SweepSchedule\.' --include=*.cs Jellyfin.Plugin.WatchSync/ | grep -v 'Transfer/SweepSchedule.cs'
Jellyfin.Plugin.WatchSync/Configuration/PluginConfiguration.cs:124:    /// Defaults to <see cref="SweepSchedule.DefaultInterval"/>, bounded by
Jellyfin.Plugin.WatchSync/Configuration/PluginConfiguration.cs:125:    /// <see cref="SweepSchedule.LongestInterval"/>. It is the only member here stored in minutes,
Jellyfin.Plugin.WatchSync/Configuration/PluginConfiguration.cs:132:        (int)SweepSchedule.DefaultInterval.TotalMinutes;
Jellyfin.Plugin.WatchSync/Configuration/ServerWideSettings.cs:84:            SweepSchedule.LongestInterval);

The first, third and fourth conditions were met on #215 and are not re-argued here.

Review

Nobody else has read this. The commands re-run on #324 and this repository's own checks stand in place of a second reader.

[iderex]

The sentence the reading above rests on has stopped being true, and half of what it holds behind it has moved. It says there is no status page and that nothing in docs/ can meet the second condition. #337 merged as 8ca5f6d113bfec0fc42a72b4353866ed115a6d6c and the configuration page shows a status now, read from the unmatched record: the count and the three most frequent reasons, and every item with its reason under the export, each reason spelled as this guide's sections are headed. The guide's opening section says so, in the same change:

git show origin/master:docs/unmatched.md | sed -n '15,21p'
Where an operator reads these reasons is the status on the configuration page, which
#62 holds and which reads the unmatched record now: the count and the three most
frequent reasons under the status, and every item with its reason under the export,
each reason spelled as the sections below are headed. What this document still does not
say is what a repaired item looks like there afterwards, because nothing yet puts an
item into the record or takes one out, so the reading after a repair has no subject.
That half arrives with the sweep in #55.

What that does and does not do to the second condition

It asks that each section name what the operator sees on the status page and what they should see afterwards. What the operator sees is the same for every reason, the reason's own name under the status and in the export, and the guide says it once at the top rather than once per section; whether that meets "each section names" or the sentence has to be repeated eleven times is a reading of the condition I have not taken, and it is cheap either way.

What they should see afterwards is still not writable. A repaired item leaves the record only when something re-derives its key, and that is the sweep in #55; until it runs, the reading after a repair has no subject, and a sentence describing it would be a description of a screen nobody can produce.

So this issue is held by #55 rather than by #62 now, and that is the fact worth having here: the surface the reading above waited for exists, and what is left is the run that would change what it shows.

Nothing on the mainline was changed for this reading beyond #337, and nobody else has read it. The command above stands in place of a second reader.