@ixo/oracle-runtime-workers 0.37.2 → 0.39.0

package/src/plugins/memory/oracle-document-tools.ts

@@ -32,70 +32,59 @@ const DOCUMENT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,119}$/;
 const spaceSchema = z
   .enum(['public', 'private'])
   .describe(
-    "Which knowledge space: 'public' is shared with every user of this oracle; 'private' is visible only to the domain's members (its controllers, owner, admins and DAO members).",
+    "'public': every user of this oracle. 'private': the domain's members only (controllers, owner, admins, DAO members).",
   );
 
 const sourceSchema = z
   .object({
     kind: z
       .enum(['attachment', 'vfs'])
-      .describe(
-        "'attachment' for a file the person attached in this conversation, 'vfs' for a file in their Library.",
-      ),
+      .describe("'attachment': attached here. 'vfs': in their Library."),
     ref: z
       .string()
       .min(1)
       .describe(
-        'For kind attachment: the value inside the `[source: eventId="…"]` (or `[source: url="…"]`) line that accompanies the attached file, passed exactly as given (an event id such as "$abc…" or an mxc:// URL). For kind vfs: the file path in the Library, for example /private/policies/travel.pdf.',
+        'attachment: the value in the `[source: eventId="…"]` or `[source: url="…"]` line beside the file, exactly as given ("$abc…" or an mxc:// URL). vfs: the Library path, e.g. /private/policies/travel.pdf.',
       ),
   })
-  .strict()
-  .describe('Where the file is.');
+  .strict();
 
 export const addOracleDocumentSchema = z
   .object({
     source: sourceSchema,
-    title: z
-      .string()
-      .min(1)
-      .max(200)
-      .describe('A short human title for the document, 1 to 200 characters.'),
+    title: z.string().min(1).max(200),
     knowledge_space_type: spaceSchema,
-    group_as_document: z
-      .boolean()
-      .describe(
-        'Required, no default. true: the file is ONE coherent record and is kept together under a document id (it can be listed and removed as one). false: the file is a collection of unrelated facts and each part is stored as ordinary loose knowledge with no document grouping. Decide with the person, see the tool description.',
-      ),
+    group_as_document: z.boolean(),
     document_id: z
       .string()
       .regex(DOCUMENT_ID_PATTERN)
       .optional()
       .describe(
-        "Only with group_as_document true (ignored otherwise). A stable id such as 'board-resolution-2026-10' (letters, digits, '.', '_' and '-', up to 120 characters, starting with a letter or digit). Adding a document with an id that already exists replaces it. Leave out and the tool derives one from the title and the content, so adding the same file again replaces it.",
+        "Grouped only: a stable id such as 'board-resolution-2026-10'. Default: derived from title and content, so adding the same file again replaces it.",
       ),
     source_description: z
       .string()
       .max(500)
       .optional()
       .describe(
-        "Only with group_as_document true (ignored otherwise). One line saying where the document comes from, up to 500 characters (for example 'Signed PDF from the board secretary, 12 Oct 2026').",
+        "Grouped only: where it comes from, e.g. 'Signed PDF from the board secretary, 12 Oct 2026'.",
       ),
     if_exists: z
       .enum(['replace', 'fail'])
       .optional()
       .describe(
-        "Only with group_as_document true (ignored otherwise). 'replace' (default) overwrites a grouped document with the same document_id; 'fail' refuses instead.",
+        "Grouped only: for a document_id that exists, 'replace' (default) or 'fail'.",
       ),
     allow_truncation: z
       .boolean()
       .optional()
       .describe(
-        'Default false. When the file is larger than the limits the tool refuses and tells you the size. Set true only after the person agreed that the first part of the file is enough.',
+        'true keeps only the first part of a file over the limits. Only after the person agreed.',
       ),
     confirmed_insertion_from_user: z
       .boolean()
       .describe(
-        'true only when the person has explicitly asked you to store this file as oracle knowledge after you told them who will be able to see it. Otherwise ask first.',
+        'true only after the person asked to store this file and you told them who will see it.',
       ),
   })
   .strict();
@@ -108,57 +97,43 @@ export const listOracleDocumentsSchema = z
     knowledge_space_type: spaceSchema,
     status: z
       .enum(['ingesting', 'ready', 'partial', 'deleting', 'delete_failed'])
-      .optional()
-      .describe('Only list documents in this status. Leave out for all.'),
+      .optional(),
     limit: z
       .number()
       .int()
       .min(1)
       .max(MAX_LIST_LIMIT)
       .optional()
-      .describe(
-        `Most documents to list, 1 to ${MAX_LIST_LIMIT} (default ${DEFAULT_LIST_LIMIT}).`,
-      ),
+      .describe(`Default ${DEFAULT_LIST_LIMIT}.`),
   })
   .strict();
 
 export const deleteOracleDocumentSchema = z
   .object({
-    document_id: z
-      .string()
-      .regex(DOCUMENT_ID_PATTERN)
-      .describe(
-        'The id of a grouped document, as shown by list_oracle_documents.',
-      ),
+    document_id: z.string().regex(DOCUMENT_ID_PATTERN),
     knowledge_space_type: spaceSchema,
-    confirmed_deletion_from_user: z
-      .boolean()
-      .describe(
-        'true only when the person has explicitly asked you to remove this document after you told them it will be deleted for everyone who can see that space.',
-      ),
+    confirmed_deletion_from_user: z.boolean(),
   })
   .strict();
 
 export const ADD_ORACLE_DOCUMENT_DESCRIPTION = [
-  "Use this, not memory-engine__add_oracle_knowledge, whenever the knowledge comes from a file: one the person attached or one in their Library, even when the file's text is visible in the conversation. Store that file as this oracle's domain knowledge. For an attachment, set source to kind 'attachment' and ref to the value inside the `[source: eventId=…]` (or `[source: url=…]`) line that accompanies the attached file: pass that eventId or mxc URL as ref. For a Library file, kind 'vfs' and ref the path. The text is read out of the file, split into parts and written to the public or private knowledge space of this oracle. Only a controller, owner, admin or DAO member of the domain can do this; the memory engine checks and refuses anyone else.",
-  '',
-  'Decide with group_as_document, which is required and has no default:',
-  '- true: the file is ONE coherent record that belongs together, such as a board resolution, a contract or a report. It is stored under one document id, so it can be listed with list_oracle_documents, replaced by adding it again with the same document_id, and removed as one with delete_oracle_document.',
-  '- false: the file is a place where someone dumped many unrelated company facts to upload them easily (for example a notes file with the office address, the refund rule, the CEO name and the opening hours). Each part is stored as an ordinary knowledge fact with no document grouping. Loose facts cannot be listed as a document or removed as a group; they are found by search and removed one by one with delete_episode.',
+  "Use this, not memory-engine__add_oracle_knowledge, whenever the knowledge comes from a file the person attached or one in their Library, even when its text is visible in the conversation. The file's text is split into parts and stored in this oracle's public or private knowledge space. The memory engine refuses anyone but a controller, owner, admin or DAO member of the domain.",
   '',
-  'If it is not obvious which one the file is, ask the person before you call this tool. Say what you found in the file in one sentence and offer the two options in plain words. Never pick one silently when the file could be either.',
+  'group_as_document is required and has no default:',
+  '- true: ONE coherent record, such as a board resolution, a contract or a report. Kept under one document id: listed with list_oracle_documents, replaced by adding it again, removed as one with delete_oracle_document.',
+  '- false: a dump of unrelated company facts (a notes file with the office address, the refund rule, the opening hours). Each part becomes a loose fact: found by search, removed one by one with delete_episode.',
+  'If the file could be either, ask the person first: say what you found in one sentence and offer the two options in plain words. Never pick silently.',
   '',
-  'Always confirm first: tell the person whether the public space (every user of this oracle) or the private space (the members of the domain only: controllers, owner, admins and DAO members) will hold the content, and set confirmed_insertion_from_user to true only after they say yes. Do not store files the person did not ask you to store.',
+  'Always confirm first: tell the person which space will hold the content and only then set confirmed_insertion_from_user. Never store a file they did not ask you to store.',
   '',
-  'Limits: a text file or a PDF with a text layer up to 25 MB; a scanned PDF, an image or an Office file (read by a helper model) up to 10 MB. Text is split into parts of about 12 KB, at most 64 parts (about 750 KB of text, the memory engine accepts 900 KB per document). A larger file is refused with its size unless allow_truncation is true, which keeps only the first part of the file; use that only if the person agrees. Without a document_id a grouped document gets one derived from the title and content, so repeating the call after a timeout replaces rather than duplicates; the result reports the id.',
-  'The result says how many parts were queued. Indexing continues in the background; for a grouped document list_oracle_documents shows the status (ingesting, ready, partial, deleting or delete_failed).',
+  'Limits: text or a PDF with a text layer up to 25 MB; a scanned PDF, image or Office file up to 10 MB; at most 64 parts of about 12 KB. A larger file is refused with its size unless allow_truncation is set. The result gives the parts queued and the document id; indexing continues in the background (list_oracle_documents shows its status).',
 ].join('\n');
 
 export const LIST_ORACLE_DOCUMENTS_DESCRIPTION =
-  "List the grouped documents in one of this oracle's knowledge spaces with their id, title, status (ingesting, ready, partial, deleting or delete_failed) and number of parts. Optional status filter and limit (default 100, at most 500). Loose facts stored with group_as_document false are not listed here; they are ordinary knowledge found by search.";
+  "List the grouped documents in one of this oracle's knowledge spaces: id, title, status, parts. This is the oracle's knowledge base, not the domain documents of the verified domain context. Loose facts (group_as_document false) are not listed; they are found by search.";
 
 export const DELETE_ORACLE_DOCUMENT_DESCRIPTION =
-  'Remove a grouped document and every one of its parts from the public or private knowledge space of this oracle. Use the id from list_oracle_documents. This cannot be undone and it takes effect for everyone who can see that space, so tell the person which document will go and set confirmed_deletion_from_user to true only after they say yes. Loose facts are not documents; remove those with delete_episode. The removal runs in the background; if list_oracle_documents later shows the document as delete_failed, call this again to retry it.';
+  'Remove a grouped document, with all its parts, for everyone who can see that space. Cannot be undone: tell the person which document will go and set confirmed_deletion_from_user only after they say yes. Loose facts: use delete_episode. Runs in the background; if list_oracle_documents later shows delete_failed, call this again to retry.';
 
 const NO_ENGINE_MESSAGE =
   'Memory engine is not reachable from this oracle (missing MEMORY_ENGINE_URL or signing key).';

package/src/plugins/pod-creator/pod-creator.plugin.ts

@@ -58,6 +58,7 @@ const manifest: PluginManifest = {
   tags: ['pod', 'domain', 'design', 'orchestration', 'on-chain'],
   category: 'automation',
   visibility: 'on-demand',
+  brief: 'design and create an IXO POD end to end',
   stability: 'experimental',
 };
 

package/src/plugins/portal/portal.plugin.ts

@@ -53,6 +53,7 @@ const manifest: PluginManifest = {
   tags: ['portal', 'browser', 'ui'],
   category: 'ui',
   visibility: 'on-demand',
+  brief: "act in the user's Portal through browser tools",
   stability: 'stable',
 };
 

package/src/plugins/sandbox/sandbox-write-blob.ts

@@ -7,25 +7,13 @@ import type { SandboxMcpTool } from './sandbox.plugin';
 const sandboxWriteBlobSchema = z.object({
   blobId: z
     .string()
-    .describe(
-      'The blobId returned by the tool that produced the value (e.g. mint_invocation). Format: `blob_<16 hex chars>`.',
-    ),
+    .describe('`blob_<16 hex chars>`, from the tool that made the value.'),
   path: z
     .string()
-    .describe(
-      'Destination path in the sandbox, e.g. `/workspace/data/<skill>/ucan_token`. Must be under /workspace/data/.',
-    ),
+    .describe('Under /workspace/data/, e.g. `/workspace/data/<skill>/token`.'),
 });
 
-const SANDBOX_WRITE_BLOB_DESCRIPTION = `Write a server-stored blob to a file in the sandbox without ever paste-relaying the value through the LLM.
-
-Use this whenever a tool returns a \`blobId\` (e.g. \`mint_invocation\`'s response). Pass the blobId + the destination path; the runtime looks the value up server-side and calls sandbox_write_file with its content. The long opaque value (base64 CARs, JWTs, etc.) never enters the LLM context — eliminates string-corruption-in-relay as a failure mode.
-
-Inputs:
-  - blobId: short hex identifier returned by the producing tool (format \`blob_<16 hex chars>\`).
-  - path: destination path in the sandbox. Must be under \`/workspace/data/\` (the sandbox enforces this; writes elsewhere are rejected).
-
-Returns: \`{ success: true, path, bytesWritten }\` on success, \`{ success: false, error }\` on failure. Common errors: blob not found (re-mint and retry — for invocations this can happen on a multi-replica deployment if the lookup lands on a different process), invalid blobId format, path outside /workspace/data/.`;
+const SANDBOX_WRITE_BLOB_DESCRIPTION = `Write a server-stored value to a sandbox file without passing it through you, so a long opaque value (base64 CAR, JWT) cannot be corrupted. Use it whenever a tool returns a \`blobId\` (e.g. \`mint_invocation\`). Returns \`{ success, path, bytesWritten }\` or \`{ success: false, error }\`; on "blob not found", mint it again and retry.`;
 
 export interface CreateSandboxWriteBlobToolParams {
   /** Upstream MCP `sandbox_write_file` tool — looked up once per request from

package/src/plugins/sandbox/sandbox.plugin.ts

@@ -51,10 +51,20 @@ const siblingEnvSchema = z.object({
   SKILLS_CAPSULES_BASE_URL: z.string().url().optional(),
 });
 
+// In the guide and not in the summary: an `always` host would pay for it in
+// the capability block on top of the tool descriptions, and a preload delivers
+// a guide but not the manifest.
+const OPERATING_GUIDE = [
+  '### Sandbox',
+  '- `sandbox_run` writes anywhere through the shell, `/tmp` included. `sandbox_write_file` writes raw bytes under `/workspace/data/` only: paths like `/tmp/...` or `/workspace/tmp/...` are rejected.',
+  "- A file at a path the user names belongs in their library (`vfs`), not here. Report the path you really wrote: `/workspace/data/...` is the box, not the user's `/...`.",
+  '- The box is a scratch disk, not your file store. Files under `/workspace/data/` are pushed up to durable storage after each call, but nothing comes back down automatically and the box is wiped after a few idle minutes. Any file not created in the current call must be fetched with `load_artifact` before you can read it.',
+].join('\n');
+
 const manifest: PluginManifest = {
   title: 'Sandbox',
   summary:
-    'Per-user Linux box for code execution. `sandbox_run` runs shell/python (writes anywhere via shell — incl. `/tmp` for scratch). `sandbox_write_file` writes raw bytes BUT only under `/workspace/data/` — paths like `/tmp/...` or `/workspace/tmp/...` are rejected; use `sandbox_run` for those. STORAGE: the box is a scratch disk, not your file store. Files under `/workspace/data/` are pushed UP to durable storage after each call, but NOTHING comes back DOWN automatically and the box is wiped after a few idle minutes. Any file not created in the current call must be fetched with `load_artifact` before you can read it.',
+    'Per-user Linux box: `sandbox_run` runs shell or python, `sandbox_write_file` writes under `/workspace/data/`.',
   whenToUse: [
     "Execute a skill — call `sandbox_run` with `cid` so user + oracle secrets are injected; the skill folder mounts read-only at `/workspace/skills/<skill-name>/` (use the absolute paths from `load_skill`'s `skillFiles`).",
     'Read a skill file (SKILL.md, scripts, configs) — call `sandbox_run` with `cid` and shell: `cat /workspace/skills/<skill-name>/SKILL.md`, `ls /workspace/skills/<skill-name>/`, `grep -r "<pattern>" /workspace/skills/<skill-name>/`, or `sed -n "1,80p" <file>` for a line range. There is no dedicated `read_skill` tool.',
@@ -67,6 +77,7 @@ const manifest: PluginManifest = {
     'Always check the result envelope: `success === true` AND `exitCode === 0` before trusting `output`. On failure, READ the `error` text and change your approach — do not retry the same call with the same args.',
   ],
   whenNotToUse: [
+    'Saving a file at a path the user names: that is their library, use `vfs`.',
     'The value is already inline in chat — just use it; opening the sandbox to echo it back wastes a turn.',
     'Fetching a URL the user just mentioned — prefer `process_file`, which archives it as an artifact (pull it into the box with `load_artifact` when you need to read it).',
     'A long human-readable page (blog, article, news) — use the Firecrawl agent.',
@@ -139,7 +150,12 @@ const manifest: PluginManifest = {
       },
     },
   ],
-  visibility: 'always',
+  // Every tool loads together: running code, its files and artifacts and the
+  // skill lifecycle (`load_skill` included) depend on one another. A host
+  // that wants it on every turn sets `visibility: 'always'` through
+  // `manifestOverrides`.
+  visibility: 'on-demand',
+  brief: 'run code; run or publish skills; generate charts and reports',
   stability: 'stable',
   category: 'core',
   tags: ['sandbox', 'execution', 'workspace', 'artifacts'],
@@ -249,6 +265,7 @@ export class SandboxPlugin extends OraclePlugin {
   readonly name = SandboxPlugin.NAME;
   readonly version = '1.0.0';
   readonly manifest = manifest;
+  override readonly operatingGuide = OPERATING_GUIDE;
   override readonly configSchema = configSchema;
   override readonly autoDetectHint = 'SANDBOX_MCP_URL';
 

package/src/plugins/tasks/manifest.ts

@@ -76,6 +76,7 @@ export const tasksManifest: PluginManifest = {
   ],
   category: 'automation',
   visibility: 'on-demand',
+  brief: 'reminders, scheduled and recurring background jobs',
   stability: 'beta',
   tags: ['scheduler', 'cron', 'automation', 'approval', 'background'],
 };

package/src/plugins/tasks/tasks-tools.ts

@@ -9,6 +9,7 @@
  * model always gets an actionable message.
  */
 import { z } from 'zod';
+import { modelFacingSchema } from '../compact-schema';
 import { tool } from '../../plugin-api/tool-helper';
 import type {
   OracleTaskRecord,
@@ -32,14 +33,11 @@ const taskIdSchema = z.object({
 });
 
 const APPROVAL_FIELD_DESCRIPTION =
-  "How each run behaves. 'never' (default) just does the work and delivers " +
-  "the result. 'before-action' is for runs the user should sign off on first " +
-  '(a tweet, a message, a ticket, an email, a publish): when such a task ' +
-  'fires it does NOT execute — it posts an approval request into the ' +
-  "user's oracle room and waits. The user approves or declines by replying " +
-  'there; record the decision with `resolve_task_approval` — approval ' +
-  'starts the run in the background (its result is posted to the room when ' +
-  'it finishes), a decline drops it.';
+  "'never' (default): do the work and deliver the result. 'before-action': for " +
+  'runs the user should sign off on first (a tweet, a message, a ticket, an ' +
+  'email, a publish): each fire posts an approval request into their oracle ' +
+  'room and waits; they reply there and you record it with ' +
+  '`resolve_task_approval`.';
 
 const taskInputShape = {
   title: z.string().min(1).max(120),
@@ -47,7 +45,7 @@ const taskInputShape = {
     .string()
     .min(1)
     .describe(
-      'Markdown instructions the run executes. Scheduled runs are BACKGROUND sessions with NO memory of this conversation — put every ID, URL, and name the run needs into this text, never assume the run "knows" anything discussed here.',
+      'Markdown instructions for a background run with NO memory of this conversation: every ID, URL and name it needs goes here.',
     ),
   // Flat at the tool boundary (a `kind` enum + optional per-kind fields),
   // converted to the store's discriminated union on parse — see
@@ -61,11 +59,8 @@ const taskInputShape = {
     .enum(['auto', 'yes', 'no'])
     .default('auto')
     .describe(
-      "Whether the task gets its own '[Task] <title>' room where each run's result " +
-        "(and, for 'before-action' tasks, each approval request) is posted. 'auto' " +
-        'creates one for frequent (sub-daily) cron tasks, long intents and ongoing ' +
-        'monitor/watch/track tasks; otherwise results go to the main oracle room. ' +
-        'Pass yes/no only when the user asked for it.',
+      "Whether results and approval requests get their own '[Task] <title>' room " +
+        "instead of the main oracle room. 'auto' decides; yes/no only when the user asked.",
     ),
 };
 
@@ -160,7 +155,7 @@ function previewTask(): PluginTool {
       name: 'preview_task',
       effect: 'read',
       description:
-        'Validate a candidate task spec and return its next run times WITHOUT creating anything. ALWAYS call this before create_task and show the user the result. IMPORTANT: scheduled runs are fresh background sessions with NO memory of this conversation — put every ID, URL, and name the run needs into the intent text.',
+        'Validate a candidate task spec and return its next run times WITHOUT creating anything. ALWAYS call this before create_task and show the user the result.',
       schema: previewInput,
     },
   );
@@ -190,8 +185,8 @@ function createTask(): PluginTool {
     {
       name: 'create_task',
       description:
-        'Schedule a previewed task. Call this ONLY after the user has seen the preview_task output and confirmed in a NEW message — never in the same turn as preview_task. TRIGGER CHOICE: "in 10 minutes", "tomorrow at 5pm" = kind "once" (compute `at` from now) — cron is ONLY for genuinely recurring schedules; `*/10 * * * *` means every-10-minutes-forever, not once-in-10-minutes. Set `approval` to "before-action" when a run would send/post/publish/create anything on the user\'s behalf: each fire then posts an approval request into their room and runs only once they approve. Runs are FRESH background sessions with no memory of this conversation — every ID/URL/name the run needs must be in the intent.',
-      schema: createInput,
+        'Schedule a previewed task, with the same fields as preview_task. Call this ONLY after the user has seen the preview_task output and confirmed in a NEW message, never in the same turn as preview_task. Set `approval` to "before-action" when a run would send, post, publish or create anything on the user\'s behalf.',
+      schema: modelFacingSchema(createInput, { descriptions: false }),
     },
   );
 }
@@ -311,8 +306,8 @@ function updateTask(): PluginTool {
     {
       name: 'update_task',
       description:
-        'Patch a task — title, schedule, approval mode, or intent (what the task does). Changing the intent changes what every future run executes, so show the user the revised intent and get their confirmation first. Changing the schedule reschedules the next run automatically.',
-      schema: updateInput,
+        'Patch a task: title, schedule, approval or intent, as in preview_task. A new intent changes what every future run executes: show it to the user and get their confirmation first. A new schedule reschedules the next run.',
+      schema: modelFacingSchema(updateInput, { descriptions: false }),
     },
   );
 }

package/src/plugins/user-preferences/user-preferences-tool.ts

@@ -1,8 +1,7 @@
 /**
- * `set_user_preferences` — the Node runtime's tool, verbatim in schema and
- * description (the description is prompt material the model has been tuned
- * against; keep it in sync with `packages/oracle-runtime`). The handler
- * writes through the host's `ctx.preferences` surface for the active room.
+ * `set_user_preferences`: the Node runtime's tool, the same schema with
+ * shorter text (the model reads it on every call). The handler writes
+ * through the host's `ctx.preferences` surface for the active room.
  */
 import { z } from 'zod';
 import { tool } from '../../plugin-api/tool-helper';
@@ -26,67 +25,42 @@ export const setUserPreferencesSchema = z.object({
     .string()
     .max(80)
     .optional()
-    .describe(
-      "What the user wants you (the agent) to be called (e.g. 'Companion'). Use exactly the form the user asked for. Max 80 characters.",
-    ),
+    .describe('What the user wants to call you, in exactly their form.'),
   userName: z
     .string()
     .max(80)
     .optional()
-    .describe(
-      "What the user wants you to call them (e.g. 'Yousef'). Use exactly the form the user asked for. Max 80 characters.",
-    ),
+    .describe('What the user wants to be called, in exactly their form.'),
   language: z
     .string()
     .max(20)
     .optional()
     .describe(
-      "Preferred reply language as a free-form code or name (e.g. 'en', 'ar', 'Arabic', 'Egyptian Arabic'). " +
-        'Be precise — if the user specified a dialect or variant, capture that. Max 20 characters.',
+      "Reply language, code or name, with any dialect (e.g. 'ar', 'Egyptian Arabic').",
     ),
   tone: z
     .string()
     .max(MAX_TONE_LENGTH)
     .optional()
     .describe(
-      "Short tone label your future self will see at the top of every prompt (e.g. 'playful and warm', " +
-        `'concise and dry', 'patient teacher'). Pick descriptive words, not vague ones. Max ${MAX_TONE_LENGTH} characters.`,
+      "Short descriptive tone label (e.g. 'playful and warm', 'concise and dry').",
     ),
   formality: z
     .enum(FORMALITY_LEVELS)
     .optional()
-    .describe(
-      'How formal the replies should be. Pick the value closest to what the user actually wants, ' +
-        'not what the request literally said.',
-    ),
+    .describe('The value closest to what the user actually wants.'),
   customInstructions: z
     .string()
     .max(2000)
     .optional()
     .describe(
-      'Free-form custom instructions your FUTURE SELF will read every turn. Treat this like writing ' +
-        'a system prompt: be specific, complete, and unambiguous. Include the WHY when it matters ' +
-        "(e.g. 'User has dyslexia — keep sentences short and avoid long lists'). " +
-        'When updating, MERGE with existing instructions rather than replacing — read what is already ' +
-        'there (visible in your current system prompt under "User Preferences") and write the full new ' +
-        'instruction set, preserving anything still relevant. Max 2000 characters.',
+      'Instructions you will read on every turn, like a system prompt: specific, complete, with the why when it matters (e.g. \'User has dyslexia: short sentences, no long lists\'). This field is replaced whole: write the full new set, keeping what is still relevant from "User Preferences" in your system prompt.',
     ),
 });
 
 export const SET_USER_PREFERENCES_DESCRIPTION =
-  "Update the user's preferences. Call this whenever the user asks you to change how you behave " +
-  "(e.g. 'call me Yousef', 'reply in Arabic', 'be more casual').\n\n" +
-  'IMPORTANT — you are writing instructions for your FUTURE SELF. ' +
-  'On every later turn this exact text will be injected back into your system prompt and you will read it cold, ' +
-  'with no memory of this conversation or why the user asked. So:\n' +
-  "  • Be specific and self-contained. Don't write 'be more casual' — write 'Use casual, conversational " +
-  "tone. Avoid corporate phrasing. Use contractions. Drop filler words.'\n" +
-  "  • Capture intent, not just the literal request. If the user says 'stop being so formal', infer the " +
-  'positive form: what should you do instead?\n' +
-  '  • Preserve existing instructions when adding new ones — only overwrite the fields you mean to change. ' +
-  'Other fields are kept as-is.\n' +
-  "  • If unsure between two interpretations, pick the more specific one — your future self can't ask back.\n\n" +
-  "Note: changes apply from the user's NEXT message (the current turn's prompt is already built).";
+  "Save how the user wants you to behave (e.g. 'call me Yousef', 'reply in Arabic', 'be more casual'). Takes effect from their NEXT message. Only the fields you pass change.\n\n" +
+  "You are writing for your FUTURE SELF, who reads this text cold on every later turn with no memory of why. Be specific and self-contained: not 'be more casual' but 'Use a casual, conversational tone. Use contractions. Avoid corporate phrasing.' Capture the intent as what to do ('stop being so formal' becomes what to do instead). Between two readings pick the more specific one.";
 
 export interface CreateSetUserPreferencesToolOptions {
   logger?: Logger;

package/src/plugins/user-preferences/user-preferences.plugin.ts

@@ -79,7 +79,11 @@ const manifest: PluginManifest = {
       args: { tone: 'concise' },
     },
   ],
+  // The Tier-1 entry stays, so the prompt says when a preference must be
+  // saved; only the tool waits for a load.
   visibility: 'always',
+  brief: 'save lasting reply preferences: name, language, tone',
+  onDemandTools: [SET_USER_PREFERENCES_TOOL_NAME],
   stability: 'stable',
   category: 'core',
 };

package/src/plugins/vfs/vfs-tools.ts

@@ -172,6 +172,11 @@ async function guard(
   try {
     return await fn();
   } catch (err) {
+    if (err instanceof VfsAuthError && err.kind !== 'no-delegation') {
+      // The user granted access but no bearer could be made (the UCAN store
+      // or the mint failed): the model only reads a generic sentence.
+      ctx.logger.warn(`[vfs] ${err.kind}: ${err.message}`);
+    }
     if (err instanceof VfsHttpError || err instanceof VfsAuthError) {
       return mapVfsError(err, { ...info, oracleDid: readOracleDid(ctx) });
     }
@@ -384,11 +389,8 @@ export function createVfsTools(deps: CreateVfsToolsDeps): PluginTool[] {
     {
       name: 'vfs_search',
       description:
-        "Find files by meaning across the user's filesystem. Use for questions and paraphrases ('the doc about pricing'). Returns file paths + cited line ranges. Follow with `vfs_read` to see the actual lines before answering or editing. For writing, editing, organising, or sharing files, load the `vfs` capability first.",
+        "Find files by meaning across the user's filesystem. Use for questions and paraphrases ('the doc about pricing'). Returns file paths + cited line ranges. Follow with `vfs_read` to see the actual lines before answering or editing.",
       schema: searchSchema,
-      // Recall must work with zero load steps — this tool and `vfs_read`
-      // stay visible while the rest of the plugin is on-demand.
-      visibility: 'always',
     },
   );
 
@@ -471,8 +473,6 @@ export function createVfsTools(deps: CreateVfsToolsDeps): PluginTool[] {
       description:
         "Read a file's contents by path. Text files come back a window of numbered lines at a time (default first 2000; page with `offset` when `hasMore`). Images and PDFs are read too — described/transcribed for you. Always read before editing or answering from a file; do not guess its contents. Reading an image costs an extra step, so read it only when you need to see it.",
       schema: readSchema,
-      // See vfs_search — the read half of the always-available recall pair.
-      visibility: 'always',
     },
   );
 

package/src/plugins/vfs/vfs.plugin.ts

@@ -74,12 +74,10 @@ const manifest: PluginManifest = {
   summary:
     "The user's Virtual Filesystem (VFS) — their persistent, secure, governed filesystem: the canonical home for their real documents, notes, datasets, and artifacts, in folders, searchable and versioned linked to their domain. Reusable context that lives across sessions — not scratch files, not chat attachments, not the web. Securely stored and access-controlled (managed encryption); authorized IXO services can read content to power search, previews, and these tools, so it is NOT end-to-end encrypted — never describe it as zero-knowledge or unreadable by IXO.",
   category: 'data',
-  // On-demand with two exceptions: `vfs_search` and `vfs_read` carry per-tool
-  // `visibility: 'always'` so recall ("what did my notes say…") works with no
-  // load step. The write/organise/share surface (and the sandbox bridges)
-  // loads via `load_capability(['vfs'])` — keeping ~11 tool schemas out of
-  // every unrelated chat turn.
+  // Every tool, recall included, loads via `load_capability(['vfs'])`: the
+  // catalogue line names the files, so a question about them costs one load.
   visibility: 'on-demand',
+  brief: "the user's library: save, read, search, organise files at any path",
   whenToUse: [
     "The user refers to a document, note, file, folder, or something they 'saved', 'uploaded', or 'shared with you'.",
     'You need to create, update, or organise a file for the user (draft, report, notes, export) that should persist.',
@@ -95,6 +93,7 @@ const manifest: PluginManifest = {
     "Content the user pasted directly into chat (act on that inline; don't write it to a file unless asked).",
     "Temporary/scratch or intermediate files produced during a code or compute run — those belong to the sandbox, not the user's filesystem.",
     'Another plugin owns the data (flows, skills, memory) — use that plugin.',
+    "The oracle's own material (its handbook, policies, procedures, reference documents): that is oracle knowledge, found with the memory search, not in the user's files.",
   ],
   examples: [
     {

package/src/plugins/yoma/yoma.plugin.ts

@@ -661,6 +661,7 @@ const manifest: PluginManifest = {
   category: 'data',
   // Yoma's assistant sets `visibility: 'always'` through `manifestOverrides`.
   visibility: 'on-demand',
+  brief: 'Yoma programmes and jobs; apply, log work, check payment',
   stability: 'beta',
 };