feat: add FILE_TOOLS_ENABLED env var to conditionally hide file tools

.env.example

@@ -113,6 +113,10 @@ TZ=UTC
 # Set to false to hide memory tools, skip auto-initialization, and omit
 # memory references from server metadata. MEMORY_DIR is ignored when false.
 # MEMORY_ENABLED=true
+# Enable or disable file tools — vault_read_file and vault_list_files (default: true).
+# Set to false to hide file tools entirely. Useful for remote deployments where
+# Obsidian Sync has attachment syncing disabled (no files on disk).
+# FILE_TOOLS_ENABLED=true
 # Memory folder name in your vault (default: "About Me")
 MEMORY_DIR=About Me
 # Comma-separated folders protected from deletion (default: MEMORY_DIR, Daily Notes).

.github/workflows/deploy.yml

@@ -249,6 +249,7 @@ jobs:
           EMBEDDING_ENABLED: ${{ vars.EMBEDDING_ENABLED }}
           RERANK_MODE: ${{ vars.RERANK_MODE }}
           MEMORY_ENABLED: ${{ vars.MEMORY_ENABLED }}
+          FILE_TOOLS_ENABLED: ${{ vars.FILE_TOOLS_ENABLED }}
           MEMORY_DIR: ${{ vars.MEMORY_DIR }}
           PROTECTED_PATHS: ${{ vars.PROTECTED_PATHS }}
           ORPHAN_EXCLUDE_FOLDERS: ${{ vars.ORPHAN_EXCLUDE_FOLDERS }}
@@ -270,6 +271,7 @@ jobs:
           EMBEDDING_ENABLED=${EMBEDDING_ENABLED:-true}
           RERANK_MODE=${RERANK_MODE:-blended}
           MEMORY_ENABLED=${MEMORY_ENABLED:-true}
+          FILE_TOOLS_ENABLED=${FILE_TOOLS_ENABLED:-true}
           MEMORY_DIR=${MEMORY_DIR:-About Me}
           PUID=1000
           PGID=1000

.github/workflows/test_deploy.yml

@@ -194,6 +194,7 @@ jobs:
           EMBEDDING_ENABLED: ${{ vars.EMBEDDING_ENABLED }}
           RERANK_MODE: ${{ vars.RERANK_MODE }}
           MEMORY_ENABLED: ${{ vars.MEMORY_ENABLED }}
+          FILE_TOOLS_ENABLED: ${{ vars.FILE_TOOLS_ENABLED }}
           MEMORY_DIR: ${{ vars.MEMORY_DIR }}
           PROTECTED_PATHS: ${{ vars.PROTECTED_PATHS }}
           ORPHAN_EXCLUDE_FOLDERS: ${{ vars.ORPHAN_EXCLUDE_FOLDERS }}
@@ -215,6 +216,7 @@ jobs:
           EMBEDDING_ENABLED=${EMBEDDING_ENABLED:-true}
           RERANK_MODE=${RERANK_MODE:-blended}
           MEMORY_ENABLED=${MEMORY_ENABLED:-true}
+          FILE_TOOLS_ENABLED=${FILE_TOOLS_ENABLED:-true}
           MEMORY_DIR=${MEMORY_DIR:-About Me}
           PUID=1000
           PGID=1000

AGENTS.md

@@ -202,7 +202,8 @@ on**, not just its topic:
   orchestrator that composes `TOOL_NAMES` from the domain group modules under
   `mcp-core/tools/` (vault-crud, search, memory, daily-note, task, asset) and
   calls each register function — conditionally skipping memory tools when
-  `MEMORY_ENABLED` is `false`. Each group module is self-contained: its own tool
+  `MEMORY_ENABLED` is `false` and file tools when `FILE_TOOLS_ENABLED` is
+  `false`. Each group module is self-contained: its own tool
   name constants, register function, and data-layer imports. Shared helpers
   (`safeHandler`, `formatNoteMetadata`, `ToolRegistrationContext` type) live in
   `tool-helpers.ts`.

ARCHITECTURE.md

@@ -303,6 +303,8 @@ The extension-to-representation routing above is implemented by the `vault-opera
 
 `vault_list_files` is the discovery surface (also `vault-operations/asset-operations.ts`): a filesystem walk (`vaultFs.listAssets` — filesystem truth, deliberately not the index), folder and case-insensitive extension filters, per-extension counts computed over the full filtered set, and byte sizes statted only for the returned slice. Files are readable and browsable but not yet searchable — content indexing is a possible future tier.
 
+**Opt-out:** File tools are opt-out: set `FILE_TOOLS_ENABLED=false` to hide `vault_read_file` and `vault_list_files`, and strip file tool references from server metadata and other tool descriptions. The `vault_get_outgoing_links` tool continues to report file links (it indexes from the links table, not the file tools). File config vars (`MAX_FILE_BYTES`, `MAX_IMAGE_OUTPUT_BYTES`, `MAX_PDF_RENDER_PAGES`) are still parsed when disabled.
+
 ### Tasks (R9)
 
 | Tool                | Input                                                                                                                                          | Annotation   |

DEPLOY.md

@@ -61,7 +61,7 @@ Then open `~/.config/vault-cortex/.env` and fill in the remaining values:
 | `VAULT_PASSWORD`      | Only if vault has E2E encryption                                                              |
 | `OBSIDIAN_AUTH_TOKEN` | Generate with the command below                                                               |
 
-The [`.env.example`](./.env.example) file also includes optional configuration for the embedding pipeline (`EMBEDDING_ENABLED`), the reranker (`RERANK_MODE`), the memory system (`MEMORY_ENABLED`, `MEMORY_DIR`, `PROTECTED_PATHS`, `ORPHAN_EXCLUDE_FOLDERS`), timezone (`TZ`), and OAuth metadata (`SERVICE_DOCUMENTATION_URL`). All have sensible defaults — see the [Configuration](./README.md#configuration) section in the README.
+The [`.env.example`](./.env.example) file also includes optional configuration for the embedding pipeline (`EMBEDDING_ENABLED`), the reranker (`RERANK_MODE`), the memory system (`MEMORY_ENABLED`, `MEMORY_DIR`, `PROTECTED_PATHS`, `ORPHAN_EXCLUDE_FOLDERS`), file tools (`FILE_TOOLS_ENABLED`), timezone (`TZ`), and OAuth metadata (`SERVICE_DOCUMENTATION_URL`). All have sensible defaults — see the [Configuration](./README.md#configuration) section in the README.
 
 ```bash
 npx vault-cortex@latest get-sync-token
@@ -329,6 +329,7 @@ To find your stage: `cat .sst/stage` (after your first deploy).
 | `EMBEDDING_ENABLED`         | Optional. Set `false` to disable the embedding pipeline — skips model download, vector tables, embedding passes, and hybrid search. Search falls back to FTS5 keyword matching. Default: `true`.                  |
 | `RERANK_MODE`               | Optional. Cross-encoder reranking mode: `blended` (default) applies position-aware score blending after RRF fusion, `none` skips reranking for lower latency. Only takes effect when `EMBEDDING_ENABLED` is true. |
 | `MEMORY_ENABLED`            | Optional. Set `false` to disable the memory layer entirely — hides memory tools, skips bootstrap, omits memory from server metadata. Default: `true`.                                                             |
+| `FILE_TOOLS_ENABLED`        | Optional. Set `false` to hide file tools (`vault_read_file`, `vault_list_files`) for deployments without synced attachments. Default: `true`.                                                                     |
 | `MEMORY_DIR`                | Optional. Memory folder name in the vault (default: `About Me`). See the [Configuration](./README.md#configuration) section.                                                                                      |
 | `PROTECTED_PATHS`           | Optional. Comma-separated folders protected from deletion (default: `MEMORY_DIR, Daily Notes`). Overrides the default entirely when set.                                                                          |
 | `ORPHAN_EXCLUDE_FOLDERS`    | Optional. Comma-separated folders excluded from orphan detection (default: `Daily Notes, Templates, MEMORY_DIR`). Overrides the default entirely when set.                                                        |

DOCKERHUB.md

@@ -144,6 +144,7 @@ All settings are environment variables with sensible defaults.
 | `EMBEDDING_ENABLED`         | —           | `true`                               | Set `false` to disable the embedding pipeline — skips model download, vector tables, embedding passes, and hybrid search. Search falls back to FTS5 keyword matching.                                                                                          |
 | `RERANK_MODE`               | —           | `blended`                            | Cross-encoder reranking mode: `blended` applies position-aware score blending after RRF fusion (~200ms added latency), `none` skips reranking. Only takes effect when `EMBEDDING_ENABLED` is true.                                                             |
 | `MEMORY_ENABLED`            | —           | `true`                               | Set `false` to fully disable the memory layer — hides memory tools, skips bootstrap, omits memory from server metadata. `MEMORY_DIR` is ignored when `false`.                                                                                                  |
+| `FILE_TOOLS_ENABLED`        | —           | `true`                               | Set `false` to hide file tools (`vault_read_file`, `vault_list_files`) — useful for remote deployments where Obsidian Sync has attachment syncing disabled.                                                                                                         |
 | `MEMORY_DIR`                | —           | `About Me`                           | Vault folder for structured memory files                                                                                                                                                                                                                       |
 | `PROTECTED_PATHS`           | —           | `MEMORY_DIR, Daily Notes`            | Folders that `vault_delete_note` refuses to touch                                                                                                                                                                                                              |
 | `ORPHAN_EXCLUDE_FOLDERS`    | —           | `Daily Notes, Templates, MEMORY_DIR` | Folders excluded from orphan detection                                                                                                                                                                                                                         |

README.md

@@ -304,6 +304,7 @@ All settings are environment variables with sensible defaults.
 | `EMBEDDING_ENABLED`         | —           | `true`                               | Set `false` to disable the embedding pipeline — skips model download, vector tables, embedding passes, and hybrid search. Search falls back to FTS5 keyword matching.                                                                                          |
 | `RERANK_MODE`               | —           | `blended`                            | Cross-encoder reranking mode: `blended` applies position-aware score blending after RRF fusion (~200ms added latency), `none` skips reranking. Only takes effect when `EMBEDDING_ENABLED` is true.                                                             |
 | `MEMORY_ENABLED`            | —           | `true`                               | Set `false` to fully disable the memory layer — hides memory tools, skips bootstrap, omits memory from server metadata. `MEMORY_DIR` is ignored when `false`.                                                                                                  |
+| `FILE_TOOLS_ENABLED`        | —           | `true`                               | Set `false` to hide file tools (`vault_read_file`, `vault_list_files`) — useful for remote deployments where Obsidian Sync has attachment syncing disabled.                                                                                                    |
 | `MEMORY_DIR`                | —           | `About Me`                           | Vault folder for structured memory files                                                                                                                                                                                                                       |
 | `PROTECTED_PATHS`           | —           | `MEMORY_DIR, Daily Notes`            | Folders that `vault_delete_note` refuses to touch                                                                                                                                                                                                              |
 | `ORPHAN_EXCLUDE_FOLDERS`    | —           | `Daily Notes, Templates, MEMORY_DIR` | Folders excluded from orphan detection                                                                                                                                                                                                                         |
@@ -317,7 +318,7 @@ All settings are environment variables with sensible defaults.
 | `MAX_IMAGE_OUTPUT_BYTES`    | —           | `49152` (48 KiB)                     | Byte budget for images delivered by `vault_read_file`, in binary bytes before base64 encoding. Images exceeding this are downscaled and recompressed to fit. Sized for the tightest mainstream MCP client cap; raise for clients that accept larger responses. |
 | `MAX_PDF_RENDER_PAGES`      | —           | `5`                                  | Maximum PDF pages to render as images when `raw: true` is set on `vault_read_file`. The per-page byte budget is `MAX_IMAGE_OUTPUT_BYTES` divided evenly across the rendered pages — fewer pages means higher quality each.                                     |
 
-**Smart defaults:** Setting `MEMORY_DIR` automatically updates the defaults for `PROTECTED_PATHS` and `ORPHAN_EXCLUDE_FOLDERS`. You only set those explicitly for a fully custom list. When `MEMORY_ENABLED` is `false`, the memory layer is fully disabled — memory tools are hidden and the memory folder is not auto-created.
+**Smart defaults:** Setting `MEMORY_DIR` automatically updates the defaults for `PROTECTED_PATHS` and `ORPHAN_EXCLUDE_FOLDERS`. You only set those explicitly for a fully custom list. When `MEMORY_ENABLED` is `false`, the memory layer is fully disabled — memory tools are hidden and the memory folder is not auto-created. When `FILE_TOOLS_ENABLED` is `false`, file tools are hidden entirely — useful when Obsidian Sync has attachment syncing disabled and no files exist on disk.
 
 See [`templates/memory/`](./templates/memory/) for memory file examples and the dated-entry design philosophy.
 

cli/src/env.ts

@@ -70,6 +70,9 @@ RERANK_MODE=blended
 # Enable or disable the memory layer (default: true).
 # Set to false to hide memory tools and skip About Me/ creation.
 MEMORY_ENABLED=true
+# Enable or disable file tools — vault_read_file and vault_list_files (default: true).
+# Set to false when Obsidian Sync has attachment syncing disabled.
+FILE_TOOLS_ENABLED=true
 # Memory folder name in your vault (default: About Me).
 MEMORY_DIR=About Me
 
@@ -161,6 +164,9 @@ MAX_PDF_RENDER_PAGES=5
 # Enable or disable the memory layer (default: true).
 # Set to false to hide memory tools and skip About Me/ creation.
 MEMORY_ENABLED=true
+# Enable or disable file tools — vault_read_file and vault_list_files (default: true).
+# Set to false when Obsidian Sync has attachment syncing disabled.
+FILE_TOOLS_ENABLED=true
 # Memory folder name in your vault (default: About Me).
 MEMORY_DIR=About Me
 

deploy/local/.env.example

@@ -53,6 +53,9 @@ RERANK_MODE=blended
 # Enable or disable the memory layer (default: true).
 # Set to false to hide memory tools and skip About Me/ creation.
 MEMORY_ENABLED=true
+# Enable or disable file tools — vault_read_file and vault_list_files (default: true).
+# Set to false when Obsidian Sync has attachment syncing disabled.
+FILE_TOOLS_ENABLED=true
 # Memory folder name in your vault (default: About Me).
 MEMORY_DIR=About Me
 

deploy/local/README.md

@@ -3,7 +3,7 @@
 Run Vault Cortex on your machine against a local Obsidian vault. No cloud, no
 Obsidian Sync — just Docker and a folder of `.md` files.
 
-**Contents** — [Prerequisites](#prerequisites) · [Setup](#setup) · [Connect](#connect-your-mcp-client) · [Verify](#verify) · [Updating](#updating) · [Stop](#stop) · [Windows](#windows-docker-desktop) · [Memory](#memory) · [Config](#configuration) · [Troubleshooting](#troubleshooting)
+**Contents** — [Prerequisites](#prerequisites) · [Setup](#setup) · [Connect](#connect-your-mcp-client) · [Verify](#verify) · [Updating](#updating) · [Stop](#stop) · [Windows](#windows-docker-desktop) · [Memory](#memory) · [File Tools](#file-tools) · [Config](#configuration) · [Troubleshooting](#troubleshooting)
 
 ## Prerequisites
 
@@ -231,11 +231,17 @@ starter template files on first startup, and agents grow it from there. See
 [Memory](../../README.md#memory) in the main README for how the layer works,
 and [templates/memory](../../templates/memory/README.md) for the file format.
 
+## File Tools
+
+File tools (`vault_read_file`, `vault_list_files`) are enabled by default. Set
+`FILE_TOOLS_ENABLED=false` in your `.env` to hide them — useful when Obsidian
+Sync has attachment syncing disabled and no files exist on disk.
+
 ## Configuration
 
 Only `MCP_AUTH_TOKEN` and `VAULT_PATH` are required. For optional settings
-(memory folder, protected paths, orphan exclusions, timezone), see the
-[Configuration](../../README.md#configuration) section in the main README.
+(memory folder, protected paths, orphan exclusions, file tools, timezone), see
+the [Configuration](../../README.md#configuration) section in the main README.
 
 ## Troubleshooting
 

deploy/local/docker-compose.yml

@@ -28,6 +28,7 @@ services:
       EMBEDDING_ENABLED: ${EMBEDDING_ENABLED:-true}
       RERANK_MODE: ${RERANK_MODE:-blended}
       MEMORY_ENABLED: ${MEMORY_ENABLED:-true}
+      FILE_TOOLS_ENABLED: ${FILE_TOOLS_ENABLED:-true}
       MEMORY_DIR: ${MEMORY_DIR:-About Me}
       LOG_LEVEL: ${LOG_LEVEL:-info}
       LOG_DIR: ${LOG_DIR:-}

deploy/remote/.env.example

@@ -67,6 +67,9 @@ MAX_PDF_RENDER_PAGES=5
 # Enable or disable the memory layer (default: true).
 # Set to false to hide memory tools and skip About Me/ creation.
 MEMORY_ENABLED=true
+# Enable or disable file tools — vault_read_file and vault_list_files (default: true).
+# Set to false when Obsidian Sync has attachment syncing disabled.
+FILE_TOOLS_ENABLED=true
 # Memory folder name in your vault (default: About Me).
 MEMORY_DIR=About Me