docs: document the vfs bundled plugin

build-an-oracle/develop/enable-bundled-plugins.mdx

@@ -1,6 +1,6 @@
 ---
 title: "Enable bundled plugins"
-description: "Toggle the 15 bundled QiForge plugins via the features map — opt out, force on, or let auto-detect handle it — and retune their manifests."
+description: "Toggle the 16 bundled QiForge plugins via the features map — opt out, force on, or let auto-detect handle it — and retune their manifests."
 icon: "boxes-stacked"
 ---
 
@@ -31,7 +31,7 @@
 
 <Steps>
   <Step title="The runtime starts with the bundled list">
-    [`BUNDLED_PLUGINS`](https://github.com/ixoworld/ixo-oracles-boilerplate/blob/main/packages/oracle-runtime/src/plugins/index.ts) is a fixed 15-plugin tuple — memory, portal, firecrawl, domain-indexer, composio, sandbox, skills, editor, agui, slack, tasks, credits, calls, user-preferences, matrix-group-chats.
+    [`BUNDLED_PLUGINS`](https://github.com/ixoworld/ixo-oracles-boilerplate/blob/main/packages/oracle-runtime/src/plugins/index.ts) is a fixed 16-plugin tuple — memory, portal, firecrawl, domain-indexer, composio, sandbox, skills, editor, agui, slack, tasks, credits, calls, user-preferences, matrix-group-chats, vfs.
 
     You do not import or instantiate the plugins you want at defaults — they are already there.
   </Step>
@@ -53,11 +53,11 @@
   </Step>
 
   <Step title="Your own plugins are added next">
     Plugins from the `plugins: []` array are always loaded — they're not gated by `features`. If a name collides with a bundled plugin, your instance wins (the loader dedupes by `name`).
   </Step>
 
   <Step title="Hard-dep cascades resolve transitively">
     If a loaded plugin has `dependsOn: ['removed-plugin']` and that dep ended up excluded, the dependent cascades off too. Soft deps (`softDependsOn`) only log a warning.
   </Step>
 </Steps>
 
@@ -82,6 +82,7 @@
 | `calls` | always on | Visibility `silent`; placeholder stub (no tools yet) |
 | `user-preferences` | always on | Visibility `always` |
 | `matrix-group-chats` | always on | Visibility `on-demand`; gating middleware + tools fire only in Matrix group rooms (`memberCount > 2`) |
+| `vfs` | always on | Visibility `always`; worker URLs derived from `NETWORK`. Contributes tools only when the oracle has a UCAN signing key and the user granted filesystem access |
 
 Full per-plugin env vars: [plugin catalog](/build-an-oracle/reference/bundled-plugins/overview) and [environment variables reference](/build-an-oracle/reference/environment-variables).
 

build-an-oracle/for-ai-agents.mdx

@@ -6,15 +6,15 @@
 
 This page is for AI tools (Cursor, Claude Code, Codex, …) scaffolding a QiForge oracle. Humans should read [Quickstart](/build-an-oracle/quickstart) and [Build a plugin](/build-an-oracle/develop/write-a-plugin) instead.
 
 If you are an AI agent: read top-to-bottom once. Every signature you need is inlined. Source paths cite the canonical files on the QiForge runtime ([`packages/oracle-runtime`](https://github.com/ixoworld/ixo-oracles-boilerplate/tree/main/packages/oracle-runtime)) and the reference oracle ([`apps/qiforge-example`](https://github.com/ixoworld/ixo-oracles-boilerplate/tree/main/apps/qiforge-example)).
 
 <Note>
 **If you are working inside a scaffolded oracle project** (one created with `qiforge-cli new`), there is already a Claude Code skill at `.claude/skills/qiforge-oracle/SKILL.md` with project-local guidance: adding plugins, adding tools, wiring env, writing tests with `createTestRuntime`. Load it first — it carries denser, scenario-specific references than this page.
 </Note>
 
 ## TL;DR — what you produce
 
-A QiForge oracle is **one `main.ts`** that calls `createOracleApp({ config, plugins, … })` plus **one folder per plugin** under `src/plugins/<name>/`. The runtime handles HTTP, auth, the agent graph, the checkpointer, Matrix, and bundles 15 plugins by default. You ship glue code, not infrastructure.
+A QiForge oracle is **one `main.ts`** that calls `createOracleApp({ config, plugins, … })` plus **one folder per plugin** under `src/plugins/<name>/`. The runtime handles HTTP, auth, the agent graph, the checkpointer, Matrix, and bundles 16 plugins by default. You ship glue code, not infrastructure.
 
 ## main.ts shape
 
@@ -210,7 +210,7 @@
 
 From [`packages/oracle-runtime/src/config/base-env-schema.ts`](https://github.com/ixoworld/ixo-oracles-boilerplate/blob/main/packages/oracle-runtime/src/config/base-env-schema.ts):
 
 These are the exact names the runtime validates — set them character-for-character or the boot-time Zod check fails.
 
 | Var | Required | Description |
 | --- | --- | --- |
@@ -220,15 +220,15 @@
 | `ORACLE_ENTITY_DID` | yes | The oracle's on-chain entity DID (`did:ixo:entity:...`). |
 | `SECP_MNEMONIC` | yes | Wallet mnemonic used to sign UCAN invocations to downstream services. |
 | `RPC_URL` | yes | IXO chain RPC endpoint. |
 | `BLOCKSYNC_GRAPHQL_URL` | yes | Blocksync GraphQL endpoint (UCAN validation reads it). |
 | `MATRIX_BASE_URL` | yes | Matrix homeserver URL. |
 | `MATRIX_RECOVERY_PHRASE` | yes | Recovery phrase for the oracle's Matrix encryption. |
 | `MATRIX_ORACLE_ADMIN_USER_ID` | yes | Matrix user ID the bot logs in as. |
 | `MATRIX_ORACLE_ADMIN_PASSWORD` | yes | Matrix bot password. |
 | `MATRIX_ORACLE_ADMIN_ACCESS_TOKEN` | yes | Matrix bot access token. |
 | `MATRIX_ACCOUNT_ROOM_ID` | yes | Oracle's Matrix account room (holds signing key + secrets). |
 | `MATRIX_VALUE_PIN` | yes | PIN for the oracle's Matrix value store / vault. |
 | `SQLITE_DATABASE_PATH` | yes | Path for the per-user SQLite checkpointer DB. |
 | `LLM_PROVIDER` | optional | `openrouter` (default) \| `nebius`. Selects the per-role model map. |
 | `OPEN_ROUTER_API_KEY` | conditional | Required when `LLM_PROVIDER=openrouter` (the default). |
 | `NEBIUS_API_KEY` | conditional | Required when `LLM_PROVIDER=nebius`. |

build-an-oracle/index.mdx

@@ -1,12 +1,12 @@
 ---
 title: "Build an Oracle"
 description: "QiForge is the framework for shipping Agentic Oracles — governed AI evaluators and workflow actors with verifiable identity, encrypted per-user storage, and a plugin runtime you wire up in ~30 lines of TypeScript."
 icon: "compass"
 ---
 
 An **Agentic Oracle** is a governed AI evaluator and workflow actor. It performs **P-Functions** over verifiable state—turning claims, evidence, models, and context into accountable intelligence: typed facts, predictions, recommendations, attestations, determinations, risk signals, compliance checks, payment triggers, and permitted workflow actions.
 
 Unlike a generic AI agent, an oracle is identity-bound, authority-scoped, evidence-grounded, protocol-governed, and audit-producing. Unlike a blockchain or data oracle, it does not merely relay information; it evaluates what information means, which rules apply, which actions are allowed, and what proof must be left behind.
 
 **QiForge** ships the runtime for that pattern: verifiable identity (IXO entity DID), UCAN delegation, encrypted per-user Matrix storage, and typed plugins ([`@ixo/oracle-runtime`](https://github.com/ixoworld/ixo-oracles-boilerplate/tree/main/packages/oracle-runtime)). Your oracle is a `main.ts` plus the plugins you want. For the full concept model, see [Agentic Oracles](/articles/agentic-oracles).
 
@@ -38,7 +38,7 @@
   <Card title="A LangGraph agent" icon="diagram-project">
     Per-request agent build, dynamic tool loading via meta-tools, four always-on middleware (capability gating, tool validation, repetition guard, retry).
   </Card>
-  <Card title="15 bundled plugins" icon="boxes-stacked">
+  <Card title="16 bundled plugins" icon="boxes-stacked">
     `memory`, `skills`, `sandbox`, `portal`, `firecrawl`, `composio`, `editor`, `agui`, `slack`, `credits`, `user-preferences`, and more — toggle them via the `features` map.
   </Card>
   <Card title="A plugin API for your code" icon="puzzle-piece">

build-an-oracle/quickstart.mdx

@@ -14,7 +14,7 @@
 
 A live oracle on `localhost:3000` with:
 
-- The 15 bundled plugins resolved at boot.
+- The 16 bundled plugins resolved at boot.
 - A custom Weather plugin loading on demand.
 - A `GET /weather/now?city=X` public HTTP route.
 - A streaming chat endpoint over SSE.
@@ -183,7 +183,7 @@
 
 | You saw | What it proves |
 | --- | --- |
 | Boot log listing plugins | Loader + topo sort + manifest validation worked. |
 | `excluded plugins:` line with reasons | Env-driven opt-in (`autoDetect`) is wired correctly. |
 | `GET /weather/now` returning JSON | Plugin Nest modules mount + auth exclusions apply. |
 | Agent calling `load_capability` then `get_current_weather` | Dynamic discovery and `loadedPlugins` state work end-to-end. |
@@ -202,10 +202,10 @@
     Every option you can pass — config, plugins, features, hooks.
   </Card>
   <Card title="Bundled plugins" icon="boxes-stacked" href="/build-an-oracle/reference/bundled-plugins/overview">
-    The 15 plugins shipped with the runtime.
+    The 16 plugins shipped with the runtime.
   </Card>
   <Card title="For AI agents" icon="robot" href="/build-an-oracle/for-ai-agents">
     Dense one-pager with every signature inlined.
   </Card>
   <Card title="Understand the model" icon="lightbulb" href="/build-an-oracle/understand/what-is-qiforge">
     Optional. The mental model, runtime layers, plugins vs skills.

build-an-oracle/reference/bundled-plugins/overview.mdx

@@ -4,7 +4,7 @@
 icon: "boxes-stacked"
 ---
 
-The runtime bundles 15 plugins that load by default; opt out per plugin via the `features` map on `createOracleApp`. One additional plugin — [`flows`](/build-an-oracle/reference/bundled-plugins/flows) — ships in the package but is **opt-in only**: wire it in explicitly via the `plugins` array.
+The runtime bundles 16 plugins that load by default; opt out per plugin via the `features` map on `createOracleApp`. One additional plugin — [`flows`](/build-an-oracle/reference/bundled-plugins/flows) — ships in the package but is **opt-in only**: wire it in explicitly via the `plugins` array.
 
 ## At a glance
 
@@ -25,6 +25,7 @@
 | [`calls`](/build-an-oracle/reference/bundled-plugins/calls) | `silent` | On (stub) | — | — |
 | [`user-preferences`](/build-an-oracle/reference/bundled-plugins/user-preferences) | `always` | On | — | — |
 | [`matrix-group-chats`](/build-an-oracle/reference/bundled-plugins/matrix-group-chats) | `on-demand` | On | — | — |
+| [`vfs`](/build-an-oracle/reference/bundled-plugins/vfs) | `always` | On | — (URLs from `NETWORK`) | — |
 | [`flows`](/build-an-oracle/reference/bundled-plugins/flows) | `on-demand` | Opt-in (not bundled) | — | `editor` Qi Flow engine |
 
 `Default state` legend:
@@ -61,7 +62,7 @@
     Web search and human-readable page scraping.
   </Card>
   <Card title="domain-indexer" icon="database" href="/build-an-oracle/reference/bundled-plugins/domain-indexer">
     IXO entity lookup — orgs, projects, DAOs, DIDs.
   </Card>
   <Card title="composio" icon="plug" href="/build-an-oracle/reference/bundled-plugins/composio">
     SaaS tool catalog (Gmail, GitHub, Linear, …).
@@ -96,6 +97,9 @@
   <Card title="matrix-group-chats" icon="comments" href="/build-an-oracle/reference/bundled-plugins/matrix-group-chats">
     Gate the bot + per-room compacted memory for Matrix group rooms.
   </Card>
+  <Card title="vfs" icon="folder" href="/build-an-oracle/reference/bundled-plugins/vfs">
+    Read, write, search, and share the user's real files on their Virtual Filesystem.
+  </Card>
   <Card title="flows" icon="diagram-project" href="/build-an-oracle/reference/bundled-plugins/flows">
     Author and inspect multi-step Qi Flow templates (opt-in).
   </Card>
@@ -103,9 +107,9 @@
 
 ## Wiring custom-constructed plugins
 
 Some plugins accept constructor args. Pass a custom instance via the `plugins` array — the loader dedupes by name, so your instance overrides the bundled default.
 
 **`credits` genuinely needs a Redis client.** Without one the enforcement middleware loads in pass-through mode and the settlement cron is skipped, so production must construct it explicitly:
 
 ```ts
 import { createOracleApp, CreditsPlugin } from '@ixo/oracle-runtime';

build-an-oracle/reference/bundled-plugins/vfs.mdx

@@ -0,0 +1,124 @@
+---
+title: "vfs"
+description: "The user's Virtual Filesystem — read, create, edit, search, organise, and share their real files, inside the folder they granted the oracle."
+icon: "folder"
+---
+
+**Source:** [`packages/oracle-runtime/src/plugins/vfs/`](https://github.com/ixoworld/ixo-oracles-boilerplate/blob/main/packages/oracle-runtime/src/plugins/vfs/)
+
+| Attribute | Value |
+| --- | --- |
+| Visibility | `always` |
+| Stability | `stable` |
+| Category | `data` |
+| Default state | On (always-on; contributes tools only when the oracle has a UCAN signing key **and** the user has granted access) |
+| Depends on | — (`sandbox` is an optional sibling — see [bridge tools](#sandbox-bridge-tools)) |
+
+## Summary
+
+The user's **Virtual Filesystem (VFS)** — their persistent, access-controlled home for real documents, notes, datasets, and artifacts, in folders, searchable and versioned. This is reusable context that lives across sessions — not sandbox scratch files, not chat attachments, not the web.
+
+The oracle acts **as the user**, inside the exact folder the user delegated to it. The **user owns their filesystem and is the sole grantor**: only their key can sign the delegation — the oracle can never grant itself access. Every file the oracle reads or writes is confined to the granted subtree and audited as `invoker=oracle, actor=user`.
+
+The filesystem is securely stored with managed encryption; authorized IXO services can read content to power search and previews, so it is **not** end-to-end encrypted — never describe it as zero-knowledge.
+
+## How the oracle gets access
+
+The user grants access from the IXO Portal — the oracle never self-grants:
+
+<Steps>
+  <Step title="User opens their domain's file access">
+    In the Portal: **your domain → Library → Files → Access** (top-right).
+  </Step>
+  <Step title="User adds the oracle's agent DID">
+    In **Manage access**, paste the oracle's account DID (its `ORACLE_DID`) as the Recipient DID, choose the rights (Read / Write / Delete), set the folder scope and duration, and **Grant access**.
+  </Step>
+  <Step title="The oracle picks it up automatically">
+    The grant is a UCAN delegation deposited in the UCAN Store Worker, addressed to the oracle. Per request the oracle pulls that delegation and mints a fresh, single-use VFS invocation — no extra wiring. Until a grant exists, the file tools return a short message telling the user how to grant access (including the oracle's DID).
+  </Step>
+</Steps>
+
+See [Identity and auth](/build-an-oracle/develop/identity-and-auth) for the two-hop UCAN flow (oracle → UCAN Store → VFS).
+
+## Environment variables
+
+The worker URLs are **bundled per network** — there is nothing to configure. Everything else is optional tuning.
+
+| Var | Required | Description |
+| --- | --- | --- |
+| `NETWORK` | yes | `mainnet` / `testnet` / `devnet`. Selects the bundled VFS + UCAN Store worker URLs (`https://[testnet.\|devnet.]vfs.ixo.earth`). Owned by the core base env schema. |
+| `VFS_MAX_READ_LINES` | no | Max lines a single `vfs_read` window returns. Default `2000`. |
+| `VFS_REQUEST_TIMEOUT_MS` | no | Per-request timeout to the VFS worker. Default `20000`. |
+| `SANDBOX_MCP_URL` | no | Read but not owned (declared by [`sandbox`](/build-an-oracle/reference/bundled-plugins/sandbox)). When set, adds the two [sandbox bridge tools](#sandbox-bridge-tools). |
+
+The oracle's UCAN signing key (loaded from its Matrix account room at boot) is required — without it the plugin contributes no tools.
+
+## What it contributes
+
+- **Tools:** ten file tools, each resolving a fresh single-use UCAN bearer per call:
+
+  | Tool | Ability | What it does |
+  | --- | --- | --- |
+  | `vfs_search` | `fs/read` | Find files by meaning (hybrid lexical + semantic); returns paths + cited line ranges. |
+  | `vfs_grep` | `fs/read` | Find files containing an exact term. |
+  | `vfs_glob` | `fs/list` | Match files by path pattern, e.g. `/notes/*.md`, `**/*.pdf`. |
+  | `vfs_list` | `fs/list` | List a folder's contents. |
+  | `vfs_read` | `fs/read` | Read a file. Text → windowed numbered lines (page with `offset`); images/PDFs → transcribed via the vision model. |
+  | `vfs_write` | `fs/write` | Create a file (or overwrite when the user asked to replace it). |
+  | `vfs_edit` | `fs/write` | Exact-string edit — change one occurrence (or `replaceAll`). |
+  | `vfs_move` | `fs/write` | Move or rename a file. |
+  | `vfs_delete` | `fs/delete` | Move a file to trash (recoverable). |
+  | `vfs_share` | `fs/write` | Publish a file/folder and return an anyone-with-the-link URL. |
+
+- **Sub-agents:** none.
+- **Middleware:** none.
+- **HTTP routes:** none.
+- **Shared state:** none.
+
+### Sandbox bridge tools
+
+When [`sandbox`](/build-an-oracle/reference/bundled-plugins/sandbox) is configured (`SANDBOX_MCP_URL` set), two extra tools move a file between the user's sandbox and their filesystem **server-side — the bytes never pass through the LLM**:
+
+- `sandbox_to_vfs` — persist something the sandbox produced (a report, export, chart) into the user's files so it survives the session.
+- `vfs_to_sandbox` — feed one of the user's files into the sandbox (under `/workspace/data/`) so `sandbox_run` code can process it.
+
+## Opt out / Opt in
+
+```ts
+const app = await createOracleApp({
+  config,
+  features: { vfs: false }, // never load
+  // features: { vfs: true },  // force on (the default — always bundled)
+});
+```
+
+## When to use it
+
+- The user refers to a document, note, file, or folder they "saved", "uploaded", or "shared with you".
+- You need to create, update, or organise a file that should persist across sessions.
+- You need to find or quote something from the user's files ("what did my notes say about X").
+- You can reuse a file the user already has instead of asking them to re-paste it.
+- The user asks you to share a file or make it downloadable.
+- Persist a sandbox artifact into the user's files (`sandbox_to_vfs`), or feed a file into the sandbox (`vfs_to_sandbox`).
+
+## When NOT to use it
+
+- General knowledge or web questions — the files are the user's private content, not a knowledge base of the world.
+- Content the user pasted directly into chat — act on it inline; don't write it to a file unless asked.
+- Temporary/scratch files from a compute run — those belong to the [`sandbox`](/build-an-oracle/reference/bundled-plugins/sandbox), not the user's filesystem.
+- Data another plugin owns (flows, skills, memory) — use that plugin.
+
+<Note>
+If a file action reports no access (or read-only), the oracle relays the grant steps above — with its agent DID — so the user can authorize it, then retries. It never claims a file is missing when the real issue is access.
+</Note>
+
+## Where to read next
+
+<CardGroup cols={2}>
+  <Card title="Identity and auth" icon="id-card" href="/build-an-oracle/develop/identity-and-auth">
+    The two-hop UCAN flow that lets the oracle act as the user.
+  </Card>
+  <Card title="sandbox" icon="server" href="/build-an-oracle/reference/bundled-plugins/sandbox">
+    The compute box the VFS bridges to.
+  </Card>
+</CardGroup>

build-an-oracle/reference/environment-variables.mdx

@@ -1,12 +1,12 @@
 ---
 title: "Environment variables"
 description: "Tier-0 (core) vars the runtime always requires, plus per-plugin vars contributed by each bundled plugin's configSchema."
 icon: "key"
 ---
 
 ## How env validation works
 
 The runtime composes one big Zod schema at boot: the **Tier-0 base schema** (always required) plus every loaded plugin's **`configSchema`**. `process.env` is validated against the merged schema. Missing required vars fail boot with `[boot-error] Plugin '<name>' env validation failed for '<field>'`.
 
 Disabling a plugin (via `features` or `autoDetect`) removes its env requirements automatically.
 
@@ -43,7 +43,7 @@
 | --- | --- | --- | --- |
 | `SQLITE_DATABASE_PATH` | string | — | Required. Must persist across restarts. |
 
 ### Blocksync / chain
 
 | Variable | Type | Default | Notes |
 | --- | --- | --- | --- |
@@ -71,7 +71,7 @@
 | `OPEN_ROUTER_API_KEY` | string | — | Required if `LLM_PROVIDER=openrouter`. |
 | `NEBIUS_API_KEY` | string | — | Required if `LLM_PROVIDER=nebius`. |
 
 Cross-field check (`validateLlmProviderKey`): the API key for the selected `LLM_PROVIDER` must be present — `OPEN_ROUTER_API_KEY` when `LLM_PROVIDER=openrouter` (the default), `NEBIUS_API_KEY` when `LLM_PROVIDER=nebius`. A missing key fails boot with a named-field error (e.g. `OPEN_ROUTER_API_KEY` / `NEBIUS_API_KEY`) rather than a generic upstream 401 at request time. The per-role model ids are hardcoded per provider — there is no env var to swap the main model id (use the `resolveModel` hook for that).
 
 ### Misc
 
@@ -105,7 +105,7 @@
 | `composio` | `COMPOSIO_BASE_URL` | No | Defaults to `https://composio.ixo.earth`. |
 | `sandbox` | `SANDBOX_MCP_URL` | Yes | Must be a valid URL. |
 | `skills` | `SKILLS_CAPSULES_BASE_URL` | No | URL. Defaults to `https://capsules.skills.ixo.earth`. |
 | `slack` | `SLACK_BOT_OAUTH_TOKEN` | Yes | Triggers autoDetect. |
 | `slack` | `SLACK_APP_TOKEN` | No | |
 | `slack` | `SLACK_USE_SOCKET_MODE` | No | Defaults to `'true'`. |
 | `slack` | `SLACK_MAX_RECONNECT_ATTEMPTS` | No | Coerced to number; default `10`. |
@@ -113,14 +113,16 @@
 | `credits` | `SUBSCRIPTION_URL` | No | URL. |
 | `credits` | `SUBSCRIPTION_ORACLE_MCP_URL` | No | URL. |
 | `credits` | `DISABLE_CREDITS` | No | Enum — exactly `'true'` or `'false'` (any other value fails env validation). `'true'` disables the credit-enforcement middleware; the plugin's `autoDetect` also excludes the whole plugin when `DISABLE_CREDITS=true`. |
 | `tasks` | `REDIS_URL` | Yes (when loaded) | Triggers autoDetect. |
 | `tasks` | `TASKS_MAX_PER_USER` | No | Coerced positive int; default `50`. Max scheduled tasks per user. |
 | `tasks` | `TASKS_RUN_LOCK_TTL_SEC` | No | Coerced positive int; default `600`. Per-run lock TTL (seconds). |
 | `tasks` | `TASKS_MIN_CRON_INTERVAL_SEC` | No | Coerced positive int; default `300`. Minimum allowed cron interval (seconds). |
 | `matrix-group-chats` | `CHANNEL_MEMORY_SYNC_INTERVAL_MS` | No | Coerced int, min `1000`; default `60000`. Debounce window between a write and the Matrix snapshot upload. |
 | `matrix-group-chats` | `GROUP_CHAT_ACTIVE_THREAD_TTL_MS` | No | Coerced int, min `60000`; default `1800000`. How long a thread stays "active with the bot" after a reply. |
 | `matrix-group-chats` | `GROUP_CHAT_REQUIRE_POWER_LEVEL` | No | Coerced int, min `0`; default `0`. Extra minimum power level the bot must have before posting (`0` = use the room default). |
 | `matrix-group-chats` | `GROUP_CHAT_ROOM_INFO_TTL_MS` | No | Coerced int, min `60000`; default `1800000`. How long roomInfo (membership, DM flag) stays cached. |
+| `vfs` | `VFS_MAX_READ_LINES` | No | Coerced positive int; default `2000`. Max lines a single `vfs_read` window returns. |
+| `vfs` | `VFS_REQUEST_TIMEOUT_MS` | No | Coerced positive int; default `20000`. Per-request timeout to the VFS worker. |
 
 ## Variables read but not owned
 
@@ -129,6 +131,7 @@
 - **`composio`** reads the core `NETWORK` and forwards it as `x-ixo-network`.
 - **`skills`** reads `NETWORK` and forwards as `X-IXO-Network`.
 - **`sandbox`** reads `ORACLE_SECRETS` (core) and `SKILLS_CAPSULES_BASE_URL` (owned by `skills`) and forwards them as headers.
+- **`vfs`** reads the core `NETWORK` (selects the bundled VFS + UCAN Store worker URLs — nothing to configure) and `SANDBOX_MCP_URL` (owned by `sandbox`; when set, adds the two sandbox↔files bridge tools).
 
 These are declared in the plugin's sibling schemas (typed `optional()`); a missing value just skips the matching header instead of failing the plugin build.
 

build-an-oracle/reference/plugin-api.mdx

@@ -210,4 +210,4 @@ Boot-time errors in `autoDetect`, `configSchema` validation, or `manifest` valid
 - [PluginContext](/build-an-oracle/reference/plugin-context)
 - [RuntimeContext](/build-an-oracle/reference/runtime-context)
 - [Manifest schema](/build-an-oracle/reference/manifest-schema)
-- [Plugin catalog](/build-an-oracle/reference/bundled-plugins/overview) — the 15 bundled plugins.
+- [Plugin catalog](/build-an-oracle/reference/bundled-plugins/overview) — the 16 bundled plugins.

build-an-oracle/understand/architecture.mdx

@@ -18,7 +18,7 @@
 
     subgraph Runtime["@ixo/oracle-runtime"]
         Core["Always-on Nest modules<br/>Sessions · Messages · WS · Secrets · UCAN · Auth · Subscription · Throttler · Checkpointer"]
-        Bundled["15 bundled plugins<br/>memory · skills · sandbox · editor · agui · portal · firecrawl · domain-indexer · composio · slack · credits · user-preferences · matrix-group-chats · tasks · calls"]
+        Bundled["16 bundled plugins<br/>memory · skills · sandbox · editor · agui · portal · firecrawl · domain-indexer · composio · slack · credits · user-preferences · matrix-group-chats · tasks · calls · vfs"]
         Agent["LangChain agent<br/>built per request"]
     end
 
@@ -41,17 +41,17 @@
 
 **You own:** the entry point, your oracle's identity, custom plugins, custom Nest modules.
 
 **You don't own:** the agent loop, the graph state shape, the checkpointer, the auth flow, the meta-tools, the bundled plugins' internals.
 
 ### Layer 2 — `@ixo/oracle-runtime`
 
 The framework. Owns the bootstrap (`createOracleApp`), the always-on Nest modules (Sessions, Messages, WebSocket, Secrets, UCAN, Auth, Subscription, Throttler, Health), the per-request agent builder, the four always-on agent middleware (capability gate, tool validation, tool-repetition guard, tool retry — plus page-context and safety-guardrail when their hooks are set), the Matrix-backed SQLite checkpointer, and the plugin API.
 
 You never edit this layer. Updates come via `pnpm update @ixo/oracle-runtime`.
 
 ### Layer 3 — Bundled plugins
 
-15 plugins shipped inside the runtime package, each independently toggleable via `features`. See the [Plugin catalog](/build-an-oracle/reference/bundled-plugins/overview) for what each one does.
+16 plugins shipped inside the runtime package, each independently toggleable via `features`. See the [Plugin catalog](/build-an-oracle/reference/bundled-plugins/overview) for what each one does.
 
 ## Bootstrap, in one picture
 
@@ -77,22 +77,22 @@
 
 | Registry | Holds | Collision rule |
 | --- | --- | --- |
 | ToolRegistry | All plugin tools | Flat namespace — collision is a boot error |
 | SubAgentRegistry | All plugin sub-agents | Flat namespace — collision is a boot error |
 | MiddlewareRegistry | All plugin middleware | Ordered topologically; no names |
 | ManifestRegistry | All plugin manifests | Title collision = soft warn |
 | ConfigSchemaRegistry | All plugin Zod schemas | Merged; later wins with warning |
 | SharedStateRegistry | Plugin shared-state accessors | Flat namespace — collision is a boot error |
 
 Source: [`packages/oracle-runtime/src/registries/`](https://github.com/ixoworld/ixo-oracles-boilerplate/blob/main/packages/oracle-runtime/src/registries/).
 
 ## What's pluggable vs fixed
 
 | Pluggable | Fixed |
 | --- | --- |
 | Plugin set (bundled toggles + your plugins) | Agent loop (LangChain `createAgent`) |
 | `nestModules` (your Nest modules) | Graph state shape (except one new `loadedPlugins` field) |
 | `authExcludedRoutes` (host + plugin) | Checkpointer (Matrix-backed SQLite) |
 | LLM provider (env-driven) | Auth flow (UCAN delegation) |
 | `hooks.checkpointerForUser` (advanced) | The four always-on middleware |
 | System prompt (via `OracleConfig.prompt`) | The Tier-1 block format |
@@ -130,7 +130,7 @@
 
 The runtime only calls `resolveModel('main')` itself, so a hook that special-cases `'main'` swaps **only the main agent's model**; sub-agents and utility calls keep the provider defaults unless your own code routes them through the hook too.
 
 `resolveModel` is one of several `hooks` — the framework's advanced extension surface. Others include `checkpointerForUser` (swap the per-user checkpointer), `safetyModel` (enable the safety-guardrail middleware), `getRoomTitle` (enable the page-context middleware), and prompt-block overrides like `operationalMode`. See the [`createOracleApp` reference](/build-an-oracle/reference/createoracleapp) for the full list.
 
 ## Read next
 

build-an-oracle/understand/plugins-vs-skills.mdx

@@ -74,7 +74,7 @@ Not directly. Skills run in a sandbox; they don't see plugins or Nest DI. They g
     The recipe.
   </Card>
   <Card title="Plugin catalog" icon="boxes-stacked" href="/build-an-oracle/reference/bundled-plugins/overview">
-    The 15 bundled plugins — including `skills` and `sandbox`.
+    The 16 bundled plugins — including `skills` and `sandbox`.
   </Card>
 </CardGroup>
 

build-an-oracle/understand/what-is-qiforge.mdx

@@ -1,14 +1,14 @@
 ---
 title: "What is QiForge?"
 description: "QiForge is the framework for building Agentic Oracles on IXO — AI agents with a verifiable identity, encrypted per-user storage, and a plugin runtime."
 icon: "compass"
 ---
 
 ## The one-pager
 
 An **Agentic Oracle** is an AI agent that owns a verifiable identity on IXO, talks to users through encrypted per-user Matrix rooms, authenticates every request via UCAN delegation, and composes its capabilities from plugins (compiled in) and skills (discovered at runtime).
 
-**QiForge is the framework that lets you ship one.** The runtime (`@ixo/oracle-runtime`) handles bootstrap, auth, the agent loop, the checkpointer, Matrix wiring, and 15 bundled plugins. Your oracle is a thin `main.ts` plus whatever custom plugins you write.
+**QiForge is the framework that lets you ship one.** The runtime (`@ixo/oracle-runtime`) handles bootstrap, auth, the agent loop, the checkpointer, Matrix wiring, and 16 bundled plugins. Your oracle is a thin `main.ts` plus whatever custom plugins you write.
 
 ## Three layers, one diagram
 
@@ -57,7 +57,7 @@
 
 <CardGroup cols={2}>
   <Card title="Architecture" icon="diagram-project" href="/build-an-oracle/understand/architecture">
     The three layers, bootstrap flow, and what's pluggable vs fixed.
   </Card>
   <Card title="Quickstart" icon="play" href="/build-an-oracle/quickstart">
     Build a working oracle in 10 minutes with the CLI.

docs.json

@@ -225,6 +225,7 @@
                   "build-an-oracle/reference/bundled-plugins/calls",
                   "build-an-oracle/reference/bundled-plugins/user-preferences",
                   "build-an-oracle/reference/bundled-plugins/matrix-group-chats",
+                  "build-an-oracle/reference/bundled-plugins/vfs",
                   "build-an-oracle/reference/bundled-plugins/flows"
                 ]
               }