File Palaces iconFilePalaces

Adding Folders (Wings)

Every folder you add to File Palaces becomes a Wing — a named region of your local palace. This page covers all the ways to add a Wing, how mining works, and how to keep it up to date.

What is a Wing?

A Wing maps to a real folder on your filesystem. Inside the palace, it becomes a top-level namespace. Sub-folders within the Wing become Rooms, and individual extracted text chunks become Drawers. This hierarchy lets you scope searches and chat queries to specific parts of your palace.

The Wing name is derived from the folder name: spaces become underscores, the result is lowercased, and the slug is capped at 40 characters. For example, My Work Projects 2024 becomes my_work_projects_2024.

Adding a Wing

Drag and drop

Drag any folder from Explorer (Windows), Finder (macOS), or your file manager directly onto the File Palaces app window. A drop target overlay appears when a drag is detected.

Using the picker

  1. Click the + button in the Wings sidebar panel
  2. The Add Folder dialog opens
  3. Toggle between Folder mode (indexes the whole directory tree) and Files mode (lets you pick individual files)
  4. Confirm — File Palaces creates the Wing and starts mining immediately
FOLDER VS FILES MODE

Folder mode is recommended for most use cases. It adds the entire directory tree and the watchdog monitors it for changes automatically.

Files mode lets you pick specific files from anywhere on your filesystem and group them into a single Wing. This is useful for ad-hoc document collections that don't share a parent folder.

Mining

Mining is the process of extracting text from your files and storing it in the vector index. It runs automatically when you add a Wing and re-runs on any changed file via the watchdog observer.

What happens during mining

  1. Extraction — text is extracted from each file using format-specific libraries (pypdf for PDF, python-docx for DOCX, Whisper for audio/video, etc.)
  2. Chunking — extracted text is split into overlapping chunks (~512 tokens by default)
  3. Embedding — each chunk is embedded using a local sentence-transformer model (no API key required)
  4. Storage — chunks and embeddings are stored in ChromaDB under the Wing's namespace

Mining runs in a background thread pool and does not block the UI.

Mining progress

The Mining Toast in the bottom-right corner shows live progress:

  • 🟡 Indexing — currently processing files
  • ✅ Done — all files processed
  • 🔴 Error — a file failed (the rest still indexed; check the toast for details)

Re-mining a Wing

To force a full re-mine of a Wing (useful after adding many new files or changing chunk settings):

  1. Right-click the Wing in the sidebar (or use the ⋯ menu)
  2. Select Re-mine
  3. The existing index for that Wing is cleared and rebuilt from scratch

Live sync (watchdog)

File Palaces runs a filesystem watchdog observer on every active Wing. When it detects a file modification, creation, or deletion, it queues a debounced re-mine for that specific file (~5-second debounce to avoid excessive re-indexing during saves).

This means your palace stays current automatically — you don't need to manually trigger re-mining after editing a document.

NOTE

The watchdog only runs while File Palaces is open. Files changed while the app is closed will be picked up the next time you open the app or manually re-mine the Wing.

Removing a Wing

To remove a Wing and delete all its indexed data from the palace:

  1. Right-click the Wing in the sidebar
  2. Select Remove Wing
  3. Confirm the dialog

This deletes all ChromaDB vectors for that Wing but does not delete your original files.

Multiple Wings

You can have as many Wings as you like. Common patterns:

  • One Wing per project
  • One Wing for personal notes
  • One Wing for reference documents (books, papers)

Use the Wing selector in the Chat panel to restrict answers to a specific Wing, or leave it set to All Wings for cross-document queries.