files assets VS paths assets

[jonathanstanley]

The docs have several (conflicting?) sections on assets:

1. AssetHandling: https://kit.svelte.dev/docs/assets
2. AssetsPath: https://kit.svelte.dev/docs/modules#$app-paths-assets
3. config.kit.paths.assets: https://kit.svelte.dev/docs/configuration#paths
4. config.kit.files.assets: https://kit.svelte.dev/docs/configuration#files
5. config.kit.appDir: https://kit.svelte.dev/docs/configuration#appdir

each seems very similar, but also slightly different:

1. AssetHandling suggests the path convention:$lib/assets/logo.png. it hashes the file name. this doesn't appear to share much with the rest of this other than a similar name?

2. AssetsPath suggests the path convention: static (outside the src folder). this convention is also used for favicon in the preloaded template. why is this one outside the lib and even outside the src folder?

3. config.kit.paths.assets is used by AssetsPath as an absolute path (in this context is it different than a url)? it's tricky because the docs are split up between config.kit.paths.assets and AssetsPath. Also, AssetsPath makes it look like it is declared separately from the config:

   const assets: https://${string} | http://${string};

   (perhaps AssetsPath docs section should folded into the config.kit.paths.assets section?

4. config.kit.files.assets just says

   "a place to put static files that should have stable URLs and undergo no processing, such as favicon.ico or manifest.json"

   I don't see any path suggestion. however, as i understand it, the default template does not use this for favicon. so perhaps the only difference is that config.kit.files.assets has no preprocessing and config.kit.paths.assets does have preprocessing? if config.kit.paths.assets does have preprocessing shouldn't the path be within the src or lib?

5. config.kit.appDir appears to default to _app and says:

   relative to paths.assets where the built JS and CSS (and imported assets) are served from.

   This isn't clear without an example. Presumably paths.assets is referring to config.kit.paths.assets? The name appDir may be a misnomer if is actually intended to refer to assets (not the entire app)? Is this to modify the rendered output path, ex:

   const config = {
     kit:{
       appDir: "media",
       // etc...
     }
   }
   // app renders assets like `https://example.com/media/example.jpg` instead of default `https://example.com/_app/example.jpg` ?

If I'm following this correctly, I'd be happy to submit a PR to clear this up.