docs(folders): trim the comments this branch adds

The same three lines explaining which folder kinds can go offline sat above both
the grid card and the list row; one copy carries the reasoning and the other
points at it.

The rest is the module docs on the new stores, saying the same things with less
around them.

frontend/editor/src/core/components/filesPage/FileGrid.tsx

@@ -534,9 +534,8 @@ function FolderCard({
 }: FolderCardProps) {
   const { t } = useTranslation();
   const { serverReachable, setError } = useFolders();
-  // Only server folders go offline: a virtual folder is browser-owned and a
-  // local one takes its name, look, and lifetime from its directory on disk —
-  // so its edit items are hidden rather than disabled-with-a-wrong-excuse.
+  // Only a server folder can go offline: the other kinds take their name, look and
+  // lifetime from elsewhere, so their edit items are hidden rather than disabled.
   const kind = folderKind(folder);
   const originBadge = useFolderOriginBadge(folder);
   const editsDisabled = kind === "server" && !serverReachable;
@@ -1285,9 +1284,7 @@ function FolderRow({
 }: FolderRowProps) {
   const { t } = useTranslation();
   const { serverReachable, setError } = useFolders();
-  // Only server folders go offline: a virtual folder is browser-owned and a
-  // local one takes its name, look, and lifetime from its directory on disk —
-  // so its edit items are hidden rather than disabled-with-a-wrong-excuse.
+  // Kinds gate the edit items, as in FolderCard.
   const kind = folderKind(folder);
   const originBadge = useFolderOriginBadge(folder);
   const editsDisabled = kind === "server" && !serverReachable;

frontend/editor/src/core/services/localFolderContents.ts

@@ -1,11 +1,8 @@
 /**
- * Reading a mounted local folder's contents straight off the disk.
- *
- * A local folder is read-through: the directory is the source of truth and
- * nothing is ingested to show it — the listing IS the directory, taken fresh
- * on every look. Only an environment that can see the filesystem can do
- * this, so core reports the capability absent and the desktop build shadows
- * this module with the Tauri filesystem plugin.
+ * Reading a mounted folder's contents straight off the disk. Read-through: the
+ * listing is the directory, taken fresh each look, with nothing ingested to show it.
+ * Only an environment that can see the filesystem can do this, so core reports the
+ * capability absent and the desktop build shadows this module.
  */
 
 /** One file inside a mounted directory, as the file manager lists it. */

frontend/editor/src/core/services/localFolderStorage.ts

@@ -1,13 +1,11 @@
 /**
- * Local Folder Storage - the record of directories mounted into the file
- * manager (kind "local").
+ * The record of directories mounted into the file manager (kind "local"): a pointer
+ * at a directory, nothing more. The directory owns its name, contents and lifetime,
+ * so the record holds only where it is and how to show it, and removing a mount
+ * removes the record and nothing else.
  *
- * A local folder is a pointer at a directory on the machine; the directory
- * itself is the source of truth for everything else — name, contents,
- * lifetime — so the record carries only where it is and how to show it.
- * Mounts are flat by construction: they have no parent, and a directory's
- * subdirectories are the filesystem's business, not a folder hierarchy for
- * this store to model. Removing a mount removes the record and nothing else.
+ * Mounts are flat by construction - no parent, and a directory's subdirectories are
+ * the filesystem's business rather than a hierarchy for this store to model.
  */
 
 import {
@@ -73,12 +71,10 @@ class LocalFolderStorageService {
   }
 
   /**
-   * Mount a directory. Mounting the same directory twice hands back the
-   * existing record — two rows for one directory would be two names for one
-   * truth, and removing one would lie about the other. Nesting is fine: a
-   * mount lists only its own files, so a subdirectory needs its own mount to
-   * be reachable at all — the same way a file manager pins both a folder and
-   * one of its children.
+   * Mount a directory, or hand back the existing record for one already mounted:
+   * two rows for one directory would be two names for one truth. Nesting is fine -
+   * a mount lists only its own files, so a subdirectory needs its own mount to be
+   * reachable.
    */
   async mountDirectory(directory: string, name: string): Promise<FolderRecord> {
     const key = directoryKey(directory);

frontend/editor/src/core/services/mountWrites.ts

@@ -7,13 +7,12 @@ export interface MountWriteItem {
 }
 
 /**
- * Write a batch of named blobs into a mounted directory — the one engine
- * behind "upload while standing in a mount" and "move library files into a
- * mount", so failure accounting and collision behavior can't drift between
- * them. Failures are counted, never thrown: the caller owes the user one
- * banner for the batch, not an abort at the first bad file. `written[i]`
- * tells the caller which items verifiably landed (and are safe to retire
- * from app storage).
+ * Write named blobs into a mounted directory - the one engine behind both uploading
+ * into a mount and moving library files into one, so failure accounting and
+ * collision behaviour cannot drift apart. Failures are counted, never thrown: the
+ * caller owes one banner for the batch rather than an abort at the first bad file.
+ * `written[i]` says which items verifiably landed and are safe to retire from app
+ * storage.
  */
 export async function writeIntoMount(
   directory: string | undefined,

frontend/editor/src/core/services/virtualFolderStorage.ts

@@ -1,16 +1,13 @@
 /**
- * Virtual Folder Storage - the system of record for kind "virtual" folders.
+ * The system of record for kind "virtual" folders - rows this store owns rather
+ * than caches. {@link folderStorage} is wiped and rewritten on every sync because
+ * the server is authoritative there; a virtual folder exists only in this browser,
+ * with nothing to restore it from. They organise files where there is no login, no
+ * server storage, or no network.
  *
- * Unlike {@link folderStorage} (a passive cache of the server's folder
- * hierarchy, wiped and rewritten on every sync), this store OWNS its rows:
- * a virtual folder exists only in this browser's IndexedDB and has no server
- * copy to be restored from. That is the point — virtual folders organise
- * files on installs with no login, no server storage, or no network.
- *
- * Because there is no server to be authoritative, the invariants the server
- * enforces for its folders are enforced here instead: no reparenting a folder
- * under its own subtree (cycles), and a bounded chain depth. Limits mirror
- * FolderService so a hierarchy never behaves differently for being virtual.
+ * No server to enforce them means the invariants live here: no reparenting a folder
+ * under its own subtree, and a bounded depth, with the limits mirroring
+ * FolderService so a hierarchy does not behave differently for being virtual.
  */
 
 import {

frontend/editor/src/desktop/services/localFolderContents.ts

@@ -24,15 +24,13 @@ import type {
 export type { DiskDirEntry, DiskFileEntry, DiskListing };
 
 /**
- * Containment: file reads and writes here run under a filesystem-wide Tauri
- * capability, but this module's contract is mounted directories only —
- * refuse any path outside one. The capability layer is the real trust
- * boundary; this keeps the contract explicit and a bad path inert.
+ * Containment: these reads and writes run under a filesystem-wide Tauri capability,
+ * but the contract here is mounted directories only, so any path outside one is
+ * refused. The capability layer is the real trust boundary; this keeps a bad path
+ * inert.
  *
- * The mount store is read fresh on every call: it holds a handful of rows,
- * which is nothing next to the file bytes about to cross the IPC bridge,
- * and the heavy callers (thumbnails) are already concurrency-throttled.
- * Fresh reads mean a removed mount is refused immediately.
+ * The mount store is read fresh every call - a handful of rows against the file
+ * bytes about to cross the IPC bridge - so a removed mount is refused at once.
  */
 async function isWithinMount(path: string): Promise<boolean> {
   const pathKey = directoryKey(path);