Watch Folders & Auto-Linking

Direct answer: Watch Folders monitor your DAW project and export folders. When a file appears, Kora scores it against your existing projects using filename similarity, path tokens and time proximity. Above 0.55 it links automatically; below that it goes to the Watch Inbox for you to resolve. Detection is event-driven, so an export is typically linked around three seconds after your DAW finishes writing it.

The design principle is that automation acting on weak signals creates more cleanup than it saves. Kora would rather ask than be confidently wrong.

What makes a match “high confidence”?

All three signal families contribute, with published weights. For matching a DAW session to a project:

Signal	Contribution
Project-name similarity	`× 0.55`
Filename ↔ project filename (only when ≥ 0.85)	`+ 0.20`
Path-token overlap	`× 0.25`
Album name present in the DAW path	`+ 0.10`
Modified within 2 days	`+ 0.15`
Modified within 7 days	`+ 0.12`
Modified within 30 days	`+ 0.08`
Modified within 90 days	`+ 0.04`
Project has no DAW file yet	`+ 0.05`

The link threshold is 0.55. Export files are scored on title instead: an exact duplicate needs 0.88, and a near-duplicate scoring 0.80–0.88 raises a review overlay rather than resolving itself.

The review queue is stricter than the automatic path. It links only when there is exactly one candidate at 0.88 or above — one strong match is a decision, two strong matches are a question.

Path tokens are filtered through a 41-entry noise list — users, documents, exports, icloud, ableton, logic and similar — so shared folder structure cannot manufacture a match. Without that filter every file under ~/Documents would look related to every other one.

How fast does detection happen?

Watching is event-driven through FSEvents, not polling, so nothing is scanning your disk on a loop. A file moves through a short pipeline before it is linked:

Watcher debounce — 1200 ms on the default balanced setting, 500 ms on live
A 2500 ms deduplication window, so one save does not register as several events
An export stability gate of 1500 ms, checked at 250 ms granularity — this is the only polling in the chain, and it exists so Kora never reads a file your DAW is still writing
A 140 ms batch flush

File type	Typical end-to-end
Export, balanced mode	≈ 3.1 seconds
Export, live mode	≈ 2.4 seconds
DAW session file	≈ 1.34 seconds

DAW files are faster because they skip the stability gate — a session file being open is normal, whereas a half-written WAV is not.

A background reconcile scan also runs every four hours and on launch, which catches anything that appeared while Kora was closed.

What is the Watch Inbox?

The Watch Inbox is a review queue, not an activity log. Files that auto-link cleanly never appear in it. Something lands there when:

Confidence scored below 0.55
The parsed title was judged unreliable
Variant signals were detected — stem or version tokens in the filename
A near-duplicate needs a human decision

The prompts name the actual situation. A file that looks like a stem produces “Review variant file: {fileName}” with the explanation “This looks like a stem/version. Link it to an existing project instead of auto-creating a new one.”

That distinction — variant of existing work versus genuinely new work — is the one most commonly gotten wrong by folder-sync tools, and it is the one that quietly fragments a library over months.

Where does auto-linking break?

Honest limitations, because knowing where automation stops is what makes it trustworthy:

Situation	Status
iCloud Drive	Handled. FSEvents reports the canonical `~/Library/Mobile Documents/com~apple~CloudDocs` path rather than the `iCloud Drive` alias you see in Finder. Kora registers both forms as roots, and `icloud` sits in the path-noise list so it never pollutes a title.
Permissions	Handled. On a watch failure Kora runs a permission diagnosis first and only surfaces “Couldn’t watch {path}. Check permissions in Settings.” if a real problem is confirmed. Repeat notifications back off exponentially from 30 seconds to a 10-minute cap.
External drives	Guidance only. Use Browse to re-authorise access after remounting, and run a permission check if a watch fails.
Renamed folders	Partial. There is no rename tracking. A renamed folder goes quiet and is surfaced by the 7-day stale-folder check rather than immediately.
Network volumes	Not handled. There is no mount-state detection or unmount recovery. If you work primarily from a NAS, treat watch folders as unsupported for that path.

Frequently asked

What is filesystem-aware workflow management?

Filesystem-aware workflow management means the system responds to real file events — a bounce appearing, a session being saved, a version superseding another — rather than waiting for you to tell it what happened. Kora watches your DAW and export folders directly, so project state follows the work instead of being maintained alongside it.

What is confidence-based automation?

Confidence-based automation means the system scores how certain it is before acting, and routes low-certainty cases to a human instead of picking the most likely answer. Kora scores every detected file and only links automatically above a defined threshold — 0.55 for projects, 0.88 for duplicate matching.

Does Kora move or rename my files?

No. Watch folders read your files and record where they are. Organisation happens inside Kora’s index, not by rearranging your disk, so your DAW’s own paths stay exactly as they were.

Why did a file end up in the Watch Inbox instead of linking?

Because it scored below 0.55, its title could not be parsed reliably, it carried stem or version tokens suggesting it is a variant of existing work, or it closely resembled a file already in your library. The inbox entry states which.

Can I watch folders on an external or network drive?

External drives work but need re-authorisation after remounting — use Browse and run a permission check if a watch fails. Network volumes are not supported today: there is no mount-state detection, so an unmounted share will not recover on its own.

How often does Kora scan for files it missed?

Every four hours by default, plus once on launch. This reconcile pass exists to catch files that appeared while Kora was closed, since FSEvents only reports changes while something is listening.

Watch Folders & Auto-Linking