Browse, preview and upload attachments
Your goal
Find local and server files in one attachment manager, organize groups and download originals when needed.
Before you start
The simplified servers, automatic resumable discovery and dedicated Downloads page are available in LeafLoom 0.1.5. Back up the vault and retain existing app data before upgrading. Attachment servers are optional: without one, files stay in local _attachments—open Attachments and prepare the local catalog to browse, preview and upload.
For remote files, open Settings → Attachment servers, add an address, account and password, then Save and connect. HTTP(S) addresses use WebDAV; smb://host/share/subfolder and Windows shared paths use SMB2/3. No brand selection or system mount is required. Use HTTPS for public WebDAV; existing numeric private/VPN HTTP connections remain supported. Official-client bridges still need their client and configured port to stay available. Prefer a Tailscale direct path (not a DERP relay); on the same LAN switch the URL to the NAS LAN IP and port. Connection tests show round-trip latency. On Attachments, choose Local for a fast local-only list; use Cache locally on remote items to materialize into the vault cache without inventing new catalog members.
Membership can switch to an app-written catalog under the server metadata directory (…/attachments/v1/members/). In Sync status, run Import existing files into catalog once for the current NAS tree; afterward LeafLoom stops automatic full-tree discovery and only lists app uploads/migrations plus catalog pulls. Import registers membership only—it does not download originals. New central paste/upload with a default remote server stages briefly in _attachments and promotes in the background. Note-sized images stay as local vault cache so embeds open quickly; larger and non-image staging drops so the grid keeps lightweight thumbnails/previews. Other full files stay on the server until you Cache locally or open them. Slow links and disconnects keep retrying until the job finishes; only authentication failures pause automatic retries.
On the same page, Server upload and migration tasks migrate local _attachments files to the selected server. Optionally list vault-relative paths (one per line); leave empty to preview the whole attachment folder. Registered HTML project trees and Design/project assets are excluded from server migration. Confirm before execute; on failure or disconnect use Resume this migration on that job only. After verification the server is authoritative and migrated local originals are removed, leaving lightweight previews. Use Cache locally or open a file for full local content; clearing downloaded cache never deletes NAS originals. If preview shows 0 files with only exclusions, expand exclusions for the local rule (not “already on the server so nothing was found”). Away from LAN, use the Tailscale 100.x URL with small batches (about 50–200 paths), keep the PC awake and resume; at home prefer the LAN URL. See the complete guide.
Older registered HTML projects still under _attachments can be relocated with the one-off script scripts/localize_html_attachments.py (dry-run by default; --apply writes after closing LeafLoom): project trees move to Web/<name>/, external central dependencies into each project’s assets/, and static HTML/CSS references are rewritten. Script-generated references are reported as blockers.
For a shared DUFS server, use your own account-specific address and credentials. See separate accounts in one DUFS container for administrator setup and safe DJ migration.
Steps
- Local uses the local filename index and original files without reading the server catalog. All shows local attachments first, then merges the saved server catalog using the selected sort order. Server and individual servers read only their saved catalog; opening a list does not initialize an index or scan a server. If the server catalog is unavailable, local results retain the active filters and their own pagination; retry returns to the latest first page. External file changes appear when the local index updates.
- Search names/paths, filter by type, sort and choose a grid or list. Create manual groups or rules using source, directory, format, category and tags. A group change updates its heading and clears the old list while loading; Retry stays in the selected group after a failed read.
- Open Attachment information to inspect a selected file. The panel starts collapsed and remembers its preference. Images, PDF, audio and video retain their viewers. Unsupported formats use an existing cover without downloading the original; a missing cover offers the file icon and download action. Previews and thumbnails use valid local file or byte-range caches immediately and check server versions in the background. Files without cached content download on demand. A confirmed version change applies to subsequent reads; an active response never mixes versions. Downloads retain their existing synchronous verification.
- Upload files here or drag them into the manager. Existing same-name originals are retained. Notes and new folders/imports use the file directory actions. Server cards can be edited, disabled or selected as the new-upload destination without moving existing attachments.
- Open Sync status for discovered files, scanned/pending directories, reused-directory counts and retry details. Scanning resumes from device-local checkpoints after disconnection or restart; automatic sources run serially, with at most two directory readers per server. Checks reuse unchanged archive directories for progressively longer intervals, up to one week; the upload tree remains on a 2-hour cadence. Expired children are checked independently. Check all directories bypasses the cache without downloading originals.
- Use Downloads to monitor original-file preparation and ZIP tasks. A verified remote file can be saved to the device; the staging limit is configured in Download settings. Releasing staged files removes local temporary copies, not server originals. Rename, move and recycle retain reference/version checks; server capabilities can differ.
Metadata, AI scope and server rules
Categories, tags, personal notes, source metadata and real covers enrich the same file list. The former fixed product view is replaced by groups; compatible product tools and optional Unity collection remain available. Groups and metadata synchronize through verified server records with explicit conflict handling. Live SQLite catalogs, pending uploads and caches stay in the device's application data; do not synchronize or delete them as disposable caches.
Enable Use for AI asset search only on the groups that AI should search. No selected groups returns no asset results. AI can inspect metadata/previews and request verified delivery to a configured local directory; it does not automatically import into Unity or verify purchase rights. See the complete guide.
A visible leafloom.ignore at the server root or a subdirectory may exclude files using Gitignore-style patterns. Its first line must be exactly # leafloom-ignore v1; a child rule or ! can reinclude files. Rules are read without requiring NAS write permission. A completed successful scan applies exclusions while retaining original files, IDs and existing references.
Upload attachments through MCP
The single-request Base64 path requires a build containing this change.
Use vault_files_update with request.action="upload" for knowledge-base attachments. ChatGPT should prefer source="files" with the host-provided top-level files array. Local clients can send one file up to 2 MiB with source="base64", name, data_base64, and the original bytes' sha256; use begin/chunk/commit for larger files. Omit folder for the configured attachment directory, or specify a vault-relative directory such as Comics/Project/assets.
Read workspace_revision from vault_index_status and use a unique operation_id; keep the ID unchanged when retrying identical arguments. Upload results include the saved path, size, SHA-256, revision and markdown_link; images also return markdown_embed. Use vault_files stat with source_note to obtain a note-relative reference, then edit the note with its current revision. Existing files remain intact.
If only Design Studio import or Feishu temporary transfers appear, check the server's tools/list: it must include vault_files and vault_files_update. Restart an updated backend and refresh/rescan the client's plugin tool directory. Restarting LeafLoom alone does not refresh a cached client directory. Check workspace-write permission separately; these uploads do not require Feishu authorization. See MCP file tools.
Attachment file types
In Settings → Attachment servers → Attachment file types, edit the allowed filename extensions and select Save. The same list applies to local files, every configured server, attachment management uploads, editor attachment insertion and MCP attachment uploads. Defaults include common images (including SVG), PDF/Office documents, audio/video, archives, fonts, e-books and .unitypackage; web pages, scripts and other source files are excluded by default. Ordinary file import remains available for those files.
Separate entries with commas, spaces or newlines. PNG becomes .png; duplicates are removed and matching ignores case. Compound extensions such as .tar.gz are supported; paths and wildcards are rejected. An empty list means no attachments, while Restore default types fills the default list for review and saving. Settings are saved per workspace on this device and do not automatically sync between devices.
Removing an extension immediately removes matching files from attachment lists, groups, AI asset search and file/size totals, including existing indexes. Adding one makes indexed local files available immediately; remote files become available after the next scan (directory caches can be reused). Server leafloom.ignore exclusions still apply; ! cannot admit a type outside the allowed list. Originals, metadata, IDs and existing links are preserved. Pending attachment uploads recheck types before publication and retain recovery bytes if disabled. Migration also retains its existing dependency and supported-format safeguards.
Background checks, catalog and scan scope
Startup shows the saved attachment list immediately. With app-only membership, background work pulls the membership catalog (and optional known-path checks) instead of walking the whole tree; lists do not wait for that work. In discover mode, directory checks still start after a short startup grace: the upload directory stays on about a 2-hour cadence while other unchanged directories lengthen up to one week. LeafLoom uploads update the local projection immediately. Idle product metadata and group pulls back off from 2 hours up to six hours. Failed transfers retry with increasing delays and remain pending across disconnects and restarts until they succeed or you cancel; authentication failures pause until credentials change.
After catalog import, files dropped onto the NAS outside LeafLoom stay invisible until you import again or temporarily return to discover mode. Use Sync now to pull the catalog; Check all directories remains available only while membership is still discover-based.
Edit a server in Settings → Attachment servers and set Server scan directories: one path per line, relative to its configured server root. Empty means the whole root. Include upload directories whose files should appear in the list. Scope limits discovery and listing, not existing file references; narrowing it does not delete files, aliases or personal metadata. Parent leafloom.ignore rules still apply.
The sync dialog separates saved-cache processing, actual server directory reads, missing-file verification, references and metadata work. It shows the current directory and metadata progress. Pause directory checks persists across restarts and keeps completed directory receipts; Resume directory checks continues discovery. Existing attachments, downloads and queued metadata remain usable. Check all directories bypasses cache only within the configured scope. Changes made outside LeafLoom may take until the next check to appear.
What to expect
Background discovery preserves browsing filters, selection, scroll and metadata drafts. An expired pagination snapshot offers List updated — show latest instead of silently moving to page one. Originals remain local or on their existing server. The overview reports originals separately from preview caches; unprepared local totals are unknown rather than zero.
If it does not work
Temporary network failures retry automatically, with the previous issue collapsed. Reconnecting and active metadata synchronization replace stale errors; authentication failures need updated credentials. Failed scans retain existing records. The first upgraded scan must establish checkpoints. Without a server change feed, periodic directory queries remain necessary. Cached originals can be opened offline; uncached or partial files need a connection.
Keep the existing server ID, logical root and metadata binding when recovering references on another device. Changing the default upload destination does not relocate originals or a bound metadata library. Server migration is under Settings → Attachment servers; local folder-reorganization entry points remain hidden while legacy journals stay available for recovery.