# fsdy — the filesystem provider

Mounts a local directory at **`/fs`** in the crabidy library. The same
engine also powers the server-managed **`/crabidy`** mount (saved queues,
bookmarks, and captures), so everything below applies to its on-disk format
too.

No login: the provider only reads a directory you point it at.

## How it works

The provider walks one configured root directory. Every **directory**
becomes a queueable library node; every file ending in
**`.cbd-track.toml`** becomes a track; everything else (audio files,
covers, hidden entries) is invisible to the library. Listing order is
case-insensitive by file name — prefix files with numbers to fix an
order (the save writers use `0001`-style prefixes for exactly this
reason).

A track file carries the track's metadata plus a reference to the
playable thing:

```toml
title = "We Will Rock You"      # required
artist = "Queen"                # optional
duration = 122                  # optional, seconds

[album]                         # optional
title = "News of the World"
release_date = "1977-10-28"

# Exactly ONE of the following four:
[playable]
file = "we-will-rock-you.flac"  # local audio; absolute, or relative to
                                # this file's directory (relocatable)
# url = "https://example.org/radio.mp3"   # http(s) stream
# link = "/tidal/artists/1/2/3"           # another provider's track
# skipped = true                # no audio: a capture recorded its
                                # source as uncapturable; shown red,
                                # skipped by playback
```

Malformed track files are skipped with a warning; they never break the
listing. `link` playables resolve exactly one hop (a link to a link
fails at play time), which keeps cycles impossible.

## Configuration — `~/.config/crabidy/fsdy.toml`

```toml
# Absolute path of the directory to expose under /fs.
# Default: the platform music directory (e.g. ~/Music). When neither is
# available the /fs mount is disabled — the rest of the server runs on.
# root = "/home/me/music"
```

## The server-managed `/crabidy` instance

`/crabidy` is a second instance of this same provider, over the server's
state directory `~/.local/state/crabidy/`, written by the server (queue
persistence, `w`, `W`) and readable with any file manager — it is just
folders of the track files described above.

- Each top-level folder is one save. It can be renamed (`e`) and deleted
  (`d`) from a client.
- `current` is the continuously persisted play queue and is protected: you
  cannot save over that name.
- A captured track's `[playable]` is a `store` entry naming a file in the
  content store at `~/.local/share/crabidy/`, which is shared and
  de-duplicated across every save.
- Deleting inside `/crabidy` removes only the metadata toml, **never** the
  shared store audio — other saves may point at the same file. Audio that
  ends up referenced by nothing shows up under `/orphans`, where you can
  delete it for real.

The `scan` subcommand writes exactly these track files for a folder of audio,
so an existing music collection browses under `/fs` without any manual work:

```sh
crabidy-server scan ~/Music                # index in place
crabidy-server scan ~/Downloads --capture  # copy the audio into the store
```

Building the server without the `fs` cargo feature drops this provider, the
content store, `/crabidy`, `/orphans`, queue persistence, and `scan` — they
all share the same on-disk machinery.